Skip to main content

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

Project description

tzfpy

  • PyPI
  • PyPI - Python Version
  • PyPI - Downloads
  • Anaconda-Server Badge
  • Conda Downloads
  • Conda Platform

[!NOTE]

  1. It's probably the fastest Python package to convert longitude/latitude to timezone name.
  2. This package use a simplified polygon data and not so accurate around borders.
  3. Rust use lazy init, so first calling will be a little slow.
  4. Use about 40MB memory.
  5. It's tested under Python 3.9+.
  6. Try it online:

Usage

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

# Install just tzfpy
pip install tzfpy

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

# Install with tzdata. https://github.com/python/tzdata
pip install "tzfpy[tzdata]"

# 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 v1.0.0 on my MacBook Pro with Apple M3 Max.

pytest --benchmark-warmup=on --benchmark-warmup-iterations=100 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     895.7926  11,420.8087  2,597.6093  1,331.8472  2,337.5032  1,587.5907  11611;1000      384.9694   33614          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 (2.03s):
         1 passed

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

More benchmarks compared with other packages can be found in ringsaturn/tz-benchmark.

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.

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.

Contributing

Install:

Available commands:
  build    - Build the project using uv
  fmt      - Format the code using ruff
  lint     - Lint the code using ruff
  sync     - Sync and compile the project using uv
  lock     - Lock dependencies using uv
  upgrade  - Upgrade dependencies using uv
  all      - Run lock, sync, fmt, lint, and test
  test     - Run tests using pytest
make all

LICENSE

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tzfpy-1.0.0.tar.gz (74.1 kB view details)

Uploaded Source

Built Distributions

tzfpy-1.0.0-cp313-cp313t-manylinux_2_24_armv7l.whl (6.3 MB view details)

Uploaded CPython 3.13tmanylinux: glibc 2.24+ ARMv7l

tzfpy-1.0.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (6.3 MB view details)

Uploaded CPython 3.13tmanylinux: glibc 2.17+ x86-64

tzfpy-1.0.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (6.3 MB view details)

Uploaded CPython 3.13tmanylinux: glibc 2.17+ ARM64

tzfpy-1.0.0-cp313-cp313t-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (12.7 MB view details)

Uploaded CPython 3.13tmacOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

tzfpy-1.0.0-cp39-abi3-win_arm64.whl (6.2 MB view details)

Uploaded CPython 3.9+Windows ARM64

tzfpy-1.0.0-cp39-abi3-win_amd64.whl (6.2 MB view details)

Uploaded CPython 3.9+Windows x86-64

tzfpy-1.0.0-cp39-abi3-musllinux_1_1_x86_64.whl (6.5 MB view details)

Uploaded CPython 3.9+musllinux: musl 1.1+ x86-64

tzfpy-1.0.0-cp39-abi3-musllinux_1_1_aarch64.whl (6.5 MB view details)

Uploaded CPython 3.9+musllinux: musl 1.1+ ARM64

