Parsers

Pipeline

A parser pipeline is a sequence of parser steps that process type annotations to produce Narwhals dtypes.

anyschema.parsers.make_pipeline(steps: IntoParserPipeline = 'auto') -> ParserPipeline

Create a ParserPipeline with the specified steps and associates the pipeline to each step.

Tip

This is the recommended way to create a parser pipeline.

Parameters:

Name	Type	Description	Default
steps	IntoParserPipeline	steps to use in the ParserPipeline. If "auto" then the sequence is automatically populated based on the available dependencies.	'auto'

Returns:

Type	Description
ParserPipeline	A ParserPipeline instance with the configured parsers.

Examples:

>>> from anyschema.parsers import make_pipeline
>>> from anyschema.parsers import PyTypeStep, UnionTypeStep, AnnotatedStep
>>>
>>> pipeline = make_pipeline(steps=[UnionTypeStep(), AnnotatedStep(), PyTypeStep()])
>>> print(pipeline.steps)
(UnionTypeStep, AnnotatedStep, PyTypeStep)

>>> pipeline = make_pipeline(steps="auto")
>>> print(pipeline.steps)
(ForwardRefStep, UnionTypeStep, AnnotatedStep, AnnotatedTypesStep, AttrsTypeStep, PydanticTypeStep, PyTypeStep)

Raises:

Type	Description
TypeError	If the steps are not a sequence of ParserStep instances.

anyschema.parsers.ParserPipeline

A pipeline of parser steps that tries each parser in sequence.

This allows for composable parsing where multiple parsers can be tried until one successfully handles the type.

Parameters:

Name	Type	Description	Default
steps	Sequence[ParserStep]	Sequence of ParserStep's to use in the pipeline (in such order).	required

parse(input_type: Any, metadata: tuple = (), *, strict: bool = True) -> DType | None

Try each parser in sequence until one succeeds.

Parameters:

Name	Type	Description	Default
input_type	Any	The type to parse.	required
metadata	tuple	Optional metadata associated with the type.	()
strict	bool	Whether or not to raise if unable to parse input_type.	True

Returns:

Type	Description
DType | None	A Narwhals DType from the first successful parser, or None if no parser succeeded and strict=False.

Parser Steps

Parser steps are the building blocks of the type parsing pipeline. Each step handles specific type patterns.

For more details on how these work together, see the parser steps section in the Architecture guide.

anyschema.parsers.ParserStep

Bases: ABC

Abstract base class for parser steps that convert type annotations to Narwhals dtypes.

This class provides a framework for parsing different types of type annotations and converting them into appropriate Narwhals data types. Each concrete parser implementation handles specific type patterns or annotation styles.

Attributes:

Name	Type	Description
pipeline	ParserPipeline	Property to access the ParserPipeline, raises UnavailablePipelineError if not set.

Raises:

Type	Description
UnavailablePipelineError	When accessing pipeline before it's been set.
TypeError	When setting pipeline with an object that's not a ParserPipeline instance.

Note

Subclasses must implement the parse method to define their specific parsing logic.

Examples:

>>> from typing import get_origin, get_args
>>> import narwhals as nw
>>> from anyschema.parsers import ParserStep, PyTypeStep, make_pipeline
>>>
>>> class CustomType: ...
>>> class CustomList[T]: ...
>>>
>>> class CustomParserStep(ParserStep):
...     def parse(self, input_type: Any, metadata: tuple = ()) -> DType | None:
...         if input_type is CustomType:
...             return nw.String()
...
...         if get_origin(input_type) is CustomList:
...             inner = get_args(input_type)[0]
...             # Delegate to pipeline for recursion
...             inner_dtype = self.pipeline.parse(inner, metadata=metadata)
...             return nw.List(inner_dtype)
...
...         # Return None if we can't handle it
...         return None
>>>
>>> pipeline = make_pipeline(steps=[CustomParserStep(), PyTypeStep()])
>>> pipeline.parse(CustomType)
String
>>> pipeline.parse(CustomList[int])
List(Int64)
>>> pipeline.parse(CustomList[str])
List(String)

pipeline: ParserPipeline property writable

Property that returns the parser chain instance.

Returns:

Name	Type	Description
ParserPipeline	ParserPipeline	The parser chain object used for parsing operations.

Raises:

Type	Description
UnavailablePipelineError	If the parser chain has not been initialized (i.e., _pipeline is None).

parse(input_type: Any, metadata: tuple = ()) -> DType | None abstractmethod

Parse a type annotation into a Narwhals dtype.

Parameters:

Name	Type	Description	Default
input_type	Any	The type to parse (e.g., int, str, list[int], etc.)	required
metadata	tuple	Optional metadata associated with the type (e.g., constraints)	()

Returns:

Type	Description
DType | None	A Narwhals DType if the parser can handle this type, None otherwise.

---

The following steps are built-in and come dependency-free.

anyschema.parsers.ForwardRefStep

Bases: ParserStep

