phantom-types
Phantom types for Python
Decision gist · record as of 2026-08-14
Yes, if you want to move validation earlier in your pipeline and leverage static type checking to prevent invalid states. The package is stable (Production/Stable classifier), has low install friction, and works well with pydantic and runtime type checkers. The 656-day gap since last release is a minor concern for long-term maintenance, but the repository remains active and there are no known vulnerabilities. Install it if your codebase values type safety and parse-don't-validate patterns.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.9 or later; optional extras (pydantic, hypothesis, dateutil, phonenumbers) require those packages to be installed separately.
- Low install friction; pure Python wheel with three runtime dependencies (typeguard, typing-extensions, numerary).
- Repository shows aging maintenance—last release was 656 days ago—but the project remains active with recent commits and no archived status.
License · maintenance · safety
BSD-3-Clause (permissive) — BSD-3-Clause (permissive) allows commercial use, modification, and distribution with minimal restrictions, making it suitable for most projects.
last release 2024-10-27 (656 days) · last repo commit 2026-01-01 · 234 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 79,453 downloads/mo, #14,356 on PyPI
Alternatives
Verify before relying
pip install phantom-types
from phantom import Phantom
from phantom.predicates.collection import contained
class Name(str, Phantom, predicate=contained({"Jane", "Joe"})): ...
name = Name.parse("Jane")
print(f"Valid: {name}")- Whether runtime validation overhead is acceptable for performance-critical code paths.
- How well phantom types integrate with type checkers other than mypy (e.g., pyright, pyre).
- Whether the 656-day gap since last release indicates active maintenance or dormancy.
What it is and what it does
Phantom types let you attach runtime predicates to Python types so that illegal states become unrepresentable at both the type-checking and runtime levels. Instead of validating data after parsing (shotgun parsing), you create a phantom type—a subclass of a base type like `str` with a predicate—and parse data into that type upfront. The type checker then treats the result as proven to satisfy the predicate, and runtime validators like typeguard or beartype can enforce the same constraint at call boundaries.
The package integrates with pydantic for schema generation and validation, works with static type checkers like mypy, and supports optional extras for datetime, phone number, and hypothesis-based testing. It requires Python 3.9+ and depends on typeguard, typing-extensions, and numerary at runtime.
Use it for
- Enforce string constraints (e.g., non-empty, from a fixed set) at the type level so functions can assume preconditions without defensive checks.
- Combine with pydantic models to validate and document API request/response schemas with phantom type predicates.
- Use with beartype or typeguard to add runtime pre- and post-condition checking to functions without explicit guard clauses.
- Parse and validate user input once at the boundary, then pass phantom-typed values through your codebase with static proof of validity.
- Generate JSONSchema from pydantic models that include phantom types, automatically documenting constraints in API specs.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes, if you want to move validation earlier in your pipeline and leverage static type checking to prevent invalid states.
The package is stable (Production/Stable classifier), has low install friction, and works well with pydantic and runtime type checkers. The 656-day gap since last release is a minor concern for long-term maintenance, but the repository remains active and there are no known vulnerabilities. Install it if your codebase values type safety and parse-don't-validate patterns.
Install
phantom-types on PyPI
Before you install
Low install friction; pure Python wheel with three runtime dependencies (typeguard, typing-extensions, numerary). Repository shows aging maintenance—last release was 656 days ago—but the project remains active with recent commits and no archived status.
Requires Python 3.9 or later; optional extras (pydantic, hypothesis, dateutil, phonenumbers) require those packages to be installed separately.
License in practice
BSD-3-Clause (permissive) allows commercial use, modification, and distribution with minimal restrictions, making it suitable for most projects.
Quickstart
pip install phantom-types
from phantom import Phantom
from phantom.predicates.collection import contained
class Name(str, Phantom, predicate=contained({"Jane", "Joe"})): ...
name = Name.parse("Jane")
print(f"Valid: {name}")Verify before relying
- Whether runtime validation overhead is acceptable for performance-critical code paths.
- How well phantom types integrate with type checkers other than mypy (e.g., pyright, pyre).
- Whether the 656-day gap since last release indicates active maintenance or dormancy.
Package facts
| License | BSD-3-Clause permissive |
| Python support | Supports the current Python release >=3.9 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 3 packagestypeguardtyping-extensionsnumerary |
| Maintenance | Aging 656 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 79,453 / month, #14,356 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableIntended Audience :: DevelopersOperating System :: OS IndependentProgramming Language :: PythonProgramming Language :: Python :: 3Programming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.9 |
Evidence: phantom_types-3.0.2-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “phantom types python”
- phantom-typesPhantom types enable you to create type-safe wrappers around base…
- runtypeRuntype provides runtime type validation, dataclass enhancement with…
- skylosSkylos is a local-first static analysis CLI that scans Python,…
Give your agent the search over MCP, or paste the wish link into any chat.
More Quality Assurance packages
Coverage.py measures which lines of Python code are executed during test runs, reporting coverage percentages and identifying untested code paths.
Install it if you want to measure test completeness or enforce coverage thresholds in your project.
Ruff is a Python linter and code formatter written in Rust that combines linting, formatting, and code fixing into a single tool, replacing Flake8, Black, isort, and related utilities.
Pexpect spawns and controls interactive console applications by sending input and matching output patterns, automating tasks that would otherwise require manual interaction.
Black reformats Python source code to a consistent style by parsing entire files and rewriting them according to an opinionated, deterministic set of rules, eliminating manual formatting decisions.
pytest-xdist distributes pytest tests across multiple CPU cores or machines to speed up test execution, with the simplest usage being `pytest -n auto` to spawn workers equal to available CPUs.
Install it if your test suite takes long enough that parallelization would save meaningful time.
Validates AWS CloudFormation templates in YAML or JSON format against resource provider schemas and best practices, checking property values and configuration correctness.
Install it if you work with CloudFormation templates.
See also annotated-types · typepy · beartype · datetype · typeguard · runtype · types-jsonschema · type-enforced · DateTime · protoc-gen-validate