Skip to content

v4.7.8

Latest

Choose a tag to compare

@github-actions github-actions released this 07 Nov 12:59
· 293 commits to b35d30c83fd94dd9e5052b67334fabafc75e3236 since this release

Note

Reliable holidays and deadlines with configurable business and fiscal calendars.

At a glance

Release type Bug fix / Feature
Upgrade priority Recommended
Breaking changes Holiday coverage and errors; forward-offset results. See Upgrade guidance.
Python support Python 3.8–3.14 (>=3.8,<3.15)

Highlights

  • Deadlines that respect working days — Parse business-day or working-day expressions with country and state/province public holidays, observed dates, custom workweeks, and company closures. For example, parse("1 business day after 2026-11-25", country="US") returns November 27, skipping Thanksgiving.
  • Reusable business calendars — parse() adds keyword arguments business_calendar, country, subdiv, and observed. BusinessCalendar(working_days=..., holidays=..., country=..., subdiv=..., observed=...) combines a chosen working week, explicit closure dates, and a country's public holidays. Weekday numbers run from Monday 0 through Sunday 6; is_business_day(date) checks eligibility and add_business_days(date, amount) supports positive, negative, and zero offsets without parsing text.
  • Selections as well as deadlines — Expressions such as in 3 business days, next 3 working days, third business day of February 2027, and first 5 business days of next month support offsets, traversal, ordinal selection, and selection within a period. Business-day offsets exclude the starting date; zero leaves it unchanged. next/last selections return dates in traversal order, while scoped selections return chronological dates. A next/last traversal of one day returns a single date; a scope with too few eligible dates returns None.
  • Holiday-aware calculations across years — Country holidays are loaded offline for the years the calculation visits and cached separately for each calendar. Calculations account for year crossings and observed holidays, including an observed New Year holiday in the preceding December. Country selection supplies holiday exclusions; choose working_days explicitly when the working week differs from Monday–Friday.
  • Fiscal reporting that follows your calendar — Choose a starting month or a 4-4-5, 4-5-4, 5-4-4, or custom week-based calendar. Resolve fiscal years, quarters, and periods through natural language or direct calendar methods, including configurable placement of a 53rd week.
  • Month-based fiscal years — FiscalCalendar(start_month=..., year_label=...) starts on the first day of the chosen month, with monthly periods and three-month quarters. year_label="end" labels July 2026–June 2027 as FY2027; "start" labels it FY2026. For January starts, both conventions use the same year. Pass the calendar with parse(..., fiscal_calendar=calendar) to resolve phrases such as Q1 FY2027, P8 FY2024, and end of FY2027.
  • Configurable retail and custom periods — RetailFiscalCalendar supports pattern, quarter_periods, start_month, start_day, week_start, alignment, and leap_week_period. A three-period pattern totaling 13 weeks repeats across four quarters, or a complete custom pattern can define 52 weeks with a chosen grouping into four quarters. Annual starts align to a weekday nearest to, on or before, or on or after the anchor date. Years contain 52 or 53 weeks; the extra week goes to the selected period, defaulting to the last. A 13-period calendar can use pattern=(4,) * 13 with quarter_periods=(3, 3, 3, 4).
  • Callable fiscal lookups and defaults — Both calendar types expose fiscal_year(date), fiscal_quarter(date), fiscal_period(date), and inclusive year_range(year), quarter_range(year, quarter), and period_range(year, period) methods. set_fiscal_calendar() and get_fiscal_calendar() manage the default for the current execution context; per-call settings override it, and set_fiscal_calendar(None) restores January–December. Business-day selection also works inside fiscal scopes, such as first business day of Q3 FY2027 with a country calendar.
  • Installation beyond Windows — Add native package builds for Linux x86-64 and macOS Intel and Apple Silicon alongside Windows x64. Linux wheels target glibc 2.28 or newer; Linux ARM, Alpine/musllinux, and Windows ARM wheels are outside this release.

