Repository service¶

`consortium.server.services.repository_service` ¶

`RepositoryService(repository_directory_path, data_model=None)` ¶

`repository_directory_path = repository_directory_path` `instance-attribute` ¶

`load_repository_metadata()` ¶

Loads repository resource metadata from the repository metadata JSON file on disk.

If the metadata file does not yet exist, an empty metadata file is created via save_repository_metadata. Resources listed in the metadata but missing from disk raise an error rather than being silently skipped.

Raises:

Type	Description
`RepositoryMetadataFileEncodingError`	If the metadata file's bytes are not valid UTF-8.
`RepositoryMetadataFileJSONError`	If the metadata file contains invalid JSON.
`RepositoryMetadataFileSchemaError`	If the metadata file does not follow the expected schema.
`RepositoryMetadataFileUnsyncedError`	If a resource recorded in the metadata file does not exist on disk.
`RepositoryMetadataFileResourceDataSchemaError`	If a `data` field in the metadata file fails validation against the repository's `data_model`. Only raised when the repository was constructed with a `data_model`.
`RepositoryMetadataFileSystemError`	If the metadata file cannot be read from disk.

`save_repository_metadata()` ¶

Writes the current in-memory repository resource metadata to disk as JSON.

Raises:

Type	Description
`RepositoryResourceFileSystemError`	If a tracked resource's `size` or `datetime_modified` cannot be read from disk while its metadata representation is being built.
`RepositoryMetadataFileSystemError`	If the metadata file cannot be written to disk.
`TypeError`	If a tracked resource's `data` is not JSON serializable. This is deliberately left unwrapped: it means a caller associated data with a resource that cannot be persisted, which is a defect in that caller rather than a condition the repository can report on and continue past.

`reserve_resource_id()` ¶

Generates and reserves a resource ID to be claimed during resource creation.

The reserved ID must be passed as resource_id to create_file or create_directory. This allows the caller to know the resource ID before the file or directory is created (e.g., to embed the ID in the file content).

Returns:

Type	Description
`UUID`	The reserved resource ID.

`create_file(content, resource_id=None, name=None, description='', data=None)` ¶

Creates and persists a new file resource in the repository.

The file is stored on disk under its resource ID alone, with no extension. Metadata is persisted after creation.

Parameters:

Name	Type	Description	Default
`content`	`str \| bytes \| TextIO \| BinaryIO`	The file content to write.	required
`name`	`str \| None`	A human-readable name for the file, recorded exactly as given and used as the name the resource is served and downloaded under. When `None`, the resource UUID is used as the name.	`None`
`description`	`str`	An optional description for the file.	`''`
`resource_id`	`str \| UUID \| None`	A previously reserved ID to assign to this resource. When `None`, a new ID is generated automatically.	`None`
`data`	`dict[str, JsonValue] \| None`	Optional additional metadata to associate with the file resource.	`None`

Returns:

Type	Description
`RepositoryFile`	The newly created repository file resource.

Raises:

Type	Description
`ResourceIDReservationNotFoundError`	If `resource_id` is provided but has no corresponding reservation.
`RepositoryResourceFileSystemError`	If the file cannot be written to disk.
`RepositoryMetadataFileSystemError`	If the metadata file cannot be written to disk.
`UnicodeDecodeError`	If `content` is a text stream carrying content that cannot be decoded. Left unwrapped as it describes the content the caller supplied rather than a failure of the repository itself.

`add_file(path, copy=False, resource_id=None, name=None, description='', data=None)` ¶

Registers an existing file on disk into the repository.

Unlike create_file, no new file is written. The file at path is moved (or copied when copy=True) into the repository directory under its resource ID alone, with no extension, and registered as a resource. Metadata is persisted after registration.

Parameters:

Name	Type	Description	Default
`path`	`Path \| str`	Path to the existing file to register.	required
`copy`	`bool`	When `False` (default) the source file is moved into the repository. When `True` the source file is copied and the original is left in place.	`False`
`resource_id`	`str \| UUID \| None`	A previously reserved ID to assign to this resource. When `None`, a new ID is generated.	`None`
`name`	`str \| None`	A human-readable name for the file, recorded exactly as given and used as the name the resource is served and downloaded under. Never affects how the file is stored on disk. When `None`, the original filename is used.	`None`
`description`	`str`	An optional description for the file.	`''`
`data`	`dict[str, JsonValue] \| None`	Optional additional metadata to associate with the file resource.	`None`

Returns:

Type	Description
`RepositoryFile`	The newly registered repository file resource.

Raises:

