# ovos-date-parser
`ovos-date-parser` is a comprehensive library for multilingual date and time parsing, extraction, and formatting,
designed to handle a range of human-readable date, time, and duration expressions.
## Features
- **Date and Time Extraction**: Extract specific dates and times from natural language phrases in various languages.
- **Duration Parsing**: Parse phrases that indicate a span of time, such as "two hours and fifteen minutes."
- **Friendly Time Formatting**: Format time for human-friendly output, supporting both 12-hour and 24-hour formats.
- **Relative Time Descriptions**: Generate relative descriptions (e.g., "tomorrow," "in three days") for given dates.
- **Multilingual Support**: Includes extraction and formatting methods for multiple languages, such as English, Spanish,
French, German, and more.
## Installation
```bash
pip install ovos-date-parser
```
## Usage
### Date and Time Extraction
Extract specific dates and times from a phrase. This function identifies date-related terms in natural language and
returns both the datetime object and any remaining text.
```python
from ovos_date_parser import extract_datetime
result = extract_datetime("Meet me next Friday at 3pm", lang="en")
print(result) # (datetime object, "at 3pm")
```
### Duration Extraction
Identify duration phrases in text and convert them into a `timedelta` object. This can parse common human-friendly
duration expressions like "30 minutes" or "two and a half hours."
```python
from ovos_date_parser import extract_duration
duration, remainder = extract_duration("It will take about 2 hours and 30 minutes", lang="en")
print(duration) # timedelta object
print(remainder) # "about"
```
### Formatting Time
Generate a natural-sounding time format suitable for voice or display in different languages, allowing customization for
speech or written text.
```python
from ovos_date_parser import nice_time
from datetime import datetime
dt = datetime.now()
formatted_time = nice_time(dt, lang="en", speech=True, use_24hour=False)
print(formatted_time) # "three o'clock"
```
### Relative Time Descriptions
Create relative phrases for describing dates and times in relation to the current moment or a reference datetime.
```python
from ovos_date_parser import nice_relative_time
from datetime import datetime, timedelta
relative_time = nice_relative_time(datetime.now() + timedelta(days=1), datetime.now(), lang="en")
print(relative_time) # "tomorrow"
```
### Languages Supported
`ovos-date-parser` supports a wide array of languages, each with its own set of methods for handling natural language
time expressions.
Parse
| Language | `extract_duration` | `extract_datetime` |
|----------|--------------------|--------------------|
| az | ✅ | ✅ |
| ca | ✅ | ✅ |
| cs | ✅ | ✅ |
| da | ❌ | ✅ |
| de | ✅ | ✅ |
| en | ✅ | ✅ |
| es | ✅ | ✅ |
| eu | ❌ | ✅ |
| fa | ✅ | ✅ |
| fr | ❌ | ✅ |
| hu | ❌ | ❌ |
| it | ❌ | ✅ |
| nl | ✅ | ✅ |
| pl | ✅ | ✅ |
| pt | ✅ | ✅ |
| ru | ✅ | ✅ |
| sv | ✅ | ✅ |
| uk | ✅ | ✅ |
Format
| Language | `nice_date`<br>`nice_date_time`<br>`nice_day` <br>`nice_weekday` <br>`nice_month` <br>`nice_year` <br>`get_date_strings` | `nice_time` | `nice_relative_time` | `nice_duration` |
|----------|--------------------------------------------------------------------------------------------------------------------------|-------------|----------------------|-----------------|
| az | ✅ | ✅ | ✅ | ✅ |
| ca | ✅ | ✅ | ✅ | ✅ |
| cs | ✅ | ✅ | ✅ | ✅ |
| da | ✅ | ✅ | ✅ | ✅ |
| de | ✅ | ✅ | ✅ | ✅ |
| en | ✅ | ✅ | ✅ | ✅ |
| es | ✅ | ✅ | ✅ | ✅ |
| eu | ✅ | ✅ | ✅ | ✅ |
| fa | ✅ | ✅ | ✅ | ✅ |
| fr | ✅ | ✅ | ✅ | ✅ |
| hu | ✅ | ✅ | ✅ | ✅ |
| it | ✅ | ✅ | ✅ | ✅ |
| nl | ✅ | ✅ | ✅ | ✅ |
| pl | ✅ | ✅ | ✅ | ✅ |
| pt | ✅ | ✅ | ✅ | ✅ |
| ru | ✅ | ✅ | ✅ | ✅ |
| sv | ✅ | ✅ | ✅ | ✅ |
| sl | ✅ | ❌ | ✅ | ✅ |
| uk | ✅ | ✅ | ✅ | ✅ |
## Related Projects
- [ovos-number-parser](https://github.com/OpenVoiceOS/ovos-number-parser) - for handling numbers
- [ovos-lang-parser](https://github.com/OVOSHatchery/ovos-lang-parser) - for handling languages
- [ovos-color-parser](https://github.com/OVOSHatchery/ovos-color-parser) - for handling colors
## License
This project is licensed under the Apache 2.0 License
Raw data
{
"_id": null,
"home_page": "https://github.com/OpenVoiceOS/ovos-date-parser",
"name": "ovos-date-parser",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Mycroft AI / OVOS",
"author_email": "jarbasai@mailfence.com",
"download_url": "https://files.pythonhosted.org/packages/8d/a1/8453258e98e63c1c1101d55dd655206a13acaae132b2a0b892edbb08da14/ovos-date-parser-0.4.0.tar.gz",
"platform": null,
"description": "# ovos-date-parser\n\n`ovos-date-parser` is a comprehensive library for multilingual date and time parsing, extraction, and formatting,\ndesigned to handle a range of human-readable date, time, and duration expressions.\n\n## Features\n\n- **Date and Time Extraction**: Extract specific dates and times from natural language phrases in various languages.\n- **Duration Parsing**: Parse phrases that indicate a span of time, such as \"two hours and fifteen minutes.\"\n- **Friendly Time Formatting**: Format time for human-friendly output, supporting both 12-hour and 24-hour formats.\n- **Relative Time Descriptions**: Generate relative descriptions (e.g., \"tomorrow,\" \"in three days\") for given dates.\n- **Multilingual Support**: Includes extraction and formatting methods for multiple languages, such as English, Spanish,\n French, German, and more.\n\n## Installation\n\n```bash\npip install ovos-date-parser\n```\n\n## Usage\n\n### Date and Time Extraction\n\nExtract specific dates and times from a phrase. This function identifies date-related terms in natural language and\nreturns both the datetime object and any remaining text.\n\n```python\nfrom ovos_date_parser import extract_datetime\n\nresult = extract_datetime(\"Meet me next Friday at 3pm\", lang=\"en\")\nprint(result) # (datetime object, \"at 3pm\")\n```\n\n### Duration Extraction\n\nIdentify duration phrases in text and convert them into a `timedelta` object. This can parse common human-friendly\nduration expressions like \"30 minutes\" or \"two and a half hours.\"\n\n```python\nfrom ovos_date_parser import extract_duration\n\nduration, remainder = extract_duration(\"It will take about 2 hours and 30 minutes\", lang=\"en\")\nprint(duration) # timedelta object\nprint(remainder) # \"about\"\n```\n\n### Formatting Time\n\nGenerate a natural-sounding time format suitable for voice or display in different languages, allowing customization for\nspeech or written text.\n\n```python\nfrom ovos_date_parser import nice_time\nfrom datetime import datetime\n\ndt = datetime.now()\nformatted_time = nice_time(dt, lang=\"en\", speech=True, use_24hour=False)\nprint(formatted_time) # \"three o'clock\"\n```\n\n### Relative Time Descriptions\n\nCreate relative phrases for describing dates and times in relation to the current moment or a reference datetime.\n\n```python\nfrom ovos_date_parser import nice_relative_time\nfrom datetime import datetime, timedelta\n\nrelative_time = nice_relative_time(datetime.now() + timedelta(days=1), datetime.now(), lang=\"en\")\nprint(relative_time) # \"tomorrow\"\n```\n\n### Languages Supported\n\n`ovos-date-parser` supports a wide array of languages, each with its own set of methods for handling natural language\ntime expressions.\n\nParse\n\n| Language | `extract_duration` | `extract_datetime` |\n|----------|--------------------|--------------------|\n| az | \u2705 | \u2705 |\n| ca | \u2705 | \u2705 |\n| cs | \u2705 | \u2705 |\n| da | \u274c | \u2705 |\n| de | \u2705 | \u2705 |\n| en | \u2705 | \u2705 |\n| es | \u2705 | \u2705 |\n| eu | \u274c | \u2705 |\n| fa | \u2705 | \u2705 |\n| fr | \u274c | \u2705 |\n| hu | \u274c | \u274c |\n| it | \u274c | \u2705 |\n| nl | \u2705 | \u2705 |\n| pl | \u2705 | \u2705 |\n| pt | \u2705 | \u2705 |\n| ru | \u2705 | \u2705 |\n| sv | \u2705 | \u2705 |\n| uk | \u2705 | \u2705 |\n\nFormat\n\n| Language | `nice_date`<br>`nice_date_time`<br>`nice_day` <br>`nice_weekday` <br>`nice_month` <br>`nice_year` <br>`get_date_strings` | `nice_time` | `nice_relative_time` | `nice_duration` |\n|----------|--------------------------------------------------------------------------------------------------------------------------|-------------|----------------------|-----------------|\n| az | \u2705 | \u2705 | \u2705 | \u2705 | \n| ca | \u2705 | \u2705 | \u2705 | \u2705 | \n| cs | \u2705 | \u2705 | \u2705 | \u2705 | \n| da | \u2705 | \u2705 | \u2705 | \u2705 | \n| de | \u2705 | \u2705 | \u2705 | \u2705 | \n| en | \u2705 | \u2705 | \u2705 | \u2705 | \n| es | \u2705 | \u2705 | \u2705 | \u2705 | \n| eu | \u2705 | \u2705 | \u2705 | \u2705 | \n| fa | \u2705 | \u2705 | \u2705 | \u2705 | \n| fr | \u2705 | \u2705 | \u2705 | \u2705 | \n| hu | \u2705 | \u2705 | \u2705 | \u2705 | \n| it | \u2705 | \u2705 | \u2705 | \u2705 | \n| nl | \u2705 | \u2705 | \u2705 | \u2705 | \n| pl | \u2705 | \u2705 | \u2705 | \u2705 | \n| pt | \u2705 | \u2705 | \u2705 | \u2705 | \n| ru | \u2705 | \u2705 | \u2705 | \u2705 | \n| sv | \u2705 | \u2705 | \u2705 | \u2705 |\n| sl | \u2705 | \u274c | \u2705 | \u2705 |\n| uk | \u2705 | \u2705 | \u2705 | \u2705 | \n\n## Related Projects\n\n- [ovos-number-parser](https://github.com/OpenVoiceOS/ovos-number-parser) - for handling numbers\n- [ovos-lang-parser](https://github.com/OVOSHatchery/ovos-lang-parser) - for handling languages\n- [ovos-color-parser](https://github.com/OVOSHatchery/ovos-color-parser) - for handling colors\n\n## License\n\nThis project is licensed under the Apache 2.0 License\n\n",
"bugtrack_url": null,
"license": "Apache2.0",
"summary": "OpenVoiceOS's multilingual text parsing and formatting library",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/OpenVoiceOS/ovos-date-parser"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2fa4c2de0b995542d9a0ca1853ab689dd6776f6d30e1fcc9c1ade78b8bc02703",
"md5": "3bf03e68d76e7bec7d0de25d83c40679",
"sha256": "ce4ce8c9aca99cb2504c44f3fa60b261ddb33ac29ccc7e5e59700194bc8b67a9"
},
"downloads": -1,
"filename": "ovos_date_parser-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3bf03e68d76e7bec7d0de25d83c40679",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 174463,
"upload_time": "2024-11-15T21:08:33",
"upload_time_iso_8601": "2024-11-15T21:08:33.098003Z",
"url": "https://files.pythonhosted.org/packages/2f/a4/c2de0b995542d9a0ca1853ab689dd6776f6d30e1fcc9c1ade78b8bc02703/ovos_date_parser-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8da18453258e98e63c1c1101d55dd655206a13acaae132b2a0b892edbb08da14",
"md5": "b81844234d004cb757abcbc57ce4eb97",
"sha256": "88b60918f14dbe2555a2d53b7bf7722c71746e87baaab295527520dd4ae20d10"
},
"downloads": -1,
"filename": "ovos-date-parser-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "b81844234d004cb757abcbc57ce4eb97",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 122557,
"upload_time": "2024-11-15T21:08:35",
"upload_time_iso_8601": "2024-11-15T21:08:35.171024Z",
"url": "https://files.pythonhosted.org/packages/8d/a1/8453258e98e63c1c1101d55dd655206a13acaae132b2a0b892edbb08da14/ovos-date-parser-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 21:08:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OpenVoiceOS",
"github_project": "ovos-date-parser",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "python-dateutil",
"specs": [
[
"~=",
"2.6"
]
]
},
{
"name": "quebra_frases",
"specs": [
[
">=",
"0.3.7"
]
]
},
{
"name": "ovos-number-parser",
"specs": [
[
">=",
"0.0.2"
],
[
"<",
"1.0.0"
]
]
}
],
"lcname": "ovos-date-parser"
}
JSON
