ISO Week Date

iso-week-date is a toolkit to work with strings representing ISO Week date in two formats, namely:

• Week format YYYY-WNN (date format %Y-W%V)
• Week date format YYYY-WNN-D (date format %Y-W%V-%u)

where YYYY represents the year, W is a string literal, NN represents the week number, and D represents the day of the week.

In a nutshell it provides:

• IsoWeek and IsoWeekDate classes that implement a series of methods to work with ISO Week (Date) formats directly, avoiding the pitfalls of going back and forth between string, date and datetime python objects.
• pandas and polars functionalities (and namespaces) to work with series of ISO Week dates.
• pydantic compatible types, as described in their docs section on how to customize validation with __get_pydantic_core_schema__

Documentation | Source Code | Issue Tracker

Installation

iso-week-date is published as a Python package on pypi, and it can be installed with pip, or directly from source using git, or with a local clone:

• pip (suggested):

  python -m pip install iso-week-date
  

• pip + source/git:

  python -m pip install git+https://github.com/FBruzzesi/iso-week-date.git
  

• local clone:

  git clone https://github.com/FBruzzesi/iso-week-date.git
  cd iso-week-date
  python -m pip install .
  

Dependencies

• To work with IsoWeek and IsoWeekDate classes, no additional dependency is required.
• pandas and polars functionalities require the installation of the respective libraries.
• pydantic integration requires pydantic>=2.40.

Getting Started

Available features

This is a high level overview of the features provided by the iso-week-date package.

The IsoWeek and IsoWeekDate classes provide the following functionalities:

• Parsing from string, date and datetime objects.
• Conversion to string, date and datetime objects.
• Comparison operations between IsoWeek (resp IsoWeekDate) objects.
• Addition with int types.
• Subtraction with int and IsoWeek (resp IsoWeekDate) types.
• Range between two IsoWeek (resp. IsoWeekDate) objects.

IsoWeek unique methods/features:

• days properties that lists the dates in the given week
• nth method to get the nth day of the week as date
• in operator and contains method to check if a (iterable of) week(s), string(s) and/or date(s) is contained in the given week
• weeksout method to generate a list of weeks that are n_weeks after the given week
• Addition and subtraction with int defaults to adding/subtracting weeks

IsoWeekDate unique methods/features:

• day property that returns the weekday as integer
• isoweek property that returns the ISO Week of the given date (as string)
• daysout method to generate a list of dates that are n_days after the given date
• Addition and subtraction with int defaults to adding/subtracting days

pandas_utils and polars_utils modules provide functionalities to work with and move back and forth with series of ISO Week date formats.

In specific both modules implements the following functionalities:

• datetime_to_isoweek and datetime_to_isoweekdate to convert a series of datetime objects to a series of ISO Week (date) strings
• isoweek_to_datetime and isoweekdate_to_datetime to convert a series of ISO Week (date) strings to a series of datetime objects
• is_isoweek_series and is_isoweekdate_series to check if a string series values match the ISO Week (date) format

Quickstart

To get started with IsoWeek and IsoWeekDate classes please refer to the quickstart documentation section.

To check examples on how to work with pandas and polars functionalities please refer to the dataframe modules documentation section.

Custom offset

One of the main reason for this library to exist is the need and the flexibility to work with custom offsets, i.e. to be able to add/subtract a custom offset (as timedelta) to the default ISO Week start and given date, and get a "shifted" week.

This feature is available both in the IsoWeek and IsoWeekDate classes and the dataframe functionalities.

To check an example see the working with custom offset section.

Contributing

Please read the contributing guidelines in the documentation site.

License

The project has a MIT Licence.