Skip to content

Assets service

consortium.server.services.assets_service

AssetsService(events_service, repository_service, user_accounts_service)

repository_directory_path = repository_service.repository_directory_path instance-attribute

load_repository_metadata()

See RepositoryService.load_repository_metadata.

save_repository_metadata()

See RepositoryService.save_repository_metadata.

reserve_resource_id()

Reserves and returns a new resource ID without creating any asset.

The returned ID can later be passed as resource_id to one of the asset creation methods to claim it. Reserving an ID up front lets a caller learn the asset's ID before its file or directory exists on disk (for example to embed the ID inside the content that will be stored).

Returns:

Type Description
UUID

The freshly reserved resource ID, unique across the repository.

create_asset_file(content, name=None, description='', resource_id=None, user_account_id=None) async

Creates a new asset file from in-memory or streamed content.

The content is written to a new file on disk in the assets repository and an ASSET_CREATED event is emitted. When a user_account_id is supplied the uploading user account is resolved and recorded against the asset for attribution.

Parameters:

Name Type Description Default
content str | bytes | TextIO | BinaryIO

The content to write into the new asset file, supplied either directly as text/bytes or as an open text/binary stream to read the content from.

 required
name str | None

A human-readable display name for the asset. When None, the asset's generated UUID is used as its name.

 None
description str

A short human-readable description of the asset. Defaults to an empty string when omitted.

 ''
resource_id str | UUID | None

A previously reserved resource ID to claim for this asset. When None, a new ID is generated automatically.

 None
user_account_id str | UUID | None

The ID of the user account that uploaded this asset, recorded for attribution. When None, the asset is stored with no uploading user account.

 None

Returns:

Type Description
Asset

The newly created asset file resource.

Raises:

Type Description
UserAccountIDNotFoundError

If user_account_id is provided but no user account with that ID exists.
ResourceIDReservationNotFoundError

If resource_id is provided but has no corresponding reservation.
RepositoryResourceFileSystemError

If the file cannot be written to disk.
RepositoryMetadataFileSystemError

If the asset metadata cannot be written to disk after the file is written.
UnicodeDecodeError

If content is a text stream carrying content that cannot be decoded.

add_asset_file(path, name=None, description='', resource_id=None, copy=False, user_account_id=None) async

Registers an existing file on disk as an asset.

Unlike create_asset_file, no new content is written: the file at path is moved (or copied when copy=True) into the assets repository, registered as a resource, and an ASSET_CREATED event is emitted. When a user_account_id is supplied the uploading user account is resolved and recorded for attribution.

Parameters:

Name Type Description Default
path Path | str

Filesystem path to the existing file to ingest as an asset.

 required
name str | None

A human-readable display name for the asset. When None, the original filename is used.

 None
description str

A short human-readable description of the asset. Defaults to an empty string when omitted.

 ''
resource_id str | UUID | None

A previously reserved resource ID to claim for this asset. When None, a new ID is generated automatically.

 None
copy bool

When False (default) the source file is moved into the repository, leaving nothing at the original path. When True the source file is copied and the original is left in place.

 False
user_account_id str | UUID | None

The ID of the user account that uploaded this asset, recorded for attribution. When None, the asset is stored with no uploading user account.

 None

Returns:

Type Description
Asset

The newly registered asset file resource.

Raises:

Type Description
UserAccountIDNotFoundError

If user_account_id is provided but no user account with that ID exists.
ResourceIDReservationNotFoundError

If resource_id is provided but has no corresponding reservation.
RepositoryResourceFileSystemError

If no file exists at path, or the file cannot be moved or copied into the repository.
RepositoryMetadataFileSystemError

If the asset metadata cannot be written to disk afterwards.

create_asset_directory(content=None, archive_file_format=None, name=None, description='', resource_id=None, user_account_id=None) async

Creates a new asset directory, optionally populated from existing content.

An empty directory is created on disk in the assets repository, or, when content is provided, it is populated from that content. How content is interpreted depends on its type: raw bytes and open binary streams are unpacked as archive content using archive_file_format, while a str or pathlib.Path is treated as a path to an existing source directory whose tree is copied in. An ASSET_CREATED event is emitted. When a user_account_id is supplied the uploading user account is resolved and recorded for attribution.

Parameters:

Name Type Description Default
content bytes | BinaryIO | str | Path | None

Archive content to unpack into the new directory, supplied as raw bytes or an open binary stream, or a path to an existing source directory to copy in. When None, an empty directory is created.

 None
archive_file_format Literal['zip', 'tar', 'gztar', 'bztar', 'xztar'] | None

The archive format used to interpret content when unpacking. Must be set whenever content is archive content; ignored when content is a source directory path or None.

 None
name str | None

A human-readable display name for the asset. When None, the asset's generated UUID is used as its name.

 None
description str

A short human-readable description of the asset. Defaults to an empty string when omitted.

 ''
resource_id str | UUID | None

