mustash.time – Date and time format handlers

pydantic model mustash.time.DateTimeFormatter

Bases: BaseModel, ABC

Date and time parser and formatter.

Config:

  • extra: str = forbid

abstract format(value: datetime, /) → Element

Format a date and time.

Parameters:

value (datetime) – Date and time to format.

Returns:

Formatted date and time.

Return type:

Element

abstract parse(value: Element, /) → datetime

Extract a date and time from a value.

Parameters:

value (Element) – Value to extract the date and time from.

Returns:

Timezone-aware date and time.

Return type:

datetime

pydantic model mustash.time.FallbackDateTimeFormatter

Bases: DateTimeFormatter

Date and time formatter using multiple subformatters, with fallback.

Config:

  • extra: str = forbid

Fields:
field formatters: Annotated[list[DateTimeFormatter], MinLen(1)] [Required]

Date and time formatters to use, as a chain.

Constraints:

  • min_length = 1

format(value: datetime, /) → Element

Format a date and time.

Parameters:

value (datetime) – Date and time to format.

Returns:

Formatted date and time.

Return type:

Element

parse(value: Element, /) → datetime

Extract a date and time from a value.

Parameters:

value (Element) – Value to extract the date and time from.

Returns:

Timezone-aware date and time.

Return type:

datetime

pydantic model mustash.time.JavaDateTimeFormatter

Bases: DateTimeFormatter

Java date and time formatter.

Config:

  • extra: str = forbid

Fields:
field pattern: str [Required]

Java time pattern to extract the date and time with.

See Java time pattern for more information.

abstract format(value: datetime, /) → Element

Format a date and time.

Parameters:

value (datetime) – Date and time to format.

Returns:

Formatted date and time.

Return type:

Element

abstract parse(value: Element, /) → datetime

Extract a date and time from a value.

Parameters:

value (Element) – Value to extract the date and time from.

Returns:

Timezone-aware date and time.

Return type:

datetime

pydantic model mustash.time.ISO8601DateTimeFormatter

Bases: DateTimeFormatter

ISO 8601 date and time formatter.

Config:

  • extra: str = forbid

format(value: datetime, /) → Element

Format a date and time.

Parameters:

value (datetime) – Date and time to format.

Returns:

Formatted date and time.

Return type:

Element

parse(value: Element, /) → datetime

Extract a date and time from a value.

Parameters:

value (Element) – Value to extract the date and time from.

Returns:

Timezone-aware date and time.

Return type:

datetime

pydantic model mustash.time.UNIXDateTimeFormatter

Bases: DateTimeFormatter

UNIX timestamp formatter with second granularity.

Config:

  • extra: str = forbid

format(value: datetime, /) → Element

Format a date and time.

Parameters:

value (datetime) – Date and time to format.

Returns:

Formatted date and time.

Return type:

Element

parse(value: Element, /) → datetime

Extract a date and time from a value.

Parameters:

value (Element) – Value to extract the date and time from.

Returns:

Timezone-aware date and time.

Return type:

datetime

pydantic model mustash.time.UNIXMSDateTimeFormatter

Bases: DateTimeFormatter

UNIX timestamp formatter with millisecond granularity.

Config:

  • extra: str = forbid

format(value: datetime, /) → Element

Format a date and time.

Parameters:

value (datetime) – Date and time to format.

Returns:

Formatted date and time.

Return type:

Element

parse(value: Element, /) → datetime

Extract a date and time from a value.

Parameters:

value (Element) – Value to extract the date and time from.

Returns:

Timezone-aware date and time.

Return type:

datetime

pydantic model mustash.time.ESTAI64NDateTimeFormatter

Bases: DateTimeFormatter

TAI64N (ElasticSearch variant) date and time formatter.

A TAI64N timestamp is composed of three parts:

  • A big endian 63-bit signed integer (using two’s complement) represented as a 16-digit hexadecimal sequence optionally prefixed by “@”, being the number of seconds since the Epoch on the “Temps Atomique International” (international atomic time).

  • A big endian 32-bit unsigned integer represented as an 8-digit hexadecimal sequence, being the number of nanoseconds between 0 and 10^9-1 inclusive.

Note

The highest bit of the seconds count is reserved for future extensions.

As for UNIX timestamps, the Epoch is 1970, January 1st at midnight. The TAI does NOT normally include leap seconds, which means one usually needs to keep an updated list of leap seconds to accurately convert between UNIX timestamps and TAI64 variations.

ElasticSearch’s TAI64N implementation has two main twists on the TAI64N format definition:

  • It takes leap seconds into account when parsing and formatting TAI64.

  • It considers nanosecond counts greater than 10^9 - 1 valid, and adds whole seconds (while the standard does not describe the behaviour to adopt in such case).

This formatter implements TAI64N with the ElasticSearch twists.

See TAI64, TAI64N, and TAI64NA for more information regarding the TAI64 family of date and time formats.

Config:

  • extra: str = forbid

format(value: datetime, /) → Element

Format a date and time.

Parameters:

value (datetime) – Date and time to format.

Returns:

Formatted date and time.

Return type:

Element

parse(value: Element, /) → datetime

Extract a date and time from a value.

Parameters:

value (Element) – Value to extract the date and time from.

Returns:

Timezone-aware date and time.

Return type:

datetime