Repository files navigation

iso-week-date is a toolkit to work with strings representingISO Week date in two formats, namely:

• Week formatYYYY-WNN (date format%Y-W%V)
• Week date formatYYYY-WNN-D (date format%Y-W%V-%u)

whereYYYY represents the year,W is a literal,NN represents the week number, andD represents the day of the week.

In a nutshell it provides:

• IsoWeek andIsoWeekDate classes that implement a series of methods to work with ISO Week (Date) formats directly, avoiding the pitfalls of going back and forth between string, date and datetime python objects.
• pandas andpolars functionalities (and namespaces) to work with series of ISO Week dates.

Documentation |Source Code |Issue Tracker

iso-week-date is published as a Python package onpypi, 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.gitcd iso-week-datepython -m pip install.

• To work withIsoWeek andIsoWeekDate classes, no additional dependency is required.
• pandas andpolars functionalities require the installation of the respective libraries.

This is a high level overview of the features provided by theiso-week-date package.

TheIsoWeek andIsoWeekDate classes provide the following functionalities:

• Parsing from string, date and datetime objects
• Conversion to string, date and datetime objects
• Comparison operations betweenIsoWeek (respIsoWeekDate) objects
• Addition withint andtimedelta types
• Subtraction withint,timedelta andIsoWeek (respIsoWeekDate) types
• Range between twoIsoWeek (resp.IsoWeekDate) objects
• __next__ method to generate the nextIsoWeek (resp.IsoWeekDate) object

IsoWeek unique methods/features:

• days properties that lists the dates in the given week
• nth method to get thenth day of the week as date
• in operator andcontains method to check if a (iterable of) week(s), string(s) and/or date(s) is contained in the given week
• weeksout method to generate a list of weeks that aren_weeks after the given week
• Addition and subtraction withint defaults to adding/subtracting weeks

IsoWeekDate unique methods/features:

• day property that returns the weekday as integer
• isoweek property that returns the ISO Week of the given date (as string)
• daysout method to generate a list of dates that aren_days after the given date
• Addition and subtraction withint defaults to adding/subtracting days

pandas_utils andpolars_utils modules provide functionalities to work with and move back and forth withseries of ISO Week date formats.

In specific both modules implements the following functionalities:

• datetime_to_isoweek anddatetime_to_isoweekdate to convert a series of datetime objects to a series of ISO Week (date) strings
• isoweek_to_datetime andisoweekdate_to_datetime to convert a series of ISO Week (date) strings to a series of datetime objects
• is_isoweek_series andis_isoweekdate_series to check if a string series values match the ISO Week (date) format

To get started withIsoWeek andIsoWeekDate classes please refer to thequickstart documentation section.

To check examples on how to work withpandas andpolars functionalities please refer to thedataframe modules documentation section.

One of the main reason for this library to exist is the need and the flexibility to work with custom offsets, i.e. to be able to add/subtract a custom offset (astimedelta) to the default ISO Week start and given date, and get a "shifted" week.

This feature is available both in theIsoWeek andIsoWeekDate classes and the dataframe functionalities.

To check an example see theworking with custom offset section.

Please read thecontributing guidelines in the documentation site.

The project has aMIT Licence.