dataspecs.core.specs module#

ROOT = Path('/')#

Root path.

class Path(*segments: str | PathLike[str])[source]#

Bases: PurePosixPath

Path for data specs.

It is based on PurePosixPath, however, the differences are a path must start with the root (/) and the match method full-matches a regular expression.

Parameters:

*segments (str | PathLike[str]) – Segments to create a path.

Raises:

ValueError – Raised if it does not start with the root.

Return type:

Self

property children: Self#

Return the regular expression that matches the child paths.

property descendants: Self#

Return the regular expression that matches the descendant paths.

property regex: Self#

Return the regular expression that matches the path itself.

match(pattern: str | PathLike[str], /) → bool[source]#

Check if the path full-matches a regular expression.

Parameters:

pattern (str | PathLike[str])

Return type:

bool

class Spec(path: ~dataspecs.core.specs.Path, name: ~typing.Hashable, tags: tuple[~dataspecs.core.typing.TagBase, ...], type: ~typing.Any, data: ~dataspecs.core.typing.TAny, anns: tuple[~typing.Any, ...] = <factory>, meta: dict[str, ~typing.Any] = <factory>, orig: ~typing.Any | None = None)[source]#

Bases: Generic[TAny]

Data specification (data spec).

Parameters:

  • path (Path) – Path of the data spec.

  • name (Hashable) – Name of the data spec.

  • tags (tuple[TagBase, ...]) – Tags of the data spec.

  • type (Any) – Type hint (unannotated) of the data spec.

  • data (TAny) – Default or final data of the data spec.

  • anns (tuple[Any, ...]) – Type hint annotations of the data spec.

  • meta (dict[str, Any]) – Metadata of the data spec.

  • orig (Any | None) – Origin of the data spec.

path: Path#

Path of the data spec.

name: Hashable#

Name of the data spec.

tags: tuple[TagBase, ...]#

Tags of the data spec.

type: Any#

Type hint (unannotated) of the data spec.

data: TAny#

Default or final data of the data spec.

anns: tuple[Any, ...]#

Type hint annotations of the data spec.

meta: dict[str, Any]#

Metadata of the data spec.

orig: Any | None = None#

Origin of the data spec.

__call__(type: Callable[[...], UAny], /) → Spec[UAny][source]#

Dynamically cast the data of the data spec.

Parameters:

type (Callable[[...], UAny])

Return type:

Spec[UAny]

__getitem__(type: Callable[[...], UAny], /) → Spec[UAny][source]#

Statically cast the data of the data spec.

Parameters:

type (Callable[[...], UAny])

Return type:

Spec[UAny]

class Specs(initlist=None)[source]#

Bases: UserList[TSpec]

Data specifications (data specs).

property first: TSpec | None#

Return the first data spec if it exists (None otherwise).

property last: TSpec | None#

Return the last data spec if it exists (None otherwise).

property unique: TSpec | None#

Return the data spec if it is unique (None otherwise).

groupby(attr: Literal['path', 'name', 'tags', 'type', 'data', 'anns', 'meta', 'orig'], /, *, method: Literal['eq', 'equality', 'id', 'identity'] = 'equality') → list[Self][source]#

Group the data specs by their attributes.

Parameters:

  • attr (Literal['path', 'name', 'tags', 'type', 'data', 'anns', 'meta', 'orig']) – Name of the data spec attribute for grouping. Either 'path', 'name', 'tags', 'type', 'data', 'anns', 'meta', or 'orig' is accepted.

  • method (Literal['eq', 'equality', 'id', 'identity']) – Grouping method. Either 'equality' (or 'eq'; hash-based grouping), or 'identity' (or 'id'; id-based grouping) is accepted.

Returns:

List of data specs grouped by the selected data spec attribute.

Return type:

list[Self]

replace(old: TSpec, new: TSpec, /) → Self[source]#

Return data specs with old data spec replaced by new one.

Parameters:

  • old (TSpec)

  • new (TSpec)

Return type:

Self

__call__(index: None | str | PathLike[str] | TagBase | type[Any] | slice | SupportsIndex, /) → Self[source]#

Select data specs by given index.

Unlike __getitem__, it always returns data specs, even when given index selects a single data spec.

Parameters:

index (None | str | PathLike[str] | TagBase | type[Any] | slice | SupportsIndex) – Normal or extended index for the selection of the data specs.

Returns:

Selected data specs by given index.

Return type:

Self

__getitem__(index: None, /) → Self[source]#
__getitem__(index: str | PathLike[str], /) → Self
__getitem__(index: TagBase, /) → Self
__getitem__(index: type[Any], /) → Self
__getitem__(index: slice, /) → Self
__getitem__(index: SupportsIndex, /) → TSpec

Select data specs by given index.

In addition to a normal index (i.e. slice or __index__-implemented object), it also accepts the following extended index for the advanced selection: (1) None to select all data specs (i.e. shallow copy), (2) a string path to select data specs that match it, (3) a tag to select data specs that contain it, (4) a tag type to select data specs that contain its tags, or (5) an any type to select data specs that contain it.

Parameters:

index – Normal or extended index for the selection of the data specs.

Returns:

Selected data spec(s) by given index.