Examples

The following examples demonstrate how siptools-ng can be used.

Note

These scripts are standalone and can be run as-is. You can do so by opening the directory doc/source/examples in project root.

Simple

This example is the minimal example that only contains the default structural map and technical metadata. The siptools_ng.sip.SIP.from_directory() factory method is used generate a SIP from a directory in the local filesystem. This also means that aside from the METS object creation and importing descriptive metadata, there is no need to use the underlying dpres-mets-builder library.

"""Example code for automated SIP creation."""
from mets_builder import METS, MetsProfile
from mets_builder.metadata import (
    DigitalProvenanceEventMetadata,
    ImportedMetadata,
)

from siptools_ng.sip import SIP

# Initialize dpres-mets-builder METS object with your information
mets = METS(
    mets_profile=MetsProfile.RESEARCH_DATA,
    contract_id="urn:uuid:abcd1234-abcd-1234-5678-abcd1234abcd",
    creator_name="Sigmund Sipenthusiast",
    creator_type="INDIVIDUAL"
)

# A prepared directory with all the files to package can be turned into a SIP
# with from_directory method. Here the technical metadata is generated for all
# the files found in the given directory and the structural map is organized
# according to the directory structure.
sip = SIP.from_directory(
    directory_path="example_files",
    mets=mets,
)

# Create provenance metadata and add it to SIP
provenance_md = DigitalProvenanceEventMetadata(
    event_type="creation",
    detail="This is a detail",
    outcome="success",
    outcome_detail="Another detail",
)
sip.add_metadata([provenance_md])

# Import descriptive metadata from an XML source, and add it to SIP
descriptive_md = ImportedMetadata.from_path("example_metadata/ead3.xml")
sip.add_metadata([descriptive_md])

sip.finalize(
    output_filepath="result/example-automated-sip.tar",
    sign_key_filepath="data/rsa-keys.crt"
)

Advanced

This example is more involved. In addition to the automatic structural map generated by siptools-ng, it details how additional metadata can be imported and a structural map created by hand. This involves the use of the underlying dpres-mets-builder library.

The example uses the siptools_ng.sip.SIP.from_files() factory method which allows generating a SIP with a directory structure different from how the files are stored on disk.

"""Example code for manual SIP creation."""
from mets_builder import (
    METS,
    MetsProfile,
    StructuralMap,
    StructuralMapDiv,
)
from mets_builder.metadata import (
    DigitalProvenanceEventMetadata,
    ImportedMetadata,
)

from siptools_ng.file import File
from siptools_ng.sip import SIP

# A part of using dpres-siptools-ng is to create a METS object using
# dpres-mets-builder in tandem with some helper utilities provided by
# dpres-siptools-ng whenever needed. See user documentation of
# dpres-mets-builder at
# https://github.com/Digital-Preservation-Finland/dpres-mets-builder for more
# detailed instructions on how to build METS objects. This example code focuses
# on automating the METS creation as much as possible.

# Initialize dpres-mets-builder METS object with your information
mets = METS(
    mets_profile=MetsProfile.CULTURAL_HERITAGE,
    contract_id="urn:uuid:abcd1234-abcd-1234-5678-abcd1234abcd",
    creator_name="CSC – IT Center for Science Ltd.",
    creator_type="ORGANIZATION"
)

# Create files each containing a digital object which contains the sip path.
file1 = File(
    path="example_files/art/movie.mkv",
    digital_object_path="data/movies/movie.mkv"
)
file2 = File(
    path="example_files/text_files/file1.txt",
    digital_object_path="data/text_files/file1.txt"
)
file3 = File(
    path="example_files/text_files/file2.txt",
    digital_object_path="data/text_files/file2.txt"
)

# Create provenance metadata
provenance_md = DigitalProvenanceEventMetadata(
    event_type="creation",
    detail="This is a detail",
    outcome="success",
    outcome_detail="Another detail",
)

# Import descriptive metadata from an XML source
descriptive_md = ImportedMetadata.from_path("example_metadata/ead3.xml")

# Add metadata to files
file1.add_metadata([provenance_md])
file2.add_metadata([provenance_md, descriptive_md])
file3.add_metadata([descriptive_md])

# Make a custom structural map div using the digital objects in files
root_div = StructuralMapDiv(
    "custom_div",
    digital_objects=[
        file1.digital_object,
        file2.digital_object,
        file3.digital_object
    ],
)

# Add the custom div to a structural map
structural_map = StructuralMap(root_div=root_div)

# Add the custom structural map to METS and generate file references
mets.add_structural_maps([structural_map])
mets.generate_file_references()

# Make a SIP using the previously created file and METS. In addition to the
# manually structural map a default custom map is generated based on the
# directory structure.
sip = SIP.from_files(mets=mets, files=[file1, file2, file3])

# Finalize the SIP and write it to file
sip.finalize(
    output_filepath="result/example-manual-sip.tar",
    sign_key_filepath="data/rsa-keys.crt"
)