Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/seandstewart/typical
Typical: Fast, simple, & correct data-validation using Python 3 typing.
https://github.com/seandstewart/typical
annotations data-validation deserialization python-types python3 python3-library python36 python37 python38 serde serdes serialization type-annotations type-hints type-safety typical typing validation
Last synced: about 1 month ago
JSON representation
Typical: Fast, simple, & correct data-validation using Python 3 typing.
- Host: GitHub
- URL: https://github.com/seandstewart/typical
- Owner: seandstewart
- License: mit
- Created: 2019-03-15T01:24:36.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2024-02-28T02:03:46.000Z (10 months ago)
- Last Synced: 2024-05-19T05:01:03.354Z (7 months ago)
- Topics: annotations, data-validation, deserialization, python-types, python3, python3-library, python36, python37, python38, serde, serdes, serialization, type-annotations, type-hints, type-safety, typical, typing, validation
- Language: Python
- Homepage: https://python-typical.org
- Size: 2.51 MB
- Stars: 182
- Watchers: 6
- Forks: 9
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# typical: Python's Typing Toolkit
[](https://pypi.org/project/typical/)
[](https://pypi.org/project/typical/)
[](https://pypi.org/project/typical/)
[](https://github.com/seandstewart/typical)
[](https://github.com/seandstewart/typical/actions)
[](https://codecov.io/gh/seandstewart/typical)
[](https://github.com/ambv/black)
[](https://app.netlify.com/sites/typical-python/deploys)
# :warning: This Project is now Archived :warning:
See [python-typelib](https://github.com/seandstewart/python-typelib) for a
modern successor to this library by the same author.
For an more extensive alternative, see
[mashumaro](https://github.com/Fatal1ty/mashumaro).
## Introduction
Typical is a library devoted to runtime analysis, inference,
validation, and enforcement of Python types,
[PEP 484](https://www.python.org/dev/peps/pep-0484/) Type Hints, and
custom user-defined data-types.
Typical is fully compliant with the following Python Typing PEPs:
- [PEP 484 -- Type Hints](https://www.python.org/dev/peps/pep-0484/)
- [PEP 563 -- Postponed Evaluation of Annotations](https://www.python.org/dev/peps/pep-0563/)
- [PEP 585 -- Type Hinting Generics In Standard Collections](https://www.python.org/dev/peps/pep-0585/)
- [PEP 586 -- Literal Types](https://www.python.org/dev/peps/pep-0586/)
- [PEP 589 -- TypedDict: Type Hints for Dictionaries with a Fixed Set of Keys](https://www.python.org/dev/peps/pep-0589/)
- [PEP 604 -- Allow writing union types as X | Y](https://www.python.org/dev/peps/pep-0604/)
It provides a high-level Protocol API, Functional API, and Object API to suit most any
occasion.
## Getting Started
Installation is as simple as `pip install -U typical`.
## Help
The latest documentation is hosted at
[python-typical.org](https://python-typical.org/).
> Starting with version 2.0, All documentation is hand-crafted
> markdown & versioned documentation can be found at typical's
> [Git Repo](https://github.com/seandstewart/typical/tree/master/docs).
> (Versioned documentation is still in-the-works directly on our
> domain.)
## A Typical Use-Case
The decorator that started it all:
### `typic.al(...)`
```python
import typic
@typic.al
def hard_math(a: int, b: int, *c: int) -> int:
return a + b + sum(c)
hard_math(1, "3")
#> 4
@typic.al(strict=True)
def strict_math(a: int, b: int, *c: int) -> int:
return a + b + sum(c)
strict_math(1, 2, 3, "4")
#> Traceback (most recent call last):
#> ...
#> typic.constraints.error.ConstraintValueError: Given value <'4'> fails constraints: (type=int, nullable=False, coerce=False)
```
Typical has both a high-level *Object API* and high-level
*Functional API*. In general, any method registered to one API is also
available to the other.
### The Protocol API
```python
import dataclasses
from typing import Iterable
import typic
@typic.constrained(ge=1)
class ID(int):
...
@typic.constrained(max_length=280)
class Tweet(str):
...
@dataclasses.dataclass # or typing.TypedDict or typing.NamedTuple or annotated class...
class Tweeter:
id: ID
tweets: Iterable[Tweet]
json = '{"id":1,"tweets":["I don\'t understand Twitter"]}'
protocol = typic.protocol(Tweeter)
t = protocol.transmute(json)
print(t)
#> Tweeter(id=1, tweets=["I don't understand Twitter"])
print(protocol.tojson(t))
#> '{"id":1,"tweets":["I don\'t understand Twitter"]}'
protocol.validate({"id": 0, "tweets": []})
#> Traceback (most recent call last):
#> ...
#> typic.constraints.error.ConstraintValueError: Tweeter.id: value <0> fails constraints: (type=int, nullable=False, coerce=False, ge=1)
```
### The Functional API
```python
import dataclasses
from typing import Iterable
import typic
@typic.constrained(ge=1)
class ID(int):
...
@typic.constrained(max_length=280)
class Tweet(str):
...
@dataclasses.dataclass # or typing.TypedDict or typing.NamedTuple or annotated class...
class Tweeter:
id: ID
tweets: Iterable[Tweet]
json = '{"id":1,"tweets":["I don\'t understand Twitter"]}'
t = typic.transmute(Tweeter, json)
print(t)
#> Tweeter(id=1, tweets=["I don't understand Twitter"])
print(typic.tojson(t))
#> '{"id":1,"tweets":["I don\'t understand Twitter"]}'
typic.validate(Tweeter, {"id": 0, "tweets": []})
#> Traceback (most recent call last):
#> ...
#> typic.constraints.error.ConstraintValueError: Tweeter.id: value <0> fails constraints: (type=int, nullable=False, coerce=False, ge=1)
```
### The Object API
```python
from typing import Iterable
import typic
@typic.constrained(ge=1)
class ID(int):
...
@typic.constrained(max_length=280)
class Tweet(str):
...
@typic.klass
class Tweeter:
id: ID
tweets: Iterable[Tweet]
json = '{"id":1,"tweets":["I don\'t understand Twitter"]}'
t = Tweeter.transmute(json)
print(t)
#> Tweeter(id=1, tweets=["I don't understand Twitter"])
print(t.tojson())
#> '{"id":1,"tweets":["I don\'t understand Twitter"]}'
Tweeter.validate({"id": 0, "tweets": []})
#> Traceback (most recent call last):
#> ...
#> typic.constraints.error.ConstraintValueError: Given value <0> fails constraints: (type=int, nullable=False, coerce=False, ge=1)
```
## Changelog
See our
[Releases](https://github.com/seandstewart/typical/releases).