PathHierarchy

class caqtus.session.PathHierarchy(*args, **kwargs)

Bases: Protocol

A file-system-like object that exists inside a session.

This object provides methods that can be used to create, delete and check for the existence of sequences.

abstractmethod does_path_exists(
path: PureSequencePath,
) → bool

Check if the path exists in the session.

Parameters:

path – the path to check for existence.

Returns:

True if the path exists in the session. False otherwise.

abstractmethod create_path(
path: PureSequencePath,
) → Success[list[PureSequencePath]] | Failure[PathIsSequenceError]

Create the path in the session and its ancestors if they do not exist.

If is safe to call this method even if the path already exists, in which case it will return a Success with an empty list.

Parameters:

path – the path to create.

Returns:

  • Success, with a list of the paths that were created if the path was created successfully. The list is ordered from parent to child.

  • Failure, with PathIsSequenceError if the path or one of its ancestors is a sequence. No path is created if any of the ancestors is a sequence.

    If a failure is returned, not paths are created.

abstractmethod delete_path(
path: PureSequencePath,
delete_sequences: bool = False,
) → Success[None] | Failure[PathNotFoundError] | Failure[PathIsSequenceError] | Failure[PathIsRootError]

Delete the path and all its descendants.

Warning

If delete_sequences is True, all sequences in the path will be deleted.

Parameters:

  • path – The path to delete. Descendants will be deleted recursively.

  • delete_sequences – If False, raise an error if the path or one of its

  • sequence. (children is a)

Returns:

Success, if the path was deleted successfully.

Failure, with one of the following errors:

  • PathNotFoundError: If the path does not exist.

  • PathIsSequenceError: If the path or one of its children is a sequence and

    delete_sequence is False.

  • PathIsRootError: If the path is the root path.

abstractmethod get_children(
path: PureSequencePath,
) → Success[set[PureSequencePath]] | Failure[PathNotFoundError] | Failure[PathIsSequenceError]

Get the children of the path.

abstractmethod get_path_creation_date(
path: PureSequencePath,
) → Success[datetime] | Failure[PathNotFoundError] | Failure[PathIsRootError]

Get the creation date of the path.

Parameters:

path – the path to get the creation date for.

Returns:

The creation date of the path.

abstractmethod get_all_paths() → set[PureSequencePath]

Get all the paths in the session.

Returns:

A set of all the paths in the session.

abstractmethod update_creation_date(
path: PureSequencePath,
date: datetime,
) → None

Update the creation date of the path.

This method is meant to be used for maintenance purposes only, such as when copying sequences from one session to another.

Parameters:

  • path – the path to update the creation date for.

  • date – the new creation date.

abstractmethod move(
source: PureSequencePath,
destination: PureSequencePath,
) → Success[None] | Failure[PathNotFoundError] | Failure[PathExistsError] | Failure[PathIsSequenceError] | Failure[RecursivePathMoveError] | Failure[SequenceRunningError]

Move a path to a new location.

Parameters:

  • source – The path to move.

  • destination – The new location of the path. If a parent of the destination path does not exist, it will be created.

Returns:

Success if the path was moved successfully. Failure with one of the following errors:

  • PathNotFoundError: If the source path does not exist.

  • PathExistsError: If the destination path already exists.

  • PathIsSequenceError: If an ancestor in the destination path is a sequence.

  • RecursivePathMoveError: If the destination path is the source path or a

    descendant of the source path. As a specific case, this error is returned if the source is the root path.

  • SequenceRunningError: If the source path contains a sequence that is currently running.

If a failure is returned, the path is not moved and no path is created.