isoperiod 1.2.1__py3-none-any.whl

isoperiod/__init__.py

@@ -0,0 +1,17 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("isoperiod")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+
+from isoperiod.exceptions import PeriodError, PeriodParsingError, PeriodValidationError
+from isoperiod.periods import Period
+
+__all__ = [
+    "Period",
+    "PeriodError",
+    "PeriodParsingError",
+    "PeriodValidationError",
+]

isoperiod/enums.py

@@ -0,0 +1,13 @@
+from enum import IntEnum
+
+
+class Step(IntEnum):
+    """The fundamental units of a Period.
+
+    A Period's duration is always some multiplier of one of these steps, e.g. a 15-minute period is 900 seconds,
+    a 1-year period is 12 months.
+    """
+
+    MICROSECONDS = 1
+    SECONDS = 2
+    MONTHS = 3

isoperiod/exceptions.py

@@ -0,0 +1,25 @@
+from isoperiod.enums import Step
+
+
+class PeriodError(Exception):
+    """Base exception for all period-related errors."""
+
+
+class PeriodParsingError(PeriodError):
+    """Raised when things like a period string or timedelta cannot be parsed."""
+
+
+class PeriodValidationError(PeriodError):
+    """Raised when a validation on objects in the Period module fails."""
+
+
+def illegal_step(step: int) -> PeriodValidationError:
+    """Build the error raised when a Step value is not one of the three legal steps.
+
+    Args:
+        step: The offending step value
+
+    Returns:
+        A PeriodValidationError, for the caller to raise
+    """
+    return PeriodValidationError(f"Illegal step: '{step}'. Must be one of: {list(Step)}")

isoperiod/iso.py

