Propertime

An attempt at proper time management in Python.

Introduction

Propertime is an attempt to implement proper time management in Python. Its approach is to fully embrace the extra complexity arising due to the intrinsic need of conflating together physical and calendar time, instead of oversimplifying or dismissing it.

Such complexity include, but is not limited to: time formats and representations, time zones, UTC offsets, daylight saving times, undefined calendar time operations and variable length time spans.

For example, while physical time (as seconds, minutes and hours) is always well-defined, calendar time (as days, weeks, months and years) entirely depends on human conventions and it is often ill-defined: the time of a day without a time zone does not make much sense, a generic day can last either 23, 24 or 25 hours depending on the daylight saving time (DST), and the result of adding a month to the 31st of January is just not defined.

In a nutshell, Propertime provides two main classes: the Time class, for representing time (similar to a datetime), and the TimeSpan class, for representing time spans (similar to a timedelta).

Such classes are implemented assuming two strict base hypotheses:

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

• Time spans can be either fixed in length (for physical time as seconds, minutes, hours) or variable (for calendar time as days, weeks, months, years). This means that the length (i.e. the duration in seconds) of a time span involving a calendar component is not defined unless put in a specific context, or in other words knowing when the time span is applied.

These two assumptions allow Propertime to adress by design many issues of time manipulation that are still present in Python's built-in datetime module as well as most third-party libraries.

Propertime provides a simple and neat API, it is relatively well tested and it plays nice with Python datetimes so that you can mix and match freely.

Implementing "proper" time comes at a price, though: the library is optimized for consistency over performance and it interfaces are quite strict.

You can get started by having a look at the example usage below, reading the quickstart notebook or checking out the API documentation.

Installing

To install Propertime, simply run pip install propertime.

It has just a few requirements, listed in the requirements.txt file, which you can use to manually install or to setup a virtualenv.

Example usage

# Time
from propertime import Time, TimeSpan

time_now = Time() # If no arguments, time is now

time = Time(1703517120.0) # Init from Epoch (UTC)

time = Time(2023,5,6,13,45) # Init datetime-like. Defaults to UTC, there is no
                            # such thing as naive time (without time zone/offset)

time = Time(2023,5,6,13,45, tz='US/Eastern') # Init datetime-like and easily
                                             # set time zone as string

time = Time(2023,11,5,1,15, tz='US/Eastern') # This is ambiguous: there are
                                             # "two" 1:15 AM on DST change

time = Time(2023,3,12,2,30, tz='US/Eastern') # This just does not exist on
                                             # US/Eastern, due to DST change

# Time spans
time_now + TimeSpan('1D') # Tomorrow same hour. Not defined when DST starts, and
                          # ambiguous when DST ends

time_now + TimeSpan('24h') # Tomorrow same hour unless applied over a DST change,
                           # where there will be a plus or minus 1 hour difference

time_now + TimeSpan('1M') # Next month same day. Not defined if the destination day
                          # does not exist (i.e. 30th of February)


# Conversions
time = Time.from_iso('2023-12-25T16:12:00+01:00') # Convert from ISO string,
                                                  # similar for datetimes

time.to_iso() # Convert to ISO string, similar for datetimes

Testing

Propertime is relatively well tested using the Python unittest module.

To run the tests, use the command python -m unittest discover in the project root.

To test against different Python versions, you can use Docker. Using Python official images and runtime requirements installation:

docker run -it -v $PWD:/Propertime python:3.9 /bin/bash -c "cd /Propertime && \
pip install -r requirements.txt && python -m unittest discover"

There is also a regression_test.sh script that tests, using Docker, from Python 3.6 to 3.13.

License

Propertime is licensed under the Apache License version 2.0. See LICENSE for the full license text.