Update dependency timezonefinder to v8.3.0

[renovate]

ℹ️ Note

This PR body was truncated due to platform limits.

This PR contains the following updates:

Package	Change	Age	Adoption	Passing	Confidence
timezonefinder	8.2.1 → 8.3.0

---

Release Notes

jannikmi/timezonefinder (timezonefinder)

v8.3.0

Compare Source

• 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

• 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()

• 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 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 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

• 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

• 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 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

• 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

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. 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
• compiled data directories are now checked for integrity where they are produced and where they are reviewed, by one shared set of assertions in scripts/data_integrity.py: the converter runs them over the files it just wrote, and the test suite runs them over the packaged binaries. They establish that the hole reference vector, the hole coordinate file and the hole bounding boxes agree with one another, and - the part with evidence independent of the references themselves - that every reference resolves to the geometry its bounding box was computed from, so a converter that mismatched a hole to the wrong boundary polygon fails loudly instead of shipping a plausible wrong timezone. Deliberately not run when a TimezoneFinder is constructed: whether a data directory is coherent is settled once, by the build, and re-deriving it in every user's process would spend startup time re-answering a question that already has an answer. Keeping it off that path is what allows the check to be thorough rather than cheap - it resolves every hole ring in the dataset
• 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

v8.2.5

Compare Source

• updated the data to 2026c <https://github.com/evansiroky/timezone-boundary-builder/releases/tag/2026c>__

v8.2.4

Compare Source

• added manylinux_2_28_x86_64 wheel to releases, fixing the fallback to version 6.0.1 when pip resolves with --platform manylinux_2_28_x86_64 (Python 3.14 + numpy 2.4). . Thanks to theirix <https://github.com/theirix>__ for the PR #​420

v8.2.3

Compare Source

• updated the data to 2026b <https://github.com/evansiroky/timezone-boundary-builder/releases/tag/2026b>__
• added examples and documentation for using parallel processing with the timezonefinder libary.

Internal:

• reduced code duplication in coordinate validators: extracted common validation logic into a reusable _validate_coordinate() helper function
• improved error handling and warning emission during __del__ resource cleanup
• refactored command_line.py for improved maintainability:
  • decomposed monolithic main() function into focused, independently testable components: _parse_arguments(), _lookup_timezone(), and _print_lookup_details()
  • reduced cyclomatic complexity and improved separation of concerns
• modernized codebase with Python 3.11+ features and best practices:
  • migrated from typing module imports to collections.abc for Iterable and Callable
  • added Self type annotation for context manager protocol
  • replaced conditional dispatches with match/case statements for improved clarity and maintainability
• using python 3.10+ type hints. Thanks to Marco Barbosa <https://github.com/aureliobarbosa>__
• enhanced test coverage:
  • added 8 comprehensive thread safety tests for concurrent singleton initialization
  • added 37 coordinate validation tests covering edge cases (NaN, Inf, boundary values)
• comprehensive code quality improvements for production-grade stability:
  • improved exception handling: replaced bare except clauses with specific

✂ Note

PR body was truncated to here.

---

Configuration

📅 Schedule: (UTC)

• Branch creation
  • At any time (no schedule defined)
• Automerge
  • At any time (no schedule defined)

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

♻ Rebasing: Whenever PR is behind base branch, 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 was generated by Mend Renovate. View the repository job log.