@@ -0,0 +1,233 @@
+"""Helpers for building ISO 8601 duration strings and the regex fragment used to parse ISO 8601 durations."""
+
+import datetime as dt
+
+from isoperiod.exceptions import PeriodParsingError
+
+
+def period_regex(prefix: str) -> str:
+    """Return a regular expression string for matching an ISO 8601 duration (but without the initial "P" character)
+
+    Args:
+        prefix: The name prefix used for Python regex group names
+
+    Returns:
+        A string containing a regular expression that can be used to parse an ISO 8601 duration
+    """
+    return (
+        rf"(?:(?P<{prefix}_years>\d+)[Yy])?"
+        rf"(?:(?P<{prefix}_months>\d+)[Mm])?"
+        rf"(?:(?P<{prefix}_days>\d+)[Dd])?"
+        r"(?:[Tt]"
+        rf"(?:(?P<{prefix}_hours>\d+)[Hh])?"
+        rf"(?:(?P<{prefix}_minutes>\d+)[Mm])?"
+        rf"(?:(?P<{prefix}_seconds>\d+)"
+        rf"(?:\.(?P<{prefix}_microseconds>\d{{1,6}}))?"
+        r"[Ss])?"
+        r")?"
+    )
+
+
+def second_string(seconds: int, microseconds: int) -> str:
+    """Convert seconds and microseconds (0-999_999) to a string that can be used to format an ISO 8601 duration string.
+
+    Args:
+        seconds: The number of seconds
+        microseconds: The number of microseconds
+
+    Returns:
+        A string representing seconds and microseconds that can be used in an ISO 8601 duration string
+
+    Examples:
+        >>> second_string(30, 0)
+        '30'
+        >>> second_string(1, 500_000)
+        '1.5'
+        >>> second_string(10, 123_400)
+        '10.1234'
+    """
+    if microseconds == 0:
+        return str(seconds)
+    return f"{seconds}.{microseconds:06}".rstrip("0")
+
+
+def append_second_elems(elems: list[str], seconds: int, microseconds: int) -> list[str]:
+    """Append total seconds and microseconds to a list of strings that, when joined, produce an ISO 8601 duration
+    string.
+
+    Args:
+        elems: The list of strings
+        seconds: The number of seconds
+        microseconds: The number of microseconds
+
+    Returns:
+        The amended list of strings
+
+    Examples (joining the result of appending onto ``["P"]``):
+        >>> "".join(append_second_elems(["P"], 90, 0))
+        'PT1M30S'
+        >>> "".join(append_second_elems(["P"], 90_061, 0))
+        'P1DT1H1M1S'
+        >>> "".join(append_second_elems(["P"], 0, 500_000))
+        'PT0.5S'
+    """
+    days, seconds_in_day = divmod(seconds, 86_400)
+    if days > 0:
+        elems.append(f"{days}D")
+    if (seconds_in_day > 0) or (microseconds > 0):
+        elems.append("T")
+        hours, seconds_in_hour = divmod(seconds_in_day, 3_600)
+        if hours > 0:
+            elems.append(f"{hours}H")
+        minutes, seconds_in_minute = divmod(seconds_in_hour, 60)
+        if minutes > 0:
+            elems.append(f"{minutes}M")
+        if (seconds_in_minute > 0) or (microseconds > 0):
+            elems.append(second_string(seconds_in_minute, microseconds))
+            elems.append("S")
+    return elems
+
+
+def append_month_elems(elems: list[str], months: int) -> list[str]:
+    """Append total number of months to a list of strings that, when joined, produce an ISO 8601 duration string.
+
+    Args:
+        elems: The list of strings
+        months: The total number of months
+
+    Returns:
+        The amended list of strings
+
+    Examples (joining the result of appending onto ``["P"]``):
+        >>> "".join(append_month_elems(["P"], 6))
+        'P6M'
+        >>> "".join(append_month_elems(["P"], 13))
+        'P1Y1M'
+    """
+    years, months_in_year = divmod(months, 12)
+    if years > 0:
+        elems.append(f"{years}Y")
+    if months_in_year > 0:
+        elems.append(f"{months_in_year}M")
+    return elems
+
+
+def microsecond_period_name(total_microseconds: int) -> str:
+    """Return an ISO 8601 duration string from a total number of microseconds in a period.
+
+    Args:
+        total_microseconds: The total number of microseconds
+
+    Returns:
+        The ISO 8601 duration string representing a period
+        of n-microseconds
+
+    Examples:
+        >>> microsecond_period_name(1)
+        'PT0.000001S'
+        >>> microsecond_period_name(1_500_000)
+        'PT1.5S'
+    """
+    seconds, microseconds = divmod(total_microseconds, 1_000_000)
+    return "".join(append_second_elems(["P"], seconds, microseconds))
+
+
+def second_period_name(seconds: int) -> str:
+    """Return an ISO 8601 duration string from a total number of seconds in a period.
+
+    Args:
+        seconds: The total number of seconds
+
+    Returns:
+        The ISO 8601 duration string representing a period
+        of n-seconds
+
+    Examples:
+        >>> second_period_name(3_600)
+        'PT1H'
+        >>> second_period_name(86_400)
+        'P1D'
+    """
+    return "".join(append_second_elems(["P"], seconds, 0))
+
+
+def month_period_name(months: int) -> str:
+    """Return an ISO 8601 duration string from a total number of months in a period.
+
+    Args:
+        months: The total number of months
+
+    Returns:
+        The ISO 8601 duration string representing a period
+        of n-months
+
+    Examples:
+        >>> month_period_name(3)
+        'P3M'
+        >>> month_period_name(18)
+        'P1Y6M'
+    """
+    return "".join(append_month_elems(["P"], months))
+
+
+# A modern, unambiguous instant at which to sample a fixed UTC offset. Sampling at datetime.min would pick up
+# the Local Mean Time a zone used before standard time was adopted.
+_TZ_REFERENCE = dt.datetime(2000, 1, 1)
+
+
+def tz_label(tzinfo: dt.tzinfo) -> str:
+    """Return a short, stable name for a tzinfo object, for use in a repr.
+
+    A named zone (:class:`zoneinfo.ZoneInfo`) is rendered by its key, a fixed-offset zone in ISO 8601 form, and
+    anything else by its class name. Never raises, and never returns an empty string, so that a period carrying a
+    timezone can always be told apart from a naive one.
+
+    Args:
+        tzinfo: The timezone to name
+
+    Returns:
+        A non-empty label for the timezone
+
+    Examples:
+        >>> from zoneinfo import ZoneInfo
+        >>> tz_label(ZoneInfo("Europe/London"))
+        'Europe/London'
+        >>> tz_label(dt.timezone.utc)
+        'Z'
+        >>> tz_label(dt.timezone(dt.timedelta(hours=5, minutes=30)))
+        '+05:30'
+    """
+    key = getattr(tzinfo, "key", None)
+    if isinstance(key, str) and key:
+        return key
+    try:
+        delta = tzinfo.utcoffset(_TZ_REFERENCE)
+        if delta is not None:
+            return format_tzdelta(delta)
+    except Exception:  # noqa: BLE001 - a repr helper must not raise, whatever a custom tzinfo does
+        pass
+    return type(tzinfo).__name__
+
+
+def format_tzdelta(delta: dt.timedelta) -> str:
+    """Convert a timedelta which represents a timezone to a string that represents that timezone
+
+    Args:
+        delta: The timedelta
+
+    Returns:
+        A string that can be used to represent a timezone in an ISO 8601 format string
+
+    Examples:
+        >>> format_tzdelta(dt.timedelta(0))
+        'Z'
+        >>> format_tzdelta(dt.timedelta(hours=5, minutes=30))
+        '+05:30'
+        >>> format_tzdelta(dt.timedelta(hours=-5))
+        '-05:00'
+    """
+    try:
+        name = dt.timezone(delta).tzname(None)
+    except ValueError as err:
+        raise PeriodParsingError(f"Illegal tz delta: {delta}. Amount of time must be less than 1 day.") from err
+    return name.removeprefix("UTC") or "Z"

