ada.services package

Submodules

ada.services.checksum module

Checksum service — retrieve file checksums from dCache.

Supports MD5 and Adler32 checksums, with recursive directory traversal and file-list input.

class ada.services.checksum.ChecksumService(api: DcacheAPI, namespace: NamespaceService | None = None)

Bases: object

Checksum retrieval for dCache files.

get(paths: str | list[str] | None = None, recursive: bool = False, from_file: str | None = None) → list[Checksum]

Get checksums for one or more files.

Args:

paths: File or directory path(s). recursive: If True, recurse into directories. from_file: Path to a file containing one path per line.

Returns:

List of Checksum objects.

ada.services.events module

Event service — SSE event streaming and channel management.

Handles subscribing to inotify events, monitoring staging progress, and managing event channels in the dCache API.

class ada.services.events.AdaState(base_dir: str | Path | None = None)

Bases: object

Manages ~/.ada/ state directory.

delete_channel_files(channel_id: str) → None

Remove all state files for a channel.

find_channel_id_by_name(name: str) → str | None

Find a channel ID by its human-readable name.

get_channel_name(channel_id: str) → str | None

Get the human-readable name for a channel ID.

get_last_event_id(channel_id: str) → str | None

Get the last processed event ID for a channel.

list_channels() → list[dict[str, str]]

List all known channels with their IDs and names.

log_request(lines: list[str]) → None

Append lines to the requests log.

save_channel_name(channel_id: str, name: str) → None

Save the mapping of channel ID to human-readable name.

save_last_event_id(channel_id: str, event_id: str) → None

Save the last processed event ID for resume support.

class ada.services.events.EventService(api: DcacheAPI, state: AdaState | None = None)

Bases: object

SSE event streaming and channel management for dCache.

delete_channel(name: str) → None

Delete an event channel by name.

Removes both the API-side channel and local state files.

list_channels(name: str | None = None) → Any

List event channels.

Args:

name: If specified, return details for this channel.

Otherwise, return all channels.

Returns:

Channel details dict or list of channels.

report_staged(channel_name: str, path: str, recursive: bool = False, timeout: int = 3600) → Iterator[dict[str, Any]]

Monitor file locality/QoS changes (staging progress).

Similar to subscribe but watches for QoS transition events.

Yields:

Events related to file staging status changes.

subscribe(channel_name: str, path: str, recursive: bool = False, resume: bool = False, force: bool = False, timeout: int = 3600) → Iterator[dict[str, Any]]

Subscribe to inotify events on a path.

Creates (or reuses) an event channel, adds a subscription for inotify events, then streams events via SSE.

Args:

channel_name: Human-readable channel name. path: dCache path to watch. recursive: If True, watch subdirectories too. resume: If True, resume from last processed event. force: If True, create a new channel even if one exists. timeout: SSE connection timeout in seconds.

Yields:

Parsed event dicts from the SSE stream.

ada.services.labels module

Label service — file metadata tagging on dCache.

Labels are simple string tags attached to files. Directories cannot have labels (dCache restriction).

class ada.services.labels.LabelService(api: DcacheAPI, namespace: NamespaceService | None = None)

Bases: object

Label management for dCache files.

find(path: str, regex: str, recursive: bool = False) → list[tuple[str, list[str]]]

Find files with labels matching a regex pattern.

Args:

path: Directory to search. regex: Regular expression to match against labels. recursive: If True, search subdirectories.

Returns:

List of (file_path, matching_labels) tuples.

list(path: str, label: str | None = None) → list[str]

List labels attached to a file.

Args:

path: File path. label: If specified, check if this specific label exists.

Returns:

List of label strings.

remove(path: str, label: str = '', all_labels: bool = False) → str

Remove a label from a file.

Args:

path: File path. label: Specific label to remove. all_labels: If True, remove all labels.

Returns:

Status message.

set(path: str, label: str) → str

Attach a label to a file.

Args:

path: File path (must be a regular file, not a directory). label: Label string to attach.

Returns:

Status message.

Raises:

AdaPathError: If the path is a directory.

ada.services.namespace module

Namespace service — file and directory operations on dCache.

Handles list, longlist, stat, mkdir, mv, delete, and helper functions for recursive traversal and path type detection.

class ada.services.namespace.NamespaceService(api: DcacheAPI)

Bases: object

File and directory operations on the dCache namespace.

delete(path: str, recursive: bool = False, force: bool = False) → None

Delete a file or directory.

Args:

path: Path to delete. recursive: If True, delete directory contents recursively. force: If True, skip confirmation prompts (library usage).

Raises:

AdaPathError: If the directory is not empty and recursive is False.

get_file_type(path: str) → FileType

Get the type of a path (DIR, REGULAR, LINK).

get_files_in_dir(path: str) → list[str]

Get regular file names within a directory.

get_pnfs_id(path: str) → str

Get the PNFS ID of a file or directory.

get_subdirs(path: str) → list[str]

Get subdirectory names within a directory.

is_dir(path: str) → bool

Check if a path is a directory. Returns False if not found.

