Phantom Types for Python

Common errors

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

  cause 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]

  cause 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'

  cause 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): ...`.

Warnings

• breaking Prior 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.
• gotcha Phantom 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): ...`
• gotcha Phantom 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.
• gotcha If 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, ...): ...`).

Install

• pip install phantom-types Base installation
• pip install phantom-types[all] With all optional dependencies

Imports

• Phantom

  from phantom import Phantom

• contained

  from phantom.predicates.collection import contained

• TZAware
  wrong:

  from phantom.tz import TZAware

  correct:

  from phantom.datetime import TZAware

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

Quickstart

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