pycrestron-cip 0.1.0__tar.gz

pycrestron_cip-0.1.0/.github/workflows/auto-pr.yml

@@ -0,0 +1,155 @@
+name: Auto PR to main
+
+on:
+  push:
+    branches: [development]
+
+concurrency:
+  group: auto-pr
+  cancel-in-progress: true
+
+jobs:
+  create-pr:
+    runs-on: ubuntu-latest
+    # Skip if the push is the release workflow syncing main back into
+    # development (prevents loop; message comes from `git merge origin/main`)
+    if: ${{ !contains(github.event.head_commit.message, 'Merge remote-tracking branch ''origin/main''') }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Check for meaningful diff
+        id: diff
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Only create PR if development is actually ahead of main
+          if git diff origin/main...origin/development --quiet; then
+            echo "has_diff=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_diff=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build changelog
+        if: steps.diff.outputs.has_diff == 'true'
+        id: changelog
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          pr_numbers=$(git log origin/main..origin/development --first-parent --format='%s' \
+            | sed -nE 's/^Merge pull request #([0-9]+).*/\1/p; s/.* \(#([0-9]+)\)$/\1/p' \
+            | awk '!seen[$0]++' \
+            | head -50)
+
+          pr_lines=""
+          if [ -n "$pr_numbers" ]; then
+            while IFS= read -r number; do
+              [ -n "$number" ] || continue
+
+              line=$(gh pr view "$number" --json number,title,author \
+                --jq '"- #\(.number) \(.title) (@\(.author.login))"' 2>/dev/null || true)
+
+              if [ -n "$line" ]; then
+                pr_lines="${pr_lines}${line}\n"
+              fi
+            done < <(printf '%s\n' "$pr_numbers")
+          fi
+
+          commit_lines=$(git log origin/main..origin/development --oneline --no-merges | head -50)
+
+          {
+            echo 'body<<CHANGELOG_EOF'
+            echo '## Changes since last release'
+            echo ''
+
+            echo '### Merged pull requests'
+            if [ -n "$pr_lines" ]; then
+              printf '%b' "$pr_lines"
+            else
+              echo '- No pull requests detected from the unreleased commit range.'
+            fi
+
+            echo ''
+            echo '### Commits'
+            if [ -n "$commit_lines" ]; then
+              printf '%s\n' "$commit_lines"
+            else
+              echo '- No non-merge commits since main.'
+            fi
+
+            echo ''
+            echo '---'
+            echo "*Auto-generated from the development branch.*"
+            echo 'CHANGELOG_EOF'
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Determine release label
+        if: steps.diff.outputs.has_diff == 'true'
+        id: label
+        run: |
+          # Derive the version bump from conventional-commit messages in the
+          # unreleased range: breaking -> major, feat -> minor, else patch.
+          subjects=$(git log origin/main..origin/development --no-merges --format='%s')
+          bodies=$(git log origin/main..origin/development --no-merges --format='%b')
+
+          label="patch"
+          if printf '%s\n' "$subjects" | grep -qE '^feat(\([^)]*\))?:'; then
+            label="minor"
+          fi
+          if printf '%s\n' "$subjects" | grep -qE '^[a-z]+(\([^)]*\))?!:' ||
+             printf '%s\n' "$bodies" | grep -q 'BREAKING CHANGE'; then
+            label="major"
+          fi
+
+          echo "Suggested release label: ${label}"
+          echo "label=${label}" >> "$GITHUB_OUTPUT"
+
+      - name: Create or update PR development → main
+        if: steps.diff.outputs.has_diff == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          PR_BODY: ${{ steps.changelog.outputs.body }}
+          LABEL: ${{ steps.label.outputs.label }}
+        run: |
+          rank() {
+            case "$1" in
+              major) echo 3 ;;
+              minor) echo 2 ;;
+              patch) echo 1 ;;
+              *) echo 0 ;;
+            esac
+          }
+
+          # Check if an open PR from development → main already exists
+          existing_pr=$(gh pr list --base main --head development --state open --json number --jq '.[0].number')
+
+          if [ -n "$existing_pr" ]; then
+            echo "Updating PR #$existing_pr body with latest changelog."
+            gh pr edit "$existing_pr" --body "$PR_BODY"
+
+            # Apply the suggested label, but never override a human choice:
+            # leave no-release alone and never downgrade a version label.
+            labels=$(gh pr view "$existing_pr" --json labels --jq '.labels[].name')
+            if printf '%s\n' "$labels" | grep -qx 'no-release'; then
+              echo "PR is labeled no-release; leaving labels untouched."
+              exit 0
+            fi
+            current=$(printf '%s\n' "$labels" | grep -m 1 -xE 'major|minor|patch' | cat)
+            if [ "$(rank "$current")" -lt "$(rank "$LABEL")" ]; then
+              if [ -n "$current" ]; then
+                gh pr edit "$existing_pr" --remove-label "$current" --add-label "$LABEL"
+              else
+                gh pr edit "$existing_pr" --add-label "$LABEL"
+              fi
+              echo "Set release label: $LABEL"
+            fi
+          else
+            gh pr create \
+              --base main \
+              --head development \
+              --title "Merge development into main" \
+              --body "$PR_BODY" \
+              --label "$LABEL"
+          fi

