data type for unix timestamp - Epoch

[commonism]

Initial Checks

• I have searched Google & GitHub for similar requests and couldn't find anything
• I have read and followed the docs and still think this feature is missing

Description

Current pydantic supports datetime.datetime type, serialization as {type: string, format: date-time}.
De-serialisation of this type includes coercion from integer in ms or seconds since epoch as well.
Serialization is limited to iso-format as string.

I propose to create a new type, Epoch {type: integer, format: date-time} to be used for unix timestamps which gets serialized to integer and has proper semantics for the schema.

I currently use an Annotated datetime, the schema generated does not match the value, it's ugly, incomplete and carrying this to multiple projects is building tomorrows technical debt.

Having Epoch as a standard data type would improve usability for pydantic at a minimal cost.

import datetime
from typing import Any

from typing_extensions import Annotated

from pydantic import BaseModel, SerializerFunctionWrapHandler
from pydantic.functional_serializers import WrapSerializer


def ser_wrap(v: Any, nxt: SerializerFunctionWrapHandler) -> int:
    return int(v.timestamp())

Epoch = Annotated[datetime.datetime, WrapSerializer(ser_wrap, when_used='json'), ]


class A(BaseModel):
    epoch: Epoch

now = datetime.datetime.now()
ts = int(now.timestamp())
a = A.model_validate({"epoch":now.timestamp()})
v = a.model_dump(mode='json')
assert v["epoch"] == ts

b = A.model_construct(epoch=now)
v = b.model_dump(mode='json')
assert v["epoch"] == ts

c = A.model_validate(dict(epoch=now))
v = c.model_dump(mode='json')
assert v["epoch"] == ts

Affected Components

• Compatibility between releases
• Data validation/parsing
• Data serialization - .model_dump() and .model_dump_json()
• JSON Schema
• Dataclasses
• Model Config
• Field Types - adding or changing a particular data type
• Function validation decorator
• Generic Models
• Other Model behaviour - model_construct(), pickling, private attributes, ORM mode
• Plugins and integration with other tools - mypy, FastAPI, python-devtools, Hypothesis, VS Code, PyCharm, etc.