opendate 0.1.34__cp39-cp39-win_amd64.whl

opendate/decorators.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import datetime as _datetime
+from collections.abc import Callable, Sequence
+from functools import partial, wraps
+from typing import Any
+
+import numpy as np
+import pandas as pd
+import pendulum as _pendulum
+
+from opendate.constants import LCL, UTC
+from opendate.helpers import isdateish
+
+
+def parse_arg(typ: type | str, arg: Any) -> Any:
+    """Parse argument to specified type or 'smart' to preserve Date/DateTime.
+    """
+    import opendate
+
+    if not isdateish(arg):
+        return arg
+
+    if typ == 'smart':
+        if isinstance(arg, (opendate.Date, opendate.DateTime)):
+            return arg
+        if isinstance(arg, (_datetime.datetime, _pendulum.DateTime)):
+            return opendate.DateTime.instance(arg)
+        if isinstance(arg, pd.Timestamp):
+            if pd.isna(arg):
+                return None
+            return opendate.DateTime.instance(arg)
+        if isinstance(arg, np.datetime64):
+            if np.isnat(arg):
+                return None
+            return opendate.DateTime.instance(arg)
+        if isinstance(arg, _datetime.date):
+            return opendate.Date.instance(arg)
+        if isinstance(arg, _datetime.time):
+            return opendate.Time.instance(arg)
+        return arg
+
+    if typ == _datetime.datetime:
+        return opendate.DateTime.instance(arg)
+    if typ == _datetime.date:
+        return opendate.Date.instance(arg)
+    if typ == _datetime.time:
+        return opendate.Time.instance(arg)
+    return arg
+
+
+def parse_args(typ: type | str, *args: Any) -> list[Any]:
+    """Parse args to specified type or 'smart' mode.
+    """
+    this = []
+    for a in args:
+        if isinstance(a, Sequence) and not isinstance(a, str):
+            this.append(parse_args(typ, *a))
+        else:
+            this.append(parse_arg(typ, a))
+    return this
+
+
+def expect(func=None, *, typ: type[_datetime.date] | str = None, exclkw: bool = False) -> Callable:
+    """Decorator to force input type of date/datetime inputs.
+
+    typ can be _datetime.date, _datetime.datetime, _datetime.time, or 'smart'
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            args = parse_args(typ, *args)
+            if not exclkw:
+                for k, v in kwargs.items():
+                    if isdateish(v):
+                        kwargs[k] = parse_arg(typ, v)
+            return func(*args, **kwargs)
+        return wrapper
+
+    if func is None:
+        return decorator
+    return decorator(func)
+
+
+expect_date = partial(expect, typ=_datetime.date)
+expect_datetime = partial(expect, typ=_datetime.datetime)
+expect_time = partial(expect, typ=_datetime.time)
+expect_date_or_datetime = partial(expect, typ='smart')
+
+
+def type_class(typ, obj):
+    """Get the appropriate class for the type/object combination."""
+    import opendate
+
+    if isinstance(typ, str):
+        if typ == 'Date':
+            return opendate.Date
+        if typ == 'DateTime':
+            return opendate.DateTime
+        if typ == 'Interval':
+            return opendate.Interval
+    if typ:
+        return typ
+    if obj.__class__.__name__ == 'Interval':
+        return opendate.Interval
+    if obj.__class__ in {_datetime.datetime, _pendulum.DateTime} or obj.__class__.__name__ == 'DateTime':
+        return opendate.DateTime
+    if obj.__class__ in {_datetime.date, _pendulum.Date} or obj.__class__.__name__ == 'Date':
+        return opendate.Date
+    raise ValueError(f'Unknown type {typ}')
+
+
+def store_calendar(func=None, *, typ=None):
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        _calendar = self._calendar
+        d = type_class(typ, self).instance(func(self, *args, **kwargs))
+        d._calendar = _calendar
+        return d
+    if func is None:
+        return partial(store_calendar, typ=typ)
+    return wrapper
+
+
+def reset_business(func):
+    """Decorator to reset business mode after function execution.
+    """
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        try:
+            return func(self, *args, **kwargs)
+        finally:
+            self._business = False
+            self._start._business = False
+            self._end._business = False
+    return wrapper
+
+
+def normalize_date_datetime_pairs(func):
+    """Decorator to normalize mixed Date/DateTime pairs to DateTime.
+    """
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        import opendate
+
+        if len(args) >= 3:
+            cls_or_self, begdate, enddate = args[0], args[1], args[2]
+            rest_args = args[3:]
+
+            tz = UTC
+            if isinstance(begdate, opendate.DateTime) and begdate.tzinfo:
+                tz = begdate.tzinfo
+            elif isinstance(enddate, opendate.DateTime) and enddate.tzinfo:
+                tz = enddate.tzinfo
+
+            if isinstance(begdate, opendate.Date) and not isinstance(begdate, opendate.DateTime):
+                if isinstance(enddate, opendate.DateTime):
+                    begdate = opendate.DateTime(begdate.year, begdate.month, begdate.day, tzinfo=tz)
+            elif isinstance(enddate, opendate.Date) and not isinstance(enddate, opendate.DateTime):
+                if isinstance(begdate, opendate.DateTime):
+                    enddate = opendate.DateTime(enddate.year, enddate.month, enddate.day, tzinfo=tz)
+
+            args = (cls_or_self, begdate, enddate) + rest_args
+
+        return func(*args, **kwargs)
+    return wrapper
+
+
+def prefer_utc_timezone(func, force: bool = False) -> Callable:
+    """Return datetime as UTC.
+    """
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        d = func(*args, **kwargs)
+        if not d:
+            return
+        if not force and d.tzinfo:
+            return d
+        return d.replace(tzinfo=UTC)
+    return wrapper
+
+
+def prefer_native_timezone(func, force: bool = False) -> Callable:
+    """Return datetime as native.
+    """
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        d = func(*args, **kwargs)
+        if not d:
+            return
+        if not force and d.tzinfo:
+            return d
+        return d.replace(tzinfo=LCL)
+    return wrapper
+
+
+expect_native_timezone = partial(prefer_native_timezone, force=True)
+expect_utc_timezone = partial(prefer_utc_timezone, force=True)

opendate/extras.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+"""Legacy compatibility functions for OpenDate.
+
+This module contains functions that exist primarily for backward compatibility
+with older codebases. These functions provide alternative interfaces to
+functionality that may be available through other means in the core Date,
+DateTime, and Interval classes.
+
+New code should prefer using the built-in methods on Date, DateTime, and
+Interval objects where applicable.
+"""
+
+from opendate.calendars import Calendar, get_calendar, get_default_calendar
+from opendate.date_ import Date
+from opendate.datetime_ import DateTime
+from opendate.interval import Interval
+
+__all__ = [
+    'is_within_business_hours',
+    'is_business_day',
+    'overlap_days',
+    'create_ics',
+]
+
+
+def is_within_business_hours(calendar: str | Calendar | None = None) -> bool:
+    """Return whether the current native datetime is between open and close of business hours.
+    """
+    if calendar is None:
+        calendar = get_default_calendar()
+    if isinstance(calendar, str):
+        calendar = get_calendar(calendar)
+    this = DateTime.now()
+    this_cal = this.in_tz(calendar.tz).calendar(calendar)
+    bounds = this_cal.business_hours()
+    return this_cal.business_open() and (bounds[0] <= this.astimezone(calendar.tz) <= bounds[1])
+
+
+def is_business_day(calendar: str | Calendar | None = None) -> bool:
+    """Return whether the current native datetime is a business day.
+    """
+    if calendar is None:
+        calendar = get_default_calendar()
+    if isinstance(calendar, str):
+        calendar = get_calendar(calendar)
+    return DateTime.now(tz=calendar.tz).calendar(calendar).is_business_day()
+
+
+def overlap_days(
+    interval_one: Interval | tuple[Date | DateTime, Date | DateTime],
+    interval_two: Interval | tuple[Date | DateTime, Date | DateTime],
+    days: bool = False,
+) -> bool | int:
+    """Calculate how much two date intervals overlap.
+
+    When days=False, returns True/False indicating whether intervals overlap.
+    When days=True, returns the actual day count (negative if non-overlapping).
+
+    Algorithm adapted from Raymond Hettinger: http://stackoverflow.com/a/9044111
+    """
+    if not isinstance(interval_one, Interval):
+        interval_one = Interval(*interval_one)
+    if not isinstance(interval_two, Interval):
+        interval_two = Interval(*interval_two)
+
+    latest_start = max(interval_one.start, interval_two.start)
+    earliest_end = min(interval_one.end, interval_two.end)
+    overlap = (earliest_end - latest_start).days + 1
+    if days:
+        return overlap
+    return overlap >= 0
+
+
+def create_ics(begdate: Date | DateTime, enddate: Date | DateTime, summary: str, location: str) -> str:
+    """Create a simple .ics file per RFC 5545 guidelines."""
+
+    return f"""BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//hacksw/handcal//NONSGML v1.0//EN
+BEGIN:VEVENT
+DTSTART;TZID=America/New_York:{begdate:%Y%m%dT%H%M%S}
+DTEND;TZID=America/New_York:{enddate:%Y%m%dT%H%M%S}
+SUMMARY:{summary}
+LOCATION:{location}
+END:VEVENT
+END:VCALENDAR
+    """

opendate/helpers.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import datetime as _datetime
+import logging
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from opendate.constants import MAX_YEAR, MIN_YEAR
+
+try:
+    from opendate._opendate import BusinessCalendar as _BusinessCalendar
+    from opendate._opendate import IsoParser as _RustIsoParser
+    from opendate._opendate import Parser as _RustParser
+    from opendate._opendate import TimeParser as _RustTimeParser
+except ImportError:
+    try:
+        from _opendate import BusinessCalendar as _BusinessCalendar
+        from _opendate import IsoParser as _RustIsoParser
+        from _opendate import Parser as _RustParser
+        from _opendate import TimeParser as _RustTimeParser
+    except ImportError:
+        _BusinessCalendar = None
+        _RustParser = None
+        _RustIsoParser = None
+        _RustTimeParser = None
+
+logger = logging.getLogger(__name__)
+
+_cached_parser: _RustParser | None = None
+_cached_iso_parser: _RustIsoParser | None = None
+_cached_time_parser: _RustTimeParser | None = None
+
+
+def _get_parser() -> _RustParser | None:
+    """Get cached Parser instance.
+    """
+    global _cached_parser
+    if _RustParser is None:
+        return None
+    if _cached_parser is None:
+        _cached_parser = _RustParser(False, False)
+    return _cached_parser
+
+
+def _get_iso_parser() -> _RustIsoParser | None:
+    """Get cached IsoParser instance.
+    """
+    global _cached_iso_parser
+    if _RustIsoParser is None:
+        return None
+    if _cached_iso_parser is None:
+        _cached_iso_parser = _RustIsoParser()
+    return _cached_iso_parser
+
+
+def _get_time_parser() -> _RustTimeParser | None:
+    """Get cached TimeParser instance.
+    """
+    global _cached_time_parser
+    if _RustTimeParser is None:
+        return None
+    if _cached_time_parser is None:
+        _cached_time_parser = _RustTimeParser()
+    return _cached_time_parser
+
+
+def isdateish(x: Any) -> bool:
+    return isinstance(x, (_datetime.date, _datetime.datetime, _datetime.time, pd.Timestamp, np.datetime64))
+
+
+def _rust_parse_datetime(s: str, dayfirst: bool = False, yearfirst: bool = False, fuzzy: bool = True) -> _datetime.datetime | None:
+    """Parse datetime string using Rust parser, return Python datetime or None.
+
+    This is an internal helper that bridges the Rust parser to Python datetime objects.
+    Returns None if parsing fails or no meaningful components are found.
+    Uses current year as default when year is missing but month/day are present.
+    """
+    iso_parser = _get_iso_parser()
+    if iso_parser is not None:
+        try:
+            result = iso_parser.isoparse(s)
+            if result is not None:
+                tzinfo = None
+                if result.tzoffset is not None:
+                    tzinfo = _datetime.timezone(_datetime.timedelta(seconds=result.tzoffset))
+                return _datetime.datetime(
+                    result.year, result.month, result.day,
+                    result.hour or 0, result.minute or 0, result.second or 0,
+                    result.microsecond or 0, tzinfo=tzinfo,
+                )
+        except Exception:
+            pass
+
+    parser = _get_parser()
+    if parser is None:
+        return None
+
+    try:
+        result = parser.parse(s, dayfirst=dayfirst, yearfirst=yearfirst, fuzzy=fuzzy)
+
+        if isinstance(result, tuple):
+            result = result[0]
+
+        if result is None:
+            return None
+
+        has_date = result.year is not None or result.month is not None or result.day is not None
+        has_time = result.hour is not None or result.minute is not None or result.second is not None
+
+        if not has_date and not has_time:
+            return None
+
+        year = result.year
+        month = result.month
+        day = result.day
+
+        if year is None or (has_time and not has_date and (month is None or day is None)):
+            now = _datetime.datetime.now()
+            year = year if year is not None else now.year
+            month = month if month is not None else (now.month if has_time and not has_date else 1)
+            day = day if day is not None else (now.day if has_time and not has_date else 1)
+        else:
+            month = month if month is not None else 1
+            day = day if day is not None else 1
+
+        tzinfo = None
+        if result.tzoffset is not None:
+            tzinfo = _datetime.timezone(_datetime.timedelta(seconds=result.tzoffset))
+
+        return _datetime.datetime(
+            year, month, day,
+            result.hour or 0, result.minute or 0, result.second or 0,
+            result.microsecond or 0, tzinfo=tzinfo,
+        )
+    except Exception as e:
+        logger.debug(f'Rust parser failed: {e}')
+        return None
+
+
+def _rust_parse_time(s: str) -> tuple[int, int, int, int] | None:
+    """Parse time string using Rust TimeParser, return (h, m, s, us) or None.
+
+    This is an internal helper that bridges the Rust TimeParser to Python.
+    Returns None if parsing fails.
+    """
+    time_parser = _get_time_parser()
+    if time_parser is None:
+        return None
+    try:
+        result = time_parser.parse(s)
+        hour = result.hour if result.hour is not None else 0
+        minute = result.minute if result.minute is not None else 0
+        second = result.second if result.second is not None else 0
+        microsecond = result.microsecond if result.microsecond is not None else 0
+        return (hour, minute, second, microsecond)
+    except Exception:
+        return None
+
+
+def _get_decade_bounds(year: int) -> tuple[_datetime.date, _datetime.date] | None:
+    """Get decade start/end dates for caching. Returns None if outside valid range."""
+    if year > MAX_YEAR or year < MIN_YEAR:
+        return None
+    decade_start = _datetime.date(year // 10 * 10, 1, 1)
+    next_decade_year = (year // 10 + 1) * 10
+    decade_end = _datetime.date(MAX_YEAR, 12, 31) if next_decade_year > MAX_YEAR else _datetime.date(next_decade_year, 1, 1)
+    return decade_start, decade_end