Skip to content

v2.0.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 11 Sep 01:59
· 16 commits to main since this release
Immutable release. Only release title and notes can be modified.
v2.0.0
9292868
This commit was signed with the committer’s verified signature.
ringsaturn Han Xiao
SSH Key Fingerprint: QySXL4DjKVxdRw74fO0nqtNwsD/jUAOXpo8cz8IpoHA
Verified
Learn about vigilant mode.

The Rust core behind tzfpy is now tzf-rs
2.0, which carries no protobuf dependency: timezone boundaries ship as the TZF
embedded binary format (.tzb). The dataset is the same 2026c release, and
query results are identical. Memory after import drops from 71.6–73.6 MB to
39.8–42.3 MB and the macOS arm64 wheel from 4.31 MB to 2.77 MB, both measured
below.

The Python API did not change. The same six functions with the same names,
signatures and return types:

from tzfpy import get_tz, get_tzs

get_tz(116.3883, 39.9289)  # 'Asia/Shanghai'   (longitude, latitude)
get_tzs(87.4160, 44.0400)  # ['Asia/Shanghai', 'Asia/Urumqi']
pip install -U tzfpy

Version numbering

The four contract changes listed below are the reason for a major version.
Code that does not depend on any of them runs unmodified after
pip install -U tzfpy.

Breaking changes

  1. get_tzs() results are sorted alphabetically. 1.x returned them in internal
    polygon order. get_tz() returns the first positive match and is the
    supported way to obtain a single name.
  2. _TZFPY_DISABLE_Y_STRIPES was removed. tzf-rs 2 removed FinderOptions,
    and the YStripes index is always enabled. Setting the variable has no effect
    and raises no error.
  3. get_tz_polygon_geojson() and get_tz_index_geojson() raise ValueError
    for a name the dataset does not carry. In 1.x the same input panicked,
    surfacing as pyo3_runtime.PanicException.
  4. Exported GeoJSON no longer repeats the duplicated junction vertices that the
    protobuf expansion carried (zero-length segments). Query results are
    identical; byte-for-byte comparisons against 1.x exports are not.

Unchanged: coordinate order is (longitude, latitude); the dataset is 2026c
(data_version() returns the same value); a point lying exactly on a shared
border belongs to both neighbouring zones; the finder is built on first use.

Measurements

MacBook Pro, Apple M3 Max, macOS 26.6.2, CPython 3.10.18. Both versions
measured back to back with the same script (scripts/measure_memory_tzfpy.py,
make bench) against the same 2026c dataset.

Metric 1.3.3 2.0.0
RSS after import tzfpy + one query 71.6–73.6 MB 39.8–42.3 MB
Whole-process RSS 89.7–96.4 MB 57.8–60.3 MB
Wheel size (macOS arm64) 4.31 MB 2.77 MB
Query median, random world cities 0.636 µs 0.683 µs

Query latency is within run-to-run variation of 1.3.3. One .tzb file replaces
the protobuf topology file and the pre-index file of 1.x, which accounts for the
memory and wheel-size figures.

Accuracy

Unchanged. tzfpy uses topology-simplified polygons; every simplified
boundary stays within about 111 m of the full-precision border (certified
111.2 m), 0.41% of border length is displaced more than 100 m, and none beyond
500 m. See the README's Accuracy section and
BORDER_CHANGE.md.

Packaging

  • Wheels for CPython 3.10+ (abi3) and free-threaded 3.14t: manylinux and
    musllinux (x86_64, aarch64, armv7), Windows (x64, x86, arm64), macOS (x86_64,
    arm64).
  • The Emscripten/Pyodide wheel is attached to this GitHub Release and,
    deliberately, not uploaded to PyPI.
  • conda-forge follows via the
    feedstock.

Links

Full Changelog: v1.3.3...v2.0.0

Assets 26
Loading