Date and Time Generation

DateTimeGenerator supports fixed values, bounded random windows, weighted calendar/time selection, relative offsets, and epoch output. Its generated signature in the date/time generator reference is the version-specific parameter contract.

Fixed and bounded values

<generate name="events" count="10">
    <variable name="issued_at" generator="DateTimeGenerator(value='2026-07-30 12:00:00')"/>
    <key name="fixed" generator="DateTimeGenerator(value='2026-07-30 12:00:00')"/>
    <key name="window" generator="DateTimeGenerator(min='2026-07-01 00:00:00', max='2026-07-31 23:59:59', random=True)"/>
    <key name="relative" generator="DateTimeGenerator(offset='-7d', max_offset='7d')"/>
    <key name="due_date" generator="DateTimeGenerator(reference='issued_at', offset='30d')" outDateFormat="%Y-%m-%d"/>
</generate>

Relative windows use the runtime clock anchor. A seeded execution uses the deterministic runtime clock; an unseeded execution intentionally reads the live clock.

Keep a datetime raw in a variable while later fields perform arithmetic, then format only the exported key. reference is deliberately a lookup contract, not arbitrary Python: it accepts a bare current-scope name, this.<field>, this.parent.<field>, or root.<field>. Calls, subscripts, and a bare parent.<field> are rejected.

Weighted selection

The generator can constrain months, weekdays, days of month, and time buckets. Weight lists select relative probability inside the corresponding domain; they do not change the requested record count.

Explicit month_weights, weekday_weights, dom_weights, hour_weights, minute_weights, or second_weights override sugar for the same dimension. Declarative string forms support literal lists, repetition such as '[1]*24', and concatenation such as '[0,0,1]+[0]*9'; list comprehensions and arbitrary expressions are not accepted.

<generate name="business_events" count="100">
    <key name="created_at" generator="DateTimeGenerator(min='2026-01-01 00:00:00', max='2026-12-31 23:59:59', weekdays='mon,tue,wed,thu,fri', hours_preset='office', minute_granularity=15)"/>
</generate>

Epoch output

Set as_epoch=True and select the implementation-supported epoch_unit when a numeric timestamp is required. Keep the consumer's unit explicit; seconds and milliseconds are not interchangeable.

For field conversion, inDateFormat="epoch" distinguishes seconds, milliseconds, microseconds, and nanoseconds by the supported digit lengths. outDateFormat accepts epoch, epoch_millis, epoch_micros, and epoch_nanos. Prefer this field-level form in XML; use generator as_epoch when the generated value itself must be numeric.

Invalid windows, weights, offsets, and formats use the central generator error catalog. Do not catch and reinterpret them in descriptor scripts.