Skip to main content

Python library for working with IIIF Image and Presentation APIs

Project description


Python library for generating and parsing IIIF Image API URLs in an object-oriented, pythonic fashion.

Unit Test Status codecov Maintainability

Piffle is tested on Python 3.8—3.11.

Piffle was originally developed by Rebecca Sutton Koeser at Emory University as a part of Readux and forked as a separate project under emory-lits-labs. It was later transferred to Rebecca Sutton Koeser at the Center for Digital Humanities at Princeton.

Installation and example use:

pip install piffle

Example use for generating an IIIF image url:

>>> from piffle.image import IIIFImageClient
>>> myimg = IIIFImageClient('http://image.server/path/', 'myimgid')
>>> print myimg
>>> print
>>> print myimg.size(width=120).format('png')

Example use for parsing an IIIF image url:

>>> from piffle.image import IIIFImageClient
>>> myimg = IIIFImageClient.init_from_url('')
>>> print myimg
>>> print
>>> myimg.as_dict()['size']['full']
>>> myimg.as_dict()['size']['exact']
>>> myimg.as_dict()['rotation']['degrees']

Example use for reading a IIIF manifest:

>>> from piffle.image import IIIFImageClient
>>> from piffle.presentation import IIIFPresentation
>>>  manifest = IIIFPresentation.from_url('')
>>> manifest.label
'Bodleian Library MS. Bodl. 264'
>>> manifest.type
>>> for canvas in manifest.sequences[0].canvases[:5]:
...     image_id = canvas.images[0]
...     iiif_img = IIIFImageClient(*image_id.rsplit('/', 1))
...     print(str(iiif_img.size(height=250)))

Development and Testing

This project uses git-flow branching conventions.

Install locally for development (the use of a python virtualenv is recommended):

pip install -e .

Install test dependencies:

pip install -e ".[dev]"

Run unit tests: py.test or python test

Install pre-commit hooks

Anyone who wants to contribute to this codebase should install the configured pre-commit hooks:

pre-commit install

This will configure a pre-commit hooks to automatically lint and format python code with ruff and black.

Pre-commit hooks and formatting conventions were added at version 0.5, so git blame may not reflect the true author of a given change. To make git blame more accurate, ignore formatting revisions:

git blame <FILE> --ignore-revs-file .git-blame-ignore-revs

Or configure your git to always ignore styling revision commits:

git config blame.ignoreRevsFile .git-blame-ignore-revs

Publishing python packages

A new python packages is automatically built and published to PyPI using a GitHub Actions workflow when a new release is created on GitHub.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

piffle-0.5.0.tar.gz (28.6 kB view hashes)

Uploaded Source

Built Distribution

piffle-0.5.0-py2.py3-none-any.whl (15.9 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page