opendate 0.1.34__cp39-cp39-win_amd64.whl

opendate/mixins/business.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from opendate.calendars import get_calendar, get_default_calendar
+from opendate.constants import MAX_YEAR, MIN_YEAR, WeekDay
+from opendate.decorators import expect_date, store_calendar
+
+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.datetime_ import DateTime
+
+
+class DateBusinessMixin:
+    """Mixin class providing business day functionality.
+
+    This mixin adds business day awareness to Date and DateTime classes,
+    allowing date operations to account for weekends and holidays according
+    to a specified calendar.
+
+    Features not available in pendulum:
+    - Business day mode toggle
+    - Calendar-specific rules (exchanges, custom)
+    - Business-aware date arithmetic
+    """
+
+    _calendar: Calendar | None = None
+    _business: bool = False
+
+    def business(self) -> Self:
+        """Switch to business day mode for date calculations.
+
+        In business day mode, date arithmetic only counts business days
+        as defined by the associated calendar (default NYSE).
+
+        Returns
+            Self instance for method chaining
+        """
+        self._business = True
+        return self
+
+    @property
+    def b(self) -> Self:
+        """Shorthand property for business() method.
+
+        Returns
+            Self instance for method chaining
+        """
+        return self.business()
+
+    def calendar(self, cal: str | Calendar | None = None) -> Self:
+        """Set the calendar for business day calculations.
+
+        Parameters
+            cal: Calendar name (str), Calendar instance, or None for default
+
+        Returns
+            Self instance for method chaining
+
+        Examples
+            d.calendar('NYSE').b.add(days=1)
+            d.calendar('LSE').b.subtract(days=5)
+            d.calendar(my_custom_calendar).is_business_day()
+        """
+        if cal is None:
+            cal = get_default_calendar()
+        if isinstance(cal, str):
+            self._calendar = get_calendar(cal)
+        else:
+            self._calendar = cal
+        return self
+
+    @property
+    def _active_calendar(self) -> Calendar:
+        """Get the active calendar (uses module default if not set).
+        """
+        if self._calendar is None:
+            return get_calendar(get_default_calendar())
+        return self._calendar
+
+    def _is_out_of_range(self) -> bool:
+        """Check if date is outside valid calendar range (1900-2100)."""
+        return self.year < MIN_YEAR or self.year > MAX_YEAR
+
+    @store_calendar
+    def add(self, years: int = 0, months: int = 0, weeks: int = 0, days: int = 0, **kwargs) -> Self:
+        """Add time periods to the current date or datetime.
+
+        Extends pendulum's add method with business day awareness. When in business mode,
+        only counts business days for the 'days' parameter.
+
+        Parameters
+            years: Number of years to add
+            months: Number of months to add
+            weeks: Number of weeks to add
+            days: Number of days to add (business days if in business mode)
+            **kwargs: Additional time units to add
+
+        Returns
+            New instance with added time
+        """
+        _business = self._business
+        self._business = False
+        if _business:
+            if days == 0:
+                return self._business_or_next()
+            if days < 0:
+                return self.business().subtract(days=abs(days))
+            if self._is_out_of_range() and self.year > MAX_YEAR:
+                return self
+            target = self._business_or_next() if self._is_out_of_range() else self
+            result = target._add_business_days(days)
+            return result if result is not None else self
+        return super().add(years, months, weeks, days, **kwargs)
+
+    @store_calendar
+    def subtract(self, years: int = 0, months: int = 0, weeks: int = 0, days: int = 0, **kwargs) -> Self:
+        """Subtract wrapper
+        If not business use Pendulum
+        If business assume only days (for now) and use local logic
+        """
+        _business = self._business
+        self._business = False
+        if _business:
+            if days == 0:
+                return self._business_or_previous()
+            if days < 0:
+                return self.business().add(days=abs(days))
+            target = self._business_or_previous() if self._is_out_of_range() else self
+            result = target._add_business_days(-days)
+            return result if result is not None else self
+        kwargs = {k: -1*v for k, v in kwargs.items()}
+        return super().add(-years, -months, -weeks, -days, **kwargs)
+
+    @store_calendar
+    def first_of(self, unit: str, day_of_week: WeekDay | None = None) -> Self:
+        """Returns an instance set to the first occurrence
+        of a given day of the week in the current unit.
+        """
+        _business = self._business
+        self._business = False
+        self = super().first_of(unit, day_of_week)
+        if _business:
+            self = self._business_or_next()
+        return self
+
+    @store_calendar
+    def last_of(self, unit: str, day_of_week: WeekDay | None = None) -> Self:
+        """Returns an instance set to the last occurrence
+        of a given day of the week in the current unit.
+        """
+        _business = self._business
+        self._business = False
+        self = super().last_of(unit, day_of_week)
+        if _business:
+            self = self._business_or_previous()
+        return self
+
+    @store_calendar
+    def start_of(self, unit: str) -> Self:
+        """Returns a copy of the instance with the time reset
+        """
+        _business = self._business
+        self._business = False
+        self = super().start_of(unit)
+        if _business:
+            self = self._business_or_next()
+        return self
+
+    @store_calendar
+    def end_of(self, unit: str) -> Self:
+        """Returns a copy of the instance with the time reset
+        """
+        _business = self._business
+        self._business = False
+        self = super().end_of(unit)
+        if _business:
+            self = self._business_or_previous()
+        return self
+
+    @store_calendar
+    def previous(self, day_of_week: WeekDay | None = None) -> Self:
+        """Modify to the previous occurrence of a given day of the week.
+
+        In business mode, snaps BACKWARD to maintain 'previous' semantics.
+        """
+        _business = self._business
+        self._business = False
+        self = super().previous(day_of_week)
+        if _business:
+            self = self._business_or_previous()
+        return self
+
+    @store_calendar
+    def next(self, day_of_week: WeekDay | None = None) -> Self:
+        """Modify to the next occurrence of a given day of the week.
+
+        In business mode, snaps FORWARD to maintain 'next' semantics.
+        """
+        _business = self._business
+        self._business = False
+        self = super().next(day_of_week)
+        if _business:
+            self = self._business_or_next()
+        return self
+
+    @expect_date
+    def is_business_day(self) -> bool:
+        """Check if the date is a business day according to the calendar.
+
+        Returns False for dates outside valid calendar range (1900-2100).
+        """
+        if self._is_out_of_range():
+            return False
+        cal = self._active_calendar._get_calendar(self)
+        if cal is None:
+            return False
+        return cal.is_business_day(self.toordinal())
+
+    # Alias for backwards compatibility
+    business_open = is_business_day
+
+    @expect_date
+    def business_hours(self) -> tuple[DateTime, DateTime]:
+        """Get market open and close times for this date.
+
+        Returns (None, None) if not a business day.
+        """
+        return self._active_calendar.business_hours(self, self)\
+            .get(self, (None, None))
+
+    def _add_business_days(self, days: int) -> Self | None:
+        """Add business days using Rust calendar.
+
+        Returns self unchanged for dates outside valid range (1900-2100).
+        """
+        if self._is_out_of_range():
+            return self
+        cal = self._active_calendar._get_calendar(self)
+        if cal is None:
+            return None
+        start_ord = self.toordinal()
+        forward = days > 0
+        offset = 1 if forward else -1
+        first_bd = (cal.next_business_day if forward else cal.prev_business_day)(start_ord + offset)
+        if first_bd is None:
+            return None
+        result_ord = cal.add_business_days(first_bd, (abs(days) - 1) * offset)
+        if result_ord is None:
+            return None
+        return super().add(days=result_ord - start_ord)
+
+    @store_calendar
+    def _snap_to_business_day(self, forward: bool = True) -> Self:
+        """Snap to nearest business day if not already on one.
+
+        For dates outside valid range (1900-2100):
+        - If forward=False and year > 2100: snap to last business day of 2100
+        - If forward=True and year < 1900: snap to first business day of 1900
+        - Otherwise return self unchanged
+        """
+        self._business = False
+        if self._is_out_of_range():
+            from opendate.date_ import Date
+            if self.year > MAX_YEAR and not forward:
+                boundary = Date(MAX_YEAR, 12, 31)
+                boundary._calendar = self._calendar
+                return boundary._snap_to_business_day(forward=False)
+            elif self.year < MIN_YEAR and forward:
+                boundary = Date(MIN_YEAR, 1, 1)
+                boundary._calendar = self._calendar
+                return boundary._snap_to_business_day(forward=True)
+            return self
+        cal = self._active_calendar._get_calendar(self)
+        if cal is None:
+            return self
+        if self.is_business_day():
+            return self
+        ordinal = self.toordinal()
+        target = cal.next_business_day(ordinal) if forward else cal.prev_business_day(ordinal)
+        if target is None:
+            return self
+        return super().add(days=target - ordinal)
+
+    def _business_or_next(self) -> Self:
+        return self._snap_to_business_day(forward=True)
+
+    def _business_or_previous(self) -> Self:
+        return self._snap_to_business_day(forward=False)

