haive.core.common.mixins.timestamp_mixin

Reusable timestamp mixins for Pydantic models.

This module provides composable mixins for automatic creation and access timestamps in Pydantic models, with built-in UTC, field freezing, custom serialization, and age calculation (as both seconds and human-readable string).

Mixins:

• CreatedTimestampMixin: Adds a frozen created_at datetime field.

• AccessTimestampsMixin: Adds a frozen last_accessed_at datetime field, internal touch logic, and computed age fields.

Typical usage example:

class MyLog(CreatedTimestampMixin):

event: str

class MySession(AccessTimestampsMixin):

user_id: int

log = MyLog(event=”example”) session = MySession(user_id=42) print(log.created_at) # UTC datetime of creation print(session.age_human) # e.g. ‘0 minutes, 2 seconds’

All datetime fields are timezone-aware (UTC). All serialization returns integer POSIX timestamps for compatibility.

Intended for use with Sphinx AutoAPI and Google-style docstrings.

Classes

AccessTimestampsMixin	Mixin to add a frozen last_accessed_at timestamp, touch logic, and age calculation.
CreatedTimestampMixin	Mixin to provide a frozen, auto-populated UTC created_at timestamp field.

Functions

to_int_timestamp(dt[, _info])	Convert a datetime object to an integer POSIX timestamp.
utcnow()	Get the current UTC datetime with timezone information.

Module Contents

class haive.core.common.mixins.timestamp_mixin.AccessTimestampsMixin(/, **data)

Bases: CreatedTimestampMixin

Mixin to add a frozen last_accessed_at timestamp, touch logic, and age calculation.

Inherits:

CreatedTimestampMixin: Provides created_at.

Parameters:

data (Any)

last_accessed_at

The UTC datetime when the object was last accessed.

Type:

datetime

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

property age: datetime.timedelta

Get the time since object creation as a timedelta.

Returns:

The duration since created_at.

Return type:

timedelta

property age_human: str

Get a human-readable string for the object’s age.

Returns:

Age as ‘X days, Y hours, Z minutes, N seconds’.

Return type:

str

property age_seconds: int

Get the object’s age in seconds since creation.

Returns:

Age in seconds.

Return type:

int

class haive.core.common.mixins.timestamp_mixin.CreatedTimestampMixin(/, **data)

Bases: pydantic.BaseModel

Mixin to provide a frozen, auto-populated UTC created_at timestamp field.

Parameters:

data (Any)

created_at

The UTC datetime when the object was created.

Type:

datetime

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

property created_at_iso: str

Get the ISO 8601 string of the creation time.

Returns:

The created_at timestamp as an ISO string.

Return type:

str

haive.core.common.mixins.timestamp_mixin.to_int_timestamp(dt, _info=None)

Convert a datetime object to an integer POSIX timestamp.

Parameters:

• dt (datetime) – The datetime to convert.

• _info (Any, optional) – Not used, for Pydantic serializer compatibility.

Returns:

POSIX timestamp.

Return type:

int

haive.core.common.mixins.timestamp_mixin.utcnow()

Get the current UTC datetime with timezone information.

Returns:

The current UTC datetime.

Return type:

datetime