Excluding from collections of nested models

In Python, generic types can accept one or more type parameters (types that are enclosed in square brackets). This pattern is often seen when representing a collection of some type, such as List[Person], where List is a generic container type, and Person specializes the contents of the collection to contain only instances of the Person class.

Given a generic type, with an arbitrary number of type parameters (e.g., GenericType[Type0, Type1, ..., TypeN]), we use the index of the type parameter to indicate which type the exclusion should refer to. For example, a.0.b, excludes the b field from the first type parameter of a, a.1.b excludes the b field from the second type parameter of a, and so on.

To demonstrate, lets add a self-referencing children relationship to our Person model:

from __future__ import annotations

from dataclasses import dataclass

from litestar import Litestar, get
from litestar.dto import DataclassDTO, DTOConfig
from litestar.params import FromPath


@dataclass
class Address:
    street: str
    city: str
    country: str


@dataclass
class Person:
    name: str
    age: int
    email: str
    address: Address
    children: list[Person]


class ReadDTO(DataclassDTO[Person]):
    config = DTOConfig(exclude={"email", "address.street", "children.0.email", "children.0.address"})


@get("/person/{name:str}", return_dto=ReadDTO, sync_to_thread=False)
def get_person(name: FromPath[str]) -> Person:
    # Your logic to retrieve the person goes here
    # For demonstration purposes, a placeholder Person instance is returned
    address = Address(street="123 Main St", city="Cityville", country="Countryland")
    child1 = Person(name="Child1", age=10, email="child1@example.com", address=address, children=[])
    child2 = Person(name="Child2", age=8, email="child2@example.com", address=address, children=[])
    return Person(
        name=name,
        age=30,
        email=f"email_of_{name}@example.com",
        address=address,
        children=[child1, child2],
    )


app = Litestar(route_handlers=[get_person])

Now, a Person can have one or many children, and each child can have one or many children, and so on.

We have explicitly excluded the email and address fields of all represented children ("children.0.email", "children.0.address").

In our handler we add children to the Person, and each child has no children of their own.

Here’s the output:

Fantastic! Our children are now represented in the output, and their emails and addresses are excluded. However, astute readers may have noticed that we didn’t exclude the children field of Person.children (e.g., children.0.children), yet that field is not represented in the output. To understand why, we’ll next look at the max_nested_depth configuration option.