vcorelib.paths package

vcorelib.paths package#

Submodules#

vcorelib.paths.base module#

A module implementing common pathing utilities.

vcorelib.paths.base.get_file_ext(path: Path | str | None, maxsplit: int = -1) → str[source]#: From a path to a file, get the file’s extension. Use ‘maxsplit’ to control how many suffixes are considered part of the name or the extension.

vcorelib.paths.base.get_file_name(path: Path | str | None, maxsplit: int = -1) → str[source]#: From a path to a file, get the name of the file. Use ‘maxsplit’ to control how many suffixes are considered part of the name or the extension.

vcorelib.paths.base.normalize(path: Path | str | None, *parts: str | Path, require: bool = False) → Path[source]#: Normalize an input that could be a path into a path.

vcorelib.paths.base.rel(path: Path | str | None, base: Path | str | None = None) → Path[source]#: Attempt to make ‘path’ relative to base (which is the current-working directory, if not provided).

vcorelib.paths.base.set_exec_flags(path: Path | str | None) → None[source]#: Set the executable bits, but respect the ‘read’ bits.

vcorelib.paths.base.stats(path: Path | str | None) → stat_result | None[source]#: Get stats for a file on disk if it exists.

vcorelib.paths.context module#

A module for context managers related to file-system paths.

vcorelib.paths.context.in_dir(path: Path | str | None, *parts: str | Path, makedirs: bool = False) → Iterator[Path][source]#: Change the current working directory as a context manager.

vcorelib.paths.context.linked_to(link: Path | str | None, target: Path | str | None, *parts: str | Path, target_is_directory: bool = False) → Iterator[Path][source]#: Provide a symbolic link as a managed context.

vcorelib.paths.context.tempfile(*args, **kwargs) → Iterator[Path][source]#: Get a valid path to a temporary file and guarantee that its cleaned up afterwards.

vcorelib.paths.find module#

A module implementing interfaces for finding files.

vcorelib.paths.find.find_file(path: Path | str | None, *parts: str | Path, search_paths: Iterable[Path | str | None] = None, include_cwd: bool = False, relative_to: Path | str | None = None, package: str = None, package_subdir: str = 'data', logger: Logger | LoggerAdapter[Any] = None, strict: bool = False) → Path | None[source]#: Combines a few simple strategies to locate a file on disk.

vcorelib.paths.find.find_package_file(parsed: ParseResult, package_subdir: str, logger: Logger | LoggerAdapter[Any] | None) → Path | None[source]#: Find a file from a package.

vcorelib.paths.find.register_file_finder(scheme: str, finder: Callable[[ParseResult, str, Logger | LoggerAdapter[Any] | None], Path | None]) → None[source]#: Register a custom, runtime file finder (for URI paths).

vcorelib.paths.hashing module#

A module for hashing file data.

vcorelib.paths.hashing.bytes_hash_hex(data: bytes, algorithm: str = 'sha256') → str[source]#: Get the hex digest from some bytes for some provided hashing algorithm.

vcorelib.paths.hashing.bytes_md5_hex(data: bytes) → str[source]#: Get the MD5 sum for some bytes.

vcorelib.paths.hashing.create_hex_digest(output: Path | str | None, name: str, sources: Path | str | None = None, algorithm: str = 'sha256') → Path[source]#: Create a hex digest file based on file hashes in some directory.

vcorelib.paths.hashing.file_hash_hex(path: Path | str | None, algorithm: str = 'sha256') → str[source]#: Get the hex digest from file data.

vcorelib.paths.hashing.file_md5_hex(path: Path | str | None) → str[source]#: Get an md5 hex string for a file by path.

vcorelib.paths.hashing.str_hash_hex(data: str, encoding: str = 'utf-8', algorithm: str = 'sha256') → str[source]#: Get the hex digest for string data.

vcorelib.paths.hashing.str_md5_hex(data: str, encoding: str = 'utf-8') → str[source]#: Get an md5 hex string from string data.