is_online(path: str) → bool

Check if a file is online (not only on tape).

list(path: str) → list[str]

List directory contents or return the file path itself.

For directories, returns sorted child names with ‘/’ appended for subdirs.

longlist(paths: str | list[str] | None = None, from_file: str | None = None) → list[FileInfo]

Get detailed file information for one or more paths.

For directories, lists children with size, mtime, QoS, and locality.

mkdir(path: str, recursive: bool = False, _depth: int = 0) → str

Create a directory.

Args:

path: The directory path to create. recursive: If True, create parent directories as needed.

Returns:

Status message.

Raises:

AdaValidationError: If recursive depth exceeds MAX_RECURSIVE_MKDIR. AdaPathError: If parent does not exist and recursive is False.

mv(source: str, destination: str) → str

Move or rename a file or directory.

Raises:

AdaPathError: If the destination already exists.

stat(path: str) → FileInfo

Get complete metadata for a file or directory.

Includes children, locality, locations, QoS, xattr, labels, checksums.

with_files_in_dir(path: str, recursive: bool = False) → list[str]

Get full paths of all regular files in a directory.

If recursive, traverses subdirectories.

ada.services.staging module

Staging service — tape staging and unstaging operations.

Handles bringing files from tape to disk (staging), releasing disk copies (unstaging), and managing bulk requests.

class ada.services.staging.StagingService(api: DcacheAPI, namespace: NamespaceService | None = None)

Bases: object

Stage/unstage operations for dCache tape-backed storage.

delete_request(request_id: str) → None

Delete a bulk request.

Args:

request_id: The bulk request ID to delete.

stage(paths: str | list[str] | None = None, recursive: bool = False, lifetime: str = '7D', from_file: str | None = None) → BulkRequest

Stage files from tape to disk.

Args:

paths: File or directory path(s) to stage. recursive: If True, stage files recursively in directories. lifetime: How long to keep files online (e.g., ‘7D’, ‘24H’). from_file: Path to a file containing one path per line.

Returns:

BulkRequest with the request ID and details.

stat_request(request_id: str) → BulkRequestStatus

Get the status of a bulk request.

Args:

request_id: The bulk request ID.

Returns:

BulkRequestStatus with target details.

unstage(paths: str | list[str] | None = None, recursive: bool = False, request_id: str | None = None, from_file: str | None = None) → BulkRequest

Unstage files — release pins so dCache can purge disk copies.

Args:

paths: File or directory path(s) to unstage. recursive: If True, unstage files recursively. request_id: Specific bulk request ID to unpin. from_file: Path to a file containing one path per line.

Returns:

BulkRequest with details.

ada.services.system module

System service — whoami, space, and quota operations.

Provides user identity, storage space, and quota information.

class ada.services.system.SystemService(api: DcacheAPI)

Bases: object

System information from the dCache API.

check_authenticated() → bool

Check if the user is authenticated by calling the user endpoint.

Returns True if authenticated, raises on failure.

quota() → list[QuotaInfo]

Get storage quota information for the current user.

Returns a list of quota entries (user and group quotas, for both disk and tape storage).

space(poolgroup: str | None = None) → SpaceInfo | list[str]

Get storage space information.

Args:

poolgroup: If specified, return space info for this pool group.

If None, return a list of available pool group names.

Returns:

SpaceInfo for a specific pool group, or list of pool group names.

whoami() → UserInfo

Get the authenticated user’s identity.

Returns user info including UID, GIDs, username, home directory, and the dCache version.

ada.services.xattr module

Extended attributes service — key-value metadata on dCache files.

Extended attributes (xattr) are key-value pairs that can be attached to files for custom metadata storage.

class ada.services.xattr.XattrService(api: DcacheAPI, namespace: NamespaceService | None = None)

Bases: object

Extended attribute management for dCache files.

find(path: str, key: str, regex: str, recursive: bool = False, all_keys: bool = False) → list[tuple[str, dict[str, str]]]

Find files with extended attributes matching a regex.

Args:

path: Directory to search. key: Attribute key to match against (or search all keys if all_keys=True). regex: Regular expression to match against attribute values. recursive: If True, search subdirectories. all_keys: If True, search all attribute keys.

Returns:

List of (file_path, matching_attributes) tuples.

list(path: str, key: str | None = None) → dict[str, str]

List extended attributes of a file.

Args:

path: File path. key: If specified, return only this attribute.

Returns:

Dict of attribute key-value pairs.

remove(path: str, key: str = '', all_keys: bool = False) → str

Remove extended attribute(s) from a file.

Args:

path: File path. key: Specific attribute key to remove. all_keys: If True, remove all extended attributes.

Returns:

Status message.

set(path: str, attributes: dict[str, str] | str) → str

Set extended attributes on a file.

Args:

path: File path. attributes: Either a dict of key-value pairs, or a string

in JSON/key=value format that will be parsed.

Returns:

Status message.

set_from_file(path: str, attr_file: str) → str

Set extended attributes from a file.

The file can contain JSON or key=value pairs.

Module contents