Skip to content

Releases

v4.7.8

Choose a tag to compare

@github-actions github-actions released this 07 Nov 12:59

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 t...
Read more

v3.3.0

Choose a tag to compare

@doydl-dev doydl-dev released this 03 Oct 08:58

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_profile implementation 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.0

Links

v3.2.4

Choose a tag to compare

@cedricmoorejr cedricmoorejr released this 24 Sep 13:54

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.4

Links

v3.2.3

Choose a tag to compare

@cedricmoorejr cedricmoorejr released this 24 Sep 13:54

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.3

Links

v3.2.2

Choose a tag to compare

@cedricmoorejr cedricmoorejr released this 24 Sep 13:53

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.date values without requiring callers to convert them first.
  • Consistent formatter behavior — Date-only inputs follow the same formatting path as datetime.datetime values.

Fixed

  • Fixed formatting of datetime.date inputs by promoting them to datetime.datetime before 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.2

Links

v3.2.1

Choose a tag to compare

@cedricmoorejr cedricmoorejr released this 24 Sep 13:53

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.1

Links

v3.0.2

Choose a tag to compare

@cedricmoorejr cedricmoorejr released this 08 Mar 06:27

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.2

Links

v2.4.0

Choose a tag to compare

@cedricmoorejr cedricmoorejr released this 16 Jul 06:10

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.MyTimeZone exposes location-aware timezone, offset, DST, and current-time details.
  • Holiday information — Holidate retrieves 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.MyTimeZone for 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.0

Links

v2.2.0b2

v2.2.0b2 Pre-release
Pre-release

Choose a tag to compare

@cedricmoorejr cedricmoorejr released this 05 Jul 20:04

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.MyTimeZone without manual zone selection.

Changed

  • Expanded TimeZoner with 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.0b2

Links

v2.1.4

Choose a tag to compare

@cedricmoorejr cedricmoorejr released this 02 Jul 18:36

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

Links