dataframe(s) extensions (#46)

* pandas Series extension

* polars Series and Expr extension

* tests and docs update

README.md

@@ -96,17 +96,17 @@ In specific both modules implements the following functionalities:
 
 ### Quickstart
 
-To get started with `IsoWeek` and `IsoWeekDate` classes please refer to the [quickstart](https://fbruzzesi.github.io/getting-started/quickstart) documentation section.
+To get started with `IsoWeek` and `IsoWeekDate` classes please refer to the [quickstart](https://fbruzzesi.github.io/user-guide/quickstart) documentation section.
 
-To check examples on how to work with _pandas_ and _polars_ functionalities please refer to the [dataframe modules](https://fbruzzesi.github.io/getting-started/dataframe-modules) documentation section.
+To check examples on how to work with _pandas_ and _polars_ functionalities please refer to the [dataframe modules](https://fbruzzesi.github.io/user-guide/dataframe-modules) documentation section.
 
 ### Custom offset
 
 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 (as `timedelta`) to the default ISO Week start and given date, and get a "shifted" week.
 
 This feature is available both in the `IsoWeek` and `IsoWeekDate` classes and the dataframe functionalities.
 
-To check an example see the [working with custom offset](https://fbruzzesi.github.io/iso-week-date/getting-started/quickstart/#working-with-custom-offset) section.
+To check an example see the [working with custom offset](https://fbruzzesi.github.io/iso-week-date/user-guide/quickstart/#working-with-custom-offset) section.
 
 ## Contributing
 

docs/api/baseisoweek.md

@@ -2,5 +2,5 @@
 
 ::: iso_week_date.base.BaseIsoWeek
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true

docs/api/isoweek.md

@@ -2,5 +2,5 @@
 
 ::: iso_week_date.isoweek.IsoWeek
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true

docs/api/isoweekdate.md

@@ -2,5 +2,5 @@
 
 ::: iso_week_date.isoweekdate.IsoWeekDate
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true

docs/api/mixins.md

@@ -10,15 +10,15 @@ In particular:
 
 ::: iso_week_date.mixin.ParserMixin
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true
 
 ::: iso_week_date.mixin.ConverterMixin
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true
 
 ::: iso_week_date.mixin.ComparatorMixin
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true

docs/api/pandas.md

@@ -1,31 +1,47 @@
 # Pandas utils module
 
+## Functions
+
 ::: iso_week_date.pandas_utils.datetime_to_isoweek
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true
+        heading_level: 3
 
 ::: iso_week_date.pandas_utils.datetime_to_isoweekdate
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true
+        heading_level: 3
 
 ::: iso_week_date.pandas_utils.isoweek_to_datetime
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true
+        heading_level: 3
 
 ::: iso_week_date.pandas_utils.isoweekdate_to_datetime
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true
+        heading_level: 3
 
 ::: iso_week_date.pandas_utils.is_isoweek_series
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true
+        heading_level: 3
 
 ::: iso_week_date.pandas_utils.is_isoweekdate_series
     options:
-        show_root_full_path: false
+        show_root_full_path: true
+        show_root_heading: true
+        heading_level: 3
+
+## Series extension
+
+::: iso_week_date.pandas_utils.SeriesIsoWeek
+    options:
+        show_root_full_path: true
         show_root_heading: true
+        heading_level: 3

docs/api/polars.md

@@ -1,31 +1,47 @@
 # Polars utils module
 
+## Functions
+
 ::: iso_week_date.polars_utils.datetime_to_isoweek
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true
+        heading_level: 3
 
 ::: iso_week_date.polars_utils.datetime_to_isoweekdate
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true
+        heading_level: 3
 
 ::: iso_week_date.polars_utils.isoweek_to_datetime
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true
+        heading_level: 3
 
 ::: iso_week_date.polars_utils.isoweekdate_to_datetime
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true
+        heading_level: 3
 
 ::: iso_week_date.polars_utils.is_isoweek_series
     options:
-        show_root_full_path: false
+        show_root_full_path: true
         show_root_heading: true
+        heading_level: 3
 
 ::: iso_week_date.polars_utils.is_isoweekdate_series
     options:
-        show_root_full_path: false
+        show_root_full_path: true
+        show_root_heading: true
+        heading_level: 3
+
+## Series extension
+
+::: iso_week_date.polars_utils.SeriesIsoWeek
+    options:
+        show_root_full_path: true
         show_root_heading: true
+        heading_level: 3

docs/contribute.md

@@ -44,7 +44,8 @@ When submitting a pull request, please make sure that you've followed the steps
     ruff format iso_week_date tests
     ```
 
-As part of the checks on pull requests, it is checked whether the code follows those standards. To ensure that the standard is met, it is recommended to install [pre-commit hooks](https://pre-commit.com/):
+As part of the checks on pull requests, it is checked whether the code follows those standards.
+To ensure that the standard is met, it is recommended to install [pre-commit hooks](https://pre-commit.com/):
 
 ```bash
 python -m pip install pre-commit

docs/index.md

@@ -57,14 +57,14 @@ In a nutshell it provides:
 
 ## Usage
 
-To get started with `IsoWeek` and `IsoWeekDate` classes please refer to the [quickstart](getting-started/quickstart.md) section.
+To get started with `IsoWeek` and `IsoWeekDate` classes please refer to the [quickstart](user-guide/quickstart.md) section.
 
-To check examples on how to work with _pandas_ and _polars_ functionalities please refer to the [dataframe modules](getting-started/dataframe-modules.md) section.
+To check examples on how to work with _pandas_ and _polars_ functionalities please refer to the [dataframe modules](user-guide/dataframe-modules.md) section.
 
 ## Contributing
 
 Please read the [contributing guidelines](contribute.md) in the documentation site.
 
 ## License
 
-The project has a [MIT Licence](https://github.com/FBruzzesi/deczoo/blob/main/LICENSE).
+The project has a [MIT Licence](https://github.com/FBruzzesi/iso-week-date/blob/main/LICENSE).

docs/user-guide/dataframe-modules.md

@@ -0,0 +1,124 @@
+# Dataframe modules
+
+The [`pandas_utils`](../api/pandas.md) and [`polars_utils`](../api/polars.md) modules provide the same API to work with `pandas.Series` and `polars.Series`/`polars.Expr` respectively.
+
+The utilities come in two _flavors_: [functions](#functions) and [extensions](#extensions).
+
+## Functions
+
+The functions approach takes the series/expr as an argument and returns a new series/expr.
+
+Available functions are:
+
+- `datetime_to_isoweek` and `datetime_to_isoweekdate`: converts a `datetime` series to an ISO week (date) series.
+- `isoweek_to_datetime` and `isoweekdate_to_datetime`: converts an ISO week date series to a `datetime` series.
+- `is_isoweek_series` and `is_isoweekdate_series`: checks if a series is an ISO week (date) series.
+
+```py title="pandas"
+import pandas as pd
+from datetime import date, timedelta
+from iso_week_date.pandas_utils import datetime_to_isoweek, isoweek_to_datetime, is_isoweek_series
+
+s_date = pd.Series(pd.date_range(date(2023, 1, 1), date(2023, 1, 10), freq="1d"))
+datetime_to_isoweek(series=s_date, offset=pd.Timedelta(days=1)).to_list()
+# ['2022-W52', '2022-W52', '2023-W01',..., '2023-W01', '2023-W02']
+
+s_iso = pd.Series(["2022-W52", "2023-W01", "2023-W02"])
+isoweek_to_datetime(series=s_iso, offset=pd.Timedelta(days=1))
+'''
+0   2022-12-27
+1   2023-01-03
+2   2023-01-10
+dtype: datetime64[ns]
+'''
+
+is_isoweek_series(s_iso)  # True
+is_isoweek_series(s_iso + "abc")  # False
+```
+
+```py title="polars"
+import polars as pl
+from datetime import date, timedelta
+from iso_week_date.polars_utils import datetime_to_isoweekdate, isoweekdate_to_datetime, is_isoweekdate_series
+
+s_date = pl.date_range(date(2023, 1, 1), date(2023, 1, 10), interval="1d", eager=True)
+datetime_to_isoweekdate(s_date, offset=timedelta(days=1)).to_list()
+# ['2022-W52-6', '2022-W52-7', '2023-W01-1',..., '2023-W01-7', '2023-W02-1']
+
+s_iso = pl.Series(["2022-W52-1", "2023-W01-2", "2023-W02-7"])
+isoweekdate_to_datetime(series=s_iso,offset=timedelta(days=1))
+'''
+date
+2022-12-27
+2023-01-04
+2023-01-16
+'''
+
+is_isoweekdate_series(s_iso)  # True
+is_isoweekdate_series(s_iso + "abc")  # False
+```
+
+## Extensions
+
+On the other hand the extensions[^1] approach extends the `pandas.Series` and `polars.Series`/`polars.Expr` classes with new methods.
+
+The extensions are available through the `isoweek` namespace, and the methods available are the same as the functions.
+
+"Translating" the previous examples to extensions:
+
+```py title="pandas"
+import pandas as pd
+from iso_week_date.pandas_utils import SeriesIsoWeek  # noqa: F401 (1)
+
+s_date = pd.Series(pd.date_range(date(2023, 1, 1), date(2023, 1, 10), freq="1d"))
+s_date.isoweek.datetime_to_isoweek(offset=pd.Timedelta(days=1)).to_list()
+# ['2022-W52', '2022-W52', '2023-W01',..., '2023-W01', '2023-W02']
+
+s_iso = pd.Series(["2022-W52", "2023-W01", "2023-W02"])
+s_iso.isoweek.isoweek_to_datetime(offset=pd.Timedelta(days=1))
+'''
+0   2022-12-27
+1   2023-01-03
+2   2023-01-10
+dtype: datetime64[ns]
+'''
+
+s_iso.isoweek.is_isoweek(s_iso)  # True
+s_iso.isoweek.is_isoweek(s_iso + "abc")  # False
+```
+
+1. The import of `SeriesIsoWeek` is needed to register the extensions.
+
+    _noqa: F401_ is added to avoid the linter(s) warning about the unused import.
+
+```py title="polars"
+import polars as pl
+from iso_week_date.polars_utils import SeriesIsoWeek  # noqa: F401 (1)
+
+s_date = pl.date_range(date(2023, 1, 1), date(2023, 1, 10), interval="1d")
+s_date.isoweek.datetime_to_isoweekdate(offset=timedelta(days=1)).to_list()
+# ['2022-W52-6', '2022-W52-7', '2023-W01-1',..., '2023-W01-7', '2023-W02-1']
+
+s_iso = pl.Series(["2022-W52-1", "2023-W01-2", "2023-W02-7"])
+s_iso.isoweek.isoweekdate_to_datetime(offset=timedelta(days=1))
+'''
+date
+2022-12-27
+2023-01-04
+2023-01-16
+'''
+
+s_iso.isoweek.is_isoweekdate()  # True
+(s_iso + "abc").isoweek.is_isoweekdate_series()  # False
+```
+
+1. The import of `SeriesIsoWeek` is needed to register the extensions.
+
+    _noqa: F401_ is added to avoid the linter(s) warning about the unused import.
+
+!!! note
+    Polars extension is valid for both `Series` and `Expr` classes.
+
+    This means that it is possible to use the extension in any [polars context](https://pola-rs.github.io/polars/user-guide/concepts/contexts/) in which it would be possible to use an expression.
+
+[^1]: Extending [pandas](https://pandas.pydata.org/docs/development/extending.html) and [polars](https://pola-rs.github.io/polars/py-polars/html/reference/api.html)

docs/getting-started/features.md → docs/user-guide/features.md

@@ -45,4 +45,4 @@ One of the main reason for this library to exist is the need and the flexibility
 
 This feature is available both in the `IsoWeek` and `IsoWeekDate` classes and the dataframe functionalities.
 
-To check an example see the [working with custom offset](../getting-started/quickstart.md/#working-with-custom-offset) section.
+To check an example see the [working with custom offset](../user-guide/quickstart.md/#working-with-custom-offset) section.