isoperiod/parsing.py

@@ -0,0 +1,256 @@
+import datetime as dt
+import re
+from dataclasses import dataclass
+
+from isoperiod.enums import Step
+from isoperiod.exceptions import PeriodValidationError
+from isoperiod.iso import period_regex
+from isoperiod.properties import Properties
+
+# Regular expressions used to detect a truncated ("reduced precision") ISO 8601 date - i.e. a bare year or year-month
+_RE_TRUNCATED_YEAR = re.compile(r"\d{4}")
+_RE_TRUNCATED_YEAR_MONTH = re.compile(r"\d{4}-\d{2}")
+
+# A regular expression Pattern used to parse an ISO 8601 duration, such as P1Y, P7M, P5Y3M, P8D9H1M4S, etc.
+_RE_PERIOD = re.compile(r"^" r"[Pp]" + period_regex("period") + r"$")
+
+# A regular expression Pattern used to parse our custom extended ISO 8601 duration string, such as P2Y+3M,
+# P1Y+9MT9H.
+# This accounts for offsets on the period.
+_RE_PERIOD_OFFSET = re.compile(r"^" r"[Pp]" + period_regex("period") + r"\+" + period_regex("offset") + r"$")
+
+
+def str_to_int(num: str | None, default: int = 0) -> int:
+    """Convert string to int, None becomes 0 (or default if specified)
+
+    Args:
+        num: The string to be converted, or None
+        default: Default int value to use if num is None (defaults to 0)
+
+    Returns:
+        The int value read from the input string
+    """
+    return default if num is None else int(num)
+
+
+def str_to_microseconds(num: str | None, default: int = 0) -> int:
+    """Convert string to microseconds, None becomes 0 (or default if specified)
+
+    A seconds + microseconds string looks like "nn.uuu". This function  converts the "uuu" part (from 1 to 6 digits)
+    to an int value between 0 and 999_999.
+
+    Args:
+        num: The string to be converted, or None
+        default: Default int value to use if num is None (defaults to 0)
+
+    Returns:
+        The int value read from the input string
+    """
+    return default if num is None else int((num + "00000")[:6])
+
+
+@dataclass(frozen=True)
+class MonthsSeconds:
+    """A basic specification for either a period or a period offset where the period/offset amount is a number of
+    months and/or seconds.
+    """
+
+    string: str
+    months: int
+    seconds: int
+    microseconds: int
+
+    def __post_init__(self) -> None:
+        if (self.months < 0) or (self.seconds < 0) or (self.microseconds < 0) or (self.microseconds > 999_999):
+            raise PeriodValidationError(f"Illegal period: {self.string}")
+        if (self.months == 0) and (self.seconds == 0) and (self.microseconds == 0):
+            raise PeriodValidationError(f"Illegal period: {self.string}")
+
+    def get_step_and_multiplier(self) -> tuple[int, int]:
+        """Return a tuple of two integers containing the
+        calculated step and multiplier
+
+        Returns:
+            A tuple of (step,multiplier)
+
+        Raises:
+            ValueError if a valid step and multiplier
+            cannot be created.  This happens, for example,
+            if boths months and seconds are >0.
+        """
+        if (self.months > 0) and (self.seconds == 0) and (self.microseconds == 0):
+            return Step.MONTHS, self.months
+        if (self.months == 0) and (self.seconds > 0) and (self.microseconds == 0):
+            return Step.SECONDS, self.seconds
+        if (self.months == 0) and (self.microseconds > 0):
+            return Step.MICROSECONDS, self.total_microseconds()
+        raise PeriodValidationError(f"Illegal period: {self.string}")
+
+    def total_microseconds(self) -> int:
+        """Return total microseconds from the seconds
+        and microseconds fields
+
+        Returns:
+            The total number of microseconds
+        """
+        return self.seconds * 1_000_000 + self.microseconds
+
+    def get_base_properties(self) -> Properties:
+        """Return a basic Properties object from the months
+        and (seconds,microseconds) fields
+
+        Raise an error if it is not possible to create
+        a valid Properties object.  This happens if,
+        for example, both months and seconds are >0.
+
+        Returns:
+            A Properties object
+        """
+        step, multiplier = self.get_step_and_multiplier()
+        return Properties(
+            step=step, multiplier=multiplier, month_offset=0, microsecond_offset=0, tzinfo=None, ordinal_shift=0
+        )
+
+
+@dataclass(frozen=True)
+class PeriodFields:
+    """A set of fields that can be read from an ISO 8601 format duration string."""
+
+    string: str
+    years: int
+    months: int
+    days: int
+    hours: int
+    minutes: int
+    seconds: int
+    microseconds: int
+
+    def __post_init__(self) -> None:
+        if (
+            (self.years < 0)
+            or (self.months < 0)
+            or (self.days < 0)
+            or (self.hours < 0)
+            or (self.minutes < 0)
+            or (self.seconds < 0)
+            or (self.microseconds < 0)
+            or (self.microseconds > 999_999)
+        ):
+            raise PeriodValidationError(f"Illegal period: {self.string}")
+
+    def get_months_seconds(self) -> MonthsSeconds:
+        """Return a MonthsSeconds object from the fields of an ISO 8601 duration
+
+        Returns:
+            A MonthsSeconds object
+        """
+        months = self.years * 12 + self.months
+        seconds = (self.days * 86_400) + (self.hours * 3_600) + (self.minutes * 60) + self.seconds
+        return MonthsSeconds(string=self.string, months=months, seconds=seconds, microseconds=self.microseconds)
+
+    def get_base_properties(self) -> Properties:
+        """Return a basic Properties object from the fields of an ISO 8601 duration
+
+        Returns:
+            A Properties object
+        """
+        return self.get_months_seconds().get_base_properties()
+
+
+def _period_match(prefix: str, matcher: re.Match[str]) -> PeriodFields:
+    """Return a PeriodFields object from a regex Matcher object
+
+    The regex Pattern that create the matcher is assumed to have been created from a string returned by the
+    period_regex function.
+
+    Args:
+        prefix: The name prefix used when creating the regex
+        matcher: The regex Matcher object
+
+    Returns:
+        The PeriodFields object
+    """
+    return PeriodFields(
+        string=matcher.string,
+        years=str_to_int(matcher.group(f"{prefix}_years")),
+        months=str_to_int(matcher.group(f"{prefix}_months")),
+        days=str_to_int(matcher.group(f"{prefix}_days")),
+        hours=str_to_int(matcher.group(f"{prefix}_hours")),
+        minutes=str_to_int(matcher.group(f"{prefix}_minutes")),
+        seconds=str_to_int(matcher.group(f"{prefix}_seconds")),
+        microseconds=str_to_microseconds(matcher.group(f"{prefix}_microseconds")),
+    )
+
+
+def _pad_truncated_date(text: str) -> str:
+    """Pad a truncated ISO 8601 date ("yyyy" or "yyyy-mm") out to a full "yyyy-mm-dd", defaulting the missing month
+    and/or day to "01" - matching ISO 8601's convention that a reduced-precision date/time represents its first instant.
+
+    Args:
+        text: The (possibly truncated) date/datetime string
+
+    Returns:
+        `text` unchanged if it wasn't truncated, otherwise the padded string
+    """
+    if _RE_TRUNCATED_YEAR.fullmatch(text):
+        return f"{text}-01-01"
+    if _RE_TRUNCATED_YEAR_MONTH.fullmatch(text):
+        return f"{text}-01"
+    return text
+
+
+def _parse_start_datetime(text: str) -> dt.datetime | None:
+    """Parse the "<start>" half of a "<start>/<duration>" string into a datetime, or return None if it isn't a valid
+    (possibly truncated) ISO 8601 date/datetime.
+
+    Args:
+        text: The "<start>" string
+
+    Returns:
+        A datetime object, or None
+    """
+    try:
+        return dt.datetime.fromisoformat(_pad_truncated_date(text))
+    except ValueError:
+        return None
+
+
+def parse_iso_duration(iso_8601_duration: str) -> Properties | None:
+    """Parse a plain ISO 8601 duration string (e.g. "P1Y" or "PT15M") into a Properties object, or return None if the
+    string doesn't match this format.
+    """
+    matcher = _RE_PERIOD.match(iso_8601_duration)
+    if matcher is None:
+        return None
+    return _period_match("period", matcher).get_base_properties()
+
+
+def parse_period_offset(duration: str) -> Properties | None:
+    """Parse the extended "<duration>+<offset>" form (e.g. "P1D+T9H") into a Properties object, or return None if
+    the string doesn't match this format.
+    """
+    matcher = _RE_PERIOD_OFFSET.match(duration)
+    if matcher is None:
+        return None
+    period_fields = _period_match("period", matcher)
+    offset_fields = _period_match("offset", matcher)
+    return period_fields.get_base_properties().with_offset_period_fields(offset_fields)
+
+
+def parse_date_and_duration(date_duration: str) -> tuple[Properties, dt.datetime] | None:
+    """Parse a "<start>/<duration>" string (e.g. "1883-01-01/P1D") into a (Properties, origin datetime) pair, or
+    return None if the string doesn't match this format.
+
+    The caller is responsible for applying the origin (via Period.with_origin) to the Period built from the Properties.
+    """
+    start_text, sep, duration_text = date_duration.partition("/")
+    if not sep:
+        return None
+    origin = _parse_start_datetime(start_text)
+    if origin is None:
+        return None
+    matcher = _RE_PERIOD.match(duration_text)
+    if matcher is None:
+        return None
+    properties = _period_match("period", matcher).get_base_properties()
+    return properties, origin