`ocfl.NewVersion`

NewVersion class to assemble what will become a new Object version.

It is expected that instances of this class will only be created and used through ocfl.Object, see the start_new_version() and write_new_version() methods.

class ocfl.NewVersion(*, srcdir='.')

Class to represent a new version to be added to an Object.

__init__(*, srcdir='.')

Create NewVersion object.

Parameters:: srcdir (str) – source directory name for files that will be added to this new version. May be a pyfs filesystem specification. Default is “.”

The default constructor is not expected to be used directly, see NewVersion.first_version(…) and NewVersion.next_version(..) for the two cases in which a new version can be created.

add(src_path, logical_path, content_path=None, src_path_has_prefix=False)

Add a file to the new version.

Parameters:

src_path (str) – path of the content to be added, within the source directory specified on creation. This need not have any relation to the path of the content within the object if the content_path parameter is supplied
logical_path (str) – logical filepath that this content should have within the version of the object
content_path (str or None) – if None (default) then will generate a content path based on the src_path and the content_path_normalization strategy selected. Otherwise will use the speficied content path provided is in the current versions content directory (must start with “vdir/content_directory/”) and doesn’t already exist in the object

Raises:

NewVersionException – if the specifies content path is not allowed

add_from_srcdir(): Add all content from srcdir.

property content_directory: Get content directory catering for default.

property created: Created string for this version.

delete(logical_path)

Delete a logical path from this new version.

This is likely to be used when constructing a new version starting from the previous state (initialization with carry_content_forward=True).

Parameters:: logical_path (str) – logical path that should be removed from the new version state
Raises:: NewVersionException – if the logical path doesn’t exist in the new version state

diff_with_previous()

Compare the current version state with the previous version state.

Returns:

of add and delete operations representing diff. Each operation: is a tuple (op, digest, logical_path) where op is “A” for and addition or “D” for a deletion; digest is the string of the content digest; and logical_path is the logical path of the content file. An empty list indicates no content change between versions.

Return type:

list

classmethod first_version(*, srcdir='.', identifier, spec_version='1.1', digest_algorithm=None, content_directory=None, metadata=None, dedupe=True, fixity=None, content_path_normalization='uri')

Start the first version for this object.

Parameters:

srcdir (str) – source directory name for files that will be added to this new version. May be a pyfs filesystem specification
identifier (str) – identifier of the object to be created
spec_version (str) – the specification version that the new version should be created in accord with. Defaults to ocfl.constants.DEFAULT_SPEC_VERSION
digest_algorithm (str or None) – the digest algorithm to use for content addressing. If None (default) then will use the value ocfl.constants.DEFAULT_DIGEST_ALGORITHM
content_directory (str or None) – the content directory name. If None (default) then will use the value “content” (as set in ocfl.constants.DEFAULT_CONTENT_DIRECTORY)
dedupe (bool) – True (default) to deduplicate files within this version, meaning that only one copy of a given file will be included in the content directory even if there are multiple copies in the new version state. If False then will store multiple copies
metadata (ocfl.VersionMetadata or None) – if an ocfl.VersionMetadata object is provided then this is used to set the metadata of the new version. The setters .created, .message, .user_address and .user_name may alternatively be used
fixity (None or list of str) – If a list then will be interpretted as the set of fixity digest types to be added for all content files in this version
content_path_normalization (str) – the path normalization strategy to use with content paths when files are added to this object (default “uri”)

Example use:

