Bootstrap semantic PR #21 rebuild

[Komzpa]

Summary

This draft rebuilds the useful parts of #21 as a clean semantic stack on top of Komzpa/twms master. It intentionally keeps TWMS tiny and general-purpose: no broad service-specific defaults, no large framework rewrite, no license/author deletion, and no Java-factory-shaped architecture.

Current commits:

• 88cfbb9 bootstraps packaging and GitHub Actions CI.
• 1320671 adds legacy package smoke tests and compatibility shims.
• 47455de clears Python 3 syntax warnings without changing behavior.
• 996ce0b adds a no-network legacy GetTile smoke test.
• 60bd619 adds a tiny stdlib ThreadingHTTPServer entry point while keeping web.py/WSGI available as twms-webpy.
• f121d79 exposes TileJSON-style tileset metadata.
• 1ddb2bb exposes WMTS 1.0.0 capabilities plus REST and KVP tile access, with Radioxoma authorship preserved.
• 3989521 modernizes the filesystem tile cache with TTL, .tne, stale fallback, atomic replacement, and Radioxoma-style dead_tile dictionaries.
• c7c3b49 modernizes projection fallback with pole-edge clamping and optional pyproj.Transformer.
• 317dc88 adds tiny WMS 1.3.0 and CRS:84 support for QGIS-style clients without replacing WMS 1.1.1.
• 4aa6b65 rewrites README client/deployment docs for stdlib, web.py, QGIS, JOSM, WMTS, TileJSON, GetTile, shared caches, and optional dependencies.
• daed6f6 adds a Windows executable artifact job for twms.exe and twms-webpy.exe.
• 35c847e preserves filters, corrections, drawing, canvas, and reprojection surfaces with current Python/Pillow fixes.
• c24f53d validates downloaded image bytes before caching and converts mismatched tile responses to the configured layer extension.
• 237dac5 records HTTP 404 and configured dead_tile.http_status values as .tne cache misses.
• 2aa87ce accepts readable named tile URL placeholders while preserving legacy %s templates.
• 2980eaa generates JOSM maps-1.0 imagery XML.
• 041580c fixes atomic WMS cache writes by passing the intended image format explicitly.
• 61df8a7 supports optional per-layer HTTP headers for tile and WMS upstreams.
• a1339fa enforces per-layer min_zoom while preserving existing exclusive max_zoom.
• 7852d8a adds opt-in cache_layout: "zxy" while keeping TWMS' historical grouped cache layout by default.
• 98c39bd accepts readable named WMS URL placeholders while preserving legacy base-URL query appending.
• 794940b bounds upstream tile/WMS fetch waits with global/per-layer timeout config.
• faadb4e hardens stdlib REST routing and WMTS REST URLs with query strings.
• 2fe1b21 applies bounded upstream waits to the preserved legacy WmsCanvas.
• ad5ead4 restores legacy empty_color overlay transparency and empty_color_delta.
• 637ef8b keeps historical cache lookups and cached GetTile bytes binary-safe.
• eb261e0 keeps legacy cache_tile_responses binary-safe.
• a4e0d9e adds optional transient upstream retries without retrying HTTP/TNE statuses.
• 618a447 makes the RAM tile cache least-recently-used and fixes its bound.
• 0dc7b06 accepts MIME format keys such as image/png in cache_tile_responses.
• d99e15a documents the cookie decision: per-layer headers yes, automatic browser cookie discovery no.
• a85b8b4 keeps generated-artifact ignore hygiene without broad unrelated IDE/tooling ignores.
• 952f1ae accepts readable layer bounds metadata aliases.
• f168719 enriches JOSM imagery XML with bounds, overlay/default/georeference hints, attribution URLs, zoom limits, and no-tile checksums.
• b29d80d aligns the overview page with layer bounds aliases and provider URLs.
• edabf43 ships optional Windows batch and Linux desktop-entry launcher templates as packaged contrib files.
• b8b3d18 cancels stale CI runs for the same workflow event and branch.
• a86e856 accepts layer mimetype metadata as a readable alias/source for tile extensions while preserving legacy ext configs.
• f2522cc supports image/webp as a normal WMS output format while reusing the existing Pillow format path.
• d552b8a supports optional layer_defaults in Python configs through a tiny dict wrapper rather than importing the fork config rewrite.
• d0b1ed1 adds tiny stdlib route aliases for /wms tile/query URLs and /josm/maps.xml while keeping routing delegated to twms_main.
• 2cd346c prints useful stdlib-server startup URLs and includes the TWMS version in the HTTP Server header without importing the fork logging rewrite.
• fbf33d1 accepts readable string fetcher aliases such as "tms" and "wms" while resolving them back to the existing legacy fetcher functions.
• 7e4d2ed makes the import smoke check shell-portable so the same GitHub Actions workflow passes under Bash on Linux and PowerShell on Windows.

Branch behavior

The branch currently:

• adds GitHub Actions CI for Ubuntu and Windows on Python 3.11 and 3.13;
• adds a Windows executable artifact job for stdlib and preserved web.py entry points;
• modernizes packaging with pyproject.toml;
• preserves TWMS' public keyboard-style version as 0.07z, while exposing PEP 440 metadata as 0.7+z;
• replaces the removed Python 3.13 imp loader with importlib;
• keeps old package-style imports working without a large relative-import rewrite;
• keeps WMS 1.1.1, adds WMS 1.3.0/CRS:84, WMTS, TileJSON, JOSM imagery XML, overview metadata, and WebP WMS output;
• keeps GetTile because it is still useful for passing filters through tile URLs, including direct /wms/<layer>/<z>/<x>/<y> route aliases;
• keeps TWMS' built-in projection shortlist tiny, with optional pyproj for configured non-core projections;
• keeps historical cache layout by default, with optional z/x/y shared-cache layout;
• supports cache TTL, stale fallback, .tne, dead_tile, binary-safe response caches, layer headers, min zoom, timeouts, retries, and named upstream URL placeholders;
• accepts layer mimetype metadata as an alias/source for tile extensions while preserving existing ext configs;
• supports optional layer_defaults for shared layer metadata without merging defaults into every layer;
• accepts readable fetch aliases "tms" / "tile" and "wms" while preserving callable legacy fetchers;
• keeps /josm/imagery.xml, /josm/maps.xml, and /maps.xml as generated imagery-list aliases;
• prints stdlib-server startup URLs for overview, WMS, WMTS, and JOSM clients, and reports a versioned HTTP Server header;
• ships optional launcher templates for old Windows/JOSM proxy and Linux desktop/manual downstream deployments without installing desktop integration by default;
• preserves legacy filter, correction, WKT/GPX drawing, canvas, reprojection, tools, manpage, WSGI, and web.py deployment surfaces;
• credits Eugene Dvoretsky (Radioxoma) in COPYING and README for modernization work;
• keeps upstream Public Domain/ISC license text instead of taking the fork's license rewrite.

Validation

Clean-venv validation passed through current head 7e4d2ed2bf7ed793d040335f0a2af672a7150154:

• editable install in a clean venv
• python -m compileall -q setup.py index.py tools twms tests
• WSGI application import
• assertions that twms.__version__ == "0.07z" and installed package metadata is 0.7+z
• python -m unittest discover -s tests -v (75 tests, 1 optional pyproj skip)
• python -m build
• source distribution and wheel contents include contrib/twms.bat and contrib/twms.desktop
• git diff --check

The optional projection extra was also checked separately:

• pip install -e '.[proj]'
• python -m unittest tests.test_legacy_smoke.LegacySmokeTest.test_optional_pyproj_projection_uses_modern_transformer -v

The smoke suite covers WMS 1.1.1/1.3.0, CRS:84, GetTile, stdlib serving, stdlib startup banner, versioned HTTP Server header, TileJSON, WMTS capabilities/KVP/REST, JOSM imagery XML, overview HTML, cache TTL/TNE/stale/dead-tile behavior, binary cache reads/writes, layer headers, min/max zoom, zxy cache layout, named URL placeholders, upstream timeout/retry behavior, projection fallback, optional pyproj, legacy rendering helpers, layer bounds aliases, layer mimetype aliases, layer defaults, string fetcher aliases, WebP WMS output, stdlib WMS/JOSM route aliases, and Windows/package artifact contents.

GitHub Actions passed on current head 7e4d2ed2bf7ed793d040335f0a2af672a7150154:

• push run: https://github.com/Komzpa/twms/actions/runs/30205132979
• pull request run: https://github.com/Komzpa/twms/actions/runs/30205134325

Both runs passed Ubuntu and Windows package smoke jobs for Python 3.11 and 3.13, plus the Windows executable artifact job that builds and uploads twms.exe and twms-webpy.exe.

Selection notes

This branch deliberately rebuilds #21 as semantic pieces instead of merging the fork wholesale.

Taken, but reshaped to fit upstream TWMS:

• modern packaging, tests, GitHub Actions, and Windows executable artifacts;
• stdlib serving while preserving the existing web.py/WSGI deployment path;
• WMS 1.3.0, WMTS, TileJSON, JOSM imagery XML, and QGIS/JOSM documentation;
• cache TTL/TNE/stale-cache behavior, image validation, named URL templates, headers, min zoom, optional retries, and opt-in shared slippy-cache layout;
• projection modernization with a tiny built-in shortlist plus optional pyproj for non-core projections;
• readable metadata aliases such as bounds and mimetype;
• WebP output support as a tiny MIME/format-map extension;
• optional layer defaults as a small config-loader feature;
• readable string fetcher aliases as a config-loader adapter to the existing fetchers;
• tiny route aliases from the fork without importing the fork api.py split;
• stdlib startup URL hints and a versioned Server header without importing the fork logging/color-output rewrite;
• optional launcher templates as packaged contrib files.

Not taken from #21:

• the license rewrite and author/copyright removals;
• deletion of legacy filters, corrections, drawing, canvas, reprojection, tools, manpage, WSGI, or web.py deployment surfaces;
• the service-specific default provider config, DZZ/Firefox cookie auto-discovery, and browser-like global headers;
• the broad OOP fetcher/cache/config rewrite, including the thread-pool code that was described as async but still blocks on submit(...).result();
• provider-specific dynamic Google tile URL discovery from JavaScript;
• colored logging, debug trace output, and global logging rewrites;
• JOSM remote-control links embedded in the overview HTML; generated maps-1.0 imagery XML and documented TMS/file-cache setup cover JOSM without making the overview page active;
• the broad black/pre-commit/mypy/docstring formatting pass;
• the public version jump to semver-style 2.x naming.

Scope

Ready for review. The reciprocal Radioxoma branch update has been posted as radioxoma#1; that fork PR is expected to be a replace/rebase PR rather than a clean merge because the fork branch history diverged from upstream.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.