ISO Week Objects

1.3.3 · maintenance · verified Sun Apr 12

The `isoweek` module provides the `Week` class, which represents specific weeks spanning Monday to Sunday, adhering to the ISO 8601 week definition. It correctly handles the 52 or 53 numbered weeks in a year, where Week 1 is the first week with four or more days in January. The library is lightweight and immutable, offering an interface similar to `datetime.date` objects. The current version is 1.3.3, and the project appears to be in maintenance mode with infrequent updates, with its last PyPI release in 2017 and GitHub activity noted as 5 years ago.

Warnings

gotcha Python's built-in `datetime.strptime`'s `%W` directive (week number with Monday as first day) does not follow ISO 8601 week numbering rules for determining the year-week boundary. Using `%W` for ISO weeks can lead to incorrect date calculations, especially for weeks spanning year ends. The `isoweek` library correctly implements ISO 8601.
Fix: Always use `isoweek.Week` for ISO 8601 compliant week handling. Avoid `datetime.strptime` with `%W` when ISO weeks are required.
gotcha The `isoweek` library has not seen significant updates since its 1.3.3 release (PyPI 2017, GitHub activity noted as 5 years ago). While functional and stable for its intended purpose, it may not leverage modern Python features (e.g., type hints, `datetime` module improvements), nor will it receive active maintenance or bug fixes for new Python versions or edge cases. For new projects requiring active development or deeper integration with contemporary Python ecosystems, consider more recently maintained alternatives like `iso-week-date`.
Fix: Evaluate whether the existing functionality meets current project needs. For long-term projects or those requiring modern Python features, consider `iso-week-date` or integrating `datetime.date.isocalendar()` for basic ISO week needs.
gotcha ISO 8601 week numbering includes complexities like years with 53 weeks and how week 1 is defined (first week with 4 or more days in January). Users unfamiliar with these rules might misunderstand how `Week` objects handle year boundaries or week counts, potentially leading to off-by-one errors or unexpected year assignments. `isoweek` correctly adheres to the ISO 8601 standard, but this requires user understanding of the standard.
Fix: Familiarize yourself with the ISO 8601 week date standard. Specifically, note that Week 1 is the first week containing a Thursday, or equivalently, the first week with at least four days in the new year.

Install

pip install isoweek Install stable version

Imports

Week
```
from isoweek import Week
```

Quickstart

Demonstrates creating Week objects, retrieving days, getting the current week, finding the week for a specific date, and checking date containment within a week.

from isoweek import Week
from datetime import date

# Create a Week object
w = Week(2023, 10) # 10th week of 2023
print(f"Week: {w}")

# Get days of the week
print(f"Monday of week {w}: {w.monday()}")
print(f"Sunday of week {w}: {w.sunday()}")
print(f"All days: {w.days()}")

# Get current week
current_week = Week.thisweek()
print(f"Current ISO week: {current_week}")

# Get week containing a specific date
some_date = date(2023, 3, 8)
week_of_date = Week.withdate(some_date)
print(f"Week of {some_date}: {week_of_date}")

# Check if a date is in a week
print(f"Is {some_date} in {w}? {w.contains(some_date)}")
print(f"Is {some_date} in {week_of_date}? {week_of_date.contains(some_date)}")

view raw JSON →