Repository navigation
Releases
v4.7.8
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 argumentsbusiness_calendar,country,subdiv, andobserved.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 Monday0through Sunday6;is_business_day(date)checks eligibility andadd_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, andfirst 5 business days of next monthsupport offsets, traversal, ordinal selection, and selection within a period. Business-day offsets exclude the starting date; zero leaves it unchanged.next/lastselections return dates in traversal order, while scoped selections return chronological dates. Anext/lasttraversal of one day returns a single date; a scope with too few eligible dates returnsNone. - 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_daysexplicitly 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 withparse(..., fiscal_calendar=calendar)to resolve phrases such asQ1 FY2027,P8 FY2024, andend of FY2027. - Configurable retail and custom periods —
RetailFiscalCalendarsupportspattern,quarter_periods,start_month,start_day,week_start,alignment, andleap_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 usepattern=(4,) * 13withquarter_periods=(3, 3, 3, 4). - Callable fiscal lookups and defaults — Both calendar types expose
fiscal_year(date),fiscal_quarter(date),fiscal_period(date), and inclusiveyear_range(year),quarter_range(year, quarter), andperiod_range(year, period)methods.set_fiscal_calendar()andget_fiscal_calendar()manage the default for the current execution context; per-call settings override it, andset_fiscal_calendar(None)restores January–December. Business-day selection also works inside fiscal scopes, such asfirst business day of Q3 FY2027with 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 daysandin 1 monthto 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 fromcalculation 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
Zsuffixes 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
Zbecoming+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, andTypecolumns remain, withPublic holidayas 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.ListCountriesreports the installed provider's supported countries. Results are sorted ISO dates within the requested year:listincludes a header row,dictreturns a list of records, anddfreturns a pandas DataFrame. Names are English where the provider supports it.- Failed holiday lookups now raise
HolidayLookupError. Invalid lookup arguments raiseTypeErrororValueError. 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
HolidayLookupErrorinstead of returning a deadline with missing exclusions. Invalid calendar configuration raisesTypeError/ValueError; unsupported general date expressions can still returnNone. - Public holiday rules are supplied by
holidays>=0.58,<1. Timezone data is supplied bytzdataon Python 3.9 and newer, with the existingpytzpath on Python 3.8. These dependencies support local calendar and timezone operations; network-backedTimeZonermethods 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.
- Choose the holiday coverage you need. Existing
Holidate.Holiday()calls now use public holidays. If you need the broader legacy feed, explicitly passsource="timeanddate"; it requires network access and can be blocked by the provider. State/provincesubdivandobservedoptions apply to the public source. - Update failure handling. Replace holiday-failure checks for
Nonewith exception handling forHolidayLookupErrorand invalid-inputTypeError/ValueError. Supply a supported country name or code; automatic country guessing is no longer used. Unrecognized generalparse()expressions can still returnNone. - Check offset consumers. Treat
parse("in 3 days")as a single date. Usenext 3 dayswhen you want the existing inclusive span beginning on the reference date, and update code that previously expected an offset to produce a range. - Configure calendars explicitly when needed. Business days default to Monday–Friday without holidays; specify
countryor pass aBusinessCalendarto exclude holidays. Put country options on the calendar when supplying one. Fiscal settings apply to explicit fiscal phrases such asQ1 FY2027; ordinaryQ1 2027retains its calendar-year meaning. - Keep calendar options consistent.
countryandbusiness_calendarare mutually exclusive parser arguments. When passing a calendar object, configurecountry,subdiv, andobservedon that object. Ordinaryweekdayexpressions continue to mean Monday–Friday and ignore holiday exclusions. Pass fiscal calendars explicitly when serving separate requests or sharing work across t...
v3.3.0
Note
Reliable temporal parsing with restored service integrations.
At a glance
| Release type | Bug fix and packaging |
| Upgrade priority | Recommended |
| Breaking changes | None |
| Python support | Python 3.8–3.14 (>=3.8,<3.15) |
Highlights
- More reliable temporal parsing — Corrects regressions affecting date and time replacement, formatted sequences, relative weekdays, repeated weekends, and documented natural-language forms.
- TimeZoner and Holidate restored — Both integrations are enabled with isolated HTTP state and offline package data.
- Complete Windows wheel coverage — Provides Windows x64 wheels for CPython 3.8 through 3.14, along with a source distribution.
Fixed
- Fixed non-ISO time replacement and timezone insertion, including strings such as
2024-03-13 T14:30:00. - Fixed argument forwarding for ISO time replacement and preservation of the original date/time separator.
- Fixed formatted sequences, numeric week-start values, relative weekday offsets, and repeated-weekend generation.
- Fixed documented natural-language parsing forms while preserving semantic bounds and invalid-input rejection.
- Fixed API-key isolation and HTTP-state restoration for TimeZoner and Holidate requests.
Changed
- Added the independent packaged
agent_profileimplementation used for realistic user-agent generation. - Updated package metadata, documentation, project assets, and release automation.
Upgrade guidance
Existing users should upgrade. No application-code, configuration, data, or credential changes are required.
Install or upgrade
python -m pip install --upgrade dately==3.3.0Links
v3.2.4
Note
Clearer documentation and practical examples for core workflows.
At a glance
| Release type | Documentation and maintenance |
| Upgrade priority | Optional |
| Breaking changes | None |
| Python support | Python 3.8+ (>=3.8) |
Highlights
- Focused examples — Adds runnable examples for date conversion, natural-language parsing, date-string replacement, and timezone operations.
- More approachable documentation — Reworks the README around the primary workflows instead of one oversized collection of embedded examples.
Changed
- Added dedicated examples for
convert_dates, NLP parsing,replace_datestring, and timezone operations. - Streamlined the README and directed detailed workflows to the new example files.
- Updated maintenance workflow configuration for the 3.2.4 release line.
Upgrade guidance
This release is optional for existing 3.2.3 users because its recorded changes focus on documentation and examples. No application-code, configuration, data, or credential changes are required.
Warning
This GitHub release and tag were reconstructed from the closest repository commit preceding the original May 10, 2025 PyPI upload. The published PyPI artifacts remain authoritative for this version.
Install or upgrade
python -m pip install --upgrade dately==3.2.4Links
v3.2.3
Note
Stricter time detection with refreshed runtime profiles.
At a glance
| Release type | Bug fix and maintenance |
| Upgrade priority | Recommended |
| Breaking changes | None |
| Python support | Python 3.8+ (>=3.8) |
Highlights
- More precise time scanning — Time detection uses a strict timezone whitelist to reduce ambiguous or unsupported matches.
- Current runtime profiles — Refreshes bundled operating-system and browser user-agent version data.
Fixed
- Fixed overly permissive time detection by limiting timezone matches to the supported timezone vocabulary.
- Refined date-time scanning behavior in preparation for broader month-abbreviation handling.
Changed
- Updated bundled operating-system profile data.
- Updated bundled browser user-agent versions used by network-backed features.
Upgrade guidance
Upgrade is recommended for applications that scan free-form text containing times or timezone abbreviations. No application-code, configuration, data, or credential changes are required.
Warning
This GitHub release and tag were reconstructed from the closest repository commit preceding the original May 8, 2025 PyPI upload. The published PyPI artifacts remain authoritative for this version.
Install or upgrade
python -m pip install --upgrade dately==3.2.3Links
v3.2.2
Note
Reliable formatting for date-only inputs.
At a glance
| Release type | Bug fix |
| Upgrade priority | Recommended |
| Breaking changes | None |
| Python support | Python 3.8+ (>=3.8) |
Highlights
- Date-only compatibility — Formatting accepts
datetime.datevalues without requiring callers to convert them first. - Consistent formatter behavior — Date-only inputs follow the same formatting path as
datetime.datetimevalues.
Fixed
- Fixed formatting of
datetime.dateinputs by promoting them todatetime.datetimebefore applying datetime formatting operations.
Upgrade guidance
Upgrade is recommended for users who pass datetime.date objects into formatting APIs. No application-code, configuration, data, or credential changes are required.
Warning
This GitHub release and tag were reconstructed from the closest repository commit preceding the original May 6, 2025 PyPI upload. The published PyPI artifacts remain authoritative for this version.
Install or upgrade
python -m pip install --upgrade dately==3.2.2Links
v3.2.1
Note
Natural-language parsing and expanded date-time tooling.
At a glance
| Release type | Feature |
| Upgrade priority | Recommended |
| Breaking changes | None documented |
| Python support | Python 3.8+ (>=3.8) |
Highlights
- Natural-language temporal resolution — Adds preprocessing, arithmetic, relative-time, quantified-time, lexical, syntactic, semantic, and spelling components for resolving English temporal expressions.
- Expanded scanning pipeline — Introduces dedicated date-time and temporal scanners for extracting, validating, and normalizing temporal content.
- Bundled reference data — Adds packaged timezone, holiday, country-variant, operating-system, and browser-profile data used by parsing and network-backed features.
Changed
- Reorganized internal modules behind underscore-prefixed package components and updated the public API wiring.
- Expanded the compiled formatting and detection helpers used for cross-platform date and time handling.
- Added automated refresh workflows for operating-system and browser user-agent profile data.
- Updated documentation to cover natural-language date and time handling.
Upgrade guidance
Upgrade is recommended for users who need natural-language temporal parsing or the expanded scanners. Existing applications should run their parsing and formatting test cases before adopting this substantial internal update; no configuration, data, or credential migration is documented.
Warning
This GitHub release and tag were reconstructed from the closest repository commit preceding the original May 5, 2025 PyPI upload. Some original build-time files were not committed, so the published PyPI artifacts remain authoritative for this version.
Install or upgrade
python -m pip install --upgrade dately==3.2.1Links
v3.0.2
Note
More consistent locale formatting and faster date processing.
At a glance
| Release type | Bug fix and maintenance |
| Upgrade priority | Recommended |
| Breaking changes | None documented |
| Python support | Python 3.8+ (>=3.8) |
Highlights
- Consistent formatted output — Locale-sensitive date formatting produces more dependable strings across supported environments.
- Lean date processing — Removes redundant computations from key date-handling paths.
- Cleaner distribution — Removes deprecated assets and refreshes bundled timezone and holiday data used by the package.
Fixed
- Fixed formatted date strings displaying incorrectly under some locale settings.
- Fixed avoidable performance overhead caused by repeated computations in date-processing operations.
Changed
- Reorganized internal date, time, timezone, and utility modules while preserving package-level access.
- Refreshed bundled holiday and timezone reference data.
- Removed deprecated project assets from the distribution source.
Upgrade guidance
Upgrade is recommended for users affected by locale-specific formatting differences or slower date-processing paths. No application-code, configuration, data, or credential changes are documented.
Install or upgrade
python -m pip install --upgrade dately==3.0.2Links
v2.4.0
Note
Holiday lookups and richer timezone operations.
At a glance
| Release type | Feature and bug fix |
| Upgrade priority | Recommended |
| Breaking changes | None documented |
| Python support | Python 3.8+ (>=3.8) |
Highlights
- Timezone objects and local time —
TimeZoner.Object()returns timezone objects or current datetimes for named and locally detected zones. - Local timezone discovery —
TimeZoner.MyTimeZoneexposes location-aware timezone, offset, DST, and current-time details. - Holiday information —
Holidateretrieves country and year holiday data as lists, dictionaries, or DataFrames.
Fixed
- Fixed incorrect timezone-offset calculations for affected regions.
- Fixed date parsing and calculations involving leap years.
- Fixed missing Daylight Saving Time adjustments in timezone results.
Changed
- Added
TimeZoner.Object()for named or current timezone objects and timezone-aware datetimes. - Added
TimeZoner.MyTimeZonefor local timezone discovery. - Added
Holidate.Holiday()and country discovery for holiday-data workflows.
Upgrade guidance
Upgrade is recommended for timezone and holiday users, particularly applications affected by offset, leap-year, or DST handling. The new APIs are additive; no configuration, data, or credential migration is documented.
Install or upgrade
python -m pip install --upgrade dately==2.4.0Links
v2.2.0b2
Note
Flexible timezone lookup and local-time discovery.
At a glance
| Release type | Feature beta |
| Upgrade priority | Optional |
| Breaking changes | None documented |
| Python support | Python 3.8+ (>=3.8) |
Highlights
- Flexible timezone fetching — Obtain a timezone object for a named region or detect the current timezone from location information.
- Current-time retrieval — Retrieve the current date and time for a selected timezone or the locally detected zone.
- Local timezone tracker — Access current local timezone information through
TimeZoner.MyTimeZonewithout manual zone selection.
Changed
- Expanded
TimeZonerwith named and locally detected timezone-object retrieval. - Added timezone-aware current date and time retrieval.
- Added bundled timezone reference data supporting the expanded lookups.
- Reorganized the beta package layout and internal timezone components.
Upgrade guidance
This beta is optional for existing users and intended for early adoption of the expanded TimeZoner behavior. Test timezone discovery and current-time results in each deployment environment before production use; no credential migration is documented.
Install or upgrade
python -m pip install --upgrade dately==2.2.0b2Links
v2.1.4
Note
Cross-platform date-time parsing, validation, and transformation.
At a glance
| Release type | Feature |
| Upgrade priority | Optional |
| Breaking changes | First currently tagged stable release |
| Python support | Python 3.8+ (>=3.8) |
Highlights
- Format detection — Detect and parse a broad range of standard and custom date and time strings.
- Timezone management — Inspect zones, convert between timezones, retrieve current zoned time, and categorize zones by country, offset, or DST behavior.
- Date-string utilities — Extract, validate, replace, or remove individual date, time, and timezone components.
- Cross-platform formatting — Compensates for Windows and Unix differences in leading-zero date format behavior.
- Accelerated internals — Uses Cython and C helpers for performance-sensitive string and date validation operations.
Upgrade guidance
This is the earliest stable release represented by the current GitHub tags. Existing PyPI users can install it without documented configuration, data, or credential migration requirements.
Install or upgrade
python -m pip install --upgrade dately==2.1.4