Timing Module

Module: piethorn.math.converter.timing

Overview

This module formats durations and converts supported time inputs into the package’s UTC string representation.

format_time

format_time(years, months, days, hours, minutes, seconds, milliseconds=0, microseconds=0, nanoseconds=0.0, time_zone='UTC')

Format pre-separated time fields into a custom string.

from piethorn.math.converter.timing import format_time

format_time(2024, 1, 2, 3, 4, 5, 6, 7, 8, "UTC")

convert_seconds

convert_seconds(x, formatted=False, f_nano=True, f_micro=True, f_milli=True)

Break seconds into years, months, days, hours, minutes, seconds, and fractional parts.

When formatted=False, a dictionary is returned. When formatted=True, the result is formatted through format_time().

convert_to_utc

convert_to_utc(time_input, tpe='sec', formatting='%Y-%m-%d %H:%M:%S.%f')

Convert numeric, datetime, or string inputs into the UTC output format used by this package.

Autodoc

piethorn.math.converter.timing.convert_seconds(x, formatted=False, f_nano=True, f_micro=True, f_milli=True)

This function converts x number of seconds into years, months, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds.

The return of this function can be either a string or a dictionary. It’ll return a string if formatted is True, the string will be created with the format_time function. On the other hand, this function will return a dictionary with each of the previously stated times that x is distributed to.

Parameters:

  • x – The number of seconds to convert.

  • formatted – Whether to format the converted seconds into a time format.

  • f_nano – Whether to format nanoseconds in. This value only matters if formatted is True.

  • f_micro – Whether to format microseconds in. If this is false, then f_nano will be hard set to false. This value only matters if formatted is True.

  • f_milli – Whether to format milliseconds in. If this is false, then f_micro and f_nano will be hard set to false. This value only matters if formatted is True.

Returns:

The converted time. If formatted is True then the return is a string. Otherwise, the return will be a dictionary with appropriate values.

piethorn.math.converter.timing.convert_to_utc(time_input, tpe='sec', formatting='%Y-%m-%d %H:%M:%S.%f')

Converts various time formats to UTC with the format: year-month-day hour:minute:second . millisecond;microsecond;nanosecond UTC

The types of tpe: (Regardless of type, auto-detect will work. type is just there to help manage certain things.)

  • unknown - This is when you don’t know the type, so auto-detection will do a bit of extra lifting.

  • date - This is when it’s a native datetime.

  • str - For when input was a string.

  • nano - For int/float input that is declared in nanoseconds.

  • micro - For int/float input that is declared in microseconds.

  • milli - For int/float input that is declared in milliseconds.

  • sec - For int/float input that is declared in seconds.

  • minu - For int/float input that is declared in minutes.

  • hr - For int/float input that is declared in hours.

  • d - For int/float input that is declared in days.

  • wk - For int/float input that is declared in weeks.

  • mh - For int/float input that is declared in months.

  • yr - For int/float input that is declared in years.

  • de - For int/float input that is declared in decades.

  • cy - For int/float input that is declared in centuries.

  • mm - For int/float input that is declared in millenniums.

When the system is converting a numeric, it’ll have to try and convert the time_input into seconds. This is why it is best to define the type for numeric inputs.

Parameters:

  • time_input – The time to convert.

  • tpe – The type of value time_input is.

  • formatting – The type of formatting time_input has, only matters if time_input is a string.

Returns:

The string that is the UTC time of the provided time in the format stated at the top of this doc.

piethorn.math.converter.timing.format_time(years: int, months: int, days: int, hours: int, minutes: int, seconds: int, milliseconds: int | float = 0, microseconds: int | float = 0, nanoseconds: int | float = 0.0, time_zone='UTC')

This function doesn’t do any mathematics calculations to format the time, this function will only insert the values provided into appropriate locations. The formatting the values will take is described as follows:

If nanoseconds isn’t zero: year-month-day hour:minute:second . millisecond;microsecond;nanosecond time_zone

If microseconds isn’t zero, but nanoseconds are: year-month-day hour:minute:second . millisecond;microsecond time_zone

If milliseconds isn’t zero, but nanoseconds and microseconds are: year-month-day hour:minute:second ; millisecond time_zone

If nanoseconds, microseconds, and milliseconds are zero: year-month-day hour:minute:second time_zone

Parameters:

  • years – The number of years in the time.

  • months – The number of months in the time.

  • days – The number of days in the time.

  • hours – The number of hours in the time.

  • minutes – The number of minutes in the time.

  • seconds – The number of seconds in the time.

  • milliseconds – The number of milliseconds in the time. If this value is zero, then it will be omitted. (Default: 0)

  • microseconds – The number of microseconds in the time. If this value is zero, then it will be omitted. (Default: 0)

  • nanoseconds – The number of nanoseconds in the time. If this value is zero, then it will be omitted. (Default: 0)

  • time_zone – The timezone that the time being formatted is in. If this value is None or an empty string, then this value is omitted. (Default: UTC)

Returns:

The formatted time.