ISO Week Date Toolkit

2.3.0 · active · verified Thu Apr 16

The `iso-week-date` library provides a toolkit for working with ISO Week date formats, specifically YYYY-WNN and YYYY-WNN-D. It offers `IsoWeek` and `IsoWeekDate` classes to manage these date formats, facilitating parsing, conversion, and operations directly, thus avoiding common pitfalls associated with converting between string, `date`, and `datetime` objects in Python. The current version is 2.3.0, and it maintains a regular release cadence as needed for updates and new features.

Common errors

```
ValueError: Invalid week: 53 (for a 52-week year)
```
cause Attempting to create an IsoWeek or IsoWeekDate object with week number 53 for a year that, according to ISO 8601, only has 52 weeks. Some tools might implicitly roll week 53 into week 1 of the next year, which isn't always correct or desired.

fix Ensure the year and week number combination is valid for the ISO week calendar. You can use `IsoWeek.weeks_in_year(year)` to check how many weeks a specific ISO year has. For example, `iso_week_date.IsoWeek.weeks_in_year(2021)` will return 52, so `IsoWeek(2021, 53)` would be invalid.
```
date 'YYYY-MM-DD' converts to wrong ISO week-year (e.g., 2024-12-30 -> 2025-W01-1)
```
cause This is not an error but a common misunderstanding of the ISO week-numbering system. The ISO year is defined by the week containing the first Thursday of the Gregorian year. Consequently, days at the end of a Gregorian year might fall into week 1 of the *next* ISO year, and days at the beginning of a Gregorian year might fall into the last week of the *previous* ISO year.

fix Understand that the ISO week-numbering year is distinct from the Gregorian calendar year. The library correctly implements this logic. When converting a `datetime.date` to `IsoWeekDate`, the resulting `IsoWeekDate.year` will reflect the correct ISO year, not necessarily the Gregorian year of the input date.
```
datetime.strptime('2023-W10-1', '%Y-W%W-%w') returns incorrect date/week
```
cause Incorrect format codes used with Python's built-in `strptime`. `%W` and `%w` are not for ISO week date parsing. `%W` uses a Sunday-to-Saturday week with week 0 for days before the first Sunday, and `%w` is the weekday (0=Sunday).

fix When using `strptime` for ISO week dates, use `%G` for the ISO year, `%V` for the ISO week number, and `%u` for the ISO weekday (1=Monday to 7=Sunday). The correct format string for 'YYYY-WNN-D' is `'%G-W%V-%u'`.

Warnings

gotcha The ISO week-numbering year can differ from the Gregorian calendar year for dates around January 1st. For instance, December 30, 2024 (Gregorian) is actually part of Week 1 of ISO year 2025. Conversely, early January days might belong to the previous ISO year's last week. This is a common source of off-by-one year errors when mixing ISO and Gregorian calendar logic without proper handling.
Fix: Always use the `iso-week-date` library's `year` property for the ISO year, or use `datetime.isocalendar()` for native `datetime` objects to get the correct ISO year, week, and weekday. Avoid relying on the Gregorian year for ISO week calculations near year boundaries.
gotcha When working with `datetime` objects, using `strftime('%W')` or `strptime('%W')` will *not* provide ISO week numbers. `%W` defines week 0 as all days in a new year preceding the first Monday, which is not ISO 8601 compliant. This can lead to incorrect week numbers and year associations.
Fix: For ISO week numbers with `datetime`, use `date.isocalendar().week` for getting the week number and `%V` with `strftime` for formatting, and ensure your input string for `strptime` aligns with ISO 8601 for week-based dates (`%G-%V-%u`). The `iso-week-date` library handles these distinctions correctly internally.
gotcha Trying to parse or represent non-existent week 53 for years that only have 52 ISO weeks can lead to unexpected results or errors in some systems or when using incorrect formatting. While `iso-week-date` is designed to handle this, incorrect manual parsing or logic may misinterpret these boundary conditions.
Fix: Rely on the library's methods for validation and conversion. If manually working with ISO week numbers, be aware that a year has 53 weeks if January 1st or December 31st falls on a Thursday. The `IsoWeek.weeks_in_year()` method can help determine this programmatically.

Install

pip install iso-week-date Install stable version

Imports

IsoWeek
wrong:
```
from isoweek import Week
```
correct:
```
from iso_week_date import IsoWeek
```
The 'isoweek' library is a different package with a similar purpose; ensure you are importing from 'iso_week_date'.
IsoWeekDate
```
from iso_week_date import IsoWeekDate
```

Quickstart

Demonstrates creating `IsoWeek` and `IsoWeekDate` objects from strings and `datetime.date` objects, and accessing their properties.

from iso_week_date import IsoWeek, IsoWeekDate
from datetime import date

# Create an IsoWeek object
week = IsoWeek.from_string("2023-W10")
print(f"IsoWeek from string: {week}")

# Get the Monday of the week
monday_date = week.monday
print(f"Monday of {week}: {monday_date}")

# Create an IsoWeekDate object
isodate = IsoWeekDate.from_string("2020-W01-1") # Monday of week 1, 2020
print(f"IsoWeekDate from string: {isodate}")

# Convert a datetime.date object to IsoWeekDate
current_date = date(2023, 3, 8)
isodate_from_date = IsoWeekDate.from_date(current_date)
print(f"IsoWeekDate from {current_date}: {isodate_from_date}")

# Access properties
print(f"Year: {isodate.year}, Week: {isodate.week_number}, Day: {isodate.day}")

view raw JSON →