Skip to content

Commit

Permalink
Rephrased some parts of the README intro and PyPI description.
Browse files Browse the repository at this point in the history
  • Loading branch information
sarusso committed Dec 2, 2024
1 parent a26fad8 commit 375c6e0
Show file tree
Hide file tree
Showing 2 changed files with 12 additions and 14 deletions.
20 changes: 9 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,27 +7,25 @@ An attempt at proper time management in Python.
## Introduction


Propertime is an attempt at implementing proper time management in Python, by fully embracing the extra complications arising due to the intrinsic need of conflating together physical and calendar time, instead of neglecting them.
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.

These include, but are not limited to: time formats and representations, time zones, UTC offsets, daylight saving times, undefined calendar time operations and variable length time spans.
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 (seconds, minutes and hours) is always well-defined, calendar time (days, weeks, months and years) is entirely dependent 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) switch, and the result of adding a month to the 31st of January is just not defined.
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.

Propertime tries to embrace such complexity and eliminate ambiguity without overcomplicating the code or its interfaces, with the intent of providing a viable solution for common time management challenges.

In a nutshell, it 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).
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 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.
- **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 of fixed length (for physical time as seconds, minutes, hours) and of *variable* length (for calendar time as days, weeks, months, years). This means that the length (i.e. the duration in seconds) of a time span involving calendar components is not defined *unless* it is put in a specific context, or in other words knowing when it is applied.
- **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.
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 and use it only when needed.
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 its interfaces are quite strict. Whether it is a suitable solution for you or not, it heavily depends on your use case.
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](Quickstart.ipynb) or checking out the [API documentation](https://propertime.readthedocs.io).

Expand Down
6 changes: 3 additions & 3 deletions setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
version='1.0.0',
description='An attempt at proper time management in Python.',
long_description="""
Propertime is an attempt at implementing proper time management in Python,
by fully embracing the extra complications arising due to the intrinsic need of
conflating together physical and calendar time, instead of neglecting them.
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.
In a nutshell, it provides two main classes: the ``Time`` class for representing
time (similar to a datetime) and the ``TimeSpan`` class for representing units
Expand Down

0 comments on commit 375c6e0

Please sign in to comment.