ab-pydantic-patch 1.2.0

Python Pydantic support of TypeScript-style utility types, including Partial, Required, Pick, and Omit. Useful for PATCH endpoints driven from BaseModel / SQLModel classes.

PATCH for Pydantic

Python Pydantic support of TypeScript-style utility types, including Partial, Required, Pick, and Omit. Useful for PATCH endpoints driven from BaseModel / SQLModel classes.

🦜🕸️

---

Table of Contents

• Introduction
• Quick Start
• Installation
• Usage
• Formatting and linting
• CICD

---

Introduction

Python is missing a key feature of modern day dynamic programming languages.

Namely, TypeScript supports these utility types: https://www.typescriptlang.org/docs/handbook/utility-types.html

• Partial: Makes all properties in type T optional. Useful for update forms or search filters where you only provide a subset of fields. [5, 6, 7]
• Required: The opposite of Partial; it makes all properties in type T mandatory, even if they were originally optional. [7, 8, 9]
• Pick<T, K>: Creates a new type by selecting a specific set of keys K from type T. Use this when you only need a small, focused subset of a larger object. [10, 11, 12]
• Omit<T, K>: The opposite of Pick; it creates a new type by removing specific keys K from type T. Use this when you want most of an object but need to strip out sensitive data (like passwords) or internal IDs. [1, 7, 13, 14, 15]

Because of this missing support in python, developers are often encouraged to duplicate their models & field definitions between their API and ORM definitions, which becomes a really tedious and feels like it involves double handling.

Especially for PATCH endpoints when we want to update something, should we really need to manually redefine the schema? Especially with larger nested JSON schemas, and even with Discriminated Unions, it becomes a really cumbersome and limited chore a developer must do to separate the API schema from their application models, when there is almost always an overlap in structure and field definitions.

This is the motivation behind building "PATCH for Pydantic".

Ultimately, with the really mature pydantic library, it actually makes building a package like this not too complicated.

---

Quick Start

Since this is just a package, and not a service, there is no real "run" action. But you can run the tests immediately.

Here are a list of available commands via make.

Bare Metal (i.e. your machine)

1. make install - install the required dependencies.
2. make test - runs the tests.

Docker

1. make build-docker - build the docker image.
2. make run-docker - run the docker compose services.
3. make test-docker - run the tests in docker.
4. make clean-docker - remove all docker containers etc.

---

Installation

For Dev work on the repo

