givenergy-cli 1.0.0__tar.gz

givenergy_cli-1.0.0/.bandit.yaml

@@ -0,0 +1 @@
+skips: []

givenergy_cli-1.0.0/.claude/settings.json

@@ -0,0 +1,19 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": {
+          "tool_name": "Edit|Write",
+          "file_pattern": "**/*.py"
+        },
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run ruff check --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\" && uv run ruff format \"$CLAUDE_TOOL_INPUT_FILE_PATH\"",
+            "statusMessage": "Linting and formatting..."
+          }
+        ]
+      }
+    ]
+  }
+}

givenergy_cli-1.0.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  # Python deps from pyproject.toml + uv.lock.
+  # Restrict to direct deps so transitive churn doesn't generate update PRs.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      pip-direct:
+        patterns: ["*"]
+    allow:
+      - dependency-type: "direct"
+
+  # Pin GitHub Actions versions; quiet cadence since these rarely change.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

givenergy_cli-1.0.0/.github/workflows/bump-givenergy-modbus.yml

@@ -0,0 +1,114 @@
+name: Bump givenergy-modbus
+
+# Triggered by a repository_dispatch event from dewet22/givenergy-modbus's
+# release workflow. Also exposed as workflow_dispatch for manual runs.
+on:
+  repository_dispatch:
+    types: [givenergy-modbus-release]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to bump givenergy-modbus to (e.g. 1.2.0)"
+        required: true
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Determine target version and base branch
+        id: ver
+        env:
+          DISPATCH_VERSION: ${{ github.event.client_payload.version }}
+          MANUAL_VERSION: ${{ inputs.version }}
+        run: |
+          NEW="${DISPATCH_VERSION:-$MANUAL_VERSION}"
+          if [ -z "$NEW" ]; then
+            echo "::error::no version supplied via client_payload.version or workflow inputs"
+            exit 1
+          fi
+          # Route the PR to the branch whose dependency range that major
+          # version belongs to. Update the case statement when a new release
+          # branch (and/or new modbus major) is introduced.
+          major="${NEW%%.*}"
+          case "$major" in
+            1) base=main ;;
+            2) base=v1.0 ;;
+            *)
+              echo "::error::no target branch configured for givenergy-modbus major $major (version $NEW)"
+              exit 1
+              ;;
+          esac
+          echo "new=$NEW" >> "$GITHUB_OUTPUT"
+          echo "base=$base" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ steps.ver.outputs.base }}
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Bump pin in pyproject.toml
+        env:
+          NEW: ${{ steps.ver.outputs.new }}
+        run: |
+          uv run --with packaging python - <<'PY'
+          import os, re, pathlib
+          from packaging.version import Version
+          new = os.environ["NEW"]
+          p = pathlib.Path("pyproject.toml")
+          text = p.read_text()
+          # Pin form: "givenergy-modbus>=X,<Y" — capture both bounds so the new
+          # floor can be validated against the existing cap before writing.
+          pin_re = re.compile(r'"givenergy-modbus>=([^",]+),<([^",]+)"')
+          m = pin_re.search(text)
+          if not m:
+              raise SystemExit("no givenergy-modbus pin with >=X,<Y form found in pyproject.toml")
+          upper = m.group(2)
+          # Compare against the release portion of NEW so e.g. "2.0.0rc1" is
+          # rejected against "<2.0.0" — otherwise uv would silently resolve the
+          # resulting spec to an empty version set.
+          if Version(Version(new).base_version) >= Version(upper):
+              print(
+                  f"::error::new version {new} violates existing upper cap <{upper}; "
+                  f"bump the cap manually in pyproject.toml first"
+              )
+              raise SystemExit(1)
+          p.write_text(pin_re.sub(f'"givenergy-modbus>={new},<{upper}"', text))
+          PY
+
+      - name: Refresh uv.lock
+        run: uv lock --upgrade-package givenergy-modbus
+
+      - name: Commit, push, open PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NEW: ${{ steps.ver.outputs.new }}
+          BASE: ${{ steps.ver.outputs.base }}
+        run: |
+          if git diff --quiet pyproject.toml uv.lock; then
+            echo "nothing to bump (pin already at ${NEW}?)"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          branch="bump/givenergy-modbus-${NEW}"
+          git checkout -B "$branch"
+          git add pyproject.toml uv.lock
+          git commit -m "fix(deps): bump givenergy-modbus to ${NEW}"
+          git push -f origin "$branch"
+
+          existing=$(gh pr list --head "$branch" --json number --jq '.[0].number // empty')
+          if [ -n "$existing" ]; then
+            echo "PR #${existing} already open for ${branch}; updated branch in place"
+          else
+            gh pr create \
+              --title "fix(deps): bump givenergy-modbus to ${NEW}" \
+              --body "Automated bump triggered by [givenergy-modbus@${NEW}](https://github.com/dewet22/givenergy-modbus/releases/tag/v${NEW})." \
+              --base "$BASE" \
+              --head "$branch"
+          fi

