{"id":7315,"library":"iso-week-date","title":"ISO Week Date Toolkit","description":"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.","status":"active","version":"2.3.0","language":"en","source_language":"en","source_url":"https://github.com/FBruzzesi/iso-week-date","tags":["date","time","iso8601","week-date","iso-week","datetime"],"install":[{"cmd":"pip install iso-week-date","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The 'isoweek' library is a different package with a similar purpose; ensure you are importing from 'iso_week_date'.","wrong":"from isoweek import Week","symbol":"IsoWeek","correct":"from iso_week_date import IsoWeek"},{"symbol":"IsoWeekDate","correct":"from iso_week_date import IsoWeekDate"}],"quickstart":{"code":"from iso_week_date import IsoWeek, IsoWeekDate\nfrom datetime import date\n\n# Create an IsoWeek object\nweek = IsoWeek.from_string(\"2023-W10\")\nprint(f\"IsoWeek from string: {week}\")\n\n# Get the Monday of the week\nmonday_date = week.monday\nprint(f\"Monday of {week}: {monday_date}\")\n\n# Create an IsoWeekDate object\nisodate = IsoWeekDate.from_string(\"2020-W01-1\") # Monday of week 1, 2020\nprint(f\"IsoWeekDate from string: {isodate}\")\n\n# Convert a datetime.date object to IsoWeekDate\ncurrent_date = date(2023, 3, 8)\nisodate_from_date = IsoWeekDate.from_date(current_date)\nprint(f\"IsoWeekDate from {current_date}: {isodate_from_date}\")\n\n# Access properties\nprint(f\"Year: {isodate.year}, Week: {isodate.week_number}, Day: {isodate.day}\")","lang":"python","description":"Demonstrates creating `IsoWeek` and `IsoWeekDate` objects from strings and `datetime.date` objects, and accessing their properties."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (Python's built-in `datetime` module)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"ValueError: Invalid week: 53 (for a 52-week 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.","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.","error":"date 'YYYY-MM-DD' converts to wrong ISO week-year (e.g., 2024-12-30 -> 2025-W01-1)"},{"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'`.","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).","error":"datetime.strptime('2023-W10-1', '%Y-W%W-%w') returns incorrect date/week"}]}