Types Module

mosaicolabs.types.Time

Bases: BaseModel

A high-precision time representation.

The Time class splits a timestamp into a 64-bit integer for seconds and a 32-bit unsigned integer for nanoseconds.

Attributes:

Name	Type	Description
seconds	int	Seconds since the epoch (Unix time).
nanoseconds	int	Nanoseconds component within the current second, ranging from 0 to 999,999,999.

seconds instance-attribute

seconds

Seconds since the epoch (Unix time).

nanoseconds instance-attribute

nanoseconds

Nanoseconds component within the current second, ranging from 0 to 999,999,999.

validate_nanosec classmethod

validate_nanosec(v)

Ensures nanoseconds are within the valid [0, 1e9) range.

from_float classmethod

from_float(ftime)

Factory method to create a Time object from a float (seconds since epoch).

This method carefully handles floating-point artifacts by using rounding for the fractional part to ensure stable nanosecond conversion.

Parameters:

Name	Type	Description	Default
ftime	float	Total seconds since epoch (e.g., from time.time()).	required

Returns:

Type	Description
Time	A normalized Time instance.

from_milliseconds classmethod

from_milliseconds(total_milliseconds)

Factory method to create a Time object from a total count of milliseconds.

Parameters:

Name	Type	Description	Default
total_milliseconds	int	Total time elapsed in milliseconds.	required

Returns:

Type	Description
Time	A Time instance with split sec/nanosec components.

from_nanoseconds classmethod

from_nanoseconds(total_nanoseconds)

Factory method to create a Time object from a total count of nanoseconds.

Parameters:

Name	Type	Description	Default
total_nanoseconds	int	Total time elapsed in nanoseconds.	required

Returns:

Type	Description
Time	A Time instance with split sec/nanosec components.

from_datetime classmethod

from_datetime(dt)

Factory method to create a Time object from a Python datetime instance.

Parameters:

Name	Type	Description	Default
dt	datetime	A standard Python datetime object.	required

Returns:

Type	Description
Time	A Time instance reflecting the datetime's timestamp.

now classmethod

now()

Factory method that returns the current system UTC time in high precision.

to_float

to_float()

Converts the high-precision time to a float.

Precision Loss

Converting to a 64-bit float may result in the loss of nanosecond precision due to mantissa limitations.

to_nanoseconds

to_nanoseconds()

Converts the time to a total integer of nanoseconds.

This conversion preserves full precision.

to_milliseconds

to_milliseconds()

Converts the time to a total integer of milliseconds.

This conversion preserves full precision.

to_datetime

to_datetime()

Converts the time to a Python UTC datetime object.

Microsecond Limitation

Python's datetime objects typically support microsecond precision; nanosecond data below that threshold will be truncated.