propertime package

Submodules

propertime.time module

Time and TimeUnit classes

class propertime.time.Time(value=None, *args, **kwargs)

Bases: float

A Time object, as a floating point number corresponding the number of seconds after the zero on the time axis (Epoch), which is set to 1st January 1970 UTC. Any other representations (as dates and hours, time zones, daylight saving times) are built on top of it.

It can be initialized in several ways:

  • Time(): if no arguments, time is set to now;

  • Time(1703517120.0): it the argument is a number, it is treated as Epoch seconds;

  • Time(2023,5,6,13,45): using a datetime-like mode;

  • Time(datetime(2023,5,6,13,45)): using a datetime, which if naive is assumed to be on UTC;

  • Time('2023-12-25T16:12:00+01:00'): using an ISO 8601 string, assumed on UTC if naive.

All these initialization modes support two additional arguments:

  • tz for the time zone, which if set on a naive time specification just decorates it, and if set on a timezone-aware (or offset-aware) time specification shifts it there;

  • offset for an offset in seconds wiht respect to UTC, which if set on a naive time specification just decorates it, and if set on a timezone-aware (or offset-aware) time specification shifts it there.

For example, Time(2023,5,6,13,45, tz='US/Eastern') creates a time directly on such time zone, while Time('2023-12-25T16:12:00+01:00', tz='US/Eastern') shifts the UTC time corresponding to the ISO 8601 specification by the string on the US/Eastern time zone.

The initialization in case of ambiguous or not-existent times generates an error: Time(2023,11,5,1,15, tz='US/Eastern') is ambiguous as there are “two” 1:15 AM on DST change on time zone US/Eastern, and Time(2023,3,12,2,30, tz='US/Eastern') just does not exists on such time zone. Creating Time objects form ambiguous time specification can be forced by enabling the “guessing” mode (guessing=True), but it will only be possible to create one of the two.

Parameters:

  • value – the time value, either as seconds (float), string representation, or datetime object.

  • tz – the time zone, either as object or string representation.

  • offset – the offset, in seconds, with respect to UTC.

  • guessing – if to enable guessing mode in case of ambiguous time specifications.

  • *args – the time components (year, month, day, hour, minute, seconds). Supersedes the value argument.

property tz

The time zone of the time. Set it to any valid time zone (object or string representation) to change it.

property offset

The (UTC) offset of the time. Set it to any valid number to change it.

dt()

Return time as a datetime object.

iso()

Return time as a string in ISO 8601 format.

conjugate()

Disabled. It does not make sense to use imaginary numbers with time.

imag()

Disabled. It does not make sense to use imaginary numbers with time.

real()

Disabled. It does not make sense to use imaginary numbers with time.

as_integer_ratio()

Return integer ratio.

Return a pair of integers, whose ratio is exactly equal to the original float and with a positive denominator.

Raise OverflowError on infinities and a ValueError on NaNs.

>>> (10.0).as_integer_ratio()
(10, 1)
>>> (0.0).as_integer_ratio()
(0, 1)
>>> (-.25).as_integer_ratio()
(-1, 4)
fromhex()

Create a floating-point number from a hexadecimal string.

>>> float.fromhex('0x1.ffffp10')
2047.984375
>>> float.fromhex('-0x1p-1074')
-5e-324
hex()

Return a hexadecimal representation of a floating-point number.

>>> (-0.1).hex()
'-0x1.999999999999ap-4'
>>> 3.14159.hex()
'0x1.921f9f01b866ep+1'
is_integer()

Return True if the float is an integer.

class propertime.time.TimeUnit(value=None, years=0, weeks=0, months=0, days=0, hours=0, minutes=0, seconds=0, microseconds=0, trustme=False)

Bases: object

A time unit object, that can have both fixed (physical) or variable (calendar) time length. It can handle precision up to the microsecond and can be added and subtracted with numerical values, Time and datetime objects, and other TimeUnits.

Can be initialized both using a numerical value, a string representation, or by explicitly setting years, months, weeks, days, hours, minutes, seconds and microseconds. In the string representation, the mapping is as follows:

  • 'Y': 'years'

  • 'M': 'months'

  • 'W': 'weeks'

  • 'D': 'days'

  • 'h': 'hours'

  • 'm': 'minutes'

  • 's': 'seconds'

  • 'u': 'microseconds'

For example, to create a time unit of one hour, the following three are equivalent, where the first one uses the numerical value, the second the string representation, and the third explicitly sets the time component (hours in this case): TimeUnit('1h'), TimeUnit(hours=1), or TimeUnit(3600). Not all time units can be initialized using the numerical value, in particular calendar time units which can have variable duration: a time unit of one day, or TimeUnit('1D'), can last for 23, 24 or 24 hours depending on DST changes. On the contrary, a TimeUnit('24h') will always last 24 hours and can be initialized as TimeUnit(86400) as well.

