ovos-date-parser


Nameovos-date-parser JSON
Version 0.4.0 PyPI version JSON
download
home_pagehttps://github.com/OpenVoiceOS/ovos-date-parser
SummaryOpenVoiceOS's multilingual text parsing and formatting library
upload_time2024-11-15 21:08:35
maintainerNone
docs_urlNone
authorMycroft AI / OVOS
requires_pythonNone
licenseApache2.0
keywords
VCS
bugtrack_url
requirements python-dateutil quebra_frases ovos-number-parser
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.38042s