API Reference

Field annotations

pydantic_views.ReadAndWrite: TypeAlias

Read and write field annotation. Field could be read and written always.

alias of Annotated[T, READ_AND_WRITE]

pydantic_views.ReadOnly: TypeAlias

Read only field annotation. Field could be read always but never written.

alias of Annotated[T, READ_ONLY]

pydantic_views.WriteOnly: TypeAlias

Write only field annotation. Field could be written always but never read.

alias of Annotated[T, WRITE_ONLY]

pydantic_views.ReadOnlyOnCreation: TypeAlias

Read only on creation field annotation. Field could be read only after creation, and never again.

alias of Annotated[T, READ_ONLY_ON_CREATION]

pydantic_views.WriteOnlyOnCreation: TypeAlias

Write only on creation field annotation. Field could be written only after creation, and never again.

alias of Annotated[T, WRITE_ONLY_ON_CREATION]

pydantic_views.Hidden: TypeAlias

Hidden field annotation. Field could not be read or written.

alias of Annotated[T, HIDDEN]

Classes

Public package surface for pydantic-views.

This module re-exports the main classes, builders, and annotations so users can import from pydantic_views directly.

class pydantic_views.AccessMode(*values)

Bases: Enum

Access rules that determine if and when a field is exposed in generated views.

READ_AND_WRITE = 1

Read and write mark.

READ_ONLY = 2

Read only mark.

WRITE_ONLY = 3

Write only mark.

READ_ONLY_ON_CREATION = 4

Read only on creation mark.

WRITE_ONLY_ON_CREATION = 5

Write only on creation mark.

HIDDEN = 6

Hidden mark.

class pydantic_views.Builder(
view_name: str,
access_modes: tuple[AccessMode, ...],
all_optional: bool = False,
all_nullable: bool = False,
hide_default_null: bool = False,
include_computed_fields: bool = False,
)

Bases: object

Factory for generating view classes from Pydantic models based on access rules.

Parameters:

  • view_name – Name suffix for the generated view class.

  • access_modes – Access modes that the builder will include in generated views.

  • all_optional – Make all fields optional (useful for update scenarios).

  • all_nullable – Make all fields nullable when allowed.

  • hide_default_null – Replace default None with PydanticUndefined to hide null in schemas.

  • include_computed_fields – Whether computed fields should be included in generated views.

build_view(
model: type[T],
) → type[View[TypeVar] | T]

Build or return a cached view for the given model.

Parameters:

model – Model class to derive the view from.

Returns:

View class associated to model for this builder.

get_view_ref(
model: type[T],
) → type[View[TypeVar] | T] | ForwardRef

Return the view class or a forward reference for the model.

Parameters:

model – Model class to derive the view from.

Returns:

View class or forward reference for model.

build_from_model(
model: type[T],
) → type[View[TypeVar] | T]

Build the concrete view class from the provided model.

Parameters:

model – Model class to derive the view from.

Returns:

Generated view class for the model.

pydantic_views.BuilderCreate(view_name: str = 'Create') → Builder

Default builder for Create views.

Keeps fields with access mode READ_AND_WRITE, WRITE_ONLY, and WRITE_ONLY_ON_CREATION, hiding default None values.

Parameters:

view_name – View name.

Returns:

Builder configured for Create views.

pydantic_views.BuilderCreateResult(
view_name: str = 'CreateResult',
) → Builder

Default builder for CreateResult views.

Keeps fields with access mode READ_AND_WRITE, READ_ONLY, and READ_ONLY_ON_CREATION, and includes computed fields.

Parameters:

view_name – View name.

Returns:

Builder configured for CreateResult views.

pydantic_views.BuilderUpdate(view_name: str = 'Update') → Builder

Default builder for Update views.

Keeps fields with access mode READ_AND_WRITE and WRITE_ONLY, and makes all fields optional.

Parameters:

view_name – View name.

Returns:

Builder configured for Update views.

pydantic_views.BuilderLoad(view_name: str = 'Load') → Builder

Default builder for Load views.

Keeps fields with access mode READ_AND_WRITE and READ_ONLY, and includes computed fields.

Parameters:

view_name – View name.

Returns:

Builder configured for Load views.

pydantic_views.ensure_model_views(model: type[T])

Ensures model has a view manager and returns it.

Parameters:

model – Model class.

Returns:

Views manager for the model class.

class pydantic_views.Manager(model: type[TModel])

Bases: Generic

Registry and factory for views derived from a model class.

Initialize a manager for the given model type.

Parameters:

model – Base model class that views will be derived from.

property model: type[TModel]

Associated model class.

Returns:

Model class associated with this manager.

build_view(builder: Builder) → type[View[TModel] | TModel]

Build view class for Manager’s model.

Parameters:

builder – Builder used to generate the view for the managed model.

Returns:

Newly built view class registered under the builder name.

class pydantic_views.View

Bases: BaseModel, Generic

Lightweight view over a base Pydantic model with helper builders and mergers.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config = {'protected_namespaces': ('view_class_root', 'view_build_to', 'view_apply_to', 'view_build_from')}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod view_class_root() → type[T]

Return the base model class this view was generated from.

Returns:

Associated base model class.

classmethod view_build_from(model: T)

Create a view instance from a model instance, omitting unset fields.

Parameters:

model – Model instance to build the view from.

Returns:

View populated with the model data.

view_build_to() → T

Build the associated model instance using only fields set on the view.

Returns:

Model instance created from the view data.

view_apply_to(model: T) → T

Merge the view data into an existing model instance, returning a copy.

Parameters:

model – Model instance used as the base.

Returns:

New model instance with the view data applied.

class pydantic_views.RootView(root: RootModelRootType = PydanticUndefined)

Bases: View[RootModel[TypeVar]], RootModel[TypeVar], Generic

View wrapper specialized for RootModel instances.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config = {'protected_namespaces': ('view_class_root', 'view_build_to', 'view_apply_to', 'view_build_from')}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].