# Aika
Time interval parsing utilities for multiple languages.
## About
Aika provides date- and time-range parsing utilities for multiple languages.
It is based on [dateparser], [arbitrary-dateparser], and [DateRangeParser],
and aims for [DWIM]-like convenience and usefulness.
Currently, it supports 200 language locales through `dateparser`, and more
specific support for English and German through `arbitrary-dateparser`.
Contributions for other languages are welcome.
## Setup
Install the most recent version of Aika.
```shell
pip install --upgrade aika
```
## Usage
```doctest
>>> import datetime as dt
>>> from aika import TimeIntervalParser
>>>
>>> ti = TimeIntervalParser()
>>>
>>> ti.parse("Sat - Tue")
>>> (dt.datetime(2023, 8, 26, 0, 0), dt.datetime(2023, 8, 29, 23, 59, 59, 999999))
>>>
>>> ti.parse_single("1. Juli")
>>> dt.datetime(2023, 7, 1, 0, 0)
```
### Example Expressions
Aika understands all types of date-/time-range expressions like provided by the
packages it is based upon, and works with single dates too. This section enumerates
a few examples.
#### dateparser
##### Calendar notations
- Week: 2025W01
- Month: 2025M02, 2025-02
- Quarter: 2025Q03
- Year: 2025
##### Time deltas
- Day: `-1d`, `-1 day`
- Week: `-1w`, `-1 week`
- Month: `-1M`, `-1 month`
- Year: `-1y`, `-1 year`
- Quarter: `-3M`, `-3 months`
- Mixed: `-3d3h5m30s`
#### arbitrary-dateparser » English
- now
- today
- last week to next friday
- tomorrow - next week
- next month
- december
- July to December
- jul 1 to jul 7
- Sat - Tue
- in March
- 2024-08-20
#### arbitrary-dateparser » German
- jetzt
- heute
- letzte woche bis nächsten freitag
- morgen - nächste woche
- nächster monat
- dezember
- Juli-Dezember
- jul 1 to jul 7
- von Samstag bis Dienstag
- im März
- 20\. August 2024
- 20.8.2024
- 20.08.2024
#### DateRangeParser » English
- 1st july
- March 2024
- July to December
- 27th-29th June 2010
- 30 May to 9th Aug
- 3rd Jan 1980 -- 2nd Jan 2013
- Wed 23 Jan -> Sat 16 February 2013
- Tuesday 29 May - Sat 2 June 2012
- From 1 to 9 Jul
- jul 1 to jul 9
- 14th July 1988
- Jan 2011 - Mar 2014
- 07:00 Tue 7th June - 17th July 3:30pm
<br>**Caveat**: Times will currently be ignored.
#### DateRangeParser » German
- 1\. Juli
- 1\. bis 7. Juli
- März 2024
- Juli bis Dezember
- Vom 3. März bis zum 9. März 2024
## Advanced Usage
By specifying `default_start_time` and `default_end_time` arguments, the
daterange boundaries will snap to the given times when they otherwise would be
"beginning of day" (00:00) or "end of day" (23:59).
```python
import datetime as dt
from aika import TimeIntervalParser
dr = TimeIntervalParser(
snap_days=True,
default_start_time=dt.time(hour=9),
default_end_time=dt.time(hour=17),
)
dr.parse("Sat - Tue")
```
```python
(datetime(2023, 8, 26, 9, 0), datetime(2023, 8, 29, 17, 0))
```
## Troubleshooting
If you see an error message like `locale.Error: unsupported locale setting` for
code like this,
```python
import locale
locale.setlocale(locale.LC_ALL, "de_DE.UTF-8")
```
you will need to generate the German locales.
```shell
apt-get update
apt-get install --yes tzdata locales
locale-gen de_DE.UTF-8
```
## Development
Acquire source code and install development sandbox.
```shell
git clone https://github.com/panodata/aika
cd aika
uv venv --seed --python 3.11
source .venv/bin/activate
uv pip install --editable='.[develop,docs,test]'
```
Run linters and software tests:
```shell
source .venv/bin/activate
poe check
```
## Etymology
Aika means "time" in the Finnish language.
## Acknowledgements
- [Elias Dorneles] and contributors for conceiving and maintaining [dateparser].
- [Michael Phelps] for conceiving [arbitrary-dateparser].
- [Robin Wilson] and contributors for conceiving and maintaining [DateRangeParser].
[arbitrary-dateparser]: https://pypi.org/project/arbitrary-dateparser/
[dateparser]: https://pypi.org/project/dateparser/
[DateRangeParser]: https://pypi.org/project/DateRangeParser/
[DWIM]: https://en.wikipedia.org/wiki/DWIM
[Elias Dorneles]: https://github.com/eliasdorneles
[Michael Phelps]: https://github.com/nottheswimmer
[Robin Wilson]: https://github.com/robintw
Raw data
{
"_id": null,
"home_page": null,
"name": "aika",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "date parsing, multi-language, time, time interval, time range, utility",
"author": null,
"author_email": "Andreas Motl <andreas.motl@panodata.org>, Richard Pobering <richard.pobering@panodata.org>",
"download_url": "https://files.pythonhosted.org/packages/8d/f7/f174b9337c75eaa16ba0488ad8277a76c4f26724d541da65b55e384a5ecf/aika-0.2.1.tar.gz",
"platform": null,
"description": "# Aika\n\nTime interval parsing utilities for multiple languages.\n\n## About\n\nAika provides date- and time-range parsing utilities for multiple languages.\nIt is based on [dateparser], [arbitrary-dateparser], and [DateRangeParser],\nand aims for [DWIM]-like convenience and usefulness.\n\nCurrently, it supports 200 language locales through `dateparser`, and more\nspecific support for English and German through `arbitrary-dateparser`.\nContributions for other languages are welcome.\n\n\n## Setup\n\nInstall the most recent version of Aika.\n```shell\npip install --upgrade aika\n```\n\n\n## Usage\n\n```doctest\n>>> import datetime as dt\n>>> from aika import TimeIntervalParser\n>>> \n>>> ti = TimeIntervalParser()\n>>>\n>>> ti.parse(\"Sat - Tue\")\n>>> (dt.datetime(2023, 8, 26, 0, 0), dt.datetime(2023, 8, 29, 23, 59, 59, 999999))\n>>>\n>>> ti.parse_single(\"1. Juli\")\n>>> dt.datetime(2023, 7, 1, 0, 0)\n```\n\n\n### Example Expressions\n\nAika understands all types of date-/time-range expressions like provided by the\npackages it is based upon, and works with single dates too. This section enumerates\na few examples.\n\n#### dateparser\n\n##### Calendar notations\n- Week: 2025W01\n- Month: 2025M02, 2025-02\n- Quarter: 2025Q03\n- Year: 2025\n\n##### Time deltas\n- Day: `-1d`, `-1 day`\n- Week: `-1w`, `-1 week`\n- Month: `-1M`, `-1 month`\n- Year: `-1y`, `-1 year`\n- Quarter: `-3M`, `-3 months`\n- Mixed: `-3d3h5m30s`\n\n#### arbitrary-dateparser \u00bb English\n\n- now\n- today\n- last week to next friday\n- tomorrow - next week\n- next month\n- december\n- July to December\n- jul 1 to jul 7\n- Sat - Tue\n- in March\n- 2024-08-20\n\n#### arbitrary-dateparser \u00bb German\n\n- jetzt\n- heute\n- letzte woche bis n\u00e4chsten freitag\n- morgen - n\u00e4chste woche\n- n\u00e4chster monat\n- dezember\n- Juli-Dezember\n- jul 1 to jul 7\n- von Samstag bis Dienstag\n- im M\u00e4rz\n- 20\\. August 2024\n- 20.8.2024\n- 20.08.2024\n\n#### DateRangeParser \u00bb English\n\n- 1st july\n- March 2024\n- July to December\n- 27th-29th June 2010\n- 30 May to 9th Aug\n- 3rd Jan 1980 -- 2nd Jan 2013\n- Wed 23 Jan -> Sat 16 February 2013\n- Tuesday 29 May - Sat 2 June 2012\n- From 1 to 9 Jul\n- jul 1 to jul 9\n- 14th July 1988\n- Jan 2011 - Mar 2014 \n- 07:00 Tue 7th June - 17th July 3:30pm\n <br>**Caveat**: Times will currently be ignored.\n\n#### DateRangeParser \u00bb German\n\n- 1\\. Juli\n- 1\\. bis 7. Juli\n- M\u00e4rz 2024\n- Juli bis Dezember\n- Vom 3. M\u00e4rz bis zum 9. M\u00e4rz 2024\n\n\n## Advanced Usage\n\nBy specifying `default_start_time` and `default_end_time` arguments, the\ndaterange boundaries will snap to the given times when they otherwise would be\n\"beginning of day\" (00:00) or \"end of day\" (23:59).\n\n```python\nimport datetime as dt\nfrom aika import TimeIntervalParser\n\ndr = TimeIntervalParser(\n snap_days=True,\n default_start_time=dt.time(hour=9),\n default_end_time=dt.time(hour=17),\n)\ndr.parse(\"Sat - Tue\")\n```\n```python\n(datetime(2023, 8, 26, 9, 0), datetime(2023, 8, 29, 17, 0))\n```\n\n\n## Troubleshooting\n\nIf you see an error message like `locale.Error: unsupported locale setting` for\ncode like this,\n```python\nimport locale\n\nlocale.setlocale(locale.LC_ALL, \"de_DE.UTF-8\")\n```\n\nyou will need to generate the German locales.\n```shell\napt-get update\napt-get install --yes tzdata locales\nlocale-gen de_DE.UTF-8\n```\n\n\n## Development\n\nAcquire source code and install development sandbox.\n```shell\ngit clone https://github.com/panodata/aika\ncd aika\nuv venv --seed --python 3.11\nsource .venv/bin/activate\nuv pip install --editable='.[develop,docs,test]'\n```\n\nRun linters and software tests:\n```shell\nsource .venv/bin/activate\npoe check\n```\n\n\n## Etymology\n\nAika means \"time\" in the Finnish language.\n\n## Acknowledgements\n\n- [Elias Dorneles] and contributors for conceiving and maintaining [dateparser].\n- [Michael Phelps] for conceiving [arbitrary-dateparser].\n- [Robin Wilson] and contributors for conceiving and maintaining [DateRangeParser].\n\n\n[arbitrary-dateparser]: https://pypi.org/project/arbitrary-dateparser/\n[dateparser]: https://pypi.org/project/dateparser/\n[DateRangeParser]: https://pypi.org/project/DateRangeParser/\n[DWIM]: https://en.wikipedia.org/wiki/DWIM\n[Elias Dorneles]: https://github.com/eliasdorneles\n[Michael Phelps]: https://github.com/nottheswimmer\n[Robin Wilson]: https://github.com/robintw\n",
"bugtrack_url": null,
"license": "LGPL 3, EUPL 1.2",
"summary": "Time interval parsing utilities for multiple languages.",
"version": "0.2.1",
"project_urls": {
"Changelog": "https://github.com/panodata/aika/blob/main/CHANGES.md",
"Issues": "https://github.com/panodata/aika/issues",
"Repository": "https://github.com/panodata/aika"
},
"split_keywords": [
"date parsing",
" multi-language",
" time",
" time interval",
" time range",
" utility"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "faa506de47d40d6b1e9645c5011f0e449e48950a1e5700d8af575f89afe57afd",
"md5": "57cc9f519529ba1de47ee854b1a8f0e5",
"sha256": "510840f5454de4a2c836240048ffe4b317665f5d011299598650695e097f00d7"
},
"downloads": -1,
"filename": "aika-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "57cc9f519529ba1de47ee854b1a8f0e5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19727,
"upload_time": "2025-02-24T08:37:50",
"upload_time_iso_8601": "2025-02-24T08:37:50.703334Z",
"url": "https://files.pythonhosted.org/packages/fa/a5/06de47d40d6b1e9645c5011f0e449e48950a1e5700d8af575f89afe57afd/aika-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8df7f174b9337c75eaa16ba0488ad8277a76c4f26724d541da65b55e384a5ecf",
"md5": "fb48fac7a3bad75a9e036752c2220588",
"sha256": "8ef6387a2135050032954d6a8243cade748649a540cadc3059ab4dbb4c6bbab1"
},
"downloads": -1,
"filename": "aika-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "fb48fac7a3bad75a9e036752c2220588",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22308,
"upload_time": "2025-02-24T08:37:52",
"upload_time_iso_8601": "2025-02-24T08:37:52.682944Z",
"url": "https://files.pythonhosted.org/packages/8d/f7/f174b9337c75eaa16ba0488ad8277a76c4f26724d541da65b55e384a5ecf/aika-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-24 08:37:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "panodata",
"github_project": "aika",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aika"
}
JSON
