Feature: `DTOData.create_instance()` nested kwargs #1741

peterschutt · 2023-05-26T11:32:05Z

This PR adds a feature to the DTOData.create_instance() method that supports providing values for arbitrarily nested data via kwargs using a double-underscore syntax. For example data.create_instance(foo__bar="baz").

In the following example, the DTO is configured to exclude the baz attribute from request data, but the field has no default, and so is required in order to be able to instantiate the hierarchy of models. The kwarg foo__baz="world" is passed to create_instance() call, which gives Bar.foo.baz a value.

from dataclasses import dataclass
from typing import Any, Dict

from typing_extensions import Annotated

from litestar import post
from litestar.dto.factory import DTOConfig, DTOData
from litestar.dto.factory.stdlib import DataclassDTO

@dataclass
class Foo:
    bar: str
    baz: str

@dataclass
class Bar:
    foo: Foo

config = DTOConfig(exclude={"foo.baz"})
dto = DataclassDTO[Annotated[Bar, config]]

@post(dto=dto, return_dto=None)
def handler(data: DTOData[Bar]) -> Dict[str, Any]:
    res = data.create_instance(foo__baz="world")
    assert res.foo.baz == "world"
    return res

Closes #1727

This commit modifies the way that DTO backends manage their `TransferFieldDefinition` instances. Previously, the backend would not keep a field definition for excluded fields, however, this proved limiting when wanting to use the `factory._backends.utils.transfer_instance_data()` method to move data from unstructured builtins to data model instances. In this scenario, and generally whenever we are moving inbound data from a transfer model to the data model, we need to transfer a value for all fields, including fields that are excluded from request and response data, unless an omitted field has a default value. Adds an `is_excluded` attribute to `TransferFieldDefinition` so that generated transfer models can still omit the field, and so that the field can still be omitted from return data. We no longer modify the `TransferFieldDefinition` type and defaults in the case of `is_partial`. Instead, the backend implementations do the `UnsetType` splicing at transfer model generation time. This is important so that we can still discern when a field definition originally had a default value specified, after the partial handling has been applied.