givenergy_cli-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,145 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Version bump type (ignored when republish_tag is set)
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+          - prerelease
+          - finalize
+      prerelease_stage:
+        description: With major/minor/patch — start a prerelease line (e.g. major + alpha → 2.0.0a1). With prerelease — advance the stage forward-only (e.g. prerelease + rc on 2.0.0a6 → 2.0.0rc1).
+        required: false
+        default: none
+        type: choice
+        options:
+          - none
+          - alpha
+          - beta
+          - rc
+      republish_tag:
+        description: Existing tag to re-publish (e.g. v1.0.0a1). Skips bump/commit/tag and the GitHub Release creation; only builds and publishes to PyPI.
+        required: false
+        type: string
+
+jobs:
+  release:
+    # Pure-Python package: the wheel is platform-independent, so a single
+    # Ubuntu runner is sufficient.
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      # Required for PyPI trusted publishing via OIDC (no API token).
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          # For republish: check out the tagged commit so the build picks up
+          # the exact pyproject.toml/uv.lock state that was originally released.
+          ref: ${{ inputs.republish_tag || github.ref }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Determine version
+        id: version
+        env:
+          BUMP: ${{ inputs.bump }}
+          PRERELEASE_STAGE: ${{ inputs.prerelease_stage }}
+          REPUBLISH_TAG: ${{ inputs.republish_tag }}
+        run: |
+          if [ -n "$REPUBLISH_TAG" ]; then
+            # Republish path: derive version from the tag, skip the bump.
+            NEW="${REPUBLISH_TAG#v}"
+          else
+            CURRENT=$(uv version --short)
+            # `prerelease_stage=none` (or unset) means no prerelease flag passed.
+            if [ -n "$PRERELEASE_STAGE" ] && [ "$PRERELEASE_STAGE" != "none" ]; then
+              NEW=$(python3 scripts/release.py bump "$CURRENT" "$BUMP" --prerelease "$PRERELEASE_STAGE")
+            else
+              NEW=$(python3 scripts/release.py bump "$CURRENT" "$BUMP")
+            fi
+            uv version "$NEW"
+            uv lock
+          fi
+          echo "version=$NEW" >> $GITHUB_OUTPUT
+          # Expose whether this is a prerelease so downstream steps can mark it.
+          if [[ "$NEW" =~ (a|b|rc)[0-9]+$ ]]; then
+            echo "prerelease=true" >> $GITHUB_OUTPUT
+          else
+            echo "prerelease=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Generate CHANGELOG section
+        if: inputs.republish_tag == ''
+        id: changelog
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          BODY=$(python3 scripts/release.py generate "$VERSION")
+          {
+            echo 'body<<EOF_BODY'
+            echo "$BODY"
+            echo 'EOF_BODY'
+          } >> $GITHUB_OUTPUT
+
+      - name: Commit and tag
+        if: inputs.republish_tag == ''
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml CHANGELOG.md uv.lock
+          git commit -m "chore: release ${{ steps.version.outputs.version }}"
+          git tag "v${{ steps.version.outputs.version }}"
+          git push
+          git push origin "v${{ steps.version.outputs.version }}"
+
+      - name: Build
+        run: uv build
+
+      - name: Create GitHub Release
+        if: inputs.republish_tag == ''
+        uses: softprops/action-gh-release@v3
+        with:
+          tag_name: v${{ steps.version.outputs.version }}
+          name: v${{ steps.version.outputs.version }}
+          body: ${{ steps.changelog.outputs.body }}
+          files: dist/*.whl
+          draft: false
+          prerelease: ${{ steps.version.outputs.prerelease == 'true' }}
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+      - name: Wait for PyPI to index the new version
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          # pypa/gh-action-pypi-publish returns once PyPI accepts the upload,
+          # but there is a brief eventual-consistency window before the new
+          # version is resolvable by `pip install` / `uv lock`. Hold the run
+          # open until the JSON API confirms the version is indexed so anyone
+          # tailing the workflow knows when the release is genuinely live.
+          URL="https://pypi.org/pypi/givenergy-cli/$VERSION/json"
+          for attempt in $(seq 1 60); do
+            if curl -fsSL "$URL" > /dev/null 2>&1; then
+              echo "PyPI has indexed $VERSION (attempt $attempt)"
+              exit 0
+            fi
+            echo "Attempt $attempt/60: $VERSION not yet resolvable, sleeping 10s..."
+            sleep 10
+          done
+          echo "::error::PyPI did not index $VERSION within 10 minutes"
+          exit 1

givenergy_cli-1.0.0/.gitignore

@@ -0,0 +1,141 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.envrc
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# PyCharm
+.idea/
+
+# Claude Code — local-only, not shared
+.claude/settings.local.json
+.claude/worktrees/
+
+# Scratch exports from manual `givenergy-cli export` runs — these contain real
+# serial numbers and aren't fixtures
+test*.json

givenergy_cli-1.0.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/) and the
+project adheres to [Semantic Versioning](https://semver.org/). Sections are
+generated at release time by `scripts/release.py generate`, which walks
+`git log <last-v-tag>..HEAD` and buckets entries by conventional-commit
+prefix. A per-commit `Changelog: <section>` or `Changelog: skip` git
+trailer overrides the automatic bucketing.
+
+## [1.0.0] - 2026-05-22
+
+### 🔧 Maintenance
+
+- align README Python requirement with pyproject (3.14+) (#11) ([238b87c](https://github.com/dewet22/givenergy-cli/commit/238b87c2da52ee24acc178088a4467be47934f76))
+

givenergy_cli-1.0.0/KNOWN_ISSUES.md

@@ -0,0 +1,31 @@
+# Known issues
+
+Things the dashboard doesn't handle cleanly today, with enough context to
+revisit when they actually bite.
+
+## Third-party generation sources on the same AC bus
+
+The inverter's `p_load_demand` register is computed by the inverter from
+what it's delivering at its AC port plus/minus what flows through to the
+grid meter. The inverter assumes it's the only generator on the AC bus.
+
+If another inverter, a generator, or some other AC source is back-feeding
+the same circuit:
+
+- `p_load_demand` will under-report by however much the third party is
+  contributing, and can go **negative** when the other source overproduces
+  past the house's consumption.
+- The Loads box would render a negative kW value (the value formatter is
+  sign-aware but the sparkline and value column aren't designed to draw
+  attention to it).
+- The trunk animation still flows inverter → loads, even when the actual
+  net flow has reversed.
+- The EnergyBalance ledger's "Total Output" understates real output by the
+  third-party contribution, which would show up as a persistent positive
+  imbalance — easy to mistake for inverter conversion loss.
+
+I haven't fixed this because every GivEnergy install I've seen is
+single-inverter. If it ever becomes relevant we'd want either (a) a
+separate "External" source node in the diagram, (b) a third-party-detected
+annotation on the Grid or Loads box, or (c) a sign-aware Load renderer
+that flips its visual when load is net negative.