ringsaturn / tzfpy

Probably the fastest Python package to convert longitude/latitude to timezone name.

tzfpy

Note

0. It's probably the fastest Python package to convert longitude/latitude to timezone name.
1. This package use a simplified polygon data and not so accurate around borders.
2. Rust use lazy init, so first calling will be a little slow.
3. Use about 40MB memory.
4. It's tested under Python 3.9+ but support 3.8+(noqa).

Usage

Please note that new timezone names may be added to tzfpy, which could be incompatible with old version package like pytz. As an option, tzfpy supports install compatible version of those packages with extra params.

# Install just tzfpy
pip install tzfpy

# Install tzfpy with pytz
pip install "tzfpy[pytz]"

# Install via conda, see more in https://github.com/conda-forge/tzfpy-feedstock
conda install -c conda-forge tzfpy

>>> from tzfpy import get_tz, get_tzs
>>> get_tz(116.3883, 39.9289)  # in (longitude, latitude) order.
'Asia/Shanghai'
>>> get_tzs(87.4160, 44.0400)  # in (longitude, latitude) order.
['Asia/Shanghai', 'Asia/Urumqi']

Performance

Benchmark runs under v0.15.3 on my MacBook Pro with Apple M3 Max.

pytest tests/test_bench.py

------------------------------------------------------------ benchmark: 1 tests ------------------------------------------------------------
Name (time in ns)                 Min          Max        Mean    StdDev      Median         IQR  Outliers  OPS (Kops/s)  Rounds  Iterations
--------------------------------------------------------------------------------------------------------------------------------------------
test_tzfpy_random_cities     837.4918  11,183.2982  1,973.3456  833.9543  1,820.9103  1,066.7020  6422;511      506.7536   20000          10
--------------------------------------------------------------------------------------------------------------------------------------------

Legend:
  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
  OPS: Operations Per Second, computed as 1 / Mean
Results (1.95s):
         4 passed

Or you can view more benchmark results on GitHub Action summary page.

Background

tzfpy was originally written in Go named tzf and use CGO compiled to .so to be used by Python. Since v0.11.0 it's rewritten in Rust built on PyO3 and tzf-rs, a tzf's Rust port.

I have written an article about the history of tzf, its Rust port, and its Rust port's Python binding; you can view it here.

Project status

tzfpy is still under development and it has been deployed into my current company's production environment and it works well under high concurrency for weather API and location related data processed. So I think it's ready to be used in production with caution.

I haven't release the v1.0.0 yet and I will try my best to keep current API as stable as possible(only 3 functions). I'm still working on performance improvements on Rust side, which is a release blocker for both tzf-rs and tzfpy.

Compare with other packages

Please note that directly compare with other packages is not fair, because they have different use cases and design goals, for example, the precise.

TimezoneFinder

I got lots of inspiration from it. Timezonefinder is a very good package and it's mostly written in Python, so it's easy to use. And it's much more widely used compared with tzfpy if you care about that.

However, it's slower than tzfpy, especially around the borders, and I have lots of API requests from there. That's the reason I created tzf originally. And then tzf-rs and tzfpy.

pytzwhere

I recommend to read timezonefinder's Comparison to pytzwhere since it's very detailed.

LICENSE

This project is licensed under the MIT license. The data is licensed under the ODbL license, same as evansiroky/timezone-boundary-builder

tzfpy's Issues

Build wheels for Linux on Apple Silicon

Hey, this project looks pretty neat! Thank you for your work on it so far. 😄

Installing tzfpy within Docker on Apple Silicon fails because it can't find an appropriate wheel to run:

$ docker run -it --rm python:3.9-slim bash -c "pip install tzfpy"
Unable to find image 'python:3.9-slim' locally
3.9-slim: Pulling from library/python
934ce60d1040: Pull complete
1433a1692260: Pull complete
762827e25253: Pull complete
e40fc74453ae: Pull complete
215b61f46b6a: Pull complete
Digest: sha256:50c261237b02d3597d9ad74e72f6d67daadb1494856902b28db0d888091f0592
Status: Downloaded newer image for python:3.9-slim
ERROR: Could not find a version that satisfies the requirement tzfpy (from versions: none)
ERROR: No matching distribution found for tzfpy
WARNING: You are using pip version 22.0.4; however, version 22.3.1 is available.
You should consider upgrading via the '/usr/local/bin/python -m pip install --upgrade pip' command.

A workaround is to specify --platform linux/amd64 when running the Docker image:

$ docker run --platform linux/amd64 -it --rm python:3.9-slim bash -c "pip install tzfpy"
Unable to find image 'python:3.9-slim' locally
3.9-slim: Pulling from library/python
8740c948ffd4: Pull complete
69038a8b17e6: Pull complete
9eda7279ef48: Pull complete
03ebd05a13a5: Pull complete
c623e99b4bd9: Pull complete
Digest: sha256:50c261237b02d3597d9ad74e72f6d67daadb1494856902b28db0d888091f0592
Status: Downloaded newer image for python:3.9-slim
Collecting tzfpy
  Downloading tzfpy-0.12.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (7.0 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.0/7.0 MB 1.3 MB/s eta 0:00:00
Installing collected packages: tzfpy
Successfully installed tzfpy-0.12.1
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
WARNING: You are using pip version 22.0.4; however, version 22.3.1 is available.
You should consider upgrading via the '/usr/local/bin/python -m pip install --upgrade pip' command.

but most users probably won't be aware of this.

I think the appropriate wheel would be cp39-cp39-manylinux_2_17_aarch64.

Release for 2023d

Code is ready, wait for pytz new version release.