opendate/mixins/extras_.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from opendate.constants import WEEKDAY_SHORTNAME, WeekDay
+from opendate.decorators import store_calendar
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+if TYPE_CHECKING:
+    pass
+
+
+class DateExtrasMixin:
+    """Extended date functionality not provided by Pendulum.
+
+    .. note::
+        This mixin exists primarily for legacy backward compatibility.
+        New code should prefer using built-in methods where possible.
+
+    This mixin provides additional date utilities primarily focused on:
+    - Financial date calculations (nearest month start/end)
+    - Weekday-oriented date navigation
+    - Relative date lookups
+
+    These methods extend OpenDate functionality with features commonly
+    needed in financial applications and reporting scenarios.
+    """
+
+    @store_calendar
+    def nearest_start_of_month(self) -> Self:
+        """Get the nearest start of month.
+
+        If day <= 15, returns start of current month.
+        If day > 15, returns start of next month.
+        In business mode, snaps to next business day if needed.
+        """
+        _business = self._business
+        self._business = False
+        if self.day > 15:
+            d = self.end_of('month').add(days=1)  # First of next month
+        else:
+            d = self.start_of('month')  # First of current month
+        if _business:
+            d = d._business_or_next()
+        return d
+
+    @store_calendar
+    def nearest_end_of_month(self) -> Self:
+        """Get the nearest end of month.
+
+        If day <= 15, returns end of previous month.
+        If day > 15, returns end of current month.
+        In business mode, snaps to previous business day if needed.
+        """
+        _business = self._business
+        self._business = False
+        if self.day <= 15:
+            d = self.start_of('month').subtract(days=1)  # End of previous month
+        else:
+            d = self.end_of('month')  # End of current month
+        if _business:
+            d = d._business_or_previous()
+        return d
+
+    def next_relative_date_of_week_by_day(self, day='MO') -> Self:
+        """Get next occurrence of the specified weekday (or current date if already that day).
+        """
+        if self.weekday() == WEEKDAY_SHORTNAME.get(day):
+            return self
+        return self.next(WEEKDAY_SHORTNAME.get(day))
+
+    def weekday_or_previous_friday(self) -> Self:
+        """Return the date if it is a weekday, otherwise return the previous Friday.
+        """
+        if self.weekday() in {WeekDay.SATURDAY, WeekDay.SUNDAY}:
+            return self.previous(WeekDay.FRIDAY)
+        return self
+
+    @classmethod
+    def third_wednesday(cls, year, month) -> Self:
+        """Calculate the date of the third Wednesday in a given month/year.
+
+        .. deprecated::
+            Use Date(year, month, 1).nth_of('month', 3, WeekDay.WEDNESDAY) instead.
+
+        Parameters
+            year: The year to use
+            month: The month to use (1-12)
+
+        Returns
+            A Date object representing the third Wednesday of the specified month
+        """
+        return cls(year, month, 1).nth_of('month', 3, WeekDay.WEDNESDAY)

