add optional extra dep: pytz (#185)

* add optional extra deps: pytz&tzdata

* fix

* fix ci failed

* trigger ci

* fix

* mention pytz extra installation

* Update Makefile

* mention numba extra installation

* update hooks

* Clarify h3 timezone polygon index

FIX #168

* add pre-commit clean cmd

* Update README.rst

* mention alternative python packages

* Update 3_about.rst

* Update CHANGELOG.rst

* Update pyproject.toml

---------

Co-authored-by: Jannik Michelfeit <github@michelfe.it>

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
     -   repo: https://github.com/pre-commit/pre-commit-hooks
-        rev: v4.3.0
+        rev: v4.4.0
         hooks:
             -   id: check-ast  # Is it valid Python?
             -   id: debug-statements # no debbuging statements used
@@ -18,27 +18,26 @@ repos:
             -   id: detect-private-key
 
     -   repo: https://github.com/pycqa/isort
-        rev: 5.10.1
+        rev: 5.12.0
         hooks:
             -   id: isort
                 args: [ "--profile", "black", "--filter-files" ]
 
     -   repo: https://github.com/psf/black
-        rev: 22.6.0
+        rev: 23.1.0
         hooks:
             -   id: black
                 language_version: python3
                 args:
                     - --line-length=120
 
     -   repo: https://github.com/asottile/blacken-docs
-        rev: v1.12.1
+        rev: 1.13.0
         hooks:
             -   id: blacken-docs
-                additional_dependencies: [ black==20.8b1 ]
 
     -   repo: https://github.com/pycqa/flake8
-        rev: 3.9.2
+        rev: 6.0.0
         hooks:
             -   id: flake8
                 exclude: ^(docs|scripts|tests)/|build.py
@@ -53,18 +52,18 @@ repos:
 
     # TODO also check docs/. make compatible with sphinx
     -   repo: https://github.com/myint/rstcheck
-        rev: 'v6.1.0'
+        rev: 'v6.1.2'
         hooks:
             -   id: rstcheck
                 exclude: ^(docs/)
 
     -   repo: https://github.com/abravalheri/validate-pyproject
-        rev: v0.9
+        rev: v0.12.1
         hooks:
             -   id: validate-pyproject
 
     -   repo: https://github.com/asottile/pyupgrade
-        rev: v2.37.3
+        rev: v3.3.1
         hooks:
             -   id: pyupgrade
 
@@ -75,7 +74,7 @@ repos:
     #          -   id: pylint
 
     -   repo: https://github.com/pre-commit/mirrors-mypy
-        rev: v0.971
+        rev: v1.1.1
         hooks:
             -   id: mypy
                 exclude: ^((tests|scripts)/)
@@ -88,6 +87,6 @@ repos:
     #        additional_dependencies: [ numpy, poetry==1.1.11 ]
 
     -   repo: https://github.com/pre-commit/mirrors-clang-format
-        rev: v14.0.6
+        rev: v15.0.7
         hooks:
             -   id: clang-format

CHANGELOG.rst

@@ -2,14 +2,12 @@
 Changelog
 =========
 
-Future TODOs:
--------------
-
-* document class attributes
-* create variables for used dtype for each type of data (polygon address, coordinate...), write generic functions for reading binary files using the right data type, performance? many fct calls
-* improve tests:
-    * locations, expected results for all different methods,
-    * parameterised tests
+
+6.1.10 (2023-03-22)
+-------------------
+
+* added a `pytz` extra for easily maintaining compatibility
+* improved documentation
 
 
 6.1.9 (2022-12-06)

Makefile

@@ -3,18 +3,16 @@
 SHELL=/bin/bash
 
 
-pin:
-	@echo "pinning the dependencies specified in 'pyproject.toml':"
-	@poetry update -vv
-	#poetry export -f requirements.txt --output docs/requirements.txt --without-hashes
-
-req:
+install:
 	@echo "installing the development dependencies..."
-	@poetry install --extras "numba" --no-root
 	@#poetry install --no-dev
+	@poetry install --extras "numba" --no-root --sync
 
+update:
+	@echo "pinning the dependencies specified in 'pyproject.toml':"
+	@poetry update -vv
+	#poetry export -f requirements.txt --output docs/requirements.txt --without-hashes
 
-update: pin req
 
 env:
 	# conda env remove -n timezonefinder
@@ -33,6 +31,9 @@ hook:
 hook2:
 	@pre-commit autoupdate
 
+hook3:
+	@pre-commit clean
+
 clean:
 	rm -rf .pytest_cache .coverage coverage.xml tests/__pycache__ .mypyp_cache/ .tox
 

README.rst

@@ -37,8 +37,7 @@ timezonefinder
 
 
 
-This is a fast and lightweight python package for looking up the corresponding
-timezone for given coordinates on earth entirely offline.
+This is a python package for looking up the corresponding timezone for given coordinates on earth entirely offline.
 
 
 Quick Guide:

docs/0_getting_started.rst

@@ -13,6 +13,20 @@ Installation
     pip install timezonefinder
 
 
+in case you are using ``pytz``, also require it via its extra to avoid incompatibilities (e.g. due to updated timezone names):
+
+.. code-block:: console
+
+    pip install timezonefinder[pytz]
+
+
+for improved speed also install the optional dependency ``numba`` via its extra (also check the :ref:`performance chapter <performance>`):
+
+.. code-block:: console
+
+    pip install timezonefinder[numba]
+
+
 For installation within a Conda environment see instructions at `conda-forge feedstock <https://github.com/conda-forge/timezonefinder-feedstock>`__
 
 

docs/3_about.rst

@@ -7,12 +7,13 @@ About
 .. include:: ./badges.rst
 
 
-timezonefinder is a fast and lightweight python package for looking up the corresponding timezone for given coordinates on earth entirely offline.
+``timezonefinder`` is a python package for looking up the corresponding timezone for given coordinates on earth entirely offline.
 
-Timezones internally are being represented by polygons and the timezone membership of a given point (= lat lng coordinate pair) is determined by simple point in polygon tests.
-A few tweaks help to keep the computational requirements low and make this package fast.
-For example precomputed, so called "shortcuts" reduce the amount of timezone polygons to be checked (a kind of index for the polygons).
-See the documentation of the code itself for further explanation.
+Timezones internally are being represented by polygons and the timezone membership of a given point (= lat lng coordinate pair) is determined by a point in polygon (PIP) check.
+In many cases an expensive PIP check can be avoided.
+This package currently uses a precomputed timezone polygon index based on the geospatial hexagon index of the `h3 library <https://github.com/uber/h3-py>`__.
+Among other tweaks this index makes ``timezonefinder`` efficient (also check the :ref:`performance chapter <performance>`).
+See the docstrings in the source code for further explanation.
 
 Data
 ----
@@ -31,6 +32,8 @@ Current **data set** in use: precompiled `timezone-boundary-builder <https://git
     and that hence a query coordinate can actually match multiple time zones.
     ``timezonefinder`` does currently NOT support such multiplicity and will always only return the first found match.
 
+- package size: ~46 MB
+- original data size: ~110 MB
 
 
 References
@@ -57,6 +60,26 @@ License
 
 
 
+Alternative python packages
+---------------------------
+
+- `tzfpy <https://github.com/ringsaturn/tzfpy>`__ (less accurate, more lightweight, faster)
+- `pytzwhere <https://pypi.python.org/pypi/tzwhere>`__ (not maintained)
+
+
+Comparison to tzfpy
+-----------------------
+
+**Differences:**
+
+- ``tzfpy`` is a Python binding of the Rust package ``tzf-rs``
+- ``tzfpy`` has no startup time
+- ``tzfpy`` uses a hierarchical tree of rectangles as timezone polygons (data):
+    - this reduces the memory requirements
+    - this reduces the accuracy
+    - this increases the lookup speed
+
+
 Comparison to pytzwhere
 -----------------------
 
@@ -77,31 +100,14 @@ This package uses at most 40MB (= encountered memory consumption of the python p
 **Differences:**
 
 -  highly decreased memory usage
-
 -  highly reduced start up time
-
 -  usage of 32bit int (instead of 64+bit float) reduces computing time and memory consumption. The accuracy of 32bit int is still high enough. According to my calculations the worst accuracy is 1cm at the equator. This is far more precise than the discrete polygons in the data.
-
 -  the data is stored in memory friendly binary files (approx. 41MB in total, original data 120MB .json)
-
 -  data is only being read on demand (not completely read into memory if not needed)
-
 -  precomputed shortcuts are included to quickly look up which polygons have to be checked
-
--  function ``get_geometry()`` enables querying timezones for their geometric shape (= multipolygon with holes)
-
--  further speedup possible by the use of ``numba`` (code JIT compilation)
-
-
-
-::
-
-    Startup times:
-    tzwhere: 0:00:29.365294
-    timezonefinder: 0:00:00.000888
-    33068.02 times faster
-
-    all other cross tests are not meaningful because tz_where is still using the outdated tz_world data set
+- function ``get_geometry()`` enables querying timezones for their geometric shape (= multipolygon with holes)
+- further speedup possible by the use of ``numba`` (code JIT compilation)
+- tz_where is still using the outdated tz_world data set
 
 
 Contact
@@ -122,10 +128,8 @@ Acknowledgements
 
 Thanks to:
 
-`Adam <https://github.com/adamchainz>`__ for adding organisational features to the project and for helping me with publishing and testing routines.
-
-`snowman2 <https://github.com/snowman2>`__ for creating the conda-forge recipe.
-
-`synapticarbors <https://github.com/synapticarbors>`__ for fixing Numba import with py27.
-
-`zedrdave <https://github.com/zedrdave>`__ for valuable feedback.
+- `Adam <https://github.com/adamchainz>`__ for adding organisational features to the project and for helping me with publishing and testing routines.
+- `ringsaturn <https://github.com/ringsaturn>`__ for valuable feedback, sponsoring this project, creating the ``tzfpy`` package and adding the ``pytz`` compatibility extra
+- `snowman2 <https://github.com/snowman2>`__ for creating the conda-forge recipe.
+- `synapticarbors <https://github.com/synapticarbors>`__ for fixing Numba import with py27.
+- `zedrdave <https://github.com/zedrdave>`__ for valuable feedback.

docs/7_performance.rst

@@ -1,3 +1,4 @@
+.. _performance:
 
 Performance
 ===========