Registry / serialization / iso-week-date

iso-week-date

library2.3.0pypypi✓ verified 84d ago

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.

serialization data

pip install iso-week-date

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · ISO-WEEK-DATE

iso-week-date

serializationpythonv2.3.0

Install

1.6s avg

Import

102ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.107s · 18.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.097s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

IsoWeek

✓ from iso_week_date import IsoWeek

✗ from isoweek import Week

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

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}")

Debug

Known issues

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

affects: All versions

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

affects: All versions (Python's built-in `datetime` module)

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

affects: All versions

Errors

Common errors & fixes

ValueError: Invalid week: 53 (for a 52-week year)

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)

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

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'`.

Upgrade

Version history

2.3.0latest on PyPI · released Apr 1, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/fbruzzesi/iso-week-date ↗

packagehttps://pypi.org/project/iso-week-date/ ↗

docshttps://fbruzzesi.github.io/iso-week-date/ ↗