ocfl.StorageRoot

OCFL Storage Root validation and manipulation.

This code uses PyFilesystem (import fs) exclusively for access to files. This should enable application beyond the operating system filesystem.

class ocfl.StorageRoot(root=None, layout_name=None, lax_digests=False, spec_version=None)

Class for handling OCFL Storage Root and include OCFL Objects.

__init__(root=None, layout_name=None, lax_digests=False, spec_version=None)

Initialize OCFL Storage Root.

Parameters:

  • root (str) – file path or fsw filesystem descriptor for the OCFL Storage Root

  • layout_name (str) – name of the file layout to use

  • lax_digests (bool)

  • spec_version (str) – OCFL specification version expected

add(object_path)

Add pre-constructed object from object_path.

The identifier is extracted from the object and the path is determined by the storage layouts

Returns:

the (identifier (str), path (str)) on success

Return type:

tuple

Raises:

StorageException – with message string on failure.

check_root_structure()

Check the OCFL Storage Root structure.

Returns:

True on success

Return type:

bool

Raises:

StorageRootException – with validator error codes if there is an error

Side effects:

self.spec_version - set to declared specification version self.layout - initialized with layout handler if specified

Assumes that self.root_fs filesystem is available to read from.

check_spec_version(spec_version, default='1.1')

Check the OCFL specification version is supported.

Parameters:

  • spec_version (str or None) – specification version to check

  • default (str) – specification version to use if spec_version is None

Raises:

StorageRootException – if spec_version is not supported

Sets self.spec_version to spec_version if given and good, otherwise to the default.

initialize(spec_version=None, layout_params=None)

Create and initialize a new OCFL Storage Root.

Parameters:

  • spec_version (str or None) – OCFL specification version to declare if specified, else default.

  • layout_params (str or None) – filename of JSON layout parameters file, else None to not use any.

Raises:

StorageRootException – on failure to create the Storage Root

property layout

Instance of layout class.

Lazily initialized. Will return either a valid layout name or None if the layout is not set.

list_objects()

List contents of this OCFL Storage Root.

Yields:

tuple – for each object, which contains (dirpath, identifier)

Side effects:

The count of self.num_objects is updated through the traversal of the storage root

object_path(identifier)

Path to OCFL object with given identifier relative to the OCFL storage root.

Parameters:

identifier (str) – OCFL Object identifier

Returns:

path to the OCFL Object specified

Return type:

str

Raises:

StorageRootException – on error

object_paths()

Generate object paths for every obect in the OCFL Storage Root.

Yields:

str –

the path to the directory for each object located, relative

to the OCFL storage root and without a preceding /.

Will log any errors seen while traversing the directory tree under the storage root.

open_root_fs()

Open existing fsw filesystem for this OCFL storage root.

Raises:

StorageRootException – on failure to open root

Relies upon self.root for the location of the storage root. Will set self.root_fs on success with the open filesystem.

parse_layout_file()

Read and parse layout file in OCFL Storage Root.

Returns:

of (extension, description) strings from the

layout file. The values of these strings are not checked

Return type:

tuple

Raises:

StorageRootException – with validator error codes if these is and error in the layout configuration

traversal_error(code, **kwargs)

Record error traversing OCFL storage root.

Parameters:

  • code (str) – error code

  • **kwargs – (dict): keyword arguments to complete the error message for the given code

Uses non-None self.log to determine validation context, in which case the error is logger to self.log. Otherwise uses logging.error() to report the error directly.

validate(*, validate_objects=True, check_digests=True, log_warnings=False, log_errors=True, max_errors=100, lang='en')

Validate OCFL Storage Root, structure, and optionally all objects.

Parameters:

  • validate_objects (bool) – True (default) to validate each object on the storage root, otherwise will not validate the objects

  • check_digests (bool) – True (default) to check the digests of each file while validating objects

  • log_warnings (bool) – True if warnings should be logged, default False

  • log_errors (bool) – True (default) if errors should be logged

  • max_errors (int) – Number of errors and warnings to log, default is 100

  • lang (str) – Language of error and warning descriptions to look for, default is “en”

Returns:

True if everything checked is valid, False otherwise

Return type:

bool

Sets a number of instance variables as side effects:

  • self.num_objects: number of objects examined

  • self.good_objects: number of valid objects

  • self.errors: list of [dirpath, message] pairs for up to max_errors errors

  • self.log: ValidationLogger object with any traversal errors

validate_extensions_dir()

Validate content of extensions directory inside storage root.

Validate the extensions directory by checking that there aren’t any entries in the extensions directory that aren’t directories themselves. Where there are extension directories they SHOULD be registered and this code relies up the registered_extensions property to list known storage root extensions.

validate_hierarchy(validate_objects=True, check_digests=True, log_warnings=False, max_errors=100)

Validate OCFL Storage Root hierarchy and, optionally, all objects.

Parameters:

  • validate_objects (bool) – True to validate each object within the storage root

  • check_digests (bool) – True to check file digests for each content file in each object

  • log_warnings (bool) – True to log warnings as well as errors

  • max_errors (int) – Number of errors to record before stopping

Returns:

tuple of (num_objects, good_objects, errors) where num_objects is

the number of objects checked, good_objects is number of objects checked that were found to be valid, and errors is a list of [dirpath, message] pairs for up to max_errors errors

write_root_declaration(root_fs)

Write Namaste root declaration file for this Storage Root.

Uses self.spec_version to determing the Storage Root version and assumes self.obj_fs is open for this object.

class ocfl.StorageRootException(code, **kwargs)

Exception class for OCFL Storage Root.

__init__(code, **kwargs)

Initialze StorageRootException.

Parameters:

  • code (str) – either an exception message (if no **kwargs) or otherwise a validation error code that can be passed to a ValidationLogger instance

  • **kwargs (dict) – keyword arguments to complete the error message for the given code

All exceptions relevant to the validator context should supply both an error code (e.g. “E072”) and a set of kwargs that match the strings defined for ValidationLogger. In other contexts, such as operations on a StorageRoot, one parameter may be supplied as the full error string.