jannikmi/timezonefinder

Follow-up to #350 / #509. The measurement below is the point of this issue: dropping holes today returns wrong timezones, so this is blocked on establishing an ordering guarantee, not on verifying one that already holds. The idea Every hole exists to say "this area is not the surrounding zone". But the area is always some other zone's polygon, and the lookup already tests those polygons. If a covering polygon is guaranteed to be tested before the surrounding one, the hole carries no information and can be dropped — along with the entire parallel data structure that serves it. That is the end state the original #350 description assumed. #509 delivered only the storage half (holes that duplicate a boundary polygon are stored as a reference to it); the structural half is this issue. What it would remove timezonefinder/data/holes/ (6 files) ~180 KB timezonefinder/data/hole_registry.json ~3 KB HoleArray (polygon_array.py) ~85 lines _iter_hole_ids_of, _holes_of_poly, _load_h

This package's whole position is border correctness: it stores every vertex of every polygon, unsimplified, and docs/alternatives.rst says plainly that if a wrong answer near a border is a rounding error rather than a bug, tzfpy is the better choice. But a caller cannot currently ask how close to a border they are — which is the question that tells them whether to trust the answer at all. The idea tf.distance_to_border(lng=..., lat=...) # -> metres tf.timezone_at(lng=..., lat=..., stable_within=50) # -> name, or a signal that 50 m of error could change it The applications that would want this all share a property: their input coordinates carry error comparable to the distances involved — consumer GPS (a few metres to tens of metres), fleet and mobility tracking, maritime and aviation, geocoded addresses. For those users "Europe/Berlin, and the nearest border is 400 m away" and "Europe/Berlin, and the nearest border is 3 m away" are very different answers, and today they a

docs/2_use_cases.rst answers its two headline questions like this: Creating aware datetime objects — check out the example script in examples/aware_datetime.py Getting a location's time zone offset — check out the example script in examples/get_offset.py So the two things most readers arrive wanting are never shown on the documentation site — a reader has to leave, find the repository, and open a file. These are also the highest-traffic questions the page exists to answer. Proposed: Inline the actual code for both, short and complete. Replace the pytz reference with stdlib zoneinfo. pytz remains an extra, but pointing at its documentation as the reference for offsets reads as dated on a Python ≥3.11 package. Add a warning about Etc/GMT±X: ocean zones use an inverted sign convention (Etc/GMT+5 is UTC−5), and since the packaged data covers the oceans, any coordinate at sea hits it. Anyone computing an offset by parsing the returned name will get it backwards. Point 3 is th

Several proposed optimisations are each justified by an assumption about which stage of a lookup dominates, and those assumptions are not all consistent with each other. One measurement settles them. #477 already showed that one such assumption — that a dict lookup is negligible — is wrong in the direction that matters, so this is not a formality. What is already known (#477, numba backend, macOS arm64) query total unique-zone hit 0.94 µs ocean hit 0.96 µs NYC 14.9 µs near a border (Basel) 28.9 µs — of which shortcut_mapping.get 68 ns So the unique-zone query is ~1 µs with no geometry touched, and the ambiguous query is 15–30× that and clearly dominated by the polygon loop. What is missing The breakdown inside those totals. Attribute time to validate_coordinates, h3.latlng_to_cell, shortcut resolution, zone_name_from_id, bbox rejection, ffi.from_buffer marshalling, and the point-in-polygon kernel itself. The clang-without-numba backend. #477 measured nu

Incorporate the feedback regarding the data parsing from #363: Officially supported and tested CLI functionality: extend the existing CLI module and tests. users can run a CLI command to generate the full dataset after pip installing the library rather than cloning the git repo and running a shell script. Example command: timezonefinder update_data [args] Should call the update_data.sh script documented make target for running file converter avoiding ImportError (scripts module couldn't be found) uv run python -m scripts.file_converter write output files to timezonefinder/data/ check in a reduced test polygon data set. include testing running the release script in the tests with the debug data set Completed: The parse_data.sh script does more than parsing the data. It downloads, runs the converter, runs tests, bumps the version, ... Calling it create_release.sh would be more accurate. I only needed the downloading and converting, so I commented out everything else. document