normalize_isodatetime

safir.pydantic.normalize_isodatetime(v)

Pydantic field validator for datetime fields in ISO format.

This field validator requires a subset of the ISO 8601 date and time format, YYYY-MM-DD[THH:MM:SS[.mmm]][Z]. Regardless of whether the trailing Z is included, the date and time are interpreted as being in UTC, not local time. This format is compatible with Kubernetes, the IVOA DALI standard, and the format produced by safir.datetime.isodatetime.

It should be used when the other formats supported by Pydantic by default (such as dates and times in other timezones) shouldn’t be allowed, such as when strict conformance with the IVOA standard is desired.

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 provided time string is not in the correct format.

Notes

Prefer to use the IvoaIsoDatetime 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="Date and time last used",
        examples=["2023-01-25T15:44:34Z"],
    )

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