goodtime 0.4.0__tar.gz

goodtime-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Edward Toroshchin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

goodtime-0.4.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: goodtime
+Version: 0.4.0
+Summary: A time library that prioritises clean and safe APIs.
+Author-email: Edward Toroshchin <dev@hades.name>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-Expression: MIT
+License-File: LICENSE
+Project-URL: Home, https://github.com/hades/goodtime
+
+Welcome to **goodtime**, a Python date/time library that prioritises safety and correctness.
+
+```python
+>>> from goodtime import *
+>>> Instant.now()
+Instant(unix_timestamp_ns=1770029789026987530)
+>>> Instant.now() + hours(1)
+Instant(unix_timestamp_ns=1770033404038049963)
+>>> Instant.now().to_unix_seconds()
+1770029824
+>>> Instant.from_unix_seconds(1770029824)
+Instant(unix_timestamp_ns=1770029824000000000)
+```
+
+Handling of timestamps, durations and human-readable dates and times is
+notoriously error-prone due to issues with time zones, ambiguous arithmetics,
+ambiguous units, etc. This is especially true in distributed systems, where
+interacting systems may be written by multiple teams that did not have shared
+assumptions about date/time semantics.
+
+The goal of **goodtime** is to minimise the potential for errors by:
+
+* using types that have well-defined semantics,
+* preventing ambiguous conversions (e.g. timestamp to integer),
+* providing explicit interfaces to interoperate with non-goodtime code.
+
+See package documentation for more information on provided types, operations,
+and best practices.
+
+## Getting Started
+
+Install **goodtime** from PyPI using your favourite Python package manager:
+
+```console
+$ python -m pip install goodtime
+$ poetry add goodtime
+$ uv add goodtime
+```
+
+## Contributing
+
+We are open to feedback and contributions under the terms of the MIT license.
+Feel free to open a Github issue or a pull request.

goodtime-0.4.0/README.md

@@ -0,0 +1,43 @@
+Welcome to **goodtime**, a Python date/time library that prioritises safety and correctness.
+
+```python
+>>> from goodtime import *
+>>> Instant.now()
+Instant(unix_timestamp_ns=1770029789026987530)
+>>> Instant.now() + hours(1)
+Instant(unix_timestamp_ns=1770033404038049963)
+>>> Instant.now().to_unix_seconds()
+1770029824
+>>> Instant.from_unix_seconds(1770029824)
+Instant(unix_timestamp_ns=1770029824000000000)
+```
+
+Handling of timestamps, durations and human-readable dates and times is
+notoriously error-prone due to issues with time zones, ambiguous arithmetics,
+ambiguous units, etc. This is especially true in distributed systems, where
+interacting systems may be written by multiple teams that did not have shared
+assumptions about date/time semantics.
+
+The goal of **goodtime** is to minimise the potential for errors by:
+
+* using types that have well-defined semantics,
+* preventing ambiguous conversions (e.g. timestamp to integer),
+* providing explicit interfaces to interoperate with non-goodtime code.
+
+See package documentation for more information on provided types, operations,
+and best practices.
+
+## Getting Started
+
+Install **goodtime** from PyPI using your favourite Python package manager:
+
+```console
+$ python -m pip install goodtime
+$ poetry add goodtime
+$ uv add goodtime
+```
+
+## Contributing
+
+We are open to feedback and contributions under the terms of the MIT license.
+Feel free to open a Github issue or a pull request.

goodtime-0.4.0/goodtime/__init__.py

@@ -0,0 +1,81 @@
+"""A time library that prioritises clean and safe APIs.
+
+Please read this documentation carefully to understand what **goodtime** types
+and functions do, and how to prevent most common date/time errors.
+
+The core types are Instant (representing a fixed absolute point in time on
+Earth), Duration (representing a length of time) and CivilTime (representing
+local time as used by humans).
+
+## Design
+
+The first thing to understand about how **goodtime** handles time is that the
+"absolute time" and "civil time" are explicitly treated as completely different
+(and, generally-speaking, incompatible) concepts.
+
+**Absolute time** (represented with the Instant type) is the underlying basis of
+measurement of time, as currently agreed upon practically everywhere on Earth.
+Any instantaneous event (keypress, rocket lift-off, log message) will have a
+unique absolute time as defined by the International Telecommunication Union. It
+is therefore very convenient to avoid ambiguity, and is commonly used in
+computing, communications, aviation, etc.
+
+**Civil time**, or **local time** is a measurement of time as regulated by
+civilian authorities, and is a tuple of six fields: year, month, day, hour,
+minute, second. The same tuple can have different meaning depending on the
+jurisdiction where it is interpreted. As such, it is inconvenient for
+communication and computing, but there is no way to avoid it, as most humans
+understand their civil time much better than global absolute time, and mostly
+use civil time to organise their life.
+
+## Truncation
+
+Operations that truncate the precision of values (e.g. Instant.to_unix_seconds
+or Duration.to_seconds) will round towards infinite past or negative infinite
+duration.
+"""
+
+__version__ = "0.4.0"
+
+from ._civil_time import CivilSecond, CivilTime
+from ._duration import (
+  Duration,
+  NegativeDuration,
+  PositiveDuration,
+  SignedDuration,
+  hours,
+  microseconds,
+  milliseconds,
+  minutes,
+  nanoseconds,
+  seconds,
+)
+from ._instant import Instant
+from ._timezone import (
+  CivilTimeInstant,
+  RepeatedCivilTimeInstant,
+  SkippedCivilTimeInstant,
+  Timezone,
+  UniqueCivilTimeInstant,
+)
+
+__all__ = [
+  "CivilSecond",
+  "CivilTime",
+  "CivilTimeInstant",
+  "Duration",
+  "Instant",
+  "NegativeDuration",
+  "PositiveDuration",
+  "RepeatedCivilTimeInstant",
+  "SignedDuration",
+  "SkippedCivilTimeInstant",
+  "Timezone",
+  "UniqueCivilTimeInstant",
+  "hours",
+  "microseconds",
+  "milliseconds",
+  "minutes",
+  "nanoseconds",
+  "seconds",
+]