Type	Description
`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 metadata file cannot be written to disk. The file has already been moved or copied into the repository by this point, so the resource exists on disk without being recorded.

`create_directory(content=None, archive_file_format=None, resource_id=None, name=None, description='', data=None)` ¶

Creates and persists a new directory resource in the repository.

How content is interpreted depends on its type. Raw bytes and open binary streams are treated as archive content and unpacked into the new directory using archive_file_format. A str or pathlib.Path is instead treated as a path to an existing source directory whose tree is copied into the new directory, and archive_file_format is ignored. Metadata is persisted after creation.

Parameters:

Name	Type	Description	Default
`content`	`bytes \| BinaryIO \| str \| Path \| None`	Archive content to unpack into the directory (as raw bytes or an open binary stream), or a path to an existing source directory to copy in, or `None` to create an empty directory.	`None`
`archive_file_format`	`Literal['zip', 'tar', 'gztar', 'bztar', 'xztar'] \| None`	The archive format to use when unpacking `content`. Must be set when `content` is archive content. Ignored when `content` is a source directory path.	`None`
`resource_id`	`str \| UUID \| None`	A previously reserved ID to assign to this resource. When `None`, a new ID is generated automatically.	`None`
`name`	`str \| None`	A human-readable name for the directory, recorded exactly as given and used as the name the resource is served and downloaded under. When `None`, the resource UUID is used as the name.	`None`
`description`	`str`	An optional description for the directory.	`''`
`data`	`dict[str, JsonValue] \| None`	Optional additional metadata to associate with the directory resource.	`None`

Returns:

Type	Description
`RepositoryDirectory`	The newly created repository directory resource.

Raises:

Type	Description
`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 metadata file cannot be written to disk.

`add_directory(path, copy=False, resource_id=None, name=None, description='', data=None)` ¶

Registers an existing directory on disk into the repository.

Unlike create_directory, no new directory content is created: the directory at path is moved (or copied when copy=True) into the repository directory under a UUID-based name and registered as a resource. When copy=True, a new directory is created on disk to hold the copy (via shutil.copytree) and the original at path is left in place; when copy=False (default), the source directory itself is relocated via shutil.move, and no copy is made. Metadata is persisted after registration.

Parameters:

Name	Type	Description	Default
`path`	`Path \| str`	Path to the existing directory to register.	required
`copy`	`bool`	When `False` (default) the source directory is moved into the repository. When `True` the source directory is copied and the original is left in place.	`False`
`resource_id`	`str \| UUID \| None`	A previously reserved ID to assign to this resource. When `None`, a new ID is generated.	`None`
`name`	`str \| None`	A human-readable name for the directory. When `None`, the original directory name is used.	`None`
`description`	`str`	An optional description for the directory.	`''`
`data`	`dict[str, JsonValue] \| None`	Optional additional metadata to associate with the directory resource.	`None`

Returns:

Type	Description
`RepositoryDirectory`	The newly registered repository directory resource.

Raises:

Type	Description
`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 metadata file cannot be written to disk. The directory has already been moved or copied into the repository by this point, so the resource exists on disk without being recorded.

`update_resource_by_resource_id(resource_id, name=None, description=None, data=None)` ¶

Updates a repository resource's metadata.

Metadata is persisted after the update.

Parameters:

Name	Type	Description	Default
`resource_id`	`str \| UUID`	The ID of the resource to update.	required
`name`	`str \| None`	A new human-readable name for the resource, recorded exactly as given and used as the name the resource is served and downloaded under. Nothing on disk is renamed. When `None`, the existing name is preserved.	`None`
`description`	`str \| None`	A new description for the resource. When `None`, the existing description is preserved.	`None`
`data`	`dict[str, JsonValue] \| None`	New additional metadata to associate with the resource. When `None`, the existing data is preserved.	`None`

Returns:

Type	Description
`RepositoryFile \| RepositoryDirectory`	The updated repository resource.

Raises:

Type	Description
`ResourceNotFoundError`	If no resource with the given ID exists.
`RepositoryMetadataFileSystemError`	If the metadata file cannot be written to disk.

`delete_resource_by_resource_id(resource_id)` ¶

Deletes a repository resource from disk and removes it from the registry.

Metadata is persisted after deletion.

Parameters:

Name	Type	Description	Default
`resource_id`	`str \| UUID`	The ID of the resource to delete.	required

A resource whose file or directory is already missing from the repository directory is deleted successfully rather than reported as an error. The caller asked for the resource not to exist and it does not, so the deregistration below is all that is left to do.

Raises:

Type	Description
`ResourceNotFoundError`	If no resource with the given ID exists.
`RepositoryResourceFileSystemError`	If the resource cannot be removed from disk.
`RepositoryMetadataFileSystemError`	If the metadata file cannot be written to disk.

`get_all_resources()` ¶

Returns all resources currently tracked by the repository service.

Returns:

Type	Description
`list[RepositoryFile \| RepositoryDirectory]`	A list of all repository resources. Empty if none have been created.

`get_resource_by_resource_id(resource_id)` ¶

Returns a repository resource by its ID.

Parameters:

Name	Type	Description	Default
`resource_id`	`str \| UUID`	The ID of the resource to retrieve.	required

Returns:

Type	Description
`RepositoryFile \| RepositoryDirectory`	The requested repository resource.

Raises:

Type	Description
`ResourceNotFoundError`	If no resource with the given ID exists.

Repository service¶

consortium.server.services.repository_service ¶