Pydantic

Pydantic is used to enforce type hints at runtime, and provides user friendly errors when data is invalid.

Models

The primary means of defining objects in pydantic is via models (models are classes which inherit from BaseModel). Models work (conceptually) the same as types in strictly typed languages. The idea is that untrusted data can be passed to a model, and after parsing and validation pydantic guarantees that the fields of the resultant model instance will conform to the field types defined on the model.

In the example below are we fetching some account details and want to make sure that the system and username are of type `StrictStr` and the password is a `SecretStr`. The difference between StrictStr and str is that pydantic will complain if the value is not a string when using StrictStr. With only str will pydantic cast the value into a string if it can and only complain if it can't.

Model Signature

All pydantic models will have their [signature generated based on their fields](https://docs.pydantic.dev/usage/models/#model-signature). An accurate signature is useful for introspection purposes.

To be included in the signature, a field's alias or name must be a valid Python identifier. pydantic prefers aliases over names, but may use field names if the alias is not a valid Python identifier.

Field Order

Field order is important in models for the following reasons:

validation is performed in the order fields are defined; fields validators can access the values of earlier fields, but not later ones
field order is preserved in the model schema
field order is preserved in validation errors
field order is preserved by .dict() and .json() functions.

Data Conversion

pydantic will try to cast input data into the model field types. In case the model type permits less information then the amount of data provided, will this lead to data loss.

class Model(BaseModel) a: int

a = Model(a=123.45) # Returns 123

[Strict type checking](https://docs.pydantic.dev/usage/types/#strict-types) is partially supported.

Required Fields

You can declare a field as required in three different ways. Either by just providing the type, or a type and an ellipses or the Field function followed by ellipses.

from pydantic import BaseModel, Field

class Model(BaseModel): a: int b: int = … c: int = Field(…)

To specify that a field is required but that the value can be Null can you use the `None` value. The same three options to write the same is possible.

class Model(BaseModel): a: int | None b: int | None = … c: int | None = Field(…)

The Field function can take many different arguments to provide extra [customization](#field-customization) to the information.

Default Values

A model can have default properties which are defined either with the assignment operator or the [Field customization](#field-customization) `default`.

If you want the default to be generated dynamically can you specify that through the Field `default_factory` argument and add a custom function.

Model Methods and Properties

Models possess the following methods and attributes:

dict(): returns a dictionary of the model's fields and values; cf. exporting models
json(): returns a JSON string representation dict()
copy(): returns a copy (by default, [shallow copy](list.md)) of the model
parse_obj(): a utility for loading any object into a model with error handling if the object is not a dictionary
parse_raw(): a utility for loading strings of numerous formats
parse_file(): like parseraw() but for file paths
from_orm(): loads data into a model from an arbitrary class
schema(): returns a dictionary representing the model as JSON Schema
schema_json(): returns a JSON string representation of schema()
construct(): a class method for creating models without running validation
__fields_set__: Set of names of fields which were set when the model instance was initialised
__fields__: a dictionary of the model's fields
__config__: the configuration class for the model

Private Model Attributes

https://docs.pydantic.dev/usage/models/#private-model-attributes

Limit attribute scope

Exclude attributes

https://docs.pydantic.dev/usage/models/#automatically-excluded-attributes

Include attributes

Recursive Models

https://docs.pydantic.dev/usage/models/#recursive-models

Below is some Json data and then a data class enhanced with Pydantic's BaseModel. The model is using [recursive models](https://docs.pydantic.dev/usage/models/#recursive-models).

from pydantic import BaseModel from typing import Optional

data = { "name": "Max", "age": "55", "location": { "city": "Stockholm", "state": "Stockholm" }, "bike": "best bike", "rides": [7, 3, 12, 14, "12"], "bikebooks": [ { "isin": "23232123459", "title": "Riding my bike", "subtitle": "And other musings" }, { "isin": "2323212345", "title": "Riding my bike again", "subtitle": "No more musings" }, ] }

class Location(BaseModel): city: str state: str country: Optional[str] = "Mariehamn" # Sets the default to "Mariehamn"

@validator('city') @classmethod def city_is_mariehamn(cls, v): if v != 'Mariehamn': raise ValueError('City must be "Mariehamn".') return v.title()

class Book(BaseModel): isin: int title: str subtitle: str

@validator('isin') @classmethod def isin_must_be_correct_length(cls, v): if len(str(v)) != 11: raise ValueError('isin must be 11 characters long') return v

class User(BaseModel): name: str location: Optional[Location] = None bike: str rides: list[int] = [] bikebooks: list[Book] = [Book(**book) for book in data.get('bikebooks')]

user = User(**data)

Reserved Names

If you encounter reserved names for your data classes, then can you use an [alias](https://docs.pydantic.dev/usage/models/#reserved-names). This is for example useful if you use Pydantic with an ORM or if you want to expose names as camelCase but internally use snake\_case.

class MyModel(BaseModel): metadata: dict[str, str] = Field(alias='metadata_')

class Config: orm_mode = True

Alias precedendence

https://docs.pydantic.dev/usage/model_config/#alias-precedence

## Construct

The [construct() method](https://docs.pydantic.dev/usage/models/#creating-models-without-validation) allows models to be created without validation. This can be useful when data has already been validated or comes from a trusted source and you want to create a model as efficiently as possible (construct() is generally around 30x faster than creating a model with full validation).

## Create Model from NamedTuple or TypedDict

Sometimes you already use in your application classes that inherit from NamedTuple or TypedDict and you don't want to duplicate all your information to have a BaseModel. For this pydantic provides [createmodelfromnamedtuple and createmodelfromtypeddict methods](https://docs.pydantic.dev/usage/models/#model-creation-from-namedtuple-or-typeddict). Those methods have the exact same keyword arguments as createmodel.

## Custom Root Types

Pydantic models can be defined with a [custom root type](https://docs.pydantic.dev/usage/models/#custom-root-types) by declaring the root field.

The root type can be any type supported by pydantic, and is specified by the type hint on the root field. The root value can be passed to the model init via the root keyword argument, or as the first and only argument to parseobj.

If you call the parseobj method for a model with a custom root type with a dict as the first argument, the following logic is used:

If the custom root type is a mapping type (eg., Dict or Mapping), the argument itself is always validated against the custom root type. For other custom root types, if the dict has precisely one key with the value root, the corresponding value will be validated against the custom root type. Otherwise, the dict itself is validated against the custom root type.

## Faux Immutability

[Models can be configured to be immutable](https://docs.pydantic.dev/usage/models/#faux-immutability) via allow\_mutation = False. When this is set, attempting to change the values of instance attributes will raise errors. See model config for more details on Config.

## Generic Models

The [generic models](https://docs.pydantic.dev/usage/models/#generic-models) makes it easier to reuse a common model structure.

In order to declare a generic model, you perform the following steps:

Declare one or more typing.TypeVar instances to use to parameterize your model.
Declare a pydantic model that inherits from pydantic.generics.GenericModel and typing.Generic, where you pass the TypeVar instances as parameters to typing.Generic.
Use the TypeVar instances as annotations where you will want to replace them with other types or pydantic models.

If you set Config or make use of validator in your generic model definition, it is applied to concrete subclasses in the same way as when inheriting from BaseModel. Any methods defined on your generic class will also be inherited.

## Dynamic Model Creation

There are some occasions where the shape of a model is not known until runtime. For this pydantic provides the [createmodel method to allow models to be created on the fly](https://docs.pydantic.dev/usage/models/#dynamic-model-creation).

## Abstract Base Classes

Pydantic models can be used alongside Python's [Abstract Base Classes](https://docs.pydantic.dev/usage/models/#abstract-base-classes) (ABCs).

## Structural Pattern Matching

https://docs.pydantic.dev/usage/models/#structural-pattern-matching

## Postponed annotations

https://docs.pydantic.dev/usage/postponed_annotations/

https://docs.pydantic.dev/usage/model_config/

## Change behaviour globally

https://docs.pydantic.dev/usage/model_config/#change-behaviour-globally

## Alias Generator

https://docs.pydantic.dev/usage/model_config/#alias-generator

## Alias precedence

https://docs.pydantic.dev/usage/model_config/#alias-precedence

Dataclasses

src/conf.py

An example of structuring configurations with pydantic dataclasses.

"""Configuration module for hax."""
import keyring
import platform
from datetime import date, datetime, timedelta
from hax.dev import BrewPackage
from tomli import load
from pathlib import Path
from pydantic import BaseModel, SecretStr, computed_field
from pydantic.dataclasses import dataclass


def get_config(file: Path) -> dict:
    """Read a file in TOML format and return a dict."""
    with open(file, mode="rb") as f:
        config = load(f)
    return config


@dataclass
class Project:
    """Project class which contains project related settings.

    Attributes:
        name: The name of the project.
        version: The version of the project.
        path: The path to the project. Is a computed value based on which operating system is used.

    """

    os = platform.system()
    path: Path = Path.home() / "Repos" / "bojort" if os == "Darwin" else Path.home() / "hax"
    database_dir = Path.home() / "Databases"
    temp_dir: Path = Path.home() / "temp"
    config_file: Path = path / "pyproject.toml"
    playwright_auth: Path = temp_dir / "playwright_auth.json"
    name: str = get_config(file=config_file)["project"]["name"]
    version: str = get_config(file=config_file)["project"]["version"]


@dataclass
class Deps:
    """Dependencies class which contains dependencies related settings.

    Attributes:
        az_cli_version: The version of Azure CLI.
    """

    az_cli_version: str = BrewPackage(package_name="az").version()


@dataclass
class Bojort:
    """Bojort class which contains Bojort related settings."""

    path: Path = Path.home() / "Repos" / "bojort"
    config_file: Path = path / "pyproject.toml"
    name: str = get_config(file=config_file)["project"]["name"]
    version: str = get_config(file=config_file)["project"]["version"]


@dataclass
class Crosskey:
    """Crosskey class which contains Crosskey related settings.

    Attributes:
        ad_username: The username for Crosskey AD.
        jira_url: The url for Crosskey Jira.
        wiki_url: The url for Crosskey Confluence.
    """

    ad_username: str = "kgronber"
    jira_url: str = "https://jira.crosskey.fi"
    wiki_url: str = "https://wiki.crosskey.fi"


class Secret(BaseModel):
    """Class which contains secrets."""

    @computed_field()
    def crosskey_ad_password(self) -> SecretStr:
        password = keyring.get_password(
            service_name=f"Crosskey AD ({Crosskey.ad_username})", username=Crosskey.ad_username)
        return SecretStr(password)

    @computed_field()
    def openai_token(self) -> SecretStr:
        token = keyring.get_password(service_name="OpenAI", username="openai-token")
        return SecretStr(token)


@dataclass(frozen=True)
class Time:
    """Class for time related settings."""

    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    today = date.today()
    yesterday = today - timedelta(days=1)
    ty = today.strftime("%Y")
    tm = today.strftime("%m")
    td = today.strftime("%d")
    yy = yesterday.strftime("%Y")
    ym = yesterday.strftime("%m")
    yd = yesterday.strftime("%d")