dataspecs package#

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

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.

class TagBase(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Base enum of tag for data specs.

Since TagBase itself does not have any members, users should create their own tags by inheriting it:

from enum import auto
from dataspecs import TagBase

class Tag(TagBase):
    ATTR = auto()
    DATA = auto()
    NAME = auto()

from_dataclass(obj: ~dataspecs.core.typing.DataClassObject | type[~dataspecs.core.typing.DataClassObject], /, *, factory: ~typing.Any = <class 'dataspecs.core.specs.Spec'>, id: str | ~os.PathLike[str] = ID('/')) → Any[source]#

Create data specs from a dataclass (object).

Parameters:

obj (DataClassObject | type[DataClassObject]) – Dataclass (object) to be parsed.
factory (Any) – Factory for creating each data spec.
id (str | PathLike[str]) – ID of the parent data spec.

Returns:

Data specs created from the dataclass (object).

Return type:

Any

Examples

from enum import auto
from dataclasses import dataclass
from dataspecs import TagBase, from_dataclass
from typing import Annotated as Ann

class Tag(TagBase):
    ATTR = auto()
    DATA = auto()
    DTYPE = auto()

@dataclass
class Weather:
    temp: Ann[list[Ann[float, Tag.DTYPE]], Tag.DATA]
    humid: Ann[list[Ann[float, Tag.DTYPE]], Tag.DATA]
    location: Ann[str, Tag.ATTR]

from_dataclass(Weather([20.0, 25.0], [50.0, 55.0], "Tokyo"))

Specs([
    Spec(
        id=ID('/temp'),
        tags=(<Tag.DATA: 2>,),
        type=list[float],
        data=[20.0, 25.0],
    ),
    Spec(
        id=ID('/temp/0'),
        tags=(<Tag.DTYPE: 3>,),
        type=<class 'float'>,
        data=None,
    ),
    Spec(
        id=ID('/humid'),
        tags=(<Tag.DATA: 2>,),
        type=list[float],
        data=[50.0, 55.0],
    ),
    Spec(
        id=ID('/humid/0'),
        tags=(<Tag.DTYPE: 3>,),
        type=<class 'float'>,
        data=None,
    ),
    Spec(
        id=ID('/location'),
        tags=(<Tag.ATTR: 1>,),
        type=<class 'str'>,
        data='Tokyo',
    ),
])

from_typehint(obj: ~typing.Any, /, *, factory: ~typing.Any = <class 'dataspecs.core.specs.Spec'>, id: str | ~os.PathLike[str] = ID('/'), data: ~typing.Any = None, metadata: dict[str, ~typing.Any] | None = None, origin: ~typing.Any | None = None) → Any[source]#

Create data specs from a type hint.

Parameters:

obj (Any) – Type hint to be parsed.
factory (Any) – Factory for creating each data spec.
id (str | PathLike[str]) – ID of the parent data spec.
data (Any) – Data of the parent data spec.
metadata (dict[str, Any] | None) – Metadata of the parent data spec.
origin (Any | None)

Returns:

Data specs created from the type hint.

Return type:

Any

Examples

from enum import auto
from dataspecs import TagBase, from_typehint
from typing import Annotated as Ann

class Tag(TagBase):
    DATA = auto()
    DTYPE = auto()

from_typehint(Ann[list[Ann[float, Tag.DTYPE]], Tag.DATA])

Specs([
    Spec(
        id=ID('/'),
        tags=(<Tag.DATA: 1>,),
        type=list[float],
        data=None,
    ),
    Spec(
        id=ID('/0'),
        tags=(<Tag.DTYPE: 2>,),
        type=<class 'float'>,
        data=None,
    ),
])

class Format(_format_id: ~typing.Annotated[str | ~os.PathLike[str], <Tag.ID: 1>], _format_of: ~typing.Annotated[~typing.Literal['id', 'tags', 'type', 'data', 'annotations', 'metadata', 'origin'], <Tag.OF: 2>] = 'data', _format_skipif: ~typing.Annotated[~typing.Any, <Tag.SKIPIF: 3>] = None)[source]#

Bases: object

Annotation for formatter specs.

Parameters:

_format_id (Annotated[str | PathLike[str], <Tag.ID: 1>]) – ID of data spec(s) to be formatted.
_format_of (Annotated[Literal['id', 'tags', 'type', 'data', 'annotations', 'metadata', 'origin'], <Tag.OF: 2>]) – Name of data spec attribute to be formatted.
_format_skipif (Annotated[Any, <Tag.SKIPIF: 3>]) – Sentinel value for which formatting is skipped.

class Replace(_replace_id: ~typing.Annotated[str | ~os.PathLike[str], <Tag.ID: 1>], _replace_of: ~typing.Annotated[~typing.Literal['id', 'tags', 'type', 'data', 'annotations', 'metadata', 'origin'], <Tag.OF: 2>] = 'data', _replace_skipif: ~typing.Annotated[~typing.Any, <Tag.SKIPIF: 3>] = None)[source]#

Bases: object

Annotation for replacer specs.

Parameters:

_replace_id (Annotated[str | PathLike[str], <Tag.ID: 1>]) – ID of data spec(s) to be replaced.
_replace_of (Annotated[Literal['id', 'tags', 'type', 'data', 'annotations', 'metadata', 'origin'], <Tag.OF: 2>]) – Name of data spec attribute to be replaced.
_replace_skipif (Annotated[Any, <Tag.SKIPIF: 3>]) – Sentinel value for which replacing is skipped.

format(specs: Specs[TSpec], /) → Specs[TSpec][source]#

Format data spec attributes by formatter specs.

Parameters:: specs (Specs[TSpec]) – Input data specs.
Returns:: Data specs whose attributes are formatted.
Return type:: Specs[TSpec]

Examples

from enum import auto
from dataclasses import dataclass
from dataspecs import TagBase, Format, from_dataclass, format
from typing import Annotated as Ann

class Tag(TagBase):
    ATTR = auto()

@dataclass
class Attrs:
    name: Ann[str, Tag.ATTR]
    units: Ann[str, Tag.ATTR]

@dataclass
class Weather:
    temp: Ann[list[float], Attrs("Temperature ({0})", "{0}")]
    units: Ann[str, Format("/temp/(name|units)")] = "degC"

format(from_dataclass(Weather([20.0, 25.0], "K")))

Specs([
    Spec(
        id=ID('/temp'),
        tags=(),
        type=list[float],
        data=[20.0, 25.0],
    ),
    Spec(
        id=ID('/temp/0'),
        tags=(),
        type=<class 'float'>,
        data=None,
    ),
    Spec(
        id=ID('/temp/name'),
        tags=(<Tag.ATTR: 1>,),
        type=<class 'str'>,
        data='Temperature (K)', # <- formatted
    ),
    Spec(
        id=ID('/temp/units'),
        tags=(<Tag.ATTR: 1>,),
        type=<class 'str'>, data='K', # <- formatted
    ),
    Spec(
        id=ID('/units'),
        tags=(),
        type=<class 'str'>,
        data='K',
    ),
    Spec(
        id=ID('/units/_format_id'),
        tags=(<Tag.ID: 1>,),
        type=<class 'str'>,
        data='/temp/attrs/(name|units)',
    ),
    Spec(
        id=ID('/units/_format_of'),
        tags=(<Tag.OF: 2>,),
        type=<class 'str'>,
        data='data',
    ),
    Spec(
        id=ID('/units/_format_skipif'),
        tags=(<Tag.SKIPIF: 3>,),
        type=typing.Any,
        data=None,
    ),
])

replace(specs: Specs[TSpec], /) → Specs[TSpec][source]#

Replace data spec attributes by replacer specs.

Parameters:: specs (Specs[TSpec]) – Input data specs.
Returns:: Data specs whose attributes are replaced.
Return type:: Specs[TSpec]

Examples

from enum import auto
from dataclasses import dataclass
from dataspecs import Replace, TagBase, from_dataclass, replace
from typing import Annotated as Ann

class Tag(TagBase):
    ATTR = auto()
    DATA = auto()
    DTYPE = auto()

@dataclass
class Weather:
    temp: Ann[list[Ann[float, Tag.DTYPE]], Tag.DATA]
    humid: Ann[list[Ann[float, Tag.DTYPE]], Tag.DATA]
    dtype: Ann[type, Replace("/[a-z]+/0", "type")] = None

replace(from_dataclass(Weather([20.0, 25.0], [50.0, 55.0], int)))

Specs([
    Spec(
        id=ID('/temp'),
        tags=(<Tag.DATA: 2>,),
        type=list[float],
        data=[20.0, 25.0],
    ),
    Spec(
        id=ID('/temp/0'),
        tags=(<Tag.DTYPE: 3>,),
        type=<class 'int'>, # <- replaced
        data=None,
    ),
    Spec(
        id=ID('/humid'),
        tags=(<Tag.DATA: 2>,),
        type=list[float],
        data=[50.0, 55.0],
    ),
    Spec(
        id=ID('/humid/0'),
        tags=(<Tag.DTYPE: 3>,),
        type=<class 'int'>, # <- replaced
        data=None,
    ),
    Spec(
        id=ID('/dtype'),
        tags=(),
        type=<class 'type'>,
        data=<class 'int'>,
    ),
    Spec(
        id=ID('/dtype/_replace_id'),
        tags=(<Tag.ID: 1>,),
        type=<class 'str'>,
        data='/[a-z]+/0',
    ),
    Spec(
        id=ID('/dtype/_replace_of'),
        tags=(<Tag.OF: 2>,),
        type=<class 'str'>,
        data='type',
    ),
    Spec(
        id=ID('/dtype/_replace_skipif'),
        tags=(<Tag.SKIPIF: 3>,),
        type=typing.Any,
        data=None,
    ),
])

dataspecs package#

Subpackages#

This Page