pycrestron_cip-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main, development]
+  push:
+    branches: [main, development]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  workflow-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Lint GitHub Actions workflows
+        uses: docker://rhysd/actionlint:latest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov=pycrestron_cip --cov-report=term-missing
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*

pycrestron_cip-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,189 @@
+name: Release
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  bump-version:
+    if: >
+      github.event.pull_request.merged == true
+      && github.event.pull_request.head.ref == 'development'
+      && !contains(github.event.pull_request.labels.*.name, 'no-release')
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: main
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+
+      - name: Validate release label
+        id: bump
+        env:
+          LABELS: ${{ toJson(github.event.pull_request.labels.*.name) }}
+        run: |
+          count=$(echo "$LABELS" | jq '[.[] | select(. == "major" or . == "minor" or . == "patch")] | length')
+
+          if [ "$count" -ne 1 ]; then
+            echo "::error::Merged PRs to main must have exactly one version label: major, minor, or patch."
+            exit 1
+          fi
+
+          part=$(echo "$LABELS" | jq -r '[.[] | select(. == "major" or . == "minor" or . == "patch")][0]')
+          echo "part=${part}" >> "$GITHUB_OUTPUT"
+
+      - name: Detect existing release bump
+        id: state
+        env:
+          MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
+        run: |
+          head_message=$(git log -1 --format=%s main)
+          if printf '%s\n' "$head_message" | grep -qE '^Bump version to '; then
+            version=$(python3 -c "exec(open('src/pycrestron_cip/__version__.py').read()); print(__version__)")
+            echo "released=true" >> "$GITHUB_OUTPUT"
+            echo "version=${version}" >> "$GITHUB_OUTPUT"
+            echo "Main already points at release version ${version}."
+            exit 0
+          fi
+
+          first_descendant=$(git rev-list --ancestry-path --reverse "${MERGE_SHA}..main" | head -n 1)
+          if [ -n "$first_descendant" ]; then
+            first_message=$(git log -1 --format=%s "$first_descendant")
+            if printf '%s\n' "$first_message" | grep -qE '^Bump version to '; then
+              echo "released=true" >> "$GITHUB_OUTPUT"
+              echo "version=${first_message#Bump version to }" >> "$GITHUB_OUTPUT"
+              echo "Found existing release bump for this merge."
+              exit 0
+            fi
+          fi
+
+          echo "released=false" >> "$GITHUB_OUTPUT"
+
+      - name: Determine release version
+        id: version
+        run: |
+          if [ "${{ steps.state.outputs.released }}" = "true" ]; then
+            echo "version=${{ steps.state.outputs.version }}" >> "$GITHUB_OUTPUT"
+            echo "Reusing version ${{ steps.state.outputs.version }}"
+            exit 0
+          fi
+
+          FILE="src/pycrestron_cip/__version__.py"
+          CURRENT=$(python3 -c "exec(open('$FILE').read()); print(__version__)")
+          IFS='.' read -r major minor patch <<< "$CURRENT"
+
+          PART="${{ steps.bump.outputs.part }}"
+          if [ "$PART" = "major" ]; then
+            major=$((major + 1)); minor=0; patch=0
+          elif [ "$PART" = "minor" ]; then
+            minor=$((minor + 1)); patch=0
+          else
+            patch=$((patch + 1))
+          fi
+
+          NEW="${major}.${minor}.${patch}"
+          echo "__version__ = \"${NEW}\"" > "$FILE"
+          echo "version=${NEW}" >> "$GITHUB_OUTPUT"
+          echo "Bumped $CURRENT -> $NEW ($PART)"
+
+      - name: Commit and tag
+        if: steps.state.outputs.released != 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add src/pycrestron_cip/__version__.py
+          git commit -m "Bump version to ${{ steps.version.outputs.version }}"
+          git tag "v${{ steps.version.outputs.version }}"
+          git push origin main "refs/tags/v${{ steps.version.outputs.version }}"
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          if gh release view "v${{ steps.version.outputs.version }}" >/dev/null 2>&1; then
+            echo "GitHub release already exists for v${{ steps.version.outputs.version }}."
+          else
+            gh release create "v${{ steps.version.outputs.version }}" \
+              --title "v${{ steps.version.outputs.version }}" \
+              --generate-notes
+          fi
+
+  sync-development:
+    needs: bump-version
+    # Run for no-release merges too (bump-version is skipped then), so the
+    # merge commit on main always flows back into development.
+    if: >
+      always()
+      && github.event.pull_request.merged == true
+      && github.event.pull_request.head.ref == 'development'
+      && (needs.bump-version.result == 'success' || needs.bump-version.result == 'skipped')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: development
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Merge main into development
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          # Retry so a racing push to development can't leave the version
+          # bump stranded on main.
+          for attempt in 1 2 3; do
+            git fetch origin main development
+            git reset --hard origin/development
+            git merge origin/main --no-edit
+            if git push origin development; then
+              exit 0
+            fi
+            echo "Push rejected (attempt ${attempt}); retrying."
+            sleep 5
+          done
+          echo "::error::Failed to sync development with main after 3 attempts."
+          exit 1
+
+  publish:
+    needs: bump-version
+    if: needs.bump-version.result == 'success'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pycrestron-cip
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: v${{ needs.bump-version.outputs.version }}
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

