Registry / serialization / phantom-types

phantom-types

library3.0.2pypypi✓ verified 85d ago

phantom-types is a Python library that enables the creation of 'phantom types' to enforce type safety at compile time without incurring runtime overhead. It leverages Python's `__instancecheck__` protocol and boolean predicates to allow developers to define stricter type constraints, helping to make 'illegal states unrepresentable' and mitigate 'shotgun parsing'. The library is currently at version 3.0.2 and follows semantic versioning after its 1.0 release, with new versions released periodically to add features, fix bugs, and maintain compatibility.

serialization testing

pip install phantom-types

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · PHANTOM-TYPES

phantom-types

serializationpythonv3.0.2

Install

4.5s avg

Import

761ms

Disk

71MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.797s · 28MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 4.5s · import 0.725s · 28MB

71MB installed

● package 71MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Phantom

✓ from phantom import Phantom

contained

✓ from phantom.predicates.collection import contained

TZAware

✓ from phantom.datetime import TZAware

✗ from phantom.tz import TZAware

TZAware was moved from phantom.tz to phantom.datetime in newer versions.

This quickstart demonstrates how to define a simple phantom type `Name` that narrows the `str` type to only accept specific values ('Jane' or 'Joe'). It shows both explicit parsing using `Name.parse()` and leveraging Python's `isinstance()` for type narrowing recognized by static type checkers. Invalid inputs are caught at compile time by type checkers, preventing runtime errors.

from phantom import Phantom from phantom.predicates.collection import contained from typing import TYPE_CHECKING # Define a phantom type 'Name' that only accepts 'Jane' or 'Joe' class Name(str, Phantom, predicate=contained({"Jane", "Joe"})): pass def greet(name: Name): print(f"Hello {name}!") # Valid usage: explicitly parsing a value into the phantom type greet(Name.parse("Jane")) # Valid usage: using runtime type checking (e.g., isinstance) to narrow the type joe = "Joe" assert isinstance(joe, Name) # This assertion informs type checkers greet(joe) # This call would typically be caught by a static type checker like MyPy # as 'bird' does not satisfy the predicate for 'Name'. # if TYPE_CHECKING: # greet("bird") # E.g., Uncommenting this line would cause a MyPy error

Debug

Known issues

breakingPrior to version 1.0, breaking changes could occur between minor versions. After 1.0, the library adheres to semantic versioning. Version 2.0.0 specifically dropped support for Python 3.7.

fix

Consult the changelog for specific migration steps if upgrading from <1.0 or if moving to 2.0.0+ from Python 3.7. Ensure your environment uses Python 3.9 or newer.

affects: <1.0, 2.0.0+

gotchaPhantom types are implemented using a metaclass, which can lead to 'metaclass conflicts' when attempting to subclass a phantom type from another type that also uses a custom metaclass.

fix

To resolve, create a new metaclass that inherits from both `PhantomMeta` (the metaclass used by `Phantom`) and the other custom metaclass, then use this new metaclass for your composite phantom type. Example: `class NewMeta(PhantomMeta, OldMeta): pass; class New(Old, Phantom, metaclass=NewMeta): ...`

affects: All

gotchaPhantom types are incompatible with mutable data types. A type checker cannot detect if a mutation to an object changes it to no longer satisfy the phantom type's predicate, leading to silent inconsistencies.

fix

Only apply phantom types to immutable base types (e.g., `str`, `int`, `tuple`, `datetime.datetime`). Avoid using them with mutable types like `list` or custom mutable objects where internal state can change.

affects: All

gotchaIf a phantom type does not properly specify its runtime type bound (e.g., by not inheriting from the base type), static type checkers might 'erase' the runtime type information when performing type guarding, leading to `AttributeError` or other type-related issues.

fix

Always ensure the phantom type explicitly inherits from its runtime base type as the first base class (e.g., `class MyPhantom(MyBaseType, Phantom, ...): ...`).

affects: All

Errors

Common errors & fixes

phantom.errors.MissingDependency: To parse timezone aware/naive datetimes from strings, install 'python-dateutil' (e.g., pip install 'phantom-types[dateutil]').

Attempting to use `TZAware.parse()` or `TZNaive.parse()` without `python-dateutil` installed.

fix

Install the `dateutil` extra: `pip install 'phantom-types[dateutil]'` or `pip install phantom-types[all]`.

mypy: Argument 1 to "greet" has incompatible type "str"; expected "Name" [arg-type]

Passing a plain string literal or a string variable that has not been explicitly narrowed (e.g., via `Name.parse()` or `assert isinstance(my_var, Name)`) to a function expecting a phantom type.

fix

Explicitly convert the value using the phantom type's `parse` method (e.g., `greet(Name.parse(my_string))`) or assert its type at runtime to inform the static type checker (e.g., `assert isinstance(my_string_var, Name); greet(my_string_var)`).

AttributeError: 'UTCDateTime' object has no attribute 'year'

When a phantom type is defined without inheriting from its concrete runtime base type (e.g., `datetime.datetime`), static type checkers might lose the knowledge of the underlying type's attributes after a type guard or parse operation.

fix

Ensure the phantom type inherits directly from its runtime type as the first base class. For instance, `class UTCDateTime(datetime.datetime, Phantom, predicate=is_utc): ...` instead of `class UTCDateTime(Phantom, predicate=is_utc): ...`.

Upgrade

Version history

3.0.2latest on PyPI · released Oct 27, 2024

Audit

Dependencies

python-dateutiloptionalRequired for parsing strings with TZAware and TZNaive types.

phonenumbersoptionalRequired to use phantom.ext.phonenumbers.

pydanticoptionalRequired for Pydantic integration and schema generation.

hypothesisoptionalFor advanced testing utilities.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/antonagestam/phantom-types ↗

packagehttps://pypi.org/project/phantom-types/ ↗

docshttps://phantom-types.readthedocs.io/en/stable/ ↗