Install uv, (if you haven't already) https://docs.astral.sh/uv/getting-started/installation/#installation-methods

brew install uv

Initialise pre-commit (validates ruff on commit.)

uv run pre-commit install

Install dependencies (including dev dependencies)

uv sync

If you are adding a new dev dependency, please run:

uv add --dev {your-new-package}

Namespaces

Packages all share the same namespace ab_core. To import this package into your project:

from ab_core.template import placeholder_func

We encourage you to make your package available to all of ab via this ab_core namespace. The goal is to streamline development, POCs and overall collaboration.

---

Usage

Adding the dependency to your project

The library is available on PyPI. You can install it using the following command:

Using pip:

pip install ab-pydantic-patch

Using UV

Note: there is currently no nice way like poetry, hence we still needd to provide the full url. https://github.com/astral-sh/uv/issues/10140

Add the dependency

uv add ab-pydantic-patch

Using poetry:

Then run the following command to install the package:

poetry add ab-pydantic-patch

How Tos

---

Pick

Select a subset of fields.

Python

Before

class User(BaseModel):
    id: int
    name: str
    email: str

Transform

UserPick = Pick[User](fields={"id", "name"})

After (conceptual)

class UserPick(BaseModel):
    id: int
    name: str

---

TypeScript equivalent

type User = {
  id: number
  name: string
  email: string
}

type UserPick = Pick<User, "id" | "name">

---

Omit

Remove specific fields.

Python

Before

class User(BaseModel):
    id: int
    name: str
    email: str

Transform

UserOmit = Omit[User](fields={"email"})

After (conceptual)

class UserOmit(BaseModel):
    id: int
    name: str

---

TypeScript equivalent

type User = {
  id: number
  name: string
  email: string
}

type UserOmit = Omit<User, "email">

---

Partial

Make fields optional.

Python

Before

class User(BaseModel):
    id: int
    name: str

Transform

UserPartial = Partial[User](fields={"name"})

After (conceptual)

class UserPartial(BaseModel):
    id: int
    name: str | None = None

---

TypeScript equivalent

type User = {
  id: number
  name: string
}

type UserPartial = Partial<Pick<User, "name">> & Pick<User, "id">

---

Required

Force fields to be required.

Python

Before

class User(BaseModel):
    id: int | None = None
    name: str | None = None

Transform

UserRequired = Required[User](fields={"id"})

After (conceptual)

class UserRequired(BaseModel):
    id: int
    name: str | None = None

---

TypeScript equivalent

type User = {
  id?: number
  name?: string
}

type UserRequired = Required<Pick<User, "id">> & Omit<User, "id">

---

Patch (combine operations)

Python

Before

class User(BaseModel):
    id: int
    name: str
    email: str

Transform

UserPatch = Patch[User](
    pick={"id", "name"},
    partial={"name"},
    required={"id"},
)

After (conceptual)

class UserPatch(BaseModel):
    id: int
    name: str | None = None

---

set() vs None

Patch[User](partial=None)

→ all fields optional

class UserPatch(BaseModel):
    id: int | None = None
    name: str | None = None
    email: str | None = None

---

Patch[User](partial=set())

→ no fields optional

class UserPatch(BaseModel):
    id: int
    name: str
    email: str

---

Parent / Child (nested models)

Python

Before

class Pet(BaseModel):
    id: int
    name: str
    type: str


class Household(BaseModel):
    id: int
    owner_name: str
    pets: list[Pet]

---

Transform

HouseholdPatch = Patch[Household](
    pick={"id", "pets"},
    required={"id"},
    child_models={
        Pet: PatchConfig(
            pick={"id", "name"},
            partial={"name"},
        )
    }
)

---

After (conceptual)

class PetPatch(BaseModel):
    id: int
    name: str | None = None


class HouseholdPatch(BaseModel):
    id: int
    pets: list[PetPatch] | None = None

---

Discriminated Union

Python

Before

from typing import Annotated, Union, Literal
from pydantic import Field


class Cat(BaseModel):
    kind: Literal["cat"]
    id: int
    name: str


class Dog(BaseModel):
    kind: Literal["dog"]
    id: int
    name: str


Pet = Annotated[Union[Cat, Dog], Field(discriminator="kind")]


class Owner(BaseModel):
    pet: Pet

---

Transform

OwnerPatch = Patch[Owner](
    pick={"pet"},
    child_models={
        Cat: PatchConfig(
            pick={"kind", "id", "name"},
            partial={"name"},
        ),
        Dog: PatchConfig(
            pick={"kind", "id", "name"},
            partial={"name"},
        ),
    }
)

---

After (conceptual)

class CatPatch(BaseModel):
    kind: Literal["cat"]
    id: int
    name: str | None = None


class DogPatch(BaseModel):
    kind: Literal["dog"]
    id: int
    name: str | None = None


PetPatch = Annotated[
    CatPatch | DogPatch,
    Field(discriminator="kind")
]


class OwnerPatch(BaseModel):
    pet: PetPatch | None = None

---

SQLModel Relationships

Python

Before

from sqlmodel import SQLModel, Field, Relationship


class Pet(SQLModel, table=True):
    id: int = Field(primary_key=True)
    name: str
    household_id: int | None = Field(default=None, foreign_key="household.id")


class Household(SQLModel, table=True):
    id: int = Field(primary_key=True)
    pets: list[Pet] = Relationship(back_populates="household")

---

Transform

HouseholdPatch = Patch[Household](
    pick={"id", "pets"},
    required={"id"},
    child_models={
        Pet: PatchConfig(
            pick={"id", "name"},
        )
    }
)

---

After (conceptual)

class PetPatch(BaseModel):
    id: int
    name: str | None = None


class HouseholdPatch(BaseModel):
    id: int
    pets: list[PetPatch] | None = None

---

Additional Notes

Caching

• Same model + same config → same generated class
• Nested models reuse generated types
• Improves performance and consistency

---

Discriminated unions

• Discriminator field is always required
• Cannot be omitted or made optional
• Each variant is transformed independently

---

Operation order

Applied in this order:

1. pick / omit
2. partial
3. required (final override)

---

Validation / Errors

• Unknown fields → error
• Required field removed by pick/omit → error
• Discriminator misconfiguration → error
• Invalid nested configs → error

---

Supported types

• BaseModel
• list[...]
• dict[...]
• Union / Annotated
• SQLModel (including relationships)

---

Forward references

pydantic-patch does not currently support unresolved forward references.

Because the library is type-driven, it needs real Python types when generating Pick, Omit, Partial, Required, or Patch models. This commonly affects SQLModel relationships split across multiple files, where relationships are declared using strings to avoid circular imports.

For example:

class Project(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str

    milestones: list["ProjectMilestone"] = Relationship(back_populates="project")

Calling Patch[Project](...) before resolving "ProjectMilestone" will raise ForwardReferencesNotSupported.

To fix this, import all related model modules first, bind the missing shallow references onto each module, then call model_rebuild(force=True) before creating the patch model.

import my_app.models.project as project_module
import my_app.models.project_milestone as milestone_module
import my_app.models.project_task as task_module
import my_app.models.task_comment as comment_module

from my_app.models import Project, ProjectMilestone, ProjectTask, TaskComment

project_module.ProjectMilestone = ProjectMilestone

milestone_module.Project = Project
milestone_module.ProjectTask = ProjectTask

task_module.ProjectMilestone = ProjectMilestone
task_module.TaskComment = TaskComment

comment_module.ProjectTask = ProjectTask

for model in (TaskComment, ProjectTask, ProjectMilestone, Project):
    model.model_rebuild(force=True)

Only create the patch schema after this setup:

ProjectPatch = Patch[Project](
    pick={"id", "name", "milestones"},
    required={"id"},
    child_models={
        ProjectMilestone: PatchConfig(
            pick={"id", "name", "tasks"},
        ),
        ProjectTask: PatchConfig(
            pick={"id", "title", "comments"},
        ),
        TaskComment: PatchConfig(
            pick={"id", "body"},
        ),
    },
)

In a real application, this setup usually belongs in your models package __init__.py, or in a central module that imports and prepares all ORM models before any patch schemas are generated.

For SQLModel relationship annotations, prefer SQLAlchemy-compatible relationship strings such as:

parent: "Project" = Relationship(back_populates="milestones")

rather than:

parent: "Project | None" = Relationship(back_populates="milestones")

SQLAlchemy can resolve "Project" as a mapped class name, but it cannot resolve "Project | None" as a relationship target.

---

Plugin: recursive_patch_orm_scalar

When using generated Patch[...] models with SQLModel / SQLAlchemy, you can apply nested updates directly onto an existing ORM object graph using recursive_patch_orm_scalar(...).

This recursively mutates the existing ORM instances in-place so SQLAlchemy can track and persist relationship changes naturally.

ProjectPatch = Patch[Project](
    pick={"name", "milestones"},
    child_models={
        ProjectMilestone: PatchConfig(
            pick={"id", "name", "tasks"},
        ),
        ProjectTask: PatchConfig(
            pick={"id", "title", "comments"},
        ),
        TaskComment: PatchConfig(
            pick={"id", "body"},
        ),
    },
)

project = db_session.get(Project, project_id)

recursive_patch_orm_scalar(project, patch)

db_session.add(project)
db_session.commit()

This is especially useful for FastAPI PATCH endpoints backed by SQLModel relationships.

---

Formatting and linting

We use Ruff as the formatter and linter. The pre-commit has hooks which runs checking and applies linting automatically. The CI validates the linting, ensuring main is always looking clean.

You can manually use these commands too:

1. make lint - check for linting issues.
2. make format - fix linting issues.

---

CICD

Publishing to PyPI

We publish to PyPI using Github releases. Steps are as follows:

1. Manually update the version in pyproject.toml file using a PR and merge to main. Use uv version --bump {patch/minor/major} to update the version.
2. Create a new release in Github with the tag name as the version number. This will trigger the publish workflow. In the Release window, type in the version number and it will prompt to create a new tag.
3. Verify the release in PyPI