opendate 0.1.12__py3-none-any.whl → 0.1.19__py3-none-any.whl

date/date.py

@@ -2,13 +2,14 @@ import calendar
 import contextlib
 import datetime as _datetime
 import logging
+import operator
 import os
 import re
 import time
 import warnings
 import zoneinfo as _zoneinfo
 from abc import ABC, abstractmethod
-from collections.abc import Callable, Sequence
+from collections.abc import Callable, Iterator, Sequence
 from functools import lru_cache, partial, wraps
 from typing import Self
 
@@ -26,7 +27,6 @@ __all__ = [
     'Date',
     'DateTime',
     'Interval',
-    'IntervalError',
     'Time',
     'Timezone',
     'EST',
@@ -39,35 +39,20 @@ __all__ = [
     'prefer_utc_timezone',
     'expect_date',
     'expect_datetime',
+    'expect_time',
     'Entity',
-    'NYSE'
+    'NYSE',
     'WEEKDAY_SHORTNAME',
+    'WeekDay',
     ]
 
 
 def Timezone(name:str = 'US/Eastern') -> _zoneinfo.ZoneInfo:
-    """Simple wrapper around Pendulum `Timezone`
-
-    Ex: sanity check US/Eastern == America/New_York
-
-    >>> winter1 = DateTime(2000, 1, 1, 12, tzinfo=Timezone('US/Eastern'))
-    >>> winter2 = DateTime(2000, 1, 1, 12, tzinfo=Timezone('America/New_York'))
-
-    >>> summer1 = DateTime(2000, 7, 1, 12, tzinfo=Timezone('US/Eastern'))
-    >>> summer2 = DateTime(2000, 7, 1, 12, tzinfo=Timezone('America/New_York'))
-
-    >>> winter = [winter1, winter2,
-    ... winter1.astimezone(Timezone('America/New_York')),
-    ... winter2.astimezone(Timezone('US/Eastern')),
-    ... ]
-    >>> assert all(x==winter[0] for x in winter)
-
-    >>> summer = [summer1, summer2,
-    ... summer1.astimezone(Timezone('America/New_York')),
-    ... summer2.astimezone(Timezone('US/Eastern')),
-    ... ]
-    >>> assert all(x==summer[0] for x in summer)
+    """Create a timezone object with the specified name.
 
+    Simple wrapper around Pendulum's Timezone function that ensures
+    consistent timezone handling across the library. Note that 'US/Eastern'
+    is equivalent to 'America/New_York' for all dates.
     """
     return _pendulum.tz.Timezone(name)
 
@@ -123,8 +108,8 @@ DATEMATCH = re.compile(r'^(?P<d>N|T|Y|P|M)(?P<n>[-+]?\d+)?(?P<b>b?)?$')
     # return entity
 
 
-def isdateish(x):
-    return isinstance(x, _datetime.date | _datetime.datetime | pd.Timestamp | np.datetime64)
+def isdateish(x) -> bool:
+    return isinstance(x, _datetime.date | _datetime.datetime | _datetime.time | pd.Timestamp | np.datetime64)
 
 
 def parse_arg(typ, arg):
@@ -162,6 +147,9 @@ def expect(func, typ: type[_datetime.date], exclkw: bool = False) -> Callable:
                         continue
                     if typ == _datetime.date:
                         kwargs[k] = Date.instance(v)
+                        continue
+                    if typ == _datetime.time:
+                        kwargs[k] = Time.instance(v)
         return func(*args, **kwargs)
     return wrapper
 
@@ -172,8 +160,17 @@ expect_time = partial(expect, typ=_datetime.time)
 
 
 def type_class(typ, obj):
+    if isinstance(typ, str):
+        if typ == 'Date':
+            return Date
+        if typ == 'DateTime':
+            return DateTime
+        if typ == 'Interval':
+            return Interval
     if typ:
         return typ
+    if obj.__class__ in {_pendulum.Interval, Interval}:
+        return Interval
     if obj.__class__ in {_datetime.datetime, _pendulum.DateTime, DateTime}:
         return DateTime
     if obj.__class__ in {_datetime.date, _pendulum.Date, Date}:
@@ -207,7 +204,21 @@ def store_both(func=None, *, typ=None):
     return wrapper
 
 
-def prefer_utc_timezone(func, force:bool = False):
+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 prefer_utc_timezone(func, force:bool = False) -> Callable:
     """Return datetime as UTC.
     """
     @wraps(func)
@@ -221,7 +232,7 @@ def prefer_utc_timezone(func, force:bool = False):
     return wrapper
 
 
-def prefer_native_timezone(func, force:bool = False):
+def prefer_native_timezone(func, force:bool = False) -> Callable:
     """Return datetime as native.
     """
     @wraps(func)
@@ -240,7 +251,15 @@ expect_utc_timezone = partial(prefer_utc_timezone, force=True)
 
 
 class Entity(ABC):
-    """ABC for named entity types"""
+    """Abstract base class for calendar entities with business day definitions.
+
+    This class defines the interface for calendar entities that provide
+    business day information, such as market open/close times and holidays.
+    Not available in pendulum.
+
+    Concrete implementations (like NYSE) provide specific calendar rules
+    for different business contexts.
+    """
 
     tz = UTC
 
@@ -261,7 +280,15 @@ class Entity(ABC):
 
 
 class NYSE(Entity):
-    """New York Stock Exchange"""
+    """New York Stock Exchange calendar entity.
+
+    Provides business day definitions, market hours, and holidays
+    according to the NYSE trading calendar. Uses pandas_market_calendars
+    for the underlying implementation.
+
+    This entity is used as the default for business day calculations
+    throughout the library.
+    """
 
     BEGDATE = _datetime.date(1900, 1, 1)
     ENDDATE = _datetime.date(2200, 1, 1)
@@ -289,31 +316,74 @@ class NYSE(Entity):
     def business_holidays(begdate=BEGDATE, enddate=ENDDATE) -> set:
         return {Date.instance(d.date())
                 for d in map(pd.to_datetime, NYSE.calendar.holidays().holidays)
-                if begdate <= d <= enddate}
+                if begdate <= d.date() <= enddate}
 
 
 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 entity.
+
+    Features not available in pendulum:
+    - Business day mode toggle
+    - Entity-specific calendar rules
+    - Business-aware date arithmetic
+    """
 
     _entity: type[NYSE] = NYSE
     _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 entity (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 entity(self, entity: type[NYSE] = NYSE) -> Self:
+        """Set the calendar entity for business day calculations.
+
+        Parameters
+            entity: Calendar entity class (defaults to NYSE)
+
+        Returns
+            Self instance for method chaining
+        """
         self._entity = entity
         return self
 
     @store_entity
     def add(self, years: int = 0, months: int = 0, weeks: int = 0, days: int = 0, **kwargs) -> Self:
-        """Add wrapper
-        If not business use Pendulum
-        If business assume only days (for now) and use local logic
+        """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
@@ -418,63 +488,21 @@ class DateBusinessMixin:
 
     @expect_date
     def business_open(self) -> bool:
-        """Business open
-
-        >>> thedate = Date(2021, 4, 19) # Monday
-        >>> thedate.business_open()
-        True
-        >>> thedate = Date(2021, 4, 17) # Saturday
-        >>> thedate.business_open()
-        False
-        >>> thedate = Date(2021, 1, 18) # MLK Day
-        >>> thedate.business_open()
-        False
+        """Check if the date is a business day (market is open).
         """
         return self.is_business_day()
 
     @expect_date
     def is_business_day(self) -> bool:
-        """Is business date.
-
-        >>> thedate = Date(2021, 4, 19) # Monday
-        >>> thedate.is_business_day()
-        True
-        >>> thedate = Date(2021, 4, 17) # Saturday
-        >>> thedate.is_business_day()
-        False
-        >>> thedate = Date(2021, 1, 18) # MLK Day
-        >>> thedate.is_business_day()
-        False
-        >>> thedate = Date(2021, 11, 25) # Thanksgiving
-        >>> thedate.is_business_day()
-        False
-        >>> thedate = Date(2021, 11, 26) # Day after ^
-        >>> thedate.is_business_day()
-        True
+        """Check if the date is a business day according to the entity calendar.
         """
         return self in self._entity.business_days()
 
     @expect_date
     def business_hours(self) -> 'tuple[DateTime, DateTime]':
-        """Business hours
-
-        Returns (None, None) if not a business day
+        """Get market open and close times for this date.
 
-        >>> thedate = Date(2023, 1, 5)
-        >>> thedate.business_hours()
-        (... 9, 30, ... 16, 0, ...)
-
-        >>> thedate = Date(2023, 7, 3)
-        >>> thedate.business_hours()
-        (... 9, 30, ... 13, 0, ...)
-
-        >>> thedate = Date(2023, 11, 24)
-        >>> thedate.business_hours()
-        (... 9, 30, ... 13, 0, ...)
-
-        >>> thedate = Date(2024, 5, 27) # memorial day
-        >>> thedate.business_hours()
-        (None, None)
+        Returns (None, None) if not a business day.
         """
         return self._entity.business_hours(self, self)\
             .get(self, (None, None))
@@ -521,35 +549,27 @@ class DateBusinessMixin:
 
 
 class DateExtrasMixin:
-    """Legacy support functionality well outside the
-    scope of Pendulum. Ideally these should be removed.
+    """Extended date functionality not provided by Pendulum.
 
-    See how pendulum does end_of and next_ with getattr
+    .. note::
+        This mixin exists primarily for legacy backward compatibility.
+        New code should prefer using built-in methods where possible.
 
-    Create a nearest [start_of, end_of] [week, day, month, quarter, year]
+    This mixin provides additional date utilities primarily focused on:
+    - Financial date calculations (nearest month start/end)
+    - Weekday-oriented date navigation
+    - Relative date lookups
 
-    combo that accounts for whatever prefix and unit is passed in
+    These methods extend OpenDate functionality with features commonly
+    needed in financial applications and reporting scenarios.
     """
 
-    def nearest_start_of_month(self):
-        """Get `nearest` start of month
-
-        1/1/2015 -> Thursday (New Year's Day)
-        2/1/2015 -> Sunday
-
-        >>> from date import Date
-        >>> Date(2015, 1, 1).nearest_start_of_month()
-        Date(2015, 1, 1)
-        >>> Date(2015, 1, 15).nearest_start_of_month()
-        Date(2015, 1, 1)
-        >>> Date(2015, 1, 15).b.nearest_start_of_month()
-        Date(2015, 1, 2)
-        >>> Date(2015, 1, 16).nearest_start_of_month()
-        Date(2015, 2, 1)
-        >>> Date(2015, 1, 31).nearest_start_of_month()
-        Date(2015, 2, 1)
-        >>> Date(2015, 1, 31).b.nearest_start_of_month()
-        Date(2015, 2, 2)
+    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, adjusts to next business day if needed.
         """
         _business = self._business
         self._business = False
@@ -563,25 +583,12 @@ class DateExtrasMixin:
             return d.business().add(days=1)
         return d
 
-    def nearest_end_of_month(self):
-        """Get `nearest` end of month
-
-        12/31/2014 -> Wednesday
-        1/31/2015 -> Saturday
-
-        >>> from date import Date
-        >>> Date(2015, 1, 1).nearest_end_of_month()
-        Date(2014, 12, 31)
-        >>> Date(2015, 1, 15).nearest_end_of_month()
-        Date(2014, 12, 31)
-        >>> Date(2015, 1, 15).b.nearest_end_of_month()
-        Date(2014, 12, 31)
-        >>> Date(2015, 1, 16).nearest_end_of_month()
-        Date(2015, 1, 31)
-        >>> Date(2015, 1, 31).nearest_end_of_month()
-        Date(2015, 1, 31)
-        >>> Date(2015, 1, 31).b.nearest_end_of_month()
-        Date(2015, 1, 30)
+    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, adjusts to previous business day if needed.
         """
         _business = self._business
         self._business = False
@@ -595,77 +602,135 @@ class DateExtrasMixin:
             return d.business().subtract(days=1)
         return d
 
-    def next_relative_date_of_week_by_day(self, day='MO'):
-        """Get next relative day of week by relativedelta code
-
-        >>> from date import Date
-        >>> Date(2020, 5, 18).next_relative_date_of_week_by_day('SU')
-        Date(2020, 5, 24)
-        >>> Date(2020, 5, 24).next_relative_date_of_week_by_day('SU')
-        Date(2020, 5, 24)
+    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):
-        """Return the date if it is a weekday, else previous Friday
-
-        >>> from date import Date
-        >>> Date(2019, 10, 6).weekday_or_previous_friday() # Sunday
-        Date(2019, 10, 4)
-        >>> Date(2019, 10, 5).weekday_or_previous_friday() # Saturday
-        Date(2019, 10, 4)
-        >>> Date(2019, 10, 4).weekday_or_previous_friday() # Friday
-        Date(2019, 10, 4)
-        >>> Date(2019, 10, 3).weekday_or_previous_friday() # Thursday
-        Date(2019, 10, 3)
+    def weekday_or_previous_friday(self) -> Self:
+        """Return the date if it is a weekday, otherwise return the previous Friday.
         """
-        dnum = self.weekday()
-        if dnum in {WeekDay.SATURDAY, WeekDay.SUNDAY}:
-            return self.subtract(days=dnum - 4)
+        if self.weekday() in {WeekDay.SATURDAY, WeekDay.SUNDAY}:
+            return self.previous(WeekDay.FRIDAY)
         return self
 
-    """
-    create a simple nth weekday function that accounts for
-    [1,2,3,4] and weekday as options
-    or weekday, [1,2,3,4]
+    @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.
 
-    @classmethod
-    def third_wednesday(cls, year, month):
-        """Third Wednesday date of a given month/year
-
-        >>> from date import Date
-        >>> Date.third_wednesday(2022, 6)
-        Date(2022, 6, 15)
-        >>> Date.third_wednesday(2023, 3)
-        Date(2023, 3, 15)
-        >>> Date.third_wednesday(2022, 12)
-        Date(2022, 12, 21)
-        >>> Date.third_wednesday(2023, 6)
-        Date(2023, 6, 21)
+        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
         """
-        third = cls(year, month, 15)  # lowest 3rd day
-        w = third.weekday()
-        if w != WeekDay.WEDNESDAY:
-            third = third.replace(day=(15 + (WeekDay.WEDNESDAY - w) % 7))
-        return third
+        return cls(year, month, 1).nth_of('month', 3, WeekDay.WEDNESDAY)
 
 
 class Date(DateExtrasMixin, DateBusinessMixin, _pendulum.Date):
-    """Inherits and wraps pendulum.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 cleaner https://stackoverflow.com/a/2073189.
+        """Format date to string, handling platform-specific format codes.
 
-        >>> Date(2022, 1, 5).to_string('%-m/%-d/%Y')
-        '1/5/2022'
+        Automatically converts '%-' format codes to '%#' on Windows.
         """
         return self.strftime(fmt.replace('%-', '%#') if os.name == 'nt' else fmt)
 
+    @store_entity(typ='Date')
+    def replace(self, *args, **kwargs):
+        """Replace method that preserves entity and business status.
+        """
+        return _pendulum.Date.replace(self, *args, **kwargs)
+
+    @store_entity(typ='Date')
+    def closest(self, *args, **kwargs):
+        """Closest method that preserves entity and business status.
+        """
+        return _pendulum.Date.closest(self, *args, **kwargs)
+
+    @store_entity(typ='Date')
+    def farthest(self, *args, **kwargs):
+        """Farthest method that preserves entity and business status.
+        """
+        return _pendulum.Date.farthest(self, *args, **kwargs)
+
+    @store_entity(typ='Date')
+    def average(self, dt=None):
+        """Modify the current instance to the average
+        of a given instance (default now) and the current instance.
+
+        Parameters
+            dt: The date to average with (defaults to today)
+
+        Returns
+            A new Date object representing the average date
+        """
+        return _pendulum.Date.average(self, dt)
+
+    @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
+        """
+        # Ensure timezone is always applied to get consistent results
+        tz = tz or UTC
+        dt = _datetime.datetime.fromtimestamp(timestamp, tz=tz)
+        return cls(dt.year, dt.month, dt.day)
+
+    @store_entity(typ='Date')
+    def nth_of(self, unit: str, nth: int, day_of_week: WeekDay) -> Self:
+        """Returns a new instance set to the given occurrence
+        of a given day of the week in the current unit.
+
+        Parameters
+            unit: The unit to use ("month", "quarter", or "year")
+            nth: The position of the day in the unit (1 to 5)
+            day_of_week: The day of the week (pendulum.MONDAY to pendulum.SUNDAY)
+
+        Returns
+            A new Date object for the nth occurrence
+
+        Raises
+            ValueError: If the occurrence can't be found
+        """
+        return _pendulum.Date.nth_of(self, unit, nth, day_of_week)
+
     @classmethod
     def parse(
         cls,
@@ -676,84 +741,47 @@ class Date(DateExtrasMixin, DateBusinessMixin, _pendulum.Date):
     ) -> Self | None:
         """Convert a string to a date handling many different formats.
 
-        creating a new Date object
-        >>> Date.parse('2022/1/1')
-        Date(2022, 1, 1)
-
-        previous business day accessed with 'P'
-        >>> Date.parse('P')==Date.today().b.subtract(days=1)
-        True
-        >>> Date.parse('T-3b')==Date.today().b.subtract(days=3)
-        True
-        >>> Date.parse('T-3b')==Date.today().b.add(days=-3)
-        True
-        >>> Date.parse('T+3b')==Date.today().b.subtract(days=-3)
-        True
-        >>> Date.parse('T+3b')==Date.today().b.add(days=3)
-        True
-        >>> Date.parse('M')==Date.today().start_of('month').subtract(days=1)
-        True
-
-        m[/-]d[/-]yyyy  6-23-2006
-        >>> Date.parse('6-23-2006')
-        Date(2006, 6, 23)
-
-        m[/-]d[/-]yy    6/23/06
-        >>> Date.parse('6/23/06')
-        Date(2006, 6, 23)
-
-        m[/-]d          6/23
-        >>> Date.parse('6/23') == Date(Date.today().year, 6, 23)
-        True
-
-        yyyy-mm-dd      2006-6-23
-        >>> Date.parse('2006-6-23')
-        Date(2006, 6, 23)
-
-        yyyymmdd        20060623
-        >>> Date.parse('20060623')
-        Date(2006, 6, 23)
-
-        dd-mon-yyyy     23-JUN-2006
-        >>> Date.parse('23-JUN-2006')
-        Date(2006, 6, 23)
-
-        mon-dd-yyyy     JUN-23-2006
-        >>> Date.parse('20 Jan 2009')
-        Date(2009, 1, 20)
-
-        month dd, yyyy  June 23, 2006
-        >>> Date.parse('June 23, 2006')
-        Date(2006, 6, 23)
-
-        dd-mon-yy
-        >>> Date.parse('23-May-12')
-        Date(2012, 5, 23)
-
-        ddmonyyyy
-        >>> Date.parse('23May2012')
-        Date(2012, 5, 23)
-
-        >>> Date.parse('Oct. 24, 2007', fmt='%b. %d, %Y')
-        Date(2007, 10, 24)
-
-        >>> Date.parse('Yesterday') == DateTime.now().subtract(days=1).date()
-        True
-        >>> Date.parse('TODAY') == Date.today()
-        True
-        >>> Date.parse('Jan. 13, 2014')
-        Date(2014, 1, 13)
-
-        >>> Date.parse('March') == Date(Date.today().year, 3, Date.today().day)
-        True
-
-        only raise error when we explicitly say so
-        >>> Date.parse('bad date') is None
-        True
-        >>> Date.parse('bad date', raise_err=True)
-        Traceback (most recent call last):
-        ...
-        ValueError: Failed to parse date: bad date
+        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)
+        - Custom format strings via fmt parameter
+
+        Parameters
+            s: String to parse or None
+            fmt: Optional strftime format string for custom parsing
+            entity: Calendar entity 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
+
+            Custom format:
+            Date.parse('15-Jan-2020', fmt='%d-%b-%Y') → Date(2020, 1, 15)
         """
 
         def date_for_symbol(s):
@@ -795,7 +823,7 @@ class Date(DateExtrasMixin, DateBusinessMixin, _pendulum.Date):
                 return
 
         with contextlib.suppress(ValueError):
-            if float(s) and not len(s) == 8: # 20000101
+            if float(s) and len(s) != 8:  # 20000101
                 if raise_err:
                     raise ValueError('Invalid date: %s', s)
                 return
@@ -872,20 +900,17 @@ class Date(DateExtrasMixin, DateBusinessMixin, _pendulum.Date):
         | None,
         raise_err: bool = False,
     ) -> Self | None:
-        """From datetime.date like object
-
-        >>> Date.instance(_datetime.date(2022, 1, 1))
-        Date(2022, 1, 1)
-        >>> Date.instance(Date(2022, 1, 1))
-        Date(2022, 1, 1)
-        >>> Date.instance(_pendulum.Date(2022, 1, 1))
-        Date(2022, 1, 1)
-        >>> Date.instance(Date(2022, 1, 1))
-        Date(2022, 1, 1)
-        >>> Date.instance(np.datetime64('2000-01', 'D'))
-        Date(2000, 1, 1)
-        >>> Date.instance(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:
@@ -901,39 +926,21 @@ class Date(DateExtrasMixin, DateBusinessMixin, _pendulum.Date):
         return cls(obj.year, obj.month, obj.day)
 
     @classmethod
-    def today(cls):
+    def today(cls) -> Self:
         d = _datetime.datetime.now(LCL)
         return cls(d.year, d.month, d.day)
 
-    def isoweek(self):
-        """Week number 1-52 following ISO week-numbering
-
-        Standard weeks
-        >>> Date(2023, 1, 2).isoweek()
-        1
-        >>> Date(2023, 4, 27).isoweek()
-        17
-        >>> Date(2023, 12, 31).isoweek()
-        52
-
-        Belongs to week of previous year
-        >>> Date(2023, 1, 1).isoweek()
-        52
+    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:
-        """Date back based on lookback string, ie last, week, month.
-
-        >>> Date(2018, 12, 7).b.lookback('last')
-        Date(2018, 12, 6)
-        >>> Date(2018, 12, 7).b.lookback('day')
-        Date(2018, 12, 6)
-        >>> Date(2018, 12, 7).b.lookback('week')
-        Date(2018, 11, 30)
-        >>> Date(2018, 12, 7).b.lookback('month')
-        Date(2018, 11, 7)
+        """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
@@ -955,42 +962,60 @@ class Date(DateExtrasMixin, DateBusinessMixin, _pendulum.Date):
 
 
 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:
-        """Convert a string to a time handling many formats::
-
-            handle many time formats:
-            hh[:.]mm
-            hh[:.]mm am/pm
-            hh[:.]mm[:.]ss
-            hh[:.]mm[:.]ss[.,]uuu am/pm
-            hhmmss[.,]uuu
-            hhmmss[.,]uuu am/pm
-
-        >>> Time.parse('9:30')
-        Time(9, 30, 0, tzinfo=Timezone('UTC'))
-        >>> Time.parse('9:30:15')
-        Time(9, 30, 15, tzinfo=Timezone('UTC'))
-        >>> Time.parse('9:30:15.751')
-        Time(9, 30, 15, 751000, tzinfo=Timezone('UTC'))
-        >>> Time.parse('9:30 AM')
-        Time(9, 30, 0, tzinfo=Timezone('UTC'))
-        >>> Time.parse('9:30 pm')
-        Time(21, 30, 0, tzinfo=Timezone('UTC'))
-        >>> Time.parse('9:30:15.751 PM')
-        Time(21, 30, 15, 751000, tzinfo=Timezone('UTC'))
-        >>> Time.parse('0930')  # Date treats this as a date, careful!!
-        Time(9, 30, 0, tzinfo=Timezone('UTC'))
-        >>> Time.parse('093015')
-        Time(9, 30, 15, tzinfo=Timezone('UTC'))
-        >>> Time.parse('093015,751')
-        Time(9, 30, 15, 751000, tzinfo=Timezone('UTC'))
-        >>> Time.parse('0930 pm')
-        Time(21, 30, 0, tzinfo=Timezone('UTC'))
-        >>> Time.parse('093015,751 PM')
-        Time(21, 30, 15, 751000, tzinfo=Timezone('UTC'))
+        """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)
         """
 
         def seconds(m):
@@ -1060,18 +1085,9 @@ class Time(_pendulum.Time):
         tz: str | _zoneinfo.ZoneInfo | _datetime.tzinfo | None = None,
         raise_err: bool = False,
     ) -> Self | None:
-        """From datetime-like object
-
-        >>> Time.instance(_datetime.time(12, 30, 1))
-        Time(12, 30, 1, tzinfo=Timezone('UTC'))
-        >>> Time.instance(_pendulum.Time(12, 30, 1))
-        Time(12, 30, 1, tzinfo=Timezone('UTC'))
-        >>> Time.instance(None)
-
-        like Pendulum, do not add timzone if no timezone and Time object
-        >>> Time.instance(Time(12, 30, 1))
-        Time(12, 30, 1)
+        """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:
@@ -1085,15 +1101,8 @@ class Time(_pendulum.Time):
 
         return cls(obj.hour, obj.minute, obj.second, obj.microsecond, tzinfo=tz)
 
-    def in_timezone(self, tz: str | _zoneinfo.ZoneInfo | _datetime.tzinfo):
-        """Convert timezone
-
-        >>> Time(12, 0).in_timezone(Timezone('America/Sao_Paulo'))
-        Time(9, 0, 0, tzinfo=Timezone('America/Sao_Paulo'))
-
-        >>> Time(12, 0, tzinfo=Timezone('Europe/Moscow')).in_timezone(Timezone('America/Sao_Paulo'))
-        Time(6, 0, 0, tzinfo=Timezone('America/Sao_Paulo'))
-
+    def in_timezone(self, tz: str | _zoneinfo.ZoneInfo | _datetime.tzinfo) -> Self:
+        """Convert time to a different timezone.
         """
         _dt = DateTime.combine(Date.today(), self, tzinfo=self.tzinfo or UTC)
         return _dt.in_timezone(tz).time()
@@ -1102,14 +1111,114 @@ class Time(_pendulum.Time):
 
 
 class DateTime(DateBusinessMixin, _pendulum.DateTime):
-    """Inherits and wraps pendulum.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):
+    def epoch(self) -> float:
         """Translate a datetime object into unix seconds since epoch
         """
         return self.timestamp()
 