Fixed

  • Fixed holiday country resolution so supported names, aliases, and ISO country codes work consistently across capitalization, accents, whitespace, and punctuation.
  • Fixed forward offsets such as in 3 days and in 1 month to return the offset date. Month and year offsets keep the result within the destination month, including leap-year boundaries.
  • Fixed temporary reference dates leaking out of failed anchored calculations. The original reference date is restored even when a starting from calculation raises an exception, preventing that failure from changing subsequent results.
  • Fixed mixed padded and unpadded date/time formats so removing a leading zero affects only the requested field and preserves literal percent signs.
  • Formatting now handles %- and %# flags independently for day, month, two-digit year, hour, minute, and second fields. For example, convert_date("2026-03-04", to_format="%-m/%d/%Y") returns "3/04/2026", retaining the day padding; escaped %% stays literal.
  • Fixed native text handling to normalize Unicode whitespace without truncating long inputs, and to expand UTC Z suffixes without unsafe buffer writes.
  • Native cleanup allocates storage for the actual input length and applies Python's Unicode whitespace rules to non-ASCII input. UTC suffix replacement uses a separate writable buffer sized for Z becoming +00:00, preserving the original input. Corrected case-sensitive header references also allow source builds on macOS and Linux.

Changed

  • Holiday lookups now default to offline public-holiday rules. Observed dates are included where supported; cultural or religious observances that are not public holidays are outside this default calendar. The Date, Name, and Type columns remain, with Public holiday as the public source's type label.
  • Holidate.Holiday(country_name, year=None, format="list", *, source="public", subdiv=None, observed=True) supports country names, aliases, and ISO alpha-2 codes. Omitting the year selects the current year at call time; an explicit year must be a four-digit integer or string. ListCountries reports the installed provider's supported countries. Results are sorted ISO dates within the requested year: list includes a header row, dict returns a list of records, and df returns a pandas DataFrame. Names are English where the provider supports it.
  • Failed holiday lookups now raise HolidayLookupError. Invalid lookup arguments raise TypeError or ValueError. Unknown country names are rejected rather than guessed, with close matches suggested where available. Country and year coverage follows the installed holiday provider.
  • Business-day parsing propagates unavailable holiday data as HolidayLookupError instead of returning a deadline with missing exclusions. Invalid calendar configuration raises TypeError/ValueError; unsupported general date expressions can still return None.
  • Public holiday rules are supplied by holidays>=0.58,<1. Timezone data is supplied by tzdata on Python 3.9 and newer, with the existing pytz path on Python 3.8. These dependencies support local calendar and timezone operations; network-backed TimeZoner methods retain their external-service requirements.
  • Matching wheels support CPython 3.8–3.14 on the listed platforms. Installing from source compiles seven required Cython extensions using a compatible compiler; there is no pure-Python fallback. Precompiled Windows binaries are no longer bundled in the source tree.

Upgrade guidance

Upgrade is recommended for applications using holidays, date offsets, or date/time formatting. Business-day and fiscal-calendar configuration is optional; the local holiday and calendar features require no API key.

Warning

Holiday coverage, error handling, and forward-offset results have changed. Review the following migration steps before upgrading existing consumers.

  1. Choose the holiday coverage you need. Existing Holidate.Holiday() calls now use public holidays. If you need the broader legacy feed, explicitly pass source="timeanddate"; it requires network access and can be blocked by the provider. State/province subdiv and observed options apply to the public source.
  2. Update failure handling. Replace holiday-failure checks for None with exception handling for HolidayLookupError and invalid-input TypeError/ValueError. Supply a supported country name or code; automatic country guessing is no longer used. Unrecognized general parse() expressions can still return None.
  3. Check offset consumers. Treat parse("in 3 days") as a single date. Use next 3 days when you want the existing inclusive span beginning on the reference date, and update code that previously expected an offset to produce a range.
  4. Configure calendars explicitly when needed. Business days default to Monday–Friday without holidays; specify country or pass a BusinessCalendar to exclude holidays. Put country options on the calendar when supplying one. Fiscal settings apply to explicit fiscal phrases such as Q1 FY2027; ordinary Q1 2027 retains its calendar-year meaning.
  5. Keep calendar options consistent. country and business_calendar are mutually exclusive parser arguments. When passing a calendar object, configure country, subdiv, and observed on that object. Ordinary weekday expressions continue to mean Monday–Friday and ignore holiday exclusions. Pass fiscal calendars explicitly when serving separate requests or sharing work across threads; context defaults do not automatically configure those independent contexts.

Install or upgrade

Use a matching prebuilt wheel when available; source installations require a compatible C compiler.

python -m pip install --upgrade dately==4.7.8

Links