==========================================
ocfl-py - An OCFL implementation in Python
==========================================

2024-09 - WARNING - THIS CODE IS UNDERGOING A SIGNIFICANT REWORKING TO PREPARE
FOR VERSION 2.0 SPECIFICATION WORK. THE LATEST STABLE VERSION IS `v1.3.0
<https://github.com/zimeon/ocfl-py/releases/tag/v1.3.0>`_, ALSO AVAILABLE ON `PyPI
<https://pypi.org/project/ocfl-py/>`_

``ocfl-py`` is a Python reference implementation of the Oxford Common File Layout
(OCFL). It also provides a number of command-line tools that may be useful for
validating and manipulating OCFL Objects and OCFL Storage Roots. The code
implements the current `OCFL specification v1.1
<https://ocfl.io/1.1/spec/>`_ while retaining support for `v1.0
<https://ocfl.io/1.0/spec/>`_. See `implementation status for errors and warnings
<https://github.com/zimeon/ocfl-py/blob/main/docs/validation_status.md>`_ for
details of validator support.

See `ocfl-py documentation
<https://oclf-py.readthedocs.io/en/latest/index.html>`_  on ReadTheDocs.

Installing
----------

This code requires Python 3.

This supports the OCFL specifications v1.1 and v1.0. To get the most
up to date version check out the ``main`` branch from github.

I hope to keep a fairly current version on `PyPI
<https://pypi.org/project/ocfl-py/>`_, which can be installed or
upgraded with:

    pip install --upgrade ocfl-py

The latest version is in the `main` branch on `github
<https://github.com/zimeon/ocfl-py>`_.

Use
---

There should then be four command-line scripts available:

- ``ocfl-root.py`` - add or access OCFL objects under an OCFL storage root
- ``ocfl-validate.py`` - validate OCFL objects, OCFL storage roots or standalone OCFL inventory files
- ``ocfl-object.py`` - build, manipulate, extract from or validate a stand-alonde OCFL object
- ``ocfl-sidecar.py`` - update OCFL inventory sidecar file (useful for manually building examples and test cases)

Each script takes ``-h`` for help.

See `examples in docs folder
<https://github.com/zimeon/ocfl-py/tree/main/docs>`_ for use of these scripts.

The code is also available as a module ``ocfl`` for other python code to use.

Contributing
------------

Bug reports welcome as `github issues
<https://github.com/zimeon/ocfl-py/issues>`_.

See `CONTRIBUTING.md
<https://github.com/zimeon/ocfl-py/blob/main/CONTRIBUTING.md>`_
for guidelines for contributing.

Other Python OCFL Code
----------------------

See also `OCFL-Core
<https://github.com/inveniosoftware/ocflcore>`_ which is another Python implementation
of OCFL, designed to support the InvenioRDM repository, and `other OCFL implementations
<https://github.com/OCFL/spec/wiki/Implementations>`_.

Copyright and License
---------------------

Copyright 2018--2025 Simeon Warner and `contributors
<https://github.com/zimeon/ocfl-py/graphs/contributors>`_.
Provided under the MIT license, see `LICENSE.txt
<https://github.com/zimeon/ocfl-py/blob/main/LICENSE.txt>`_.
