Skip to content

wend.query

Queries: discovery plans that filter what a pattern finds (SEMANTICS.md ยง11).

A query starts from an expression or a union and adds filters::

src = P("src") / SubPath("rel") / T(t"{stem}.py")
tests = P("src") / SubPath("rel") / T(t"{stem}_test.py")
recent = (src - tests).where(File, modified_after(yesterday))
for m in recent.glob():
    ...
  • q - pattern drops paths that pattern matches;
  • q & pattern keeps paths that pattern also matches, adding its bindings (a parameter both patterns bind must agree);
  • q.where(*predicates) keeps paths for which every predicate holds. A predicate is a condition (File, Readable, Under(base)...), a filesystem test such as modified_after, or any callable taking the Match.

Nothing runs until glob (or match) is called, and results stream as they are found. Filters are a conjunction: wend runs the pattern filters first, then pure callables, then the predicates that touch the filesystem, which is the cheapest order and gives the same results.

FsPredicate 

FsPredicate(description: str, test: Callable[[stat_result], bool])

A test on the filesystem entry at a matched path (an effect).

description instance-attribute 

description = description

test instance-attribute 

test = test

__call__ 

__call__(m: Match) -> bool

Query 

Query(
    source: Any,
    drop: tuple[Any, ...] = (),
    keep: tuple[Any, ...] = (),
    where: tuple[Any, ...] = (),
)

A lazy discovery plan: a source pattern and filters (see the module).

source instance-attribute 

source = _pattern(source)

drop instance-attribute 

drop = drop

keep instance-attribute 

keep = keep

predicates instance-attribute 

predicates = where

__sub__ 

__sub__(other: Any) -> Query

__and__ 

__and__(other: Any) -> Query

where 

where(*predicates: Any) -> Query

glob 

glob(
    mapping: Any = None,
    /,
    *,
    ambiguous: Literal["raise", "skip"]
    | Callable[[AmbiguousMatchError], object] = "raise",
    **kw: Any,
) -> Iterator[Match]

Discover the source's paths and yield those every filter admits, as they are found (see wend.glob for the options). Conditions are checked on the filesystem the walk reads (fs=); a condition that cannot be determined raises IndeterminateError.

ambiguous decides, as for wend.glob, what happens to a path with more than one reading: one the source reads two ways, which the source's glob reports before its first match, or one a & pattern reads two ways, reported when the stream reaches it (as wend.Lens.map reports). Neither is yielded.

match 

match(path: Any, *, fs: Any = None) -> Match | None

The source's reading of path, if every filter admits it. The filesystem predicates look at path now, on fs.

larger_than 

larger_than(size: int) -> FsPredicate

The path's size in bytes is more than size.

modified_after 

modified_after(when: datetime | float) -> FsPredicate

The path was modified after when (a datetime or a POSIX timestamp).

modified_before 

modified_before(when: datetime | float) -> FsPredicate

The path was modified before when.

smaller_than 

smaller_than(size: int) -> FsPredicate

The path's size in bytes is less than size.