# Python Datemath
## What?
A date math (aka datemath) parser compatiable with the elasticsearch "date math" format
## What is "date math"?
Date Math is the short hand arithmetic to find relative time to fixed moments in date and time. Similar to the SOLR date math format, we aim to support that same coverage in python.
> The date type supports using date math expression when using it in a query/filter (mainly makes sense in range query/filter).
>
> The expression starts with an "anchor" date, which can be either now or a date string (in the applicable format) ending with `||`.
>
> It can then follow by a math expression, supporting `+`, `-` and `/` (rounding).
>
> The units supported are `y` (year), `M` (month), `w` (week), `d` (day), `h` (hour), `m` (minute), and `s` (second).
>
> Here are some samples: `now+1h`, `now+1h+1m`, `now+1h/d`, `2012-01-01||+1M/d`.
>
> Note, when doing range type searches, and the upper value is inclusive, the rounding will properly be rounded to the ceiling instead of flooring it.
### Unit Maps
The "unit maps" here define the shorthand sytax for the dates/timeframes we are working with:
```yaml
y or Y = 'year'
M = 'month'
m = 'minute'
d or D = 'day'
w = 'week'
h or H = 'hour'
s or S = 'second'
now = <current_time_and_date>
```
### Examples
Here are some examples of using date math to find dates both in the past and in the future
Assuming our "now" datetime is currently: `2016-01-01T00:00:00-00:00`
```yaml
Expression: Result:
now-1h 2015-12-31T23:00:00+00:00
now-1y 2015-01-01T00:00:00+00:00
now+1y+2d 2017-01-03T00:00:00+00:00
now+12h 2016-01-01T12:00:00+00:00
now+1d/d 2016-01-03T00:00:00+00:00
now-2.5h 2015-12-31T21:30:00+00:00
+2h 2016-01-01T02:00:00+00:00
+1h/h 2016-01-01T02:00:00+00:00
now+1w/w 2016-01-11T00:00:00+00:00
now/d+7d+12h 2016-01-08T12:00:00+00:00
2016-01-01||+1d 2016-01-02T00:00:00+00:00
2015-01-01||+2w 2015-01-15T00:00:00+00:00
# Using the roundDown=False option
now/d 2016-01-01T23:59:59+00:00
now/Y 2016-12-31T23:59:59+00:00
```
## Usage
If you use the `dm` function in the datemath module, we will return an arrow date object representing your timestamp.
```python
>>> from datemath import dm
>>>
>>> dm('now+1h')
<Arrow [2016-01-01T01:00:00+00:00]>
>>> dm('now+1h+1m')
<Arrow [2016-01-01T01:01:00+00:00]>
>>> dm('now+1h/d')
<Arrow [2016-01-02T00:00:00+00:00]>
>>> dm('now-1d')
<Arrow [2015-12-31T00:00:00+00:00]>
>>> dm('2016-01-01||+1/d')
<Arrow [2016-01-02T00:00:00+00:00]>
>>> dm('now/d+2h+3m')
<Arrow [2016-01-01T02:03:00+00:00]>
>>> dm('now+/d', roundDown=False)
<Arrow [2016-01-01T23:59:00+00:00]>
>>> dm('now/d')
<Arrow [2016-01-01T00:00:00+00:00]>
>>> dm(1451610061) # Timestamp in epoch/unix as int (Please note, we do not support epoch millisecond at this time. Please convert your epoch millis to the nearest second. i.e. 1451610061000/1000)
<Arrow [2016-01-01T01:01:01+00:00]>
>>> dm('1451610061') # Timestamp in epoch/unix as string
<Arrow [2016-01-01T01:01:01+00:00]>
```
If you would rather have a string, you can use arrow's ```.format()``` method.
> For for info on string formatting, check out arrows tokens section: http://crsmithdev.com/arrow/#tokens
```python
>>> from datemath import dm
>>>
>>> src_timestamp = dm('2016-01-01')
>>> print src_timestamp
2016-01-01T00:00:00+00:00
>>>
>>> new_timestamp = dm('-2w', now=src_timestamp)
>>> print new_timestamp
2015-12-18T00:00:00+00:00
>>>
>>> new_timestamp.format('YYYY.MM.DD')
u'2015.12.18'
```
If you would rather have your time object come back in standard python `datetime`, use the `datemath` function instead:
```python
>>> from datemath import datemath
>>> ## Assuming "now" is 2016-01-01T00:00:00
>>> datemath("now-1h")
datetime.datetime(2015, 12, 31, 23, 0, tzinfo=tzutc())
# Cast it as a str() get a string of the timestamp back too
>>> str(datemath("now-1h"))
'2015-12-31 23:00:00+00:00'
>>> # roundDown=True is default and implied
>>> datemath('2016-01-01T16:20:00||/d')
datetime.datetime(2016, 1, 1, 0, 0, tzinfo=tzutc())
>>> # Using the roundDown option
>>> datemath('2016-01-01T16:20:00||/d', roundDown=False)
datetime.datetime(2016, 1, 1, 23, 59, 59, 999999, tzinfo=tzutc())
```
Or you can use the `dm` function and set its `type` to `datetime`:
```python
from datemath import dm
>>> dm('now', type='datetime')
datetime.datetime(2016, 1, 22, 22, 58, 28, 338060, tzinfo=tzutc())
>>>
>>> dm('now+2d-1m', type='datetime')
datetime.datetime(2016, 1, 24, 22, 57, 45, 394470, tzinfo=tzutc())
```
If you want a Epoch timestamp back instead, we can do that too.
```python
>>> dm('now+2d-1m', type='timestamp')
1453676321
```
## What timezone are my objects in?
By default all objects returned by datemath are in UTC.
If you want them them back in a different timezone, just pass along the ```tz``` argument. Timezone list can be found here: [https://gist.github.com/pamelafox/986163](https://gist.github.com/pamelafox/986163)
If you provide a timezone offset in your timestring, datemath will return your time object as that timezone offset in the string.
Note - currently timestrings with a timezone offset and the usage of the ```tz``` argument will result in the time object being returned with the timezone of what was in the timezone offset in the original string
```python
>>> from datemath import dm
>>>
>>> dm('now')
<Arrow [2016-01-26T01:00:53.601088+00:00]>
>>>
>>> dm('now', tz='US/Eastern')
<Arrow [2016-01-25T20:01:05.976880-05:00]>
>>>
>>> dm('now', tz='US/Pacific')
<Arrow [2016-01-25T17:01:18.456882-08:00]>
>>>
>>> dm('2017-10-20 09:15:20', tz='US/Pacific')
<Arrow [2017-10-20T09:15:20.000000-08:00]>
>>>
>>> # Timestring with TZ offset in the string (ISO8601 format only)
>>> dm('2016-01-01T00:00:00-05:00')
<Arrow [2016-01-01T00:00:00-05:00]>
>>>
>>> # Timestring with TZ offset with datemath added (again, TS must be in ISO8601)
>>> dm('2016-01-01T00:00:00-05:00||+2d+3h+5m')
<Arrow [2016-01-03T03:05:00-05:00]>
>>>
>>> # Note, timestrings with TZ offsets will be returned as the timezone of the offset in the string even if the "tz" option is used.
>>> dm('2016-01-01T00:00:00-05:00', tz='US/Central')
<Arrow [2016-01-01T00:00:00-05:00]>
```
## Install
```python
pip install python-datemath
```
## Debugging
If you would like more verbose output to debug the process of what datemath is doing, simply set `export DATEMATH_DEBUG=true` in your shell then run some datemath tests. To stop debugging, run `unset DATEMATH_DEBUG`.
## Changes
See CHANGELOG.md
# Happy date math'ing!
Raw data
{
"_id": null,
"home_page": "https://github.com/nickmaccarthy/python-datemath",
"name": "python-datemath",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "date math datemath elaticsearch solr",
"author": "Nick MacCarthy",
"author_email": "nickmaccarthy@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/40/06/24934ae306aeb96a5872612483e48aaa807a6041a2cfe5cd6a44a14d8516/python-datemath-3.0.2.tar.gz",
"platform": null,
"description": "# Python Datemath\n\n## What?\n\nA date math (aka datemath) parser compatiable with the elasticsearch \"date math\" format\n\n## What is \"date math\"?\n\nDate Math is the short hand arithmetic to find relative time to fixed moments in date and time. Similar to the SOLR date math format, we aim to support that same coverage in python.\n\n> The date type supports using date math expression when using it in a query/filter (mainly makes sense in range query/filter).\n>\n> The expression starts with an \"anchor\" date, which can be either now or a date string (in the applicable format) ending with `||`.\n>\n> It can then follow by a math expression, supporting `+`, `-` and `/` (rounding).\n>\n> The units supported are `y` (year), `M` (month), `w` (week), `d` (day), `h` (hour), `m` (minute), and `s` (second).\n>\n> Here are some samples: `now+1h`, `now+1h+1m`, `now+1h/d`, `2012-01-01||+1M/d`.\n>\n> Note, when doing range type searches, and the upper value is inclusive, the rounding will properly be rounded to the ceiling instead of flooring it.\n\n### Unit Maps\n\nThe \"unit maps\" here define the shorthand sytax for the dates/timeframes we are working with:\n```yaml\ny or Y = 'year'\nM = 'month'\nm = 'minute'\nd or D = 'day'\nw = 'week'\nh or H = 'hour'\ns or S = 'second'\nnow = <current_time_and_date>\n```\n\n### Examples\n\nHere are some examples of using date math to find dates both in the past and in the future\n\nAssuming our \"now\" datetime is currently: `2016-01-01T00:00:00-00:00`\n\n```yaml\nExpression: Result:\nnow-1h 2015-12-31T23:00:00+00:00\nnow-1y 2015-01-01T00:00:00+00:00\nnow+1y+2d 2017-01-03T00:00:00+00:00\nnow+12h 2016-01-01T12:00:00+00:00\nnow+1d/d 2016-01-03T00:00:00+00:00\nnow-2.5h 2015-12-31T21:30:00+00:00\n+2h 2016-01-01T02:00:00+00:00\n+1h/h 2016-01-01T02:00:00+00:00\nnow+1w/w 2016-01-11T00:00:00+00:00\nnow/d+7d+12h 2016-01-08T12:00:00+00:00\n2016-01-01||+1d 2016-01-02T00:00:00+00:00\n2015-01-01||+2w 2015-01-15T00:00:00+00:00\n\n# Using the roundDown=False option\nnow/d 2016-01-01T23:59:59+00:00\nnow/Y 2016-12-31T23:59:59+00:00\n```\n\n## Usage\n\nIf you use the `dm` function in the datemath module, we will return an arrow date object representing your timestamp. \n\n```python\n>>> from datemath import dm\n>>>\n>>> dm('now+1h')\n<Arrow [2016-01-01T01:00:00+00:00]>\n>>> dm('now+1h+1m')\n<Arrow [2016-01-01T01:01:00+00:00]>\n>>> dm('now+1h/d')\n<Arrow [2016-01-02T00:00:00+00:00]>\n>>> dm('now-1d')\n<Arrow [2015-12-31T00:00:00+00:00]>\n>>> dm('2016-01-01||+1/d')\n<Arrow [2016-01-02T00:00:00+00:00]>\n>>> dm('now/d+2h+3m')\n<Arrow [2016-01-01T02:03:00+00:00]>\n>>> dm('now+/d', roundDown=False)\n<Arrow [2016-01-01T23:59:00+00:00]>\n>>> dm('now/d')\n<Arrow [2016-01-01T00:00:00+00:00]>\n>>> dm(1451610061) # Timestamp in epoch/unix as int (Please note, we do not support epoch millisecond at this time. Please convert your epoch millis to the nearest second. i.e. 1451610061000/1000)\n<Arrow [2016-01-01T01:01:01+00:00]>\n>>> dm('1451610061') # Timestamp in epoch/unix as string\n<Arrow [2016-01-01T01:01:01+00:00]>\n```\n\nIf you would rather have a string, you can use arrow's ```.format()``` method.\n> For for info on string formatting, check out arrows tokens section: http://crsmithdev.com/arrow/#tokens\n\n```python\n>>> from datemath import dm\n>>>\n>>> src_timestamp = dm('2016-01-01')\n>>> print src_timestamp\n2016-01-01T00:00:00+00:00\n>>>\n>>> new_timestamp = dm('-2w', now=src_timestamp)\n>>> print new_timestamp\n2015-12-18T00:00:00+00:00\n>>>\n>>> new_timestamp.format('YYYY.MM.DD')\nu'2015.12.18'\n```\n\nIf you would rather have your time object come back in standard python `datetime`, use the `datemath` function instead:\n\n```python\n>>> from datemath import datemath\n>>> ## Assuming \"now\" is 2016-01-01T00:00:00\n>>> datemath(\"now-1h\")\ndatetime.datetime(2015, 12, 31, 23, 0, tzinfo=tzutc())\n# Cast it as a str() get a string of the timestamp back too\n>>> str(datemath(\"now-1h\"))\n'2015-12-31 23:00:00+00:00'\n>>> # roundDown=True is default and implied\n>>> datemath('2016-01-01T16:20:00||/d')\ndatetime.datetime(2016, 1, 1, 0, 0, tzinfo=tzutc())\n>>> # Using the roundDown option\n>>> datemath('2016-01-01T16:20:00||/d', roundDown=False)\ndatetime.datetime(2016, 1, 1, 23, 59, 59, 999999, tzinfo=tzutc())\n```\n\nOr you can use the `dm` function and set its `type` to `datetime`:\n```python\nfrom datemath import dm\n>>> dm('now', type='datetime')\ndatetime.datetime(2016, 1, 22, 22, 58, 28, 338060, tzinfo=tzutc())\n>>>\n>>> dm('now+2d-1m', type='datetime')\ndatetime.datetime(2016, 1, 24, 22, 57, 45, 394470, tzinfo=tzutc())\n```\n\nIf you want a Epoch timestamp back instead, we can do that too. \n\n```python\n>>> dm('now+2d-1m', type='timestamp')\n1453676321\n```\n\n## What timezone are my objects in?\n\nBy default all objects returned by datemath are in UTC. \n\nIf you want them them back in a different timezone, just pass along the ```tz``` argument. Timezone list can be found here: [https://gist.github.com/pamelafox/986163](https://gist.github.com/pamelafox/986163)\n\nIf you provide a timezone offset in your timestring, datemath will return your time object as that timezone offset in the string.\n\nNote - currently timestrings with a timezone offset and the usage of the ```tz``` argument will result in the time object being returned with the timezone of what was in the timezone offset in the original string\n\n```python\n>>> from datemath import dm \n>>>\n>>> dm('now')\n<Arrow [2016-01-26T01:00:53.601088+00:00]>\n>>>\n>>> dm('now', tz='US/Eastern')\n<Arrow [2016-01-25T20:01:05.976880-05:00]>\n>>>\n>>> dm('now', tz='US/Pacific')\n<Arrow [2016-01-25T17:01:18.456882-08:00]>\n>>>\n>>> dm('2017-10-20 09:15:20', tz='US/Pacific')\n<Arrow [2017-10-20T09:15:20.000000-08:00]>\n>>> \n>>> # Timestring with TZ offset in the string (ISO8601 format only)\n>>> dm('2016-01-01T00:00:00-05:00')\n<Arrow [2016-01-01T00:00:00-05:00]>\n>>>\n>>> # Timestring with TZ offset with datemath added (again, TS must be in ISO8601)\n>>> dm('2016-01-01T00:00:00-05:00||+2d+3h+5m')\n<Arrow [2016-01-03T03:05:00-05:00]>\n>>>\n>>> # Note, timestrings with TZ offsets will be returned as the timezone of the offset in the string even if the \"tz\" option is used. \n>>> dm('2016-01-01T00:00:00-05:00', tz='US/Central')\n<Arrow [2016-01-01T00:00:00-05:00]>\n```\n\n## Install\n\n```python\npip install python-datemath\n```\n\n## Debugging\n\nIf you would like more verbose output to debug the process of what datemath is doing, simply set `export DATEMATH_DEBUG=true` in your shell then run some datemath tests. To stop debugging, run `unset DATEMATH_DEBUG`.\n\n## Changes\n\nSee CHANGELOG.md\n\n# Happy date math'ing!\n\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "\"A python module to emulate the date math used in SOLR and Elasticsearch\"",
"version": "3.0.2",
"project_urls": {
"Download": "https://github.com/nickmaccarthy/python-datemath/tarball/3.0.2",
"Homepage": "https://github.com/nickmaccarthy/python-datemath"
},
"split_keywords": [
"date",
"math",
"datemath",
"elaticsearch",
"solr"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cbfbd847ad09154fcce776870d0a76174c04ee4bf7a6750fc6bd2fb66bc04752",
"md5": "bb895c36983912fc9af67b7926df93dc",
"sha256": "90847118b727a37d2189ff1c125f0998f0e9fa7efc316258d6f6f32ba408f9ab"
},
"downloads": -1,
"filename": "python_datemath-3.0.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb895c36983912fc9af67b7926df93dc",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 12147,
"upload_time": "2024-09-11T18:56:24",
"upload_time_iso_8601": "2024-09-11T18:56:24.507474Z",
"url": "https://files.pythonhosted.org/packages/cb/fb/d847ad09154fcce776870d0a76174c04ee4bf7a6750fc6bd2fb66bc04752/python_datemath-3.0.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "400624934ae306aeb96a5872612483e48aaa807a6041a2cfe5cd6a44a14d8516",
"md5": "95260da61f343b6ed12e67c1b9341aad",
"sha256": "fcc158958611817beca99f506cfa22b82e5f01384cb53e783d1c55b58ba592fe"
},
"downloads": -1,
"filename": "python-datemath-3.0.2.tar.gz",
"has_sig": false,
"md5_digest": "95260da61f343b6ed12e67c1b9341aad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16180,
"upload_time": "2024-09-11T18:56:25",
"upload_time_iso_8601": "2024-09-11T18:56:25.956568Z",
"url": "https://files.pythonhosted.org/packages/40/06/24934ae306aeb96a5872612483e48aaa807a6041a2cfe5cd6a44a14d8516/python-datemath-3.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-11 18:56:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nickmaccarthy",
"github_project": "python-datemath",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "python-datemath"
}
JSON
