normalize_datetime

safir.pydantic.normalize_datetime(v)

Pydantic field validator for datetime fields.

Supports datetime fields given as either datetime objects or seconds since epoch (not the other types Pydantic natively supports) and ensures that the resulting datetime object is timezone-aware and in the UTC timezone.

Parameters:

v (Any) – Field representing a datetime.

Returns:

The timezone-aware datetime or None if the input was None.

Return type:

datetime.datetime or None

Raises:

ValueError – Raised if the input could not be parsed as a datetime.

Notes

Prefer to use the UtcDatetime type instead of using this function as a validator.

Examples

Here is a partial model that uses this function as a field validator.

class Info(BaseModel):
    last_used: datetime | None = Field(
        None,
        title="Last used",
        description="When last used in seconds since epoch",
        examples=[1614986130],
    )

    _normalize_last_used = field_validator("last_used", mode="before")(
        normalize_datetime
    )