Metadata-Version: 2.1
Name: datetime-matcher
Version: 0.1.3
Summary: A library which extends regex with support for datetime format codes.
Home-page: https://github.com/stephen-zhao/datetime_matcher
Author: Stephen Zhao
Author-email: mail@zhaostephen.com
License: UNKNOWN
Description: # date-matcher
        
        A python module that works with an extension of regex which allows formatted
        datetime strings using python/C-style strftime format codes, hereby dubbed 
        "dfregex" (read datetime format regex).
        
        Most notably, the library includes a function which can substitute a given text
        matching a given search dfregex with a replacement string, allowing
        **both _datetime format substitutions_ and backslash-number substitutions**.
        See an example in the section below.
        
        ## Install
        
        Get it from pypi now by running.
        
        ```sh
        pip install datetime-matcher
        ```
        
        ## Substitution Example
        
        Given the following as search pattern:
        
        ```python3
        search_dfregex = r'(\w+)\%.+_(%Y-%b-%d)\.jpe?g'
        ```
        
        > Note: The percentage literal in conventional regex (`%`) must be escaped in dfregex (`\%`)
        because an unescaped one marks the beginning of a datetime format code and otherwise would be
        ambiguous.
        
        If we use this piece of text:
        
        ```python3
        text = 'MyLovelyPicture%38E7F8AEA5_2020-Mar-10.jpeg'
        ```
        
        And the following replacement formatter:
        
        ```python3
        replacement = r'%Y%m%d-\1.jpg'
        ```
        
        Then we can run the following substitution:
        
        ```python3
        from datetime_matcher import DatetimeMatcher
        
        dtmatcher = DatetimeMatcher()
        result = dtmatcher.sub(search_dfregex, replacement, text)
        
        # result == '20200310-MyLovelyPicture.jpg'
        ```
        
        ## Features
        
        The library features a class `DatetimeMatcher` which provides the following
        public-facing methods:
        
        ### `sub`
        
        ```python3
        def sub(self, search_dfregex: str, replacement_dfregex: str, text: str) -> str
        ```
        
        - Replace the first matching instance of the search dfregex in the
          given text with the replacement dfregex, intelligently transferring
          the first matching date from the original text to the replaced text.
        - Use strftime codes within a dfregex string to extract/place datetimes.
        - Example: as demonstrated in the section above.
        
        ### `match`
        
        ```python3
        def match(self, search_dfregex: str, text: str) -> Optional[Match[AnyStr]]
        ```
        
        - Determine if the given text matches the search dfregex, and return
          the corresponding Match object if it exists.
        - Use strftime codes within a dfregex string to extract/place datetimes.
        
        ### `get_regex_from_dfregex`
        
        ```python3
        def get_regex_from_dfregex(self, dfregex: str, is_capture_dfs: bool = False) -> str
        ```
        
        - Converts a dfregex to its corresponding conventional regex.
        - By default, the datetime format groups are NOT captured.
        - Use strftime codes within a dfregex string to match datetimes.
        
        ### `extract_datetime`
        
        ```python3
        def extract_datetime(self, dfregex: str, text: str) -> Optional[datetime]
        ```
        
        - Extracts a datetime object from text given a dfregex string.
        - Use strftime codes within a dfregex string to match datetimes.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
