Metadata-Version: 2.1
Name: ovos-date-parser
Version: 0.0.2a1
Summary: OpenVoiceOS's multilingual text parsing and formatting library
Home-page: https://github.com/OpenVoiceOS/ovos-date-parser
Author: Mycroft AI / OVOS
Author-email: jarbasai@mailfence.com
License: Apache2.0
Description: # 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
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Text Processing :: Linguistic
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Obsoletes: ovos_date_parser
Description-Content-Type: text/markdown
