PrivatePath – vcspull._internal.private_path

Warning

PrivatePath is an internal helper. Its import path and behavior may change without notice. File an issue if you rely on it downstream so we can discuss a supported API.

PrivatePath subclasses pathlib.Path and normalizes every textual rendering (str()/repr()) so the current user’s home directory is collapsed to ~. The class behaves exactly like the standard path object for filesystem ops; it only alters how the path is displayed. This keeps CLI logs, JSON/NDJSON output, and tests from leaking usernames while preserving full absolute paths for internal logic.

from vcspull._internal.private_path import PrivatePath

home_repo = PrivatePath("~/code/vcspull")
print(home_repo)          # -> ~/code/vcspull
print(repr(home_repo))    # -> "PrivatePath('~/code/vcspull')"

Usage guidelines

  • Wrap any path destined for user-facing output (logs, console tables, JSON payloads) in PrivatePath before calling str().

  • The helper is safe to instantiate with pathlib.Path objects or strings; it does not touch relative paths that lack a home prefix.

  • Prefer storing raw pathlib.Path objects (or strings) in configuration models, then convert to PrivatePath at the presentation layer. This keeps serialization and equality checks deterministic while still masking the home directory when needed.

Why not contract_user_home?

The previous contract_user_home() helper duplicated the tilde-collapsing logic in multiple modules and required callers to remember to run it themselves. By centralizing the behavior in a pathlib.Path subclass we get:

  • Built-in protection—str() and repr() automatically apply the privacy filter.

  • Consistent behavior across every CLI command and test fixture.

  • Easier mocking in tests, because PrivatePath respects monkeypatched Path.home() implementations.

If you need alternative redaction behavior, consider composing your own helper around PrivatePath instead of reintroducing ad hoc string munging.

class vcspull._internal.private_path.PrivatePath(*args, **kwargs)[source]

Bases: PosixPath

Path subclass that hides the user’s home directory in textual output.

The class behaves like pathlib.Path, but normalizes string and representation output to replace the current user’s home directory with ~. This is useful when logging or displaying paths that should not leak potentially sensitive information.

Examples

>>> from pathlib import Path
>>> home = Path.home()
>>> PrivatePath(home)
PrivatePath('~')
>>> PrivatePath(home / "projects" / "vcspull")
PrivatePath('~/projects/vcspull')
>>> str(PrivatePath("/tmp/example"))
'/tmp/example'
>>> f'build dir: {PrivatePath(home / "build")}'
'build dir: ~/build'
>>> '{}'.format(PrivatePath(home / 'notes.txt'))
'~/notes.txt'

Construct a PurePath from one or several strings and or existing PurePath objects. The strings and path objects are combined so as to yield a canonicalized path, which is incorporated into the new PurePath object.

Parameters:

  • args (t.Any)

  • kwargs (t.Any)

Return type:

PrivatePath

classmethod _collapse_home(value)[source]

Collapse the user’s home directory to ~ in value.

Return type:

str

Parameters:

value (str)