opendate 0.1.34__cp39-cp39-win_amd64.whl

opendate/date_.py

@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+import contextlib
+import datetime as _datetime
+import sys
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+import pendulum as _pendulum
+
+from opendate.constants import _IS_WINDOWS, DATEMATCH, LCL, UTC
+from opendate.helpers import _rust_parse_datetime
+from opendate.metaclass import DATE_METHODS_RETURNING_DATE, DateContextMeta
+from opendate.mixins import DateBusinessMixin, DateExtrasMixin
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+if TYPE_CHECKING:
+    from opendate.calendars import Calendar
+
+
+class Date(
+    DateExtrasMixin,
+    DateBusinessMixin,
+    _pendulum.Date,
+    metaclass=DateContextMeta,
+    methods_to_wrap=DATE_METHODS_RETURNING_DATE
+):
+    """Date class extending pendulum.Date with business day and additional functionality.
+
+    This class inherits all pendulum.Date functionality while adding:
+    - Business day calculations with NYSE calendar integration
+    - Additional date navigation methods
+    - Enhanced parsing capabilities
+    - Custom financial date utilities
+
+    Unlike pendulum.Date, methods that create new instances return Date objects
+    that preserve business status and entity association when chained.
+    """
+
+    def to_string(self, fmt: str) -> str:
+        """Format date to string, handling platform-specific format codes.
+
+        Automatically converts '%-' format codes to '%#' on Windows.
+        """
+        return self.strftime(fmt.replace('%-', '%#') if _IS_WINDOWS else fmt)
+
+    @classmethod
+    def fromordinal(cls, *args, **kwargs) -> Self:
+        """Create a Date from an ordinal.
+
+        Parameters
+            n: The ordinal value
+
+        Returns
+            Date instance
+        """
+        result = _pendulum.Date.fromordinal(*args, **kwargs)
+        return cls.instance(result)
+
+    @classmethod
+    def fromtimestamp(cls, timestamp, tz=None) -> Self:
+        """Create a Date from a timestamp.
+
+        Parameters
+            timestamp: Unix timestamp
+            tz: Optional timezone (defaults to UTC)
+
+        Returns
+            Date instance
+        """
+        tz = tz or UTC
+        dt = _datetime.datetime.fromtimestamp(timestamp, tz=tz)
+        return cls(dt.year, dt.month, dt.day)
+
+    @classmethod
+    def parse(
+        cls,
+        s: str | None,
+        calendar: str | Calendar = 'NYSE',
+        raise_err: bool = False,
+    ) -> Self | None:
+        """Convert a string to a date handling many different formats.
+
+        Supports various date formats including:
+        - Standard formats: YYYY-MM-DD, MM/DD/YYYY, MM/DD/YY, YYYYMMDD
+        - Named months: DD-MON-YYYY, MON-DD-YYYY, Month DD, YYYY
+        - Special codes: T (today), Y (yesterday), P (previous business day)
+        - Business day offsets: T-3b, P+2b (add/subtract business days)
+
+        Parameters
+            s: String to parse or None
+            calendar: Calendar name or instance for business day calculations (default 'NYSE')
+            raise_err: If True, raises ValueError on parse failure instead of returning None
+
+        Returns
+            Date instance or None if parsing fails and raise_err is False
+
+        Examples
+            Standard numeric formats:
+            Date.parse('2020-01-15') → Date(2020, 1, 15)
+            Date.parse('01/15/2020') → Date(2020, 1, 15)
+            Date.parse('01/15/20') → Date(2020, 1, 15)
+            Date.parse('20200115') → Date(2020, 1, 15)
+
+            Named month formats:
+            Date.parse('15-Jan-2020') → Date(2020, 1, 15)
+            Date.parse('Jan 15, 2020') → Date(2020, 1, 15)
+            Date.parse('15JAN2020') → Date(2020, 1, 15)
+
+            Special codes:
+            Date.parse('T') → today's date
+            Date.parse('Y') → yesterday's date
+            Date.parse('P') → previous business day
+            Date.parse('M') → last day of previous month
+
+            Business day offsets:
+            Date.parse('T-3b') → 3 business days ago
+            Date.parse('P+2b') → 2 business days after previous business day
+            Date.parse('T+5') → 5 calendar days from today
+        """
+
+        def date_for_symbol(s):
+            if s == 'N':
+                return cls.today()
+            if s == 'T':
+                return cls.today()
+            if s == 'Y':
+                return cls.today().subtract(days=1)
+            if s == 'P':
+                return cls.today().calendar(calendar).business().subtract(days=1)
+            if s == 'M':
+                return cls.today().start_of('month').subtract(days=1)
+
+        if not s:
+            if raise_err:
+                raise ValueError('Empty value')
+            return
+
+        if not isinstance(s, str):
+            raise TypeError(f'Invalid type for date parse: {s.__class__}')
+
+        with contextlib.suppress(ValueError):
+            if float(s) and len(s) != 8:  # 20000101
+                if raise_err:
+                    raise ValueError('Invalid date: %s', s)
+                return
+
+        # special shortcode symbolic values: T, Y-2, P-1b
+        if m := DATEMATCH.match(s):
+            d = date_for_symbol(m.groupdict().get('d'))
+            n = m.groupdict().get('n')
+            if not n:
+                return d
+            n = int(n)
+            b = m.groupdict().get('b')
+            if b:
+                if b != 'b':
+                    raise ValueError(f"Expected 'b' for business day modifier, got '{b}'")
+                d = d.calendar(calendar).business().add(days=n)
+            else:
+                d = d.add(days=n)
+            return d
+        if 'today' in s.lower():
+            return cls.today()
+        if 'yester' in s.lower():
+            return cls.today().subtract(days=1)
+
+        parsed = _rust_parse_datetime(s)
+        if parsed is not None:
+            return cls.instance(parsed)
+
+        if raise_err:
+            raise ValueError('Failed to parse date: %s', s)
+
+    @classmethod
+    def instance(
+        cls,
+        obj: _datetime.date
+        | _datetime.datetime
+        | _datetime.time
+        | pd.Timestamp
+        | np.datetime64
+        | Self
+        | None,
+        raise_err: bool = False,
+    ) -> Self | None:
+        """Create a Date instance from various date-like objects.
+
+        Converts datetime.date, datetime.datetime, pandas Timestamp,
+        numpy datetime64, and other date-like objects to Date instances.
+
+        Parameters
+            obj: Date-like object to convert
+            raise_err: If True, raises ValueError for None/NA values instead of returning None
+
+        Returns
+            Date instance or None if obj is None/NA and raise_err is False
+        """
+        if pd.isna(obj):
+            if raise_err:
+                raise ValueError('Empty value')
+            return
+
+        if type(obj) is cls:
+            return obj
+
+        if isinstance(obj, pd.Timestamp):
+            obj = obj.to_pydatetime()
+            return cls(obj.year, obj.month, obj.day)
+
+        if isinstance(obj, np.datetime64):
+            obj = np.datetime64(obj, 'us').astype(_datetime.datetime)
+            return cls(obj.year, obj.month, obj.day)
+
+        return cls(obj.year, obj.month, obj.day)
+
+    @classmethod
+    def today(cls) -> Self:
+        d = _datetime.datetime.now(LCL)
+        return cls(d.year, d.month, d.day)
+
+    def isoweek(self) -> int | None:
+        """Get ISO week number (1-52/53) following ISO week-numbering standard.
+        """
+        with contextlib.suppress(Exception):
+            return self.isocalendar()[1]
+
+    def lookback(self, unit='last') -> Self:
+        """Get date in the past based on lookback unit.
+
+        Supported units: 'last'/'day' (1 day), 'week', 'month', 'quarter', 'year'.
+        Respects business day mode if enabled.
+        """
+        def _lookback(years=0, months=0, weeks=0, days=0):
+            _business = self._business
+            self._business = False
+            d = self\
+                .subtract(years=years, months=months, weeks=weeks, days=days)
+            if _business:
+                return d._business_or_previous()
+            return d
+
+        return {
+            'day': _lookback(days=1),
+            'last': _lookback(days=1),
+            'week': _lookback(weeks=1),
+            'month': _lookback(months=1),
+            'quarter': _lookback(months=3),
+            'year': _lookback(years=1),
+            }.get(unit)

