Merge pull request #40 from nickmaccarthy/feat/python-3-type-hints

feat: many many fixes and additions

Author: nickmaccarthy

.github/workflows/tests.yaml

@@ -7,20 +7,19 @@ on:
     branches:
     - master
 jobs:
-  tests-python2:
-    runs-on: ubuntu-20.04
-    steps:
-      - uses: actions/checkout@v2
-      - run: sudo apt install python2
-      - run: curl https://bootstrap.pypa.io/pip/2.7/get-pip.py --output get-pip.py
-      - run: sudo python2 get-pip.py
-      - run: pip2 install -r requirements-2.txt
-      - run: python2 tests.py
   tests-python3:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-20.04 # this should probably get updated to a python 3.9+ image
     steps:
       - uses: actions/checkout@v2
+      - name: print python version
+        run:  python3 --version
       - name: install requirements
         run: pip3 install -r requirements-3.txt
       - name: run the tests
         run: python3 tests.py 
+      - name: verify type hints
+        run: mypy datemath
+      - name: verify package install
+        run: python3 setup.py install --user
+      - name: verify we can import
+        run: python3 -c "from datemath import datemath; print(datemath('now-1d'))"

CHANGELOG.md

@@ -1,48 +1,87 @@
 # Changelog
-## 1.5.5 (2021-04-26)
-* [FIX] [Issue #28](https://github.com/nickmaccarthy/python-datemath/issues/28)
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased] 
+### fixed
+- Fix: Race condition in timezone tests: https://github.com/nickmaccarthy/python-datemath/issues/36
+- Fix: Updated arrow version: https://github.com/nickmaccarthy/python-datemath/issues/32
+- Fix: mypy type hint checking in tests: https://github.com/nickmaccarthy/python-datemath/issues/31 
+- Fix: SyntaxWarning: invalid escape sequence in `re.match()`: https://github.com/nickmaccarthy/python-datemath/pull/39
+- Fix: Licence Classifier: https://github.com/nickmaccarthy/python-datemath/pull/34
+- Fix: Bump certifi to latest: https://github.com/nickmaccarthy/python-datemath/pull/38
+### added 
+- Feat: Typehint support: https://github.com/nickmaccarthy/python-datemath/issues/31
+- Feat: Revamed CHANGELOG.md to keepachangelog.org format
+
+### todo
+- todo: Fix pypi: https://github.com/nickmaccarthy/python-datemath/issues/33
+
+## deprecated
+- python 2.7 support. Python 3.8+ will only be supported going forward
+
+## [1.5.5] - 2021-04-26
+### fixed 
+- fix: [Issue #28](https://github.com/nickmaccarthy/python-datemath/issues/28)
     * `datemath()` object now returns the expected `datetime` object instead of an `Arrow` object
     * added tests to catch invalid object types of helpers
 
-## 1.5.4 (2021-04-20)
-* skipped due to name conflict on pypi, all changes in this are from `1.5.3`
+## [1.5.4] - 2021-04-20
+### Unused 
+- skipped due to name conflict on pypi, all changes in this are from `1.5.3`
 
-## 1.5.3 (2021-04-16)
-* [FIX] [Issue #25](https://github.com/nickmaccarthy/python-datemath/issues/25) - Fixed an issue where if you provided an invalid timestamp, i.e. `datemath('2')` you would not get an DateMathException back.  Also bumped dependencies.
+## [1.5.3] - 2021-04-16
+### fixed
+- FIX: [Issue #25](https://github.com/nickmaccarthy/python-datemath/issues/25) - Fixed an issue where if you provided an invalid timestamp, i.e. `datemath('2')` you would not get an DateMathException back.  Also bumped dependencies.
 
-## 1.5.2 (2020-10-01)
-* [FIX] [Issue #21](https://github.com/nickmaccarthy/python-datemath/issues/21) - Fixed an issue where if timezone offset was in a datetime string (ISO8601), the timezone of the returned datemath object would be UTC and not the timezone as specified in the datetime string.
+## [1.5.2] - 2020-10-01
+### fixed
+- FIX: [Issue #21](https://github.com/nickmaccarthy/python-datemath/issues/21) - Fixed an issue where if timezone offset was in a datetime string (ISO8601), the timezone of the returned datemath object would be UTC and not the timezone as specified in the datetime string.
 
 ## 1.5.1 (2020-03-25)
 
-* [FIX] [Issue #15](https://github.com/nickmaccarthy/python-datemath/issues/15) - Fixed issue with parser finding invalid timeunits and throwing correct errors
-* [NEW] [Issue #16](https://github.com/nickmaccarthy/python-datemath/issues/16) - Added support for parser to accecpt a epoch/unix timestamp but throw an error on epoch milli's since arrow can't support that.  
+### fixed
+- FIX: [Issue #15](https://github.com/nickmaccarthy/python-datemath/issues/15) - Fixed issue with parser finding invalid timeunits and throwing correct errors
+### added
+- Feat: [Issue #16](https://github.com/nickmaccarthy/python-datemath/issues/16) - Added support for parser to accecpt a epoch/unix timestamp but throw an error on epoch milli's since arrow can't support that.  
 
-## 1.5.0 (2019-11-09)
+## 1.5.0 - 2019-11-09
 
-* [FIX] [Issue #12](https://github.com/nickmaccarthy/python-datemath/issues/12) - missing VERSION.txt.  Added MANIFEST.in for sdist build
-* [FIX] [PR #13](https://github.com/nickmaccarthy/python-datemath/pull/13) - Fix `BaseException` to `Exception` inheritence, thank you for your contribution @yury-primer!
+### fixed
+- [Issue #12](https://github.com/nickmaccarthy/python-datemath/issues/12) - missing VERSION.txt.  Added MANIFEST.in for sdist build
+- [PR #13](https://github.com/nickmaccarthy/python-datemath/pull/13) - Fix `BaseException` to `Exception` inheritence, thank you for your contribution @yury-primer!
 
-## 1.4.9 (2019-10-26)
+## [1.4.9] - 2019-10-26
 
 ** PLEASE DO NOT USE THIS VERSION, use `1.5.0+` instead.  This may not compile on your system due to a missing VERSION.txt which was fixed in `1.5.0+` **
-* [FIX] [Issue #9](https://github.com/nickmaccarthy/python-datemath/issues/9) && [Issue #8](https://github.com/nickmaccarthy/python-datemath/issues/8) - Fixing deprecated arrow `replace()` function with `shift()`.
-* [FIX] Arrow upgrade to `0.15.2` to fix the above mentioned issues
-* [NEW] Breakout of python2 and python3 requirements
-* [NEW] Breakout of python2 and python3 specific CICD pipelines
-* [NEW] Derecated the following python version (although they may still work, they are no longer supported) - `2.4`,`2.6`,`3.4`,`3.5`
-* [FIX] Modifed `tests.py` to account for the timestamp change (tz is now `+0000`, instead of `-0000`)
-* [FIX] replaced `ts = ts.replace(tzinfo=tz.gettz(timezone))` with `ts = ts.replace(tzinfo=timezone)` in `datemath.helpers.parseTime()` to fix [Issue #7](https://github.com/nickmaccarthy/python-datemath/issues/7)
-
-## v1.4.8 (2019-10-25)
+
+### fixed 
+- [FIX] [Issue #9](https://github.com/nickmaccarthy/python-datemath/issues/9) && [Issue #8](https://github.com/nickmaccarthy/python-datemath/issues/8) - Fixing deprecated arrow `replace()` function with `shift()`.
+- [FIX] Arrow upgrade to `0.15.2` to fix the above mentioned issues
+- [FIX] Modifed `tests.py` to account for the timestamp change (tz is now `+0000`, instead of `-0000`)
+- [FIX] replaced `ts = ts.replace(tzinfo=tz.gettz(timezone))` with `ts = ts.replace(tzinfo=timezone)` in `datemath.helpers.parseTime()` to fix [Issue #7](https://github.com/nickmaccarthy/python-datemath/issues/7)
+### added
+
+- [NEW] Breakout of python2 and python3 requirements
+- [NEW] Breakout of python2 and python3 specific CICD pipelines
+- [NEW] Derecated the following python version (although they may still work, they are no longer supported) - `2.4`,`2.6`,`3.4`,`3.5`
+
+
+## [1.4.8] - 2019-10-25
+** dont use this version **
 * skipped due to name conflict on pypi, all changes are in `1.4.9`
 
-## v1.4.7 (2017-11-10)
-* [FIX] Fixed timezone for date strings: [Issue #6](https://github.com/nickmaccarthy/python-datemath/issues/6)
+## [1.4.7] - 2017-11-10
+### fixed 
+- [FIX] Fixed timezone for date strings: [Issue #6](https://github.com/nickmaccarthy/python-datemath/issues/6)
 
-## v1.4.5 (2017-03-21)
-* [NEW] Added roundDown functionality.  Allows user to specify the default rounding for expressions such as `/d`.
-* example - assuming the time is currently 2016-01-01 12:00:00, we should get the following
+## [1.4.5] - 2017-03-21
+### added
+- [NEW] Added roundDown functionality.  Allows user to specify the default rounding for expressions such as `/d`.
+- example - assuming the time is currently 2016-01-01 12:00:00, we should get the following
 ```
 >>> # now = 2016-01-01 14:00:00+00:00
 >>> dm('now+/d', roundDown=False)
@@ -51,8 +90,10 @@
 <Arrow [2016-01-01T00:00:00+00:00]>
 ```   
 
-## v1.4.4 (2016-12-28)
-* [FIX] Fixed bug with expression logic and rounding:  https://github.com/nickmaccarthy/python-datemath/pull/2
+## [1.4.4] - 2016-12-28
+### fixed
+- [FIX] Fixed bug with expression logic and rounding:  https://github.com/nickmaccarthy/python-datemath/pull/2
 
-## 1.4.3 (2016-03-31)
-* [NEW] Floats are now supported for days, hours, and seconds units.  Example ```now-2.5d```, ```now-3.2h```. Any other unit other than days, hours, or seconds that is a float will be converted to an int and floored due to the datetime() module not being able to handle them.
+## [1.4.3] - 2016-03-31
+### added 
+[NEW] Floats are now supported for days, hours, and seconds units.  Example ```now-2.5d```, ```now-3.2h```. Any other unit other than days, hours, or seconds that is a float will be converted to an int and floored due to the datetime() module not being able to handle them.

Makefile

@@ -0,0 +1,5 @@
+
+
+tests:
+	python3 tests.py 
+

README.md

@@ -1,21 +1,12 @@
-[![Build Status](https://travis-ci.org/nickmaccarthy/python-datemath.svg?branch=master)](https://travis-ci.org/nickmaccarthy/python-datemath.svg?branch=master)
-
 # Python Datemath
 
 ## What?
 
-A date math (aka datemath) parser compatiable with the elasticsearch 'date math' format
-
-## Why?
-
-Working with date objects in python has always been interesting.  Having a background in php, I have been looking for quite some time ( no pun intended ) for a way to do date time interpolation similar to php's ```strtotime()``` function.  While the arrow module comes close, I needed something that could turn date math type strings into datetime objects for use in [tattle.io](http://tattle.io) and other projects I use in elasticsearch.  I have found even more uses for it, including AWS cloudwatch and various other projects and hopefully you will too.
+A date math (aka datemath) parser compatiable with the elasticsearch "date math" format
 
-## What is date math?
+## 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, Elasticsearch has its own built in format for short hand date math and this module aims to support that same coverage in python.
-
-Documentation from elasticsearch:
-[http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/mapping-date-format.html#date-math](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/mapping-date-format.html#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).
 >
@@ -31,6 +22,7 @@ Documentation from elasticsearch:
 
 ## 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'
@@ -39,17 +31,14 @@ d or D      =   'day'
 w           =   'week'
 h or H      =   'hour'
 s or S      =   'second'
-```
-
-## Install
-
-```python
-pip install python-datemath
+now         =    <current_time_and_date>
 ```
 
 ## Examples
 
-Assuming our datetime is currently: `2016-01-01T00:00:00-00:00`
+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:
@@ -73,7 +62,7 @@ now/Y                       2016-12-31T23:59:59+00:00
 
 ## Usage
 
-By default datemath return an arrow date object representing your timestamp.  
+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
@@ -118,8 +107,25 @@ If you would rather have a string, you can use arrow's ```.format()``` method.
 u'2015.12.18'
 ```
 
-Rather have a python datetime object instead? Just pass along the 'datetime' type
+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')
@@ -129,21 +135,7 @@ datetime.datetime(2016, 1, 22, 22, 58, 28, 338060, tzinfo=tzutc())
 datetime.datetime(2016, 1, 24, 22, 57, 45, 394470, tzinfo=tzutc())
 ```
 
-Or you can just import the `datemath` module, this will always give us a native `datetime` object
-
-```python
->>> from datemath import datemath
->>>
->>> datemath('2016-01-01T16:20:00||/d', roundDown=False)
-datetime.datetime(2016, 1, 1, 23, 59, 59, 999999, tzinfo=tzutc())
->>>
->>>
->>> # roundDown=True is default and implied
->>> datemath('2016-01-01T16:20:00||/d')
-datetime.datetime(2016, 1, 1, 0, 0, tzinfo=tzutc())
-```
-
-If you want a Epoch timestamp back instead, we can do that.  
+If you want a Epoch timestamp back instead, we can do that too.  
 
 ```python
 >>> dm('now+2d-1m', type='timestamp')
@@ -152,7 +144,7 @@ If you want a Epoch timestamp back instead, we can do that.
 
 ## What timezone are my objects in?
 
-By default all object returned by datemath are in UTC.  
+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)
 
@@ -188,6 +180,12 @@ Note - currently timestrings with a timezone offset and the usage of the ```tz``
 <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`.

RELEASE.md

@@ -1,5 +1,5 @@
 # How to release
 
-*  Create a new tag/release in github. 
+* Create a new tag/release in github. 
 * Ensure new tag version matches VERSION.txt 
 * Actions should take care of the rest

VERSION.txt

@@ -1 +1 @@
-1.5.5
+3.0.1