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

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

@@ -5,6 +5,31 @@ 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)
 ==========================
 

{nwp500_python-9.3.1 → 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.1/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.1
+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/)

{nwp500_python-9.3.1 → nwp500_python-9.3.2}/docs/openapi.yaml

@@ -196,12 +196,10 @@ paths:
                               type: integer
                               example: 2
                             modelTypeCode:
-                              type: integer
-                              nullable: true
+                              type: [integer, "null"]
                               example: null
                             installerId:
-                              type: string
-                              nullable: true
+                              type: [string, "null"]
                               example: null
                         location:
                           type: object
@@ -220,22 +218,19 @@ paths:
                           description: Last recorded device fault.
                           properties:
                             errorCode:
-                              type: integer
+                              type: [integer, "null"]
                               example: 0
                             errorOccuredTime:
-                              type: string
-                              nullable: true
+                              type: [string, "null"]
                               example: "2025-12-07T11:58:02"
                         descaling:
                           type: object
                           properties:
                             descalingStartTime:
-                              type: string
-                              nullable: true
+                              type: [string, "null"]
                               example: null
                             descalingEndTime:
-                              type: string
-                              nullable: true
+                              type: [string, "null"]
                               example: null
   /device/info:
     post:
@@ -311,23 +306,18 @@ paths:
                             type: number
                             example: -118.243683
                           altitude:
-                            type: object
-                            nullable: true
+                            type: [object, "null"]
                       installer:
                         type: object
                         properties:
                           installerId:
-                            type: object
-                            nullable: true
+                            type: [object, "null"]
                           installerFirstName:
-                            type: object
-                            nullable: true
+                            type: [object, "null"]
                           installerLastName:
-                            type: object
-                            nullable: true
+                            type: [object, "null"]
                           installerPhoneNumber:
-                            type: object
-                            nullable: true
+                            type: [object, "null"]
                       alarmInfo:
                         type: object
                         properties:
@@ -341,11 +331,9 @@ paths:
                         type: object
                         properties:
                           descalingStartTime:
-                            type: object
-                            nullable: true
+                            type: [object, "null"]
                           descalingEndTime:
-                            type: object
-                            nullable: true
+                            type: [object, "null"]
   /device/firmware/info:
     post:
       summary: Firmware Info
@@ -398,8 +386,7 @@ paths:
                               type: integer
                               example: 52
                             deviceGroup:
-                              type: object
-                              nullable: true
+                              type: [object, "null"]
                             curSwCode:
                               type: integer
                               example: 33556241
@@ -407,8 +394,7 @@ paths:
                               type: integer
                               example: 167837696
                             downloadedVersion:
-                              type: integer
-                              nullable: true
+                              type: [integer, "null"]
                               example: 0
   /device/tou:
     get:

{nwp500_python-9.3.1 → nwp500_python-9.3.2}/docs/reference/python_api/models.rst

@@ -95,9 +95,11 @@ remains readable while the device is offline.
 
    **Fields:**
 
-   * ``error_code`` (ErrorCode | int) - ``ErrorCode.NO_ERROR`` when there is no
-     recorded fault. A code the enum does not know is kept as a plain int rather
-     than failing the whole response.
+   * ``error_code`` (ErrorCode | int | None) - ``ErrorCode.NO_ERROR`` when the
+     device has no recorded fault, and ``None`` when the cloud reports no code
+     at all - it sends ``"errorCode": null`` on some devices, which is not the
+     same claim as "no error". A code the enum does not know is kept as a plain
+     int, so neither a null nor an unrecognised code fails the whole response.
    * ``error_occurred_time`` (str, optional) - When the fault was recorded, as an
      ISO-8601 string. Sent by the API under the misspelled key ``errorOccuredTime``.
 
@@ -108,8 +110,9 @@ remains readable while the device is offline.
       devices = await api.list_devices()
 
       for device in devices:
-          if device.error and device.error.error_code != ErrorCode.NO_ERROR:
-              code = device.error.error_code
+          code = device.error.error_code if device.error else None
+          # None is "the cloud told us nothing", not "no fault".
+          if code is not None and code != ErrorCode.NO_ERROR:
               # A code the enum knows arrives as an ErrorCode; anything else
               # falls back to a plain int, which has no .name.
               label = code.name if isinstance(code, ErrorCode) else f"code {code}"

{nwp500_python-9.3.1 → nwp500_python-9.3.2}/scripts/bump_version.py

@@ -375,11 +375,10 @@ def main() -> None:
 
     print("\n[OK] Version bump complete!")
     print("\nNext steps:")
-    print(f"  1. Push the tag:    git push origin v{new_version}")
-    print("     (also push the changelog commit: git push origin HEAD)")
-    print("  2. Build release:   make build")
-    print("  3. Test on TestPyPI: make publish-test")
-    print("  4. Publish to PyPI:  make publish")
+    print("  1. Push the changelog commit: git push origin HEAD")
+    print(f"  2. Push the tag:             git push origin v{new_version}")
+    print("\nThe tag triggers .github/workflows/release.yml, which runs the")
+    print("pre-release checks and publishes to PyPI. Do not publish by hand.")
 
 
 if __name__ == "__main__":