ningen.capture module

Capture parts from strings using a convenient glob-like syntax.

ningen.capture.captures(pattern: str, values: Union[str, Sequence[Optional[str]]], *, must_match: bool = False, name: str = 'path') → List[Capture]

Given a capture pattern, return all the Capture results of applying it to each of the (sorted, unique, non-None) values. If must_match, all the values must match the pattern. Otherwise, only captures of matching values are returned.

By default, the complete matched string is made available in a data member path (as this is typically used to parse disk file paths). You can override this by specifying a different name.

See Capture for the description of the capture pattern.

ningen.capture.globs(pattern: str) → List[Capture]

Given a capture pattern, return all the Capture results of applying it to the results of a glob of the equivalent pattern.

See Capture for the description of the capture pattern.

class ningen.capture.Capture(**kwargs: str)

Bases: object

Capture the results of successfully matching a string (typically, a path name) with a capture pattern.

A capture pattern is similar to a glob pattern. However, all wildcards must be specified inside {...} as follows:

• You need to escape the { character as {{ and the } character as }}.

• {*name} has the same effect as *. The matching substring will be captured using the

  key name. For example, foo.{*suffix} will capture the file suffix.

• If name starts with _ then the matching substring will be discarded instead of being captured. For example, if you don’t want to capture the suffix, write foo.{*_} instead of foo.{*suffix}.

• If name is followed by :, it must be followed by a glob pattern. That is, {*name} is a shorthand for {*name:*}. For example foo.{*suffix:[0-9]} will capture a single decimal digit suffix.

• {**name} is shorthand for {*name:**}. In this case you may not use : to specify a glob pattern. For example, foo/{**dir}/bar will capture all the (possibly empty) paths from foo to nested bar files.

Note

Use /{**name}/ instead of /{*name:**}/ as the shorthand is given special treatment allow for capturing an empty sub-directory (that is, match a single /).

The captured named values are available as members of the object, that is, write capture.foo to access the value of a captured {*foo}.

ningen.capture.capture2glob(capture: str) → str

Translate a capture pattern to the equivalent glob pattern.

ningen.capture.capture2re(capture: str) → Pattern

Convert a capture pattern to the equivalent re.Pattern.