iso-week-date 0.0.1

Toolkit to work with str representing ISO Week date format

iso-week-date

iso-week-date is a toolkit to work with strings representing ISO Week date in the YYYY-WNN format.

In a nutshell it provides:

• a IsoWeek class implementing a series of functionalities and methods to work with ISO Week date format and avoiding the pitfalls of going back and forth between Iso Week, string and date/datetime object.
• pandas and polars functionalities to work with series of Iso Week dates.

---

Documentation | Source Code

---

Installation

iso-week-date is published as a Python package on pypi with the name of iso-week-date, and it can be installed with pip, or directly from source using git, or with a local clone:

• pip (suggested):

  python -m pip install iso-week-date
  

• pip + source/git:

  python -m pip install git+https://github.com/FBruzzesi/iso-week-date.git
  

• local clone:

  git clone https://github.com/FBruzzesi/iso-week-date.git
  cd iso-week-date
  python -m pip install .
  

Dependencies

• To work with IsoWeek class, no additional dependency is required.
• pandas and polars functionalities require the installation of the respective libraries.

Getting Started

Features

IsoWeek class provides the following functionalities:

• Parsing from string, date and datetime objects
• Conversion to string, date and datetime objects
• Comparison between IsoWeek objects
• Addition with int and timedelta types
• Subtraction with int, timedelta and IsoWeek types
• Range between (iso)weeks
• Weeksout generation
• in operator and contains method to check if a (iterable of) week(s) is contained in the given week value

pandas_utils and polars_utils modules provide functionalities to work with and move back and forth with series of Iso Week dates.

Quickstart

The IsoWeek class is accessible from the top-level module:

from datetime import date, datetime, timedelta
from iso_week_date import IsoWeek

An instance can be initialized from parsing multiple types:

• str in YYYY-WNN format

  iw = IsoWeek("2023-W01")
  iw.value, iw._offset # "2023-W01", datetime.timedelta(0)
  

• str in compact format YYYYWNN

  IsoWeek.from_compact("2023W01")
  

• date or datetime objects

  IsoWeek.from_date(date(2023, 1, 2))
  IsoWeek.from_datetime(datetime(2023, 1, 2, 12, 0, 0))
  

Once initialized, the instance provides the following methods:

• properties to access year, week and days of the week:

  iw.year # 2023
  iw.week # 1
  iw.days # (date(2023, 1, 2),..., date(2023, 1, 8))
  

• Conversion to multiple types:

  iw.to_str() # "2023-W01"
  iw.to_compact() # "2023W01"
  iw.to_date() # date(2023, 1, 2)
  iw.to_date(weekday=2) # date(2023, 1, 3)
  iw.to_datetime() # datetime(2023, 1, 2, 0, 0)
  

• Comparison operations:

  iw == IsoWeek("2023-W01") # True
  iw == IsoWeek("2023-W02") # False
  iw < IsoWeek("2023-W02") # True
  iw > IsoWeek("2023-W02") # False
  

• Addition with int and timedelta types:

  iw + 1 # IsoWeek("2023-W02")
  iw + timedelta(weeks=2) # IsoWeek("2023-W03")
  

• Subtraction with int, timedelta and IsoWeek types:

  iw - 1 # IsoWeek("2022-W52")
  iw - timedelta(weeks=2) # IsoWeek("2022-W51")
  iw - IsoWeek("2022-W52") # 1
  

• Range between (iso)weeks:

  tuple(IsoWeek.range(start="2023-W01", end="2023-W07", step=2, inclusive="both", as_str=True))  # ('2023-W01', '2023-W03', '2023-W05', '2023-W07')
  

• Weeksout generator:

  tuple(iw.weeksout(3)) # ('2023-W02', '2023-W03', '2023-W04')
  

• in operator and contains method to check if a (iterable of) week(s) is contained in the given week value:

  date(2023, 1, 1) in iw # False
  date(2023, 1, 2) in iw # True
  
  iw.contains((IsoWeek("2023-W01"), date(2023, 1, 1), date(2023, 1, 2))) # (True, False, True)
  

Working with custom offset

The "standard" ISO Week starts on Monday and end on Sunday. However there are cases in which one may require a shift in the starting day of a week.

The IsoWeek class has one class attribute called offset_ which can be used to define a custom offset for the week.

class MyWeek(IsoWeek):
    """
    MyWeek class is a IsoWeek with custom offset of -2 days.
    Therefore MyWeek starts the Saturday before the "standard" ISO week.
    """
    offset_ = timedelta(days=-2)

This is all that is required to work with a custom shifted week.

Contributing

Please read the Contributing guidelines in the documentation site.

License

The project has a MIT Licence