+    @store_entity(typ='DateTime')
+    def astimezone(self, *args, **kwargs):
+        """Convert to a timezone-aware datetime in a different timezone.
+        """
+        return _pendulum.DateTime.astimezone(self, *args, **kwargs)
+
+    @store_entity(typ='DateTime')
+    def in_timezone(self, *args, **kwargs):
+        """Convert to a timezone-aware datetime in a different timezone.
+        """
+        return _pendulum.DateTime.in_timezone(self, *args, **kwargs)
+
+    @store_entity(typ='DateTime')
+    def in_tz(self, *args, **kwargs):
+        """Convert to a timezone-aware datetime in a different timezone.
+        """
+        return _pendulum.DateTime.in_tz(self, *args, **kwargs)
+
+    @store_entity(typ='DateTime')
+    def replace(self, *args, **kwargs):
+        """Replace method that preserves entity and business status.
+        """
+        return _pendulum.DateTime.replace(self, *args, **kwargs)
+
+    @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.
@@ -1126,12 +1235,21 @@ class DateTime(DateBusinessMixin, _pendulum.DateTime):
                    d.microsecond, tzinfo=d.tzinfo, fold=d.fold)
 
     @classmethod
-    def today(cls, tz: str | _zoneinfo.ZoneInfo | None = None):
-        """Unlike Pendulum, returns DateTime object at start of day
+    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):
+    def date(self) -> Date:
         return Date(self.year, self.month, self.day)
 
     @classmethod
@@ -1146,25 +1264,13 @@ class DateTime(DateBusinessMixin, _pendulum.DateTime):
         _tzinfo = tzinfo or time.tzinfo
         return DateTime.instance(_datetime.datetime.combine(date, time, tzinfo=_tzinfo))
 
-    def rfc3339(self):
-        """
-        >>> DateTime.parse('Fri, 31 Oct 2014 10:55:00')
-        DateTime(2014, 10, 31, 10, 55, 0, tzinfo=Timezone('UTC'))
-        >>> DateTime.parse('Fri, 31 Oct 2014 10:55:00').rfc3339()
-        '2014-10-31T10:55:00+00:00'
+    def rfc3339(self) -> str:
+        """Return RFC 3339 formatted string (same as isoformat()).
         """
         return self.isoformat()
 