A previously reserved resource ID to claim for this asset. When None, a new ID is generated automatically.

 None
user_account_id str | UUID | None

The ID of the user account that uploaded this asset, recorded for attribution. When None, the asset is stored with no uploading user account.

 None

Returns:

Type Description
Asset

The newly created asset directory resource.

Raises:

Type Description
UserAccountIDNotFoundError

If user_account_id is provided but no user account with that ID exists.
ResourceIDReservationNotFoundError

If resource_id is provided but has no corresponding reservation.
InvalidRepositoryDirectoryArchiveFileFormatError

If content is archive content that cannot be unpacked as archive_file_format, or if archive_file_format is not set.
RepositoryResourceFileSystemError

If the directory cannot be created or the source directory or archive cannot be unpacked into it.
RepositoryMetadataFileSystemError

If the asset metadata cannot be written to disk after the directory is created.

add_asset_directory(path, name=None, description='', resource_id=None, copy=False, user_account_id=None) async

Registers an existing directory on disk as an asset.

Unlike create_asset_directory, no new directory is created: the directory at path is moved (or copied when copy=True) into the assets repository, registered as a resource, and an ASSET_CREATED event is emitted. When a user_account_id is supplied the uploading user account is resolved and recorded for attribution.

Parameters:

Name Type Description Default
path Path | str

Filesystem path to the existing directory to ingest as an asset.

 required
name str | None

A human-readable display name for the asset. When None, the original directory name is used.

 None
description str

A short human-readable description of the asset. Defaults to an empty string when omitted.

 ''
resource_id str | UUID | None

A previously reserved resource ID to claim for this asset. When None, a new ID is generated automatically.

 None
copy bool

When False (default) the source directory is moved into the repository, leaving nothing at the original path. When True the source directory is copied and the original is left in place.

 False
user_account_id str | UUID | None

The ID of the user account that uploaded this asset, recorded for attribution. When None, the asset is stored with no uploading user account.

 None

Returns:

Type Description
Asset

The newly registered asset directory resource.

Raises:

Type Description
UserAccountIDNotFoundError

If user_account_id is provided but no user account with that ID exists.
ResourceIDReservationNotFoundError

If resource_id is provided but has no corresponding reservation.
RepositoryResourceFileSystemError

If no directory exists at path, or the directory or any file within it cannot be moved or copied into the repository.
RepositoryMetadataFileSystemError

If the asset metadata cannot be written to disk afterwards.

update_asset_by_resource_id(resource_id, name=None, description=None, user_account_id=_UNSET) async

Updates an asset's mutable metadata.

name and description are updated in place when provided. The asset's stored data is only rebuilt when user_account_id is passed, mirroring the attribution parameter of the asset creation methods: the given user account is resolved into a stored reference exactly as it would be on creation. When user_account_id is omitted the existing data is left untouched. An ASSET_UPDATED event is emitted.

Parameters:

Name Type Description Default
resource_id str | UUID

The ID of the asset to update.

 required
name str | None

A new human-readable display name for the asset. When None, the existing name is preserved.

 None
description str | None

A new description for the asset. When None, the existing description is preserved.

 None
user_account_id str | UUID | None

When provided, rebuilds the asset's attribution data from this user account ID (or clears attribution when None). When omitted entirely, the asset's existing data is left unchanged.

 _UNSET

Returns:

Type Description
Asset

The updated asset resource.

Raises:

Type Description
ResourceNotFoundError

If no asset with the given ID exists.
UserAccountIDNotFoundError

If user_account_id is provided but no user account with that ID exists.
RepositoryMetadataFileSystemError

If the updated metadata cannot be written to disk.

delete_asset_by_resource_id(resource_id) async

Deletes an asset from disk and the repository.

The asset's metadata is snapshotted before removal so it can be carried on the emitted ASSET_DELETED event, then the resource is deleted from disk and deregistered.

Parameters:

Name Type Description Default
resource_id str | UUID

The ID of the asset to delete.

 required

An asset whose file or directory is already missing from the repository directory is deleted successfully: the record is deregistered and the event is still emitted.

Raises:

Type Description
ResourceNotFoundError

If no asset with the given ID exists.
RepositoryResourceFileSystemError

If the asset's file or directory exists on disk but cannot be deleted.
RepositoryMetadataFileSystemError

If the metadata file cannot be written to disk after deletion.

get_all_assets()

Returns every asset currently tracked by the assets service.

Returns:

Type Description
list[Asset]

A list of all assets, covering both file and directory assets, each wrapping its repository resource. Empty if no assets exist.

get_asset_by_resource_id(resource_id)

Returns a single asset by its ID.

Parameters:

Name Type Description Default
resource_id str | UUID

The ID of the asset to retrieve.

 required

Returns:

Type Description
Asset

The requested asset resource, either a file or a directory depending on how it was created.

Raises:

Type Description
ResourceNotFoundError

If no asset with the given ID exists.