rbrooks/WeatherBot

Watch

Fork 0

chore(deps): update dependency timezonefinder to v9 #193

Open

renovate-bot wants to merge 1 commit from renovate/timezonefinder-9.x into main

renovate-bot commented

2026-09-14 06:18:38 +00:00

Contributor

This PR contains the following updates:

Package	Change	Age	Confidence
timezonefinder	`==8.2.5` → `==9.2.0`

Release Notes

jannikmi/timezonefinder (timezonefinder)

`v9.2.0`

Compare Source

Changed:

On x86_64 Linux, free-threaded CPython 3.15 and later installs a prebuilt wheel with the C extension, built against the free-threaded stable ABI (abi3t), instead of compiling from the sdist, and GIL builds of 3.15 and later install that same wheel. It needs an installer that knows the abi3t tag, such as a current pip or uv; older installers, other platforms and free-threaded 3.14 build from the sdist as before.
Python 3.15 is supported and tested. Python 3.12 remains supported until its NEP 29 drop date, 2027-04-02.

Documentation:

The comparison to pytzwhere <https://timezonefinder.readthedocs.io/en/latest/alternatives.html#comparison-to-pytzwhere>__ is shorter and now also compares batch throughput, one timezone_names_at() call against the per-point loop that is all pytzwhere offers, and says why the pure-Python fallback answers many points more slowly than pytzwhere.
The README and the About page gain a Used by section naming well-known dependents, and the repository carries a CITATION.cff, so GitHub offers a citation for it.

Internal:

