Typing#

Optional dependency exports#

The sqlspec.typing module and its private sqlspec._typing backing module resolve heavy optional-dependency symbols lazily. Importing sqlspec does not import Pydantic, Litestar, PyArrow, pandas, Polars, OpenTelemetry, or Prometheus. Accessing one of their exported symbols imports its dependency on first use and caches the resolved object:

import sqlspec.typing as sqlspec_typing

arrow_table_type = sqlspec_typing.ArrowTable  # Imports PyArrow here.

When an optional dependency is not installed, the same access returns a stable typed shim. Repeated access returns the identical real object or shim, preserving annotation and runtime identity behavior. Features that require the dependency still raise the normal missing-dependency error when enabled.

msgspec remains eager because its core types and conversion functions are used throughout result mapping and serialization. orjson also remains on the existing eager path; both have a small measured import cost compared with the deferred integrations.

Metadata Types#

Schema metadata types (such as TableMetadata, ColumnMetadata, ForeignKeyMetadata, and IndexMetadata) are defined in Data Dictionary.

Protocols#

SQLSpec defines focused protocols for reading dictionary-like rows, inspecting dataclasses, and interfacing with Apache Arrow record batch readers and schemas.

class sqlspec.typing.DictLike[source]#

Bases: Protocol

A protocol for objects that behave like a dictionary for reading.

__init__(*args, **kwargs)#

class sqlspec.typing.DataclassProtocol[source]#

Bases: Protocol

Protocol for instance checking dataclasses.

__init__(*args, **kwargs)#

class sqlspec.typing.ArrowRecordBatchReaderProtocol[source]#

Bases: Protocol

Typed shim for pyarrow.RecordBatchReader.

read_all()[source]#

Read all batches into a table.

Return type:

Any

read_next_batch()[source]#

Read next batch.

Return type:

Any

__iter__()[source]#

Iterate over batches.

Return type:

Iterable[typing.Any]

__init__(*args, **kwargs)#

class sqlspec.typing.ArrowSchemaProtocol[source]#

Bases: Protocol

Typed shim for pyarrow.Schema.

field(i)[source]#

Get field by index.

Return type:

Any

property names: list[str]#

Get list of field names.

__len__()[source]#

Get number of fields.

Return type:

int

__init__(*args, **kwargs)#

Type Variables#

sqlspec.typing.ConnectionT = ~ConnectionT#

Type variable for connection types.

ConnectionT

sqlspec.typing.PoolT = ~PoolT#

Type variable for pool types.

PoolT

sqlspec.typing.SchemaT = ~SchemaT#

Type variable for schema types (models, TypedDict, dataclasses, etc.).

Unbounded TypeVar for use with schema_type parameter in driver methods. Supports all schema types including TypedDict which cannot be bounded to a class hierarchy.

Type Aliases#

sqlspec.typing.SupportedSchemaModel: TypeAlias = sqlspec.typing.DictLike | sqlspec._typing.StructStub | sqlspec._typing.BaseModelStub | sqlspec._typing.DataclassProtocol | sqlspec._typing.AttrsInstanceStub | collections.abc.Mapping[str, typing.Any]#

Type alias for pydantic or msgspec models.

msgspec.Struct | pydantic.BaseModel | DataclassProtocol | AttrsInstance

sqlspec.typing.StatementParameters: TypeAlias = 'dict[str, object] | list[object] | tuple[object, ...] | object | None'#

Type alias for statement parameters.

Represents:

• dict[str, object]

• list[object]

• tuple[object, ...]

• object

• None

sqlspec.typing.ArrowReturnFormat#

Type alias for Apache Arrow return format options.

Represents:

• "table" - Return PyArrow Table

• "reader" - Return PyArrow RecordBatchReader

• "batch" - Return single PyArrow RecordBatch

• "batches" - Return list of PyArrow RecordBatches

alias of Literal['table', 'reader', 'batch', 'batches']

Sentinels#

sqlspec.typing.Empty = EmptyEnum.EMPTY#

A sentinel enum used as placeholder.

sqlspec.typing.UNSET = UNSET#

A singleton indicating a field value is unset.

This may be useful for working with message schemas where an unset field in an object needs to be treated differently than one containing an explicit None value. In this case, you may use UNSET as the default value, rather than None when defining object schemas. This feature is supported for any msgspec.Struct, dataclasses or attrs types.

Examples

>>> from msgspec import Struct, UnsetType, UNSET, json
>>> class Example(Struct):
...     x: int
...     y: int | None | UnsetType = UNSET

During encoding, any field containing UNSET is omitted from the message.

>>> json.encode(Example(1))
b'{"x":1}'
>>> json.encode(Example(1, 2))
b'{"x":1,"y":2}'

During decoding, if a field isn't explicitly set in the message, the default value of UNSET will be set instead. This lets downstream consumers determine whether a field was left unset, or explicitly set to None

>>> json.decode(b'{"x": 1}', type=Example)  # unset
Example(x=1, y=UNSET)
>>> json.decode(b'{"x": 1, "y": null}', type=Example)  # explicit null
Example(x=1, y=None)
>>> json.decode(b'{"x": 1, "y": 2}', type=Example)  # explicit value
Example(x=1, y=2)

Helper Functions#

sqlspec.typing.get_type_adapter(f)[source]#

Caches and returns a pydantic type adapter.

Parameters:

f¶ (type[TypeVar(T)]) -- Type to create a type adapter for.

Return type:

Any

Returns:

:class:`pydantic.TypeAdapter`[:class:`typing.TypeVar`[T]]