goodtime-0.4.0/goodtime/_civil_time.py

@@ -0,0 +1,84 @@
+"""Representations for civil (local) date and time."""
+
+import dataclasses
+import datetime
+from typing import final
+
+from ._duration import Duration
+
+
+@final
+@dataclasses.dataclass(init=False, repr=False, order=True, frozen=True, slots=True)
+class CivilSecond:
+  dt: datetime.datetime
+
+  def __init__(self, *, dt: datetime.datetime):
+    if not isinstance(dt, datetime.datetime):
+      msg = f"dt must be datetime.datetime, was {type(dt)}"
+      raise TypeError(msg)
+    if dt.tzinfo is not datetime.timezone.utc:
+      msg = f"dt must have tzinfo=datetime.timezone.utc, was {dt.tzinfo!r}"
+      raise ValueError(msg)
+    object.__setattr__(self, "dt", dt)
+
+  @classmethod
+  def from_utc_datetime(cls, dt: datetime.datetime) -> "CivilSecond":
+    return CivilSecond(dt=dt)
+
+  @classmethod
+  def from_fields(cls, year: int, month: int, day: int, hour: int, minute: int, second: int) -> "CivilSecond":  # noqa: PLR0913
+    return CivilSecond(
+      dt=datetime.datetime(
+        year=year,
+        month=month,
+        day=day,
+        hour=hour,
+        minute=minute,
+        second=second,
+        tzinfo=datetime.timezone.utc,
+      )
+    )
+
+  @property
+  def year(self) -> int:
+    return self.dt.year
+
+  @property
+  def month(self) -> int:
+    return self.dt.month
+
+  @property
+  def day(self) -> int:
+    return self.dt.day
+
+  @property
+  def hour(self) -> int:
+    return self.dt.hour
+
+  @property
+  def minute(self) -> int:
+    return self.dt.minute
+
+  @property
+  def second(self) -> int:
+    return self.dt.second
+
+
+@final
+@dataclasses.dataclass(init=False, repr=True, order=True, frozen=True, slots=True)
+class CivilTime:
+  second: CivilSecond
+  subsecond: Duration
+
+  def __init__(self, *, second: CivilSecond, subsecond: Duration):
+    if not isinstance(subsecond, Duration):
+      msg = f"subsecond_ns must be Duration, was {type(subsecond)}"
+      raise TypeError(msg)
+    if not isinstance(second, CivilSecond):
+      msg = f"second must be CivilSecond, was {type(second)}"
+      raise TypeError(msg)
+    if not (0 <= subsecond.to_nanos() < 1_000_000_000):  # noqa: PLR2004
+      msg = f"subsecond must be in [0, 1_000_000_000)ns, was {subsecond.to_nanos()}ns"
+      raise ValueError(msg)
+    object.__setattr__(self, "second", second)
+    object.__setattr__(self, "subsecond", subsecond)

goodtime-0.4.0/goodtime/_duration.py

