Getting Started

Installation

You can install the SWORDv3 client from PyPI as sword3client.

Making a client

Create a new instance of the client

from sword3client import SWORD3Client
client = SWORD3Client()

See the object definitions for full details of all operations available.

Create an object with metadata only

from sword3common import Metadata
from sword3client import SWORD3Client
client = SWORD3Client()

SERVICE = "http://example.com/service-document"
metadata = Metadata()
metadata.add_dc_field("creator", "Test")
response = client.create_object_with_metadata(SERVICE, metadata)

Create an object with a package

from sword3common import constants
from sword3client import SWORD3Client
client = SWORD3Client()

package_path = "/path/to/file.zip"
digest = {constants.DIGEST_SHA_256: "digest...."}
SERVICE = "http://example.com/service-document"
with open(package_path, "rb") as stream:
    response = client.create_object_with_package(
                SERVICE,
                stream,
                "test.zip",
                digest,
                content_type="application/zip",
                packaging=constants.PACKAGE_SWORDBAGIT,
            )

Retrieve the Object’s status

from sword3client import SWORD3Client
client = SWORD3Client()

OBJ_URL = "http://example.com/object/1"
status = client.get_object(OBJ_URL)

Append a binary file

from sword3client import SWORD3Client
client = SWORD3Client()

OBJ_URL = "http://example.com/object/1"
file_path = "/path/to/binary.bin"
digest = {sword3common.constants.DIGEST_SHA_256: "digest...."}
with open(file_path, "rb") as stream:
    response = client.add_binary(OBJ_URL, stream, "test.bin", digest)

Delete the object

from sword3client import SWORD3Client
client = SWORD3Client()

OBJ_URL = "http://example.com/object/1"
response = client.delete_object(OBJ_URL)

Create an object by reference

from sword3common import ByReference
from sword3client import SWORD3Client
client = SWORD3Client()

SERVICE = "http://example.com/service-document"

br = ByReference()
br.add_file("http://example.com/file.pdf",
        "file.pdf",
        "application/pdf",
        True)

response = client.create_object_by_reference(SERVICE, br)

Upload a large file by segments

from io import BytesIO
from sword3common import constants
from sword3client import SWORD3Client
client = SWORD3Client()

SERVICE = "http://example.com/service-document"
FILE_SIZE = 1000000
SEGMENT_COUNT = 10
SEGMENT_SIZE = 100000
DIGEST = {constants.DIGEST_SHA_256: "digest...."}
LARGE_FILE = "/path/to/large/file.zip"

# get the service document, which tells us important details on segmented uploads
service_document = client.get_service(SERVICE)

# initialise the upload, to get a temporary url
resp = client.initialise_segmented_upload(
    service_document,
    assembled_size=FILE_SIZE,
    segment_count=SEGMENT_COUNT,
    segment_size=SEGMENT_SIZE,
    digest=DIGEST
)
temporary_url = resp.location

# send each segment to the temporary url
with open(LARGE_FILE, "rb") as f:
    for i in range(SEGMENT_COUNT):
        segment = f.read(SEGMENT_SIZE)
        stream = BytesIO(segment)
        segment_response = client.upload_file_segment(temporary_url, stream, i)

Retrieve information about a segmented upload

from sword3client import SWORD3Client
client = SWORD3Client()

# Temporary URL obtained from initialisation of segmented upload step (see above)
TEMPORARY_URL = "http://example.com/temporary_url"

upload_status = client.segmented_upload_status(TEMPORARY_URL)

print(upload_status.received)
print(upload_status.expecting)
print(upload_status.size)
print(upload_status.segment_size)

Deposit a file uploaded by segments

from sword3client import SWORD3Client
client = SWORD3Client()

SERVICE = "http://example.com/service-document"

# Temporary URL obtained from initialisation of segmented upload step (see above)
TEMPORARY_URL = "http://example.com/temporary_url"

resp = client.create_object_with_temporary_file(SERVICE,
                                            TEMPORARY_URL,
                                            "test.zip",
                                            "application/zip")

Creating an object with metadata and then add a file

Here’s an example of usage, to create a deposit with metadata and a single file:

from sword3client import SWORD3Client
from sword3common import Metadata

metadata = Metadata()
metadata.add_dc_field("creator", "Smith, J.")
metadata.add_dcterms_field("license", "https://creativecommons.org/licenses/by-sa/4.0/")
metadata.add_field("custom", "entry")

client = SWORD3Client()

# create the object with the metadata document, and set in_progress=True to allow
# us to come back and add more content to the object
dr = client.create_object_with_metadata(SERVICE_URL, metadata, in_progress=True)

with open('data-table.csv') as f:
    # calcuate the SHA-256 for the binary
    sha256 = hashlib.sha256()
    for chunk in iter(lambda: f.read(4096), b""):
        sha256.update(chunk)

    content_length = f.tell()
    f.seek(0)

    digest = {constants.DIGEST_SHA_256: sha256.digest()}

    # send the binary file to be added to the object
    client.add_binary(
        dr.status_document,
        f,
        'data-table.csv',
        digest,
        content_length,
        content_type="text/csv"
    )