OCFL Core

OCFL Core is a Python library for working with [Oxford Common Filesystem Layout](https://ocfl.io).

Features include:

• Domain model API: Implements a flexible domain model API for working with OCFL, that allows easy customization of OCFL features such as e.g. storage hierarchies.

• Storage abstraction: Works with byte streams to allow any storage system to be used.

• Deduplication: Content files are automatically deduplicated in the OCFL object.

• Segregating Objects-in-flight: A workspace is being used to assemble objects prior to adding them into the repository to ensure as atomic operations as possible on top of a file system and with support for cleaning up after failed operations.

Further documentation is available on https://ocflcore.readthedocs.io/.

Quick start

Import the required classes:

from datetime import datetime, timezone
from io import BytesIO

from ocflcore import (
    FileSystemStorage,
    OCFLRepository,
    OCFLObject,
    OCFLVersion,
    StorageRoot,
    StreamDigest,
    TopLevelLayout,
)

Create a OCFL storage root using a top-level storage hierarchy:

root = StorageRoot(TopLevelLayout())

Initialize an OCFL repository:

# Setup workspace and root storage:
storage = FileSystemStorage("root")
workspace_storage = FileSystemStorage("workspace")
# Initialize the repository
repository = OCFLRepository(root, storage, workspace_storage=workspace_storage)
repository.initialize()

Create an in-memory example file and compute its SHA512 digest:

example_file = StreamDigest(BytesIO(b"minimal example"))

Create a minimal OCFL object:

# Create version
v = OCFLVersion(datetime.now(timezone.utc))
v.files.add("file.txt", example_file.stream, example_file.digest)

# Create the object
o = OCFLObject("12345-abcde")
o.versions.append(v)

Last, but not least, add the OCFL object to the OCFL repository:

repository.add(o)

Result

The result is an OCFL repository:

$ tree .
.
|-- root
|   |-- 0=ocfl_1.1
|   |-- 12345-abcde
|   |   |-- 0=ocfl_object_1.1
|   |   |-- inventory.json
|   |   |-- inventory.json.SHA512
|   |   `-- v1
|   |       |-- content
|   |       |   `-- file.txt
|   |       |-- inventory.json
|   |       `-- inventory.json.SHA512
|   `-- ocfl_layout.json
`-- workspace

5 directories, 8 files

With the OCFL inventories and nameste files:

$ cat root/12345-abcde/inventory.json
{
"contentDirectory": "content",
"digestAlgorithm": "sha512",
"head": "v1",
"id": "12345-abcde",
"manifest": {
    "8ef7dc319954f0d8ed13b1da8e744a4e00fad3cf0952a9ee75c51f455769f1b7c09d623b3ec433483d2627b85100485727a4f200a7b75fb7f81a41af451167da": [
    "v1/content/file.txt"
    ]
},
"type": "https://ocfl.io/1.1/spec/#inventory",
"versions": {
    "v1": {
    "created": "2021-12-14T08:09:17.743663+00:00",
    "state": {
        "8ef7dc319954f0d8ed13b1da8e744a4e00fad3cf0952a9ee75c51f455769f1b7c09d623b3ec433483d2627b85100485727a4f200a7b75fb7f81a41af451167da": [
        "file.txt"
        ]
    }
    }
}
}

Install

pip install ocflcore

Running tests

git clone https://github.com/inveniosoftware/ocflcore
cd ocflcore
pip install -e ".[all]"
./run-tests.sh

API Reference

If you are looking for information on a specific function, class or method, this part of the documentation is for you.

• Main API
  • Domain model
  • Persistence
  • Digests
• Domain API
  • OCFL Objects
  • OCFL Storage Root
  • Storage hierarchies
• Persistence API
  • Repository
  • Inventory
  • Transaction
  • Workspace
  • Storage

Additional Notes

Notes on how to contribute, legal information and changes are here for the interested.

• Contributing
• Changes
• License
• Authors