Parameters:

  • value – the time unit value, either as seconds (float) or string representation according to the mapping above.

  • years – the time unit years component.

  • weeks – the time unit weeks component.

  • months – the time unit weeks component.

  • days – the time unit days component.

  • hours – the time unit hours component.

  • minutes – the time unit minutes component.

  • seconds – the time unit seconds component.

  • microseconds – the time unit microseconds component.

  • trustme – a boolean switch to skip checks.

property value

The value of the TimeUnit, as its string representation.

property type

The type of the TimeUnit.

  • “Physical” if based on hours, minutes, seconds and microseconds, which have fixed duration.

  • “Calendar” if based on years, months, weeks and days, which have variable duration depending on the starting date, and their math is not always well defined (e.g. adding a month to the 30th of January does not make sense).

is_physical()

Return True if the TimeUnit type is physical, False otherwise.

is_calendar()

Return True if the TimeUnit type is calendar, False otherwise.

round(time, how=None)

Round a Time or datetime according to this TimeUnit.

floor(time)

Floor a Time or datetime according to this TimeUnit.

ceil(time)

Ceil a Time or datetime according to this TimeUnit.

shift(time, times=1)

Shift a given Time or datetime n times this TimeUnit.

as_seconds(start=None)

The duration of the TimeUnit in seconds.

Time manipulation utilities

propertime.utilities.timezonize(tz)

Convert a string representation of a time zone to its pytz object, or do nothing if the argument is already a pytz time zone or tzoffset, or None.

propertime.utilities.is_dt_inconsistent(dt)

Check that a datetieme object is consistent with its time zone (some conditions can lead to have summer time set in winter, or to end up in non-existent times as when changing DST).

propertime.utilities.is_dt_ambiguous_without_offset(dt)

Check if a datetime object is specified in an ambigous way on a given time zone

propertime.utilities.now_s()

Return the current time in epoch seconds.

propertime.utilities.now_dt(tz='UTC')

Return the current time in datetime format.

propertime.utilities.dt(*args, **kwargs)

Initialize a datetime object with the time zone in the proper way. Using the standard datetime initilization leads to various problems if setting a pytz time zone.

Parameters:

  • year (int) – the year.

  • month (int) – the month.

  • day (int) – the day.

  • hour (int) – the hour, defaults to 0.

  • minute (int) – the minute, Defaults to 0.

  • second (int) – the second, Defaults to 0.

  • microsecond (int) – the microsecond, Defaults to None.

  • naive (bool) – if to create a naive (without time zone) datetime.

  • tz (tzinfo, pytz, str) – the time zone, defaults to UTC or None if naive is set.

  • offset_s (int,float) – an optional offset, in seconds.

  • trustme (bool) – if to skip sanity checks. Defaults to False.

  • guessing (bool) – if to enable guessing mode and guess in ambiguous situations.

propertime.utilities.get_tz_offset(dt)

Get the time zone offset, in seconds.

propertime.utilities.correct_dt_dst(dt)

Correct the DST of a datetime object, by re-creating it.

propertime.utilities.as_tz(dt, tz)

Get a datetime object as if it was on the given time zone.

Parameters:

  • dt (datetime) – the datetime object.

  • tz (tzinfo,pytz,str) – the time zone.

propertime.utilities.dt_from_s(s, tz='UTC')

Create a datetime object from epoch seconds. If no time zone is given, UTC is assumed.

propertime.utilities.s_from_dt(dt, tz=None)

Return the epoch seconds from a datetime object, with floating point for milliseconds/microseconds.

propertime.utilities.dt_from_str(string, tz=None)

Create a datetime object from a string.

This is a basic IS0 8601, see https://www.w3.org/TR/NOTE-datetime

Supported formats on UTC:

  1. YYYY-MM-DDThh:mm:ssZ

  2. YYYY-MM-DDThh:mm:ss.{u}Z

Supported formats with offset

  1. YYYY-MM-DDThh:mm:ss+ZZ:ZZ

  2. YYYY-MM-DDThh:mm:ss.{u}+ZZ:ZZ

Other supported formats:

  1. YYYY-MM-DDThh:mm:ss (without the trailing Z, treated as naive)

propertime.utilities.str_from_dt(dt)

Return the a string representation of a datetime object (as IS08601).

propertime.utilities.is_numerical(item)

Check if the argument is numerical.

The library logger

propertime.logger.setup(level='CRITICAL', force=False)

Setup the library logger at the given level. Checks also if such logger is already inizialized and if there are any inconsistencies between the legger levels, and force the new level if required to.

Common exceptions

exception propertime.exceptions.ConsistencyError

Bases: Exception

Raised when there is an internal consistency error.