Parser for ForwardRef types (string annotations and forward references).

This parser handles type annotations that are forward references (ForwardRef), which occur when using string annotations or referencing types before they're defined.

The parser resolves the ForwardRef to the actual type and delegates to the parser chain.

Initialization can be customized by providing a global and local namespace that will be used to evaluate the forward references when resolving the type. The default namespace is built with common types, yet you can override it with your own types.

Parameters:

Name	Type	Description	Default
globalns	dict | None	Global namespace for evaluating forward references. Defaults to a namespace with common types.	None
localns	dict | None	Local namespace for evaluating forward references. Defaults to an empty namespace.	None

parse(input_type: Any, metadata: tuple = ()) -> DType | None

Parse ForwardRef types by resolving them and delegating to the chain.

Parameters:

Name	Type	Description	Default
input_type	Any	The type to parse (may be a ForwardRef).	required
metadata	tuple	Optional metadata associated with the type.	()

Returns:

Type	Description
DType | None	A Narwhals DType if this is a ForwardRef that can be resolved, None otherwise.

anyschema.parsers.UnionTypeStep

Bases: ParserStep

Parser for Union types including Optional.

Handles:

• Union[T, None], T | None, Optional[T]
• Extracts the non-None type and its metadata for further parsing

parse(input_type: Any, metadata: tuple = ()) -> DType | None

Parse Union types, particularly Optional types.

Parameters:

Name	Type	Description	Default
input_type	Any	The type to parse.	required
metadata	tuple	Optional metadata associated with the type (will be preserved and passed through).	()

Returns:

Type	Description
DType | None	A Narwhals DType by extracting the non-None type and delegating to the chain.

anyschema.parsers.AnnotatedStep

Bases: ParserStep

Parser for typing.Annotated types.

Handles:

• Annotated[T, metadata...] - extracts the type and metadata for further parsing

parse(input_type: Any, metadata: tuple = ()) -> DType | None

Parse Annotated types by extracting the base type and metadata.

Parameters:

Name	Type	Description	Default
input_type	Any	The type to parse.	required
metadata	tuple	Optional metadata associated with the type.	()

Returns:

Type	Description
DType | None	A Narwhals DType by extracting the base type and delegating to the chain.

anyschema.parsers.PyTypeStep

Bases: ParserStep

Parser for Python builtin types.

Handles:

• int, float, decimal, str, bytes, bool, date, datetime, timedelta, time, object, Enum, Literal
• generics: list[T], Sequence[T], Iterable[T], tuple[T, ...]
• dict,Mapping[K, V], and typed dictionaries (TypedDict)

parse(input_type: Any, metadata: tuple = ()) -> DType | None

Parse Python type annotations into Narwhals dtypes.

Parameters:

Name	Type	Description	Default
input_type	Any	The type to parse.	required
metadata	tuple	Optional metadata associated with the type.	()

Returns:

Type	Description
DType | None	A Narwhals DType if this parser can handle the type, None otherwise.

---

anyschema.parsers.annotated_types.AnnotatedTypesStep

Bases: ParserStep

Parser for types with annotated_types metadata.

Handles:

• Integer constraints (Gt, Ge, Lt, Le, Interval)
• Type refinement based on metadata

Warning

It requires annotated-types to be installed.

parse(input_type: Any, metadata: tuple = ()) -> DType | None

Parse types with annotated metadata into refined Narwhals dtypes.

Parameters:

Name	Type	Description	Default
input_type	Any	The type to parse.	required
metadata	tuple	Metadata associated with the type (e.g., constraints).	()

Returns:

Type	Description
DType | None	A Narwhals DType if this parser can refine the type based on metadata, None otherwise.

anyschema.parsers.attrs.AttrsTypeStep

Bases: ParserStep

Parser for attrs-specific types.

Handles:

• attrs classes (Struct types)

Warning

It requires attrs to be installed.

parse(input_type: Any, metadata: tuple = ()) -> DType | None

Parse attrs-specific types into Narwhals dtypes.

Parameters:

Name	Type	Description	Default
input_type	Any	The type to parse.	required
metadata	tuple	Optional metadata associated with the type.	()

Returns:

Type	Description
DType | None	A Narwhals DType if this parser can handle the type, None otherwise.

anyschema.parsers.pydantic.PydanticTypeStep

Bases: ParserStep

Parser for Pydantic-specific types.

Handles:

• Pydantic datetime types (AwareDatetime, NaiveDatetime, etc.)
• Pydantic date types (PastDate, FutureDate)
• Pydantic BaseModel (Struct types)

Warning

It requires pydantic to be installed.

parse(input_type: Any, metadata: tuple = ()) -> DType | None

Parse Pydantic-specific types into Narwhals dtypes.

Parameters:

Name	Type	Description	Default
input_type	Any	The type to parse.	required
metadata	tuple	Optional metadata associated with the type.	()

Returns:

Type	Description
DType | None	A Narwhals DType if this parser can handle the type, None otherwise.