nwp500-python 9.3.0__tar.gz → 9.3.2__tar.gz

{nwp500_python-9.3.0 → nwp500_python-9.3.2}/.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.0 → nwp500_python-9.3.2}/CHANGELOG.rst

@@ -5,6 +5,130 @@ Changelog
 Unreleased
 ==========
 
+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)
+==========================
+
+``NavienMqttClient.request_tou_settings()`` is removed. Not a breaking
+change in practice: the device never answered it, so no caller can have
+been getting a schedule out of it. Code that still names the method will
+now fail with ``AttributeError`` rather than time out. See Removed below.
+
+Added
+-----
+- **REST fields the cloud added since the models were written.**
+  ``/device/list`` now returns an ``error`` block (``errorCode``,
+  ``errorOccuredTime``) and the ``descaling`` block previously seen only
+  on ``/device/info``, and ``deviceInfo`` gained ``modelTypeCode`` and
+  ``installerId``. None of these were modelled, and ``NavienBaseModel``
+  ignores unknown keys, so all of them were silently discarded.
+  :class:`~nwp500.models.Device` gains optional ``error``
+  (:class:`~nwp500.models.DeviceErrorSummary`) and ``descaling``
+  (:class:`~nwp500.models.DescalingInfo`) sections, and
+  :class:`~nwp500.models.DeviceInfo` gains ``model_type_code`` and
+  ``installer_id``. ``error`` makes the device's last recorded fault
+  readable without an MQTT connection, including while the device is
+  offline. Every new field is optional, so responses that omit them - such
+  as ``/device/info``, which carries no ``error`` block - parse unchanged.
+  ``error_code`` is typed ``ErrorCode | int`` (validated left to right, so a
+  known code becomes an ``ErrorCode`` member and only an unknown one stays a
+  plain int) so an unrecognised code cannot make a whole listing unparseable. ``docs/openapi.yaml`` is
+  updated to match.
+
+Removed
+-------
+- **``request_tou_settings()`` removed - the device has no MQTT read for its
+  TOU schedule.** The method published a ``CommandCode.TOU_RESERVATION``
+  message to ``ctrl/tou/rd`` carrying only ``controllerSerialNumber``, then
+  waited for a reply on ``res/tou/rd``. No reply ever comes: a live device
+  with TOU provisioned (``program_reservation_use`` true, a valid controller
+  serial, and a plan the REST API returns in full) stayed silent for 45
+  seconds. ``ctrl/tou/rd`` with that command code is the *write* - it is what
+  :meth:`~nwp500.NavienMqttClient.configure_tou_schedule` publishes and what
+  the vendor app publishes from its TOU editor
+  (``TouScheduleViewmodel.setPublishMgppControlTou``) - and the device answers
+  on ``res/tou/rd`` only to confirm such a write. The vendor app reads TOU
+  over REST, which is the only TOU read the protocol has.
+
+  Beyond returning nothing, the call published a write-shaped command with no
+  schedule attached. This device ignored it - ``touStatus`` was unchanged
+  across repeated calls - but a firmware that took it at face value could read
+  it as "store an empty TOU schedule".
+
+  **Migration**: use :meth:`~nwp500.NavienAPIClient.get_tou_info`, which
+  returns the stored plan - rate name, utility, ZIP code and the seasonal
+  pricing intervals. The read itself is pure REST; it is keyed by the
+  controller serial number, which only the MQTT device-info response
+  publishes, so fetch that once and cache it.
+  :meth:`~nwp500.NavienMqttClient.subscribe_tou_response` is unaffected and
+  still delivers write confirmations. Enabling and disabling TOU
+  (:meth:`~nwp500.NavienMqttClient.set_tou_enabled`, command codes
+  ``TOU_ON``/``TOU_OFF``) is a separate path and is unaffected.
+
+Fixed
+-----
+- **CLI ``energy --months`` no longer duplicates ``--month`` output.**
+  ``handle_get_energy_request`` picked the view from the length of the
+  month list, so ``--months 5`` took the single-month branch and printed
+  the same daily breakdown as ``--month 5`` instead of the monthly
+  summary. The handler now takes an explicit ``daily`` flag set by the
+  option the user actually passed. ``energy`` also rejects ``--month``
+  and ``--months`` together rather than silently preferring ``--month``,
+  and validates the ``--months`` range and format the way ``--month``
+  already did. All of that validation now happens while Click parses the
+  arguments, so a bad invocation is a usage error (exit code 2) before any
+  authentication or MQTT connection is attempted - previously the command
+  body raised ``ClickException`` after connecting, where ``async_command``'s
+  catch-all reported it as an "Unexpected Error" with a traceback, and
+  anyone without working credentials saw an authentication failure instead
+  of the usage error. That catch-all now re-raises ``ClickException`` so any
+  command can report a usage error as itself.
+- **``DeviceFeature.mixing_valve_use`` now reads the device's actual key.**
+  The field was aliased to ``mixingValveUse``, but the device sends
+  ``mixingValueUse`` - "Value", not "Valve" - and the base model ignores
+  unknown keys, so the field silently reported its ``False`` default on
+  every device regardless of whether a thermostatic mixing valve was
+  supported. The CLI's "Mixing Valve" capability row was wrong for the
+  same reason. The misspelling is Navien's own: it appears in the vendor
+  app's ``KDResponseMgppDid$Feature`` class and in
+  ``docs/reference/protocol/device_features.rst``, which documented the
+  wire spelling correctly all along.
+
+- **``firmware_payload_capture.py`` captured almost nothing.** Its wildcards
+  covered ``cmd/{type}/{client_id}/res/#`` and the event topic, but the device
+  acknowledges control and query commands on
+  ``cmd/{type}/navilink-{mac}/{client_id}/res`` - which neither pattern
+  matches - so the device status and device info responses were missed, along
+  with every request published on the device path. A capture run recorded 2
+  payloads where it should have recorded 11. It now also subscribes to
+  ``cmd/{type}/navilink-{mac}/#``, which additionally picks up traffic from
+  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.0 → nwp500_python-9.3.2}/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.0/src/nwp500_python.egg-info → nwp500_python-9.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 9.3.0
+Version: 9.3.2
 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.3.2/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/)