-    def time(self):
-        """Extract time from self (preserve timezone)
-
-        >>> d = DateTime(2022, 1, 1, 12, 30, 15, tzinfo=EST)
-        >>> d.time()
-        Time(12, 30, 15, tzinfo=Timezone('US/Eastern'))
-
-        >>> d = DateTime(2022, 1, 1, 12, 30, 15, tzinfo=UTC)
-        >>> d.time()
-        Time(12, 30, 15, tzinfo=Timezone('UTC'))
+    def time(self) -> Time:
+        """Extract time component from datetime (preserving timezone).
         """
         return Time.instance(self)
 
@@ -1174,38 +1280,46 @@ class DateTime(DateBusinessMixin, _pendulum.DateTime):
         entity: Entity = NYSE,
         raise_err: bool = False
         ) -> Self | None:
-        """Thin layer on Date parser and our custom `Date.parse``
-
-        >>> DateTime.parse('2022/1/1')
-        DateTime(2022, 1, 1, 0, 0, 0, tzinfo=Timezone('...'))
-
-        Assume UTC, convert to EST
-        >>> this_est1 = DateTime.parse('Fri, 31 Oct 2014 18:55:00').in_timezone(EST)
-        >>> this_est1
-        DateTime(2014, 10, 31, 14, 55, 0, tzinfo=Timezone('US/Eastern'))
-
-        This is actually 18:55 UTC with -4 hours applied = EST
-        >>> this_est2 = DateTime.parse('Fri, 31 Oct 2014 14:55:00 -0400')
-        >>> this_est2
-        DateTime(2014, 10, 31, 14, 55, 0, tzinfo=...)
-
-        UTC time technically equals GMT
-        >>> this_utc = DateTime.parse('Fri, 31 Oct 2014 18:55:00 GMT')
-        >>> this_utc
-        DateTime(2014, 10, 31, 18, 55, 0, tzinfo=tzutc())
-
-        We can freely compare time zones
-        >>> this_est1==this_est2==this_utc
-        True
-
-        Format tests
-        >>> DateTime.parse(1707856982).replace(tzinfo=UTC).epoch()
-        1707856982.0
-        >>> DateTime.parse('Jan 29  2010')
-        DateTime(2010, 1, 29, 0, 0, 0, tzinfo=Timezone('UTC'))
-        >>> _ = DateTime.parse('Sep 27 17:11')
-        >>> _.month, _.day, _.hour, _.minute
-        (9, 27, 17, 11)
+        """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
+            entity: Calendar entity 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
         """
         if not s:
             if raise_err:
@@ -1216,6 +1330,8 @@ class DateTime(DateBusinessMixin, _pendulum.DateTime):
             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
             iso = _datetime.datetime.fromtimestamp(s).isoformat()
             return cls.parse(iso).replace(tzinfo=LCL)
 
@@ -1254,41 +1370,23 @@ class DateTime(DateBusinessMixin, _pendulum.DateTime):
         tz: str | _zoneinfo.ZoneInfo | _datetime.tzinfo | None = None,
         raise_err: bool = False,
     ) -> Self | None:
-        """From datetime-like object
-
-        >>> DateTime.instance(_datetime.date(2022, 1, 1))
-        DateTime(2022, 1, 1, 0, 0, 0, tzinfo=Timezone('...'))
-        >>> DateTime.instance(Date(2022, 1, 1))
-        DateTime(2022, 1, 1, 0, 0, 0, tzinfo=Timezone('...'))
-        >>> DateTime.instance(_datetime.datetime(2022, 1, 1, 0, 0, 0))
-        DateTime(2022, 1, 1, 0, 0, 0, tzinfo=Timezone('...'))
-        >>> DateTime.instance(_pendulum.DateTime(2022, 1, 1, 0, 0, 0))
-        DateTime(2022, 1, 1, 0, 0, 0, tzinfo=Timezone('...'))
-        >>> DateTime.instance(None)
-
-        like Pendulum, do not add timzone if no timezone and DateTime object
-        >>> DateTime.instance(DateTime(2022, 1, 1, 0, 0, 0))
-        DateTime(2022, 1, 1, 0, 0, 0)
-        >>> DateTime.instance(DateTime(2000, 1, 1))
-        DateTime(2000, 1, 1, 0, 0, 0)
-
-        no tz -> UTC
-        >>> DateTime.instance(Time(4, 4, 21))
-        DateTime(..., 4, 4, 21, tzinfo=Timezone('UTC'))
-
-        tzinfo on time -> time tzinfo (precedence)
-        >>> DateTime.instance(Time(4, 4, 21, tzinfo=UTC))
-        DateTime(..., 4, 4, 21, tzinfo=Timezone('UTC'))
-        >>> DateTime.instance(Time(4, 4, 21, tzinfo=LCL))
-        DateTime(..., 4, 4, 21, tzinfo=Timezone('...'))
-
-        >>> DateTime.instance(np.datetime64('2000-01', 'D'))
-        DateTime(2000, 1, 1, 0, 0, 0, tzinfo=Timezone('UTC'))
-
-        Convert date to datetime (will use native time zone)
-        >>> DateTime.instance(_datetime.date(2000, 1, 1))
-        DateTime(2000, 1, 1, 0, 0, 0, tzinfo=Timezone('...'))
+        """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
         """
         if pd.isna(obj):
             if raise_err:
@@ -1321,25 +1419,91 @@ class DateTime(DateBusinessMixin, _pendulum.DateTime):
                    obj.second, obj.microsecond, tzinfo=tz)
 
 
-class IntervalError(AttributeError):
-    pass
+class Interval(_pendulum.Interval):
+    """Interval class extending pendulum.Interval with business day awareness.
 
+    This class represents the difference between two dates or datetimes with
+    additional support for business day calculations, entity awareness, and
+    financial period calculations.
 
-class Interval:
+    Unlike pendulum.Interval:
+    - Has business day mode that only counts business days
+    - Preserves entity association (e.g., NYSE)
+    - Additional financial methods like yearfrac()
+    - Support for range operations that respect business days
+    """
 
     _business: bool = False
     _entity: type[NYSE] = NYSE
 
-    def __init__(self, begdate: str | Date | None = None, enddate: str | Date | None = None):
-        self.begdate = Date.parse(begdate) if isinstance(begdate, str) else Date.instance(begdate)
-        self.enddate = Date.parse(enddate) if isinstance(enddate, str) else Date.instance(enddate)
+    def __new__(cls, begdate: Date | DateTime, enddate: Date | DateTime) -> Self:
+        assert begdate and enddate, 'Interval dates cannot be None'
+        instance = super().__new__(cls, begdate, enddate, False)
+        return instance
+
+    def __init__(self, begdate: Date | DateTime, enddate: Date | DateTime) -> None:
+        super().__init__(begdate, enddate, False)
+        self._sign = 1 if begdate <= enddate else -1
+        if begdate <= enddate:
+            self._start = begdate
+            self._end = enddate
+        else:
+            self._start = enddate
+            self._end = begdate
+
+    @staticmethod
+    def _get_quarter_start(date: Date | DateTime) -> Date | DateTime:
+        """Get the start date of the quarter containing the given date.
+        """
+        quarter_month = ((date.month - 1) // 3) * 3 + 1
+        return date.replace(month=quarter_month, day=1)
+
+    @staticmethod
+    def _get_quarter_end(date: Date | DateTime) -> Date | DateTime:
+        """Get the end date of the quarter containing the given date.
+        """
+        quarter_month = ((date.month - 1) // 3) * 3 + 3
+        return date.replace(month=quarter_month).end_of('month')
+
+    def _get_unit_handlers(self, unit: str) -> dict:
+        """Get handlers for the specified time unit.
+
+        Returns a dict with:
+            get_start: Function to get start of period containing date
+            get_end: Function to get end of period containing date
+            advance: Function to advance to next period start
+        """
+        if unit == 'quarter':
+            return {
+                'get_start': self._get_quarter_start,
+                'get_end': self._get_quarter_end,
+                'advance': lambda date: self._get_quarter_start(date.add(months=3)),
+            }
+
+        if unit == 'decade':
+            return {
+                'get_start': lambda date: date.start_of('decade'),
+                'get_end': lambda date: date.end_of('decade'),
+                'advance': lambda date: date.add(years=10).start_of('decade'),
+            }
+
+        if unit == 'century':
+            return {
+                'get_start': lambda date: date.start_of('century'),
+                'get_end': lambda date: date.end_of('century'),
+                'advance': lambda date: date.add(years=100).start_of('century'),
+            }
+
+        return {
+            'get_start': lambda date: date.start_of(unit),
+            'get_end': lambda date: date.end_of(unit),
+            'advance': lambda date: date.add(**{f'{unit}s': 1}).start_of(unit),
+        }
 
     def business(self) -> Self:
         self._business = True
-        if self.begdate:
-            self.begdate.business()
-        if self.enddate:
-            self.enddate.business()
+        self._start.business()
+        self._end.business()
         return self
 
     @property
@@ -1348,249 +1512,120 @@ class Interval:
 
     def entity(self, e: type[NYSE] = NYSE) -> Self:
         self._entity = e
-        if self.begdate:
-            self.enddate._entity = e
-        if self.enddate:
-            self.enddate._entity = e
+        if self._start:
+            self._end._entity = e
+        if self._end:
+            self._end._entity = e
         return self
 
-    def range(self, window=0) -> tuple[_datetime.date, _datetime.date]:
-        """Set date ranges based on begdate, enddate and window.
-
-        The combinations are as follows:
-
-          beg end num    action
-          --- --- ---    ---------------------
-           -   -   -     Error, underspecified
-          set set set    Error, overspecified
-          set set  -
-          set  -   -     end=max date
-           -  set  -     beg=min date
-           -   -  set    end=max date, beg=end - num
-          set  -  set    end=beg + num
-           -  set set    beg=end - num
-
-        Basic/legacy cases
-        >>> Interval(Date(2014, 4, 3), None).b.range(3)
-        (Date(2014, 4, 3), Date(2014, 4, 8))
-        >>> Interval(None, Date(2014, 7, 27)).range(20)
-        (Date(2014, 7, 7), Date(2014, 7, 27))
-        >>> Interval(None, Date(2014, 7, 27)).b.range(20)
-        (Date(2014, 6, 27), Date(2014, 7, 27))
-
-        Do not modify dates if both are provided
-        >>> Interval(Date(2024, 7, 25), Date(2024, 7, 25)).b.range(None)
-        (Date(2024, 7, 25), Date(2024, 7, 25))
-        >>> Interval(Date(2024, 7, 27), Date(2024, 7, 27)).b.range(None)
-        (Date(2024, 7, 27), Date(2024, 7, 27))
-
-        Edge cases (7/27/24 is weekend)
-        >>> Interval(Date(2024, 7, 27), None).b.range(0)
-        (Date(2024, 7, 27), Date(2024, 7, 27))
-        >>> Interval(None, Date(2024, 7, 27)).b.range(0)
-        (Date(2024, 7, 27), Date(2024, 7, 27))
-        >>> Interval(Date(2024, 7, 27), None).b.range(1)
-        (Date(2024, 7, 27), Date(2024, 7, 29))
-        >>> Interval(None, Date(2024, 7, 27)).b.range(1)
-        (Date(2024, 7, 26), Date(2024, 7, 27))
+    def is_business_day_range(self) -> list[bool]:
+        """Generate boolean values indicating whether each day in the range is a business day.
         """
-        begdate, enddate = self.begdate, self.enddate
+        self._business = False
+        for thedate in self.range('days'):
+            yield thedate.is_business_day()
 
-        window = abs(int(window or 0))
+    @reset_business
+    def range(self, unit: str = 'days', amount: int = 1) -> Iterator[DateTime | Date]:
+        """Generate dates/datetimes over the interval.
 
-        if begdate and enddate and window:
-            raise IntervalError('Window requested and begdate and enddate provided')
-        if not begdate and not enddate and not window:
-            raise IntervalError('Missing begdate, enddate, and window')
-        if not begdate and not enddate and window:
-            raise IntervalError('Missing begdate and enddate, window specified')
+        Parameters
+            unit: Time unit ('days', 'weeks', 'months', 'years')
+            amount: Step size (e.g., every N units)
 
-        if begdate and enddate:
-            pass  # do nothing if both provided
-        elif (not begdate and not enddate) or enddate:
-            begdate = enddate.subtract(days=window) if window else enddate
-        else:
-            enddate = begdate.add(days=window) if window else begdate
+        In business mode (for 'days' only), skips non-business days.
+        """
+        _business = self._business
+        parent_range = _pendulum.Interval.range
 
-        enddate._business = False
-        begdate._business = False
+        def _range_generator():
+            if unit != 'days':
+                yield from (type(d).instance(d) for d in parent_range(self, unit, amount))
+                return
 
-        return begdate, enddate
+            if self._sign == 1:
+                op = operator.le
+                this = self._start
+                thru = self._end
+            else:
+                op = operator.ge
+                this = self._end
+                thru = self._start
+
+            while op(this, thru):
+                if _business:
+                    if this.is_business_day():
+                        yield this
+                else:
+                    yield this
+                this = this.add(days=self._sign * amount)
 
-    def is_business_day_series(self) -> list[bool]:
-        """Is business date range.
+        return _range_generator()
 
-        >>> list(Interval(Date(2018, 11, 19), Date(2018, 11, 25)).is_business_day_series())
-        [True, True, True, False, True, False, False]
-        >>> list(Interval(Date(2021, 11, 22),Date(2021, 11, 28)).is_business_day_series())
-        [True, True, True, False, True, False, False]
+    @property
+    @reset_business
+    def days(self) -> int:
+        """Get number of days in the interval (respects business mode and sign).
         """
-        for thedate in self.series():
-            yield thedate.is_business_day()
+        return self._sign * len(tuple(self.range('days'))) - self._sign
 
-    def series(self, window=0):
-        """Get a series of datetime.date objects.
-
-        give the function since and until wherever possible (more explicit)
-        else pass in a window to back out since or until
-        - Window gives window=N additional days. So `until`-`window`=1
-        defaults to include ALL days (not just business days)
-
-        >>> next(Interval(Date(2014,7,16), Date(2014,7,16)).series())
-        Date(2014, 7, 16)
-        >>> next(Interval(Date(2014,7,12), Date(2014,7,16)).series())
-        Date(2014, 7, 12)
-        >>> len(list(Interval(Date(2014,7,12), Date(2014,7,16)).series()))
-        5
-        >>> len(list(Interval(Date(2014,7,12), None).series(window=4)))
-        5
-        >>> len(list(Interval(Date(2014,7,16)).series(window=4)))
-        5
-
-        Weekend and a holiday
-        >>> len(list(Interval(Date(2014,7,3), Date(2014,7,5)).b.series()))
-        1
-        >>> len(list(Interval(Date(2014,7,17), Date(2014,7,16)).series()))
-        Traceback (most recent call last):
-        ...
-        AssertionError: Begdate must be earlier or equal to Enddate
-
-        since != business day and want business days
-        1/[3,10]/2015 is a Saturday, 1/7/2015 is a Wednesday
-        >>> len(list(Interval(Date(2015,1,3), Date(2015,1,7)).b.series()))
-        3
-        >>> len(list(Interval(Date(2015,1,3), None).b.series(window=3)))
-        3
-        >>> len(list(Interval(Date(2015,1,3), Date(2015,1,10)).b.series()))
-        5
-        >>> len(list(Interval(Date(2015,1,3), None).b.series(window=5)))
-        5
-        """
-        window = abs(int(window))
-        since, until = self.begdate, self.enddate
-        _business = self._business
-        assert until or since, 'Since or until is required'
-        if not since and until:
-            since = (until.business() if _business else
-                     until).subtract(days=window)
-        elif since and not until:
-            until = (since.business() if _business else
-                     since).add(days=window)
-        assert since <= until, 'Since date must be earlier or equal to Until date'
-        thedate = since
-        while thedate <= until:
-            if _business:
-                if thedate.is_business_day():
-                    yield thedate
-            else:
-                yield thedate
-            thedate = thedate.add(days=1)
-
-    def start_of_series(self, unit='month') -> list[Date]:
-        """Return a series between and inclusive of begdate and enddate.
-
-        >>> Interval(Date(2018, 1, 5), Date(2018, 4, 5)).start_of_series('month')
-        [Date(2018, 1, 1), Date(2018, 2, 1), Date(2018, 3, 1), Date(2018, 4, 1)]
-        >>> Interval(Date(2018, 4, 30), Date(2018, 7, 30)).start_of_series('month')
-        [Date(2018, 4, 1), Date(2018, 5, 1), Date(2018, 6, 1), Date(2018, 7, 1)]
-        >>> Interval(Date(2018, 1, 5), Date(2018, 4, 5)).start_of_series('week')
-        [Date(2018, 1, 1), Date(2018, 1, 8), ..., Date(2018, 4, 2)]
-        """
-        begdate = self.begdate.start_of(unit)
-        enddate = self.enddate.start_of(unit)
-        interval = _pendulum.interval(begdate, enddate)
-        return [Date.instance(d).start_of(unit) for d in interval.range(f'{unit}s')]
-
-    def end_of_series(self, unit='month') -> list[Date]:
-        """Return a series between and inclusive of begdate and enddate.
-
-        >>> Interval(Date(2018, 1, 5), Date(2018, 4, 5)).end_of_series('month')
-        [Date(2018, 1, 31), Date(2018, 2, 28), Date(2018, 3, 31), Date(2018, 4, 30)]
-        >>> Interval(Date(2018, 4, 30), Date(2018, 7, 30)).end_of_series('month')
-        [Date(2018, 4, 30), Date(2018, 5, 31), Date(2018, 6, 30), Date(2018, 7, 31)]
-        >>> Interval(Date(2018, 1, 5), Date(2018, 4, 5)).end_of_series('week')
-        [Date(2018, 1, 7), Date(2018, 1, 14), ..., Date(2018, 4, 8)]
+    @property
+    def months(self) -> float:
+        """Get number of months in the interval including fractional parts.
+
+        Overrides pendulum's months property to return a float instead of an integer.
+        Calculates fractional months based on actual day counts within partial months.
         """
-        begdate = self.begdate.end_of(unit)
-        enddate = self.enddate.end_of(unit)
-        interval = _pendulum.interval(begdate, enddate)
-        return [Date.instance(d).end_of(unit) for d in interval.range(f'{unit}s')]
+        year_diff = self._end.year - self._start.year
+        month_diff = self._end.month - self._start.month
+        total_months = year_diff * 12 + month_diff
+
+        if self._end.day >= self._start.day:
+            day_diff = self._end.day - self._start.day
+            days_in_month = calendar.monthrange(self._start.year, self._start.month)[1]
+            fraction = day_diff / days_in_month
+        else:
+            total_months -= 1
+            days_in_start_month = calendar.monthrange(self._start.year, self._start.month)[1]
+            day_diff = (days_in_start_month - self._start.day) + self._end.day
+            fraction = day_diff / days_in_start_month
 
-    def days(self) -> int:
-        """Return days between (begdate, enddate] or negative (enddate, begdate].
-
-        >>> Interval(Date(2018, 9, 6), Date(2018, 9, 10)).days()
-        4
-        >>> Interval(Date(2018, 9, 10), Date(2018, 9, 6)).days()
-        -4
-        >>> Interval(Date(2018, 9, 6), Date(2018, 9, 10)).b.days()
-        2
-        >>> Interval(Date(2018, 9, 10), Date(2018, 9, 6)).b.days()
-        -2
+        return self._sign * (total_months + fraction)
+
+    @property
+    def quarters(self) -> float:
+        """Get approximate number of quarters in the interval.
+
+        Note: This is an approximation using day count / 365 * 4.
         """
-        assert self.begdate
-        assert self.enddate
-        if self.begdate == self.enddate:
-            return 0
-        if not self._business:
-            return (self.enddate - self.begdate).days
-        if self.begdate < self.enddate:
-            return len(list(self.series())) - 1
-        _reverse = Interval(self.enddate, self.begdate)
-        _reverse._entity = self._entity
-        _reverse._business = self._business
-        return -len(list(_reverse.series())) + 1
-
-    def quarters(self):
-        """Return the number of quarters between two dates
-        TODO: good enough implementation; refine rules to be heuristically precise
-
-        >>> round(Interval(Date(2020, 1, 1), Date(2020, 2, 16)).quarters(), 2)
-        0.5
-        >>> round(Interval(Date(2020, 1, 1), Date(2020, 4, 1)).quarters(), 2)
-        1.0
-        >>> round(Interval(Date(2020, 1, 1), Date(2020, 7, 1)).quarters(), 2)
-        1.99
-        >>> round(Interval(Date(2020, 1, 1), Date(2020, 8, 1)).quarters(), 2)
-        2.33
+        return self._sign * 4 * self.days / 365.0
+
+    @property
+    def years(self) -> int:
+        """Get number of complete years in the interval (always floors).
         """
-        return 4 * self.days() / 365.0
-
-    def years(self, basis: int = 0):
-        """Years with Fractions (matches Excel YEARFRAC)
-
-        Adapted from https://web.archive.org/web/20200915094905/https://dwheeler.com/yearfrac/calc_yearfrac.py
-
-        Basis:
-        0 = US (NASD) 30/360
-        1 = Actual/actual
-        2 = Actual/360
-        3 = Actual/365
-        4 = European 30/360
-
-        >>> begdate = Date(1978, 2, 28)
-        >>> enddate = Date(2020, 5, 17)
-
-        Tested Against Excel
-        >>> "{:.4f}".format(Interval(begdate, enddate).years(0))
-        '42.2139'
-        >>> '{:.4f}'.format(Interval(begdate, enddate).years(1))
-        '42.2142'
-        >>> '{:.4f}'.format(Interval(begdate, enddate).years(2))
-        '42.8306'
-        >>> '{:.4f}'.format(Interval(begdate, enddate).years(3))
-        '42.2438'
-        >>> '{:.4f}'.format(Interval(begdate, enddate).years(4))
-        '42.2194'
-        >>> '{:.4f}'.format(Interval(enddate, begdate).years(4))
-        '-42.2194'
-
-        Excel has a known leap year bug when year == 1900 (=YEARFRAC("1900-1-1", "1900-12-1", 1) -> 0.9178)
-        The bug originated from Lotus 1-2-3, and was purposely implemented in Excel for the purpose of backward compatibility.
-        >>> begdate = Date(1900, 1, 1)
-        >>> enddate = Date(1900, 12, 1)
-        >>> '{:.4f}'.format(Interval(begdate, enddate).years(4))
-        '0.9167'
+        year_diff = self._end.year - self._start.year
+        if self._end.month < self._start.month or \
+           (self._end.month == self._start.month and self._end.day < self._start.day):
+            year_diff -= 1
+        return self._sign * year_diff
+
+    def yearfrac(self, basis: int = 0) -> float:
+        """Calculate the fraction of years between two dates (Excel-compatible).
+
+        This method provides precise calculation using various day count conventions
+        used in finance. Results are tested against Excel for compatibility.
+
+        Parameters
+            basis: Day count convention to use:
+                0 = US (NASD) 30/360 (default)
+                1 = Actual/actual
+                2 = Actual/360
+                3 = Actual/365
+                4 = European 30/360
+
+        Note: Excel has a known leap year bug for year 1900 which is intentionally
+        replicated for compatibility (1900 is treated as a leap year even though it wasn't).
         """
 
         def average_year_length(date1, date2):
@@ -1675,32 +1710,84 @@ class Interval:
                 (date1day + date1month * 30 + date1year * 360)
             return daydiff360 / 360
 
-        begdate, enddate = self.begdate, self.enddate
-        if enddate is None:
-            return
-
-        sign = 1
-        if begdate > enddate:
-            begdate, enddate = enddate, begdate
-            sign = -1
-        if begdate == enddate:
+        if self._start == self._end:
             return 0.0
-
         if basis == 0:
-            return basis0(begdate, enddate) * sign
+            return basis0(self._start, self._end) * self._sign
         if basis == 1:
-            return basis1(begdate, enddate) * sign
+            return basis1(self._start, self._end) * self._sign
         if basis == 2:
-            return basis2(begdate, enddate) * sign
+            return basis2(self._start, self._end) * self._sign
         if basis == 3:
-            return basis3(begdate, enddate) * sign
+            return basis3(self._start, self._end) * self._sign
         if basis == 4:
-            return basis4(begdate, enddate) * sign
+            return basis4(self._start, self._end) * self._sign
 
         raise ValueError('Basis range [0, 4]. Unknown basis {basis}.')
 
+    @reset_business
+    def start_of(self, unit: str = 'month') -> list[Date | DateTime]:
+        """Return the start of each unit within the interval.
+
+        Parameters
+            unit: Time unit ('month', 'week', 'year', 'quarter')
+
+        Returns
+            List of Date or DateTime objects representing start of each unit
+
+        In business mode, each start date is adjusted to the next business day
+        if it falls on a non-business day.
+        """
+        handlers = self._get_unit_handlers(unit)
+        result = []
+
+        current = handlers['get_start'](self._start)
+
+        if self._business:
+            current._entity = self._entity
+
+        while current <= self._end:
+            if self._business:
+                current = current._business_or_next()
+            result.append(current)
+            current = handlers['advance'](current)
+
+        return result
+
+    @reset_business
+    def end_of(self, unit: str = 'month') -> list[Date | DateTime]:
+        """Return the end of each unit within the interval.
+
+        Parameters
+            unit: Time unit ('month', 'week', 'year', 'quarter')
+
+        Returns
+            List of Date or DateTime objects representing end of each unit
 
-def create_ics(begdate, enddate, summary, location):
+        In business mode, each end date is adjusted to the previous business day
+        if it falls on a non-business day.
+        """
+        handlers = self._get_unit_handlers(unit)
+        result = []
+
+        current = handlers['get_start'](self._start)
+
+        if self._business:
+            current._entity = self._entity
+
+        while current <= self._end:
+            end_date = handlers['get_end'](current)
+
+            if self._business:
+                end_date = end_date._business_or_previous()
+            result.append(end_date)
+
+            current = handlers['advance'](current)
+
+        return result
+
+
+def create_ics(begdate, enddate, summary, location) -> str:
     """Create a simple .ics file per RFC 5545 guidelines."""
 
     return f"""BEGIN:VCALENDAR
@@ -1714,35 +1801,3 @@ LOCATION:{location}
 END:VEVENT
 END:VCALENDAR
     """
-
-
-# apply any missing Date functions
-for func in (
-    'average',
-    'closest',
-    'farthest',
-    'fromordinal',
-    'fromtimestamp',
-    'nth_of',
-    'replace',
-):
-    setattr(Date, func, store_entity(getattr(_pendulum.Date, func), typ=Date))
-
-# apply any missing DateTime functions
-for func in (
-    'astimezone',
-    'date',
-    'fromordinal',
-    'fromtimestamp',
-    'in_timezone',
-    'in_tz',
-    'replace',
-    'strptime',
-    'utcfromtimestamp',
-    'utcnow',
-):
-    setattr(DateTime, func, store_entity(getattr(_pendulum.DateTime, func), typ=DateTime))
-
-
-if __name__ == '__main__':
-    __import__('doctest').testmod(optionflags=4 | 8 | 32)