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 %G-W%V)
• Week date format YYYY-WNN-D (date format %G-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, the only dependency is packaging, which is used to compare the versions of the optional dependencies below.
• pandas and polars functionalities require the installation of the respective libraries (pandas>=1.1.0, polars>=0.18.0).
• pydantic integration requires pydantic>=2.4.0.

Getting Started

from datetime import date

from iso_week_date import IsoWeek

week = IsoWeek.from_date(date(2026, 3, 10))

week  # IsoWeek(2026-W11)
week.year, week.week  # (2026, 11)
week.nth(1), week.nth(7)  # (date(2026, 3, 9), date(2026, 3, 15))
week + 1  # IsoWeek(2026-W12)
week - 13  # IsoWeek(2025-W50), year boundary handled
date(2026, 3, 12) in week  # True

tuple(IsoWeek.range(start=week - 2, end=week, inclusive="both", as_str=True))
# ('2026-W09', '2026-W10', '2026-W11')

Work through the quickstart to build something end to end, or jump to the API tour for every available parsing, conversion, comparison and arithmetic option.

Documentation

If you want to...	Go to
learn the library by building something	Quickstart
look up a specific method and see it used	API tour
apply this to a pandas or polars series	Working with dataframes
validate ISO week strings on a model field	Working with Pydantic
have weeks start on a day other than Monday	Weeks not starting on Monday
understand why the library works this way	Why iso-week-date?
read exact signatures and exceptions	API Reference

Custom offset

One of the main reasons for this library to exist is the flexibility to work with custom offsets, i.e. to add/subtract a custom offset (as timedelta) to the default ISO Week start, and get a "shifted" week. This is available both in the IsoWeek/IsoWeekDate classes and in the dataframe functionalities: see weeks not starting on Monday.

Contributing

Please read the contributing guidelines in the documentation site.

License

The project has a MIT Licence.