vcorelib.paths.hashing.validate_hex_digest(path: Path | str | None, root: Path | str | None = None, strict: bool = False) → None[source]#: Attempt to validate a hex-digest file.

vcorelib.paths.info module#

A module implementing a data structure for tracking information about files in a file-system.

class vcorelib.paths.info.FileChangeEvent(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

An enumeration describing possible file-change events.

CREATED = 1#

REMOVED = 2#

UPDATED = 3#

class vcorelib.paths.info.FileInfo(path: Path, size: int, md5_hex: str, modified_ns: int)[source]#

Bases: NamedTuple

A collection of data to describe an identity of a file.

static from_file(path: Path | str | None, stats: stat_result = None) → FileInfo[source]#: Create file info from a file.

static from_json(data: Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]], force: bool = False) → Dict[Path, FileInfo][source]#: Create file info from JSON data.

md5_hex: str#: Alias for field number 2

modified_ns: int#: Alias for field number 3

path: Path#: Alias for field number 0

poll(check_contents: bool = True) → Tuple[FileChangeEvent | None, FileInfo | None][source]#: Determine if this file is in a new state or not.

same(other: FileInfo) → bool[source]#: Check if two file info contents match.

size: int#: Alias for field number 1

to_json(data: Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]] = None) → Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]][source]#: Get JSON data for this instance.

vcorelib.paths.info_cache module#

A module implementing a file-info cache.

class vcorelib.paths.info_cache.FileChangeEvent(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

An enumeration describing possible file-change events.

CREATED = 1#

REMOVED = 2#

UPDATED = 3#

class vcorelib.paths.info_cache.FileChanged(new: FileInfo | None, old: FileInfo | None, event: FileChangeEvent)[source]#

Bases: NamedTuple

Data provided to a file-changed callback.

event: FileChangeEvent#: Alias for field number 2

new: FileInfo | None#: Alias for field number 0

old: FileInfo | None#: Alias for field number 1

class vcorelib.paths.info_cache.FileInfo(path: Path, size: int, md5_hex: str, modified_ns: int)[source]#

Bases: NamedTuple

A collection of data to describe an identity of a file.

static from_file(path: Path | str | None, stats: stat_result = None) → FileInfo[source]#: Create file info from a file.

static from_json(data: Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]], force: bool = False) → Dict[Path, FileInfo][source]#: Create file info from JSON data.

md5_hex: str#: Alias for field number 2

modified_ns: int#: Alias for field number 3

path: Path#: Alias for field number 0

poll(check_contents: bool = True) → Tuple[FileChangeEvent | None, FileInfo | None][source]#: Determine if this file is in a new state or not.

same(other: FileInfo) → bool[source]#: Check if two file info contents match.

size: int#: Alias for field number 1

to_json(data: Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]] = None) → Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]][source]#: Get JSON data for this instance.

class vcorelib.paths.info_cache.FileInfoManager(poll_cb: Callable[[FileChanged], bool], initial: Dict[Path, FileInfo] = None, logger: Logger | LoggerAdapter[Any] = None, level: int = 10, check_contents: bool = True)[source]#

Bases: object

A class simplifying evaluation of changes to files on disk.

poll_directory(path: Path | str | None, recurse: bool = True, base: Path | str | None = None) → None[source]#: Poll an entire directory for changes. If files previously in this directory were polled and are no longer present, they won’t be polled and thus won’t trigger the callback. Use ‘poll_existing’ for that behavior.

poll_existing(base: Path | str | None = None) → None[source]#: Poll all existing files. This is the only way to detect files that have been deleted.

poll_file(path: Path | str | None, base: Path | str | None = None) → None[source]#: Check if a file has changed and invoke the callback if so.

vcorelib.paths.info_cache.file_info_cache(cache_path: Path | str | None, poll_cb: Callable[[FileChanged], bool], logger: Logger | LoggerAdapter[Any] = None, level: int = 10, check_contents: bool = True) → Iterator[FileInfoManager][source]#: Obtain a file-info manager as a cached context.