opendate/time_.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import datetime as _datetime
+import sys
+import time
+import zoneinfo as _zoneinfo
+
+import numpy as np
+import pandas as pd
+import pendulum as _pendulum
+
+from opendate.constants import UTC
+from opendate.decorators import prefer_utc_timezone
+from opendate.helpers import _rust_parse_time
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+
+class Time(_pendulum.Time):
+    """Time class extending pendulum.Time with additional functionality.
+
+    This class inherits all pendulum.Time functionality while adding:
+    - Enhanced parsing for various time formats
+    - Default UTC timezone when created
+    - Simple timezone conversion utilities
+
+    Unlike pendulum.Time, this class has more lenient parsing capabilities
+    and different timezone defaults.
+    """
+
+    @classmethod
+    @prefer_utc_timezone
+    def parse(cls, s: str | None, fmt: str | None = None, raise_err: bool = False) -> Self | None:
+        """Parse time string in various formats.
+
+        Supported formats:
+        - hh:mm or hh.mm
+        - hh:mm:ss or hh.mm.ss
+        - hh:mm:ss.microseconds
+        - Any of above with AM/PM
+        - Compact: hhmmss or hhmmss.microseconds
+
+        Returns Time with UTC timezone by default.
+
+        Parameters
+            s: String to parse or None
+            fmt: Optional strftime format string for custom parsing
+            raise_err: If True, raises ValueError on parse failure instead of returning None
+
+        Returns
+            Time instance with UTC timezone or None if parsing fails and raise_err is False
+
+        Examples
+            Basic time formats:
+            Time.parse('14:30') → Time(14, 30, 0, 0, tzinfo=UTC)
+            Time.parse('14.30') → Time(14, 30, 0, 0, tzinfo=UTC)
+            Time.parse('14:30:45') → Time(14, 30, 45, 0, tzinfo=UTC)
+
+            With microseconds:
+            Time.parse('14:30:45.123456') → Time(14, 30, 45, 123456000, tzinfo=UTC)
+            Time.parse('14:30:45,500000') → Time(14, 30, 45, 500000000, tzinfo=UTC)
+
+            AM/PM formats:
+            Time.parse('2:30 PM') → Time(14, 30, 0, 0, tzinfo=UTC)
+            Time.parse('11:30 AM') → Time(11, 30, 0, 0, tzinfo=UTC)
+            Time.parse('12:30 PM') → Time(12, 30, 0, 0, tzinfo=UTC)
+
+            Compact formats:
+            Time.parse('143045') → Time(14, 30, 45, 0, tzinfo=UTC)
+            Time.parse('1430') → Time(14, 30, 0, 0, tzinfo=UTC)
+
+            Custom format:
+            Time.parse('14-30-45', fmt='%H-%M-%S') → Time(14, 30, 45, 0, tzinfo=UTC)
+        """
+        if not s:
+            if raise_err:
+                raise ValueError('Empty value')
+            return
+
+        if not isinstance(s, str):
+            raise TypeError(f'Invalid type for time parse: {s.__class__}')
+
+        if fmt:
+            try:
+                return cls(*time.strptime(s, fmt)[3:6])
+            except (ValueError, TypeError):
+                if raise_err:
+                    raise ValueError(f'Unable to parse {s} using fmt {fmt}')
+                return
+
+        result = _rust_parse_time(s)
+        if result is not None:
+            hour, minute, second, microsecond = result
+            return cls(hour, minute, second, microsecond)
+
+        if raise_err:
+            raise ValueError('Failed to parse time: %s', s)
+
+    @classmethod
+    def instance(
+        cls,
+        obj: _datetime.time
+        | _datetime.datetime
+        | pd.Timestamp
+        | np.datetime64
+        | Self
+        | None,
+        tz: str | _zoneinfo.ZoneInfo | _datetime.tzinfo | None = None,
+        raise_err: bool = False,
+    ) -> Self | None:
+        """Create Time instance from time-like object.
+
+        Adds UTC timezone by default unless obj is already a Time instance.
+        """
+        if pd.isna(obj):
+            if raise_err:
+                raise ValueError('Empty value')
+            return
+
+        if type(obj) is cls and not tz:
+            return obj
+
+        tz = tz or obj.tzinfo or UTC
+
+        return cls(obj.hour, obj.minute, obj.second, obj.microsecond, tzinfo=tz)
+
+    def in_timezone(self, tz: str | _zoneinfo.ZoneInfo | _datetime.tzinfo) -> Self:
+        """Convert time to a different timezone.
+        """
+        from opendate.date_ import Date
+        from opendate.datetime_ import DateTime
+
+        _dt = DateTime.combine(Date.today(), self, tzinfo=self.tzinfo or UTC)
+        return _dt.in_timezone(tz).time()
+
+    in_tz = in_timezone