nwp500-python 9.3.1__tar.gz → 9.4.0__tar.gz

{nwp500_python-9.3.1 → nwp500_python-9.4.0}/.github/workflows/ci.yml

@@ -69,15 +69,45 @@ jobs:
 
       - name: Run tox tests
         run: tox -e default
-      - name: Install project testing extras (ensure pytest-asyncio present)
+
+  test-without-cli-extras:
+    # tox installs the cli extra, so the job above never exercises an
+    # install without click or rich. release.yml installs
+    # -e ".[testing]", which has neither, and a test module importing
+    # click above its ImportError guard failed there and nowhere else,
+    # after the release tag was already pushed. This job runs the
+    # release workflow's install so that failure surfaces on the pull
+    # request instead.
+    name: Test without CLI extras
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+
+      - name: Install project with testing extras only
         run: |
           python -m pip install --upgrade pip
-          python -m pip install '.[testing]'
+          python -m pip install -e ".[testing]"
+
+      - name: Verify the CLI extras really are absent
+        run: |
+          if python -c 'import click' 2>/dev/null; then
+            echo "click is installed; this job no longer tests what it claims to"
+            exit 1
+          fi
+
+      - name: Run tests
+        run: python -m pytest
 
   build:
     name: Build Distribution
     runs-on: ubuntu-latest
-    needs: [lint, test]
+    needs: [lint, test, test-without-cli-extras]
     
     steps:
       - uses: actions/checkout@v4

{nwp500_python-9.3.1 → nwp500_python-9.4.0}/CHANGELOG.rst

@@ -5,6 +5,189 @@ Changelog
 Unreleased
 ==========
 