opendate/datetime_.py

@@ -0,0 +1,339 @@
+from __future__ import annotations
+
+import datetime as _datetime
+import sys
+import zoneinfo as _zoneinfo
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+import pendulum as _pendulum
+
+from opendate.constants import LCL, UTC, Timezone
+from opendate.helpers import _rust_parse_datetime
+from opendate.metaclass import DATETIME_METHODS_RETURNING_DATETIME, DateContextMeta
+from opendate.mixins import DateBusinessMixin
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+if TYPE_CHECKING:
+    from opendate.calendars import Calendar
+    from opendate.date_ import Date
+    from opendate.time_ import Time
+
+
+class DateTime(
+    DateBusinessMixin,
+    _pendulum.DateTime,
+    metaclass=DateContextMeta,
+    methods_to_wrap=DATETIME_METHODS_RETURNING_DATETIME
+):
+    """DateTime class extending pendulum.DateTime with business day and additional functionality.
+
+    This class inherits all pendulum.DateTime functionality while adding:
+    - Business day calculations with NYSE calendar integration
+    - Enhanced timezone handling
+    - Extended parsing capabilities
+    - Custom utility methods for financial applications
+
+    Unlike pendulum.DateTime:
+    - today() returns start of day rather than current time
+    - Methods preserve business status and entity when chaining
+    - Has timezone handling helpers not present in pendulum
+    """
+
+    def epoch(self) -> float:
+        """Translate a datetime object into unix seconds since epoch
+        """
+        return self.timestamp()
+
+    @classmethod
+    def fromordinal(cls, *args, **kwargs) -> Self:
+        """Create a DateTime from an ordinal.
+
+        Parameters
+            n: The ordinal value
+
+        Returns
+            DateTime instance
+        """
+        result = _pendulum.DateTime.fromordinal(*args, **kwargs)
+        return cls.instance(result)
+
+    @classmethod
+    def fromtimestamp(cls, timestamp, tz=None) -> Self:
+        """Create a DateTime from a timestamp.
+
+        Parameters
+            timestamp: Unix timestamp
+            tz: Optional timezone
+
+        Returns
+            DateTime instance
+        """
+        tz = tz or UTC
+        result = _pendulum.DateTime.fromtimestamp(timestamp, tz)
+        return cls.instance(result)
+
+    @classmethod
+    def strptime(cls, time_str, fmt) -> Self:
+        """Parse a string into a DateTime according to a format.
+
+        Parameters
+            time_str: String to parse
+            fmt: Format string
+
+        Returns
+            DateTime instance
+        """
+        result = _pendulum.DateTime.strptime(time_str, fmt)
+        return cls.instance(result)
+
+    @classmethod
+    def utcfromtimestamp(cls, timestamp) -> Self:
+        """Create a UTC DateTime from a timestamp.
+
+        Parameters
+            timestamp: Unix timestamp
+
+        Returns
+            DateTime instance
+        """
+        result = _pendulum.DateTime.utcfromtimestamp(timestamp)
+        return cls.instance(result)
+
+    @classmethod
+    def utcnow(cls) -> Self:
+        """Create a DateTime representing current UTC time.
+
+        Returns
+            DateTime instance
+        """
+        result = _pendulum.DateTime.utcnow()
+        return cls.instance(result)
+
+    @classmethod
+    def now(cls, tz: str | _zoneinfo.ZoneInfo | _datetime.tzinfo | None = None) -> Self:
+        """Get a DateTime instance for the current date and time.
+        """
+        if tz is None or tz == 'local':
+            d = _datetime.datetime.now(LCL)
+        elif tz is UTC or tz == 'UTC':
+            d = _datetime.datetime.now(UTC)
+        else:
+            d = _datetime.datetime.now(UTC)
+            tz = _pendulum._safe_timezone(tz)
+            d = d.astimezone(tz)
+        return cls(d.year, d.month, d.day, d.hour, d.minute, d.second,
+                   d.microsecond, tzinfo=d.tzinfo, fold=d.fold)
+
+    @classmethod
+    def today(cls, tz: str | _zoneinfo.ZoneInfo | None = None) -> Self:
+        """Create a DateTime object representing today at the start of day.
+
+        Unlike pendulum.today() which returns current time, this method
+        returns a DateTime object at 00:00:00 of the current day.
+
+        Parameters
+            tz: Optional timezone (defaults to local timezone)
+
+        Returns
+            DateTime instance representing start of current day
+        """
+        return DateTime.now(tz).start_of('day')
+
+    def date(self) -> Date:
+        from opendate.date_ import Date
+        return Date(self.year, self.month, self.day)
+
+    @classmethod
+    def combine(
+        cls,
+        date: _datetime.date,
+        time: _datetime.time,
+        tzinfo: _zoneinfo.ZoneInfo | None = None,
+    ) -> Self:
+        """Combine date and time (*behaves differently from Pendulum `combine`*).
+        """
+        _tzinfo = tzinfo or time.tzinfo
+        return DateTime.instance(_datetime.datetime.combine(date, time, tzinfo=_tzinfo))
+
+    def rfc3339(self) -> str:
+        """Return RFC 3339 formatted string (same as isoformat()).
+        """
+        return self.isoformat()
+
+    def time(self) -> Time:
+        """Extract time component from datetime (preserving timezone).
+        """
+        from opendate.time_ import Time
+        return Time.instance(self)
+
+    @classmethod
+    def parse(
+        cls, s: str | int | None,
+        calendar: str | Calendar = 'NYSE',
+        raise_err: bool = False
+        ) -> Self | None:
+        """Convert a string or timestamp to a DateTime with extended format support.
+
+        Unlike pendulum's parse, this method supports:
+        - Unix timestamps (int/float, handles milliseconds automatically)
+        - Special codes: T (today), Y (yesterday), P (previous business day)
+        - Business day offsets: T-3b, P+2b (add/subtract business days)
+        - Multiple date-time formats beyond ISO 8601
+        - Combined date and time strings with various separators
+
+        Parameters
+            s: String or timestamp to parse
+            calendar: Calendar name or instance for business day calculations (default 'NYSE')
+            raise_err: If True, raises ValueError on parse failure instead of returning None
+
+        Returns
+            DateTime instance or None if parsing fails and raise_err is False
+
+        Examples
+            Unix timestamps:
+            DateTime.parse(1609459200) → DateTime(2021, 1, 1, 0, 0, 0, tzinfo=LCL)
+            DateTime.parse(1609459200000) → DateTime(2021, 1, 1, 0, 0, 0, tzinfo=LCL)
+
+            ISO 8601 format:
+            DateTime.parse('2020-01-15T14:30:00') → DateTime(2020, 1, 15, 14, 30, 0)
+
+            Date and time separated:
+            DateTime.parse('2020-01-15 14:30:00') → DateTime(2020, 1, 15, 14, 30, 0, tzinfo=LCL)
+            DateTime.parse('01/15/2020:14:30:00') → DateTime(2020, 1, 15, 14, 30, 0, tzinfo=LCL)
+
+            Date only (time defaults to 00:00:00):
+            DateTime.parse('2020-01-15') → DateTime(2020, 1, 15, 0, 0, 0)
+            DateTime.parse('01/15/2020') → DateTime(2020, 1, 15, 0, 0, 0)
+
+            Time only (uses today's date):
+            DateTime.parse('14:30:00') → DateTime(today's year, month, day, 14, 30, 0, tzinfo=LCL)
+
+            Special codes:
+            DateTime.parse('T') → today at 00:00:00
+            DateTime.parse('Y') → yesterday at 00:00:00
+            DateTime.parse('P') → previous business day at 00:00:00
+        """
+        from opendate.date_ import Date
+        from opendate.time_ import Time
+
+        if not s:
+            if raise_err:
+                raise ValueError('Empty value')
+            return
+
+        if not isinstance(s, (str, int, float)):
+            raise TypeError(f'Invalid type for datetime parse: {s.__class__}')
+
+        if isinstance(s, (int, float)):
+            if len(str(int(s))) == 13:
+                s /= 1000  # Convert from milliseconds to seconds
+            dt = _datetime.datetime.fromtimestamp(s)
+            return cls(dt.year, dt.month, dt.day, dt.hour, dt.minute,
+                       dt.second, dt.microsecond, tzinfo=LCL)
+
+        parsed = _rust_parse_datetime(s)
+        if parsed is not None:
+            return cls.instance(parsed)
+
+        for delim in (' ', ':'):
+            bits = s.split(delim, 1)
+            if len(bits) == 2:
+                d = Date.parse(bits[0])
+                t = Time.parse(bits[1])
+                if d is not None and t is not None:
+                    return DateTime.combine(d, t, LCL)
+
+        d = Date.parse(s, calendar=calendar)
+        if d is not None:
+            return cls(d.year, d.month, d.day, 0, 0, 0)
+
+        current = Date.today()
+        t = Time.parse(s)
+        if t is not None:
+            return cls.combine(current, t, LCL)
+
+        if raise_err:
+            raise ValueError('Invalid date-time format: %s', s)
+
+    @classmethod
+    def instance(
+        cls,
+        obj: _datetime.date
+        | _datetime.time
+        | pd.Timestamp
+        | np.datetime64
+        | Self
+        | None,
+        tz: str | _zoneinfo.ZoneInfo | _datetime.tzinfo | None = None,
+        raise_err: bool = False,
+    ) -> Self | None:
+        """Create a DateTime instance from various datetime-like objects.
+
+        Provides unified interface for converting different date/time types
+        including pandas and numpy datetime objects into DateTime instances.
+
+        Unlike pendulum, this method:
+        - Handles pandas Timestamp and numpy datetime64 objects
+        - Adds timezone (UTC by default) when none is specified
+        - Has special handling for Time objects (combines with current date)
+
+        Parameters
+            obj: Date, datetime, time, or compatible object to convert
+            tz: Optional timezone to apply (if None, uses obj's timezone or UTC)
+            raise_err: If True, raises ValueError for None/NA values instead of returning None
+
+        Returns
+            DateTime instance or None if obj is None/NA and raise_err is False
+        """
+        from opendate.date_ import Date
+        from opendate.time_ import Time
+
+        if pd.isna(obj):
+            if raise_err:
+                raise ValueError('Empty value')
+            return
+
+        if type(obj) is cls and not tz:
+            return obj
+
+        if isinstance(obj, pd.Timestamp):
+            obj = obj.to_pydatetime()
+            tz = tz or obj.tzinfo or UTC
+            if tz is _datetime.timezone.utc:
+                tz = UTC
+            elif hasattr(tz, 'zone'):
+                tz = Timezone(tz.zone)
+            elif isinstance(tz, str):
+                tz = Timezone(tz)
+            return cls(obj.year, obj.month, obj.day, obj.hour, obj.minute,
+                       obj.second, obj.microsecond, tzinfo=tz)
+
+        if isinstance(obj, np.datetime64):
+            obj = np.datetime64(obj, 'us').astype(_datetime.datetime)
+            tz = tz or UTC
+            return cls(obj.year, obj.month, obj.day, obj.hour, obj.minute,
+                       obj.second, obj.microsecond, tzinfo=tz)
+
+        if type(obj) is Date:
+            return cls(obj.year, obj.month, obj.day, tzinfo=tz or UTC)
+
+        if isinstance(obj, _datetime.date) and not isinstance(obj, _datetime.datetime):
+            return cls(obj.year, obj.month, obj.day, tzinfo=tz or UTC)
+
+        tz = tz or obj.tzinfo or UTC
+
+        if type(obj) is Time:
+            return cls.combine(Date.today(), obj, tzinfo=tz)
+
+        if isinstance(obj, _datetime.time):
+            from opendate.date_ import Date
+            return cls.combine(Date.today(), obj, tzinfo=tz)
+
+        return cls(obj.year, obj.month, obj.day, obj.hour, obj.minute,
+                   obj.second, obj.microsecond, tzinfo=tz)