API Reference

This section documents the public API of the darca-repository module, including its key classes, interfaces, exceptions, and registries.

Repository Instance

class darca_repository.instance.RepositoryInstance(repository: Repository)[source]

Bases: object

Represents an active repository instance with its storage client resolved.

Provides access to:

repository metadata
associated StorageClient

property client: StorageClient | None: Return the connected StorageClient if available.

async connect() → StorageClient[source]

property metadata: Repository

property name: str

async test_connection() → bool[source]

Probes whether the repository’s root directory is reachable.

Returns:: True if the repository is usable, False otherwise.
Return type:: bool

Models

class darca_repository.models.Repository(*, name: str, storage_url: str, scheme: ~darca_repository.models.StorageScheme, credentials: ~typing.Dict[str, ~pydantic.types.SecretStr] | None = None, parameters: ~typing.Dict[str, str] = <factory>, tags: ~typing.Dict[str, str] | None = None, enabled: bool = True, priority: int | None = None)[source]

Bases: BaseModel

Represents a configured repository for storing logical spaces.

credentials: Dict[str, SecretStr] | None

enabled: bool

get_secret(key: str) → str | None[source]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

parameters: Dict[str, str]

priority: int | None

scheme: StorageScheme

storage_url: str

tags: Dict[str, str] | None

class darca_repository.models.StorageScheme(*values)[source]

Bases: str, Enum

FILE = 'file'

MEMORY = 'mem'

NFS = 'nfs'

S3 = 's3'

Registry System

darca_repository.registry.factory.get_repository_registry() → RepositoryRegistry[source]: Factory to instantiate the appropriate RepositoryRegistry backend based on the DARCA_REPOSITORY_MODE environment variable.

class darca_repository.registry.base.RepositoryRegistry[source]

Abstract interface for loading and managing repository profiles.

Implementations may load profiles from: - Local YAML files - SQL databases (MySQL, PostgreSQL, etc.) - Remote config services

abstractmethod get_profile(name: str) → Repository[source]

Retrieve a single repository profile by its name.

Raises:: KeyError – if the profile does not exist.

abstractmethod list_profiles() → List[Repository][source]: Return a list of all available repository profiles.

class darca_repository.registry.yaml_registry.YamlRepositoryRegistry(directory: str)[source]

Loads repository profiles from a YAML directory.

Each YAML file represents a single repository profile.

get_profile(name: str) → Repository[source]

Retrieve a single repository profile by its name.

Raises:: KeyError – if the profile does not exist.

list_profiles() → List[Repository][source]: Return a list of all available repository profiles.

class darca_repository.registry.mysql_registry.MySQLRepositoryRegistry(connection_url: str, user: str, password: str)[source]

Future implementation: MySQL-backed repository registry.

Intended to support centralized, mutable repository configurations.

list_profiles() → List[Repository][source]: Return a list of all available repository profiles.

Exceptions

exception darca_repository.exceptions.RepositoryAccessDenied(name: str, user: str | None = None)[source]: Bases: RepositoryException

exception darca_repository.exceptions.RepositoryConnectionError(name: str, *, message: str = None, cause: Exception = None)[source]: Bases: RepositoryException

exception darca_repository.exceptions.RepositoryException(message: str, error_code: str = 'REPOSITORY_ERROR', metadata: dict | None = None, cause: Exception | None = None)[source]

Bases: DarcaException

General-purpose exception for repository-related failures.

exception darca_repository.exceptions.RepositoryNotFound(name: str)[source]: Bases: RepositoryException

exception darca_repository.exceptions.RepositoryNotFoundError(name: str)[source]: Bases: RepositoryException

exception darca_repository.exceptions.RepositoryValidationError(message: str, *, cause: Exception = None)[source]

Bases: RepositoryException

Raised when a repository fails validation checks.