isoweek

library1.3.3pypypi✓ verified 21d ago

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.

serialization

pip install isoweek

github ↗package ↗

INSTALL

IMPORT

SIG · ISOWEEK

isoweek

serializationpythonv1.3.3

Install

1.5s avg

Import

10ms

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 v1.3.3 · 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.95 runs

installs and imports cleanly · install 0.0s · import 0.002s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.002s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

Week

✓ from isoweek import Week

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

Debug

Known issues

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

affects: <=1.3.3

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

affects: All versions (<=1.3.3)

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

affects: All versions (<=1.3.3)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'isoweek'

The 'isoweek' library has not been installed in your Python environment or is not accessible.

fix

Install the library using pip: `pip install isoweek`

ValueError: year must be in 1..9999

The year provided to the `isoweek.Week` constructor is outside the valid range of 1 to 9999.

fix

Ensure the year argument for `isoweek.Week(year, week)` is an integer between 1 and 9999 inclusive.

AttributeError: 'Week' object has no attribute 'day'

You are trying to access an attribute or method (like 'day' or 'isocalendar') that exists on `datetime.date` objects but not on `isoweek.Week` objects, or you are attempting to access a specific day without calling the appropriate method.

fix

To get a specific day of the week, use methods like `w.monday()`, `w.tuesday()`, up to `w.sunday()`. If you need a `datetime.date` object, you can convert it using these methods.

Upgrade

Version history

1.3.3latest on PyPI · released Jan 4, 2017

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttp://github.com/gisle/isoweek ↗

packagehttps://pypi.org/project/isoweek/ ↗