contribution-city 1.3.0__tar.gz

contribution_city-1.3.0/.github/workflows/tests.yml

@@ -0,0 +1,170 @@
+name: Tests and Quality Checks
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  lint:
+    name: Lint & Format Check (Ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+
+      - name: Install Ruff
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[dev]"
+
+      - name: Check code formatting and linting
+        run: |
+          ruff check .
+          ruff format --check .
+
+  test:
+    name: Test Suite (Python ${{ matrix.python-version }} on ${{ matrix.os }})
+    needs: lint
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies and package
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[dev]"
+
+      # Pixel comparisons against the approved baselines run once, in the "visual" job below,
+      # so a font or renderer difference on one operating system cannot fail the whole matrix.
+      - name: Run test suite with pytest
+        run: |
+          pytest --tb=short -m "not baseline"
+
+      - name: Verify CLI executable works
+        run: |
+          contribution-city generate --input examples/sample-contributions.json --theme navy-cyan --output dist/ci-test.svg
+          test -f dist/ci-test.svg || exit 1
+        shell: bash
+
+      - name: Test composite action directly
+        if: runner.os == 'Linux' && matrix.python-version == '3.12'
+        uses: ./
+        with:
+          input: examples/sample-contributions.json
+          theme: profile
+          appearance: auto
+          layout: compact
+          height-mode: linear
+          transparent: "true"
+          output: dist/composite-action-test.svg
+
+      - name: Check generated SVG is well-formed XML
+        if: runner.os == 'Linux' && matrix.python-version == '3.12'
+        run: python -c "import xml.dom.minidom as m; m.parse('dist/composite-action-test.svg'); print('well-formed')"
+        shell: bash
+
+      - name: Verify composite action output was generated
+        if: runner.os == 'Linux' && matrix.python-version == '3.12'
+        run: |
+          test -f dist/composite-action-test.svg || exit 1
+        shell: bash
+
+  visual:
+    name: Visual regression and gallery
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install dependencies and package
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[dev]"
+
+      - name: Compare renders with the approved baselines
+        run: |
+          contribution-city visual check --baseline-dir tests/visual/baselines --artifacts-dir visual-artifacts
+          pytest --tb=short -m baseline
+
+      - name: Upload comparison artifacts (only when the comparison fails)
+        if: failure()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: visual-regression-failures
+          path: visual-artifacts/
+          if-no-files-found: ignore
+          retention-days: 7
+
+      - name: Check that previews/ and the README grids are up to date
+        run: contribution-city previews --check --readme README.md
+
+      - name: Generate the preview gallery
+        if: always()
+        run: |
+          contribution-city gallery --output-dir gallery --fail-on-error
+          contribution-city check-svg gallery/svg/*.svg
+
+      - name: Upload the gallery (contact sheet, manifest, SVGs, thumbnails)
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: contribution-city-gallery
+          path: gallery/
+          if-no-files-found: ignore
+          retention-days: 14
+
+  build:
+    name: Build package
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel and check the reported version
+        run: |
+          python -m pip install --upgrade pip
+          pip wheel . --no-deps -w wheelhouse
+          pip install wheelhouse/*.whl
+          contribution-city --version
+          python -c "import contribution_city; print(contribution_city.__version__)"

contribution_city-1.3.0/.gitignore

@@ -0,0 +1,38 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing and coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+
+# IDE files
+.vscode/
+.idea/
+
+# Local generated output
+output/
+*.svg.tmp
+
+# Generated by `contribution-city gallery` and `contribution-city visual check`
+# (docs/gallery/ holds the small curated copies that ARE committed)
+/gallery/
+/visual-artifacts/
+/wheelhouse/
+dist/
+
+.venv-v13/

contribution_city-1.3.0/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+## 1.3.0 (2026-11-15)
+
+### Changed - please read
+- **The default building height is now the `standard` preset.** Buildings are proportionate to the
+  platform (at most about three tiles high) instead of the towers of 1.0 to 1.2. This changes the
+  look of every default render.
+  - To get the previous look exactly: `--height-preset tall` (action input `height-preset: tall`,
+    YAML `city.height_preset: tall`).
+  - **Existing configurations that set `building_scale`, `min_building_height` or
+    `max_building_height` without a preset are not reinterpreted:** they select the new `custom`
+    preset, which is the 1.2.0 look with their numbers.
+  - The preset (overall height profile) and the existing `--height-mode` (power, linear, sqrt, log;
+    the curve inside the profile) are independent settings.
+- The Python defaults of `building_scale`, `min_building_height` and `max_building_height` in
+  `RenderConfig` / `CitySettings` are now `None` ("use the preset") instead of 1.0 / 6.0 / 125.0. Code
+  that passes these values explicitly behaves as before.
+- `examples/config.example.yaml` now shows `height_preset` instead of the three explicit numbers.
+- The example workflows use `background:` instead of the legacy `transparent:` input.
+
+### Added
+- **Height presets:** `standard` (default), `tall` (the 1.0-1.2 look), `custom`
+  (`--height-preset`, action input `height-preset`, YAML `city.height_preset`), plus
+  `--min-building-height` / `--max-building-height` and validated limits for every height setting
+  (scale 0.1-5, minimum 0-40, maximum 8-400, canvas 100-10000 px).
+- **Building styles:** `--building-style detailed|solid`. `solid` draws plain boxes with three
+  shades: no windows, no rooftop beacons, no outlines. Works with every theme, layout, preset and view.
+- **Viewing angles:** `--view-angle isometric|low|high|top-down` (30, 20, 42 and 58 degrees of
+  camera elevation) and `--view-elevation DEGREES` (10-70). The projection, building heights,
+  platform, island and windows follow the camera; the default `isometric` view is byte-identical to
+  1.2.0.
+- **Preview gallery:** `previews/` with about 40 SVGs (themes, layouts, heights, building styles,
+  viewing angles, backgrounds), a README index per category, `manifest.json`, and the four preview
+  grids in the root README, all generated by the real renderer from deterministic sample data
+  (`contribution-city previews`, with `--check` for CI). Transparent previews have
+  `*.on-checkerboard.svg` companions; the real files stay transparent.
+- **Examples:** a complete customization guide (`examples/README.md`) and ready-to-copy workflows
+  (`basic-city`, `customized-city`, `solid-city`, `heights-and-angles`, `transparent-city`) and
+  configurations (`examples/config/`). Tests check that every workflow and every snippet in the guide
+  uses only real action inputs with valid values.
+- Action inputs: `height-preset`, `scale` (extended), `min-building-height`, `max-building-height`,
+  `building-style`, `view-angle`, `view-elevation`, with early validation of the enumerated values.
+- 70+ new visual cases and 43 approved baselines (was 35).
+
+### Fixed
+- On very small canvases the city could overflow: the fit scale was clamped at 0.5. It now shrinks as
+  far as needed (tests: every angle x layout x preset x canvas size stays inside the image).
+- Configuration validation hardening: non-finite and out-of-range tile dimensions are rejected, and
+  null, boolean, and invalid non-integer canvas dimensions are rejected with clean ConfigError messages.
+
+### Compatibility
+- For the same options, `--height-preset tall` reproduces 1.2.0 (and 1.1.0) output byte for byte, for
+  every theme and for the calendar and compact layouts (tested against references generated from the
+  1.1.0 source). Layout names, theme names, height modes, background behaviour and every CLI option of
+  1.2.0 are unchanged.
+
+## 1.2.0 (2026-10-27)
+
+### Added
+- **Themes:** `neon-harbor`, `cyberpunk`, `emerald-matrix`, `copper-forge`, `arctic-glass`,
+  `sunset-grid`. They are plain data in `renderer/palettes.py`; tests check text contrast, level
+  separation and window visibility for each.
+- **Layouts:** `dense-grid`, `downtown`, `floating-island`, `wireframe`, from a small layout registry
+  (`renderer/layouts.py`). `calendar` and `compact` are unchanged.
+- **Background modes:** `--background solid | transparent | transparent-sky | auto` (config
+  `city.background`, action input `background`). It takes precedence over the legacy `transparent`
+  flag, which keeps working; contradictory settings warn.
+- **Visual regression suite:** deterministic fixtures, a case registry generated from the theme and
+  layout registries, resvg-based PNG rendering, tolerance-based comparison that separates
+  antialiasing noise from real changes, approved baselines, failure artifacts (current, baseline,
+  diff, side-by-side, JSON) and an explicit `visual approve --yes` command. Baselines are never
+  written by tests or CI.
+- **Gallery:** `contribution-city gallery` writes SVGs, PNG thumbnails, a labelled contact sheet and a
+  deterministic `manifest.json` (settings, validation status, transparency probe, removed duplicates).
+- **`check-svg` command and `svgcheck` module:** well-formed XML, unique ids, resolving references,
+  no external resources or active content, matching viewBox.
+- **`--id-prefix`:** namespaces element ids and scopes the CSS so several SVGs can be inlined in one
+  page. Without it the ids are exactly the 1.1.0 ones.
+- **Offline `--year`, `--from`, `--to`** now filter `--input` files as well as live data.
+- Action: inputs `background` and `id-prefix`; early validation of `layout`, `appearance`,
+  `background`, `height-mode`; local execution tests of the real script (including hostile values).
+- CI: a `visual` job (baseline comparison, gallery, SVG checks, artifacts) and a `build` job that
+  checks the reported version. Example `gallery-artifact.yml` (read-only permissions).
+
+### Changed
+- Default output is byte-identical to 1.1.0 for the same input and options (tested against
+  references generated from the 1.1.0 source).
+- CLI help lists themes and layouts from the registries.
+- Window contrast of three palettes added in this cycle was raised after the contrast tests found it
+  too low (`neon-harbor`, `emerald-matrix`, `arctic-glass`).
+
+### Fixed
+- The gallery records a case with invalid options as `failed` instead of stopping.
+
+## 1.1.0
+
+### Fixed
+- **SVG escaping:** `custom_title` and the username were written into the SVG unescaped, which could
+  produce invalid XML (a broken image) or inject markup. All text is now escaped.
+- **Shell injection in `action.yml`:** inputs were pasted into the bash script. They now reach the
+  script only through environment variables, and the token is no longer passed on the command line.
+- **Version and name mismatches:** the version now lives in one place (`_version.py`) and is used by
+  the package, the build and the HTTP User-Agent. Docs, example workflow, license and author point
+  at `partialHuman/contribution-city`.
+- **README** contained the whole document twice; it now exists once.
+- **`isometric` layout** was only an alias of `calendar`. It was removed from the CLI, the action and
+  the config (a helpful error explains that `calendar` is the isometric view).
+- **Streaks** no longer treat missing dates in custom data as consecutive days.
+
+### Added
+- **Auto-fit:** the city is scaled to fill the canvas (`auto_fit`, `--no-fit` to turn it off).
+- **Light and dark:** `appearance: auto` embeds a light palette and follows `prefers-color-scheme`;
+  `transparent` removes the background. New themes: `profile`, `profile-light`, `navy-cyan-light`.
+- **Height modes:** `power` (default), `linear` (proportional), `sqrt`, `log`.
+- **Date ranges and several years:** `--year` (repeatable), `--from`, `--to`.
+- **Private contributions:** the count of restricted contributions is read and shown in the header.
+- **Retries** with exponential back-off for network errors, 5xx responses and secondary rate limits.
+- **Accessibility:** root `<title>`, `<desc>` and `role="img"` with totals.
+- **Pixel-art edges** (`crispEdges`) by default (`--smooth` to turn off).
+- `compact` layout leaves a tile between buildings so towers no longer hide each other.
+- Example workflow publishes to an `output` branch (one commit, no history growth) and shows the
+  light/dark `<picture>` setup. Third-party actions are pinned to commit SHAs.
+
+### Changed
+- Smaller files: empty tiles are one path with no tooltip, styling uses CSS classes, and windows are
+  four paths per building instead of a line each. The sample city went from about 308 KB to about
+  140 KB.
+- Raising the canvas size now enlarges the city (it used to stay at a fixed 18 px tile size).
+
+## 1.0.0
+- Initial release.

contribution_city-1.3.0/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,122 @@
+# Implementation summary: Contribution City 1.3.0
+
+Built from the 1.2.0 release archive. Everything below was implemented in the source and checked
+by running the commands listed under [Verification](#verification).
+
+## Read this first
+
+- **The reference SVGs and screenshots mentioned in the task did not arrive** (only the 1.2.0 ZIP was
+  attached). The *standard* height preset, the solid style and the angle presets were therefore
+  designed from the proportions described in the task and from the renderer's own geometry, not
+  matched to the images. The values are data in one file
+  ([`renderer/presets.py`](src/contribution_city/renderer/presets.py)) if you want to tune them to
+  your reference: `STANDARD` (min 3, max 56, growth 3.8, against the old 6 / 125 / 8.5) and
+  `VIEW_ANGLES` (30, 20, 42 and 58 degrees).
+- **The default look changes** (standard heights). The old look is `--height-preset tall`.
+  Configurations with explicit `building_scale` / `min_building_height` / `max_building_height` are
+  not reinterpreted. See [Backward compatibility](#backward-compatibility).
+
+## What was added
+
+| Area | New | Where |
+|---|---|---|
+| Heights | Presets `standard` (default), `tall`, `custom`; `--min-building-height`, `--max-building-height`; validated limits | `renderer/presets.py`, `renderer/svg.py`, `config.py`, `cli.py` |
+| Building style | `--building-style detailed\|solid` (solid: no windows, beacons or outlines; three shades) | `renderer/svg.py` |
+| Viewing angle | `--view-angle isometric\|low\|high\|top-down`, `--view-elevation 10-70` | `renderer/svg.py`, `renderer/presets.py` |
+| Gallery | `previews/` (41 SVGs in 6 categories, a README per category, `manifest.json`), four grids in the root README, `contribution-city previews [--check]` | `previews.py`, `previews/`, `README.md` |
+| Examples | `examples/README.md` (19-section guide), 5 new workflows, 4 new configurations | `examples/` |
+| Action | inputs `height-preset`, `min-building-height`, `max-building-height`, `building-style`, `view-angle`, `view-elevation`, early validation | `action.yml` |
+| Tests | 382 new tests (568 in 1.2.0, 950 collected now) | `tests/` |
+| Release | version 1.3.0, changelog section, CI job for gallery freshness | `_version.py`, `CHANGELOG.md`, `.github/workflows/tests.yml` |
+
+### Preset versus mode
+
+- **Height preset** = the overall profile (how tall the tallest building may be, and the growth rate).
+- **Height mode** (`power`, `linear`, `sqrt`, `log`, unchanged) = the curve from a day's count to a
+  height inside that profile. All four modes work with all presets (tested).
+
+### Defaults, identical in the CLI, YAML and the action
+
+| Setting | Default |
+|---|---|
+| height preset | `standard` (it stays unset and becomes `custom` only if scale or min/max are set without a preset) |
+| height mode | `power` |
+| building style | `detailed` |
+| view angle | `isometric` |
+| layout / theme / background | `calendar` / `navy-cyan` / `solid` |
+
+A test renders once with the CLI, once with a YAML file and once from Python with nothing set and
+requires identical SVGs; another does the same for every new option.
+
+## Backward compatibility
+
+- With `--height-preset tall`, output is **byte-identical to 1.2.0 and 1.1.0** for every original
+  theme in the calendar and compact layouts and for the other tested options (23 reference renders
+  generated from the original 1.1.0 source). The default `isometric` view is byte-identical to 1.2.0.
+- Explicit legacy height values keep their look: `RenderConfig(building_scale=1.0)` equals `tall`.
+- No theme, layout, height mode, background mode or CLI option was removed or renamed.
+- Python API change: the defaults of `building_scale`, `min_building_height` and
+  `max_building_height` in `RenderConfig` / `CitySettings` are `None` ("use the preset") rather than
+  1.0 / 6.0 / 125.0. Code that passes them explicitly is unaffected.
+
+## A bug found and fixed while testing
+
+On small canvases the auto-fit scale was clamped at 0.5, so the city could overflow the image. It
+now shrinks as far as needed (regression tests cover every angle x layout x preset x canvas size).
+
+## Verification
+
+Run in a clean copy of the final tree (Python 3.12.3, resvg-py 0.5.0, Pillow 13.0.0, Linux):
+
+| Command | Result |
+|---|---|
+| `pytest` | **949 passed, 1 skipped** (950 collected). The skip is intentional: one 1.1.0 reference sets `building_scale`, and a separate test covers that case. |
+| `pytest -m baseline` / `-m "not baseline"` | 46 passed / 903 passed, 1 skipped |
+| `ruff check .` | All checks passed |
+| `ruff format --check .` | 53 files already formatted |
+| `pip wheel . --no-deps` | `contribution_city-1.3.0-py3-none-any.whl` built; installed into a fresh virtual environment, `contribution-city --version` prints `1.3.0`, `contribution_city.__version__` is `1.3.0` |
+| CLI smoke tests from the installed wheel | 26 runs covering every preset, mode, style, view angle, background mode and layout: 26 ok, 0 failed. Invalid values print readable errors. |
+| `contribution-city check-svg` on those 26 outputs | all OK |
+| `contribution-city previews --check --readme README.md` | up to date (files and README grids) |
+| `contribution-city visual check` | 43 compared, 43 match |
+| `contribution-city gallery --fail-on-error` | 66 cases: 66 ok, 0 invalid, 0 failed |
+| Link test | every relative link and image in the READMEs, the guide and the preview indexes resolves |
+
+### Not run, and why
+
+- **The workflows were not executed on GitHub** (no GitHub access here). What was run: the action's real
+  bash script locally with controlled inputs (including hostile values), plus structural tests that
+  every `with:` key exists in `action.yml`, values are valid, third-party actions are pinned, permissions
+  are minimal and committing workflows cannot trigger themselves.
+- **Image links were checked locally** (the files exist at the relative paths); how GitHub renders them
+  was not observed.
+- **No browser test** of `prefers-color-scheme` inside `<img>`; the docs recommend the `<picture>` method
+  for GitHub.
+- The pixel baselines were produced and compared on Linux with one renderer version.
+- `@v1` in the examples resolves only after you publish the release and create or move the `v1` tag.
+
+## Known limitations
+
+- No oblique (non-symmetric) projection; the four presets change the camera elevation only.
+- `--no-fit` with a low or steep angle can leave the canvas (the default fit cannot).
+- The preview gallery uses dark themes; light-page rendering is covered by the `*-light` themes.
+- `downtown` is not chronological; `wireframe` on a transparent background uses the theme's paper colour
+  to hide lines.
+- Some documented GitHub screens (token creation, workflow permissions) may change wording over time.
+
+## Files
+
+**Added (72):** `previews/` (49 generated files, of which 41 SVGs), 8 new baseline images,
+`examples/README.md`, `examples/config/{all-options,solid,transparent,heights-and-angles}.yaml`,
+`examples/workflows/{basic-city,customized-city,solid-city,heights-and-angles,transparent-city}.yml`,
+`src/contribution_city/previews.py`, `src/contribution_city/renderer/presets.py`,
+`tests/test_v13_options.py`, `tests/test_docs_and_examples.py`, this file.
+
+**Modified (56):** `README.md`, `CHANGELOG.md`, `action.yml`, `.github/workflows/tests.yml`,
+`docs/visual-testing.md`, `docs/gallery/{contact-sheet.png,manifest.json}`, `examples/config.example.yaml`,
+`examples/workflows/generate-profile-city.yml`, `src/contribution_city/{_version,cli,config}.py`,
+`src/contribution_city/renderer/svg.py`, `src/contribution_city/visual/{cases,cli,fixtures}.py`,
+`tests/{snapshots/tiny_default.svg,test_action_execution,test_svg_quality,test_themes_layouts}.py`,
+and 35 re-approved baseline images plus their `index.json` (their default heights changed).
+
+**Removed (1):** `docs/gallery/new-in-1.2.png` (a generated image of the previous release).

contribution_city-1.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 partialHuman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.