pythonbuilder.pbutil.Paths

class documentation

class Paths(Iterable[Path], os.PathLike, pb.StateProvider):

Constructors: Paths.filtered(path, fileOK, dirOK, dirs, itName), Paths.glob(path, pattern), Paths.reFiltered(path, fileI, fileX, dirI, dirX, ...), Paths.rglob(path, pattern), Paths(root, itSupplier, itName)

View In Hierarchy

An iterable on files, much like Path().glob() but keeps the path from which the iteration starts.

NOTE: Objects of this class can be conveniently used as the item of a Target when combined with pythonbuilder.stateFileIteratorContent as the state= parameter.

Many targets have a Path as their item and use state="dir" to obtain its state hash, which includes all contained files. If only a subset of files shall covered, use this class as a target's item. You could use the iterator Path("src/python").rglob("*.py") directly as the item, but then you loose the information where the glob started, i.e. "src/python". This class also provides the directory from which the glob starts, as it will often be needed in the target's cmd.

Hint: to create a 1:1 file copy target look in particular at mappedTo.

Objects of this class implement the Iterator[Path] protocol. The iterator basically replays the iterator provided to the constructor, except that it throws a BuildException, if an iterated path is not a sub-path of the root parameter. Further, this is a restartable iterator, i.e. it is possibly to iterate more than once over the same instance.

When used as a os.PathLike, the root is returned.

Static Method	`filtered`	Creates a `Paths` object with an iterable created by calling `filterPath`.
Static Method	`glob`	Creates a `Paths` object from a root path and an iterator derived straight from the `glob` pattern.
Static Method	`reFiltered`	Creates a `Paths` object with an iterable created by calling `filterPathRe`.
Static Method	`rglob`	Creates a `Paths` object from a root path and an iterator derived straight from the `rglob` pattern.
Method	`__fspath__`	Calls `os.fspath` on `root`.
Method	`__init__`	Creates the `Paths` object with a root and an iterable which must deliver sub-paths of `root`. Iterating over the `Paths` object will replay the iterable, but will fail if a path is not a sub-path of `root`.
Method	`__iter__`	Replays the iterator provided to the constructor, failing if it returns a path which is not a sub-path of `root`.
Method	`__str__`	Readable short form for a `Paths`
Method	`mappedTo`	Maps this object to a different common ancestor. All paths returned when iterating the new object will have the `root` replaced by `otherRoot`.
Method	`provideState`	Provides the state of the files such that a `Paths` object may be used with no `state` provided when used as a `Target`'s item. The function `stateFileIteratorContent` is used to compute the state.
Method	`withFilter`	Returns an instance which maps and filters the relative paths of this object.
Instance Variable	`root`	A common ancestor of the paths returned by iterating this object.
Method	`_filter`	Undocumented
Instance Variable	`_itName`	Undocumented
Instance Variable	`_paths`	Undocumented

@staticmethod

def filtered(path: Path, fileOK: Callable[[Path], bool] = lambda p: True, dirOK: Callable[[Path], bool] = lambda p: True, dirs: bool = False, itName: str = 'filtered') -> Paths: ¶

Creates a Paths object with an iterable created by calling filterPath.

@staticmethod

def glob(path: Path | str, pattern: str) -> Paths: ¶

Creates a Paths object from a root path and an iterator derived straight from the glob pattern.

@staticmethod

def reFiltered(path: Path, fileI: str = '.', *, fileX: str | None = None, dirI: str = '.', dirX: str | None = None, dirs: bool = False) -> Paths: ¶

Creates a Paths object with an iterable created by calling filterPathRe.

@staticmethod

def rglob(path: Path | str, pattern: str) -> Paths: ¶

Creates a Paths object from a root path and an iterator derived straight from the rglob pattern.

def __fspath__(self) -> str: ¶

Calls os.fspath on root.

def __init__(self, root: Path | str, itSupplier: Callable[[Path], Iterable[Path]], itName: str | None = None): ¶

Creates the Paths object with a root and an iterable which must deliver sub-paths of root. Iterating over the Paths object will replay the iterable, but will fail if a path is not a sub-path of root.

Parameters
root:`Path \| str`	a common ancestor of paths of the iterable
itSupplier:`Callable[[Path], Iterable[Path]]`	sub-paths of `root`
itName:`str \| None`	a nice name of the generated iterator to be used by `__str__`

def __iter__(self) -> Iterator[Path]: ¶

Replays the iterator provided to the constructor, failing if it returns a path which is not a sub-path of root.

def __str__(self) -> str: ¶

Readable short form for a Paths

def mappedTo(self, otherRoot: Path) -> Paths: ¶

Maps this object to a different common ancestor. All paths returned when iterating the new object will have the root replaced by otherRoot.

Parameters
otherRoot:`Path`	the new common ancestor of all paths

Returns
`Paths`	a `Paths` object with `otherRoot` as the `root`.

def provideState(self) -> str: ¶

overrides pythonbuilder.pythonbuilder.StateProvider.provideState

Provides the state of the files such that a Paths object may be used with no state provided when used as a Target's item. The function stateFileIteratorContent is used to compute the state.

def withFilter(self, relativePathFilter: Callable[[Path], Path | None], filterName: str | None = None) -> Paths: ¶

Returns an instance which maps and filters the relative paths of this object.

Example:

allSrc = Paths.rglob(Path("src", "app"), "*")
nohtml = allSrc.withFilter(lambda p: None if p.suffix == ".html" else p, "nohtml")

Parameters
relativePathFilter:`Callable[[Path], Path \| None]`	a function to map paths relative to our root to a changed path, the same path or `None`. A returned path must be a relative path, otherwise a `BuildException` is raised. If `None` is returned, the input path is filtered out.
filterName:`str \| None`	for a better `str()` output of the filter

Returns
`Paths`	Undocumented

root: Path = ¶

A common ancestor of the paths returned by iterating this object.

def _filter(self, relativePathFilter: Callable[[Path], Path | None], root: Path) -> Iterable[Path]: ¶

Undocumented

_itName = ¶

Undocumented

_paths = ¶

Undocumented