@@ -0,0 +1,385 @@
+"""Durations represent finite lengths of time."""
+
+import dataclasses
+import datetime
+from typing import final
+
+
+@final
+@dataclasses.dataclass(init=False, repr=True, order=True, frozen=True, slots=True)
+class Duration:
+  """Duration represents a fixed length of time with nanosecond precision.
+
+  The Duration values can be constructed using factory functions (from_nanos,
+  from_micros, from_millis and from_seconds) and can be used for unit
+  arithmetics, e.g.  adding or subtracting from each other and to/from the
+  Instant values.
+
+  Unlike SignedDuration, the length of time is always non-negative. It is therefore
+  useful for measuring, for example, the amount of time a request or a computation took
+  place, or to set a timeout.
+
+  Python operators (comparison, hashing, addition, subtraction) are supported
+  naturally. Note that subtracting another Duration results in a SignedDuration.
+
+  It is recommended to use this (or SignedDuration) type in all APIs (fields,
+  function signatures) instead of raw integers to avoid ambiguity. Use explicit
+  conversion functions at the boundary of your code to interoperate with
+  non-goodtime libraries and APIs.
+  """
+
+  ns: int
+
+  def __init__(self, *, ns: int):
+    """Create an instance of Duration from non-negative amount of nanoseconds.
+
+    To improve readability it is recommended to use the explicit factory functions (from_nanos
+    from_micros, from_millis and from_seconds) instead.
+    """
+    if not isinstance(ns, int):
+      msg = f"ns must be int, was {type(ns)}"
+      raise TypeError(msg)
+    if ns < 0:
+      msg = f"ns must be non-negative, was {ns}"
+      raise ValueError(msg)
+    object.__setattr__(self, "ns", ns)
+
+  @classmethod
+  def from_nanos(cls, value: int) -> "Duration":
+    """Create an instance of Duration from non-negative amount of nanoseconds."""
+    return cls(ns=value)
+
+  @classmethod
+  def from_micros(cls, value: int) -> "Duration":
+    """Create an instance of Duration from non-negative amount of microseconds."""
+    return cls(ns=value * 1000)
+
+  @classmethod
+  def from_millis(cls, value: int) -> "Duration":
+    """Create an instance of Duration from non-negative amount of milliseconds."""
+    return cls(ns=value * 1_000_000)
+
+  @classmethod
+  def from_seconds(cls, value: int) -> "Duration":
+    """Create an instance of Duration from non-negative amount of seconds."""
+    return cls(ns=value * 1_000_000_000)
+
+  def to_nanos(self) -> int:
+    """Return the duration as integer amount of nanoseconds."""
+    return self.ns
+
+  def to_micros(self) -> int:
+    """Return the duration as integer amount of microseconds, rounding towards zero."""
+    return self.ns // 1000
+
+  def to_millis(self) -> int:
+    """Return the duration as integer amount of milliseconds, rounding towards zero."""
+    return self.ns // 1_000_000
+
+  def to_seconds(self) -> int:
+    """Return the duration as integer amount of seconds, rounding towards zero."""
+    return self.ns // 1_000_000_000
+
+  def to_timedelta(self) -> datetime.timedelta:
+    """Return the duration as Python timedelta value, rounding towards zero."""
+    return datetime.timedelta(microseconds=self.to_micros())
+
+  def __add__(self, other: "Duration") -> "Duration":
+    if not isinstance(other, Duration):
+      return NotImplemented
+    return Duration(ns=self.ns + other.ns)
+
+  def __sub__(self, other: "Duration") -> "SignedDuration":
+    if not isinstance(other, Duration):
+      return NotImplemented
+    return SignedDuration.from_nanos(self.ns - other.ns)
+
+
+@dataclasses.dataclass(init=False, repr=False, order=False, frozen=True, slots=True)
+class SignedDuration:
+  """SignedDuration represents a fixed length of time with nanosecond precision.
+
+  The SignedDuration values can be constructed using factory functions (from_nanos,
+  from_micros, from_millis and from_seconds) or convenience helper functions
+  (hours, minutes, seconds, etc.) and can be used for unit arithmetics, e.g.
+  adding or subtracting from each other and to/from the Instant values.
+
+  Do not use SignedDuration constructor directly. SignedDuration is meant as a
+  union type, and may be updated in the future to prevent incorrect usage.
+
+  Unlike Duration, the length of time can be negative. This makes it useful for
+  unit arithmetics, while simultaneously preventing the user from accidentally
+  using a negative duration where it does not make sense, such as timeouts.
+
+  To extract Duration from SignedDuration, check whether your value is an
+  instance of PositiveDuration or NegativeDuration. A `match` operator provides
+  a concise syntax for this:
+
+      >>> def print_duration(d: Duration) -> None:
+      ...  match d:
+      ...   case PositiveDuration(p):
+      ...    print(f"{p.to_seconds()}s")
+      ...   case NegativeDuration(n):
+      ...    print(f"-{n.to_seconds()}s")
+      ...
+      >>> print_duration(hours(2))
+      7200s
+      >>> print_duration(hours(-2))
+      -7200s
+
+  Python operators (comparison, hashing, addition, subtraction) are supported
+  naturally. Note that adding a SignedDuration to a Duration results in a
+  SignedDuration.
+
+  It is recommended to use this (or Duration) type in all APIs (fields, function
+  signatures) instead of raw integers to avoid ambiguity. Use explicit
+  conversion functions at the boundary of your code to interoperate with
+  non-goodtime libraries and APIs.
+  """
+
+  absolute_value: Duration
+
+  def __init__(self, absolute_value: Duration):
+    """Use only in subclasses of SignedDuration."""
+    if not isinstance(absolute_value, Duration):
+      msg = f"absolute_value must be Duration, was {type(absolute_value)}"
+      raise TypeError(msg)
+    object.__setattr__(self, "absolute_value", absolute_value)
+
+  @classmethod
+  def from_timedelta(cls, value: datetime.timedelta) -> "SignedDuration":
+    """Create an instance of SignedDuration from a Python timedelta value."""
+    if not isinstance(value, datetime.timedelta):
+      msg = f"value must be datetime.timedelta, was {type(value)}"
+      raise TypeError(msg)
+    if value.days >= 0:
+      return PositiveDuration(Duration.from_micros(value // datetime.timedelta(microseconds=1)))
+    return NegativeDuration(Duration.from_micros(value // datetime.timedelta(microseconds=-1)))
+
+  @classmethod
+  def from_nanos(cls, value: int) -> "SignedDuration":
+    """Create an instance of SignedDuration from integer amount of nanoseconds."""
+    if value > 0:
+      return PositiveDuration(Duration(ns=value))
+    return NegativeDuration(Duration(ns=-value))
+
+  @classmethod
+  def from_micros(cls, value: int) -> "SignedDuration":
+    """Create an instance of SignedDuration from integer amount of microseconds."""
+    if value > 0:
+      return PositiveDuration(Duration(ns=value * 1000))
+    return NegativeDuration(Duration(ns=-value * 1000))
+
+  @classmethod
+  def from_millis(cls, value: int) -> "SignedDuration":
+    """Create an instance of SignedDuration from integer amount of milliseconds."""
+    if value > 0:
+      return PositiveDuration(Duration(ns=value * 1_000_000))
+    return NegativeDuration(Duration(ns=-value * 1_000_000))
+
+  @classmethod
+  def from_seconds(cls, value: int) -> "SignedDuration":
+    """Create an instance of SignedDuration from integer amount of seconds."""
+    if value > 0:
+      return PositiveDuration(Duration(ns=value * 1_000_000_000))
+    return NegativeDuration(Duration(ns=-value * 1_000_000_000))
+
+  def to_timedelta(self) -> datetime.timedelta:
+    """Return the duration as Python timedelta value, rounding towards negative infinity."""
+    raise NotImplementedError
+
+  def __ge__(self, other: "SignedDuration|Duration") -> bool:
+    return NotImplemented
+
+  def __gt__(self, other: "SignedDuration|Duration") -> bool:
+    return NotImplemented
+
+  def __le__(self, other: "SignedDuration|Duration") -> bool:
+    return NotImplemented
+
+  def __lt__(self, other: "SignedDuration|Duration") -> bool:
+    return NotImplemented
+
+
+@final
+class PositiveDuration(SignedDuration):
+  def __repr__(self) -> str:
+    return f"PositiveDuration({self.absolute_value!r})"
+
+  @classmethod
+  def from_nanos(cls, _value: int) -> SignedDuration:
+    msg = "Calling PositiveDuration.from_nanos is not supported. Call SignedDuration.from_nanos instead."
+    raise TypeError(msg)
+
+  @classmethod
+  def from_micros(cls, _value: int) -> SignedDuration:
+    msg = "Calling PositiveDuration.from_micros is not supported. Call SignedDuration.from_micros instead."
+    raise TypeError(msg)
+
+  @classmethod
+  def from_millis(cls, _value: int) -> SignedDuration:
+    msg = "Calling PositiveDuration.from_millis is not supported. Call SignedDuration.from_millis instead."
+    raise TypeError(msg)
+
+  @classmethod
+  def from_seconds(cls, _value: int) -> SignedDuration:
+    msg = "Calling PositiveDuration.from_seconds is not supported. Call SignedDuration.from_seconds instead."
+    raise TypeError(msg)
+
+  def to_timedelta(self) -> datetime.timedelta:
+    return datetime.timedelta(microseconds=self.absolute_value.to_micros())
+
+  def __add__(self, other: SignedDuration | Duration) -> SignedDuration:
+    match other:
+      case Duration(ns=other_ns) | PositiveDuration(Duration(ns=other_ns)):
+        return SignedDuration.from_nanos(self.absolute_value.ns + other_ns)
+      case NegativeDuration(Duration(ns=other_negative_ns)):
+        return SignedDuration.from_nanos(self.absolute_value.ns - other_negative_ns)
+    return NotImplemented
+
+  def __radd__(self, other: Duration) -> SignedDuration:
+    return self.__add__(other)
+
+  def __sub__(self, other: SignedDuration | Duration) -> SignedDuration:
+    match other:
+      case Duration(ns=other_ns) | PositiveDuration(Duration(ns=other_ns)):
+        return SignedDuration.from_nanos(self.absolute_value.ns - other_ns)
+      case NegativeDuration(Duration(ns=other_negative_ns)):
+        return SignedDuration.from_nanos(self.absolute_value.ns + other_negative_ns)
+    return NotImplemented
+
+  def __rsub__(self, other: Duration) -> SignedDuration:
+    if not isinstance(other, Duration):
+      return NotImplemented
+    return SignedDuration.from_nanos(other.ns - self.absolute_value.ns)
+
+  def __le__(self, other: SignedDuration | Duration) -> bool:
+    match other:
+      case Duration(ns=other_ns) | PositiveDuration(Duration(ns=other_ns)):
+        return self.absolute_value.ns <= other_ns
+      case NegativeDuration(Duration(ns=other_negative_ns)):
+        return self.absolute_value.ns <= -other_negative_ns
+    return NotImplemented
+
+  def __gt__(self, other: SignedDuration | Duration) -> bool:
+    result = self.__le__(other)
+    return NotImplemented if result is NotImplemented else not result
+
+  def __lt__(self, other: SignedDuration | Duration) -> bool:
+    match other:
+      case Duration(ns=other_ns) | PositiveDuration(Duration(ns=other_ns)):
+        return self.absolute_value.ns < other_ns
+      case NegativeDuration(Duration(ns=other_negative_ns)):
+        return self.absolute_value.ns < -other_negative_ns
+    return NotImplemented
+
+  def __ge__(self, other: SignedDuration | Duration) -> bool:
+    result = self.__lt__(other)
+    return NotImplemented if result is NotImplemented else not result
+
+
+@final
+class NegativeDuration(SignedDuration):
+  def __repr__(self) -> str:
+    return f"NegativeDuration({self.absolute_value!r})"
+
+  @classmethod
+  def from_nanos(cls, _value: int) -> SignedDuration:
+    msg = "Calling NegativeDuration.from_nanos is not supported. Call SignedDuration.from_nanos instead."
+    raise TypeError(msg)
+
+  @classmethod
+  def from_micros(cls, _value: int) -> SignedDuration:
+    msg = "Calling NegativeDuration.from_micros is not supported. Call SignedDuration.from_micros instead."
+    raise TypeError(msg)
+
+  @classmethod
+  def from_millis(cls, _value: int) -> SignedDuration:
+    msg = "Calling NegativeDuration.from_millis is not supported. Call SignedDuration.from_millis instead."
+    raise TypeError(msg)
+
+  @classmethod
+  def from_seconds(cls, _value: int) -> SignedDuration:
+    msg = "Calling NegativeDuration.from_seconds is not supported. Call SignedDuration.from_seconds instead."
+    raise TypeError(msg)
+
+  def to_timedelta(self) -> datetime.timedelta:
+    return datetime.timedelta(microseconds=-self.absolute_value.to_micros())
+
+  def __add__(self, other: SignedDuration | Duration) -> SignedDuration:
+    match other:
+      case Duration(ns=other_ns) | PositiveDuration(Duration(ns=other_ns)):
+        return SignedDuration.from_nanos(-self.absolute_value.ns + other_ns)
+      case NegativeDuration(Duration(ns=other_negative_ns)):
+        return SignedDuration.from_nanos(-self.absolute_value.ns - other_negative_ns)
+    return NotImplemented
+
+  def __radd__(self, other: Duration) -> SignedDuration:
+    return self.__add__(other)
+
+  def __sub__(self, other: SignedDuration | Duration) -> SignedDuration:
+    match other:
+      case Duration(ns=other_ns) | PositiveDuration(Duration(ns=other_ns)):
+        return SignedDuration.from_nanos(-self.absolute_value.ns - other_ns)
+      case NegativeDuration(Duration(ns=other_negative_ns)):
+        return SignedDuration.from_nanos(-self.absolute_value.ns + other_negative_ns)
+    return NotImplemented
+
+  def __rsub__(self, other: Duration) -> SignedDuration:
+    if not isinstance(other, Duration):
+      return NotImplemented
+    return SignedDuration.from_nanos(other.ns + self.absolute_value.ns)
+
+  def __le__(self, other: SignedDuration | Duration) -> bool:
+    match other:
+      case Duration(ns=other_ns) | PositiveDuration(Duration(ns=other_ns)):
+        return -self.absolute_value.ns <= other_ns
+      case NegativeDuration(Duration(ns=other_negative_ns)):
+        return -self.absolute_value.ns <= -other_negative_ns
+    return NotImplemented
+
+  def __gt__(self, other: SignedDuration | Duration) -> bool:
+    result = self.__le__(other)
+    return NotImplemented if result is NotImplemented else not result
+
+  def __lt__(self, other: SignedDuration | Duration) -> bool:
+    match other:
+      case Duration(ns=other_ns) | PositiveDuration(Duration(ns=other_ns)):
+        return -self.absolute_value.ns < other_ns
+      case NegativeDuration(Duration(ns=other_negative_ns)):
+        return -self.absolute_value.ns < -other_negative_ns
+    return NotImplemented
+
+  def __ge__(self, other: SignedDuration | Duration) -> bool:
+    result = self.__lt__(other)
+    return NotImplemented if result is NotImplemented else not result
+
+
+def hours(n: int) -> SignedDuration:
+  """Create an instance of SignedDuration from integer amount of hours."""
+  return SignedDuration.from_seconds(n * 3600)
+
+
+def minutes(n: int) -> SignedDuration:
+  """Create an instance of SignedDuration from integer amount of minutes."""
+  return SignedDuration.from_seconds(n * 60)
+
+
+def seconds(n: int) -> SignedDuration:
+  """Create an instance of SignedDuration from integer amount of seconds."""
+  return SignedDuration.from_seconds(n)
+
+
+def milliseconds(n: int) -> SignedDuration:
+  """Create an instance of SignedDuration from integer amount of milliseconds."""
+  return SignedDuration.from_millis(n)
+
+
+def microseconds(n: int) -> SignedDuration:
+  """Create an instance of SignedDuration from integer amount of microseconds."""
+  return SignedDuration.from_micros(n)
+
+
+def nanoseconds(n: int) -> SignedDuration:
+  """Create an instance of SignedDuration from integer amount of nanoseconds."""
+  return SignedDuration.from_nanos(n)

goodtime-0.4.0/goodtime/_instant.py

@@ -0,0 +1,110 @@
+"""Instants represent fixed points in time."""
+
+import dataclasses
+import time
+from typing import final, overload
+
+from ._duration import Duration, NegativeDuration, PositiveDuration, SignedDuration
+
+
+@final
+@dataclasses.dataclass(init=False, repr=True, order=True, frozen=True, slots=True)
+class Instant:
+  """Instant represents a specific absolute instant in time on Earth.
+
+  Values can be created using the now() function or the factory functions
+  (from_unix_nanos, from_unix_micros, from_unix_millis, from_unix_seconds).
+
+  Instant has absolutely no understanding of leap seconds. If your system does
+  not implement leap second smearing, you may encounter "jumps" or "skips" in
+  the value of Instant that can lead to errors. Additionally, calculating the
+  length of time between two Instants does not represent the real physical
+  amount of time passed whenever leap seconds have been inserted or removed.
+
+  It is recommended to use the values of Instant type everywhere in your code,
+  including fields and function signatures. Use explicit conversion functions at
+  the boundary of your code to interoperate with non-goodtime libraries and
+  APIs.
+  """
+
+  unix_timestamp_ns: int
+
+  def __init__(self, *, unix_timestamp_ns: int):
+    """Construct a value of Instant from UNIX timestamp in nanoseconds.
+
+    For readability it is recommended to use the explicit factory functions
+    (from_unix_nanos, from_unix_micros, from_unix_millis, from_unix_seconds)
+    instead.
+    """
+    if not isinstance(unix_timestamp_ns, int):
+      msg = f"unix_timestamp_ns must be int, was {type(unix_timestamp_ns)}"
+      raise TypeError(msg)
+    object.__setattr__(self, "unix_timestamp_ns", unix_timestamp_ns)
+
+  @classmethod
+  def from_unix_nanos(cls, value: int) -> "Instant":
+    """Create an Instant value from UNIX timestamp in nanoseconds."""
+    return cls(unix_timestamp_ns=value)
+
+  @classmethod
+  def from_unix_micros(cls, value: int) -> "Instant":
+    """Create an Instant value from UNIX timestamp in microseconds."""
+    return cls(unix_timestamp_ns=value * 1000)
+
+  @classmethod
+  def from_unix_millis(cls, value: int) -> "Instant":
+    """Create an Instant value from UNIX timestamp in milliseconds."""
+    return cls(unix_timestamp_ns=value * 1_000_000)
+
+  @classmethod
+  def from_unix_seconds(cls, value: int) -> "Instant":
+    """Create an Instant value from UNIX timestamp in seconds."""
+    return cls(unix_timestamp_ns=value * 1_000_000_000)
+
+  @classmethod
+  def now(cls) -> "Instant":
+    """Create an Instant representing the current time."""
+    return cls(unix_timestamp_ns=time.time_ns())
+
+  def to_unix_nanos(self) -> int:
+    """Return the value of this Instant as UNIX timestamp in nanoseconds."""
+    return self.unix_timestamp_ns
+
+  def to_unix_micros(self) -> int:
+    """Return the value of this Instant as UNIX timestamp in microseconds, rounding towards infinite past."""
+    return self.unix_timestamp_ns // 1000
+
+  def to_unix_millis(self) -> int:
+    """Return the value of this Instant as UNIX timestamp in milliseconds, rounding towards infinite past."""
+    return self.unix_timestamp_ns // 1_000_000
+
+  def to_unix_seconds(self) -> int:
+    """Return the value of this Instant as UNIX timestamp in seconds, rounding towards infinite past."""
+    return self.unix_timestamp_ns // 1_000_000_000
+
+  def __add__(self, other: Duration | SignedDuration) -> "Instant":
+    match other:
+      case Duration(ns=delta) | PositiveDuration(Duration(ns=delta)):
+        return Instant.from_unix_nanos(self.unix_timestamp_ns + delta)
+      case NegativeDuration(Duration(ns=negative_delta)):
+        return Instant.from_unix_nanos(self.unix_timestamp_ns - negative_delta)
+    return NotImplemented
+
+  def __radd__(self, other: Duration | SignedDuration) -> "Instant":
+    return self.__add__(other)
+
+  @overload
+  def __sub__(self, other: "Instant") -> SignedDuration: ...
+
+  @overload
+  def __sub__(self, other: Duration | SignedDuration) -> "Instant": ...
+
+  def __sub__(self, other: "Instant|Duration|SignedDuration") -> "Instant|SignedDuration":
+    match other:
+      case Duration(ns=delta) | PositiveDuration(Duration(ns=delta)):
+        return Instant.from_unix_nanos(self.unix_timestamp_ns - delta)
+      case NegativeDuration(Duration(ns=negative_delta)):
+        return Instant.from_unix_nanos(self.unix_timestamp_ns + negative_delta)
+      case Instant(unix_timestamp_ns=other_timestamp_ns):
+        return SignedDuration.from_nanos(self.unix_timestamp_ns - other_timestamp_ns)
+    return NotImplemented

goodtime-0.4.0/goodtime/_timezone.py

@@ -0,0 +1,164 @@
+"""Representations for time zones."""
+
+import dataclasses
+import datetime
+import zoneinfo
+
+from ._civil_time import CivilSecond, CivilTime
+from ._duration import Duration
+from ._instant import Instant
+
+
+@dataclasses.dataclass(frozen=True, repr=True, init=True, slots=True, eq=True)
+class UniqueCivilTimeInstant:
+  """Civil time that has been uniquely mapped to an absolute instant.
+
+  This will be the result of Timezone.civil_time_to_instant most of the time
+  (i.e. except DST transitions).
+  """
+
+  instant: Instant
+
+
+@dataclasses.dataclass(frozen=True, repr=True, init=True, slots=True, eq=True)
+class RepeatedCivilTimeInstant:
+  """Civil time that happens twice due to DST transitions.
+
+  When Daylight Savings Time ends, the civil wall clock will display time that
+  it has already displayed before. It is therefore impossible to uniquely
+  identify the exact absolute instant of when the provided civil time was
+  observed.
+
+  Two possible options are pre_transition (civil time was observed before the
+  DST ended) and post_transition (after the DST ended). The instant of the
+  transition itself is returned in the transition field.
+  """
+
+  pre_transition: Instant
+  post_transition: Instant
+  transition: Instant
+
+
+@dataclasses.dataclass(frozen=True, repr=True, init=True, slots=True, eq=True)
+class SkippedCivilTimeInstant:
+  """Civil time that was (or will be) skipped.
+
+  When Daylight Savings Time begins, the civil wall clock will skip certain
+  times. The provided civil time never happened (and never will happen).
+
+  For convenience, the instant of the transition itself is returned, as well as
+  instants when two hypothetical incorrect wall clocks would have shown the
+  provided civil time: pre_transition (wall clock that was not updated for the
+  DST), and post_transition (wall clock that was updated for the DST too early).
+  """
+
+  pre_transition: Instant
+  post_transition: Instant
+  transition: Instant
+
+
+CivilTimeInstant = UniqueCivilTimeInstant | RepeatedCivilTimeInstant | SkippedCivilTimeInstant
+
+
+@dataclasses.dataclass(frozen=True, repr=True, order=False, slots=True, eq=False)
+class Timezone:
+  """A Timezone represents a geographical region with identical civil time.
+
+  This is not the same as a UTC offset, since multiple regions have different
+  UTC offsets throughout the year (such as offsets for standard time and
+  daylight saving time).
+
+  To construct an instance of Timezone, use the from_tzdata_identifier factory
+  function.
+  """
+
+  tzinfo: datetime.tzinfo
+
+  @classmethod
+  def from_tzdata_identifier(cls, identifier: str) -> "Timezone":
+    """Construct a Timezone instance from a string identifier.
+
+    This identifier is also known as tzdata identifier, zoneinfo identifier or
+    IANA time zone. Examples are "America/Los_Angeles" and "Europe/Berlin".
+    """
+    return Timezone(zoneinfo.ZoneInfo(identifier))
+
+  def instant_to_civil_time(self, instant: Instant) -> CivilTime:
+    """Return the civil time for this timezone at a certain instant."""
+    seconds, nanoseconds = divmod(instant.to_unix_nanos(), 1_000_000_000)
+    dt = datetime.datetime.fromtimestamp(seconds, tz=datetime.timezone.utc).astimezone(self.tzinfo)
+    dt = datetime.datetime(
+      year=dt.year,
+      month=dt.month,
+      day=dt.day,
+      hour=dt.hour,
+      minute=dt.minute,
+      second=dt.second,
+      tzinfo=datetime.timezone.utc,
+    )
+    return CivilTime(second=CivilSecond.from_utc_datetime(dt), subsecond=Duration.from_nanos(nanoseconds))
+
+  def civil_time_to_instant(self, civil_time: CivilTime) -> CivilTimeInstant:
+    """Return the absolute instant when a given civil time was observed in this timezone.
+
+    When a civil time is repeated or skipped due to DST transitions, returns times calculated
+    before and after the transition, as well as the transition time itself.
+    """
+    utc_ts = int(
+      datetime.datetime(
+        year=civil_time.second.year,
+        month=civil_time.second.month,
+        day=civil_time.second.day,
+        hour=civil_time.second.hour,
+        minute=civil_time.second.minute,
+        second=civil_time.second.second,
+        tzinfo=datetime.timezone.utc,
+      ).timestamp()
+    )
+    offsets: list[tuple[int, int]] = []
+    for ts in range(utc_ts - 38 * 3600, utc_ts + 38 * 3600):
+      offset_td = datetime.datetime.fromtimestamp(ts, tz=self.tzinfo).utcoffset()
+      if not offset_td:
+        continue
+      offset = int(offset_td.total_seconds())
+      if not offsets or offsets[-1][0] != offset:
+        offsets.append((offset, ts))
+    if not offsets:
+      msg = (
+        "Unable to look up Instant based on given time zone and civil_time: tzinfo {self.tzinfo!r} did not "
+        "return UTC offsets as expected."
+      )
+      raise ValueError(msg)
+    if len(offsets) == 1:
+      return UniqueCivilTimeInstant(Instant.from_unix_seconds(utc_ts - offsets[0][0]) + civil_time.subsecond)
+    if len(offsets) > 2:  # noqa: PLR2004
+      msg = (
+        "Unable to look up Instant based on given time zone and civil_time: tzinfo {self.tzinfo!r} returned "
+        "too many different UTC offsets around the expected time."
+      )
+      raise ValueError(msg)
+    transition_ts = offsets[1][1]
+    pre_ts = utc_ts - offsets[0][0]
+    post_ts = utc_ts - offsets[1][0]
+    is_pre_ts_valid = pre_ts < transition_ts
+    is_post_ts_valid = post_ts >= transition_ts
+    match (is_pre_ts_valid, is_post_ts_valid):
+      case (True, True):
+        return RepeatedCivilTimeInstant(
+          Instant.from_unix_seconds(pre_ts) + civil_time.subsecond,
+          Instant.from_unix_seconds(post_ts) + civil_time.subsecond,
+          Instant.from_unix_seconds(transition_ts),
+        )
+      case (True, False):
+        return UniqueCivilTimeInstant(
+          Instant.from_unix_seconds(pre_ts) + civil_time.subsecond,
+        )
+      case (False, True):
+        return UniqueCivilTimeInstant(
+          Instant.from_unix_seconds(post_ts) + civil_time.subsecond,
+        )
+    return SkippedCivilTimeInstant(
+      Instant.from_unix_seconds(pre_ts) + civil_time.subsecond,
+      Instant.from_unix_seconds(post_ts) + civil_time.subsecond,
+      Instant.from_unix_seconds(transition_ts),
+    )

goodtime-0.4.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+authors = [{name = "Edward Toroshchin", email = "dev@hades.name"}]
+dependencies = []
+dynamic = ["version", "description"]
+license = "MIT"
+license-files = ["LICENSE"]
+name = "goodtime"
+readme = "README.md"
+requires-python = ">=3.10"
+
+[build-system]
+requires = ["flit_core >=3.11,<4"]
+build-backend = "flit_core.buildapi"
+
+[project.urls]
+Home = "https://github.com/hades/goodtime"
+
+[dependency-groups]
+dev = [
+  "mypy>=1.19.1",
+  "pytest>=9.0.2",
+  "pytest-cov>=7.0.0",
+  "ruff>=0.14.14",
+]
+
+[tool.mypy]
+strict = true
+
+[tool.ruff]
+line-length = 120
+indent-width = 2
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  "COM812",  # missing-trailing-comma
+  "COM819",  # prohibited-trailing-comma
+  "D203",    # incorrect-blank-line-before-class
+  "D213",    # multi-line-summary-second-line
+  "TRY003",  # raise-vanilla-args
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+  "ANN",
+  "D",
+  "PLR",
+  "S",
+]
+
+[tool.ruff.lint.flake8-annotations]
+mypy-init-return = true