DOCSEARCHbyAlgolia
Submit Docs

dateutil

repository·master·Indexed 25 days ago

https://github.com/dateutil/dateutil

A library providing extensions to Python's standard datetime module, specializing in flexible date parsing, relative time deltas, recurrence rules (rrule), and comprehensive timezone handling. It includes tools for ISO 8601 parsing, RFC 5545 recurrence strings, and support for various timezone formats including IANA/zoneinfo, Windows, and local system timezones.

Tokens
9K
Snippets
4
Records
93
Agent score
80%

What's inside dateutil

  1. Overview of dateutil features

    master

    The dateutil module provides powerful extensions to the standard Python datetime module, including:

    • Relative Deltas: Computing differences between dates or offsets like "next month", "next Monday", or "last week of month".
    • Recurrence Rules: Computing dates based on flexible recurrence rules (a superset of the iCalendar specification) and parsing RFC strings.
    • Generic Parsing: Parsing dates from almost any string format.
    • Timezone Support: Implementations for tzfile(5) formats, TZ environment strings, iCalendar formats, fixed offsets, UTC, and Windows registry-based time zones.
    • Easter Sunday Calculation: Computing Easter Sunday for any year using Western, Orthodox, or Julian algorithms.

  2. Use the tz.win module for Windows timezone support

    master
    The dateutil.tz.win module provides classes for interacting with Windows timezone data. It includes support for retrieving timezone information, display names, and transition rules specific to the Windows environment.

  3. Use rrule for recurrence rules

    master

    The dateutil.rrule module provides classes and functions for working with recurrence rules (RFC 5545).

    Key components include:

    • rrule: A class used to define a single recurrence rule.
    • rruleset: A class used to combine multiple rrule instances or exclude specific dates from a rule.
    • rrulestr: A function to create an rrule instance from an RFC 5545 string.

  5. Handle month and year boundaries automatically

    master
    When adding months or years, relativedelta automatically handles varying month lengths and leap years. If the resulting day would fall outside the target month (e.g., adding 1 month to January 31st), it defaults to the last valid day of that month (e.g., February 28th or 29th).

  6. Generate monthly recurrence rules with rrule

    master

    Use rrule with MONTHLY frequency for complex monthly patterns.

    Key options:

    • byweekday: Specify a day and an occurrence within the month (e.g., FR(1) for the first Friday, MO(-2) for the second to last Monday, or SU(1), SU(-1) for the first and last Sunday).
    • bymonthday: Specify days of the month (e.g., (2, 15) for the 2nd and 15th, or -3 for the third to last day).
    • bysetpos: Specify the $n$-th instance within the set of dates generated by other rules (e.g., bysetpos=3 for the 3rd instance).
    • interval: Set the frequency of months (e.g., interval=2 for every other month).

  7. Generate hourly and minutely recurrence rules with rrule

    master

    Use rrule with HOURLY or MINUTELY frequency for sub-day patterns.

    Key options:

    • byhour: Specify hours of the day (e.g., range(9,17) for 9 AM to 4 PM).
    • byminute: Specify minutes of the hour (e.g., (0, 20, 40)).
    • interval: Set the frequency (e.g., interval=3 for every 3 hours).

  8. Perform date arithmetic with relativedelta

    master

    Use relativedelta to add or subtract relative time units (like months, weeks, or years) to datetime or date objects. You can combine multiple units in a single operation.

    Key behaviors:

    • Relative units: Using plural forms like months=+1 or weeks=+1 performs arithmetic.
    • Absolute units: Using singular forms like year=2024 or month=1 replaces the value in the original object rather than adding to it.
    • Month/Year boundaries: relativedelta handles varying month lengths and leap years gracefully, ensuring that adding a month does not cross a month boundary unexpectedly (e.g., adding 1 month to Jan 31 results in Feb 28/29).

  9. Generate weekly recurrence rules with rrule

    master

    Use rrule with WEEKLY frequency to generate weekly dates.

    Key options:

    • wkst: Set the start of the week (e.g., SU for Sunday).
    • byweekday: Specify specific days of the week (e.g., (TU, TH) for Tuesday and Thursday).
    • byweekno: Specify a particular week number in the year.
    • interval: Set the frequency of the weeks (e.g., interval=2 for every other week).

  11. Find specific weekdays using relativedelta

    master

    You can use the weekday parameter to find the next or previous occurrence of a specific day of the week.

    • Use weekday=FR (or calendar.FRIDAY) for the next Friday.
    • Use weekday=FR(-1) to find the last Friday of a month (when combined with day=31).
    • Use weekday=WE(+1) to find the next Wednesday, where +1 indicates the next occurrence even if today is Wednesday.

  12. Parse datetime strings with timezone context

    master
    When parsing datetime strings containing ambiguous three-letter timezone abbreviations (like 'CST'), use dateutil.parser.parse in conjunction with dateutil.tz to provide context. This allows you to map ambiguous abbreviations to specific IANA-style timezones based on the expected geographic context (e.g., US, India, or Japan).