| Name | iso-week-date JSON |
| Version |
1.3.0
JSON |
| download |
| home_page | None |
| Summary | Toolkit to work with str representing ISO Week date format |
| upload_time | 2024-05-10 21:18:19 |
| maintainer | None |
| docs_url | None |
| author | Francesco Bruzzesi |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2023 Francesco Bruzzesi
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ISO Week Date
[](https://github.com/astral-sh/ruff)
<img src="docs/img/iso-week-date-logo.svg" width=160 height=160 align="right">
**iso-week-date** is a toolkit to work with strings representing [ISO Week date](https://en.wikipedia.org/wiki/ISO_week_date) in two formats, namely:
- Week format **YYYY-WNN** (date format **%Y-W%V**)
- Week date format **YYYY-WNN-D** (date format **%Y-W%V-%u**)
where _YYYY_ represents the year, _W_ is a literal, _NN_ represents the week number, and _D_ represents the day of the week.
In a nutshell it provides:
- [`IsoWeek`](https://fbruzzesi.github.io/iso-week-date/api/isoweek/) and [`IsoWeekDate`](https://fbruzzesi.github.io/iso-week-date/api/isoweekdate/) 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](https://fbruzzesi.github.io/iso-week-date/api/pandas/) and [polars](https://fbruzzesi.github.io/iso-week-date/api/polars/) functionalities (and namespaces) to work with series of ISO Week dates.
---
[Documentation](https://fbruzzesi.github.io/iso-week-date/) | [Source Code](https://github.com/fbruzzesi/iso-week-date/) | [Issue Tracker](https://github.com/fbruzzesi/iso-week-date/issues)
---
## Installation
**iso-week-date** is published as a Python package on [pypi](https://pypi.org/project/iso-week-date/), and it can be installed with pip, or directly from source using git, or with a local clone:
- **pip** (suggested):
```bash
python -m pip install iso-week-date
```
- **pip + source/git**:
```bash
python -m pip install git+https://github.com/FBruzzesi/iso-week-date.git
```
- **local clone**:
```bash
git clone https://github.com/FBruzzesi/iso-week-date.git
cd iso-week-date
python -m pip install .
```
### Dependencies
- To work with `IsoWeek` and `IsoWeekDate` classes, no additional dependency is required.
- _pandas_ and _polars_ functionalities require the installation of the respective libraries.
## Getting Started
### Available features
This is a high level overview of the features provided by the `iso-week-date` package.
The [`IsoWeek`](https://fbruzzesi.github.io/iso-week-date/api/isoweek/) and [`IsoWeekDate`](https://fbruzzesi.github.io/iso-week-date/api/isoweekdate/) classes provide the following functionalities:
- Parsing from string, date and datetime objects
- Conversion to string, date and datetime objects
- Comparison operations between `IsoWeek` (resp `IsoWeekDate`) objects
- Addition with `int` and `timedelta` types
- Subtraction with `int`, `timedelta` and `IsoWeek` (resp `IsoWeekDate`) types
- Range between two `IsoWeek` (resp. `IsoWeekDate`) objects
- `__next__` method to generate the next `IsoWeek` (resp. `IsoWeekDate`) object
`IsoWeek` unique methods/features:
- `days` properties that lists the dates in the given week
- `nth` method to get the _nth_ day of the week as date
- `in` operator and `contains` 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 are _n\_weeks_ after the given week
- Addition and subtraction with `int` 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 are _n\_days_ after the given date
- Addition and subtraction with `int` defaults to adding/subtracting days
[`pandas_utils`](https://fbruzzesi.github.io/iso-week-date/api/pandas/) and [`polars_utils`](https://fbruzzesi.github.io/iso-week-date/api/polars/) modules provide functionalities to work with and move back and forth with _series_ of ISO Week date formats.
In specific both modules implements the following functionalities:
- `datetime_to_isoweek` and `datetime_to_isoweekdate` to convert a series of datetime objects to a series of ISO Week (date) strings
- `isoweek_to_datetime` and `isoweekdate_to_datetime` to convert a series of ISO Week (date) strings to a series of datetime objects
- `is_isoweek_series` and `is_isoweekdate_series` to check if a string series values match the ISO Week (date) format
### Quickstart
To get started with `IsoWeek` and `IsoWeekDate` classes please refer to the [quickstart](https://fbruzzesi.github.io/iso-week-date/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/iso-week-date/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/user-guide/quickstart/#working-with-custom-offset) section.
## Contributing
Please read the [contributing guidelines](https://fbruzzesi.github.io/iso-week-date/contribute/) in the documentation site.
## License
The project has a [MIT Licence](https://github.com/FBruzzesi/iso-week-date/blob/main/LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "iso-week-date",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Francesco Bruzzesi",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/23/c2/1a0a02e9a96859fce2cf01bfb5567089fa787f1924e25a0064510066e871/iso_week_date-1.3.0.tar.gz",
"platform": null,
"description": "# ISO Week Date\n\n\n\n[](https://github.com/astral-sh/ruff)\n\n\n\n<img src=\"docs/img/iso-week-date-logo.svg\" width=160 height=160 align=\"right\">\n\n**iso-week-date** is a toolkit to work with strings representing [ISO Week date](https://en.wikipedia.org/wiki/ISO_week_date) in two formats, namely:\n\n- Week format **YYYY-WNN** (date format **%Y-W%V**)\n- Week date format **YYYY-WNN-D** (date format **%Y-W%V-%u**)\n\nwhere _YYYY_ represents the year, _W_ is a literal, _NN_ represents the week number, and _D_ represents the day of the week.\n\nIn a nutshell it provides:\n\n- [`IsoWeek`](https://fbruzzesi.github.io/iso-week-date/api/isoweek/) and [`IsoWeekDate`](https://fbruzzesi.github.io/iso-week-date/api/isoweekdate/) 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.\n- [pandas](https://fbruzzesi.github.io/iso-week-date/api/pandas/) and [polars](https://fbruzzesi.github.io/iso-week-date/api/polars/) functionalities (and namespaces) to work with series of ISO Week dates.\n\n---\n\n[Documentation](https://fbruzzesi.github.io/iso-week-date/) | [Source Code](https://github.com/fbruzzesi/iso-week-date/) | [Issue Tracker](https://github.com/fbruzzesi/iso-week-date/issues)\n\n---\n\n## Installation\n\n**iso-week-date** is published as a Python package on [pypi](https://pypi.org/project/iso-week-date/), and it can be installed with pip, or directly from source using git, or with a local clone:\n\n- **pip** (suggested):\n\n ```bash\n python -m pip install iso-week-date\n ```\n\n- **pip + source/git**:\n\n ```bash\n python -m pip install git+https://github.com/FBruzzesi/iso-week-date.git\n ```\n\n- **local clone**:\n\n ```bash\n git clone https://github.com/FBruzzesi/iso-week-date.git\n cd iso-week-date\n python -m pip install .\n ```\n\n### Dependencies\n\n- To work with `IsoWeek` and `IsoWeekDate` classes, no additional dependency is required.\n- _pandas_ and _polars_ functionalities require the installation of the respective libraries.\n\n## Getting Started\n\n### Available features\n\nThis is a high level overview of the features provided by the `iso-week-date` package.\n\nThe [`IsoWeek`](https://fbruzzesi.github.io/iso-week-date/api/isoweek/) and [`IsoWeekDate`](https://fbruzzesi.github.io/iso-week-date/api/isoweekdate/) classes provide the following functionalities:\n\n- Parsing from string, date and datetime objects\n- Conversion to string, date and datetime objects\n- Comparison operations between `IsoWeek` (resp `IsoWeekDate`) objects\n- Addition with `int` and `timedelta` types\n- Subtraction with `int`, `timedelta` and `IsoWeek` (resp `IsoWeekDate`) types\n- Range between two `IsoWeek` (resp. `IsoWeekDate`) objects\n- `__next__` method to generate the next `IsoWeek` (resp. `IsoWeekDate`) object\n\n`IsoWeek` unique methods/features:\n\n- `days` properties that lists the dates in the given week\n- `nth` method to get the _nth_ day of the week as date\n- `in` operator and `contains` method to check if a (iterable of) week(s), string(s) and/or date(s) is contained in the given week\n- `weeksout` method to generate a list of weeks that are _n\\_weeks_ after the given week\n- Addition and subtraction with `int` defaults to adding/subtracting weeks\n\n`IsoWeekDate` unique methods/features:\n\n- `day` property that returns the weekday as integer\n- `isoweek` property that returns the ISO Week of the given date (as string)\n- `daysout` method to generate a list of dates that are _n\\_days_ after the given date\n- Addition and subtraction with `int` defaults to adding/subtracting days\n\n[`pandas_utils`](https://fbruzzesi.github.io/iso-week-date/api/pandas/) and [`polars_utils`](https://fbruzzesi.github.io/iso-week-date/api/polars/) modules provide functionalities to work with and move back and forth with _series_ of ISO Week date formats.\n\nIn specific both modules implements the following functionalities:\n\n- `datetime_to_isoweek` and `datetime_to_isoweekdate` to convert a series of datetime objects to a series of ISO Week (date) strings\n- `isoweek_to_datetime` and `isoweekdate_to_datetime` to convert a series of ISO Week (date) strings to a series of datetime objects\n- `is_isoweek_series` and `is_isoweekdate_series` to check if a string series values match the ISO Week (date) format\n\n### Quickstart\n\nTo get started with `IsoWeek` and `IsoWeekDate` classes please refer to the [quickstart](https://fbruzzesi.github.io/iso-week-date/user-guide/quickstart/) documentation section.\n\nTo check examples on how to work with _pandas_ and _polars_ functionalities please refer to the [dataframe modules](https://fbruzzesi.github.io/iso-week-date/user-guide/dataframe-modules/) documentation section.\n\n### Custom offset\n\nOne 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.\n\nThis feature is available both in the `IsoWeek` and `IsoWeekDate` classes and the dataframe functionalities.\n\nTo check an example see the [working with custom offset](https://fbruzzesi.github.io/iso-week-date/user-guide/quickstart/#working-with-custom-offset) section.\n\n## Contributing\n\nPlease read the [contributing guidelines](https://fbruzzesi.github.io/iso-week-date/contribute/) in the documentation site.\n\n## License\n\nThe project has a [MIT Licence](https://github.com/FBruzzesi/iso-week-date/blob/main/LICENSE).\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2023 Francesco Bruzzesi\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Toolkit to work with str representing ISO Week date format",
"version": "1.3.0",
"project_urls": {
"documentation": "https://fbruzzesi.github.io/iso-week-date/",
"issue-tracker": "https://github.com/fbruzzesi/iso-week-date/issues",
"repository": "https://github.com/fbruzzesi/iso-week-date"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5a1e4882cd0c3bf855e180d526afa86267f41a13837d09d85f7aadeb3a2b7b71",
"md5": "c0c32bbaaa900249d870ca1b7d6a32a0",
"sha256": "4fb831b7f0f3b1f39df1159bf5abdd6b62f87494b5993d500e73af3b52b6501e"
},
"downloads": -1,
"filename": "iso_week_date-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c0c32bbaaa900249d870ca1b7d6a32a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26204,
"upload_time": "2024-05-10T21:18:17",
"upload_time_iso_8601": "2024-05-10T21:18:17.542620Z",
"url": "https://files.pythonhosted.org/packages/5a/1e/4882cd0c3bf855e180d526afa86267f41a13837d09d85f7aadeb3a2b7b71/iso_week_date-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "23c21a0a02e9a96859fce2cf01bfb5567089fa787f1924e25a0064510066e871",
"md5": "775e0c388857ae02adc256f3dc7a2c2f",
"sha256": "3cc957493a28e6c253a689d82cf742d88119b3643c99946215fd86d70797ab91"
},
"downloads": -1,
"filename": "iso_week_date-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "775e0c388857ae02adc256f3dc7a2c2f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19698,
"upload_time": "2024-05-10T21:18:19",
"upload_time_iso_8601": "2024-05-10T21:18:19.079728Z",
"url": "https://files.pythonhosted.org/packages/23/c2/1a0a02e9a96859fce2cf01bfb5567089fa787f1924e25a0064510066e871/iso_week_date-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-10 21:18:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fbruzzesi",
"github_project": "iso-week-date",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "iso-week-date"
}