tzfpy-1.0.0-cp39-abi3-manylinux_2_24_armv7l.whl (6.3 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.24+ ARMv7l

tzfpy-1.0.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (6.3 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

tzfpy-1.0.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (6.3 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

tzfpy-1.0.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (12.7 MB view details)

Uploaded CPython 3.9+macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

File details

Details for the file tzfpy-1.0.0.tar.gz.

File metadata

  • Download URL: tzfpy-1.0.0.tar.gz
  • Upload date:
  • Size: 74.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: maturin/1.8.3

File hashes

Hashes for tzfpy-1.0.0.tar.gz
Algorithm Hash digest
SHA256 8852bfcf392d4bbf980c88d9c9980d79dad559731b4a6b658a2875a2fa611f3b
MD5 c835e14042c7b2681830303f55367d28
BLAKE2b-256 f3875f797d7a4c2fb7a7bfaff1be552c380ef4a390251f7c8e61390380ebca9c

See more details on using hashes here.

File details

Details for the file tzfpy-1.0.0-cp313-cp313t-manylinux_2_24_armv7l.whl.

File metadata

File hashes

Hashes for tzfpy-1.0.0-cp313-cp313t-manylinux_2_24_armv7l.whl
Algorithm Hash digest
SHA256 3ed638a61131b7e84a4d89e4f7a1590a81aa0ff0262c04fcc7aa3882dbfaba15
MD5 49e5c5314318fb2ea92a85dd161987e5
BLAKE2b-256 f28fde15db4f0be3e9fa1cdd89e95e4b7785bd5d96c9ba01a73dc9fe4d5da0ea

See more details on using hashes here.

File details

Details for the file tzfpy-1.0.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for tzfpy-1.0.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 7369846a1f24339aa634054bd672dfbe00ee7bee832fa7884130639d19d37a3b
MD5 c01552eb0093a0f6c17427f8747ded06
BLAKE2b-256 786781c1ce2d358af696b2a6019d5154008b36267ac34f20a7b1c5784e564e02

See more details on using hashes here.

File details

Details for the file tzfpy-1.0.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for tzfpy-1.0.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 54159aa90f09b51fe26c76cd512b7b12275dac764f5e8bcb4f963adf99afb076
MD5 f552e3f68cee05cba00ca5d621bea2f4
BLAKE2b-256 af74b4fc5340badf9d94e2abd4fbc8d67668c7c8ce6f8b69115d6b9ae6cecbbe

See more details on using hashes here.

File details

Details for the file tzfpy-1.0.0-cp313-cp313t-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

File hashes

Hashes for tzfpy-1.0.0-cp313-cp313t-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 34b5e986d927a6aca1d2ba4ccffd15d5380fd6571064094c7fed157492ebc809
MD5 b9dad7916f2222ebd57ad55c3865ee79
BLAKE2b-256 f2dcadf3e8a1004d5234827ba661b853d51a4b579e948bdb23ab27ef651cafdd

See more details on using hashes here.

File details

Details for the file tzfpy-1.0.0-cp39-abi3-win_arm64.whl.

File metadata

  • Download URL: tzfpy-1.0.0-cp39-abi3-win_arm64.whl
  • Upload date:
  • Size: 6.2 MB
  • Tags: CPython 3.9+, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: maturin/1.8.3

File hashes

Hashes for tzfpy-1.0.0-cp39-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 d6c4d60bb00c18ee589899f667d5170ffbcf3b087312c223a5b6ae246d64c5fe
MD5 42e8d69417fd28cdedc8f75b46542f0d
BLAKE2b-256 484f70cf6ffc4d43dc14871b77a2417a8a6fda8eb4a0207bcc3a3b5abb59dfd7

See more details on using hashes here.

File details

Details for the file tzfpy-1.0.0-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: tzfpy-1.0.0-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 6.2 MB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: maturin/1.8.3

File hashes

Hashes for tzfpy-1.0.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 25528601b43db135414be5388ed11d73dc0e47b5e7f27eabf846b344a14e83df
MD5 2a1858431e5a0600853fe96b363a054a
BLAKE2b-256 a2e04c09f3e5c5ff3f53ef2af46f1cdbd2cf8e9453cb4019066090bb7ad4be32

See more details on using hashes here.

File details

Details for the file tzfpy-1.0.0-cp39-abi3-musllinux_1_1_x86_64.whl.

File metadata

File hashes

Hashes for tzfpy-1.0.0-cp39-abi3-musllinux_1_1_x86_64.whl
Algorithm Hash digest
SHA256 b74055119068111c82f330dbcdc62f9e0c3deed4c84e3523d7312db71bc97b33
MD5 cd345d66f6de14f43a6a6d2574324d75
BLAKE2b-256 bb02f808894da9de3c884618e6e3643747548b9239368bf5e614e11b15646e3f

See more details on using hashes here.

File details

Details for the file tzfpy-1.0.0-cp39-abi3-musllinux_1_1_aarch64.whl.

File metadata

File hashes

Hashes for tzfpy-1.0.0-cp39-abi3-musllinux_1_1_aarch64.whl
Algorithm Hash digest
SHA256 d7d77c48a5bd42821ae95757cf9d5118b25f72ad3116772b3349b5fd04012ec8
MD5 7d2ed745f323f51855fea5bf4f135b86
BLAKE2b-256 8ad072387ffc2a0b946cb77ffd64c31e08760ae51a3976d41995b46c3f33b427

See more details on using hashes here.

File details

Details for the file tzfpy-1.0.0-cp39-abi3-manylinux_2_24_armv7l.whl.

File metadata

File hashes

Hashes for tzfpy-1.0.0-cp39-abi3-manylinux_2_24_armv7l.whl
Algorithm Hash digest
SHA256 8750466ba55b5d46cc365e33c643dca3af7d84d76ed8a2199dbf53e32b3a29cc
MD5 a6377e756d89b990055631ff8aa7f72b
BLAKE2b-256 3fc513873f5942722df8aa81e5480b4ff689d72b36f2abeed7adbf2fe95b3f8f

See more details on using hashes here.

File details

Details for the file tzfpy-1.0.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for tzfpy-1.0.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 11290c1f8c87e33760d953acbfa1b0f2ed5d2bb402699cce8016abb9880063be
MD5 be599df2e5b719db4a68c85212b07c9c
BLAKE2b-256 2077cef4a08a1569368b18cd8f517862f42188e43140c2338d96464e2d7f4fac

See more details on using hashes here.

File details

Details for the file tzfpy-1.0.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for tzfpy-1.0.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 222dbb1f8581a0d124579f8b6aa6a51b5a91e4582e3ee51580806d902ad0997c
MD5 f577bd80a5dddddd8c6647c4ba095dc0
BLAKE2b-256 2e9458c8fdb023a77e182f389831ac3e6937d12cf8f9de9ed766d4ed2933ca34

See more details on using hashes here.

File details

Details for the file tzfpy-1.0.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

File hashes

Hashes for tzfpy-1.0.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 ed4cf971bd93291f12879092d0afcba4c3abde8e7840ac1b4ef7caa55da8a734
MD5 5f8d2680c2455c5944a4ff492881fcab
BLAKE2b-256 42259a142669f712a9360a5994fcfe6824cc0594ba0176dd0803a65c0ffc687d

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page