+Version 9.4.0 (2026-09-12)
+==========================
+
+This release realigns the MQTT command set with what the NaviLink app
+actually sends. The app (version 2.03.00) was decompiled and its request
+builder compared with the library; every query it sends now has a
+method, six commands it never sends were removed, and the recirculation
+schedule write was corrected. Breaking changes are listed under
+*Removed* and *Changed*.
+
+Added
+-----
+- **Installer diagnostics query.** ``request_diagnostics()`` /
+  ``subscribe_diagnostics()`` and the ``nwp-cli diagnostics`` command
+  return the lifetime counters the app's installer screen shows: heat
+  pump and element energy, days since installation, fault event counts,
+  demand-response operation times, hot-water draw statistics and
+  component run times and start counts, as
+  :class:`~nwp500.models.DeviceDiagnostics`. The device answers the
+  ``st/td/rd`` query with packed hex; the NaviLink cloud decodes it into
+  JSON only when the reply topic has the app's five-segment form, so the
+  library requests that form. Verified live: the energies and compressor
+  and element run times match the energy query's lifetime totals.
+- **Monthly energy query.** ``request_energy_usage_monthly()`` /
+  ``subscribe_energy_usage_monthly()`` and ``nwp-cli energy --years``
+  return one entry per year with twelve per-month items. Verified live.
+- **Hourly energy query.** ``request_energy_usage_hourly()`` /
+  ``subscribe_energy_usage_hourly()`` send the app's per-hour query. The
+  NWP500 tested never answered it in four attempts, so it has no CLI
+  command.
+- **Recirculation schedule read.** ``request_recirculation_schedule()``
+  and ``nwp-cli recirc-schedule get``; the write is exposed as
+  ``nwp-cli recirc-schedule set``, which checks the JSON before
+  connecting (known keys only, integers in range, at most 20 entries).
+  The read was verified live on a unit that reports recirculation
+  scheduling but has no pump (empty, disabled schedule); the write and
+  its echo are unverified. The CLI reports a write as updated only when
+  the echo matches what was written. ``RecirculationSchedule`` and
+  ``RecirculationScheduleEntry`` fields are strict integers, so ``True``
+  or ``6.0`` is rejected instead of coerced.
+- **Firmware download info.** ``request_firmware_download_info()`` /
+  ``subscribe_firmware_download_info()`` and ``nwp-cli firmware info``
+  return :class:`~nwp500.models.FirmwareDownloadInfo`. The device replies
+  on its own topic rather than a client-keyed one. Verified live.
+- **Session end.** ``end_session()`` sends the ``st/end`` query the app
+  sends whenever it leaves a device. No reply to it has been observed.
+  Unlike other commands it is never queued while disconnected (it raises
+  ``MqttNotConnectedError``), since a session end replayed after a
+  reconnect would end the new session.
+- ``MqttConnectionConfig.send_session_end_on_disconnect`` (default
+  ``True``) controls whether ``disconnect()`` sends it.
+- ``subscribe_firmware_commit_response()`` receives the reply to
+  ``commit_firmware_update()``, which is requested on the app-form
+  ``res/commit-ota`` topic that no other subscription covers.
+- **Controls with app builder cases that had no method:**
+  ``set_vacation_duration(days)`` (``goout-day``; the app has a builder
+  case but no screen that calls it; verified live to change the day count
+  without changing the operation mode),
+  ``set_air_filter_life(hours)`` (``air-filter-life``; the wire value is
+  hours divided by 500, matching the app's 0 or 1000-10000 picker;
+  verified live) and ``reset_condenser_fault()`` (``cond-fault-reset``,
+  installer-level in the app; acknowledged live, clearing effect not
+  observable without a fault). CLI: ``vacation-duration``,
+  ``filter-life``, ``reset-condenser-fault``.
+- **Command codes** for every member of the app's ``DeviceControlMGPP``
+  enum, with the declared-but-never-sent ones annotated.
+- ``EnergyUsageResponse.type_of_usage``, ``get_year_data()``,
+  ``MonthlyEnergyData.day`` and ``EnergyUsageDay.ep_usage`` /
+  ``water_usage`` (declared by the app; not reported by the NWP500).
+
+Changed
+-------
+- **Recirculation schedule models take the app's entry shape** (breaking).
+  :class:`~nwp500.models.RecirculationScheduleEntry` is now
+  ``enable``/``week``/``hour``/``min``/``mode``/``param`` like a
+  reservation entry (``mode`` is the entry's pump on/off toggle in the
+  app's editor) and :class:`~nwp500.models.RecirculationSchedule` carries
+  ``reservation_use`` plus ``reservation`` instead of ``schedule``. The
+  previous start/end window fields were not what the device accepts.
+- ``MonthlyEnergyData.month`` is optional: monthly-query entries have no
+  month.
+- **``NavienMqttClient.disconnect()`` now sends ``st/end``** to every
+  device that was passed to any subscription, as the NaviLink app does
+  when it leaves a device. The publishes go straight to the connection,
+  never into the offline command queue, stop if the connection drops,
+  are bounded by a short timeout and never fail the disconnect. What it
+  does to other clients connected to the same device (for example a Home
+  Assistant integration) is not known; turn it off with
+  ``MqttConnectionConfig(send_session_end_on_disconnect=False)``.
+- **CLI energy summaries total the requested periods.** ``energy
+  --month``, ``--months`` and ``--years`` printed the device's lifetime
+  total under a per-month or per-year heading. Each summary now covers
+  only the rows shown, and the lifetime total is printed once under its
+  own heading. (The response's ``total`` is lifetime whatever is
+  requested; checked live.)
+- **Parameter validation.** ``set_air_filter_life()``,
+  ``set_vacation_duration()`` and the daily, monthly and hourly energy
+  queries reject non-integers (including ``True`` and floats) and
+  out-of-range values; years must be 2000-2099 and ``--years`` drops
+  duplicates. ``filter-life``, ``--year`` and ``--years`` reject bad
+  input before connecting. ``request_energy_usage()`` now rejects an
+  empty month list.
+
+Fixed
+-----
+- **``configure_recirculation_schedule()`` published to the wrong topic
+  with the wrong keys.** It sent ``{"schedule": [...]}`` on the bare
+  ``ctrl`` topic; the app publishes RECIR_RESERVATION on
+  ``ctrl/recirc-rsv/rd`` with ``reservationUse`` and ``reservation`` and
+  asks for the echo on ``recirc-rsv/rd``.
+- **``commit_firmware_update()`` published to the bare ``ctrl`` topic.**
+  The app publishes OTA_COMMIT on ``ctrl/commit-ota`` and asks for the
+  reply on ``res/commit-ota``; the library now does the same. Not
+  exercised against a device.
+- **Unsubscribing could remove the wrong handler.** When one callback was
+  registered for more than one device-wildcard subscription (status,
+  feature, firmware info), unsubscribing one removed whichever handler
+  came first. Handlers are now matched on subscription kind as well.
+- **Query replies could reach another device's callback.** Client-keyed
+  reply topics are shared by every device a client queries, so with two
+  devices subscribed a reservation, energy, TOU, diagnostics or
+  recirculation reply reached both callbacks. Typed subscriptions now
+  ignore replies whose ``macAddress`` names a different device.
+- Recirculation read-backs in hex carry the unused ``param`` as ``0xFF``
+  and in JSON as ``-1``; the model normalizes to ``-1`` so the two compare
+  equal.
+- **Protocol documentation** rewritten from the decompiled request
+  builder and live captures: real topic structure, the anti-legionella
+  modes (``anti-leg-on [days]`` / ``anti-leg-off``, not
+  ``anti-legionella-setting``), the message example that paired the
+  weekly-reservation code with ``dhw-temperature``, the undocumented
+  16777226 reservation write, response shapes for every query, and the
+  quick reference's invented ``header``/``body`` format with 0x11/0x21/0x31
+  codes that never existed. Stale ``docs/protocol/`` paths in code
+  comments and docstrings now point at ``docs/reference/protocol/``.
+- ``models/schedule.py`` docstrings cited 33554444 (the hot button) for
+  the recirculation reservation; it is 33554440.
+- CLI reference: token cache path is ``~/.nwp500_tokens.json``, ``-vv``
+  is a repeated ``-v`` (there was no ``--very-verbose``), and the
+  ``--unit-system`` option and ``tou rates``/``plan``/``apply`` commands
+  are documented.
+
+Removed
+-------
+- **Six MQTT commands the NaviLink app never sends** (breaking):
+  ``check_firmware_update()``, ``reconnect_wifi()``, ``reset_wifi()``,
+  ``set_freeze_protection_temperature()``, ``run_smart_diagnostic()`` and
+  ``update_weekly_reservation()`` with
+  ``subscribe_weekly_reservation_response()`` and the
+  ``WeeklyReservationEntry`` / ``WeeklyReservationSchedule`` models. The
+  app's enum declares the first five codes but its request builder has
+  no case for them, so the library's ``ota-check``, ``wifi-reconnect``,
+  ``wifi-reset``, ``frez-temp`` and ``smart-diagnostic`` mode strings were
+  invented. The app's weekly schedule is the ordinary reservation
+  program: it writes with 16777226 on ``ctrl/rsv/rd``
+  (``update_reservations()``), never with 33554438 or a ``rsv-weekly/rd``
+  topic. The ``CommandCode`` members stay, annotated as declared only.
+
+Version 9.3.2 (2026-09-01)
+==========================
+
+Fixed
+-----
+- **A null ``errorCode`` no longer makes ``/device/list`` unparseable.**
+  The cloud returns ``"error": {"errorCode": null}`` on some devices.
+  :class:`~nwp500.models.DeviceErrorSummary` typed the field
+  ``ErrorCode | int``, so validation of the whole listing failed and every
+  caller - including the Home Assistant integration, which could no longer
+  set up - lost the device entirely. ``error_code`` is now
+  ``ErrorCode | int | None`` and defaults to ``None``: a null means the
+  cloud reported no code, which is not the same claim as ``NO_ERROR``.
+  Callers that treated the field as always-present should handle ``None``.
+
+Security
+--------
+- **MAC address no longer logged in the clear when a reservations
+  unsubscribe fails.** ``fetch_reservations`` logged
+  ``device_info.mac_address`` unredacted in its cleanup warning, while the
+  identical warning in ``update_reservations_confirmed`` a few lines below
+  passed it through ``redact_mac``. CodeQL flagged it as
+  ``py/clear-text-logging-sensitive-data`` (high). Both call sites now
+  redact.
+
 Version 9.3.1 (2026-08-29)
 ==========================
 
@@ -104,6 +287,7 @@ Fixed
   other clients on the same device. Query results the device routes back to a
   client-keyed topic, such as reservations and energy usage, were already
   covered by the existing response wildcard.
+
 Version 9.3.0 (2026-08-03)
 ==========================
 

{nwp500_python-9.3.1 → nwp500_python-9.4.0}/Makefile

@@ -53,10 +53,11 @@ build: clean  ## Build distribution packages
 check-release: lint format-check test validate-version  ## Run all checks before release (lint, format check, tests, version validation)
 	@echo "✓ All checks passed! Ready for release."
 
-release: check-release build  ## Prepare and build a release (run checks, then build)
+release: check-release build  ## Run the release checks and build locally (does not publish)
 	@echo "✓ Release build complete!"
-	@echo "To publish to TestPyPI: make publish-test"
-	@echo "To publish to PyPI: make publish"
+	@echo "This built locally and published nothing."
+	@echo "To release: make version-bump BUMP=patch, then push main and the tag."
+	@echo "Pushing the tag is what publishes to PyPI. See RELEASE.md."
 
 publish-test:  ## Publish to TestPyPI
 	python -m twine check dist/*

{nwp500_python-9.3.1/src/nwp500_python.egg-info → nwp500_python-9.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 9.3.1
+Version: 9.4.0
 Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
 Home-page: https://github.com/eman/nwp500-python
 Author: Emmanuel Levijarvi

nwp500_python-9.4.0/RELEASE.md

@@ -0,0 +1,418 @@
+# Release Process
+
+This document describes the release process for nwp500-python, including code quality checks, formatting, and publishing.
+
+## Prerequisites
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+# or
+make install-dev
+```
+
+## Quick Release
+
+Despite the name, this does not release anything - it runs the checks and
+builds locally so you can see the release is in a fit state:
+
+```bash
+make release
+```
+
+This will:
+1. Run linting checks
+2. Verify code formatting
+3. Run all tests
+4. Validate the version configuration
+5. Clean build artifacts
+6. Build distribution packages
+
+Releasing is `make version-bump` followed by pushing the tag, which hands off
+to CI. See [The Release Runs Itself](#5-the-release-runs-itself).
+
+## Step-by-Step Release Process
+
+### 1. Code Quality Checks
+
+#### Format Code
+
+Format all code with ruff:
+
+```bash
+make format
+# or
+tox -e format
+```
+
+This will:
+- Automatically fix linting issues where possible
+- Format code to comply with PEP 8 and project standards
+- Sort imports according to isort rules
+
+#### Check Linting
+
+Check code without making changes:
+
+```bash
+make lint
+# or
+tox -e lint
+```
+
+#### Verify Formatting
+
+Check that code is properly formatted:
+
+```bash
+make format-check
+```
+
+### 2. Run Tests
+
+Run the test suite:
+
+```bash
+make test
+# or
+pytest
+```
+
+Run tests with coverage report:
+
+```bash
+make test-cov
+```
+
+### 3. Run All Checks
+
+Run all quality checks at once:
+
+```bash
+make check-release
+```
+
+This runs:
+- Linting checks
+- Format verification
+- Full test suite
+
+### 4. Update Version and Changelog
+
+#### Understanding Version Management
+
+**IMPORTANT**: This project uses `setuptools_scm` to manage versions from git tags.
+The version is **NOT** stored in any Python files or config files.
+
+**DO NOT** edit the `version` field in `setup.cfg`'s `[pyscaffold]` section!
+That field stores the PyScaffold tool version (4.6), not the package version.
+
+#### Version Bump Process
+
+The bump script owns the version heading, the changelog commit and the tag.
+Do not write any of them by hand - `scripts/extract_changelog.py` parses the
+heading it produces to build the GitHub release notes, and a hand-written
+duplicate silently breaks that.
+
+1. Make sure `CHANGELOG.rst` describes the release under `Unreleased`.
+
+   Add entries only - no `Version X.Y.Z` heading, no date. Normally each PR
+   has already added its own entry, so this is a review rather than a write:
+
+   ```rst
+   Unreleased
+   ==========
+
+   Fixed
+   -----
+   - **Something was broken.** It is no longer broken.
+   ```
+
+   If you edit anything here, commit it before continuing: the script
+   refuses to run on a dirty working directory.
+
+2. Run the bump script:
+
+   ```bash
+   # For a patch release (X.Y.Z -> X.Y.Z+1)
+   make version-bump BUMP=patch
+
+   # For a minor release (X.Y.Z -> X.Y+1.0)
+   make version-bump BUMP=minor
+
+   # For a major release (X.Y.Z -> X+1.0.0)
+   make version-bump BUMP=major
+
+   # Or specify an explicit version
+   make version-bump BUMP=3.1.5
+   ```
+
+   The script will:
+   - Refuse to run unless the working directory is clean
+   - Refuse to run if the branch is behind its upstream (it warns, but
+     continues, if the branch is ahead or has no upstream)
+   - Get the current version from git tags
+   - Calculate the new version and validate the progression (prevents large
+     jumps)
+   - Insert `Version X.Y.Z (YYYY-MM-DD)` under `Unreleased` in `CHANGELOG.rst`
+   - Commit that as `Update changelog for vX.Y.Z`
+   - Create the annotated tag `vX.Y.Z`
+
+3. Push the commit, then the tag:
+
+   ```bash
+   git push origin main
+   git push origin vX.Y.Z
+   ```
+
+   Push the commit first. The tag triggers the release, and the release notes
+   come from the changelog at that commit.
+
+#### Manual Version Tagging (Not Recommended)
+
+If you need to create a tag manually:
+
+```bash
+git tag -a vX.Y.Z -m "Release version X.Y.Z"
+git push origin vX.Y.Z
+```
+
+**Warning**: Manual tagging bypasses the clean-tree, not-behind-upstream and
+version progression checks, and does not touch the changelog - so unless you
+added the `Version X.Y.Z (YYYY-MM-DD)` heading yourself,
+`scripts/extract_changelog.py` finds no matching section and the GitHub release
+notes fall back to the bare line `Release X.Y.Z`. Use the version bump script
+instead.
+
+### 5. The Release Runs Itself
+
+Pushing a `v*` tag starts `.github/workflows/release.yml`, which is the only
+thing that publishes. In order, it:
+
+1. **Pre-release Checks** - `ruff check`, `ruff format --check`, and `pytest`
+   against an install of `-e ".[testing]"`
+2. **Build and Publish to PyPI** - `python -m build`, `twine check`, then
+   `pypa/gh-action-pypi-publish` via PyPI trusted publishing (no API tokens
+   are stored anywhere)
+3. **Create GitHub Release** - release notes extracted from the `Version
+   X.Y.Z` section of `CHANGELOG.rst`
+
+Each job depends on the one before it, so a failing check publishes nothing.
+
+Watch it:
+
+```bash
+gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')
+```
+
+Then confirm the result:
+
+```bash
+gh release view vX.Y.Z
+pip index versions nwp500-python
+```
+
+#### Do Not Publish By Hand
+
+`make publish` and `make publish-test` still exist as an emergency fallback,
+but a normal release must not use them. The workflow has already uploaded the
+artifacts by the time you could, and PyPI refuses to accept a version twice -
+so running them after a successful release fails, and running them before it
+makes the workflow fail instead. Publishing is CI's job.
+
+#### If the Release Fails After You Pushed the Tag
+
+The tag is the trigger, so a failing pre-release check leaves a tag on the
+remote pointing at a commit that was never released. Nothing was published -
+the publish job is gated behind the checks - so the version number is still
+free. Fix the problem, then move the tag:
+
+```bash
+# after committing the fix and pushing main
+git tag -d vX.Y.Z
+git push origin :refs/tags/vX.Y.Z
+git tag -a vX.Y.Z -m "Release version X.Y.Z"
+git push origin vX.Y.Z
+```
+
+Confirm first that nothing was published - if the publish job did succeed,
+that version is gone for good and you need a new patch version instead:
+
+```bash
+gh run view <run-id> --json jobs --jq '.jobs[] | "\(.name): \(.conclusion)"'
+pip index versions nwp500-python
+```
+
+### 6. Building Locally (Optional)
+
+Building locally is a sanity check, not part of publishing:
+
+```bash
+make build
+```
+
+This creates:
+- `dist/nwp500_python-X.Y.Z.tar.gz` (source distribution)
+- `dist/nwp500_python-X.Y.Z-py3-none-any.whl` (wheel)
+
+The version comes from `git describe`, so building on an untagged commit
+produces a development version like `9.3.1.dev3+g1a2b3c4` - that is expected,
+and it is a quick way to confirm the tag you just created is what
+`setuptools_scm` sees.
+
+## Using Tox
+
+You can also use tox directly for all steps:
+
+```bash
+# Run lint checks
+tox -e lint
+
+# Format code
+tox -e format
+
+# Run tests
+tox
+
+# Build package
+tox -e build
+
+# Clean artifacts
+tox -e clean
+```
+
+## Ruff Configuration
+
+Ruff is configured in `pyproject.toml` with the following rules:
+
+- **Line length**: 88 characters (Black-compatible)
+- **Target version**: Python 3.7+
+- **Enabled rules**:
+  - `E`, `W`: pycodestyle errors and warnings
+  - `F`: Pyflakes
+  - `I`: isort (import sorting)
+  - `UP`: pyupgrade (Python version upgrades)
+  - `B`: flake8-bugbear (common bugs)
+  - `C4`: flake8-comprehensions
+  - `SIM`: flake8-simplify
+
+### Checking Specific Files
+
+```bash
+# Check specific file
+ruff check src/nwp500/auth.py
+
+# Format specific file
+ruff format src/nwp500/auth.py
+
+# Check and fix specific directory
+ruff check --fix src/nwp500/
+```
+
+## Troubleshooting
+
+### Linting Errors
+
+If you encounter linting errors:
+
+1. Try auto-fixing: `make format`
+2. Review remaining errors: `make lint`
+3. Manually fix any errors that can't be auto-fixed
+4. Re-run checks: `make check-release`
+
+### Test Failures
+
+If tests fail:
+
+1. Review the test output
+2. Fix the issues in the code
+3. Re-run tests: `make test`
+4. Ensure all tests pass before release
+
+### Build Errors
+
+If build fails:
+
+1. Clean build artifacts: `make clean`
+2. Verify dependencies are installed: `pip install -e ".[dev]"`
+3. Try building again: `make build`
+
+## Pre-Release Checklist
+
+Before releasing, ensure:
+
+- [ ] Everything intended for the release is merged to `main`
+- [ ] `CHANGELOG.rst` describes it all under `Unreleased`, with no
+      hand-written `Version X.Y.Z` heading
+- [ ] All code is formatted: `make format`
+- [ ] Linting passes: `make lint`
+- [ ] All tests pass: `make test`
+- [ ] Version configuration is valid: `make validate-version`
+- [ ] Documentation is up to date
+- [ ] Examples work correctly
+- [ ] Working directory is clean and `main` is in sync with the remote
+      (the bump script enforces both)
+- [ ] Build succeeds: `make build`
+
+Then bump, push, and let the workflow publish - see
+[The Release Runs Itself](#5-the-release-runs-itself).
+
+## Publishing Credentials
+
+There are none to set up. The release workflow publishes through
+[PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/): PyPI is
+configured to trust `release.yml` in this repository, and the job mints a
+short-lived token through the `pypi` GitHub environment using its
+`id-token: write` permission. No API token is stored in the repository, in
+GitHub secrets, or on your machine.
+
+`TWINE_USERNAME`/`TWINE_PASSWORD` and `~/.pypirc` are only relevant if you
+ever need the emergency `make publish` fallback, which a normal release must
+not use.
+
+## Continuous Integration
+
+Two workflows already cover this:
+
+**`.github/workflows/ci.yml`** - on pushes and pull requests:
+
+| Job | What it does |
+|-----|--------------|
+| Lint and Format Check | `tox -e lint` (`ruff check` and `ruff format --check`) |
+| Security Check | `ruff check --select S src/` |
+| Test on Python 3.14 | `tox -e default` - pytest and pyright, with the `cli` and `testing` extras |
+| Test without CLI extras | pytest against an `-e ".[testing]"` install, matching what `release.yml` does |
+| Build Distribution | `python -m build` plus `twine check` |
+
+**`.github/workflows/release.yml`** - on a `v*` tag: pre-release checks, then
+build and publish to PyPI, then create the GitHub release.
+
+`Test without CLI extras` exists because `tox` installs the `cli` extra while
+`release.yml` does not. Without it, a test module that imports `click` outside
+its `ImportError` guard passes every pull request and fails only once the
+release tag has been pushed.
+
+## Quick Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `make version-bump` | Bump version (requires BUMP=patch/minor/major/X.Y.Z) |
+| `make help` | Show all available commands |
+| `make install-dev` | Install with dev dependencies |
+| `make format` | Format code with ruff |
+| `make lint` | Check code with ruff |
+| `make test` | Run tests |
+| `make check-release` | Run all pre-release checks |
+| `make release` | Full release build process |
+| `make build` | Build distribution packages locally (CI builds what is published) |
+| `make clean` | Remove build artifacts |
+| `make publish-test` | Emergency fallback only - upload to TestPyPI by hand |
+| `make publish` | Emergency fallback only - upload to PyPI by hand |
+
+## More Information
+
+- [Ruff Documentation](https://docs.astral.sh/ruff/)
+- [Python Packaging User Guide](https://packaging.python.org/)
+- [Twine Documentation](https://twine.readthedocs.io/)
+- [Semantic Versioning](https://semver.org/)

{nwp500_python-9.3.1 → nwp500_python-9.4.0}/docs/explanation/index.rst

@@ -10,4 +10,5 @@ Understanding-oriented deep dives into the library's design and advanced feature
    advanced-features
    architecture
    tank-energy
+   tou-recovery-cap
    unknown-values