3.7 · Guides
Utilities¶
Hinoki includes a small set of helpers where the framework can define clear behavior. Use the Python standard library for ordinary IDs, paths, and application-specific formatting.
UTC time¶
utc_now() returns a timezone-aware datetime in UTC. It is suitable for field factories and application code:
from datetime import datetime
from uuid import UUID, uuid4
from hinoki.orm import Model, field
from hinoki.utils import utc_now
class Event(Model):
id: UUID = field(primary_key=True, default_factory=uuid4)
created_at: datetime = field(default_factory=utc_now)
The clock is a callable, so code that depends on time can accept a Clock and tests can supply a fixed function. No process-wide clock patch is needed.
For tests that need to move time more than once, use ManualClock from hinoki.testing:
from datetime import UTC, datetime
from hinoki.testing import ManualClock
clock = ManualClock(datetime(2026, 1, 1, tzinfo=UTC))
first = clock()
clock.advance(seconds=60)
second = clock()
It stores instants in UTC, accepts only timezone-aware values, and can be passed to app.now(clock) or utc_today(clock).
Application timezone¶
Set an IANA timezone name in the app's global settings. It defaults to UTC; invalid names fail while settings are constructed:
from hinoki import Hinoki, settings
class ProjectSettings(settings.AppSettings):
timezone: str = "Europe/Rome"
app = Hinoki(settings=ProjectSettings)
current_time = app.now() # aware datetime in Europe/Rome
app.now() reads the timezone from that app's settings and returns an aware datetime. Apps in one process can use different settings. There is no Hinoki(timezone=...) argument. To make time-dependent code deterministic, pass a Clock to app.now(clock).
utc_today(clock=utc_now) returns the calendar date in UTC. The framework uses it for waiver expiry so the result does not depend on the machine's local timezone. For example, 2026-01-02 00:30+02:00 is 2026-01-01 in UTC.
Model update timestamps¶
Declare the columns explicitly and decorate the model with @timestamps() to refresh updated_at on each ORM update:
from datetime import datetime
from uuid import UUID, uuid4
from hinoki.orm import Model, field, timestamps
from hinoki.utils import utc_now
@timestamps()
class Note(Model):
id: UUID = field(primary_key=True, default_factory=uuid4)
title: str
created_at: datetime = field(default_factory=utc_now)
updated_at: datetime = field(default_factory=utc_now)
The decorator requires a non-nullable datetime field named updated_at. Use @timestamps("modified_at", clock=my_clock) for another field or an injected clock. Clock values must be timezone-aware; Hinoki converts them to UTC. A value supplied for the managed field in an update is replaced by the clock value.
The behavior applies to Model.aupdate/update_where, instance asave/aupdate_from, and QuerySet.aupdate, including sync counterparts. All rows changed by one statement receive the same time. Creation uses the declared field factories. Raw SQL bypasses this ORM behavior; use an explicit database trigger if independent writers need database-authoritative timestamps.
These fields are ordinary model columns. They remain visible to type checkers and the migration planner; Hinoki does not add hidden fields or apply migrations automatically.
Other common needs¶
- Use
uuid.uuid4()for ordinary UUID identifiers. - Use
secretsorhinoki.crypto.random_tokenfor secret tokens, depending on whether the token is part of Hinoki authentication. - Use
pathlib.Pathfor filesystem paths and the existingSettingsloader for environment and dotenv configuration. - Use
hinoki.testingclients for application requests; inject a clock callable when behavior depends on time.
Hinoki does not provide generic slug, retry, or environment helpers because their rules depend on the application.