Metadata-Version: 2.1
Name: esdateutil
Version: 0.1.0
Summary: ES datemath and date formatting utilities
Author-email: Matthew Murr <matt@murr.dev>
License: Copyright (c) 2024 Matthew Murr
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://git.sr.ht/~murr/esdateutil
Project-URL: Repository, https://git.sr.ht/~murr/esdateutil
Project-URL: Documentation, https://git.sr.ht/~murr/esdateutil/tree/master/item/README.md
Keywords: elasticsearch,elastic,es,datemath,parser,date,format
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# esdateutil

Provides utilities for handling dates like how Elasticsearch does.

In particular:
 - Datemath parsing and evaluation
 - ES-like datetime string format parsing

The goals of this project are:
 - Be as close to Elasticsearch behaviour as Python makes sensible.
 - No runtime dependencies.
 - Customizability; most functionality should be parameterizable.

This project will be version 1.0 when it provides:
 - Full datemath parsing
 - ES & java-style date string format parsing (https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-date-format.html)
 - Robust tests for weird stuff like datemath rounding on DST boundaries

## Building

Requires pyenv and pyenv-virtualenv to be installed on your machine.
Requires pyenv-init (pyenv and pyenv-virtualenv) to be run for pyenv local to work w/ virtualenv

## Hitchhiker's Guide to Python Datetimes

One of the consequences of using Python's built-in datetime objects and
functions by default is that they can behave very differently from version to
version and from Elasticsearch defaults. Below are some of the most important
differences in functionality to be aware of.

 - The default date parsing format in Elasticsearch is
   [strict_date_optional_time||epoch_millis](https://www.elastic.co/guide/en/elasticsearch/reference/current/date.html).
   The default parse function of DateMath in this library is
   datetime.datetime.fromisoformat, but it can be customized with
   `DateMath(date_fn=custom_date_parsing_function)`. The dateformat module
   approximates the ES functionality, but is not correct yet. If you are
   parsing datemath strings containing absolute datetime values, this means:
   - By default, ES supports millisecond epochs as a datetime format, by default we do not.
   - datetime.datetime.fromisoformat only [parses from ISO format properly in 3.11+](https://docs.python.org/3/library/datetime.html#datetime.datetime.fromisoformat).
     It is recommended to use a different date_fn if you are using a version
     below 3.11, such as python-dateutil's
     [parser.parse](https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.parse) and [parser.isoparse](https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse) or the [iso8601](https://pypi.org/project/iso8601/) library.
   - ES strict_date_optional_time allows 2024 or 2024-08 as dates, but Python's
     fromisoformat does not even in 3.11+. python-dateutil
     [parser.isoparse](https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse)
     and [iso8601](https://pypi.org/project/iso8601/) support this, or you can
     set a custom date_fn using the dateformat module of this library or the
     built-in strptime if you need this functionality.
 - The default time resolution in Elasticsearch is milliseconds, whereas in
   Python datetime it is microseconds. This shouldn't be important unless you
   are using the optional UNITS_ROUND_UP or another custom round
   implementation. UNITS_ROUND_UP_MILLIS is provided as an alternative.
