{"id":4963,"library":"isoweek","title":"ISO Week Objects","description":"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.","status":"maintenance","version":"1.3.3","language":"en","source_language":"en","source_url":"http://github.com/gisle/isoweek","tags":["date","time","iso8601","week","calendar"],"install":[{"cmd":"pip install isoweek","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Week","correct":"from isoweek import Week"}],"quickstart":{"code":"from isoweek import Week\nfrom datetime import date\n\n# Create a Week object\nw = Week(2023, 10) # 10th week of 2023\nprint(f\"Week: {w}\")\n\n# Get days of the week\nprint(f\"Monday of week {w}: {w.monday()}\")\nprint(f\"Sunday of week {w}: {w.sunday()}\")\nprint(f\"All days: {w.days()}\")\n\n# Get current week\ncurrent_week = Week.thisweek()\nprint(f\"Current ISO week: {current_week}\")\n\n# Get week containing a specific date\nsome_date = date(2023, 3, 8)\nweek_of_date = Week.withdate(some_date)\nprint(f\"Week of {some_date}: {week_of_date}\")\n\n# Check if a date is in a week\nprint(f\"Is {some_date} in {w}? {w.contains(some_date)}\")\nprint(f\"Is {some_date} in {week_of_date}? {week_of_date.contains(some_date)}\")","lang":"python","description":"Demonstrates creating Week objects, retrieving days, getting the current week, finding the week for a specific date, and checking date containment within a week."},"warnings":[{"fix":"Always use `isoweek.Week` for ISO 8601 compliant week handling. Avoid `datetime.strptime` with `%W` when ISO weeks are required.","message":"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.","severity":"gotcha","affected_versions":"<=1.3.3"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions (<=1.3.3)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (<=1.3.3)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}