>>> import ocfl
>>> nv = ocfl.NewVersion.first_version(identifier="http://example.org/minimal")
>>> nv.add("fixtures/1.1/good-objects/spec-ex-minimal/v1/content/file.txt", "file.txt")
>>> nv.created = "2018-10-02T12:00:00Z"
>>> nv.message = "One file"
>>> nv.user_address = "mailto:alice@example.org"
>>> nv.user_name = "Alice"
>>> print(nv.inventory.as_json())
{
  "digestAlgorithm": "sha512",
  "head": "v1",
  "id": "http://example.org/minimal",
  "manifest": {
    "7545b8720a601235067473f2c87f43461f5c147fb622d51bfcdcda05e0773c96e9f922f4d88d371bb7f87793b655b9e1c3b8bbca35f2950c5c87eda955179f67": [
      "v1/content/fixtures/1.1/good-objects/spec-ex-minimal/v1/content/file.txt"
    ]
  },
  "type": "https://ocfl.io/1.1/spec/#inventory",
  "versions": {
    "v1": {
      "created": "2018-10-02T12:00:00Z",
      "message": "One file",
      "state": {
        "7545b8720a601235067473f2c87f43461f5c147fb622d51bfcdcda05e0773c96e9f922f4d88d371bb7f87793b655b9e1c3b8bbca35f2950c5c87eda955179f67": [
          "file.txt"
        ]
      },
      "user": {
        "address": "mailto:alice@example.org",
        "name": "Alice"
      }
    }
  }
}

property message: Message string for this version.

classmethod next_version(*, inventory, srcdir='.', spec_version='1.1', metadata=None, content_path_normalization='uri', forward_delta=True, dedupe=True, carry_content_forward=False, old_digest_algorithm=None)

Start the new version by adjusting inventory.

If carry_content_forward is set then the state block of the previous version is copied forward into the new version. Items may later be added or deleted.

Note that this method does not take a digest_algorithm parameter. The digest_algorithm is a property of the inventory. Code to implement a change of digest_algorithm between version requires access to the files and is implemented within ocfl.object. This method does have an old_digest_algorithm parameter which is used just to store information for ocfl.object methods.

Parameters:

inventory (ocfl.Inventory) – inventory that we will modify to build the new version
srcdir (str) – source directory name for files that will be added to this new version. May be a pyfs filesystem specification
metadata (ocfl.VersionMetadata or None) – Either a VersionMetadata object to set the metadata for the new version, None to not set metadata
content_path_normalization (str) – the path normalization strategy to use with content paths when files are added to this object (default “uri”)
forward_delta (bool) – True (default) to use forward delta strategy for files in the new version, meaning that only files not present in a previous version will be added in the content directory of this new version. If False the all files that are part of this version’s state will be added in the content directory
dedupe (bool) – True (defult) to deduplicate files within this version, meaning that only one copy of a given file will be included in the content directory even if there are multiple copies in the new version state. If False then will store multiple copies
carry_content_forward (bool) – True to carry forward the state from the last current version as a starting point. False to start with empty version state
old_digest_algorithm (str) – Can be used to record the digest algorithm of the previous version so that the root inventory sidecar is cleaned up when writing the new inventory in the object root. The value is not used within NewVerion code. Default is None

Example use:

>>> # Prep:
>>> # mkdir tmp
>>> # cp -rp fixtures/1.1/good-objects/spec-ex-full tmp/spec-ex-full
>>>
>>> import ocfl
>>> object = ocfl.Object()
>>> nv = object.start_new_version(objdir="tmp/spec-ex-full", carry_content_forward=True)
>>> nv.inventory.current_version.logical_paths
['foo/bar.xml', 'empty2.txt', 'image.tiff']
>>> nv.delete("foo/bar.xml")
>>> nv.rename("empty2.txt", "empty3.txt")
>>> nv.add("fixtures/1.1/content/README.md", "readme", "v4/readme")
>>> object.write_new_version(nv)
INFO:root:Updated OCFL object ark:/12345/bcd987 in tmp/spec-ex-full by adding v4
<ocfl.inventory.Inventory object at 0x1014e6cd0>

rename(old_logical_path, new_logical_path)

Rename content in the version state to a new logical_path.

Parameters:

old_logical_path (str) – logical path that should be renamed
new_logical_path (str) – new logical path to replace old_logical_path

Raises:

NewVersionException – if the old logical path doesn’t exist in the new version state, or if the new logical path already exists

property user_address: User_address string for this version.

property user_name: user_name string for this version.

class ocfl.NewVersionException: Exception class for NewVersion objects.

`ocfl.NewVersion`

ocfl-py

Navigation

Related Topics

ocfl.NewVersion

`ocfl.NewVersion`