phantom-types
Phantom types for Python will help you make illegal states unrepresentable and avoid shotgun parsing by enabling you to practice "Parse, don't validate".
This project is in early development and fundamental changes should be expected. Semantic versioning will be followed after version 1.0, but before that breaking changes might occur between minor versions.
Checkout the complete documentation on Read the Docs →
Installation
$ python3 -m pip install phantom-types
Examples
By introducing a phantom type we can define a pre-condition for a function argument.
from phantom import Phantom
from phantom.predicates.collection import contained
class Name(str, Phantom, predicate=contained({"Jane", "Joe"})):
...
def greet(name: Name):
print(f"Hello {name}!")
Now this will be a valid call.
greet(Name.parse("Jane"))
... and so will this.
joe = "Joe"
assert isinstance(joe, Name)
greet(joe)
But this will yield a static type checking error.
greet("bird")
Runtime type checking
By combining phantom types with a runtime type-checker like beartype or typeguard, we can achieve the same level of security as you'd gain from using contracts.
import datetime
from beartype import beartype
from phantom.datetime import TZAware
@beartype
def soon(dt: TZAware) -> TZAware:
return dt + datetime.timedelta(seconds=10)
The soon function will now validate that both its argument and return value is timezone aware, e.g. pre- and post conditions.
Pydantic support
Phantom types are ready to use with pydantic and have integrated support out-of-the-box. Subclasses of Phantom work with both pydantic's validation and its schema generation.
class Name(str, Phantom, predicate=contained({"Jane", "Joe"})):
@classmethod
def __schema__(cls) -> Schema:
return super().__schema__() | {
"description": "Either Jane or Joe",
"format": "custom-name",
}
class Person(BaseModel):
name: Name
created: TZAware
print(json.dumps(Person.schema(), indent=2))
The code above outputs the following JSONSchema.
{
"title": "Person",
"type": "object",
"properties": {
"name": {
"title": "Name",
"description": "Either Jane or Joe",
"format": "custom-name",
"type": "string"
},
"created": {
"title": "TZAware",
"description": "A date-time with timezone data.",
"type": "string",
"format": "date-time"
}
},
"required": ["name", "created"]
}
Development
Install development requirements, preferably in a virtualenv:
$ python3 -m pip install .[test,pydantic,phonenumbers]
Run tests:
$ pytest
# or
$ make test
Linting and static type checking is setup with pre-commit, after installing it you can setup hooks with the following command, so that checks run before you push changes.
# configure hooks to run when pushing
$ pre-commit install -t pre-push
# or when committing
$ pre-commit install -t pre-commit
# run all checks
$ pre-commit run --all-files
# or just a single hook
$ pre-commit run mypy --all-files
In addition to static type checking, the project is setup with pytest-mypy-plugins to test that exposed mypy types work as expected, these checks will run together with the rest of the test suite, but you can single them out with the following command.
$ make test-typing
![`NonEmpty[str]` type cannot be used as sorting key](https://avatars.githubusercontent.com/u/3703560?v=4)
663 Jan 08, 2023
1.2k Dec 30, 2022
398 Dec 23, 2022
12 Jul 14, 2020
589 Dec 26, 2022
238 Dec 27, 2022
2.1k Jan 01, 2023
98 Jan 08, 2023
2 Dec 29, 2021
520 Dec 26, 2022
2 Dec 05, 2022
3.4k Dec 29, 2022
463 Dec 31, 2022
57 Jan 02, 2023
45 Dec 13, 2022
36 Oct 29, 2022
194 Dec 19, 2022
13 Nov 03, 2022