protonfs.usage.paths module

Drive path helpers and du target resolution.

Drive paths are /-separated; a literal / inside a node name is written \/ and a literal backslash \\. resolve_target() maps a du argument (a Drive path or a local path inside a protonfs store) to a Drive path.

Added in version 3.4.0.

protonfs.usage.paths.DU_SECTIONS = frozenset({'devices', 'my-files'})

Sections du can analyse.

protonfs.usage.paths.SECTIONS = frozenset({'albums', 'devices', 'my-files', 'photos', 'photos-shared-by-me', 'photos-shared-with-me', 'photos-trash', 'shared-by-me', 'shared-with-me', 'trash'})

Top-level Drive sections the CLI knows.

class protonfs.usage.paths.Target(remote, store_root)[source]

Bases: object

A resolved du target.

Variables:
  • remote – Normalised Drive path.

  • store_root – The local store root it was derived from, or None for a Drive path given directly.

Added in version 3.4.0.

remote: str
store_root: Path | None
exception protonfs.usage.paths.TargetError[source]

Bases: ValueError

A du target could not be resolved to a supported Drive path.

Added in version 3.4.0.

protonfs.usage.paths.child_path(parent, name, uid, decrypted)[source]

Return the escaped Drive path of a listed child of parent.

Same as join(parent, node_segment(name, uid, decrypted)).

Parameters:
  • parent (str) – escaped Drive path of the folder that listed the child.

  • name (str) – the child’s listed name (plain).

  • uid (str | None) – the child’s uid, if known.

  • decrypted (bool) – whether name is the decrypted name.

Return type:

str

Returns:

the child’s escaped Drive path.

Added in version 3.4.0.

protonfs.usage.paths.escape_name(name)[source]

Return name escaped for use as one Drive path segment. :rtype: str

Added in version 3.4.0.

protonfs.usage.paths.expand_pattern(pattern, children)[source]

Return the Drive paths matching a Drive path whose segments may hold glob patterns.

The segments before the first pattern are taken as they are; from there, each level is matched against a listing of the folders matched so far, so only the pattern’s literal parent (and, for a pattern in an earlier segment, the folders it matches) is listed. A pattern segment never crosses /, as in a shell. Within one listing, a name equal to the segment wins over glob matches, so a folder called run[7] is not taken for a pattern; segments before the last match folders only.

Parameters:
  • pattern (str) – Drive path, e.g. /my-files/sim/mload005*.

  • children (Callable[[str], Sequence[Any]]) – returns the entries of a folder (objects with name, kind, uid and decrypted, like RawEntry), given its escaped Drive path.

Return type:

list[str]

Returns:

the matching escaped Drive paths, sorted; empty when nothing matches. A pattern with no glob character returns itself, normalised, without a listing.

Added in version 3.4.0.

protonfs.usage.paths.has_glob(text)[source]

Return whether text holds a glob metacharacter (*, ? or [). :rtype: bool

Added in version 3.4.0.

protonfs.usage.paths.is_remote(arg)[source]

Return whether arg is a Drive path, i.e. starts with / and, if not / itself, its first segment is a known Drive section. :rtype: bool

Added in version 3.4.0.

protonfs.usage.paths.is_within(path, base)[source]

Return whether path equals base or lies below it (whole segments only). :rtype: bool

Added in version 3.4.0.

protonfs.usage.paths.join(parent, segment)[source]

Return the Drive path of the child segment (an unescaped name) under parent. :rtype: str

Added in version 3.4.0.

protonfs.usage.paths.node_segment(name, uid, decrypted)[source]

Return the plain (unescaped) path segment that addresses a listed node.

That is name, or the node uid when the name could not be decrypted (name itself if the uid is unknown).

Parameters:
  • name (str) – the listed name.

  • uid (str | None) – the node uid, if known.

  • decrypted (bool) – whether name is the decrypted name.

Return type:

str

Returns:

the segment, ready for join().

Added in version 3.4.0.

protonfs.usage.paths.parent_of(path)[source]

Return the Drive path of the parent of path, or None for /. :rtype: str | None

Added in version 3.4.0.

protonfs.usage.paths.relative(path, base)[source]

Return path relative to base with unescaped segments joined by /.

Parameters:
  • path (str) – A Drive path at or below base.

  • base (str) – A Drive path.

Return type:

str

Returns:

"" when path == base.

Raises:

ValueError – If path is not within base.

Added in version 3.4.0.

protonfs.usage.paths.resolve_target(arg, cwd)[source]

Resolve a du argument to a Target.

Parameters:
  • arg (str | None) – A Drive path, a local path (absolute or relative to cwd), or None for cwd itself.

  • cwd (Path) – The working directory.

Return type:

Target

Returns:

The target; store_root is set only for local arguments. The local path need not exist.

Raises:

TargetError – If a Drive path is outside /, /my-files and /devices, or a local path is not inside a protonfs store.

Added in version 3.4.0.

protonfs.usage.paths.split(path)[source]

Return the unescaped, non-empty segments of a Drive path ([] for /). :rtype: list[str]

Added in version 3.4.0.