Utilities & Helpers

ZCore includes a collection of utility functions and serialization helpers designed to handle advanced Python data types, dynamic application timezones, Draft-7 JSON Schema validation, URL-safe slug generation, and database-to-application event bridging.

1. JSON Serialization & Parsing

Standard Python json fails when serializing UUID, datetime, date, time, or Decimal objects. ZCore provides custom encoders and wrapper functions:

from zcore.utils.helpers import json_dumps, json_loads, CustomJSONEncoder

json_dumps

Serializes a Python object or Pydantic data structure into a JSON string using CustomJSONEncoder.

def json_dumps(obj: Any, **kwargs: Any) -> str: ...

json_loads

Deserializes a JSON string or binary byte stream back into Python structures.

def json_loads(s: str | bytes, **kwargs: Any) -> Any: ...

2. Dynamic Timezone Management (zcore.utils.timezone)

Provides timezone-aware datetime operations powered by Python's zoneinfo standard library, falling back to UTC if misconfigured or running across system platforms without native zoneinfo tables.

from zcore.utils.timezone import (
    now,
    utc_now,
    to_app_timezone,
    get_app_timezone,
    format_iso_with_app_timezone,
    ZDateTime
)

now

Returns the current timezone-aware datetime bound to the application's configured timezone (settings.TIMEZONE).

def now() -> datetime: ...

utc_now

Returns the current timezone-aware datetime explicitly bound to UTC.

def utc_now() -> datetime: ...

to_app_timezone

Converts any datetime object (naive or aware) to the application's configured timezone. Naive datetimes are assumed to be UTC before transformation.

def to_app_timezone(dt: datetime | None) -> datetime | None: ...

format_iso_with_app_timezone

Converts a datetime to the application's timezone and outputs a standardized ISO 8601 string. Respects settings.AUTO_CONVERT_TIMEZONE.

def format_iso_with_app_timezone(dt: datetime | None) -> str | None: ...

ZDateTime

Pydantic Annotated type wrapper for datetime attributes that automatically formats fields to ISO 8601 strings in the application's configured timezone during JSON response serialization.

from pydantic import BaseModel
from zcore.utils.timezone import ZDateTime

class TaskResponse(BaseModel):
    created_at: ZDateTime

3. JSON Schema Validation (validate_json_schema)

Validates arbitrary dictionary payloads or schema structures using the Draft-7 JSON Schema specification.

from zcore.utils.validators import validate_json_schema

# Validate payload against a schema
validate_json_schema(data={"name": "Task 1"}, schema=my_draft7_schema)

# Or assert that a schema definition itself is structurally valid
validate_json_schema(data=my_draft7_schema)

4. Text & Type Utilities

slugify

Transforms an input text string into a sanitized, URL-safe, hyphenated slug.

from zcore.utils.helpers import slugify

slug = slugify("Hello World & Welcome!") # -> "hello-world-welcome"

SafeUrl

Pydantic Annotated type wrapper for HttpUrl that automatically serializes URL instances cleanly to plain strings during model dumps.

from zcore.utils.helpers import SafeUrl
from pydantic import BaseModel

class WebhookConfig(BaseModel):
    target_url: SafeUrl  # Serializes directly to str in JSON exports

5. Database Event Bridge (zcore.db.events)

Provides a decoupled, non-blocking bridge between low-level database operations and the application's central EventDispatcher.

from zcore.db.events import register_db_event_dispatcher, dispatch_db_event

register_db_event_dispatcher

Configures the central event dispatcher used by database modules to notify downstream systems of lifecycle transitions. Invoked during main.py bootstrap.

register_db_event_dispatcher(kernel.dispatcher)

dispatch_db_event

Safely dispatches database lifecycle events asynchronously within the active event loop, catching and logging handler errors to protect calling database engines.

await dispatch_db_event("db.record_created", {"table": "tasks", "id": str(task_id)})