https://github.com/astropenguin/typespecs
Data specifications by type hints
https://github.com/astropenguin/typespecs
annotation dataclass dataframe namedtuple python specification typeddict typing
Last synced: about 2 months ago
JSON representation
Data specifications by type hints
- Host: GitHub
- URL: https://github.com/astropenguin/typespecs
- Owner: astropenguin
- License: mit
- Created: 2025-10-11T07:29:06.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-04-11T09:09:23.000Z (2 months ago)
- Last Synced: 2026-04-11T10:28:12.247Z (2 months ago)
- Topics: annotation, dataclass, dataframe, namedtuple, python, specification, typeddict, typing
- Language: Python
- Homepage: https://astropenguin.github.io/typespecs/
- Size: 4.09 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Citation: CITATION.cff
Awesome Lists containing this project
README
# Typespecs
[](https://pypi.org/project/typespecs/)
[](https://pypi.org/project/typespecs/)
[](https://pepy.tech/project/typespecs)
[](https://doi.org/10.5281/zenodo.17681195)
[](https://github.com/astropenguin/typespecs/actions)
Data specifications by type hints
## Overview
Typespecs is a lightweight Python library that leverages `typing.Annotated` to embed, extract, and manage metadata (such as units, categories, and descriptions) directly within your data structures.
It keeps your code clean by binding specifications directly to your type hints.
The extracted specifications are returned as a transparent subclass of `pandas.DataFrame`, making it instantly compatible with the rich PyData ecosystem.
## Installation
```bash
pip install typespecs
```
## Basic Usage
You can attach metadata to your class fields using `Annotated` and the `typespecs.Spec` object.
The `Spec` object acts as a read-only dictionary, ensuring your metadata remains immutable and safe from runtime modifications.
Once your data structure is defined, use `typespecs.from_annotated` to parse the instance and extract both the actual data and its associated metadata into a `DataFrame` object.
```python
import typespecs as ts
from dataclasses import dataclass
from typing import Annotated as Ann, TypeVar
@dataclass
class Weather:
temp: Ann[list[float], ts.Spec(category="data", name="Temperature", units="K")]
wind: Ann[list[float], ts.Spec(category="data", name="Wind speed", units="m/s")]
loc: Ann[str, ts.Spec(category="info", name="Observed location")]
weather = Weather([273.15, 280.15], [5.0, 10.0], "Tokyo")
specs = ts.from_annotated(weather)
print(specs)
```
```
category data name type units
temp data [273.15, 280.15] Temperature list[float] K
wind data [5.0, 10.0] Wind speed list[float] m/s
loc info Tokyo Observed location
```
## Advanced Usage
### Handling Sub-annotations
Typespecs simplifies working with nested types.
You can easily create reusable type aliases with built-in specifications.
Furthermore, by using the special `typespecs.ITSELF` object, the library dynamically captures the subtype (e.g., `float` in `list[float]`) as one of metadata.
```python
T = TypeVar("T")
Dtype = Ann[T, ts.Spec(dtype=ts.ITSELF)]
@dataclass
class Weather:
temp: Ann[list[Dtype[float]], ts.Spec(category="data", name="Temperature", units="K")]
wind: Ann[list[Dtype[float]], ts.Spec(category="data", name="Wind speed", units="m/s")]
loc: Ann[str, ts.Spec(category="info", name="Observed location")]
weather = Weather([273.15, 280.15], [5.0, 10.0], "Tokyo")
specs = ts.from_annotated(weather)
print(specs)
```
```
category data dtype name type units
temp data [273.15, 280.15] Temperature list[float] K
wind data [5.0, 10.0] Wind speed list[float] m/s
loc info Tokyo Observed location
```
### Handling Missing Values
By default, missing metadata values are filled with `pandas.NA`.
You can override this behavior and specify a custom fallback value by using the `default` parameter in `from_annotated`.
```python
specs = ts.from_annotated(weather, default=None)
print(specs)
```
```
category data dtype name type units
temp data [273.15, 280.15] Temperature list[float] K
wind data [5.0, 10.0] Wind speed list[float] m/s
loc info Tokyo None Observed location None
```
### Handling Full Specification
By default, typespecs neatly merges nested metadata (e.g., `float` in `list[float]`) into a single parent row.
If you need to inspect the exact structural hierarchy of your annotations, set `merge=False` in `from_annotated`.
This unpacks the tree, distinguishing between the parent collection and its elements.
```python
specs = ts.from_annotated(weather, merge=False)
print(specs)
```
```
category data dtype name type units
temp data [273.15, 280.15] Temperature list[float] K
temp/0
wind data [5.0, 10.0] Wind speed list[float] m/s
wind/0
loc info Tokyo Observed location
```