dataspecs.core.specs module#

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

Bases: PurePosixPath

Identifier (ID) for data specs.

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

Parameters:

*segments (str | PathLike[str]) – Path segments to create an ID.

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 IDs.

property descendants: Self#

Return the regular expression that matches the descendant IDs.

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

Check if the ID full-matches a regular expression.

Parameters:

pattern (str | PathLike[str])

Return type:

bool

ROOT = ID('/')#

Root ID.

class Spec(id: ~dataspecs.core.specs.ID, tags: tuple[~dataspecs.core.typing.TagBase, ...], type: ~typing.Any, data: ~dataspecs.core.typing.TAny, annotations: tuple[~typing.Any, ...] = <factory>, metadata: dict[str, ~typing.Any] = <factory>, origin: ~typing.Any | None = None)[source]#

Bases: Generic[TAny]

Data specification (data spec).

Parameters:

  • id (ID) – ID of the data spec.

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

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

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

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

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

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

id: ID#

ID of the data spec.

tags: tuple[TagBase, ...]#

Tags of the data spec.

type: Any#

Type hint for the data of the data spec.

data: TAny#

Default or final data of the data spec.

annotations: tuple[Any, ...]#

Type hint annotations of the data spec.

metadata: dict[str, Any]#

Metadata of the data spec.

origin: 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(by: Literal['id', 'tags', 'type', 'data', 'annotations', 'metadata', 'origin'], /, *, method: Literal['eq', 'equality', 'id', 'identity'] = 'equality') → list[Self][source]#

Group the data specs by their attributes.

Parameters:

  • by (Literal['id', 'tags', 'type', 'data', 'annotations', 'metadata', 'origin']) – Name of the data spec attribute for grouping. Either 'id', 'tags', 'type', 'data', 'annotations', 'metadata', or 'origin' 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

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

Select data specs with given index.

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

Parameters:

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

Returns:

Selected data specs with given index.