PyUnsplash

An open source Python wrapper for the Unsplash REST API. The source code is available on GitHub at https://github.com/salvoventura/pyunsplash.

Installation

PyUnsplash is available on PyPI and thus can be installed with pip on most platforms. :

$ pip install pyunsplash

Dependencies

This library depends on Requests to make - well - requests to the Unsplash API. This additional package should be automatically installed at installation time, or you can simply install it by: :

$ pip install requests

Examples

This example shows how the interaction with the paging functionality of the unsplash API is greatly abstracted and simplified. The code below will iterate through all collections, and retrieve each photo in there, and print their download link.

import logging
from pyunsplash import PyUnsplash
api_key = 'YOUR_APPLICATION_ID'

# instantiate PyUnsplash object
py_un = PyUnsplash(api_key=api_key)

# pyunsplash logger defaults to level logging.ERROR
# If you need to change that, use getLogger/setLevel
# on the module logger, like this:
logging.getLogger("pyunsplash").setLevel(logging.DEBUG)

# Start with the generic collection, maximize number of items
# note: this will run until all photos of all collections have
#       been visited, unless a connection error occurs.
#       Typically the API hourly limit gets hit during this
#
collections = py_un.collections(per_page=30)
while collections.has_next:
    for collection in collections.entries:
        photos = collection.photos()
        for photo in photos.entries:
            print collection.title, photo.link_download, photo.get_attribution()

    # no need to specify per_page: will take from original object
    collections = collections.get_next_page()

Documentation

Documentation is published on ReadTheDocs.

Version

PyUnsplash v1.0.0rc2 (release candidate, v2)

This is the second release candidate for production ready 1.0.0 of PyUnsplash. Thanks to all the early adopters and bug reporters: thanks to you there have been a number of improvements and bugfixes and we are progressing the rc process.

This release brings mainly one bugfix:

#13 search.get_next_page() does not work

Todo - Authorization workflow & Current user - Write operations

PyUnsplash v1.0.0rc1 (release candidate, v1)

This is the first release candidate for production ready 1.0.0 of PyUnsplash. Thanks to all the early adopters, there have been a number of improvements and bugfixes and now should be a good time to start the rc process.

This release brings one useful addition:

Introduction of SinglePhoto which allows instantiating a Photo object using a photo_id

Deprecated format value 'str' in favor of 'txt' in get_attribution()

PyUnsplash v1.0.0b9 (beta, v9)

Introduce get_attribution method in class Photo

Update tests, examples and documentation accordingly

Update documentation for objects supporting .body attribute

Update Copyright years adding 2020

Todo - Authorization workflow & Current user - Write operations

PyUnsplash v1.0.0b8 (beta, v8)

Fix documentation for random photos API endpoint

Update library and documentation for deprecated 'curated' photos

Update library and documentation for deprecated 'curated' collection

Add library warning in logs for 'curated' when used

Fix documentation for object parameter type_ instead of type

Core library now raising exception for invalid parameters

Added support for user statistics API, and related doc and tests

Todo - Authorization workflow & Current user - Write operations

PyUnsplash v1.0.0b7 (beta, v7)

Fixed issues submitted on GitHub: - Search class: Param "type" is "type" - Provide property for download_location in PyUnsplasy.Photo class

Todo - Authorization workflow & Current user - Write operations

PyUnsplash v1.0.0b6 (beta, v6)

Added Python3 support

Todo - Authorization workflow & Current user - Write operations

PyUnsplash v1.0.0b5 (beta, v5)

Todo - Authorization workflow & Current user - Write operations

PyUnsplash v1.0.0b4 (beta, v4)

Todo - Authorization workflow & Current user - Write operations

PyUnsplash v1.0.0b3 (beta, v3)

Still troubles in getting Travis-Ci and PyPI publishing automation tied.

Todo - Get PyPI publishing automated via Travis-Ci after tag commits. - Authorization workflow & Current user - Write operations

PyUnsplash v1.0.0b2 (beta, v2)

Getting Travis-Ci and PyPI publishing automation tied.

Todo - Authorization workflow & Current user - Write operations

PyUnsplash v1.0.0b1 (beta, v1)

Logging subsystem overhaul, now cleaner. Changes have percolated across many files. Documentation checked and verified, and issues fixed.

Todo - Get PyPI publishing automated via Travis-Ci after tag commits. - Authorization workflow & Current user - Write operations

PyUnsplash v1.0.0a3 (alpha, v3)

v1.0.0a2 broke the library with the attempt to import the build number from Travis via the environment variable, which obviously vanishes outside of the CI system. Fixed. Will need a different solution if I really want/need build numbering inside the library version number.

Todo

Still struggling to get PyPI publishing automated via Travis-Ci after tag commits.

PyUnsplash v1.0.0a2 (alpha, v2)

Added support and integration for more tools, which also required some code cleanup:

integrate and run automated unit tests

integrate with CodeCov

integrate with CodeClimate

Todo

Still struggling to get PyPI publishing automated via Travis-Ci after tag commits.

PyUnsplash v1.0.0a1 (alpha, v1)

This first release offers read-only capabilities to the Unsplash REST API. Although with this limitation, I thought it would be useful to start exposing the library and collect feedback from the community early on.

Features that are right now on my TODO list:

Authorization workflow & Current user

Write operations

Desired:

More unit-test coverage

Documentation review

License

PyUnsplash is released under the MIT License.