Skip to content

pydantic_jsonpointer.pydantic_adapter

pydantic_jsonpointer.pydantic_adapter

Pydantic-specific traversal support.

Provides: - FieldResolver Protocol: maps RFC 6901 tokens <-> Python attribute names - Three shipped resolvers: ByAttribute, BySerializationAlias, ByValidationAlias - BaseModelAdapter: ContainerAdapter for pydantic.BaseModel instances

BaseModelAdapter is auto-registered against pydantic.BaseModel in pydantic_jsonpointer/__init__.py; importing this module alone has no side effects on the adapter registry.

BaseModelAdapter 

BaseModelAdapter(resolver: FieldResolver | None = None)

ContainerAdapter for pydantic.BaseModel instances.

Resolves tokens via a configurable FieldResolver (default BySerializationAlias). RootModel containers are transparently unwrapped to their .root value via unwrap.

Notes on semantics: - set and add are equivalent: a BaseModel's field set is fixed, so "create-or-replace" collapses to "replace". - remove sets the field to None and returns the previous value; only permitted when the field annotation accepts None. - is_step_frozen reports True when the parent model has ConfigDict(frozen=True) or the addressed field has Field(frozen=True); the walker propagates this taint to every descendant slot.

Source code in src/pydantic_jsonpointer/pydantic_adapter.py 
218
219
def __init__(self, resolver: FieldResolver | None = None) -> None:
    self._resolver: FieldResolver = resolver or BySerializationAlias()

with_resolver 

with_resolver(resolver: FieldResolver) -> Self

Return a copy of this adapter with resolver substituted.

Used by adapter_for(..., resolver=...) to apply a per-call resolver override without mutating the registered adapter. Subclasses that carry extra state inherit this behavior automatically because copy.copy preserves it; subclasses whose extra state needs custom cloning should override this method.

Source code in src/pydantic_jsonpointer/pydantic_adapter.py 
221
222
223
224
225
226
227
228
229
230
231
232
def with_resolver(self, resolver: FieldResolver) -> Self:
    """Return a copy of this adapter with ``resolver`` substituted.

    Used by ``adapter_for(..., resolver=...)`` to apply a per-call
    resolver override without mutating the registered adapter. Subclasses
    that carry extra state inherit this behavior automatically because
    ``copy.copy`` preserves it; subclasses whose extra state needs custom
    cloning should override this method.
    """
    new = copy.copy(self)
    new._resolver = resolver
    return new

ByAttribute

Resolves tokens against Python attribute names only.

Strictest policy — no aliases are consulted. Useful when patches are authored in code against models with attribute-name access patterns.

BySerializationAlias

Resolves tokens against the name that appears in model_dump(by_alias=True).

Match priority for to_attr (and equivalent precedence for to_token): 1. field.serialization_alias 2. field.alias 3. attribute name (only if neither alias is set)

This is the default resolver because JSON-Patch documents typically originate from the same serialized vocabulary the model emits.

ByValidationAlias

Resolves tokens against the names accepted by model_validate.

Match priority for to_attr: 1. any string in field.validation_alias (handling AliasChoices/AliasPath) 2. field.alias 3. attribute name (only if neither validation_alias nor alias is set)

FieldResolver

Bases: Protocol

Maps RFC 6901 tokens to Python attribute names on a Pydantic model.

Implementations must be stateless and side-effect-free.

to_attr 

to_attr(
    model_cls: type[BaseModel], token: str
) -> str | None

Return the Python attribute name on model_cls that this token addresses, or None if no field matches under this resolver's policy.

Source code in src/pydantic_jsonpointer/pydantic_adapter.py 
39
40
41
42
43
def to_attr(self, model_cls: type[BaseModel], token: str) -> str | None:
    """Return the Python attribute name on `model_cls` that this token
    addresses, or None if no field matches under this resolver's policy.
    """
    ...

to_token 

to_token(model_cls: type[BaseModel], attr: str) -> str

Inverse of to_attr: given an attribute name, return the token that should appear in a pointer addressing that field under this resolver's policy.

Source code in src/pydantic_jsonpointer/pydantic_adapter.py 
45
46
47
48
49
50
def to_token(self, model_cls: type[BaseModel], attr: str) -> str:
    """Inverse of `to_attr`: given an attribute name, return the token
    that should appear in a pointer addressing that field under this
    resolver's policy.
    """
    ...