Toolkit to work with str representing ISO Week date format
Project description
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.
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
andtimedelta
types - Subtraction with
int
,timedelta
andIsoWeek
types - Range between (iso)weeks
- Weeksout generation
in
operator andcontains
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 formatiw = IsoWeek("2023-W01") iw.value, iw._offset # "2023-W01", datetime.timedelta(0)
-
str
in compact format YYYYWNNIsoWeek.from_compact("2023W01")
-
date
ordatetime
objectsIsoWeek.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
andtimedelta
types:iw + 1 # IsoWeek("2023-W02") iw + timedelta(weeks=2) # IsoWeek("2023-W03")
-
Subtraction with
int
,timedelta
andIsoWeek
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 andcontains
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for iso_week_date-0.0.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 21eca8fff9fac7f2b7040f34d58166fd155bdf6777022ae0f5bc1ccd8582bbe4 |
|
MD5 | bb660611c049770fba1528ebe51562da |
|
BLAKE2b-256 | 87101cfd78dccf088751038e37aa2755f5be0b06a9cc32506f70bd9df114d49f |