Pydantic integration

[miguelgrinberg]

This change adds a few features that support the use of Pydantic models with the DSL module, instead of the standard models defined as subclasses of the AsyncDocument class.

As part of this work some additions have been made to the typing implementation of DSL documents.

• Support for the Annotated syntax when defining document fields in the DSL module. Examples:

class TypedDocAnnotated(AsyncDocument):
    ip: Annotated[Optional[str], field.Ip()]
    k1: Annotated[str, field.Keyword(required=True)]
    k2: Annotated[M[str], field.Keyword()]
    k3: Annotated[str, mapped_field(field.Keyword(), default="foo")]

• Option to exclude a class variable from the list of attributes used to create the ES mapping:

class Doc(AsyncDocument):
    some_var: str = mapped_field(exclude=True)

• New BaseESModel and AsyncBaseESModel classes that inherit from Pydantic's BaseModel and add Elasticsearch superpowers. In particular, any model defined with one of these as its base class will have meta and _doc private attributes and to_doc() and from_doc() methods. The meta attribute includes metadata for each document, things such as id or score. The _doc attribute is a dynamically generated Document or AsyncDocument instance that can be used whenever access to the Elasticsearch index is needed. The methods convert between Pydantic models and ES documents.

  Aside from the extra attributes, this class works exactly like BaseModel and can be used to define data attributes and their validation rules, and the ES document is derived from them automatically. In particular, this class can be used in FastAPI routes, as shown in the quotes example included in this PR. Any annotations intended for the DSL module can be included in the Annotated[] type hint of the respective fields. The Index inner class can be included as well.

class Quote(BaseESModel):
    quote: str
    author: Annotated[str, dsl.Keyword()]
    tags: Annotated[list[str], dsl.Keyword()]
    embedding: Annotated[list[float], dsl.DenseVector()] = Field(init=False, default=[])

    class Index:
        name = 'quotes'

[github-actions]

🔍 Preview links for changed docs

• docs/reference/dsl_how_to_guides.md
• docs/reference/dsl_tutorials.md