pydantic-enhanced-serializer 2.1.1

Pydantic extension that allows user selection of object fields or expansions inline when serializing models

Better pydantic serialization for API use cases

Enhance pydantic's output serialization with features that can help make better APIs:

1. Output only fields and sets of fields requested by the caller, instead of all fields.

For example:

    api caller: Give me a User object with only the email and id fields.

    api response: Ok, instead of the usual 20 User fields, here is the object with only two.

2. Expand field values into more complex objects when requested

    api caller: Give me 10 Blog objects AND the User Objects that created them in ONE API response.

    api response: Ok, in addition to Blog.user_id, I will also give you Blog.User and its fields.

Both features are useful if you are using pydantic models to drive REST APIs (ie: FastAPI) and you want to emulate the field/expansion request model of GraphQL or other sophisticated APIs.

Features

• Simply formatted "Fields" Request: When serializing a model, specify which fields you want and get ONLY those fields
• "Field Sets": Ask for specific fields or named groupings of fields
• "Expansions": Create new field names that "expand" into bigger objects via complex loading (for example, if you have a user id field, you can ask for the entire user object to be loaded and included in the serialization.
• Nested Model: Full support for nested models, lists of models, etc...
• Schema: Augment pydantic json schema generation with fieldset options
• Integration examples are given for:
  • Django Ninja
  • FastAPI
  • Flask

Installation

$ pip install pydantic-enhanced-serializer

Help

See documentation for full details.

Quickstart Example - Python

Basically: use render_fieldset_model instead of model.model_dump() or model.model_dump_json().

Note that render_fieldset_model is an async function, so you may need to await it, depending on your application.

    from typing import ClassVar

    from pydantic import BaseModel
    from pydantic_enhanced_serializer import render_fieldset_model, FieldsetConfig

    class MyModel(BaseModel):
        field_1: str
        field_2: str
        field_3: str
        field_4: str
        expensive_field_5: str
        expensive_field_6: str

        # This is the key config
        fieldset_config: ClassVar = FieldsetConfig(
            fieldsets = {
                "default": ["field_1", "field_2"],
                "extra": ["field_3", "field_4"],
            }
        )

Get only "default" fields:

    model = MyModel(
        field_1="field1 value",
        field_2="field2 value",
        field_3="field3 value",
        field_4="field4 value",
        expensive_field_5="field5 value",
        expensive_field_6="field6 value",
    )

    # instead of model.model_dump() do:
    result = await render_fieldset_model(
        model=model,
        fieldsets=[]
    )

Result:

    # Only "default" fieldset fields returned
    result == {
        "field_1": "field1 value",
        "field_2": "field2 value",
    }

Ask for specific fields:

    result = await render_fieldset_model(
        model=model,
        fieldsets=["extra", "expensive_field_5"],
    )

Result:

    # "default" fieldset fields, "extra" fieldset fields and
    # "expensive_field_5" returned, but NOT "expensive_field_6"
    result == {
        "field_1": "field1 value",
        "field_2": "field2 value",
        "field_3": "field3 value",
        "field_4": "field4 value",
        "expensive_field_5": field5 value",
    }

Nested Fields example

    class SubModel(BaseModel):
        subfield1: str
        subfield2: str

        fieldset_config: ClassVar = FieldsetConfig(
            fieldsets = {
                "default": ["subfield1"],
            }
        )

    class MyModel(BaseModel):
        field1: str
        subfield: SubModel

        fieldset_config: ClassVar = FieldsetConfig(
            fieldsets = {
                "default": ["field1"],
            }
        )

    result = await render_fieldset_model(
        model=mymodel_instance,
        fields=["subfield.field2"]
    )

License

This project is licensed under the terms of the MIT license.