Types

Reusable Pydantic Annotated types for human-readable sizes and durations.

These types are used across settings models and can be reused in custom configs.

SizeField

Accepts:

Integers: raw bytes (e.g., 10485760)
Strings: human-readable sizes (e.g., "10 MB", "1024B")

Formats:

Units: B, KB, MB, GB, TB (case-insensitive)
Optional whitespace: "10MB", "10 MB", " 10 MB "
Decimals allowed with units: "10.5 MB"
Numeric strings without units are treated as raw bytes: "10485760"

DurationField

Accepts:

Numbers: raw seconds (e.g., 3600, 0.25)
Strings: human-readable durations (e.g., "5s", "1h", "100ms")

Formats:

Units: ms, s, m, h, d, w (case-insensitive)
Optional whitespace: "5s", "5 s", "100 ms"
Decimals with units: "0.5s", "1.5h", "2.5d"
Numeric strings (including decimals) are treated as raw seconds: "9.5"

Examples:

_parse_duration("100ms")   # 0.1 seconds
_parse_duration("500ms")   # 0.5 seconds
_parse_duration("0.5s")    # 0.5 seconds
_parse_duration("1.5h")    # 5400.0 seconds
_parse_duration("2.5d")    # 216000.0 seconds

RotationDurationField

Accepts:

All DurationField formats
Rotation keywords: hourly, daily, weekly (case-insensitive)

Note: rotation keywords represent fixed intervals (e.g., "daily" means every 24 hours), not wall-clock boundaries.

Optional Variants

OptionalSizeField accepts None in addition to valid sizes.
OptionalDurationField accepts None in addition to valid durations.
OptionalRotationDurationField accepts None in addition to valid rotation durations.

Usage

from pydantic import BaseModel
from fapilog.core.types import DurationField, RotationDurationField, SizeField


class MyConfig(BaseModel):
    max_bytes: SizeField
    timeout_seconds: DurationField
    interval_seconds: RotationDurationField


cfg = MyConfig(max_bytes="10 MB", timeout_seconds="5s", interval_seconds="daily")
assert cfg.max_bytes == 10 * 1024 * 1024
assert cfg.timeout_seconds == 5.0
assert cfg.interval_seconds == 86400.0