Module contents#

Common path manipulation utilities.

vcorelib.paths.bytes_hash_hex(data: bytes, algorithm: str = 'sha256') → str[source]#: Get the hex digest from some bytes for some provided hashing algorithm.

vcorelib.paths.bytes_md5_hex(data: bytes) → str[source]#: Get the MD5 sum for some bytes.

vcorelib.paths.create_hex_digest(output: Path | str | None, name: str, sources: Path | str | None = None, algorithm: str = 'sha256') → Path[source]#: Create a hex digest file based on file hashes in some directory.

vcorelib.paths.file_hash_hex(path: Path | str | None, algorithm: str = 'sha256') → str[source]#: Get the hex digest from file data.

vcorelib.paths.file_md5_hex(path: Path | str | None) → str[source]#: Get an md5 hex string for a file by path.

vcorelib.paths.find_file(path: Path | str | None, *parts: str | Path, search_paths: Iterable[Path | str | None] = None, include_cwd: bool = False, relative_to: Path | str | None = None, package: str = None, package_subdir: str = 'data', logger: Logger | LoggerAdapter[Any] = None, strict: bool = False) → Path | None[source]#: Combines a few simple strategies to locate a file on disk.

vcorelib.paths.get_file_ext(path: Path | str | None, maxsplit: int = -1) → str[source]#: From a path to a file, get the file’s extension. Use ‘maxsplit’ to control how many suffixes are considered part of the name or the extension.

vcorelib.paths.get_file_name(path: Path | str | None, maxsplit: int = -1) → str[source]#: From a path to a file, get the name of the file. Use ‘maxsplit’ to control how many suffixes are considered part of the name or the extension.

vcorelib.paths.modified_after(path: Path | str | None, candidates: Iterable[Path | str | None]) → bool[source]#: Check if any candidate paths are more recently modified than the provided path. If the path doesn’t exists but one or more of the candidates do, this method returns True.

vcorelib.paths.modified_ns(path: Path | str | None) → int | None[source]#: Get the last-modified time from a path if the data can be obtained.

vcorelib.paths.normalize(path: Path | str | None, *parts: str | Path, require: bool = False) → Path[source]#: Normalize an input that could be a path into a path.

vcorelib.paths.rel(path: Path | str | None, base: Path | str | None = None) → Path[source]#: Attempt to make ‘path’ relative to base (which is the current-working directory, if not provided).

vcorelib.paths.resource(path: Path | str | None, *parts: str | Path, search_paths: Iterable[Path | str | None] = None, include_cwd: bool = False, relative_to: Path | str | None = None, package: str = None, package_subdir: str = 'data', logger: Logger | LoggerAdapter[Any] = None, strict: bool = False) → Path | None#: Combines a few simple strategies to locate a file on disk.

vcorelib.paths.set_exec_flags(path: Path | str | None) → None[source]#: Set the executable bits, but respect the ‘read’ bits.

vcorelib.paths.stats(path: Path | str | None) → stat_result | None[source]#: Get stats for a file on disk if it exists.

vcorelib.paths.str_hash_hex(data: str, encoding: str = 'utf-8', algorithm: str = 'sha256') → str[source]#: Get the hex digest for string data.

vcorelib.paths.str_md5_hex(data: str, encoding: str = 'utf-8') → str[source]#: Get an md5 hex string from string data.

vcorelib.paths.validate_hex_digest(path: Path | str | None, root: Path | str | None = None, strict: bool = False) → None[source]#: Attempt to validate a hex-digest file.

vcorelib.paths package

Contents

vcorelib.paths package#

Submodules#

vcorelib.paths.base module#

vcorelib.paths.context module#

vcorelib.paths.find module#

vcorelib.paths.hashing module#

vcorelib.paths.info module#

vcorelib.paths.info_cache module#

Module contents#