The pyXY-pytz tox envs run the test suite once, with pytz installed, rather than also repeating the plain pyXY run.
A push to a release/** branch now commits the benchmark pages rendered for it, and a merged release pull request is tagged by CI once its master build is green, so neither is installed or pushed by hand.
ruff is raised to 0.17, with the pre-commit hook at the same version; the explicitly selected rule set reports nothing new and nothing is reformatted.
CI runs the slow tox env in a 3.14 job of its own, in parallel with the rest of the matrix, instead of after the other 3.14 envs.

`v9.1.0`

Compare Source

New features:

timezone_id_at() and timezone_id_at_land(), available on both finder classes and as global functions, return the numeric id of the same zone named by their existing scalar counterparts. They return None where the name lookup does; numeric zone ids remain local to the loaded dataset and must not be persisted without its version.
timezones_at(), as a TimezoneFinder method and a global function, returns every timezone whose polygons contain a point instead of the single one timezone_at() has to pick where the dataset's zones genuinely overlap - Asia/Urumqi inside Asia/Shanghai, and several disputed or dual-administered areas. The list always contains timezone_at()'s answer, which is what stops the two contradicting each other, and that answer is always the first element, so zones[0] is a drop-in for timezone_at(); the order of the rest is the internal candidate order and carries no meaning. There is no batch form.

Changed:

Dropped support for Python 3.11, which passed its drop date under the NumPy/Scientific-Python support schedule this project follows; the package now requires Python 3.12 or newer and its abi3 wheels are built against the cp312 stable ABI.
Raised the minimum required NumPy version to 2.2, the oldest release still supported by the schedule this project follows (2.0 and 2.1 passed their drop dates in June and August 2026).
The shortcut index is a longitude/latitude-aligned grid tree rather than an H3 hexagon grid: 0.75° cells, each refining into a 4×4 block of 0.1875° cells where several zones meet. The cell is two integer divisions per level rather than a library call, so it vectorises over a batch, and the cells are exact in the coordinate frame the point-in-polygon kernel reads, so a zone whose polygons only reach across a cell edge is no longer a candidate inside it. The published benchmark and data reports carry what the change measures in speed, memory and disk. TimezoneFinder answers are essentially unchanged: 2,000,000 area-weighted random points answer exactly as before, and over all 4,113,237 distinct stored boundary vertices off the −180 meridian and the −90 parallel, whose reading changes separately, 19 answers move. Those 19 are the two cases where candidate order decides rather than geometry, and the order is per cell: 18 are points inside no polygon at all - slivers on the 7.5° meridians where the ocean zones meet, where timezone_at() returns the final candidate untested and never promised otherwise - and one is a point inside both Australia/Brisbane and Etc/GMT-9, where the first containing candidate wins and both answers are equally truthful. TimezoneFinderL is an approximation by cell, so its answers move wherever a cell does. This is a binary format change: DATA_FORMAT_VERSION is 4, and timezonefinder now requires timezonefinder-data>=4.2026.5,<5.
The compiled C extension is now the point-in-polygon implementation wherever it loaded, and the optional numba extra is the fallback for an installation that has none, the ordering the acceleration path comparison <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_acceleration_paths.html>__ measures. Numba is no longer imported at all where the extension answers queries: timezonefinder.utils imports timezonefinder.utils_numba only in the branch a missing extension takes, since that import is what compiles it, so an installation carrying both no longer imports or compiles a JIT kernel it does not run. The coordinate converters that module used to supply (int2coord, convert2coords, convert2coord_pairs) are NumPy implementations in timezonefinder.utils now, returning exactly what they returned before. TimezoneFinder.using_numba() consequently reports whether the JIT kernel is what a lookup runs, which is False on an installation whose extension loaded however Numba is installed; TimezoneFinder.using_clang_pip() is unchanged, and the two are mutually exclusive again.
The package now declares the Programming Language :: Python :: Free Threading :: 3 - Stable classifier: lookups are supported and tested on free-threaded CPython builds, where the GIL stays disabled. Wheels for free-threaded interpreters are not published yet, so those installs build from the sdist.
h3 is no longer a runtime dependency and is not installed with the package: the grid-tree shortcut index replaced the H3 index it was there for. An import h3 that happened to work because timezonefinder pulled it in now fails unless h3 is declared directly. Dropping it also removes the one extension in the install that shipped without Py_mod_gil, so on a free-threaded build the GIL now stays disabled.
A lookup now reads lng=-180.0 as lng=180.0, the same meridian, and lat=-90.0 as the point one stored unit (~1.1 cm) north of the South Pole, so a point on either line answers the same zone whichever way it is spelled. As spelled, no polygon owns such a point: the point-in-polygon test gives a point on a boundary to the polygon west of it, or south of it along an east-west edge, and nothing lies west of -180° or south of -90°. So certain_timezone_at() returned None on both lines, and on the -180° meridian timezone_at(), timezones_at() and the batch lookups answered the last zone the shortcut index lists for the cell without testing it, which in places owned neither side of the meridian; they now answer what they answer at lng=180.0. TimezoneFinderL answers do not change.
Where two zones' polygons overlap, timezone_at() now answers the zone with the smaller spherical area - the one enclaved in the other - in every cell of the shortcut index, with the timezone identifier breaking an exact tie. Before, the pick in an overlap followed the zones' vertex counts within each index cell, a property of the index rather than of the zones that a data update could flip. timezones_at() still returns both zones, now with the smaller one first. With timezonefinder-data 4.2026.5 (upstream 2026e) and compared with 3.2026.4, eight overlaps change answer, each as a whole region: Kafia Kingi and Abyei from Africa/Khartoum to Africa/Juba, the West Bank overlap from Asia/Jerusalem to Asia/Hebron, the Southern Patagonian Ice Field from America/Punta_Arenas to America/Argentina/Rio_Gallegos, the Croatia-Serbia Danube border from Europe/Belgrade to Europe/Zagreb, the Bay of Piran from Europe/Zagreb to Europe/Ljubljana, a strip of the Strait of Juan de Fuca from America/Los_Angeles to America/Vancouver, and slivers of the Sint Maarten border from America/Marigot to America/Lower_Princes and of the Nova Scotia-New Brunswick border from America/Halifax to America/Moncton. Upstream 2026e also adds an overlap, a strip of sea off the Cerbère-Portbou coast that both Europe/Paris and Europe/Madrid now cover, which answers Europe/Madrid. The other overlaps, among them Asia/Urumqi inside Asia/Shanghai and Asia/Tbilisi over Europe/Moscow, keep their answer. TimezoneFinderL answers a multi-zone cell with the zone the full lookup tests last, which wherever the converter keeps this order is now the largest of the cell's zones, so its answer moves beyond the overlaps, mostly in coastal cells beside an ocean zone: measured on the 2026d boundaries, at 499 of the 1,843,200 centres of the index's smallest cells, where TimezoneFinder moves at 75, all inside the overlaps above.

Documentation:

The acceleration path comparison <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_acceleration_paths.html>__ now opens with which path measured fastest, and states every pairing - in its headlines and in its tables' result column - as "X is N times faster than Y" with the faster path as the subject, instead of a multiple of the C extension that had to be read backwards; the README no longer calls Numba the preferred backend, since it is used only where the C extension is unavailable.
The package comparison <https://timezonefinder.readthedocs.io/en/latest/alternatives.html>__ treats tzfpy's experimental full-precision variant as a genuine alternative, states which remaining distribution and API differences distinguish timezonefinder, and limits its benchmark conclusions to the simplified PyPI build it actually measured.
New page When batched lookups pay <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_batch_break_even.html>__: the batch API amortises validation, coordinate scaling and the shortcut table read over a whole batch, so a small batch is slower per point than a loop of scalar calls and a large one stops improving - the page measures where each of those happens, as a sweep of paired comparisons over a ladder of batch sizes from 10 to 100,000 points that runs past where batching stops improving, so that point is measured rather than off the end of the ladder, and says where a still larger batch gets slower per point again. Both answers depend on the caller's coordinates as much as on their hardware, because points sharing a shortcut cell are answered together, so scripts/measure_batch_break_even.py (make batch-break-even) takes --points your.csv and reports the same two numbers for your own workload.
Getting Started has a new "Upgrading and pinning" section: pin both timezonefinder and timezonefinder-data, record both versions with stored results, and recompute stored zones when either changes.
The acceleration path comparison <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_acceleration_paths.html>__ now also measures what installing the optional numba extra costs a process before any query - resident memory and time from a cold process to its first answer, in both environments, with the difference stated as the price of the extra - because speed was the only consequence the page priced and it is not the one a container memory limit or a cold-start budget is spent against. The README, getting started <https://timezonefinder.readthedocs.io/en/latest/0_getting_started.html>__, the performance page and the architecture page say so where they offer the extra, and the architecture page no longer claims the JIT compiles on first use: the signatures are eager, so a finder's construction pays the compilation.
The comparison to pytzwhere <https://timezonefinder.readthedocs.io/en/latest/alternatives.html#comparison-to-pytzwhere>__ now reports a side-by-side re-measurement against its last release: memory, startup and query speed, coverage, crashes near the poles, NumPy compatibility, and disk size.
The README is written in Markdown, which is what the PyPI project page now renders; its text, links and badges are unchanged.
New page Result stability and reproducibility <https://timezonefinder.readthedocs.io/en/latest/result_stability.html>__: a lookup is a pure function of the coordinates and the installed data, which leaves two axes that can still move an answer. A timezonefinder-data update can change it through boundary geometry, polygon precedence where polygons overlap, or shortcut composition and ordering; a code release can change it through a bug fix, a documented semantic change, or an optimization of the query logic - 9.0.0's candidate reordering changed what TimezoneFinderL returns in a multi-zone cell. A point strictly inside exactly one polygon is decided by geometry alone and none of it reaches that point. timezonefinder-data versions read <format>.<year>.<letter>[.postN] and are not semantic versions: no data bump promises unchanged answers, dataset changes reach an unpinned install without a code release, and the code changelog does not record them. Pinning the data freezes the artefacts and pinning the code freezes the rules that read them, so reproducibility across deployments needs both.
The thread-safety documentation now says one thing: concurrent lookups through the global functions or on a shared TimezoneFinder are safe, and one instance per thread is recommended for parallel throughput rather than for correctness.
The tzfpy comparison page is renamed Speed and startup against tzfpy <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_vs_tzfpy.html>__ and adds a Bulk lookups table: the same points answered by one timezone_names_at() call against a loop of tzfpy calls, since tzfpy has no batch API.
The notes on certain_timezone_at() and timezones_at() and the certainty-probe paragraph of the alternatives page now say where no polygon contains a point with the packaged data: in slivers the stored boundaries of neighbouring zones leave between them. A point on a border two zones share goes to one of them, and lng=180.0 and lat=90.0 are owned like any other edge.
New design page Why timezonefinder doesn't simplify polygons <https://timezonefinder.readthedocs.io/en/latest/why_no_simplification.html>__: why simplification concentrates error at the borders a lookup can get wrong, how it would break shared borders and hole deduplication, which lossless mechanisms deliver its benefits instead, the options considered, and the conditions that would reopen the decision.

Internal:

The abi3 wheel claim in setup.py is now withheld on free-threaded interpreters, so a free-threaded wheel build no longer fails on a py_limited_api setting that setuptools refuses there.
make shortcut-calibration fits the shortcut-ordering costs from counted predicate stages, re-orders every ambiguous cell with the fitted and an area-only model, and A/B-times whole lookups on the cells that change; make shortcut-calibration-record keeps a reviewed run in benchmarks/shortcut_ordering_model.json. The production coefficients are unchanged: re-calibrated on the aligned grid tree, the fitted order is not shown to be better, and the recorded run's decision line says why.
The payload calibration table the data-update guard's bands are checked against is no longer required to end at the packaged release, so a data update owes it no hand-written row; a format-generation assertion replaces that requirement and fails only when a layout change makes the recorded byte counts incomparable.
The data converter now reaches its boundary and hole rings through one collection object each, named and accessed as the runtime names the same two collections (boundaries/holes with coords_of, nr_vertices, bounds_of, ids_of and holes_of), instead of indexing parallel per-polygon lists that callers had to keep in step by hand.
The automated data-update workflows now check that the DATA_UPDATER_GH_APP_ID and DATA_UPDATER_GH_PRIVATE_KEY secrets are both set before minting a token, and the fallback issue the weekly check opens names an unconfigured GitHub App as the cause instead of asking for the data to be regenerated by hand.
The automated data-release workflow now brings an update pull request onto current master itself when branch protection has left it behind, instead of waiting for someone to press "Update branch" on a finished release.
The automated data-update pull request now states that it merges and publishes itself once CI passes, and how to withhold the release, instead of leaving a reviewer to infer whether it is waiting on them.
The weekly data update now stages the acceleration-paths, batch-break-even and reduced-zone-mapping files its own regeneration writes, and a test holds that staging list against the generated-file constants so a newly added report page fails there rather than after a full regeneration.
The data converter orders shortcut candidates deterministically: zones of exactly equal spherical area are ordered by timezone identifier and equal polygons within a zone by polygon id, so compiling one boundary release twice yields byte-identical shortcut indexes. timezonefinder-data 4.2026.5 is compiled with this order.
A free-threaded tox env, run in CI, now tests the package on a free-threaded interpreter.
Changelog fragment previews and release assembly generate the pending section on demand, so CHANGELOG.rst contains only released history between releases.
The converter's rule for a cell's candidate polygons is tight rather than conservative, and rests on a planar predicate rather than on evidence that cannot establish an exclusion. A cell is an axis-aligned rectangle of the stored integer coordinates, so "can this polygon own one of the cell's points" is a question about two rectangles and a ring, evaluated against the point-in-polygon kernel's own edge convention: scripts/grid_cells.py holds it. It never omits a polygon the kernel can place a cell's point inside, and over-includes only one whose interior enters the cell without reaching any of its integer points - a sliver under ~1.1 cm, costing that cell one bounding-box rejection. tests/grid_cells_test.py holds the rule to the kernel over randomised polygons, and scripts/audit_shortcut_candidates.py probes every stored cell's four corners and four edge midpoints on each compiled dataset.
Reporting now starts from a form: a bug report that asks for the failing coordinates and for the output of one command reporting the installed versions and which point-in-polygon backend the installation actually uses, or a feature request, with links routing usage questions to Discussions and misplaced boundaries upstream to timezone-boundary-builder.
Tests pin which polygon owns a point exactly on its boundary - the one whose interior lies immediately west of the point, or immediately south of it along an east-west edge - on every point-in-polygon kernel, compiled and interpreted, packed and unpacked, and through the whole lookup on the borders the ocean zones share. The point-in-polygon cases tests/utils_test.py had left commented out as undefined are now asserted.
Prevent code-release workflows from silently skipping the PyPI upload after their tag-side test job is intentionally skipped.
Add a guarded trusted-publishing recovery command that downloads and validates an existing code tag's GitHub Release assets before uploading them to PyPI.
The committed tzfpy agreement chart is rendered with the same deterministic Matplotlib SVG conventions as the other report charts, while remaining byte-for-byte reproducible from its stored measurement.
The Linux wheel job retries pulls of its pinned manylinux and musllinux build images before cibuildwheel starts, so transient container-registry failures do not invalidate an otherwise successful wheel build.
The shortcut index now maps a coordinate to its cell itself (ShortcutIndex.entry_at and entries_at): the lookup methods, the benchmark fixture generator and the tests that resolve a point hand it a longitude and latitude instead of computing an H3 cell id of their own, and the shortcut-ordering calibration's stand-in index answers the same question, so replacing the index's cells needs no change to timezonefinder.py.
The candidate-ordering guarantee is now asserted against the real lookup: permuting a multi-zone cell's candidates within one zone cannot move a TimezoneFinder answer, a point contained by a single zone's candidates survives any permutation at all, a cross-zone rotation does move answers (so those two assert something), TimezoneFinderL answers the final candidate's zone, and the converter's geometric safety gate refuses pole and antimeridian cells before reading any geometry.
CI now runs the test suite against the oldest NumPy release the published numpy>=2.2 requirement allows (2.2.0 on Python 3.12) via the new py312-min tox environment, so the declared lower bound is exercised instead of assumed.

`v9.0.0`

Compare Source

New features:

timezone_id_at() and timezone_id_at_land(), available on both finder classes and as global functions, return the numeric id of the same zone named by their existing scalar counterparts. They return None where the name lookup does; numeric zone ids remain local to the loaded dataset and must not be persisted without its version.
timezones_at(), as a TimezoneFinder method and a global function, returns every timezone whose polygons contain a point instead of the single one timezone_at() has to pick where the dataset's zones genuinely overlap - Asia/Urumqi inside Asia/Shanghai, and several disputed or dual-administered areas. The list always contains timezone_at()'s answer, which is what stops the two contradicting each other, and that answer is always the first element, so zones[0] is a drop-in for timezone_at(); the order of the rest is the internal candidate order and carries no meaning. There is no batch form.

Changed:

Dropped support for Python 3.11, which passed its drop date under the NumPy/Scientific-Python support schedule this project follows; the package now requires Python 3.12 or newer and its abi3 wheels are built against the cp312 stable ABI.
Raised the minimum required NumPy version to 2.2, the oldest release still supported by the schedule this project follows (2.0 and 2.1 passed their drop dates in June and August 2026).
The shortcut index is a longitude/latitude-aligned grid tree rather than an H3 hexagon grid: 0.75° cells, each refining into a 4×4 block of 0.1875° cells where several zones meet. The cell is two integer divisions per level rather than a library call, so it vectorises over a batch, and the cells are exact in the coordinate frame the point-in-polygon kernel reads, so a zone whose polygons only reach across a cell edge is no longer a candidate inside it. The published benchmark and data reports carry what the change measures in speed, memory and disk. TimezoneFinder answers are essentially unchanged: 2,000,000 area-weighted random points answer exactly as before, and over all 4,113,237 distinct stored boundary vertices off the −180 meridian and the −90 parallel, whose reading changes separately, 19 answers move. Those 19 are the two cases where candidate order decides rather than geometry, and the order is per cell: 18 are points inside no polygon at all - slivers on the 7.5° meridians where the ocean zones meet, where timezone_at() returns the final candidate untested and never promised otherwise - and one is a point inside both Australia/Brisbane and Etc/GMT-9, where the first containing candidate wins and both answers are equally truthful. TimezoneFinderL is an approximation by cell, so its answers move wherever a cell does. This is a binary format change: DATA_FORMAT_VERSION is 4, and timezonefinder now requires timezonefinder-data>=4.2026.5,<5.
The compiled C extension is now the point-in-polygon implementation wherever it loaded, and the optional numba extra is the fallback for an installation that has none, the ordering the acceleration path comparison <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_acceleration_paths.html>__ measures. Numba is no longer imported at all where the extension answers queries: timezonefinder.utils imports timezonefinder.utils_numba only in the branch a missing extension takes, since that import is what compiles it, so an installation carrying both no longer imports or compiles a JIT kernel it does not run. The coordinate converters that module used to supply (int2coord, convert2coords, convert2coord_pairs) are NumPy implementations in timezonefinder.utils now, returning exactly what they returned before. TimezoneFinder.using_numba() consequently reports whether the JIT kernel is what a lookup runs, which is False on an installation whose extension loaded however Numba is installed; TimezoneFinder.using_clang_pip() is unchanged, and the two are mutually exclusive again.
The package now declares the Programming Language :: Python :: Free Threading :: 3 - Stable classifier: lookups are supported and tested on free-threaded CPython builds, where the GIL stays disabled. Wheels for free-threaded interpreters are not published yet, so those installs build from the sdist.
h3 is no longer a runtime dependency and is not installed with the package: the grid-tree shortcut index replaced the H3 index it was there for. An import h3 that happened to work because timezonefinder pulled it in now fails unless h3 is declared directly. Dropping it also removes the one extension in the install that shipped without Py_mod_gil, so on a free-threaded build the GIL now stays disabled.
A lookup now reads lng=-180.0 as lng=180.0, the same meridian, and lat=-90.0 as the point one stored unit (~1.1 cm) north of the South Pole, so a point on either line answers the same zone whichever way it is spelled. As spelled, no polygon owns such a point: the point-in-polygon test gives a point on a boundary to the polygon west of it, or south of it along an east-west edge, and nothing lies west of -180° or south of -90°. So certain_timezone_at() returned None on both lines, and on the -180° meridian timezone_at(), timezones_at() and the batch lookups answered the last zone the shortcut index lists for the cell without testing it, which in places owned neither side of the meridian; they now answer what they answer at lng=180.0. TimezoneFinderL answers do not change.
Where two zones' polygons overlap, timezone_at() now answers the zone with the smaller spherical area - the one enclaved in the other - in every cell of the shortcut index, with the timezone identifier breaking an exact tie. Before, the pick in an overlap followed the zones' vertex counts within each index cell, a property of the index rather than of the zones that a data update could flip. timezones_at() still returns both zones, now with the smaller one first. With timezonefinder-data 4.2026.5 (upstream 2026e) and compared with 3.2026.4, eight overlaps change answer, each as a whole region: Kafia Kingi and Abyei from Africa/Khartoum to Africa/Juba, the West Bank overlap from Asia/Jerusalem to Asia/Hebron, the Southern Patagonian Ice Field from America/Punta_Arenas to America/Argentina/Rio_Gallegos, the Croatia-Serbia Danube border from Europe/Belgrade to Europe/Zagreb, the Bay of Piran from Europe/Zagreb to Europe/Ljubljana, a strip of the Strait of Juan de Fuca from America/Los_Angeles to America/Vancouver, and slivers of the Sint Maarten border from America/Marigot to America/Lower_Princes and of the Nova Scotia-New Brunswick border from America/Halifax to America/Moncton. Upstream 2026e also adds an overlap, a strip of sea off the Cerbère-Portbou coast that both Europe/Paris and Europe/Madrid now cover, which answers Europe/Madrid. The other overlaps, among them Asia/Urumqi inside Asia/Shanghai and Asia/Tbilisi over Europe/Moscow, keep their answer. TimezoneFinderL answers a multi-zone cell with the zone the full lookup tests last, which wherever the converter keeps this order is now the largest of the cell's zones, so its answer moves beyond the overlaps, mostly in coastal cells beside an ocean zone: measured on the 2026d boundaries, at 499 of the 1,843,200 centres of the index's smallest cells, where TimezoneFinder moves at 75, all inside the overlaps above.

Documentation:

The acceleration path comparison <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_acceleration_paths.html>__ now opens with which path measured fastest, and states every pairing - in its headlines and in its tables' result column - as "X is N times faster than Y" with the faster path as the subject, instead of a multiple of the C extension that had to be read backwards; the README no longer calls Numba the preferred backend, since it is used only where the C extension is unavailable.
The package comparison <https://timezonefinder.readthedocs.io/en/latest/alternatives.html>__ treats tzfpy's experimental full-precision variant as a genuine alternative, states which remaining distribution and API differences distinguish timezonefinder, and limits its benchmark conclusions to the simplified PyPI build it actually measured.
New page When batched lookups pay <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_batch_break_even.html>__: the batch API amortises validation, coordinate scaling and the shortcut table read over a whole batch, so a small batch is slower per point than a loop of scalar calls and a large one stops improving - the page measures where each of those happens, as a sweep of paired comparisons over a ladder of batch sizes from 10 to 100,000 points that runs past where batching stops improving, so that point is measured rather than off the end of the ladder, and says where a still larger batch gets slower per point again. Both answers depend on the caller's coordinates as much as on their hardware, because points sharing a shortcut cell are answered together, so scripts/measure_batch_break_even.py (make batch-break-even) takes --points your.csv and reports the same two numbers for your own workload.
Getting Started has a new "Upgrading and pinning" section: pin both timezonefinder and timezonefinder-data, record both versions with stored results, and recompute stored zones when either changes.
The acceleration path comparison <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_acceleration_paths.html>__ now also measures what installing the optional numba extra costs a process before any query - resident memory and time from a cold process to its first answer, in both environments, with the difference stated as the price of the extra - because speed was the only consequence the page priced and it is not the one a container memory limit or a cold-start budget is spent against. The README, getting started <https://timezonefinder.readthedocs.io/en/latest/0_getting_started.html>__, the performance page and the architecture page say so where they offer the extra, and the architecture page no longer claims the JIT compiles on first use: the signatures are eager, so a finder's construction pays the compilation.
The comparison to pytzwhere <https://timezonefinder.readthedocs.io/en/latest/alternatives.html#comparison-to-pytzwhere>__ now reports a side-by-side re-measurement against its last release: memory, startup and query speed, coverage, crashes near the poles, NumPy compatibility, and disk size.
The README is written in Markdown, which is what the PyPI project page now renders; its text, links and badges are unchanged.
New page Result stability and reproducibility <https://timezonefinder.readthedocs.io/en/latest/result_stability.html>__: a lookup is a pure function of the coordinates and the installed data, which leaves two axes that can still move an answer. A timezonefinder-data update can change it through boundary geometry, polygon precedence where polygons overlap, or shortcut composition and ordering; a code release can change it through a bug fix, a documented semantic change, or an optimization of the query logic - 9.0.0's candidate reordering changed what TimezoneFinderL returns in a multi-zone cell. A point strictly inside exactly one polygon is decided by geometry alone and none of it reaches that point. timezonefinder-data versions read <format>.<year>.<letter>[.postN] and are not semantic versions: no data bump promises unchanged answers, dataset changes reach an unpinned install without a code release, and the code changelog does not record them. Pinning the data freezes the artefacts and pinning the code freezes the rules that read them, so reproducibility across deployments needs both.
The thread-safety documentation now says one thing: concurrent lookups through the global functions or on a shared TimezoneFinder are safe, and one instance per thread is recommended for parallel throughput rather than for correctness.
The tzfpy comparison page is renamed Speed and startup against tzfpy <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_vs_tzfpy.html>__ and adds a Bulk lookups table: the same points answered by one timezone_names_at() call against a loop of tzfpy calls, since tzfpy has no batch API.
The notes on certain_timezone_at() and timezones_at() and the certainty-probe paragraph of the alternatives page now say where no polygon contains a point with the packaged data: in slivers the stored boundaries of neighbouring zones leave between them. A point on a border two zones share goes to one of them, and lng=180.0 and lat=90.0 are owned like any other edge.
New design page Why timezonefinder doesn't simplify polygons <https://timezonefinder.readthedocs.io/en/latest/why_no_simplification.html>__: why simplification concentrates error at the borders a lookup can get wrong, how it would break shared borders and hole deduplication, which lossless mechanisms deliver its benefits instead, the options considered, and the conditions that would reopen the decision.

Internal:

The abi3 wheel claim in setup.py is now withheld on free-threaded interpreters, so a free-threaded wheel build no longer fails on a py_limited_api setting that setuptools refuses there.
make shortcut-calibration fits the shortcut-ordering costs from counted predicate stages, re-orders every ambiguous cell with the fitted and an area-only model, and A/B-times whole lookups on the cells that change; make shortcut-calibration-record keeps a reviewed run in benchmarks/shortcut_ordering_model.json. The production coefficients are unchanged: re-calibrated on the aligned grid tree, the fitted order is not shown to be better, and the recorded run's decision line says why.
The payload calibration table the data-update guard's bands are checked against is no longer required to end at the packaged release, so a data update owes it no hand-written row; a format-generation assertion replaces that requirement and fails only when a layout change makes the recorded byte counts incomparable.
The data converter now reaches its boundary and hole rings through one collection object each, named and accessed as the runtime names the same two collections (boundaries/holes with coords_of, nr_vertices, bounds_of, ids_of and holes_of), instead of indexing parallel per-polygon lists that callers had to keep in step by hand.
The automated data-update workflows now check that the DATA_UPDATER_GH_APP_ID and DATA_UPDATER_GH_PRIVATE_KEY secrets are both set before minting a token, and the fallback issue the weekly check opens names an unconfigured GitHub App as the cause instead of asking for the data to be regenerated by hand.
The automated data-release workflow now brings an update pull request onto current master itself when branch protection has left it behind, instead of waiting for someone to press "Update branch" on a finished release.
The automated data-update pull request now states that it merges and publishes itself once CI passes, and how to withhold the release, instead of leaving a reviewer to infer whether it is waiting on them.
The weekly data update now stages the acceleration-paths, batch-break-even and reduced-zone-mapping files its own regeneration writes, and a test holds that staging list against the generated-file constants so a newly added report page fails there rather than after a full regeneration.
The data converter orders shortcut candidates deterministically: zones of exactly equal spherical area are ordered by timezone identifier and equal polygons within a zone by polygon id, so compiling one boundary release twice yields byte-identical shortcut indexes. timezonefinder-data 4.2026.5 is compiled with this order.
A free-threaded tox env, run in CI, now tests the package on a free-threaded interpreter.
Changelog fragment previews and release assembly generate the pending section on demand, so CHANGELOG.rst contains only released history between releases.
The converter's rule for a cell's candidate polygons is tight rather than conservative, and rests on a planar predicate rather than on evidence that cannot establish an exclusion. A cell is an axis-aligned rectangle of the stored integer coordinates, so "can this polygon own one of the cell's points" is a question about two rectangles and a ring, evaluated against the point-in-polygon kernel's own edge convention: scripts/grid_cells.py holds it. It never omits a polygon the kernel can place a cell's point inside, and over-includes only one whose interior enters the cell without reaching any of its integer points - a sliver under ~1.1 cm, costing that cell one bounding-box rejection. tests/grid_cells_test.py holds the rule to the kernel over randomised polygons, and scripts/audit_shortcut_candidates.py probes every stored cell's four corners and four edge midpoints on each compiled dataset.
Reporting now starts from a form: a bug report that asks for the failing coordinates and for the output of one command reporting the installed versions and which point-in-polygon backend the installation actually uses, or a feature request, with links routing usage questions to Discussions and misplaced boundaries upstream to timezone-boundary-builder.
Tests pin which polygon owns a point exactly on its boundary - the one whose interior lies immediately west of the point, or immediately south of it along an east-west edge - on every point-in-polygon kernel, compiled and interpreted, packed and unpacked, and through the whole lookup on the borders the ocean zones share. The point-in-polygon cases tests/utils_test.py had left commented out as undefined are now asserted.
Prevent code-release workflows from silently skipping the PyPI upload after their tag-side test job is intentionally skipped.
Add a guarded trusted-publishing recovery command that downloads and validates an existing code tag's GitHub Release assets before uploading them to PyPI.
The committed tzfpy agreement chart is rendered with the same deterministic Matplotlib SVG conventions as the other report charts, while remaining byte-for-byte reproducible from its stored measurement.
The Linux wheel job retries pulls of its pinned manylinux and musllinux build images before cibuildwheel starts, so transient container-registry failures do not invalidate an otherwise successful wheel build.
The shortcut index now maps a coordinate to its cell itself (ShortcutIndex.entry_at and entries_at): the lookup methods, the benchmark fixture generator and the tests that resolve a point hand it a longitude and latitude instead of computing an H3 cell id of their own, and the shortcut-ordering calibration's stand-in index answers the same question, so replacing the index's cells needs no change to timezonefinder.py.
The candidate-ordering guarantee is now asserted against the real lookup: permuting a multi-zone cell's candidates within one zone cannot move a TimezoneFinder answer, a point contained by a single zone's candidates survives any permutation at all, a cross-zone rotation does move answers (so those two assert something), TimezoneFinderL answers the final candidate's zone, and the converter's geometric safety gate refuses pole and antimeridian cells before reading any geometry.
CI now runs the test suite against the oldest NumPy release the published numpy>=2.2 requirement allows (2.2.0 on Python 3.12) via the new py312-min tox environment, so the declared lower bound is exercised instead of assumed.

`v8.3.0`

Compare Source

New features:

The dataset version is now exposed at runtime. TimezoneFinder().data_version (and TimezoneFinderL().data_version) return the timezone-boundary-builder release the packaged data was built from, read from a data_version.txt stamp that scripts/file_converter.py writes into the data directory it generates and that ships in the wheel. Previously an installed timezonefinder could not state it at all: the release tag lived only in a repo-root file that is not packaged. Which release a parse is stamped with comes from the input's filename (combined-with-oceans-2026c.json, which update_data.sh now produces), or from scripts/file_converter.py --data-version for an input that cannot carry it; your own GeoJSON is stamped "unknown", and an unpacked release archive that lost its tag is refused rather than compiled into data that could never say where it came from. timezonefinder.__version__ is now exposed as well, read from the installed distribution metadata. Solves issue #498.
The command line script gained a --stdin streaming mode: it reads delimited rows from standard input and writes each back out with a timezone column appended, building the finder once instead of paying full initialisation per coordinate. Which columns hold the coordinates is read off the header by name, or stated with --lng-col/--lat-col, and never inferred from their position - a swapped pair is still a valid coordinate for any longitude between -90 and 90, so guessing would answer with a real but wrong timezone instead of failing. Every input row produces exactly one output row, and a row that cannot be used warns on stderr and makes the run exit non-zero rather than ending the stream. Whether the first row is a header is worked out from the row, or stated with --header/--no-header. New flags -d/--delimiter and --in-memory apply to the whole stream. See the usage documentation <https://timezonefinder.readthedocs.io/en/latest/1_usage.html#looking-up-many-coordinates-at-once>. Solves issue #504. Thanks to weed33834 <https://github.com/weed33834> for the PR #516.

Changed:

Polygon coordinates are now stored one axis at a time in the packaged coordinates.bin files - all x values followed by all y values per polygon, instead of interleaved. The point in polygon test scans a single axis per iteration, so contiguous per-axis blocks halve the cache lines it touches: ~1.6x faster on a median polygon and ~2.5x faster on the largest ones via the C extension, 14-25% faster via Numba. The bundled data was regenerated accordingly, and the layout is described in the data format documentation <https://timezonefinder.readthedocs.io/en/latest/data_format.html>__.
Every packaged FlatBuffers file now carries a file identifier and a layout version, and TimezoneFinder raises a ValueError naming the offending file when either does not match - previously such a directory was read without complaint and produced wrong timezones. For coordinates.bin the version records how the coordinates are encoded and which polygons the file holds. The hybrid shortcut binaries get an identifier that differs per zone id width, because the uint8 and uint16 schemas differ only in the width of a zone id and each parses cleanly as the other; the width is now read from the buffer instead of being guessed from the file name, so a renamed or mispaired shortcut file fails loudly rather than returning wrong zones. If you compile your own data and point bin_file_location at it, regenerate it once with scripts/file_converter.py, since the coordinate layout, the hole storage, the shortcut container and the file names all changed in this release. The markers track what a file holds rather than the package version, so this is not a per-release obligation. Solves issue #458.
The hybrid shortcut loader no longer keeps the entire shortcut binary in memory. The polygon id arrays it returns were zero-copy views onto the ~1.5 MB file buffer, so ~47 KB of live data pinned the whole thing for the lifetime of every TimezoneFinder / TimezoneFinderL instance. They are now disjoint read-only slices of a single compact array, cutting the shortcut mapping's footprint from ~7.4 MB to ~4.7 MB per instance, and every finder's resident set by ~2 MB, at unchanged initialisation time - which matters most for concurrent workloads, where the recommended one-instance-per-thread pattern multiplied the waste.
Holes that duplicate a timezone boundary polygon are no longer stored twice. Almost every hole is an enclave, cut into the surrounding zone with exactly the ring the upstream data also emits as the enclosed zone's own boundary polygon - the same geometry under two IDs. The packaged hole coordinate file now holds only the rings with no such twin (27 of 756 in the current data), and a new holes/poly_ref.npy records per hole which boundary polygon to read instead. Hole data drops from ~2.0 MiB to ~0.16 MiB, and in_memory=True saves the same amount of RAM, since those holes now resolve into the boundary arrays rather than materialising a second copy. Matching is exact - rings are compared as integer coordinates in a canonical form, with bounding boxes used only to narrow the search - so every timezone lookup returns what it did before. One visible consequence: get_geometry() may hand back a deduplicated hole ring starting at a different vertex or winding the other way than it used to, tracing the same closed path. The encoding is described in the data format documentation <https://timezonefinder.readthedocs.io/en/latest/data_format.html>__.
The timezone boundary data now ships as its own distribution, timezonefinder-data. pip install timezonefinder is unchanged - it is a hard dependency and is installed automatically - but the dataset can now be pinned on its own (pip install timezonefinder "timezonefinder-data==1.2026.3"), where previously holding a dataset meant pinning an old timezonefinder and forfeiting every code fix since. Every release used to carry the whole ~65 MB dataset in three platform wheels plus an sdist to distinguish a few kilobytes of compiled code, which had already exhausted the PyPI project storage quota once. A data update is consequently no longer a timezonefinder release at all: it publishes timezonefinder-data under its own tag namespace and is recorded in that package's README rather than here. Its version reads <format>.<year>.<letter> - 1.2026.3 is data format generation 1 built from timezone-boundary-builder 2026c - and timezonefinder requires timezonefinder-data>=…,<2: no ceiling on the data axis, so a dataset update needs no code release, and a hard one on the format axis, so code paired with data it cannot read fails when resolving rather than at the first lookup. DATA_LICENSE moves with the database it covers and now ships inside the data wheel, and a compiled data directory additionally carries a schemas/ copy of the FlatBuffers definitions its binaries were written by, so it can be read back without the package that wrote it. Solves the first part of issue #446.
The packaged FlatBuffers binaries are now named .bin rather than .fbs: boundaries/coordinates.bin, holes/coordinates.bin and hybrid_shortcuts_uint16.bin. .fbs is the FlatBuffers schema extension, and the data directory now ships actual schemas next to the buffers, so one extension was naming two unrelated kinds of file. Each buffer already states what it is through the file identifier in its first bytes, which is what a rename or a mispaired copy cannot forge - the name never carried that meaning. The bytes are unchanged.

Bug fixes:

Fixed a BufferError: cannot close exported pointers exist raised during resource cleanup in file mode (in_memory=False). A coordinate array obtained from coords_of() is a zero-copy view onto the memory-mapped file, and mmap.close() refuses to unmap while one is alive, so an array outliving its TimezoneFinder raised on cleanup. The mapping now stays valid instead of leaving the views dangling, and FileCoordAccessor.cleanup() releases its own references so the deferred close happens as soon as the last view is dropped. The accessor must not be used after cleanup().

Documentation:

The memory footprint of every finder configuration is now measured and published in a new memory report <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_memory.html>__, separating what a configuration allocates (tracemalloc) from what it makes resident (RSS, which additionally counts memory-mapped pages). The distinction is the point: the default mode maps the coordinate data instead of reading it, so it allocates an order of magnitude less than the in-memory mode, and only the pages a lookup actually touches become resident. This replaces documentation claiming a 40MB process ceiling and a 41MB data directory, both long out of date.
Restructured the two entry points a reader actually arrives at - README.rst and the documentation landing page <https://timezonefinder.readthedocs.io/en/latest/>__ - so both state what the package is and how it works instead of only what it is called. The README opens with the project banner and a one-sentence statement of what the package is for, then the badges, then the quick guide - and adds three short sections that were missing entirely: How it works (the lookup pipeline and the no-simplification trade-off), Performance (a concrete throughput figure with its configuration named, the three point-in-polygon backends and the pure-Python fallback), and Engineering notes linking the architecture, data format and benchmarking methodology pages. The maintainers-wanted notice moves from the first heading after the intro into a new Contributing section at the bottom, which also links CONTRIBUTING.md for the first time. The badge block is corrected along the way: the code style: black badge named a formatter this project has never used and is replaced by ruff, and a supported-Python-versions badge was added. The banner is referenced by absolute URL, since PyPI serves the long description without the repository and a docs/… path renders as a broken image there. The landing page gains the same How it works summary, the no-simplification trade-off and the ocean-zone consequence for timezone_at(), and its flat seventeen-entry table of contents is grouped into Using it, Design, Performance and Project, so the sidebar says what kind of project this is rather than listing pages in the order they were written.
Rewrote the package comparison <https://timezonefinder.readthedocs.io/en/latest/alternatives.html>__ page. It now states its position in prose before the first table - border correctness is what this package optimises for, speed is the constraint that work happens under - and says plainly when tzfpy is the better choice. Every quantitative cell names what it measures and links its source, and the speed row is deliberately qualitative on both sides, with a note explaining that the two packages have never been benchmarked under one harness. The decision table drops the rows on which the two packages do not differ.
Two new documentation pages: Architecture <https://timezonefinder.readthedocs.io/en/latest/architecture.html>__ describes the lookup pipeline, the three point-in-polygon backends and the memory modes, and states the ceilings this package deliberately does not exceed - unsimplified geometry, ~1 cm coordinate resolution, no general-purpose spatial code. It also documents how the package is built and shipped, which was previously described nowhere outside the workflow YAML: why one abi3 wheel per target replaces one wheel per Python version and what abi3audit is guarding, why three libc targets are built, why the end-to-end job installs the built wheel and asserts the C extension loaded rather than merely importing the package, and why a tag pushed from outside master aborts the release. The testing section gained the property-based suite and the reason the tox matrix is a matrix - the acceleration paths are bound at import time, so a passing run describes one configuration only. Both sections are linked from the README's Engineering notes. Benchmarking Methodology <https://timezonefinder.readthedocs.io/en/latest/benchmarking_methodology.html>__ documents how the published numbers are produced and what they can and cannot tell you: ubuntu-latest pins the runner image and not the CPU, which is why a pull request is measured against its own merge base on the same runner and why every alert threshold is derived from measured noise. It was previously addressed only to contributors, in the second half of CONTRIBUTING.md, which now keeps the operational instructions and links to it.
The H3 resolution choice in the data format documentation <https://timezonefinder.readthedocs.io/en/latest/data_format.html>__ is no longer asserted to "offer a good balance" but reports the study behind it (prototypes/single_resolution_bench.py): resolution 3 keeps the hybrid index at a small fraction of the packaged polygon data, while resolution 4 would exceed 10 % of it for gains that do not justify the increase.
The hand-written documentation no longer restates exact figures that belong to the generated pages - dataset vertex, polygon and hole counts, index and distribution sizes, memory footprints, lookup throughput. Those change with every data update and with code that shifts a footprint, which silently left the copies wrong: the memory figures had already gone stale in four places. The prose now states the magnitude that survives a data update and links the data report <https://timezonefinder.readthedocs.io/en/latest/data_report.html>__ or the relevant benchmark report <https://timezonefinder.readthedocs.io/en/latest/7_performance.html>__, which are regenerated from the packaged data and are always current.
The three weakest hand-written documentation pages no longer answer a question by pointing at a file the reader has to open. The performance page <https://timezonefinder.readthedocs.io/en/latest/7_performance.html>__ now opens with the four benchmark reports and the trend chart instead of a bullet list of adjectives about the binary format, and its C extension and Numba sections are cut to what a user does - which call reports the active backend - with the explanation left to the architecture page that already carried a more precise version of it. Getting started lists the four runtime dependencies and what each is for, where it previously said to consult pyproject.toml, which remains linked as the authoritative source for version ranges. The use case pages carry runnable snippets for building an aware datetime and reading a UTC offset, with the examples/ scripts as the follow-up rather than the whole answer; the snippets use the standard library's zoneinfo, so neither needs an optional dependency.
The shortcut entry distributions in the data report <https://timezonefinder.readthedocs.io/en/latest/data_report.html>__ no longer report three quarters of all H3 cells as holding 0 polygons, which is impossible for data whose ocean zones cover the globe. Those cells are covered by a single timezone and store its id directly, so a lookup there needs no point-in-polygon test at all - the column is now Polygons to test and the row reads none (unique zone). The tables are introduced by a sentence on what they measure, including why no cell ever needs exactly one test.
The usage examples in README.rst and the usage documentation <https://timezonefinder.readthedocs.io/en/latest/1_usage.html>__ now show the result the packaged data actually returns. Every snippet queries the same Berlin coordinates and annotated the answer as 'Europe/Paris', which is the value from the reduced timezones-now dataset, where Europe/Berlin is merged into Europe/Paris - not from the full dataset the package ships by default. All eleven annotations now read 'Europe/Berlin', verified against the packaged data for each of timezone_at(), timezone_at_land(), certain_timezone_at(), unique_timezone_at() and TimezoneFinderL, and the get_geometry() call in the opening example asks for that same zone instead of a different one. tests/test_documented_contracts.py now re-runs each of those documented lookups, so a data update that moves the example coordinate's zone fails there rather than leaving every snippet on both pages quietly wrong again.

Internal:

The release pipeline refuses to publish timezonefinder unless a compatible timezonefinder-data already exists on PyPI. The two distributions release independently, and on a data format change the order is fixed - data first, then the code requiring it - because a code wheel whose declared data version does not exist yet is uninstallable for everyone until it does, and the version number cannot be reused to fix it. The check reads the requirement out of the built wheel rather than out of pyproject.toml, and asks the index the same question a user's resolver will, so a yanked release does not count as one that satisfies it. It runs before the GitHub Release, which is the first step of the release that cannot be taken back.
Pull requests are opened against a template (.github/pull_request_template.md) prompting for the change, its motivation and the checks that were run.
update_data.sh resolves the timezone-boundary-builder release tag before downloading and fetches that release's asset, instead of fetching releases/latest/download/ and separately asking the API what latest was - two independent questions that a release landing between them answered differently, attributing one release's data to the other. The tag now names the downloaded archive and the GeoJSON as well, so a leftover file from another release or another dataset variant cannot satisfy the "already downloaded" checks and be parsed in place of what was asked for.
Names and docstrings now describe what the code does. TimezoneFinder.timezone_at documents the optimisation it actually performs: once no other zone can be matched the last remaining zone is returned without a point in polygon test, which is always correct against the packaged data - the ocean zones cover the globe, so every point lies within one of the candidate polygons - but not against custom data that leaves areas uncovered, where a point inside none of the candidates is still attributed to that zone and certain_timezone_at is the method that tests every candidate. Three tests were named after something other than what they do: test_rectify_coords_valid/_invalid were named for a rectify_coords that exists nowhere in the package and both call validate_coordinates, and the first was subsumed entirely by test_validate_coordinates_accepts_finite_values, which covers all four of its distinct corners and additionally asserts the return value where the older test asserted only "does not raise"; and test_single_element_arrays_should_not_occur asserted that they do occur (assert single_element_count == 2) under a triple-quoted string placed after the first statement, making it a discarded expression rather than a docstring - so it reached neither --collect-only nor a failure report, which is where the contradicting name was the only thing a reader saw. A stale comment duplicated across the last two lines of tests/main_test.py, reading as a to-do for something TestTimezonefinderClassTestMEM already does, is gone.
Added DATA_VERSION file tracking which timezone-boundary-builder release the packaged data was generated from, written automatically by the data update script after a successful parse. Thanks to Lucas Hemkemeier <https://github.com/hemkdev>__ for the PR #429.
The packaged data now updates itself: a weekly workflow compares DATA_VERSION against the latest timezone-boundary-builder release, regenerates the data and opens a ready-to-review update PR, which is merged and released automatically once its CI passes - the version tag is pushed with a GitHub App token, since the default one would not trigger the release pipeline. The tag lives in its own data-v* namespace, which the code release pipeline excludes at its trigger and again on the job that creates the GitHub Release, and the data stream publishes by PyPI Trusted Publishing from its own deployment environment rather than with a shared token. It refuses to release when the squash it produced did not land on the master it checked, so the tag names a tree that was actually built. Failed CI takes the same manual-attention path and falls back to the previous notification issue. Each cause labels the PR automation-failed and leaves one comment naming that cause and linking the run, deduplicated per cause so re-running CI neither repeats a notice nor hides a second one; a failure past the merge is a cause of its own, since that leaves master carrying the update with no tag pushed and only a hand-pushed tag still releases it. The manual release path drops the stop condition it carried for an out-of-order CHANGELOG.rst: the automation can no longer produce one, and the test suite asserts the committed file's section order if anything else does (issues #273, #167 and #510). Thanks to Lucas Hemkemeier <https://github.com/hemkdev>__ for the PRs #434 and #436, and to Nice6042 <https://github.com/Nice6042>__ for the PR #518.
update_data.sh (renamed from parse_data.sh) is CI-ready: interactive prompts replaced by flags (--dataset=full|same-since-now, --with-oceans, --rm-tmp), the release note for a data update written automatically into the data package's README, no redundant tox run, and a make reports at the end so the benchmark and data reports cannot go stale relative to the data an update PR ships. A standalone make parse/make testparse still needs a manual make reports (issues #167 and #510). Thanks to Lucas Hemkemeier <https://github.com/hemkdev>__ for the PRs #432 and #434.
Added property-based tests (hypothesis) for coordinate validation (solves issue #143). Thanks to Lu Yicheng <https://github.com/01luyicheng>__ for the PRs #431 and #433.
Replaced the hand-rolled timeit timing in scripts/check_speed_*.py with pytest-benchmark suites under benchmarks/, excluded from make test/make testall via testpaths. Both they and the memory harness run over deterministic committed fixtures (tests/fixtures/benchmarks/), so two runs of the same commit execute the exact same workload; the loader rejects fixtures that no longer match the checkout. Measurement and rendering are decoupled, so docs/benchmark_results_*.rst can be regenerated from a stored JSON without re-measuring. Run via make speedtest, make benchmarks, make memory or make reports.
Memory is measured by its own harness (scripts/measure_memory.py, make memory) rather than by pytest-benchmark, which times code and would have its timings distorted by allocation tracking. It emits pytest-benchmark-shaped JSON, so the existing normalisation, noise and comparison tooling works on it unchanged given a --metric. tests/test_memory_footprint.py fails if a mode's allocation leaves its order of magnitude - the regression that would make in_memory=False stop being the low-memory option.
Added continuous benchmarking on CI (solves issue #150), deliberately kept out of the release pipeline in build.yml: the tracked core subset and the memory harness run on every pull request and every push to master, publishing trend charts <https://jannikmi.github.io/timezonefinder/dev/bench/>__ to gh-pages and posting a same-runner base/head comparison on the pull request. The comparison reports added or removed benchmark IDs without trying to ratio unmatched measurements, which lets the trusted default-branch consumer remain compatible while the suite evolves. A pull request is measured against its own merge base in the same job rather than against a stored baseline, because runs-on: ubuntu-latest pins the runner image and not the CPU. The measurement design, the tracked estimator and every alert threshold are documented in the new benchmarking methodology <https://timezonefinder.readthedocs.io/en/latest/benchmarking_methodology.html>__ page. The measuring job holds no write permissions and no secrets, so branch and fork pull requests behave identically; the comment is posted by a separate, privileged workflow via workflow_run.
Guarded the benchmark plumbing against silent drift: tests/test_benchmark_names.py and tests/test_memory_metric_names.py pin the node ids and metric names that join a measurement to its chart history, so a rename fails loudly instead of starting an empty chart beside the orphaned old one; tests/test_benchmark_workflows.py asserts that the constants duplicated across the two workflows agree, where a one-sided edit previously had no failure mode at all, and that the cross-machine trend chart cannot creep back into the pull request comparison; and every generated report page states the inputs it describes - docs/benchmark_results_*.rst the fixture and timezone data versions they were measured against, docs/data_report.rst the timezone data version its figures were derived from. Both stamps are covered by tests: one renders each report and fails if a renderer stops emitting it, another checks the committed pages against the current fixture metadata and DATA_VERSION, so regenerating fixtures or updating the data without re-rendering fails loudly instead of leaving a page whose numbers are all plausible and all stale.
Every generator now emits output that is already pre-commit-clean, so regenerating and diffing compares like with like: write_json sorts keys the way pretty-format-json does, and neither scripts/reporting.py nor BenchmarkReporter emits trailing whitespace on empty cells or a trailing blank line. Previously every make parse/make reports left its outputs looking modified until the hooks had run, which masked whether a regeneration had actually changed anything.
Every generated benchmark report now opens with its headline figure and the configuration behind it, above the tables: how long a lookup takes and how many per second, the per-check cost across polygon sizes, construction time, footprint per mode - all derived from the same parsed JSON as the tables, never hardcoded. The banner beneath states which acceleration path and platform produced the numbers, and says whether that is the configuration CI tracks: the committed reports are rendered from a developer machine with Numba enabled, while CI measures the C extension without Numba, so their figures were never comparable to the trend chart and now say so.
make flatbuf no longer overwrites hand-maintained __init__.py files. flatc derives its output path from the schema namespace and writes an empty __init__.py at every level of it, so generating in place wiped the __all__ in timezonefinder/__init__.py - the whole public API. The target now generates into a scratch tree, copies back only the generated packages, and runs the formatters on the result so a regeneration diff shows the codegen change rather than formatting churn.
Mypy now type-checks the whole package except the flatc-generated bindings. ignore_errors previously covered roughly 800 lines of hand-written code as well, where a blatantly wrong return type still reported "Success"; they all pass once the exemption is lifted, bar two genuine findings now fixed. tests/test_mypy_config.py keeps the list restricted to generated code, so silencing a module is a reviewed decision rather than a one-line edit.
The hybrid shortcut reader and writer now select their FlatBuffers schema from a single registry (SHORTCUT_SCHEMAS in timezonefinder/flatbuf/io/hybrid_shortcuts.py) instead of dispatching on the zone id width in three places, each keyed differently. One ShortcutSchema per width owns the width, the file name, the uintN marker and the maximum zone id, which were previously written down across five places with nothing tying them together. Verified behaviour-preserving down to the bytes: re-writing the shipped shortcut binary produces a byte-identical file.
Each distribution's build is now asserted to contain exactly what it should. The data wheel's payload is compared against the committed dataset as a set, in both directions: a missing binary fails on first use and gets reported, but an extra one ships silently - setuptools copies package data into build/lib and never prunes it, so a file renamed in the source tree keeps being zipped into every later wheel built from that checkout, which is how a 63 MB coordinates.fbs was still shipping next to the coordinates.bin that replaced it and doubling the wheel whose size is the reason the distribution was split out. The wheel builders clear that directory first, so a local build matches the fresh checkout CI builds from, and the code sdist's checks cover its grafted test fixtures again.
The packaged data is additionally held to a floor on how much hole deduplication achieves - the test suite fails if fewer than 90% of its holes match a boundary polygon (96.4% currently), because a future upstream release that stopped emitting enclaves as shared rings would still compile and still return correct timezones, just with the shipped data quietly re-inflated. The floor applies to that dataset and nothing else: compiling your own GeoJSON with scripts/file_converter.py is a supported use case, holes that are ordinary interior rings rather than enclaves are stored inline and answer correctly, and the converter only reports the ratio rather than refusing to compile. prototypes/hole_boundary_redundancy.py is the study behind the threshold: it reads the upstream GeoJSON, so re-running it against a new release re-verifies the assumption rather than restating it. prototypes/hole_removal_impact.py is the study behind keeping the unmatched holes stored inline rather than dropping them, which is the obvious next step and does not work: dropping holes and re-running the lookups changes answers, wrongly, because being covered by another zone only puts that zone among the shortcut candidates and says nothing about it being tested first (issue #513).
Removed constructs that provably did nothing, and gave two vacuous tests real assertions. Most consequentially, four __slots__ entries were declared but assigned by nothing, which silently re-permitted the very attributes __slots__ is there to forbid - assigning those names now raises AttributeError, and test_declared_slots_are_assigned keeps the list honest.
get_corrected_hex_boundaries exists once again. An earlier refactor left two verbatim copies of the antimeridian and pole clipping rules with nothing keeping them in sync; the copy without callers is deleted, and the survivor is now covered by tests/hex_utils_test.py - it previously had no direct tests at all. scripts/configs.py no longer declares MAX_LAT/MAX_LNG as a second pair of names for timezonefinder.configs's constants.
prototypes/ has a README.md saying what the three scripts there are: exploratory studies behind committed design decisions, run by hand, outside the package and the test suite. One of them is the measurement that chose H3 resolution 3 - the central algorithmic parameter of the package, already cited from the data format page - and another is the evidence for not building a hierarchical index. MANIFEST.in now excludes the whole directory from the source distribution rather than only its *.py files.
plans/ is git-ignored alongside tmp/ and .venv/: implementation plans written while working on a change are local scratch, and leaving the directory untracked-but-unignored made it noise in every git status and a candidate for an over-broad git add.
Failing paths now report the input that failed. tests/auxiliaries.py's run_command assembled the child's stdout and stderr into a message and then raised a fresh CalledProcessError that never used it, with from None discarding the original too, so a packaging failure under make testint reported an exit code and nothing about the cause; it now echoes the captured streams and re-raises the original exception with its traceback intact. scripts/reporting.py passes the coordinate file paths into get_polygon_collection, whose optional file_path exists precisely so an incompatible-layout ValueError can say which of the two files was stale - make reports against an outdated data directory previously could not. Boundaries.overlaps names the type it rejected instead of raising a bare TypeError, and the RuntimeError for missing original_polygons names the polygon and resolution it was computing. The two re-raises ruff flags under B904 now say from None explicitly, so a deliberately dropped exception chain is distinguishable from a forgotten one, and timezonefinder/command_line.py drops FileNotFoundError from an except tuple that already caught its base class OSError. tests/test_error_diagnostics.py pins what each of these messages must contain.
The command line interface no longer routes its own output through a temporary file. main redirected stdout to a mkstemp file for the duration of the lookup and then, in verbose mode, reopened it to read back a string it still held in a local variable - nothing inside the redirected block ever wrote to stdout, since the lookup functions return their result rather than printing it. The context manager, the read-back, its warning path and the file cleanup are gone, and the lookup function is now resolved once per invocation instead of twice, so -f 3/-f 4 under -v no longer construct a second TimezoneFinderL and reload its shortcut data just to read a function name. Output is unchanged character for character, across every function id in both modes. tests/cli_test.py gains the coverage that makes that checkable - verbose mode, the empty line printed when no timezone is found, and the rejected function id had none - and asserts the printed name verbatim instead of passing it through rstrip("\n\x1b[0m"), which strips a set of characters rather than a suffix and so truncates 12 of the packaged zone names (Europe/Amsterdam -> Europe/Amsterda).
Docstrings now describe the code that exists. Six documented something the implementation contradicts: AbstractTimezoneFinder.__init__ called in_memory inert and "kept for API compatibility" when it is what selects memory-mapped against in-memory coordinate access - the claim help(TimezoneFinder) surfaces, and the opposite of what the usage docs say; both get_geometry docstrings pointed at a timezone_names.json that does not exist under that name; read_zone_names promised an empty list where it raises FileNotFoundError, and illustrated itself with a hardcoded zone count that the packaged data had since outgrown; and zone_id_of / zone_name_from_id each advertised an exception type they convert away, sending callers to write handlers that can never fire. Five further :param:/Args: entries in scripts/ and tests/ documented arguments that were removed along with the parallel shortcut compilation they belonged to. tests/test_documented_contracts.py pins the exception types and the coordinate access mode, so those promises now rest on something besides prose.
The test and benchmark suites no longer contain checks that cannot fail. Eighteen calls sat inside four shared pytest.raises blocks in tests/main_test.py, and execution leaves such a block at the first statement to raise - so one out-of-range coordinate, one positional call shape and one rejected get_geometry input were verified while the remaining fifteen were unreachable. Each is a test case of its own now: every coordinate just outside the WGS84 range, every positional call shape of every keyword-only lookup method, and the unknown-zone-name, past-the-end and negative zone id rejections of get_geometry. The __del__ cleanup test binds its exception per iteration rather than closing over the loop variable, which decided what a garbage-collected instance would raise long after the loop had moved on. On the benchmark side, pip_inputs_by_stratum validated only the strata the fixture happened to contain, so one missing from it altogether passed and surfaced later as a bare KeyError inside a benchmark, and the points and their labels were paired from two files with a non-strict zip that truncates silently. That grouping now lives in tests/auxiliaries.py as group_pip_inputs_by_stratum, checks against the declared PIP_STRATA - which the generator no longer keeps a second copy of - and has tests for each way the two fixture files can disagree.
Both point-in-polygon acceleration paths are now covered by a local test run, whichever one the environment happens to bind. The implementation is selected at import time and Numba wins whenever it is importable - which the documented setup (uv sync --all-groups) makes it - so the C extension was reached only by direct-kernel tests on hand-built arrays, and everything about how real polygon buffers arrive at it, including the read-only memory-mapped views, was first exercised in CI's non-numba tox environments: the configuration a plain pip install timezonefinder produces. tests/test_acceleration_paths.py now rebinds utils.inside_polygon and drives the full lookup stack through both implementations, asserting that they agree across the real boundary data, that the C path returns the known-correct answers, and that the point-in-polygon stage was reached at all rather than short-circuited by the shortcut layer (issue #482).
The packaging guard in tests/test_package_contents.py no longer names files that do not exist. It asserts that nothing in the built sdist and wheel matches a list of unwanted paths, which passes just as readily when a pattern matches nothing at all: .github lacked the trailing slash that directory patterns need, Agents.* stopped matching when the file was renamed to AGENTS.md, and readthedocs.yaml never matched readthedocs.yml - so the CI configuration and both of those files were unguarded while the suite stayed green. The patterns are corrected, the provider stubs, contributing/, .agents/, .claude/ and .cursor/ are covered to match what MANIFEST.in excludes, and test_every_unwanted_pattern_matches_a_project_file now fails on any hand-written pattern that matches no path in the checkout, so the next rename cannot silently disarm one. It carries the unit marker rather than the module's former blanket integration mark, since it needs no build: a mistyped pattern surfaces in make test. .gitignore re-include lines (!…) are also no longer read as exclusions, which had produced one more parametrised case that could never fail. The converse direction is checked too: test_every_manifest_exclusion_is_guarded parses the exclude/recursive-exclude/prune/global-exclude directives out of MANIFEST.in and fails when one of them keeps a path out of the build that no pattern here names - previously such a line was enforced by the build and verified by nothing, so deleting it would have shipped the file with the suite still green. The two lists are hand-maintained statements of one intent and had drifted before, in both directions. The architecture page <https://timezonefinder.readthedocs.io/en/latest/architecture.html>__ describes the guard from both sides: among the tests that exist to give an invariant a failure mode, and under How it ships as the check on what the built artifacts actually contain.
The distributions built by the test suite are now built for the interpreter running it. uv build was invoked without --python, so it targeted the newest interpreter on the machine, while tests/test_integration.py creates its throwaway venv from sys.executable: on a checkout whose .venv is older than the newest installed Python, make testint produced a cp314 wheel and failed with pip's "not a supported wheel on this platform". Every tox environment offers a single interpreter, so the two agreed by accident in CI and the mismatch only ever hit developer machines, where the workaround was to pin UV_PYTHON. test_build_commands_pin_the_running_interpreter keeps the pin in place; it needs no build, so it fails in make test rather than waiting on a CI environment that cannot reproduce the mismatch.
Two tests no longer leak numpy's global error state into whatever pytest collects next. np.seterr and the warning filters are process-global, and test_overflow (tests/main_test.py) plus test_inside_polygon (tests/utils_test.py, six parametrisations) each set them and never restored them - so every later test in the same process ran with under promoted from ignore to warn, and which of the two modules pytest collected first decided the state the other ran under. The filters were undone only incidentally, by pytest's per-test catch_warnings(), not by the tests themselves. benchmarks/conftest.py already had the correct pattern; it now lives in tests/auxiliaries.py as the strict_numpy_errors context manager plus a thin strict_numpy_warnings fixture, re-exported through the conftest of each suite, and both call sites request it. The context manager form is what makes the restore directly testable - a leaked global otherwise surfaces only as an unrelated later failure that depends on collection order, which is the hardest kind to attribute.
The zone id invariants in scripts/timezone_data.py are each enforced in exactly one place, and now have tests. ZoneCollection.validate_structure and zone_positions each walked poly_zone_ids element by element checking it was non-decreasing and each raised the same message built from its own locals; the scan moves into one _validate_non_decreasing helper and zone_positions drops its copy, which could only ever have fired if a caller mutated the array in place - the validator runs at construction and nothing writes to it afterwards. A if min_zone_id < 0 branch is deleted as unreachable: the same method rejects any non-unsigned dtype a dozen lines earlier, so it read as the guard against negative zone ids while being incapable of firing. The class had no tests at all, so what it actually promises - the unsigned-dtype rejection that makes a negative id unrepresentable, the ordering and maximum-id rules, and the shape zone_positions returns - is now pinned by tests/timezone_data_test.py.
The seven out-of-range coordinates - one representable step outside the valid WGS84 range, per axis and at every corner - are declared once in tests/locations.py instead of verbatim in both tests/main_test.py and tests/utils_test.py, where only one copy carried the comment explaining what makes them interesting and adding a corner to it left the other testing a smaller set.
The shortcut compilation chain in scripts/shortcuts.py is annotated for what it is actually passed. Both annotations were the wrong way round: check_shortcut_sorting declared np.ndarray and only ever receives the list[int] that optimise_shortcut_ordering returns, and it hands the np.ndarray it derives to has_coherent_sequences(lst: list[int]). Widened rather than swapped, since tests/shortcut_test.py calls the latter with real lists.
The supported Python versions are declared in five places that cannot read each other - requires-python and one classifier per minor version in pyproject.toml, the py{...} factors of tox.ini's envlist, the test matrix and CIBW_BUILD_VERSIONS in build.yml, and py_limited_api in setup.py - and two "must match" comments said so while nothing enforced them. tests/test_python_version_support.py fails when they drift, in either of the two directions that fail silently: a classifier added without a matrix entry ships a version the package claims to support and CI never runs, and a requires-python raised without moving the abi3 base builds wheels tagged for an interpreter that is no longer supported. Each assertion was checked against the specific one-sided edit it targets, and both comments now name the test.
The data report generator states figures it derives rather than ones it restates, and its annotations describe what it returns. calculate_shortcut_index_stats took the number of H3 cells existing at the shortcut resolution from a ladder of literals covering resolutions 0 to 4 and fell through, for anything else, to the number of cells actually stored - which reports coverage of exactly 100 % instead of failing - behind an except ImportError that cannot fire, since h3 is a runtime dependency rather than an optional one. It asks h3.get_num_cells, which returns precisely the numbers that were tabulated. Running mypy over scripts/reporting.py, which the pre-commit hook excludes, found seventeen further disagreements between the module and its own signatures: the statistics bag was typed as holding scalars while returning two distributions, load_binary_data's nine-key result was a bare dict indexed by string literal, the table renderer declared string rows while stringifying whatever it is handed, main was annotated None while returning exit codes to exit(), and print_polygon_distribution_table documented a return value it never produced while its one caller discarded it. The two dict results are now TypedDict\ s in scripts/configs.py, carrying tests that assert their keys against what is really returned, since CI cannot type-check scripts/. The polygon count that labels a distribution row is no longer formatted into that label and parsed back out of it to key the example lookup. docs/data_report.rst and the benchmark reports regenerate byte-identically throughout.
Removed five definitions nothing referenced - three JSON/pickle helpers in scripts/utils.py and the import pickle they kept alive, the i8 dtype shim in timezonefinder/_numba_replacements.py that the no-numba fallback never imports, and a test helper self-documented as kept for future reference - and a guard in scripts/hex_utils.py that could not fire. Hex.poly_candidates re-read its cache after initialising it and returned an empty set if it were still unset, which no path through _init_candidates leaves it: an empty set there means "no candidate polygons", so a converter bug would have surfaced as silently missing shortcuts rather than as a failure. The property had no direct test, being reached only through shortcut generation, and now has one. _memory_mode_label looks its two labels up in PARAM_LABELS instead of spelling them out, so renaming the display vocabulary can no longer leave the comparison bullets and the tables above them disagreeing.
make parse and make testparse run again. Both invoked scripts/file_converter.py by path, which puts scripts/ on sys.path[0] instead of the repository root, so the converter's own from scripts.timezone_data import ... raised ModuleNotFoundError before any work started - a total failure that CI never sees, since it runs neither target. make testparse is the only cheap end-to-end exercise of the converter (update_data.sh needs a ~55 MB download), and nothing under tests/ covers parse_data(), so while it was broken the converter had no smoke test at all. The invocation documented in the usage docs had the same defect and is now the python -m scripts.file_converter form that update_data.sh already used; tests/test_script_invocations.py fails if a by-path invocation returns. Note that parse_data() writes its report to the checkout's committed docs/data_report.rst whatever -out it is given, so make testparse leaves that file describing the three-zone fixture - the target now says so.
scripts/ is type-checked by the mypy pre-commit hook instead of being excluded from it. The directory holds the data converter and the benchmark tooling - most of the repository's non-library Python - and with nothing running mypy over it the annotations had drifted to fifteen errors: two # type: ignore codes mypy no longer emits, so the ignore silenced nothing; two implicit Optional defaults that no_implicit_optional = true was already configured to reject; a dict annotated with a narrower value type than it is assigned; a bucket key and four bounding-box lists annotated int while Boundaries declares float; and two missing variable annotations. All fixed as annotations, with no runtime change. Two of the four errors mypy reported in tests/auxiliaries.py, which it reaches by following imports out of scripts/, are fixed alongside. test_scripts_are_type_checked_by_the_hook guards the exclude, which is a quieter way to stop type-checking a directory than the ignore_errors list the neighbouring tests already cover: it takes no override entry and reports nothing.
The eight __del__ cleanup tests that differed only in which exception cleanup() raised, and whether zero or one ResourceWarning was expected, are two parametrized tests over the suppressed and warned exception tuples. Each previously repeated the same subclass, the same catch_warnings block and the same filter, so adding a ninth exception to __del__'s suppression list meant copying the block a ninth time and a copy asserting the wrong count would be invisible. Coverage rises rather than falls: the hand-rolled loop asserting that __del__ never raises to user code now runs over all six exception types instead of four.
Three leftovers in the converter that read as bugs are gone: has_coherent_sequences built an iterator solely to take its first element and then looped from the start anyway (correct, but it reads as an off-by-one), compile_bboxes unpacked a pair and immediately reassigned half of it, and process_single_hex returned the hex_id it was handed so its only caller reassigned the loop variable to itself. Two shadowed builtins (dir as a loop variable, id as a parameter) are renamed and three bare generator signatures annotated. The benchmark renderer classifies its "other" group by name suffix, as the two lines above it do, rather than by deep-equality scan over lists of dicts; and the check-manifest ignore list drops two entries naming files that do not exist (CONTRIBUTING.rst, publish.py). Every converter change was verified by parsing tests/test_input.json before and after and comparing the outputs byte for byte.

Configuration

📅 Schedule: (in timezone America/New_York)

Branch creation
- "before 6am on monday"
Automerge
- At any time (no schedule defined)

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

If you want to rebase/retry this PR, check this box

This PR has been generated by Mend Renovate.

This PR contains the following updates: | Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | |---|---|---|---| | [timezonefinder](https://github.com/jannikmi/timezonefinder) | `==8.2.5` → `==9.2.0` | ![age](https://developer.mend.io/api/mc/badges/age/pypi/timezonefinder/9.2.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/pypi/timezonefinder/8.2.5/9.2.0?slim=true) | --- ### Release Notes <details> <summary>jannikmi/timezonefinder (timezonefinder)</summary> ### [`v9.2.0`](https://github.com/jannikmi/timezonefinder/blob/HEAD/CHANGELOG.rst#920-2026-10-22) [Compare Source](https://github.com/jannikmi/timezonefinder/compare/9.1.0...9.2.0) Changed: - On x86\_64 Linux, free-threaded CPython 3.15 and later installs a prebuilt wheel with the C extension, built against the free-threaded stable ABI (`abi3t`), instead of compiling from the sdist, and GIL builds of 3.15 and later install that same wheel. It needs an installer that knows the `abi3t` tag, such as a current pip or uv; older installers, other platforms and free-threaded 3.14 build from the sdist as before. - Python 3.15 is supported and tested. Python 3.12 remains supported until its NEP 29 drop date, 2027-04-02. Documentation: - The `comparison to pytzwhere <https://timezonefinder.readthedocs.io/en/latest/alternatives.html#comparison-to-pytzwhere>`\_\_ is shorter and now also compares batch throughput, one `timezone_names_at()` call against the per-point loop that is all `pytzwhere` offers, and says why the pure-Python fallback answers many points more slowly than `pytzwhere`. - The README and the About page gain a *Used by* section naming well-known dependents, and the repository carries a `CITATION.cff`, so GitHub offers a citation for it. Internal: - The `pyXY-pytz` tox envs run the test suite once, with `pytz` installed, rather than also repeating the plain `pyXY` run. - A push to a `release/**` branch now commits the benchmark pages rendered for it, and a merged release pull request is tagged by CI once its `master` build is green, so neither is installed or pushed by hand. - ruff is raised to 0.17, with the pre-commit hook at the same version; the explicitly selected rule set reports nothing new and nothing is reformatted. - CI runs the `slow` tox env in a 3.14 job of its own, in parallel with the rest of the matrix, instead of after the other 3.14 envs. ### [`v9.1.0`](https://github.com/jannikmi/timezonefinder/blob/HEAD/CHANGELOG.rst#910-2026-10-20) [Compare Source](https://github.com/jannikmi/timezonefinder/compare/9.0.0...9.1.0) New features: - `timezone_id_at()` and `timezone_id_at_land()`, available on both finder classes and as global functions, return the numeric id of the same zone named by their existing scalar counterparts. They return `None` where the name lookup does; numeric zone ids remain local to the loaded dataset and must not be persisted without its version. - `timezones_at()`, as a `TimezoneFinder` method and a global function, returns every timezone whose polygons contain a point instead of the single one `timezone_at()` has to pick where the dataset's zones genuinely overlap - `Asia/Urumqi` inside `Asia/Shanghai`, and several disputed or dual-administered areas. The list always contains `timezone_at()`'s answer, which is what stops the two contradicting each other, and that answer is always the first element, so `zones[0]` is a drop-in for `timezone_at()`; the order of the rest is the internal candidate order and carries no meaning. There is no batch form. Changed: - Dropped support for Python 3.11, which passed its drop date under the NumPy/Scientific-Python support schedule this project follows; the package now requires Python 3.12 or newer and its abi3 wheels are built against the `cp312` stable ABI. - Raised the minimum required NumPy version to 2.2, the oldest release still supported by the schedule this project follows (2.0 and 2.1 passed their drop dates in June and August 2026). - The shortcut index is a longitude/latitude-aligned grid tree rather than an H3 hexagon grid: 0.75° cells, each refining into a 4×4 block of 0.1875° cells where several zones meet. The cell is two integer divisions per level rather than a library call, so it vectorises over a batch, and the cells are exact in the coordinate frame the point-in-polygon kernel reads, so a zone whose polygons only reach across a cell edge is no longer a candidate inside it. The published benchmark and data reports carry what the change measures in speed, memory and disk. `TimezoneFinder` answers are essentially unchanged: 2,000,000 area-weighted random points answer exactly as before, and over all 4,113,237 distinct stored boundary vertices off the −180 meridian and the −90 parallel, whose reading changes separately, 19 answers move. Those 19 are the two cases where candidate order decides rather than geometry, and the order is per cell: 18 are points inside no polygon at all - slivers on the 7.5° meridians where the ocean zones meet, where `timezone_at()` returns the final candidate untested and never promised otherwise - and one is a point inside both `Australia/Brisbane` and `Etc/GMT-9`, where the first containing candidate wins and both answers are equally truthful. `TimezoneFinderL` is an approximation *by cell*, so its answers move wherever a cell does. This is a binary format change: `DATA_FORMAT_VERSION` is 4, and `timezonefinder` now requires `timezonefinder-data>=4.2026.5,<5`. - The compiled C extension is now the point-in-polygon implementation wherever it loaded, and the optional `numba` extra is the fallback for an installation that has none, the ordering `the acceleration path comparison <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_acceleration_paths.html>`\_\_ measures. **Numba is no longer imported at all where the extension answers queries**: `timezonefinder.utils` imports `timezonefinder.utils_numba` only in the branch a missing extension takes, since that import is what compiles it, so an installation carrying both no longer imports or compiles a JIT kernel it does not run. The coordinate converters that module used to supply (`int2coord`, `convert2coords`, `convert2coord_pairs`) are NumPy implementations in `timezonefinder.utils` now, returning exactly what they returned before. `TimezoneFinder.using_numba()` consequently reports whether the JIT kernel is what a lookup *runs*, which is `False` on an installation whose extension loaded however Numba is installed; `TimezoneFinder.using_clang_pip()` is unchanged, and the two are mutually exclusive again. - The package now declares the `Programming Language :: Python :: Free Threading :: 3 - Stable` classifier: lookups are supported and tested on free-threaded CPython builds, where the GIL stays disabled. Wheels for free-threaded interpreters are not published yet, so those installs build from the sdist. - `h3` is no longer a runtime dependency and is not installed with the package: the grid-tree shortcut index replaced the H3 index it was there for. An `import h3` that happened to work because `timezonefinder` pulled it in now fails unless `h3` is declared directly. Dropping it also removes the one extension in the install that shipped without `Py_mod_gil`, so on a free-threaded build the GIL now stays disabled. - A lookup now reads `lng=-180.0` as `lng=180.0`, the same meridian, and `lat=-90.0` as the point one stored unit (\~1.1 cm) north of the South Pole, so a point on either line answers the same zone whichever way it is spelled. As spelled, no polygon owns such a point: the point-in-polygon test gives a point on a boundary to the polygon west of it, or south of it along an east-west edge, and nothing lies west of -180° or south of -90°. So `certain_timezone_at()` returned `None` on both lines, and on the -180° meridian `timezone_at()`, `timezones_at()` and the batch lookups answered the last zone the shortcut index lists for the cell without testing it, which in places owned neither side of the meridian; they now answer what they answer at `lng=180.0`. `TimezoneFinderL` answers do not change. - Where two zones' polygons overlap, `timezone_at()` now answers the zone with the smaller spherical area - the one enclaved in the other - in every cell of the shortcut index, with the timezone identifier breaking an exact tie. Before, the pick in an overlap followed the zones' vertex counts within each index cell, a property of the index rather than of the zones that a data update could flip. `timezones_at()` still returns both zones, now with the smaller one first. With `timezonefinder-data` 4.2026.5 (upstream 2026e) and compared with 3.2026.4, eight overlaps change answer, each as a whole region: Kafia Kingi and Abyei from `Africa/Khartoum` to `Africa/Juba`, the West Bank overlap from `Asia/Jerusalem` to `Asia/Hebron`, the Southern Patagonian Ice Field from `America/Punta_Arenas` to `America/Argentina/Rio_Gallegos`, the Croatia-Serbia Danube border from `Europe/Belgrade` to `Europe/Zagreb`, the Bay of Piran from `Europe/Zagreb` to `Europe/Ljubljana`, a strip of the Strait of Juan de Fuca from `America/Los_Angeles` to `America/Vancouver`, and slivers of the Sint Maarten border from `America/Marigot` to `America/Lower_Princes` and of the Nova Scotia-New Brunswick border from `America/Halifax` to `America/Moncton`. Upstream 2026e also adds an overlap, a strip of sea off the Cerbère-Portbou coast that both `Europe/Paris` and `Europe/Madrid` now cover, which answers `Europe/Madrid`. The other overlaps, among them `Asia/Urumqi` inside `Asia/Shanghai` and `Asia/Tbilisi` over `Europe/Moscow`, keep their answer. `TimezoneFinderL` answers a multi-zone cell with the zone the full lookup tests last, which wherever the converter keeps this order is now the largest of the cell's zones, so its answer moves beyond the overlaps, mostly in coastal cells beside an ocean zone: measured on the 2026d boundaries, at 499 of the 1,843,200 centres of the index's smallest cells, where `TimezoneFinder` moves at 75, all inside the overlaps above. Documentation: - The `acceleration path comparison <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_acceleration_paths.html>`\_\_ now opens with which path measured fastest, and states every pairing - in its headlines and in its tables' result column - as "X is N times faster than Y" with the faster path as the subject, instead of a multiple of the C extension that had to be read backwards; the README no longer calls Numba the preferred backend, since it is used only where the C extension is unavailable. - The `package comparison <https://timezonefinder.readthedocs.io/en/latest/alternatives.html>`\_\_ treats `tzfpy`'s experimental full-precision variant as a genuine alternative, states which remaining distribution and API differences distinguish `timezonefinder`, and limits its benchmark conclusions to the simplified PyPI build it actually measured. - New page `When batched lookups pay <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_batch_break_even.html>`\_\_: the batch API amortises validation, coordinate scaling and the shortcut table read over a whole batch, so a small batch is *slower* per point than a loop of scalar calls and a large one stops improving - the page measures where each of those happens, as a sweep of paired comparisons over a ladder of batch sizes from 10 to 100,000 points that runs past where batching stops improving, so that point is measured rather than off the end of the ladder, and says where a still larger batch gets slower per point again. Both answers depend on the caller's coordinates as much as on their hardware, because points sharing a shortcut cell are answered together, so `scripts/measure_batch_break_even.py` (`make batch-break-even`) takes `--points your.csv` and reports the same two numbers for your own workload. - Getting Started has a new "Upgrading and pinning" section: pin both `timezonefinder` and `timezonefinder-data`, record both versions with stored results, and recompute stored zones when either changes. - The `acceleration path comparison <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_acceleration_paths.html>`\_\_ now also measures what installing the optional `numba` extra costs a process *before* any query - resident memory and time from a cold process to its first answer, in both environments, with the difference stated as the price of the extra - because speed was the only consequence the page priced and it is not the one a container memory limit or a cold-start budget is spent against. The README, `getting started <https://timezonefinder.readthedocs.io/en/latest/0_getting_started.html>`\_\_, the performance page and the architecture page say so where they offer the extra, and the architecture page no longer claims the JIT compiles on first use: the signatures are eager, so a finder's construction pays the compilation. - The `comparison to pytzwhere <https://timezonefinder.readthedocs.io/en/latest/alternatives.html#comparison-to-pytzwhere>`\_\_ now reports a side-by-side re-measurement against its last release: memory, startup and query speed, coverage, crashes near the poles, NumPy compatibility, and disk size. - The README is written in Markdown, which is what the PyPI project page now renders; its text, links and badges are unchanged. - New page `Result stability and reproducibility <https://timezonefinder.readthedocs.io/en/latest/result_stability.html>`\_\_: a lookup is a pure function of the coordinates and the installed data, which leaves two axes that can still move an answer. A `timezonefinder-data` update can change it through boundary geometry, polygon precedence where polygons overlap, or shortcut composition and ordering; a code release can change it through a bug fix, a documented semantic change, or an optimization of the query logic - 9.0.0's candidate reordering changed what `TimezoneFinderL` returns in a multi-zone cell. A point strictly inside exactly one polygon is decided by geometry alone and none of it reaches that point. `timezonefinder-data` versions read `<format>.<year>.<letter>[.postN]` and are not semantic versions: no data bump promises unchanged answers, dataset changes reach an unpinned install without a code release, and the code changelog does not record them. Pinning the data freezes the artefacts and pinning the code freezes the rules that read them, so reproducibility across deployments needs both. - The thread-safety documentation now says one thing: concurrent lookups through the global functions or on a shared `TimezoneFinder` are safe, and one instance per thread is recommended for parallel throughput rather than for correctness. - The tzfpy comparison page is renamed `Speed and startup against tzfpy <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_vs_tzfpy.html>`\_\_ and adds a *Bulk lookups* table: the same points answered by one `timezone_names_at()` call against a loop of tzfpy calls, since tzfpy has no batch API. - The notes on `certain_timezone_at()` and `timezones_at()` and the certainty-probe paragraph of the alternatives page now say where no polygon contains a point with the packaged data: in slivers the stored boundaries of neighbouring zones leave between them. A point on a border two zones share goes to one of them, and `lng=180.0` and `lat=90.0` are owned like any other edge. - New design page `Why timezonefinder doesn't simplify polygons <https://timezonefinder.readthedocs.io/en/latest/why_no_simplification.html>`\_\_: why simplification concentrates error at the borders a lookup can get wrong, how it would break shared borders and hole deduplication, which lossless mechanisms deliver its benefits instead, the options considered, and the conditions that would reopen the decision. Internal: - The abi3 wheel claim in `setup.py` is now withheld on free-threaded interpreters, so a free-threaded wheel build no longer fails on a `py_limited_api` setting that setuptools refuses there. - `make shortcut-calibration` fits the shortcut-ordering costs from counted predicate stages, re-orders every ambiguous cell with the fitted and an area-only model, and A/B-times whole lookups on the cells that change; `make shortcut-calibration-record` keeps a reviewed run in `benchmarks/shortcut_ordering_model.json`. The production coefficients are unchanged: re-calibrated on the aligned grid tree, the fitted order is not shown to be better, and the recorded run's decision line says why. - The payload calibration table the data-update guard's bands are checked against is no longer required to end at the packaged release, so a data update owes it no hand-written row; a format-generation assertion replaces that requirement and fails only when a layout change makes the recorded byte counts incomparable. - The data converter now reaches its boundary and hole rings through one collection object each, named and accessed as the runtime names the same two collections (`boundaries`/`holes` with `coords_of`, `nr_vertices`, `bounds_of`, `ids_of` and `holes_of`), instead of indexing parallel per-polygon lists that callers had to keep in step by hand. - The automated data-update workflows now check that the `DATA_UPDATER_GH_APP_ID` and `DATA_UPDATER_GH_PRIVATE_KEY` secrets are both set before minting a token, and the fallback issue the weekly check opens names an unconfigured GitHub App as the cause instead of asking for the data to be regenerated by hand. - The automated data-release workflow now brings an update pull request onto current `master` itself when branch protection has left it behind, instead of waiting for someone to press "Update branch" on a finished release. - The automated data-update pull request now states that it merges and publishes itself once CI passes, and how to withhold the release, instead of leaving a reviewer to infer whether it is waiting on them. - The weekly data update now stages the acceleration-paths, batch-break-even and reduced-zone-mapping files its own regeneration writes, and a test holds that staging list against the generated-file constants so a newly added report page fails there rather than after a full regeneration. - The data converter orders shortcut candidates deterministically: zones of exactly equal spherical area are ordered by timezone identifier and equal polygons within a zone by polygon id, so compiling one boundary release twice yields byte-identical shortcut indexes. `timezonefinder-data` 4.2026.5 is compiled with this order. - A `free-threaded` tox env, run in CI, now tests the package on a free-threaded interpreter. - Changelog fragment previews and release assembly generate the pending section on demand, so `CHANGELOG.rst` contains only released history between releases. - The converter's rule for a cell's candidate polygons is tight rather than conservative, and rests on a planar predicate rather than on evidence that cannot establish an exclusion. A cell is an axis-aligned rectangle of the stored integer coordinates, so "can this polygon own one of the cell's points" is a question about two rectangles and a ring, evaluated against the point-in-polygon kernel's own edge convention: `scripts/grid_cells.py` holds it. It never omits a polygon the kernel can place a cell's point inside, and over-includes only one whose interior enters the cell without reaching any of its integer points - a sliver under \~1.1 cm, costing that cell one bounding-box rejection. `tests/grid_cells_test.py` holds the rule to the kernel over randomised polygons, and `scripts/audit_shortcut_candidates.py` probes every stored cell's four corners and four edge midpoints on each compiled dataset. - Reporting now starts from a form: a bug report that asks for the failing coordinates and for the output of one command reporting the installed versions and which point-in-polygon backend the installation actually uses, or a feature request, with links routing usage questions to Discussions and misplaced boundaries upstream to `timezone-boundary-builder`. - Tests pin which polygon owns a point exactly on its boundary - the one whose interior lies immediately west of the point, or immediately south of it along an east-west edge - on every point-in-polygon kernel, compiled and interpreted, packed and unpacked, and through the whole lookup on the borders the ocean zones share. The point-in-polygon cases `tests/utils_test.py` had left commented out as undefined are now asserted. - Prevent code-release workflows from silently skipping the PyPI upload after their tag-side test job is intentionally skipped. - Add a guarded trusted-publishing recovery command that downloads and validates an existing code tag's GitHub Release assets before uploading them to PyPI. - The committed `tzfpy` agreement chart is rendered with the same deterministic Matplotlib SVG conventions as the other report charts, while remaining byte-for-byte reproducible from its stored measurement. - The Linux wheel job retries pulls of its pinned manylinux and musllinux build images before cibuildwheel starts, so transient container-registry failures do not invalidate an otherwise successful wheel build. - The shortcut index now maps a coordinate to its cell itself (`ShortcutIndex.entry_at` and `entries_at`): the lookup methods, the benchmark fixture generator and the tests that resolve a point hand it a longitude and latitude instead of computing an H3 cell id of their own, and the shortcut-ordering calibration's stand-in index answers the same question, so replacing the index's cells needs no change to `timezonefinder.py`. - The candidate-ordering guarantee is now asserted against the real lookup: permuting a multi-zone cell's candidates within one zone cannot move a `TimezoneFinder` answer, a point contained by a single zone's candidates survives any permutation at all, a cross-zone rotation does move answers (so those two assert something), `TimezoneFinderL` answers the final candidate's zone, and the converter's geometric safety gate refuses pole and antimeridian cells before reading any geometry. - CI now runs the test suite against the oldest NumPy release the published `numpy>=2.2` requirement allows (2.2.0 on Python 3.12) via the new `py312-min` tox environment, so the declared lower bound is exercised instead of assumed. ### [`v9.0.0`](https://github.com/jannikmi/timezonefinder/blob/HEAD/CHANGELOG.rst#910-2026-10-20) [Compare Source](https://github.com/jannikmi/timezonefinder/compare/8.3.0...9.0.0) New features: - `timezone_id_at()` and `timezone_id_at_land()`, available on both finder classes and as global functions, return the numeric id of the same zone named by their existing scalar counterparts. They return `None` where the name lookup does; numeric zone ids remain local to the loaded dataset and must not be persisted without its version. - `timezones_at()`, as a `TimezoneFinder` method and a global function, returns every timezone whose polygons contain a point instead of the single one `timezone_at()` has to pick where the dataset's zones genuinely overlap - `Asia/Urumqi` inside `Asia/Shanghai`, and several disputed or dual-administered areas. The list always contains `timezone_at()`'s answer, which is what stops the two contradicting each other, and that answer is always the first element, so `zones[0]` is a drop-in for `timezone_at()`; the order of the rest is the internal candidate order and carries no meaning. There is no batch form. Changed: - Dropped support for Python 3.11, which passed its drop date under the NumPy/Scientific-Python support schedule this project follows; the package now requires Python 3.12 or newer and its abi3 wheels are built against the `cp312` stable ABI. - Raised the minimum required NumPy version to 2.2, the oldest release still supported by the schedule this project follows (2.0 and 2.1 passed their drop dates in June and August 2026). - The shortcut index is a longitude/latitude-aligned grid tree rather than an H3 hexagon grid: 0.75° cells, each refining into a 4×4 block of 0.1875° cells where several zones meet. The cell is two integer divisions per level rather than a library call, so it vectorises over a batch, and the cells are exact in the coordinate frame the point-in-polygon kernel reads, so a zone whose polygons only reach across a cell edge is no longer a candidate inside it. The published benchmark and data reports carry what the change measures in speed, memory and disk. `TimezoneFinder` answers are essentially unchanged: 2,000,000 area-weighted random points answer exactly as before, and over all 4,113,237 distinct stored boundary vertices off the −180 meridian and the −90 parallel, whose reading changes separately, 19 answers move. Those 19 are the two cases where candidate order decides rather than geometry, and the order is per cell: 18 are points inside no polygon at all - slivers on the 7.5° meridians where the ocean zones meet, where `timezone_at()` returns the final candidate untested and never promised otherwise - and one is a point inside both `Australia/Brisbane` and `Etc/GMT-9`, where the first containing candidate wins and both answers are equally truthful. `TimezoneFinderL` is an approximation *by cell*, so its answers move wherever a cell does. This is a binary format change: `DATA_FORMAT_VERSION` is 4, and `timezonefinder` now requires `timezonefinder-data>=4.2026.5,<5`. - The compiled C extension is now the point-in-polygon implementation wherever it loaded, and the optional `numba` extra is the fallback for an installation that has none, the ordering `the acceleration path comparison <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_acceleration_paths.html>`\_\_ measures. **Numba is no longer imported at all where the extension answers queries**: `timezonefinder.utils` imports `timezonefinder.utils_numba` only in the branch a missing extension takes, since that import is what compiles it, so an installation carrying both no longer imports or compiles a JIT kernel it does not run. The coordinate converters that module used to supply (`int2coord`, `convert2coords`, `convert2coord_pairs`) are NumPy implementations in `timezonefinder.utils` now, returning exactly what they returned before. `TimezoneFinder.using_numba()` consequently reports whether the JIT kernel is what a lookup *runs*, which is `False` on an installation whose extension loaded however Numba is installed; `TimezoneFinder.using_clang_pip()` is unchanged, and the two are mutually exclusive again. - The package now declares the `Programming Language :: Python :: Free Threading :: 3 - Stable` classifier: lookups are supported and tested on free-threaded CPython builds, where the GIL stays disabled. Wheels for free-threaded interpreters are not published yet, so those installs build from the sdist. - `h3` is no longer a runtime dependency and is not installed with the package: the grid-tree shortcut index replaced the H3 index it was there for. An `import h3` that happened to work because `timezonefinder` pulled it in now fails unless `h3` is declared directly. Dropping it also removes the one extension in the install that shipped without `Py_mod_gil`, so on a free-threaded build the GIL now stays disabled. - A lookup now reads `lng=-180.0` as `lng=180.0`, the same meridian, and `lat=-90.0` as the point one stored unit (\~1.1 cm) north of the South Pole, so a point on either line answers the same zone whichever way it is spelled. As spelled, no polygon owns such a point: the point-in-polygon test gives a point on a boundary to the polygon west of it, or south of it along an east-west edge, and nothing lies west of -180° or south of -90°. So `certain_timezone_at()` returned `None` on both lines, and on the -180° meridian `timezone_at()`, `timezones_at()` and the batch lookups answered the last zone the shortcut index lists for the cell without testing it, which in places owned neither side of the meridian; they now answer what they answer at `lng=180.0`. `TimezoneFinderL` answers do not change. - Where two zones' polygons overlap, `timezone_at()` now answers the zone with the smaller spherical area - the one enclaved in the other - in every cell of the shortcut index, with the timezone identifier breaking an exact tie. Before, the pick in an overlap followed the zones' vertex counts within each index cell, a property of the index rather than of the zones that a data update could flip. `timezones_at()` still returns both zones, now with the smaller one first. With `timezonefinder-data` 4.2026.5 (upstream 2026e) and compared with 3.2026.4, eight overlaps change answer, each as a whole region: Kafia Kingi and Abyei from `Africa/Khartoum` to `Africa/Juba`, the West Bank overlap from `Asia/Jerusalem` to `Asia/Hebron`, the Southern Patagonian Ice Field from `America/Punta_Arenas` to `America/Argentina/Rio_Gallegos`, the Croatia-Serbia Danube border from `Europe/Belgrade` to `Europe/Zagreb`, the Bay of Piran from `Europe/Zagreb` to `Europe/Ljubljana`, a strip of the Strait of Juan de Fuca from `America/Los_Angeles` to `America/Vancouver`, and slivers of the Sint Maarten border from `America/Marigot` to `America/Lower_Princes` and of the Nova Scotia-New Brunswick border from `America/Halifax` to `America/Moncton`. Upstream 2026e also adds an overlap, a strip of sea off the Cerbère-Portbou coast that both `Europe/Paris` and `Europe/Madrid` now cover, which answers `Europe/Madrid`. The other overlaps, among them `Asia/Urumqi` inside `Asia/Shanghai` and `Asia/Tbilisi` over `Europe/Moscow`, keep their answer. `TimezoneFinderL` answers a multi-zone cell with the zone the full lookup tests last, which wherever the converter keeps this order is now the largest of the cell's zones, so its answer moves beyond the overlaps, mostly in coastal cells beside an ocean zone: measured on the 2026d boundaries, at 499 of the 1,843,200 centres of the index's smallest cells, where `TimezoneFinder` moves at 75, all inside the overlaps above. Documentation: - The `acceleration path comparison <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_acceleration_paths.html>`\_\_ now opens with which path measured fastest, and states every pairing - in its headlines and in its tables' result column - as "X is N times faster than Y" with the faster path as the subject, instead of a multiple of the C extension that had to be read backwards; the README no longer calls Numba the preferred backend, since it is used only where the C extension is unavailable. - The `package comparison <https://timezonefinder.readthedocs.io/en/latest/alternatives.html>`\_\_ treats `tzfpy`'s experimental full-precision variant as a genuine alternative, states which remaining distribution and API differences distinguish `timezonefinder`, and limits its benchmark conclusions to the simplified PyPI build it actually measured. - New page `When batched lookups pay <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_batch_break_even.html>`\_\_: the batch API amortises validation, coordinate scaling and the shortcut table read over a whole batch, so a small batch is *slower* per point than a loop of scalar calls and a large one stops improving - the page measures where each of those happens, as a sweep of paired comparisons over a ladder of batch sizes from 10 to 100,000 points that runs past where batching stops improving, so that point is measured rather than off the end of the ladder, and says where a still larger batch gets slower per point again. Both answers depend on the caller's coordinates as much as on their hardware, because points sharing a shortcut cell are answered together, so `scripts/measure_batch_break_even.py` (`make batch-break-even`) takes `--points your.csv` and reports the same two numbers for your own workload. - Getting Started has a new "Upgrading and pinning" section: pin both `timezonefinder` and `timezonefinder-data`, record both versions with stored results, and recompute stored zones when either changes. - The `acceleration path comparison <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_acceleration_paths.html>`\_\_ now also measures what installing the optional `numba` extra costs a process *before* any query - resident memory and time from a cold process to its first answer, in both environments, with the difference stated as the price of the extra - because speed was the only consequence the page priced and it is not the one a container memory limit or a cold-start budget is spent against. The README, `getting started <https://timezonefinder.readthedocs.io/en/latest/0_getting_started.html>`\_\_, the performance page and the architecture page say so where they offer the extra, and the architecture page no longer claims the JIT compiles on first use: the signatures are eager, so a finder's construction pays the compilation. - The `comparison to pytzwhere <https://timezonefinder.readthedocs.io/en/latest/alternatives.html#comparison-to-pytzwhere>`\_\_ now reports a side-by-side re-measurement against its last release: memory, startup and query speed, coverage, crashes near the poles, NumPy compatibility, and disk size. - The README is written in Markdown, which is what the PyPI project page now renders; its text, links and badges are unchanged. - New page `Result stability and reproducibility <https://timezonefinder.readthedocs.io/en/latest/result_stability.html>`\_\_: a lookup is a pure function of the coordinates and the installed data, which leaves two axes that can still move an answer. A `timezonefinder-data` update can change it through boundary geometry, polygon precedence where polygons overlap, or shortcut composition and ordering; a code release can change it through a bug fix, a documented semantic change, or an optimization of the query logic - 9.0.0's candidate reordering changed what `TimezoneFinderL` returns in a multi-zone cell. A point strictly inside exactly one polygon is decided by geometry alone and none of it reaches that point. `timezonefinder-data` versions read `<format>.<year>.<letter>[.postN]` and are not semantic versions: no data bump promises unchanged answers, dataset changes reach an unpinned install without a code release, and the code changelog does not record them. Pinning the data freezes the artefacts and pinning the code freezes the rules that read them, so reproducibility across deployments needs both. - The thread-safety documentation now says one thing: concurrent lookups through the global functions or on a shared `TimezoneFinder` are safe, and one instance per thread is recommended for parallel throughput rather than for correctness. - The tzfpy comparison page is renamed `Speed and startup against tzfpy <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_vs_tzfpy.html>`\_\_ and adds a *Bulk lookups* table: the same points answered by one `timezone_names_at()` call against a loop of tzfpy calls, since tzfpy has no batch API. - The notes on `certain_timezone_at()` and `timezones_at()` and the certainty-probe paragraph of the alternatives page now say where no polygon contains a point with the packaged data: in slivers the stored boundaries of neighbouring zones leave between them. A point on a border two zones share goes to one of them, and `lng=180.0` and `lat=90.0` are owned like any other edge. - New design page `Why timezonefinder doesn't simplify polygons <https://timezonefinder.readthedocs.io/en/latest/why_no_simplification.html>`\_\_: why simplification concentrates error at the borders a lookup can get wrong, how it would break shared borders and hole deduplication, which lossless mechanisms deliver its benefits instead, the options considered, and the conditions that would reopen the decision. Internal: - The abi3 wheel claim in `setup.py` is now withheld on free-threaded interpreters, so a free-threaded wheel build no longer fails on a `py_limited_api` setting that setuptools refuses there. - `make shortcut-calibration` fits the shortcut-ordering costs from counted predicate stages, re-orders every ambiguous cell with the fitted and an area-only model, and A/B-times whole lookups on the cells that change; `make shortcut-calibration-record` keeps a reviewed run in `benchmarks/shortcut_ordering_model.json`. The production coefficients are unchanged: re-calibrated on the aligned grid tree, the fitted order is not shown to be better, and the recorded run's decision line says why. - The payload calibration table the data-update guard's bands are checked against is no longer required to end at the packaged release, so a data update owes it no hand-written row; a format-generation assertion replaces that requirement and fails only when a layout change makes the recorded byte counts incomparable. - The data converter now reaches its boundary and hole rings through one collection object each, named and accessed as the runtime names the same two collections (`boundaries`/`holes` with `coords_of`, `nr_vertices`, `bounds_of`, `ids_of` and `holes_of`), instead of indexing parallel per-polygon lists that callers had to keep in step by hand. - The automated data-update workflows now check that the `DATA_UPDATER_GH_APP_ID` and `DATA_UPDATER_GH_PRIVATE_KEY` secrets are both set before minting a token, and the fallback issue the weekly check opens names an unconfigured GitHub App as the cause instead of asking for the data to be regenerated by hand. - The automated data-release workflow now brings an update pull request onto current `master` itself when branch protection has left it behind, instead of waiting for someone to press "Update branch" on a finished release. - The automated data-update pull request now states that it merges and publishes itself once CI passes, and how to withhold the release, instead of leaving a reviewer to infer whether it is waiting on them. - The weekly data update now stages the acceleration-paths, batch-break-even and reduced-zone-mapping files its own regeneration writes, and a test holds that staging list against the generated-file constants so a newly added report page fails there rather than after a full regeneration. - The data converter orders shortcut candidates deterministically: zones of exactly equal spherical area are ordered by timezone identifier and equal polygons within a zone by polygon id, so compiling one boundary release twice yields byte-identical shortcut indexes. `timezonefinder-data` 4.2026.5 is compiled with this order. - A `free-threaded` tox env, run in CI, now tests the package on a free-threaded interpreter. - Changelog fragment previews and release assembly generate the pending section on demand, so `CHANGELOG.rst` contains only released history between releases. - The converter's rule for a cell's candidate polygons is tight rather than conservative, and rests on a planar predicate rather than on evidence that cannot establish an exclusion. A cell is an axis-aligned rectangle of the stored integer coordinates, so "can this polygon own one of the cell's points" is a question about two rectangles and a ring, evaluated against the point-in-polygon kernel's own edge convention: `scripts/grid_cells.py` holds it. It never omits a polygon the kernel can place a cell's point inside, and over-includes only one whose interior enters the cell without reaching any of its integer points - a sliver under \~1.1 cm, costing that cell one bounding-box rejection. `tests/grid_cells_test.py` holds the rule to the kernel over randomised polygons, and `scripts/audit_shortcut_candidates.py` probes every stored cell's four corners and four edge midpoints on each compiled dataset. - Reporting now starts from a form: a bug report that asks for the failing coordinates and for the output of one command reporting the installed versions and which point-in-polygon backend the installation actually uses, or a feature request, with links routing usage questions to Discussions and misplaced boundaries upstream to `timezone-boundary-builder`. - Tests pin which polygon owns a point exactly on its boundary - the one whose interior lies immediately west of the point, or immediately south of it along an east-west edge - on every point-in-polygon kernel, compiled and interpreted, packed and unpacked, and through the whole lookup on the borders the ocean zones share. The point-in-polygon cases `tests/utils_test.py` had left commented out as undefined are now asserted. - Prevent code-release workflows from silently skipping the PyPI upload after their tag-side test job is intentionally skipped. - Add a guarded trusted-publishing recovery command that downloads and validates an existing code tag's GitHub Release assets before uploading them to PyPI. - The committed `tzfpy` agreement chart is rendered with the same deterministic Matplotlib SVG conventions as the other report charts, while remaining byte-for-byte reproducible from its stored measurement. - The Linux wheel job retries pulls of its pinned manylinux and musllinux build images before cibuildwheel starts, so transient container-registry failures do not invalidate an otherwise successful wheel build. - The shortcut index now maps a coordinate to its cell itself (`ShortcutIndex.entry_at` and `entries_at`): the lookup methods, the benchmark fixture generator and the tests that resolve a point hand it a longitude and latitude instead of computing an H3 cell id of their own, and the shortcut-ordering calibration's stand-in index answers the same question, so replacing the index's cells needs no change to `timezonefinder.py`. - The candidate-ordering guarantee is now asserted against the real lookup: permuting a multi-zone cell's candidates within one zone cannot move a `TimezoneFinder` answer, a point contained by a single zone's candidates survives any permutation at all, a cross-zone rotation does move answers (so those two assert something), `TimezoneFinderL` answers the final candidate's zone, and the converter's geometric safety gate refuses pole and antimeridian cells before reading any geometry. - CI now runs the test suite against the oldest NumPy release the published `numpy>=2.2` requirement allows (2.2.0 on Python 3.12) via the new `py312-min` tox environment, so the declared lower bound is exercised instead of assumed. ### [`v8.3.0`](https://github.com/jannikmi/timezonefinder/blob/HEAD/CHANGELOG.rst#830-2026-08-19) [Compare Source](https://github.com/jannikmi/timezonefinder/compare/8.2.5...8.3.0) New features: - The dataset version is now exposed at runtime. `TimezoneFinder().data_version` (and `TimezoneFinderL().data_version`) return the timezone-boundary-builder release the packaged data was built from, read from a `data_version.txt` stamp that `scripts/file_converter.py` writes into the data directory it generates and that ships in the wheel. Previously an installed `timezonefinder` could not state it at all: the release tag lived only in a repo-root file that is not packaged. Which release a parse is stamped with comes from the input's filename (`combined-with-oceans-2026c.json`, which `update_data.sh` now produces), or from `scripts/file_converter.py --data-version` for an input that cannot carry it; your own GeoJSON is stamped `"unknown"`, and an unpacked release archive that lost its tag is refused rather than compiled into data that could never say where it came from. `timezonefinder.__version__` is now exposed as well, read from the installed distribution metadata. Solves issue [#498](https://github.com/jannikmi/timezonefinder/issues/498). - The command line script gained a `--stdin` streaming mode: it reads delimited rows from standard input and writes each back out with a `timezone` column appended, building the finder once instead of paying full initialisation per coordinate. Which columns hold the coordinates is read off the header by name, or stated with `--lng-col`/`--lat-col`, and never inferred from their position - a swapped pair is still a valid coordinate for any longitude between -90 and 90, so guessing would answer with a real but wrong timezone instead of failing. Every input row produces exactly one output row, and a row that cannot be used warns on stderr and makes the run exit non-zero rather than ending the stream. Whether the first row is a header is worked out from the row, or stated with `--header`/`--no-header`. New flags `-d`/`--delimiter` and `--in-memory` apply to the whole stream. See the `usage documentation <https://timezonefinder.readthedocs.io/en/latest/1_usage.html#looking-up-many-coordinates-at-once>`**. Solves issue [#504](https://github.com/jannikmi/timezonefinder/issues/504). Thanks to `weed33834 <https://github.com/weed33834>`** for the PR [#516](https://github.com/jannikmi/timezonefinder/issues/516). Changed: - Polygon coordinates are now stored one axis at a time in the packaged `coordinates.bin` files - all x values followed by all y values per polygon, instead of interleaved. The point in polygon test scans a single axis per iteration, so contiguous per-axis blocks halve the cache lines it touches: \~1.6x faster on a median polygon and \~2.5x faster on the largest ones via the C extension, 14-25% faster via Numba. The bundled data was regenerated accordingly, and the layout is described in the `data format documentation <https://timezonefinder.readthedocs.io/en/latest/data_format.html>`\_\_. - Every packaged FlatBuffers file now carries a file identifier and a layout version, and `TimezoneFinder` raises a `ValueError` naming the offending file when either does not match - previously such a directory was read without complaint and produced wrong timezones. For `coordinates.bin` the version records how the coordinates are encoded and which polygons the file holds. The hybrid shortcut binaries get an identifier that differs per zone id width, because the uint8 and uint16 schemas differ only in the width of a zone id and each parses cleanly as the other; the width is now read from the buffer instead of being guessed from the file name, so a renamed or mispaired shortcut file fails loudly rather than returning wrong zones. If you compile your own data and point `bin_file_location` at it, regenerate it once with `scripts/file_converter.py`, since the coordinate layout, the hole storage, the shortcut container and the file names all changed in this release. The markers track what a file holds rather than the package version, so this is not a per-release obligation. Solves issue [#458](https://github.com/jannikmi/timezonefinder/issues/458). - The hybrid shortcut loader no longer keeps the entire shortcut binary in memory. The polygon id arrays it returns were zero-copy views onto the \~1.5 MB file buffer, so \~47 KB of live data pinned the whole thing for the lifetime of every `TimezoneFinder` / `TimezoneFinderL` instance. They are now disjoint read-only slices of a single compact array, cutting the shortcut mapping's footprint from \~7.4 MB to \~4.7 MB per instance, and every finder's resident set by \~2 MB, at unchanged initialisation time - which matters most for concurrent workloads, where the recommended one-instance-per-thread pattern multiplied the waste. - Holes that duplicate a timezone boundary polygon are no longer stored twice. Almost every hole is an enclave, cut into the surrounding zone with exactly the ring the upstream data also emits as the enclosed zone's own boundary polygon - the same geometry under two IDs. The packaged hole coordinate file now holds only the rings with no such twin (27 of 756 in the current data), and a new `holes/poly_ref.npy` records per hole which boundary polygon to read instead. Hole data drops from \~2.0 MiB to \~0.16 MiB, and `in_memory=True` saves the same amount of RAM, since those holes now resolve into the boundary arrays rather than materialising a second copy. Matching is exact - rings are compared as integer coordinates in a canonical form, with bounding boxes used only to narrow the search - so every timezone lookup returns what it did before. One visible consequence: `get_geometry()` may hand back a deduplicated hole ring starting at a different vertex or winding the other way than it used to, tracing the same closed path. The encoding is described in the `data format documentation <https://timezonefinder.readthedocs.io/en/latest/data_format.html>`\_\_. - The timezone boundary data now ships as its own distribution, `timezonefinder-data`. `pip install timezonefinder` is unchanged - it is a hard dependency and is installed automatically - but the dataset can now be pinned on its own (`pip install timezonefinder "timezonefinder-data==1.2026.3"`), where previously holding a dataset meant pinning an old `timezonefinder` and forfeiting every code fix since. Every release used to carry the whole \~65 MB dataset in three platform wheels plus an sdist to distinguish a few kilobytes of compiled code, which had already exhausted the PyPI project storage quota once. A data update is consequently no longer a `timezonefinder` release at all: it publishes `timezonefinder-data` under its own tag namespace and is recorded in that package's README rather than here. Its version reads `<format>.<year>.<letter>` - `1.2026.3` is data format generation 1 built from timezone-boundary-builder `2026c` - and `timezonefinder` requires `timezonefinder-data>=…,<2`: no ceiling on the data axis, so a dataset update needs no code release, and a hard one on the format axis, so code paired with data it cannot read fails when resolving rather than at the first lookup. `DATA_LICENSE` moves with the database it covers and now ships inside the data wheel, and a compiled data directory additionally carries a `schemas/` copy of the FlatBuffers definitions its binaries were written by, so it can be read back without the package that wrote it. Solves the first part of issue [#446](https://github.com/jannikmi/timezonefinder/issues/446). - The packaged FlatBuffers binaries are now named `.bin` rather than `.fbs`: `boundaries/coordinates.bin`, `holes/coordinates.bin` and `hybrid_shortcuts_uint16.bin`. `.fbs` is the FlatBuffers *schema* extension, and the data directory now ships actual schemas next to the buffers, so one extension was naming two unrelated kinds of file. Each buffer already states what it is through the file identifier in its first bytes, which is what a rename or a mispaired copy cannot forge - the name never carried that meaning. The bytes are unchanged. Bug fixes: - Fixed a `BufferError: cannot close exported pointers exist` raised during resource cleanup in file mode (`in_memory=False`). A coordinate array obtained from `coords_of()` is a zero-copy view onto the memory-mapped file, and `mmap.close()` refuses to unmap while one is alive, so an array outliving its `TimezoneFinder` raised on cleanup. The mapping now stays valid instead of leaving the views dangling, and `FileCoordAccessor.cleanup()` releases its own references so the deferred close happens as soon as the last view is dropped. The accessor must not be used after `cleanup()`. Documentation: - The memory footprint of every finder configuration is now measured and published in a new `memory report <https://timezonefinder.readthedocs.io/en/latest/benchmark_results_memory.html>`\_\_, separating what a configuration allocates (`tracemalloc`) from what it makes resident (RSS, which additionally counts memory-mapped pages). The distinction is the point: the default mode maps the coordinate data instead of reading it, so it allocates an order of magnitude less than the in-memory mode, and only the pages a lookup actually touches become resident. This replaces documentation claiming a 40MB process ceiling and a 41MB data directory, both long out of date. - Restructured the two entry points a reader actually arrives at - `README.rst` and the `documentation landing page <https://timezonefinder.readthedocs.io/en/latest/>`\_\_ - so both state what the package is and how it works instead of only what it is called. The README opens with the project banner and a one-sentence statement of what the package is for, then the badges, then the quick guide - and adds three short sections that were missing entirely: *How it works* (the lookup pipeline and the no-simplification trade-off), *Performance* (a concrete throughput figure with its configuration named, the three point-in-polygon backends and the pure-Python fallback), and *Engineering notes* linking the architecture, data format and benchmarking methodology pages. The maintainers-wanted notice moves from the first heading after the intro into a new `Contributing` section at the bottom, which also links `CONTRIBUTING.md` for the first time. The badge block is corrected along the way: the `code style: black` badge named a formatter this project has never used and is replaced by `ruff`, and a supported-Python-versions badge was added. The banner is referenced by absolute URL, since PyPI serves the long description without the repository and a `docs/…` path renders as a broken image there. The landing page gains the same *How it works* summary, the no-simplification trade-off and the ocean-zone consequence for `timezone_at()`, and its flat seventeen-entry table of contents is grouped into *Using it*, *Design*, *Performance* and *Project*, so the sidebar says what kind of project this is rather than listing pages in the order they were written. - Rewrote the `package comparison <https://timezonefinder.readthedocs.io/en/latest/alternatives.html>`\_\_ page. It now states its position in prose before the first table - border correctness is what this package optimises for, speed is the constraint that work happens under - and says plainly when `tzfpy` is the better choice. Every quantitative cell names what it measures and links its source, and the speed row is deliberately qualitative on both sides, with a note explaining that the two packages have never been benchmarked under one harness. The decision table drops the rows on which the two packages do not differ. - Two new documentation pages: `Architecture <https://timezonefinder.readthedocs.io/en/latest/architecture.html>`\_\_ describes the lookup pipeline, the three point-in-polygon backends and the memory modes, and states the ceilings this package deliberately does not exceed - unsimplified geometry, \~1 cm coordinate resolution, no general-purpose spatial code. It also documents how the package is built and shipped, which was previously described nowhere outside the workflow YAML: why one abi3 wheel per target replaces one wheel per Python version and what `abi3audit` is guarding, why three libc targets are built, why the end-to-end job installs the built wheel and asserts the C extension loaded rather than merely importing the package, and why a tag pushed from outside `master` aborts the release. The testing section gained the property-based suite and the reason the tox matrix is a matrix - the acceleration paths are bound at import time, so a passing run describes one configuration only. Both sections are linked from the README's *Engineering notes*. `Benchmarking Methodology <https://timezonefinder.readthedocs.io/en/latest/benchmarking_methodology.html>`\_\_ documents how the published numbers are produced and what they can and cannot tell you: `ubuntu-latest` pins the runner image and not the CPU, which is why a pull request is measured against its own merge base on the same runner and why every alert threshold is derived from measured noise. It was previously addressed only to contributors, in the second half of `CONTRIBUTING.md`, which now keeps the operational instructions and links to it. - The H3 resolution choice in the `data format documentation <https://timezonefinder.readthedocs.io/en/latest/data_format.html>`\_\_ is no longer asserted to "offer a good balance" but reports the study behind it (`prototypes/single_resolution_bench.py`): resolution 3 keeps the hybrid index at a small fraction of the packaged polygon data, while resolution 4 would exceed 10 % of it for gains that do not justify the increase. - The hand-written documentation no longer restates exact figures that belong to the generated pages - dataset vertex, polygon and hole counts, index and distribution sizes, memory footprints, lookup throughput. Those change with every data update and with code that shifts a footprint, which silently left the copies wrong: the memory figures had already gone stale in four places. The prose now states the magnitude that survives a data update and links `the data report <https://timezonefinder.readthedocs.io/en/latest/data_report.html>`\_\_ or the relevant `benchmark report <https://timezonefinder.readthedocs.io/en/latest/7_performance.html>`\_\_, which are regenerated from the packaged data and are always current. - The three weakest hand-written documentation pages no longer answer a question by pointing at a file the reader has to open. The `performance page <https://timezonefinder.readthedocs.io/en/latest/7_performance.html>`\_\_ now opens with the four benchmark reports and the trend chart instead of a bullet list of adjectives about the binary format, and its C extension and Numba sections are cut to what a user does - which call reports the active backend - with the explanation left to the architecture page that already carried a more precise version of it. *Getting started* lists the four runtime dependencies and what each is for, where it previously said to consult `pyproject.toml`, which remains linked as the authoritative source for version ranges. The use case pages carry runnable snippets for building an aware `datetime` and reading a UTC offset, with the `examples/` scripts as the follow-up rather than the whole answer; the snippets use the standard library's `zoneinfo`, so neither needs an optional dependency. - The shortcut entry distributions in the `data report <https://timezonefinder.readthedocs.io/en/latest/data_report.html>`\_\_ no longer report three quarters of all H3 cells as holding `0` polygons, which is impossible for data whose ocean zones cover the globe. Those cells are covered by a single timezone and store its id directly, so a lookup there needs no point-in-polygon test at all - the column is now *Polygons to test* and the row reads *none (unique zone)*. The tables are introduced by a sentence on what they measure, including why no cell ever needs exactly one test. - The usage examples in `README.rst` and the `usage documentation <https://timezonefinder.readthedocs.io/en/latest/1_usage.html>`\_\_ now show the result the packaged data actually returns. Every snippet queries the same Berlin coordinates and annotated the answer as `'Europe/Paris'`, which is the value from the reduced `timezones-now` dataset, where `Europe/Berlin` is merged into `Europe/Paris` - not from the full dataset the package ships by default. All eleven annotations now read `'Europe/Berlin'`, verified against the packaged data for each of `timezone_at()`, `timezone_at_land()`, `certain_timezone_at()`, `unique_timezone_at()` and `TimezoneFinderL`, and the `get_geometry()` call in the opening example asks for that same zone instead of a different one. `tests/test_documented_contracts.py` now re-runs each of those documented lookups, so a data update that moves the example coordinate's zone fails there rather than leaving every snippet on both pages quietly wrong again. Internal: - The release pipeline refuses to publish `timezonefinder` unless a compatible `timezonefinder-data` already exists on PyPI. The two distributions release independently, and on a data format change the order is fixed - data first, then the code requiring it - because a code wheel whose declared data version does not exist yet is uninstallable for everyone until it does, and the version number cannot be reused to fix it. The check reads the requirement out of the built wheel rather than out of `pyproject.toml`, and asks the index the same question a user's resolver will, so a yanked release does not count as one that satisfies it. It runs before the GitHub Release, which is the first step of the release that cannot be taken back. - Pull requests are opened against a template (`.github/pull_request_template.md`) prompting for the change, its motivation and the checks that were run. - `update_data.sh` resolves the timezone-boundary-builder release tag before downloading and fetches that release's asset, instead of fetching `releases/latest/download/` and separately asking the API what `latest` was - two independent questions that a release landing between them answered differently, attributing one release's data to the other. The tag now names the downloaded archive and the GeoJSON as well, so a leftover file from another release or another dataset variant cannot satisfy the "already downloaded" checks and be parsed in place of what was asked for. - Names and docstrings now describe what the code does. `TimezoneFinder.timezone_at` documents the optimisation it actually performs: once no other zone can be matched the last remaining zone is returned *without* a point in polygon test, which is always correct against the packaged data - the ocean zones cover the globe, so every point lies within one of the candidate polygons - but not against custom data that leaves areas uncovered, where a point inside none of the candidates is still attributed to that zone and `certain_timezone_at` is the method that tests every candidate. Three tests were named after something other than what they do: `test_rectify_coords_valid`/`_invalid` were named for a `rectify_coords` that exists nowhere in the package and both call `validate_coordinates`, and the first was subsumed entirely by `test_validate_coordinates_accepts_finite_values`, which covers all four of its distinct corners and additionally asserts the return value where the older test asserted only "does not raise"; and `test_single_element_arrays_should_not_occur` asserted that they *do* occur (`assert single_element_count == 2`) under a triple-quoted string placed after the first statement, making it a discarded expression rather than a docstring - so it reached neither `--collect-only` nor a failure report, which is where the contradicting name was the only thing a reader saw. A stale comment duplicated across the last two lines of `tests/main_test.py`, reading as a to-do for something `TestTimezonefinderClassTestMEM` already does, is gone. - Added `DATA_VERSION` file tracking which timezone-boundary-builder release the packaged data was generated from, written automatically by the data update script after a successful parse. Thanks to `Lucas Hemkemeier <https://github.com/hemkdev>`\_\_ for the PR [#429](https://github.com/jannikmi/timezonefinder/issues/429). - The packaged data now updates itself: a weekly workflow compares `DATA_VERSION` against the latest timezone-boundary-builder release, regenerates the data and opens a ready-to-review update PR, which is merged and released automatically once its CI passes - the version tag is pushed with a GitHub App token, since the default one would not trigger the release pipeline. The tag lives in its own `data-v*` namespace, which the code release pipeline excludes at its trigger and again on the job that creates the GitHub Release, and the data stream publishes by PyPI Trusted Publishing from its own deployment environment rather than with a shared token. It refuses to release when the squash it produced did not land on the `master` it checked, so the tag names a tree that was actually built. Failed CI takes the same manual-attention path and falls back to the previous notification issue. Each cause labels the PR `automation-failed` and leaves one comment naming that cause and linking the run, deduplicated per cause so re-running CI neither repeats a notice nor hides a second one; a failure past the merge is a cause of its own, since that leaves master carrying the update with no tag pushed and only a hand-pushed tag still releases it. The manual release path drops the stop condition it carried for an out-of-order `CHANGELOG.rst`: the automation can no longer produce one, and the test suite asserts the committed file's section order if anything else does (issues [#273](https://github.com/jannikmi/timezonefinder/issues/273), [#167](https://github.com/jannikmi/timezonefinder/issues/167) and [#510](https://github.com/jannikmi/timezonefinder/issues/510)). Thanks to `Lucas Hemkemeier <https://github.com/hemkdev>`\_\_ for the PRs [#434](https://github.com/jannikmi/timezonefinder/issues/434) and [#436](https://github.com/jannikmi/timezonefinder/issues/436), and to `Nice6042 <https://github.com/Nice6042>`\_\_ for the PR [#518](https://github.com/jannikmi/timezonefinder/issues/518). - `update_data.sh` (renamed from `parse_data.sh`) is CI-ready: interactive prompts replaced by flags (`--dataset=full|same-since-now`, `--with-oceans`, `--rm-tmp`), the release note for a data update written automatically into the data package's README, no redundant `tox` run, and a `make reports` at the end so the benchmark and data reports cannot go stale relative to the data an update PR ships. A standalone `make parse`/`make testparse` still needs a manual `make reports` (issues [#167](https://github.com/jannikmi/timezonefinder/issues/167) and [#510](https://github.com/jannikmi/timezonefinder/issues/510)). Thanks to `Lucas Hemkemeier <https://github.com/hemkdev>`\_\_ for the PRs [#432](https://github.com/jannikmi/timezonefinder/issues/432) and [#434](https://github.com/jannikmi/timezonefinder/issues/434). - Added property-based tests (`hypothesis`) for coordinate validation (solves issue [#143](https://github.com/jannikmi/timezonefinder/issues/143)). Thanks to `Lu Yicheng <https://github.com/01luyicheng>`\_\_ for the PRs [#431](https://github.com/jannikmi/timezonefinder/issues/431) and [#433](https://github.com/jannikmi/timezonefinder/issues/433). - Replaced the hand-rolled `timeit` timing in `scripts/check_speed_*.py` with `pytest-benchmark` suites under `benchmarks/`, excluded from `make test`/`make testall` via `testpaths`. Both they and the memory harness run over deterministic committed fixtures (`tests/fixtures/benchmarks/`), so two runs of the same commit execute the exact same workload; the loader rejects fixtures that no longer match the checkout. Measurement and rendering are decoupled, so `docs/benchmark_results_*.rst` can be regenerated from a stored JSON without re-measuring. Run via `make speedtest`, `make benchmarks`, `make memory` or `make reports`. - Memory is measured by its own harness (`scripts/measure_memory.py`, `make memory`) rather than by `pytest-benchmark`, which times code and would have its timings distorted by allocation tracking. It emits pytest-benchmark-shaped JSON, so the existing normalisation, noise and comparison tooling works on it unchanged given a `--metric`. `tests/test_memory_footprint.py` fails if a mode's allocation leaves its order of magnitude - the regression that would make `in_memory=False` stop being the low-memory option. - Added continuous benchmarking on CI (solves issue [#150](https://github.com/jannikmi/timezonefinder/issues/150)), deliberately kept out of the release pipeline in `build.yml`: the tracked core subset and the memory harness run on every pull request and every push to `master`, publishing `trend charts <https://jannikmi.github.io/timezonefinder/dev/bench/>`\_\_ to `gh-pages` and posting a same-runner base/head comparison on the pull request. The comparison reports added or removed benchmark IDs without trying to ratio unmatched measurements, which lets the trusted default-branch consumer remain compatible while the suite evolves. A pull request is measured against its own merge base in the same job rather than against a stored baseline, because `runs-on: ubuntu-latest` pins the runner image and not the CPU. The measurement design, the tracked estimator and every alert threshold are documented in the new `benchmarking methodology <https://timezonefinder.readthedocs.io/en/latest/benchmarking_methodology.html>`\_\_ page. The measuring job holds no write permissions and no secrets, so branch and fork pull requests behave identically; the comment is posted by a separate, privileged workflow via `workflow_run`. - Guarded the benchmark plumbing against silent drift: `tests/test_benchmark_names.py` and `tests/test_memory_metric_names.py` pin the node ids and metric names that join a measurement to its chart history, so a rename fails loudly instead of starting an empty chart beside the orphaned old one; `tests/test_benchmark_workflows.py` asserts that the constants duplicated across the two workflows agree, where a one-sided edit previously had no failure mode at all, and that the cross-machine trend chart cannot creep back into the pull request comparison; and every generated report page states the inputs it describes - `docs/benchmark_results_*.rst` the fixture and timezone data versions they were measured against, `docs/data_report.rst` the timezone data version its figures were derived from. Both stamps are covered by tests: one renders each report and fails if a renderer stops emitting it, another checks the committed pages against the current fixture metadata and `DATA_VERSION`, so regenerating fixtures or updating the data without re-rendering fails loudly instead of leaving a page whose numbers are all plausible and all stale. - Every generator now emits output that is already pre-commit-clean, so regenerating and diffing compares like with like: `write_json` sorts keys the way `pretty-format-json` does, and neither `scripts/reporting.py` nor `BenchmarkReporter` emits trailing whitespace on empty cells or a trailing blank line. Previously every `make parse`/`make reports` left its outputs looking modified until the hooks had run, which masked whether a regeneration had actually changed anything. - Every generated benchmark report now opens with its headline figure and the configuration behind it, above the tables: how long a lookup takes and how many per second, the per-check cost across polygon sizes, construction time, footprint per mode - all derived from the same parsed JSON as the tables, never hardcoded. The banner beneath states which acceleration path and platform produced the numbers, and says whether that is the configuration CI tracks: the committed reports are rendered from a developer machine with Numba enabled, while CI measures the C extension without Numba, so their figures were never comparable to the trend chart and now say so. - `make flatbuf` no longer overwrites hand-maintained `__init__.py` files. `flatc` derives its output path from the schema namespace and writes an empty `__init__.py` at every level of it, so generating in place wiped the `__all__` in `timezonefinder/__init__.py` - the whole public API. The target now generates into a scratch tree, copies back only the generated packages, and runs the formatters on the result so a regeneration diff shows the codegen change rather than formatting churn. - Mypy now type-checks the whole package except the `flatc`-generated bindings. `ignore_errors` previously covered roughly 800 lines of hand-written code as well, where a blatantly wrong return type still reported "Success"; they all pass once the exemption is lifted, bar two genuine findings now fixed. `tests/test_mypy_config.py` keeps the list restricted to generated code, so silencing a module is a reviewed decision rather than a one-line edit. - The hybrid shortcut reader and writer now select their FlatBuffers schema from a single registry (`SHORTCUT_SCHEMAS` in `timezonefinder/flatbuf/io/hybrid_shortcuts.py`) instead of dispatching on the zone id width in three places, each keyed differently. One `ShortcutSchema` per width owns the width, the file name, the `uintN` marker and the maximum zone id, which were previously written down across five places with nothing tying them together. Verified behaviour-preserving down to the bytes: re-writing the shipped shortcut binary produces a byte-identical file. - Each distribution's build is now asserted to contain exactly what it should. The data wheel's payload is compared against the committed dataset as a set, in both directions: a missing binary fails on first use and gets reported, but an extra one ships silently - setuptools copies package data into `build/lib` and never prunes it, so a file renamed in the source tree keeps being zipped into every later wheel built from that checkout, which is how a 63 MB `coordinates.fbs` was still shipping next to the `coordinates.bin` that replaced it and doubling the wheel whose size is the reason the distribution was split out. The wheel builders clear that directory first, so a local build matches the fresh checkout CI builds from, and the code sdist's checks cover its grafted test fixtures again. - The packaged data is additionally held to a floor on how much hole deduplication achieves - the test suite fails if fewer than 90% of its holes match a boundary polygon (96.4% currently), because a future upstream release that stopped emitting enclaves as shared rings would still compile and still return correct timezones, just with the shipped data quietly re-inflated. The floor applies to that dataset and nothing else: compiling your own GeoJSON with `scripts/file_converter.py` is a supported use case, holes that are ordinary interior rings rather than enclaves are stored inline and answer correctly, and the converter only reports the ratio rather than refusing to compile. `prototypes/hole_boundary_redundancy.py` is the study behind the threshold: it reads the upstream GeoJSON, so re-running it against a new release re-verifies the assumption rather than restating it. `prototypes/hole_removal_impact.py` is the study behind keeping the unmatched holes stored inline rather than dropping them, which is the obvious next step and does not work: dropping holes and re-running the lookups changes answers, wrongly, because being covered by another zone only puts that zone among the shortcut candidates and says nothing about it being tested first (issue [#513](https://github.com/jannikmi/timezonefinder/issues/513)). - Removed constructs that provably did nothing, and gave two vacuous tests real assertions. Most consequentially, four `__slots__` entries were declared but assigned by nothing, which silently re-permitted the very attributes `__slots__` is there to forbid - assigning those names now raises `AttributeError`, and `test_declared_slots_are_assigned` keeps the list honest. - `get_corrected_hex_boundaries` exists once again. An earlier refactor left two verbatim copies of the antimeridian and pole clipping rules with nothing keeping them in sync; the copy without callers is deleted, and the survivor is now covered by `tests/hex_utils_test.py` - it previously had no direct tests at all. `scripts/configs.py` no longer declares `MAX_LAT`/`MAX_LNG` as a second pair of names for `timezonefinder.configs`'s constants. - `prototypes/` has a `README.md` saying what the three scripts there are: exploratory studies behind committed design decisions, run by hand, outside the package and the test suite. One of them is the measurement that chose H3 resolution 3 - the central algorithmic parameter of the package, already cited from the data format page - and another is the evidence for not building a hierarchical index. `MANIFEST.in` now excludes the whole directory from the source distribution rather than only its `*.py` files. - `plans/` is git-ignored alongside `tmp/` and `.venv/`: implementation plans written while working on a change are local scratch, and leaving the directory untracked-but-unignored made it noise in every `git status` and a candidate for an over-broad `git add`. - Failing paths now report the input that failed. `tests/auxiliaries.py`'s `run_command` assembled the child's stdout and stderr into a message and then raised a *fresh* `CalledProcessError` that never used it, with `from None` discarding the original too, so a packaging failure under `make testint` reported an exit code and nothing about the cause; it now echoes the captured streams and re-raises the original exception with its traceback intact. `scripts/reporting.py` passes the coordinate file paths into `get_polygon_collection`, whose optional `file_path` exists precisely so an incompatible-layout `ValueError` can say which of the two files was stale - `make reports` against an outdated data directory previously could not. `Boundaries.overlaps` names the type it rejected instead of raising a bare `TypeError`, and the `RuntimeError` for missing `original_polygons` names the polygon and resolution it was computing. The two re-raises ruff flags under `B904` now say `from None` explicitly, so a deliberately dropped exception chain is distinguishable from a forgotten one, and `timezonefinder/command_line.py` drops `FileNotFoundError` from an `except` tuple that already caught its base class `OSError`. `tests/test_error_diagnostics.py` pins what each of these messages must contain. - The command line interface no longer routes its own output through a temporary file. `main` redirected stdout to a `mkstemp` file for the duration of the lookup and then, in verbose mode, reopened it to read back a string it still held in a local variable - nothing inside the redirected block ever wrote to stdout, since the lookup functions return their result rather than printing it. The context manager, the read-back, its warning path and the file cleanup are gone, and the lookup function is now resolved once per invocation instead of twice, so `-f 3`/`-f 4` under `-v` no longer construct a second `TimezoneFinderL` and reload its shortcut data just to read a function name. Output is unchanged character for character, across every function id in both modes. `tests/cli_test.py` gains the coverage that makes that checkable - verbose mode, the empty line printed when no timezone is found, and the rejected function id had none - and asserts the printed name verbatim instead of passing it through `rstrip("\n\x1b[0m")`, which strips a *set* of characters rather than a suffix and so truncates 12 of the packaged zone names (`Europe/Amsterdam` -> `Europe/Amsterda`). - Docstrings now describe the code that exists. Six documented something the implementation contradicts: `AbstractTimezoneFinder.__init__` called `in_memory` inert and "kept for API compatibility" when it is what selects memory-mapped against in-memory coordinate access - the claim `help(TimezoneFinder)` surfaces, and the opposite of what the usage docs say; both `get_geometry` docstrings pointed at a `timezone_names.json` that does not exist under that name; `read_zone_names` promised an empty list where it raises `FileNotFoundError`, and illustrated itself with a hardcoded zone count that the packaged data had since outgrown; and `zone_id_of` / `zone_name_from_id` each advertised an exception type they convert away, sending callers to write handlers that can never fire. Five further `:param:`/`Args:` entries in `scripts/` and `tests/` documented arguments that were removed along with the parallel shortcut compilation they belonged to. `tests/test_documented_contracts.py` pins the exception types and the coordinate access mode, so those promises now rest on something besides prose. - The test and benchmark suites no longer contain checks that cannot fail. Eighteen calls sat inside four shared `pytest.raises` blocks in `tests/main_test.py`, and execution leaves such a block at the first statement to raise - so one out-of-range coordinate, one positional call shape and one rejected `get_geometry` input were verified while the remaining fifteen were unreachable. Each is a test case of its own now: every coordinate just outside the WGS84 range, every positional call shape of every keyword-only lookup method, and the unknown-zone-name, past-the-end and negative zone id rejections of `get_geometry`. The `__del__` cleanup test binds its exception per iteration rather than closing over the loop variable, which decided what a garbage-collected instance would raise long after the loop had moved on. On the benchmark side, `pip_inputs_by_stratum` validated only the strata the fixture happened to contain, so one missing from it altogether passed and surfaced later as a bare `KeyError` inside a benchmark, and the points and their labels were paired from two files with a non-strict `zip` that truncates silently. That grouping now lives in `tests/auxiliaries.py` as `group_pip_inputs_by_stratum`, checks against the declared `PIP_STRATA` - which the generator no longer keeps a second copy of - and has tests for each way the two fixture files can disagree. - Both point-in-polygon acceleration paths are now covered by a local test run, whichever one the environment happens to bind. The implementation is selected at import time and Numba wins whenever it is importable - which the documented setup (`uv sync --all-groups`) makes it - so the C extension was reached only by direct-kernel tests on hand-built arrays, and everything about how real polygon buffers arrive at it, including the read-only memory-mapped views, was first exercised in CI's non-numba tox environments: the configuration a plain `pip install timezonefinder` produces. `tests/test_acceleration_paths.py` now rebinds `utils.inside_polygon` and drives the full lookup stack through both implementations, asserting that they agree across the real boundary data, that the C path returns the known-correct answers, and that the point-in-polygon stage was reached at all rather than short-circuited by the shortcut layer (issue [#482](https://github.com/jannikmi/timezonefinder/issues/482)). - The packaging guard in `tests/test_package_contents.py` no longer names files that do not exist. It asserts that nothing in the built sdist and wheel matches a list of unwanted paths, which passes just as readily when a pattern matches nothing at all: `.github` lacked the trailing slash that directory patterns need, `Agents.*` stopped matching when the file was renamed to `AGENTS.md`, and `readthedocs.yaml` never matched `readthedocs.yml` - so the CI configuration and both of those files were unguarded while the suite stayed green. The patterns are corrected, the provider stubs, `contributing/`, `.agents/`, `.claude/` and `.cursor/` are covered to match what `MANIFEST.in` excludes, and `test_every_unwanted_pattern_matches_a_project_file` now fails on any hand-written pattern that matches no path in the checkout, so the next rename cannot silently disarm one. It carries the `unit` marker rather than the module's former blanket `integration` mark, since it needs no build: a mistyped pattern surfaces in `make test`. `.gitignore` re-include lines (`!…`) are also no longer read as exclusions, which had produced one more parametrised case that could never fail. The converse direction is checked too: `test_every_manifest_exclusion_is_guarded` parses the `exclude`/`recursive-exclude`/`prune`/`global-exclude` directives out of `MANIFEST.in` and fails when one of them keeps a path out of the build that no pattern here names - previously such a line was enforced by the build and verified by nothing, so deleting it would have shipped the file with the suite still green. The two lists are hand-maintained statements of one intent and had drifted before, in both directions. The `architecture page <https://timezonefinder.readthedocs.io/en/latest/architecture.html>`\_\_ describes the guard from both sides: among the tests that exist to give an invariant a failure mode, and under *How it ships* as the check on what the built artifacts actually contain. - The distributions built by the test suite are now built for the interpreter running it. `uv build` was invoked without `--python`, so it targeted the newest interpreter on the machine, while `tests/test_integration.py` creates its throwaway venv from `sys.executable`: on a checkout whose `.venv` is older than the newest installed Python, `make testint` produced a `cp314` wheel and failed with pip's "not a supported wheel on this platform". Every tox environment offers a single interpreter, so the two agreed by accident in CI and the mismatch only ever hit developer machines, where the workaround was to pin `UV_PYTHON`. `test_build_commands_pin_the_running_interpreter` keeps the pin in place; it needs no build, so it fails in `make test` rather than waiting on a CI environment that cannot reproduce the mismatch. - Two tests no longer leak numpy's global error state into whatever pytest collects next. `np.seterr` and the warning filters are process-global, and `test_overflow` (`tests/main_test.py`) plus `test_inside_polygon` (`tests/utils_test.py`, six parametrisations) each set them and never restored them - so every later test in the same process ran with `under` promoted from `ignore` to `warn`, and which of the two modules pytest collected first decided the state the other ran under. The filters were undone only incidentally, by pytest's per-test `catch_warnings()`, not by the tests themselves. `benchmarks/conftest.py` already had the correct pattern; it now lives in `tests/auxiliaries.py` as the `strict_numpy_errors` context manager plus a thin `strict_numpy_warnings` fixture, re-exported through the conftest of each suite, and both call sites request it. The context manager form is what makes the restore directly testable - a leaked global otherwise surfaces only as an unrelated later failure that depends on collection order, which is the hardest kind to attribute. - The zone id invariants in `scripts/timezone_data.py` are each enforced in exactly one place, and now have tests. `ZoneCollection.validate_structure` and `zone_positions` each walked `poly_zone_ids` element by element checking it was non-decreasing and each raised the same message built from its own locals; the scan moves into one `_validate_non_decreasing` helper and `zone_positions` drops its copy, which could only ever have fired if a caller mutated the array in place - the validator runs at construction and nothing writes to it afterwards. A `if min_zone_id < 0` branch is deleted as unreachable: the same method rejects any non-unsigned dtype a dozen lines earlier, so it read as the guard against negative zone ids while being incapable of firing. The class had no tests at all, so what it actually promises - the unsigned-dtype rejection that makes a negative id unrepresentable, the ordering and maximum-id rules, and the shape `zone_positions` returns - is now pinned by `tests/timezone_data_test.py`. - The seven out-of-range coordinates - one representable step outside the valid WGS84 range, per axis and at every corner - are declared once in `tests/locations.py` instead of verbatim in both `tests/main_test.py` and `tests/utils_test.py`, where only one copy carried the comment explaining what makes them interesting and adding a corner to it left the other testing a smaller set. - The shortcut compilation chain in `scripts/shortcuts.py` is annotated for what it is actually passed. Both annotations were the wrong way round: `check_shortcut_sorting` declared `np.ndarray` and only ever receives the `list[int]` that `optimise_shortcut_ordering` returns, and it hands the `np.ndarray` it derives to `has_coherent_sequences(lst: list[int])`. Widened rather than swapped, since `tests/shortcut_test.py` calls the latter with real lists. - The supported Python versions are declared in five places that cannot read each other - `requires-python` and one classifier per minor version in `pyproject.toml`, the `py{...}` factors of `tox.ini`'s envlist, the test matrix and `CIBW_BUILD_VERSIONS` in `build.yml`, and `py_limited_api` in `setup.py` - and two "must match" comments said so while nothing enforced them. `tests/test_python_version_support.py` fails when they drift, in either of the two directions that fail silently: a classifier added without a matrix entry ships a version the package claims to support and CI never runs, and a `requires-python` raised without moving the abi3 base builds wheels tagged for an interpreter that is no longer supported. Each assertion was checked against the specific one-sided edit it targets, and both comments now name the test. - The data report generator states figures it derives rather than ones it restates, and its annotations describe what it returns. `calculate_shortcut_index_stats` took the number of H3 cells existing at the shortcut resolution from a ladder of literals covering resolutions 0 to 4 and fell through, for anything else, to the number of cells actually stored - which reports coverage of exactly 100 % instead of failing - behind an `except ImportError` that cannot fire, since h3 is a runtime dependency rather than an optional one. It asks `h3.get_num_cells`, which returns precisely the numbers that were tabulated. Running mypy over `scripts/reporting.py`, which the pre-commit hook excludes, found seventeen further disagreements between the module and its own signatures: the statistics bag was typed as holding scalars while returning two distributions, `load_binary_data`'s nine-key result was a bare `dict` indexed by string literal, the table renderer declared string rows while stringifying whatever it is handed, `main` was annotated `None` while returning exit codes to `exit()`, and `print_polygon_distribution_table` documented a return value it never produced while its one caller discarded it. The two dict results are now `TypedDict`\ s in `scripts/configs.py`, carrying tests that assert their keys against what is really returned, since CI cannot type-check `scripts/`. The polygon count that labels a distribution row is no longer formatted into that label and parsed back out of it to key the example lookup. `docs/data_report.rst` and the benchmark reports regenerate byte-identically throughout. - Removed five definitions nothing referenced - three JSON/pickle helpers in `scripts/utils.py` and the `import pickle` they kept alive, the `i8` dtype shim in `timezonefinder/_numba_replacements.py` that the no-numba fallback never imports, and a test helper self-documented as kept for future reference - and a guard in `scripts/hex_utils.py` that could not fire. `Hex.poly_candidates` re-read its cache after initialising it and returned an empty set if it were still unset, which no path through `_init_candidates` leaves it: an empty set there means "no candidate polygons", so a converter bug would have surfaced as silently missing shortcuts rather than as a failure. The property had no direct test, being reached only through shortcut generation, and now has one. `_memory_mode_label` looks its two labels up in `PARAM_LABELS` instead of spelling them out, so renaming the display vocabulary can no longer leave the comparison bullets and the tables above them disagreeing. - `make parse` and `make testparse` run again. Both invoked `scripts/file_converter.py` by path, which puts `scripts/` on `sys.path[0]` instead of the repository root, so the converter's own `from scripts.timezone_data import ...` raised `ModuleNotFoundError` before any work started - a total failure that CI never sees, since it runs neither target. `make testparse` is the only cheap end-to-end exercise of the converter (`update_data.sh` needs a \~55 MB download), and nothing under `tests/` covers `parse_data()`, so while it was broken the converter had no smoke test at all. The invocation documented in the usage docs had the same defect and is now the `python -m scripts.file_converter` form that `update_data.sh` already used; `tests/test_script_invocations.py` fails if a by-path invocation returns. Note that `parse_data()` writes its report to the checkout's committed `docs/data_report.rst` whatever `-out` it is given, so `make testparse` leaves that file describing the three-zone fixture - the target now says so. - `scripts/` is type-checked by the mypy pre-commit hook instead of being excluded from it. The directory holds the data converter and the benchmark tooling - most of the repository's non-library Python - and with nothing running mypy over it the annotations had drifted to fifteen errors: two `# type: ignore` codes mypy no longer emits, so the ignore silenced nothing; two implicit `Optional` defaults that `no_implicit_optional = true` was already configured to reject; a dict annotated with a narrower value type than it is assigned; a bucket key and four bounding-box lists annotated `int` while `Boundaries` declares `float`; and two missing variable annotations. All fixed as annotations, with no runtime change. Two of the four errors mypy reported in `tests/auxiliaries.py`, which it reaches by following imports out of `scripts/`, are fixed alongside. `test_scripts_are_type_checked_by_the_hook` guards the exclude, which is a quieter way to stop type-checking a directory than the `ignore_errors` list the neighbouring tests already cover: it takes no override entry and reports nothing. - The eight `__del__` cleanup tests that differed only in which exception `cleanup()` raised, and whether zero or one `ResourceWarning` was expected, are two parametrized tests over the suppressed and warned exception tuples. Each previously repeated the same subclass, the same `catch_warnings` block and the same filter, so adding a ninth exception to `__del__`'s suppression list meant copying the block a ninth time and a copy asserting the wrong count would be invisible. Coverage rises rather than falls: the hand-rolled loop asserting that `__del__` never raises to user code now runs over all six exception types instead of four. - Three leftovers in the converter that read as bugs are gone: `has_coherent_sequences` built an iterator solely to take its first element and then looped from the start anyway (correct, but it reads as an off-by-one), `compile_bboxes` unpacked a pair and immediately reassigned half of it, and `process_single_hex` returned the `hex_id` it was handed so its only caller reassigned the loop variable to itself. Two shadowed builtins (`dir` as a loop variable, `id` as a parameter) are renamed and three bare generator signatures annotated. The benchmark renderer classifies its "other" group by name suffix, as the two lines above it do, rather than by deep-equality scan over lists of dicts; and the `check-manifest` ignore list drops two entries naming files that do not exist (`CONTRIBUTING.rst`, `publish.py`). Every converter change was verified by parsing `tests/test_input.json` before and after and comparing the outputs byte for byte. </details> --- ### Configuration 📅 **Schedule**: (in timezone America/New_York) - Branch creation - "before 6am on monday" - Automerge - At any time (no schedule defined) 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://github.com/renovatebot/renovate).

renovate-bot added 1 commit

2026-09-14 06:18:38 +00:00

chore(deps): update dependency timezonefinder to v9

CI / test (pull_request) Successful in 7m6s

Details

116ed57b6e