nwp500-python 7.4.5__tar.gz → 7.4.7__tar.gz

nwp500_python-7.4.7/.github/RESOLVING_PR_COMMENTS.md

@@ -0,0 +1,376 @@
+# How to Resolve GitHub Review Comments
+
+This guide documents how to mark review comment conversations as resolved after addressing reviewer feedback in pull requests.
+
+## Quick Reference
+
+```bash
+# 1. Get all review threads for PR #74
+gh api graphql -f query='
+query {
+  repository(owner: "eman", name: "nwp500-python") {
+    pullRequest(number: 74) {
+      reviewThreads(first: 10) {
+        nodes {
+          id
+          path
+          line
+          isResolved
+        }
+      }
+    }
+  }
+}
+' | jq '.data.repository.pullRequest.reviewThreads.nodes'
+
+# 2. Resolve a specific thread
+gh api graphql -f query='
+mutation {
+  resolveReviewThread(input: {threadId: "PRRT_kwDOP_hNvM5ukIVT"}) {
+    thread { isResolved }
+  }
+}
+'
+```
+
+## Why Resolve Comments?
+
+- **Clarity**: Shows reviewers their feedback has been acted upon
+- **Workflow**: Prevents reviewers from re-reading already-addressed comments
+- **Signal Readiness**: Indicates PR is ready for another review pass
+- **Clean PR Interface**: Makes GitHub's PR conversation cleaner and easier to follow
+
+## Workflow: Address and Resolve
+
+### 1. Address the Comment
+
+Make the code changes requested by the reviewer:
+- Fix bugs
+- Update documentation
+- Refactor code
+- Add tests
+
+**Example:**
+```bash
+# Edit file based on comment
+nano src/nwp500/converters.py
+
+# Commit the change
+git add src/nwp500/converters.py
+git commit -m "Fix div_10 converter to handle string inputs"
+
+# Push to remote
+git push
+```
+
+### 2. Verify Tests Pass
+
+Run all validation before marking comments as resolved:
+
+```bash
+# Run tests
+pytest --ignore=tests/test_mqtt_hypothesis.py
+
+# Run linting
+make ci-lint
+
+# Run type checking
+python3 -m mypy src/nwp500 --config-file pyproject.toml
+```
+
+All must pass before proceeding.
+
+### 3. Get Review Thread IDs
+
+Query GraphQL to find threads that need resolving:
+
+```bash
+gh api graphql -f query='
+query {
+  repository(owner: "eman", name: "nwp500-python") {
+    pullRequest(number: 74) {
+      reviewThreads(first: 10) {
+        nodes {
+          id
+          path
+          line
+          isResolved
+        }
+      }
+    }
+  }
+}
+' | jq '.data.repository.pullRequest.reviewThreads.nodes'
+```
+
+**Output example:**
+```json
+[
+  {
+    "id": "PRRT_kwDOP_hNvM5ukIVT",
+    "path": "src/nwp500/converters.py",
+    "line": 125,
+    "isResolved": false
+  },
+  {
+    "id": "PRRT_kwDOP_hNvM5ukIVo",
+    "path": "tests/test_model_converters.py",
+    "line": 212,
+    "isResolved": false
+  }
+]
+```
+
+### 4. Identify Which Threads to Resolve
+
+Cross-reference the output with:
+1. Which file you modified
+2. Which line the comment was on (approximately)
+3. Whether `isResolved` is `false`
+
+### 5. Resolve the Threads
+
+For each thread you addressed:
+
+```bash
+gh api graphql -f query='
+mutation {
+  resolveReviewThread(input: {threadId: "PRRT_kwDOP_hNvM5ukIVT"}) {
+    thread {
+      isResolved
+    }
+  }
+}
+'
+```
+
+Success response:
+```json
+{
+  "data": {
+    "resolveReviewThread": {
+      "thread": {
+        "isResolved": true
+      }
+    }
+  }
+}
+```
+
+### 6. Verify All Are Resolved
+
+Re-run the query from Step 3 to confirm all addressed threads now show `"isResolved": true`:
+
+```bash
+gh api graphql -f query='
+query {
+  repository(owner: "eman", name: "nwp500-python") {
+    pullRequest(number: 74) {
+      reviewThreads(first: 10) {
+        nodes {
+          path
+          isResolved
+        }
+      }
+    }
+  }
+}
+' | jq '.data.repository.pullRequest.reviewThreads.nodes'
+```
+
+## Batch Resolving Multiple Threads
+
+If you have many threads to resolve, use a loop:
+
+```bash
+#!/bin/bash
+
+# Define thread IDs
+THREAD_IDS=(
+  "PRRT_kwDOP_hNvM5ukIVT"
+  "PRRT_kwDOP_hNvM5ukIVo"
+  "PRRT_kwDOP_hNvM5ukIVx"
+)
+
+# Resolve each one
+for thread_id in "${THREAD_IDS[@]}"; do
+  gh api graphql -f query="
+  mutation {
+    resolveReviewThread(input: {threadId: \"$thread_id\"}) {
+      thread { isResolved }
+    }
+  }
+  " && echo "✓ $thread_id resolved"
+done
+
+echo "All threads resolved!"
+```
+
+Or as a one-liner:
+
+```bash
+for id in PRRT_kwDOP_hNvM5ukIVT PRRT_kwDOP_hNvM5ukIVo PRRT_kwDOP_hNvM5ukIVx; do
+  gh api graphql -f query="mutation { resolveReviewThread(input: {threadId: \"$id\"}) { thread { isResolved } } }" && echo "✓ $id resolved"
+done
+```
+
+## Shell Function (Optional)
+
+Add this to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):
+
+```bash
+# Resolve a single GitHub PR review thread
+resolve-pr-thread() {
+  local thread_id="$1"
+  if [[ -z "$thread_id" ]]; then
+    echo "Usage: resolve-pr-thread THREAD_ID"
+    echo "Example: resolve-pr-thread PRRT_kwDOP_hNvM5ukIVT"
+    return 1
+  fi
+  
+  gh api graphql -f query="
+  mutation {
+    resolveReviewThread(input: {threadId: \"$thread_id\"}) {
+      thread { isResolved }
+    }
+  }
+  " | jq '.data.resolveReviewThread.thread.isResolved'
+}
+
+# Get all unresolved threads for a PR
+pr-threads() {
+  local pr_num="${1:?PR number required}"
+  gh api graphql -f query="
+  query {
+    repository(owner: \"eman\", name: \"nwp500-python\") {
+      pullRequest(number: $pr_num) {
+        reviewThreads(first: 10) {
+          nodes {
+            id
+            path
+            line
+            isResolved
+          }
+        }
+      }
+    }
+  }
+  " | jq '.data.repository.pullRequest.reviewThreads.nodes'
+}
+```
+
+Usage:
+```bash
+pr-threads 74                          # List all threads for PR #74
+resolve-pr-thread PRRT_kwDOP_hNvM5ukIVT  # Resolve one thread
+```
+
+## Special Cases
+
+### Unresolving a Thread
+
+If a reviewer asks for changes after you marked it resolved, unresolve it:
+
+```bash
+gh api graphql -f query='
+mutation {
+  unresolveReviewThread(input: {threadId: "PRRT_kwDOP_hNvM5ukIVT"}) {
+    thread {
+      isResolved
+    }
+  }
+}
+'
+```
+
+### Force-Pushed Commits
+
+When you amend and force-push commits:
+1. Old review threads remain resolvable
+2. Thread IDs don't change
+3. Line numbers may be different in new commits
+4. Comments still point to old code but threads can be resolved
+5. This is normal GitHub behavior - resolve all threads once your changes are complete
+
+### Multiple Changes to Same File
+
+If a reviewer left multiple comments on the same file and you addressed them all:
+1. Make all changes to the file
+2. Commit and push
+3. Get all thread IDs for that file
+4. Resolve each one individually
+
+## Troubleshooting
+
+### "Not Found" Error
+
+**Problem:**
+```
+{
+  "message": "Not Found",
+  "documentation_url": "https://docs.github.com/rest",
+  "status": 404
+}
+```
+
+**Solutions:**
+- Verify PR number is correct
+- Check you have access to the repository
+- Verify `gh auth status` shows you're authenticated
+- Try running `gh auth login` again
+
+### No Threads Returned
+
+**Problem:**
+```
+{
+  "data": {
+    "repository": {
+      "pullRequest": {
+        "reviewThreads": {
+          "nodes": []
+        }
+      }
+    }
+  }
+}
+```
+
+**Solutions:**
+- Verify PR number is correct
+- The PR may have only general comments (not review comments)
+- Try increasing `first: 10` to `first: 100` if there are many threads
+- Verify reviewers left inline code comments, not just PR comments
+
+### Thread Won't Resolve
+
+**Problem:**
+Mutation succeeds but `isResolved` still returns `false` on next check
+
+**Solutions:**
+- Wait a moment and query again (GitHub API may have delay)
+- Verify you're using the exact same thread ID
+- Check that you have write permissions on the repository
+- Try running `gh auth refresh` to refresh your token
+
+### Can't Find Thread ID for Comment I Fixed
+
+**Problem:**
+You fixed the code but can't find the matching thread ID
+
+**Possible Causes:**
+1. The comment was a general PR comment, not an inline code comment (can't be resolved)
+2. The thread was already resolved by someone else
+3. You're looking at the wrong PR number
+4. The comment was deleted by the reviewer
+
+**Solution:**
+Go to the PR on GitHub.com and manually verify the comment still exists and is an inline review comment (not a general comment).
+
+## References
+
+- [GitHub GraphQL API: resolveReviewThread](https://docs.github.com/en/graphql/reference/mutations#resolvereviewthread)
+- [GitHub GraphQL API: unresolveReviewThread](https://docs.github.com/en/graphql/reference/mutations#unresolvereviewthread)
+- [GitHub GraphQL API: Review Threads](https://docs.github.com/en/graphql/reference/objects#reviewthread)
+- [GitHub CLI: gh api](https://cli.github.com/manual/gh_api)
+- [GitHub: Review conversations](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#about-pull-request-reviews)

{nwp500_python-7.4.5 → nwp500_python-7.4.7}/.github/copilot-instructions.md

@@ -54,6 +54,71 @@ When working on pull requests, use the GitHub CLI to access review comments:
 
 This ensures you can address all feedback from code reviewers systematically.
 
+#### Marking Conversations as Resolved
+
+After addressing a review comment, mark the conversation as resolved to signal reviewers that the feedback has been acted upon.
+
+**Step 1: Get review thread IDs**
+```bash
+gh api graphql -f query='
+query {
+  repository(owner: "eman", name: "nwp500-python") {
+    pullRequest(number: 74) {
+      reviewThreads(first: 10) {
+        nodes {
+          id
+          path
+          line
+          isResolved
+        }
+      }
+    }
+  }
+}
+'
+```
+
+Replace `74` with the actual PR number. This returns thread IDs like `PRRT_kwDOP_hNvM5ukIVT`.
+
+**Step 2: Resolve a thread**
+```bash
+gh api graphql -f query='
+mutation {
+  resolveReviewThread(input: {threadId: "PRRT_kwDOP_hNvM5ukIVT"}) {
+    thread {
+      isResolved
+    }
+  }
+}
+'
+```
+
+Replace the thread ID with the one from Step 1. Success response shows `"isResolved": true`.
+
+**Step 3: Resolve multiple threads efficiently**
+```bash
+for id in PRRT_kwDOP_hNvM5ukIVT PRRT_kwDOP_hNvM5ukIVo PRRT_kwDOP_hNvM5ukIVx; do
+  gh api graphql -f query="
+  mutation {
+    resolveReviewThread(input: {threadId: \"$id\"}) {
+      thread { isResolved }
+    }
+  }
+  " && echo "✓ $id resolved"
+done
+```
+
+**Step 4: Verify all are resolved**
+Re-run Step 1 query and confirm all addressed threads show `"isResolved": true`.
+
+**Important Notes:**
+- Only inline code review comments can be resolved (not general PR comments)
+- Conversations remain resolvable even after force-pushing commits
+- When commits are amended and force-pushed, old thread IDs remain valid
+- If you need to reopen a resolved thread, use `unresolveReviewThread` mutation instead
+
+See detailed instructions at `.github/copilot-instructions.md` for more examples and troubleshooting.
+
 ### Before Committing Changes
 Always run these checks before finalizing changes to ensure your code will pass CI:
 1. **Linting**: `make ci-lint` - Ensures code style matches CI requirements

{nwp500_python-7.4.5 → nwp500_python-7.4.7}/.github/workflows/ci.yml

@@ -28,6 +28,25 @@ jobs:
       - name: Run tox lint
         run: tox -e lint
 
+  security:
+    name: Security Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      
+      - name: Install ruff
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ruff
+
+      - name: Run security checks (ruff bandit)
+        run: ruff check --select S src/
+
   test:
     name: Test on Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest

{nwp500_python-7.4.5 → nwp500_python-7.4.7}/.gitignore

@@ -38,6 +38,7 @@ htmlcov/*
 junit*.xml
 coverage.xml
 .pytest_cache/
+.hypothesis/
 
 # Diagnostics output
 diagnostics_output/
@@ -61,3 +62,9 @@ venv*/
 .secrets
 reference/*
 resources/*
+
+# Tool caches
+.mypy_cache/
+.ruff_cache/
+.bandit
+.agent/

{nwp500_python-7.4.5 → nwp500_python-7.4.7}/CHANGELOG.rst

@@ -2,6 +2,59 @@
 Changelog
 =========
 
+Version 7.4.7 (2026-02-17)
+==========================
+
+Added
+-----
+- **OpenEI Client Module**: New ``OpenEIClient`` async client (``nwp500.openei``) for browsing utility rate plans from the OpenEI API by zip code. Supports listing utilities, filtering rate plans, and fetching plan details. API key read from ``OPENEI_API_KEY`` environment variable.
+- **Convert TOU API**: ``NavienAPIClient.convert_tou()`` sends raw OpenEI rate data to the Navien backend for server-side conversion into device-ready TOU schedules with season/week bitfields and scaled pricing.
+- **Update TOU API**: ``NavienAPIClient.update_tou()`` applies a converted TOU rate plan to a device, matching the mobile app's ``PUT /device/tou`` endpoint.
+- **ConvertedTOUPlan Model**: New Pydantic model for parsed ``convert_tou()`` results (utility, name, schedule).
+- **CLI ``tou rates``**: Browse utilities and rate plans for a zip code (``nwp500 tou rates 94903``).
+- **CLI ``tou plan``**: View converted rate plan details with decoded pricing (``nwp500 tou plan 94903 "EV Rate A"``).
+- **CLI ``tou apply``**: Apply a rate plan to the water heater with optional ``--enable`` flag to activate TOU via MQTT.
+- **CLI Reservations Table Output**: ``nwp-cli reservations get`` now displays reservations as a formatted table by default with global status indicator (ENABLED/DISABLED). Use ``--json`` flag for JSON output.
+- **CLI ``anti-legionella set-period``**: New subcommand to change the Anti-Legionella cycle period (1-30 days) without toggling the feature. Use ``nwp-cli anti-legionella set-period 7`` to update cycle period.
+
+Changed
+-------
+- **``examples/advanced/tou_openei.py``**: Rewritten to use the new ``OpenEIClient`` and ``convert_tou()``/``update_tou()`` library methods instead of inline OpenEI API calls and client-side conversion.
+
+Fixed
+-----
+- **Week Bitfield Encoding (CRITICAL)**: Fixed MGPP week bitfield encoding to match NaviLink APK protocol. Sunday is now correctly bit 7 (128), Monday bit 6 (64), ..., Saturday bit 1 (2); bit 0 is unused. Affects all reservation and TOU schedule operations. Verified against reference captures.
+- **Enable/Disable Convention**: Fixed reservation and TOU enable/disable flags to use standard device boolean convention (1=OFF, 2=ON) instead of inverted logic. This aligns with other device binary sensors and matches app behavior. Global reservation status now correctly shows DISABLED when ``reservationUse=1``.
+- **Reservation Set Command Timeout**: Fixed ``reservations set`` subscription pattern that had extra wildcards preventing response matching. Command now receives confirmations correctly.
+- **Intermittent Fetch Bug**: Tightened MQTT topic filter for reservation fetch from ``/res/`` to ``/res/rsv/`` with content validation to prevent false matches on unrelated response messages.
+
+Version 7.4.6 (2026-02-13)
+==========================
+
+Fixed
+-----
+- **Converter Consistency**: ``div_10()`` and ``mul_10()`` now correctly apply division/multiplication to all input types after ``float()`` conversion, not just ``int``/``float`` types
+- **Reservation Decoding**: Fixed ``decode_reservation_hex()`` to validate chunk length before checking for empty entries, preventing potential out-of-bounds access
+- **Factory Cleanup**: ``create_navien_clients()`` now properly cleans up auth session if authentication fails during context manager entry
+- **MQTT Reconnection**: MQTT client now resubscribes to all topics after successful reconnection
+- **Subscription Leak**: Fixed resource leak where ``wait_for_device_feature()`` did not unsubscribe its callback after completion
+- **Duplicate Handlers**: Subscription manager now prevents duplicate callback registration for the same topic
+- **Command Queue**: ``MqttCommandQueue`` now raises on ``QueueFull`` instead of silently swallowing the error
+- **Flow Rate Metadata**: Removed hardcoded ``"GPM"`` unit from ``recirc_dhw_flow_rate`` field; unit is now dynamic based on unit system
+- **Temperature Rounding**: ``RawCelsius`` Fahrenheit conversion now uses a catch-all default for standard rounding instead of matching only ``STANDARD`` enum value
+- **Unit System Default**: ``is_metric_preferred()`` now returns ``False`` (Fahrenheit) instead of ``None`` when no unit system override or context is set
+
+Security
+--------
+- **Sensitive Data Logging**: Redacted MQTT topics in subscription manager logging to prevent leaking device IDs (resolves CodeQL alerts)
+
+Added
+-----
+- **Auth Session Property**: Added ``NavienAuthClient.session`` property to access the active ``aiohttp`` session without using ``getattr``
+- **Unsubscribe Feature**: Added ``unsubscribe_device_feature()`` method to MQTT client and subscription manager for targeted callback removal
+- **Hypothesis Fuzzing**: Added property-based fuzzing tests for MQTT payload handling
+- **Bandit Security Scanning**: Added bandit configuration for security analysis in CI
+
 Version 7.4.5 (2026-02-04)
 ==========================
 

{nwp500_python-7.4.5/src/nwp500_python.egg-info → nwp500_python-7.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 7.4.5
+Version: 7.4.7
 Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
 Home-page: https://github.com/eman/nwp500-python
 Author: Emmanuel Levijarvi
@@ -29,6 +29,7 @@ Requires-Dist: setuptools; extra == "testing"
 Requires-Dist: pytest; extra == "testing"
 Requires-Dist: pytest-cov; extra == "testing"
 Requires-Dist: pytest-asyncio; extra == "testing"
+Requires-Dist: hypothesis; extra == "testing"
 Provides-Extra: dev
 Requires-Dist: ruff>=0.1.0; extra == "dev"
 Requires-Dist: pyright>=1.1.0; extra == "dev"
@@ -36,6 +37,7 @@ Requires-Dist: setuptools; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
 Dynamic: license-file
 
 =============
@@ -110,7 +112,7 @@ Basic Usage
         if device:
             # Access status information
             status = device.status
-            print(f"Water Temperature: {status.dhw_temperature}°F")
+            print(f"Water Temperature: {status.dhw_temperature}")
             print(f"Tank Charge: {status.dhw_charge_per}%")
             print(f"Power Consumption: {status.current_inst_power}W")
             

{nwp500_python-7.4.5 → nwp500_python-7.4.7}/README.rst

@@ -70,7 +70,7 @@ Basic Usage
         if device:
             # Access status information
             status = device.status
-            print(f"Water Temperature: {status.dhw_temperature}°F")
+            print(f"Water Temperature: {status.dhw_temperature}")
             print(f"Tank Charge: {status.dhw_charge_per}%")
             print(f"Power Consumption: {status.current_inst_power}W")
             

{nwp500_python-7.4.5 → nwp500_python-7.4.7}/docs/api/nwp500.rst

@@ -133,6 +133,14 @@ nwp500.mqtt\_events module
    :show-inheritance:
    :undoc-members:
 
+nwp500.openei module
+--------------------
+
+.. automodule:: nwp500.openei
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 nwp500.temperature module
 -------------------------
 

{nwp500_python-7.4.5 → nwp500_python-7.4.7}/docs/guides/advanced_features_explained.rst

@@ -499,5 +499,5 @@ See Also
 
 * :doc:`../protocol/data_conversions` - Temperature field conversions (HalfCelsiusToF, DeciCelsiusToF)
 * :doc:`../protocol/device_status` - Complete device status field reference
-* :doc:`scheduling_features` - Reservation and TOU integration points
+* :doc:`scheduling` - Scheduling and automation guide
 * :doc:`../python_api/models` - DeviceStatus model field definitions