typespecs package#

class typespecs.Config[source]#

Bases: TypedDict

Configuration for typespecs.

This dictionary defines the configuration settings that can be provided via the __typespecs_config__ attribute of an object to take precedence over the default behavior of typespecs.from_annotated.

conflict: NotRequired[Mapping[str, Literal['override', 'update'] | Callable[[Any, Any], Any]] | Literal['override', 'update'] | Callable[[Any, Any], Any]]#: Resolution strategy for conflicts between metadata. Either a single resolution or a mapping of column names to resolutions is accepted. As built-in resolutions, "override" (new value overrides old value; default behavior) and "update" (new mapping updates old mapping) are supported. A function that takes old and new values and returns resolved value can also be accepted as a custom resolution.

data: NotRequired[str | None]#: Name of the column for the actual data of the annotations. If it is None, the data column will not be created.

default: NotRequired[Mapping[str, Any] | Any]#: Default value for each column. Either a single value or a mapping of column names to values is accepted. If the specified columns are not present in the created specification DataFrame, each column filled with the specified value will be added.

depth: NotRequired[int | None]#: Maximum depth of sub-annotations to search. If it is None, all sub-annotations will be searched.

merge: NotRequired[bool]#: Whether to merge all sub-annotations into a single row. If it is False, each sub-annotation will have its own row.

separator: NotRequired[str]#: Separator for concatenating root and sub-indices.

type: NotRequired[str | None]#: Name of the column for the metadata-stripped annotations. If it is None, the type column will not be created.

class typespecs.ItselfType[source]#

Bases: object

Sentinel object specifying metadata-stripped annotation itself.

class typespecs.Spec(*args: Any, **kwargs: Any)[source]#

Bases: ReadonlyDict[str, Any]

Type specification.

This is a subclass of the read-only dictionary without any runtime modifications. It is intended to distinguish a type specification from other type metadata.

typespecs.from_annotated(obj: ~typing.Any, /, conflict: ~collections.abc.Mapping[str, ~typing.Literal['override', 'update'] | ~collections.abc.Callable[[~typing.Any, ~typing.Any], ~typing.Any]] | ~typing.Literal['override', 'update'] | ~collections.abc.Callable[[~typing.Any, ~typing.Any], ~typing.Any] = 'override', data: str | None = 'data', default: ~collections.abc.Mapping[str, ~typing.Any] | ~typing.Any = <NA>, depth: int | None = None, merge: bool = True, separator: str = '/', type: str | None = 'type') → DataFrame[source]#

Create a specification DataFrame from given object with annotations.

Parameters:

obj – The object to convert.
conflict – Resolution strategy for conflicts between metadata. Either a single resolution or a mapping of column names to resolutions is accepted. As built-in resolutions, "override" (new value overrides old value; default behavior) and "update" (new mapping updates old mapping) are supported. A function that takes old and new values and returns resolved value can also be accepted as a custom resolution.
data – Name of the column for the actual data of the annotations. If it is None, the data column will not be created.
default – Default value for each column. Either a single value or a mapping of column names to values is accepted. If the specified columns are not present in the created specification DataFrame, each column filled with the specified value will be added.
depth – Maximum depth of sub-annotations to search. If it is None, all sub-annotations will be searched.
merge – Whether to merge all sub-annotations into a single row. If it is False, each sub-annotation will have its own row.
separator – Separator for concatenating root and sub-indices.
type – Name of the column for the metadata-stripped annotations. If it is None, the type column will not be created.

Returns:

Created specification DataFrame.

Note

If the given object has a __typespecs_config__ attribute, the configuration settings defined in it will take precedence over the arguments passed to this function.

typespecs.from_annotation(obj: ~typing.Any, /, *, conflict: ~collections.abc.Mapping[str, ~typing.Literal['override', 'update'] | ~collections.abc.Callable[[~typing.Any, ~typing.Any], ~typing.Any]] | ~typing.Literal['override', 'update'] | ~collections.abc.Callable[[~typing.Any, ~typing.Any], ~typing.Any] = 'override', default: ~collections.abc.Mapping[str, ~typing.Any] | ~typing.Any = <NA>, depth: int | None = None, index: str = 'root', merge: bool = True, separator: str = '/', type: str | None = 'type') → DataFrame[source]#

Create a specification DataFrame from given annotation.

Parameters:

obj – The annotation to convert.
conflict – Resolution strategy for conflicts between metadata. Either a single resolution or a mapping of column names to resolutions is accepted. As built-in resolutions, "override" (new value overrides old value; default behavior) and "update" (new mapping updates old mapping) are supported. A function that takes old and new values and returns resolved value can also be accepted as a custom resolution.
default – Default value for each column. Either a single value or a mapping of column names to values is accepted. If the specified columns are not present in the created specification DataFrame, each column filled with the specified value will be added.
depth – Maximum depth of sub-annotations to search. If it is None, all sub-annotations will be searched.
index – Root index of the created specification DataFrame.
merge – Whether to merge all sub-annotations into a single row. If it is False, each sub-annotation will have its own row.
separator – Separator for concatenating root and sub-indices.
type – Name of the column for the metadata-stripped annotations. If it is None, the type column will not be created.

Returns:

Created specification DataFrame.

typespecs.from_annotations(obj: ~collections.abc.Mapping[str, ~typing.Any], /, *, conflict: ~collections.abc.Mapping[str, ~typing.Literal['override', 'update'] | ~collections.abc.Callable[[~typing.Any, ~typing.Any], ~typing.Any]] | ~typing.Literal['override', 'update'] | ~collections.abc.Callable[[~typing.Any, ~typing.Any], ~typing.Any] = 'override', default: ~collections.abc.Mapping[str, ~typing.Any] | ~typing.Any = <NA>, depth: int | None = None, merge: bool = True, separator: str = '/', type: str | None = 'type') → DataFrame[source]#

Create a specification DataFrame from given annotations.

Parameters:

obj – The annotations to convert.
conflict – Resolution strategy for conflicts between metadata. Either a single resolution or a mapping of column names to resolutions is accepted. As built-in resolutions, "override" (new value overrides old value; default behavior) and "update" (new mapping updates old mapping) are supported. A function that takes old and new values and returns resolved value can also be accepted as a custom resolution.
default – Default value for each column. Either a single value or a mapping of column names to values is accepted. If the specified columns are not present in the created specification DataFrame, each column filled with the specified value will be added.
depth – Maximum depth of sub-annotations to search. If it is None, all sub-annotations will be searched.
merge – Whether to merge all sub-annotations into a single row. If it is False, each sub-annotation will have its own row.
separator – Separator for concatenating root and sub-indices.
type – Name of the column for the metadata-stripped annotations. If it is None, the type column will not be created.

Returns:

Created specification DataFrame.

typespecs package#

Submodules#