piffle

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

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
http://image.server/path/myimgid/full/full/0/default.jpg
>>> print myimg.info()
http://image.server/path/myimgid/info.json"
>>> print myimg.size(width=120).format('png')
http://image.server/path/myimgid/full/120,/0/default.png

Example use for parsing an IIIF image url:

>>> from piffle.image import IIIFImageClient
>>> myimg = IIIFImageClient.init_from_url('http://www.example.org/image-service/abcd1234/full/full/0/default.jpg')
>>> print myimg
http://www.example.org/image-service/abcd1234/full/full/0/default.jpg
>>> print myimg.info()
http://www.example.org/image-service/abcd1234/info.json
>>> myimg.as_dict()['size']['full']
True
>>> myimg.as_dict()['size']['exact']
False
>>> myimg.as_dict()['rotation']['degrees']
0.0

Example use for reading a IIIF manifest:

>>> from piffle.image import IIIFImageClient
>>> from piffle.presentation import IIIFPresentation
>>>  manifest = IIIFPresentation.from_url('https://iiif.bodleian.ox.ac.uk/iiif/manifest/60834383-7146-41ab-bfe1-48ee97bc04be.json')
>>> manifest.label
'Bodleian Library MS. Bodl. 264'
>>> manifest.id
'https://iiif.bodleian.ox.ac.uk/iiif/manifest/60834383-7146-41ab-bfe1-48ee97bc04be.json'
>>> manifest.type
'sc:Manifest'
>>> for canvas in manifest.sequences[0].canvases[:5]:
...     image_id = canvas.images[0].resource.id
...     iiif_img = IIIFImageClient(*image_id.rsplit('/', 1))
...     print(str(iiif_img.size(height=250)))
...
https://iiif.bodleian.ox.ac.uk/iiif/image/90701d49-5e0c-4fb5-9c7d-45af96565468/full/,250/0/default.jpg
https://iiif.bodleian.ox.ac.uk/iiif/image/e878cc78-acd3-43ca-ba6e-90a392f15891/full/,250/0/default.jpg
https://iiif.bodleian.ox.ac.uk/iiif/image/0f1ed064-a972-4215-b884-d8d658acefc5/full/,250/0/default.jpg
https://iiif.bodleian.ox.ac.uk/iiif/image/6fe52b9a-5bb7-4b5b-bbcd-ad0489fcad2a/full/,250/0/default.jpg
https://iiif.bodleian.ox.ac.uk/iiif/image/483ff8ec-347d-4070-8442-dbc15bc7b4de/full/,250/0/default.jpg

Development and Testing

This project uses git flow branching conventions via git-flow-next.

Note

Make sure you are using the correct version of git flow. The original git-flow and its successor git-flow-avh are no longer maintained. While git-flow-next is backwards compatible, this project assumes the workflow and features of git-flow-next.

For development, we assume the usage of uv. uv is compatible with the use of pip for python package management and a tool of your choice for creating python virtual environments (e.g., mamba, venv).

Initial setup and installation

Initizalize and configure git-flow in your local repository

Install git-flow-next if it's not installed. It can be installed via Homebrew or manual installation. See git-flow-next's installation documentation for more details.

To initialize git-flow run:

git flow init --preset=classic --defaults

This package uses custom configurations options for git-flow including the use of custom git-flow hooks which are defined in gitflow-hooks. Run the provided setup_gitflow.sh script to update git-flow's configuration.

sh setup_gitflow.sh

These configuration options are set in the local git config (.git/config).

To display an overview of the current git-flow configuration, branch structure, and workflow status run:

git flow overview

Install uv

Install uv if it's not installed. It can be installed via PyPi, Homebrew, or a standalone installer. See uv's installation documentation for more details.

To explicitly sync the project's dependencies, including optional dependencies for development and testing, to your local environment run:

uv sync

Note that uv performs syncing and locking automatically (e.g., any time uv run is invoked). By default, syncing will remove any packages not specifically specified in the pyproject.toml.

Install pre-commit hooks

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

To install pre-commit run:

uv tool install pre-commit --with pre-commit-uv

To install the configure pre-commit hooks run:

pre-commit install

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

To run pre-commit explicitly run:

pre-commit run --all-files

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

Unit testing

Unit tests are set up to be used with pytest.

To run the tests, run:

uv run pytest

Pull requests

To propose code changes, create a pull request against the develop branch (per our git flow workflow). Pull requests should include an update to CHANGELOG.md documenting the changes to the project.

Several GitHub Actions are run for pull requests: unit testing, code coverage, ruff checks, and a changelog check. By default, the changelog check will fail if the PR does not update CHANGELOG.md. For pull requests that do not modify code, the "no changelog" label can be added to skip this check.

Publishing python packages

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

License

piffle is distributed under the Apache 2.0 License.

Contributors

• Rebecca Sutton Koeser
• Graham Hukill
• Rosie Wood
• Klaus Rettinghaus
• Laure Thompson