adsfolio.pdf.tracked_move

Filesystem moves kept consistent with the PDF catalog.

class adsfolio.pdf.tracked_move.TrackedFileState(*args, **kwargs)[source]

Bases: Protocol

State operations required for a catalog-consistent file move.

directory: pathlib.Path
find_by_current_filename(filename)[source]
Parameters:

filename (str)

Return type:

tuple[str, collections.abc.Mapping[str, Any]] | None

save()[source]
Return type:

pathlib.Path

set_current_filename(original_filename, current_filename)[source]
Parameters:

  • original_filename (str)

  • current_filename (str)

Return type:

bool

exception adsfolio.pdf.tracked_move.TrackedMoveConflictError(source, destination)[source]

Bases: FileExistsError

Report a move destination that already exists as a distinct file.

Parameters:

  • source (Path)

  • destination (Path)

Return type:

None

exception adsfolio.pdf.tracked_move.TrackedMoveRollbackError[source]

Bases: RuntimeError

Report both catalog and filesystem rollback failures.

adsfolio.pdf.tracked_move.is_same_file_alias(source_path, destination_path)[source]

Check whether two paths name the exact same directory entry.

Returns True when both paths reference the same device and inode in the same parent directory, neither path is a symlink, and the destination name is not an independently existing directory entry (such as a hard link).

Parameters:
Return type:

bool

adsfolio.pdf.tracked_move.move_tracked_file(state, source_path, destination_path)[source]

Move one tracked file and update its root-relative catalog location.

The filesystem move is rolled back if the catalog update fails.

Parameters:
Return type:

pathlib.Path

adsfolio.pdf.tracked_move.move_tracked_file_outside_root(state, source_path, destination_path)[source]

Move a selected PDF outside its library and retain its location history.

Parameters:

  • state (CentralPdfRegistryState) – Open catalog state for the source library.

  • source_path (Path) – Current path of the tracked PDF inside the library root.

  • destination_path (Path) – New path outside the root on the same filesystem.

Returns:

Destination after the catalog marks the old location missing.

Return type:

Path

Raises:

  • ValueError – The source lies outside the root or the destination lies inside it.

  • KeyError – The source has no tracked location.

  • OSError – The exclusive file move failed.

  • TrackedMoveRollbackError – A catalog failure also prevented filesystem rollback.

Notes

Catalog failure rolls the file move back without replacing another file.

adsfolio.pdf.tracked_move.resolved_file_directory(root, source_path, unresolved_directory=None)[source]

Choose the directory for a resolved PDF within one catalog root.

Parameters:

  • root (Path) – Library root owning the file’s catalog location.

  • source_path (Path) – Current PDF path.

  • unresolved_directory (Path, optional) – Configured unresolved directory, relative to root when not absolute. Defaults to <root>/unresolved.

Returns:

The library root for files below its unresolved subtree; otherwise the source parent. An external directory or the root itself is not treated as an unresolved subtree because its owning library is ambiguous.

Return type:

Path