pycrestron_cip-0.1.0/.github/workflows/version-label.yml

@@ -0,0 +1,50 @@
+name: Version label check
+
+on:
+  pull_request:
+    types: [opened, synchronize, labeled, unlabeled]
+    branches: [main]
+
+concurrency:
+  group: version-label-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  source-branch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Only development can target main
+        if: github.head_ref != 'development'
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+        run: |
+          echo "::error::Only the 'development' branch can target 'main'. Got '${HEAD_REF}'."
+          exit 1
+
+  version-label:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require exactly one release label
+        env:
+          LABELS: ${{ toJson(github.event.pull_request.labels.*.name) }}
+        run: |
+          no_release=$(echo "$LABELS" | jq '[.[] | select(. == "no-release")] | length')
+          version=$(echo "$LABELS" | jq '[.[] | select(. == "major" or . == "minor" or . == "patch")] | length')
+
+          if [ "$no_release" -ge 1 ] && [ "$version" -ge 1 ]; then
+            echo "::error::Cannot combine 'no-release' with a version label."
+            exit 1
+          fi
+
+          if [ "$no_release" -eq 1 ]; then
+            echo "Label: no-release — skipping version bump and publish."
+            exit 0
+          fi
+
+          if [ "$version" -ne 1 ]; then
+            echo "::error::PR to main must have exactly one label: major, minor, patch, or no-release."
+            exit 1
+          fi
+
+          label=$(echo "$LABELS" | jq -r '[.[] | select(. == "major" or . == "minor" or . == "patch")][0]')
+          echo "Version label found: $label"

pycrestron_cip-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+dist/
+build/
+.ruff_cache/
+.DS_Store

pycrestron_cip-0.1.0/CODEOWNERS

@@ -0,0 +1 @@
+*       @antonio112009

pycrestron_cip-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to pycrestron-cip
+
+Thank you for your interest in contributing! This document explains the workflow and guidelines.
+
+## Branch Strategy
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Stable release branch. Protected — no direct pushes. |
+| `development` | Integration branch. All feature work merges here first. |
+| `feature/*` | Short-lived branches for individual changes. |
+
+## Workflow
+
+1. **Create a feature branch** from `development`:
+   ```bash
+   git checkout development && git pull
+   git checkout -b feature/my-change
+   ```
+
+2. **Make your changes**, commit, and push:
+   ```bash
+   git push origin feature/my-change
+   ```
+
+3. **Open a Pull Request** targeting `development`. CI (lint + tests) must pass before merging.
+
+4. **When ready to release**, open a Pull Request from `development` → `main`. CI runs again.
+
+5. **On merge to `main`**, a release is created automatically:
+   - Version in `__version__.py` is bumped from the PR label
+   - A git tag and GitHub release are created
+   - Add exactly one of `patch`, `minor`, or `major` to the PR before merging
+
+## Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/Antonio112009/pycrestron-cip.git
+cd pycrestron-cip
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+## Linting
+
+This project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+ruff check .
+ruff format --check .
+```
+
+## Code Style
+
+- Python 3.13+, no runtime dependencies: the library must stay easy to install inside Home Assistant
+- Line length: 120 characters
+- Follow existing patterns in the codebase
+- Add tests for new functionality. Byte vectors should come from real captures where possible;
+  say which processor they come from
+- Never commit captures that contain addresses, passwords or names from a real installation
+
+## Project Structure
+
+```
+src/pycrestron_cip/
+├── client.py              # CipClient: connection, sync, heartbeats, reconnect, join caches
+├── protocol.py            # Frame encoding/decoding (no I/O)
+├── exceptions.py          # Exception hierarchy
+├── probe.py               # pycrestron-cip-probe: read-only recording tool
+└── testing.py             # FakeProcessor: a CIP server for tests
+docs/protocol.md           # Wire format notes and hardware findings
+```
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

pycrestron_cip-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio112009
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.