pysnapdog 0.1.0__tar.gz

pysnapdog-0.1.0/.editorconfig

@@ -0,0 +1,19 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+max_line_length = 100
+
+[*.{toml,yml,yaml,json,jsonc}]
+indent_size = 2
+
+[*.{ts,tsx,js,mjs,cjs}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

pysnapdog-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @metaneutrons

pysnapdog-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Report something that is not working as expected
+title: "[Bug] "
+labels: bug
+---
+
+**Describe the bug**
+A clear, short description of what is wrong.
+
+**To reproduce**
+Steps to reproduce the behavior:
+1. ...
+2. ...
+
+**Expected behavior**
+What you expected to happen instead.
+
+**Actual behavior**
+What actually happened (error messages, logs, screenshots).
+
+**Environment**
+- pysnapdog version:
+- SnapDog server version:
+- Python version:
+- OS / platform:
+- Minimal code that shows the problem (redact the API key):

pysnapdog-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature request
+about: Suggest an idea or enhancement for this project
+title: "[Feature] "
+labels: enhancement
+---
+
+**Problem**
+What problem or limitation are you running into? Why does it matter?
+
+**Proposed solution**
+What you would like to happen. Describe the feature or change you have in
+mind.
+
+**Alternatives considered**
+Any alternative solutions or workarounds you have considered.

pysnapdog-0.1.0/.github/dependabot.yml

@@ -0,0 +1,48 @@
+# Template. Goes to .github/dependabot.yml; delete the ecosystems the project
+# does not have.
+#
+# The grouping is deliberately separated by update kind. One group with
+# `patterns: ['*']` across all kinds bundles breaking changes with harmless
+# bumps, and one broken dependency then blocks the whole stack. Minor and patch
+# stay bundled, because checking them individually gains nothing there. Major
+# stays ungrouped, so that each case arrives on its own.
+#
+# `cooldown` keeps a version that is withdrawn shortly after publication out of
+# every pull request.
+# Without a `timezone`, times are in UTC. Anyone needing local execution times
+# enters a suitable IANA time zone per project.
+
+version: 2
+
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: '05:00'
+    open-pull-requests-limit: 5
+    cooldown:
+      default-days: 3
+      semver-major-days: 7
+    groups:
+      python-minor-patch:
+        patterns: ['*']
+        update-types: [minor, patch]
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: '05:15'
+    open-pull-requests-limit: 5
+    cooldown:
+      default-days: 3
+      # semver-major-days is not permitted for github-actions. If it stands
+      # here, Dependabot rejects the ENTIRE file and not a single update runs
+      # any more, not even a security update.
+    groups:
+      github-actions-minor-patch:
+        patterns: ['*']
+        update-types: [minor, patch]

pysnapdog-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+## What changed
+
+<!-- Briefly describe the change. -->
+
+## Why
+
+<!-- What problem does this solve, or what does it improve? -->
+
+## How it was tested
+
+<!-- e.g. `uv run pytest`, `uv run ruff check .`, `uv run mypy`, manual verification, new/updated tests. -->
+
+---
+
+- [ ] The PR title follows [Conventional Commits](https://www.conventionalcommits.org/)
+      (`type(scope): description`, `!` or `BREAKING CHANGE:` for breaking
+      changes) — it becomes the commit message on `main` after squash merge
+      and drives the release version and changelog.

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

@@ -0,0 +1,145 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Lint, types, tests (Python ${{ matrix.python }})
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.14']
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      # --locked fails when uv.lock does not match pyproject.toml. That is
+      # exactly what it is for.
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - name: Check the hook configuration
+        run: uv run lefthook validate
+      - run: uv run mypy
+      # The coverage floor (fail_under) lives in pyproject.toml.
+      - run: uv run pytest --cov
+      - name: Coverage of the server contracts
+        run: uv run python scripts/check_coverage.py
+      - name: Check the distribution content
+        run: |
+          set -euo pipefail
+          uv build --out-dir "$RUNNER_TEMP/dist"
+          unzip -l "$RUNNER_TEMP"/dist/*.whl | grep -E 'pysnapdog/(py.typed|client.py)'
+          tar -tzf "$RUNNER_TEMP"/dist/*.tar.gz | sort
+
+  security:
+    name: Secrets and advisories
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+      # The gitleaks action wants a licence for organisation repositories. The CLI it wraps
+      # does not, so run the pinned release binary and verify its checksum.
+      - name: Scan the history for secrets
+        run: |
+          set -euo pipefail
+          version=8.30.1
+          archive="$RUNNER_TEMP/gitleaks.tar.gz"
+          curl -sSfL -o "$archive" \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${version}/gitleaks_${version}_linux_x64.tar.gz"
+          echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb  $archive" | sha256sum -c -
+          tar -xzf "$archive" -C "$RUNNER_TEMP" gitleaks
+          "$RUNNER_TEMP/gitleaks" detect --source . --redact --no-banner --verbose
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: '3.14'
+      - run: uv sync --locked
+      - run: uv audit --preview-features audit-command
+
+  commit-hygiene:
+    name: Commit hygiene
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+      - name: Check title, body and every commit
+        # Title and body reach the script exclusively through env, never by
+        # interpolation into the script text: otherwise the pull request title
+        # would be a shell injection vector.
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          set -euo pipefail
+          status=0
+          cc='^((feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9._/-]+\))?!?: .+|Revert ".+")'
+          # grep works line by line, hence .* rather than [^\n]*: in ERE
+          # [^\n] would be the class "neither a backslash nor an n" and would
+          # exclude names containing an 'n'. In the RE2 rule of the ruleset
+          # [^\n] is the correct one. Anchored at the start of the line: by
+          # convention a trailer stands on a line of its own. Without the anchor
+          # the rule also fires when a pull request body merely mentions the
+          # forbidden trailer, for instance to describe a doctor finding, and it
+          # then rejects a valid input.
+          ban='^[[:space:]]*co-authored-by:.*(claude|anthropic)|^[[:space:]]*generated with.*claude code'
+
+          # On a squash merge the pull request title becomes the subject line
+          # on main and thereby determines the next version.
+          if ! printf '%s' "$PR_TITLE" | grep -Eq "$cc"; then
+            echo "::error::pull request title does not follow Conventional Commits: $PR_TITLE"
+            status=1
+          fi
+
+          # With squash_merge_commit_message=PR_BODY the body lands in the commit.
+          if printf '%s' "$PR_BODY" | grep -Eiq "$ban"; then
+            echo "::error::the pull request body contains an AI attribution trailer."
+            status=1
+          fi
+
+          for sha in $(git rev-list "${BASE_SHA}..${HEAD_SHA}"); do
+            if git log -1 --format=%B "$sha" | grep -Eiq "$ban"; then
+              echo "::error::commit $sha contains an AI attribution trailer."
+              status=1
+            fi
+            email=$(git log -1 --format='%ae%n%ce' "$sha")
+            if printf '%s' "$email" | grep -Fq 'noreply@anthropic.com'; then
+              echo "::error::commit $sha has an Anthropic address as author or committer."
+              status=1
+            fi
+          done
+
+          if [ "$status" -ne 0 ]; then
+            echo "::notice::switch this off for good in ~/.claude/settings.json: {\"attribution\":{\"commit\":\"\",\"pr\":\"\"}}"
+            exit 1
+          fi
+
+  ci-success:
+    name: CI Success
+    if: always()
+    needs: [quality, security, commit-hygiene]
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Every preceding job must have succeeded or been skipped
+        run: |
+          set -euo pipefail
+          printf '%s\n' '${{ toJSON(needs) }}' |
+            jq -e 'all(.[]; .result == "success" or .result == "skipped")'

pysnapdog-0.1.0/.github/workflows/release-please.yml

@@ -0,0 +1,47 @@
+# The only automatic route by which a production tag comes about.
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+  actions: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-24.04
+    # Per the non-negotiable rule the app credentials live exclusively in this
+    # environment. Without the declaration they are invisible to the job.
+    environment: release
+    steps:
+      # The release pull request MUST be created with an app token. GitHub
+      # suppresses workflow triggers from GITHUB_TOKEN pushes as recursion
+      # protection; CI would then never run on the release pull request and the
+      # required checks would stay pending. An app token is a genuine actor.
+      - uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3
+        id: app-token
+        with:
+          client-id: ${{ vars.RELEASE_PLEASE_CLIENT_ID }}
+          private-key: ${{ secrets.RELEASE_PLEASE_APP_PRIVATE_KEY }}
+
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        id: rp
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      # Hand the draft release to the publish workflow. The tag exists (force-tag-creation).
+      - name: Start the release workflow
+        if: steps.rp.outputs.release_created == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          TAG: ${{ steps.rp.outputs.tag_name }}
+        run: gh workflow run release.yml --repo "$GITHUB_REPOSITORY" -f tag="$TAG"

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

@@ -0,0 +1,92 @@
+# Publishes a release to PyPI. Started by release-please.yml for the draft release it created,
+# or by hand for a tag that exists. The first upload uses the PYPI_TOKEN of the release
+# environment. Once the project exists on PyPI, a trusted publisher replaces the token
+# (id-token: write, no password) and the secret is deleted.
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag, for example v0.1.0
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ inputs.tag }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-24.04
+    environment: release
+    steps:
+      - name: Preflight
+        env:
+          TAG: ${{ inputs.tag }}
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "bad tag: $TAG"; exit 1; }
+          [ -n "$PYPI_TOKEN" ] || { echo "PYPI_TOKEN is empty"; exit 1; }
+          gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: '3.14'
+
+      - name: Check that the tag and the package agree
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          version=$(uv run --no-project python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          [ "v$version" = "$TAG" ] || { echo "pyproject says $version, the tag is $TAG"; exit 1; }
+
+      - name: Test and build
+        run: |
+          set -euo pipefail
+          uv sync --locked
+          uv run pytest --cov
+          uv build --out-dir dist
+
+      - name: Upload to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: uv publish dist/*
+
+      - name: Verify that PyPI serves exactly what was built
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          version="${TAG#v}"
+          for file in dist/*; do
+            name=$(basename "$file")
+            want=$(sha256sum "$file" | cut -d' ' -f1)
+            for _ in 1 2 3 4 5 6 7 8 9 10 11 12; do
+              got=$(curl -sSf "https://pypi.org/pypi/pysnapdog/${version}/json" \
+                | jq -r --arg n "$name" '.urls[] | select(.filename==$n) | .digests.sha256' || true)
+              [ "$got" = "$want" ] && break
+              sleep 10
+            done
+            [ "$got" = "$want" ] || { echo "$name: PyPI has '$got', built $want"; exit 1; }
+            echo "$name verified"
+          done
+
+      - name: Publish the GitHub release
+        env:
+          TAG: ${{ inputs.tag }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          gh release upload "$TAG" dist/* --clobber --repo "$GITHUB_REPOSITORY"
+          gh release edit "$TAG" --draft=false --repo "$GITHUB_REPOSITORY"

pysnapdog-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Patterns deliberately UNANCHORED, so that they bite at every level.
+# Canonical inputs and generators stay tracked; reproducible outputs do not.
+# uv.lock and .python-version are tracked on purpose.
+
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Tool caches and coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Environment and state
+.env
+.env.*
+!.env.example
+*.log
+
+# Editor and operating system
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+.DocumentRevisions-V100/
+.fseventsd/
+.Spotlight-V100/
+.TemporaryItems/
+.Trashes/
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+[Dd]esktop.ini
+$RECYCLE.BIN/
+*.stackdump
+.fuse_hidden*
+.directory
+.Trash-*
+.nfs*
+.idea/
+.vscode/
+*.swp
+*.swo
+*~

pysnapdog-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

pysnapdog-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

pysnapdog-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (2026-11-01)
+
+
+### Features
+
+* bootstrap the repository ([4105e40](https://github.com/SnapDogRocks/pysnapdog/commit/4105e4044bdc9d445b11a2de33d6f3b077e182d0))
+* cover the REST API and the WebSocket events of the server ([72cf902](https://github.com/SnapDogRocks/pysnapdog/commit/72cf90263d862c2d5e58a8e11137cbd56d5bd492))
+
+
+### Documentation
+
+* align the README header with the server repository ([c0c5385](https://github.com/SnapDogRocks/pysnapdog/commit/c0c538564124faf9e54837a65fbae0d968998f12))
+* drop the not-yet-released notes from the README ([#4](https://github.com/SnapDogRocks/pysnapdog/issues/4)) ([2a045cf](https://github.com/SnapDogRocks/pysnapdog/commit/2a045cf860fc0beba9e58d597c98462d5e677db3))

pysnapdog-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+Thanks for helping. The library is small on purpose, so most changes are quick to review.
+
+## Setup
+
+The project uses [uv](https://docs.astral.sh/uv/) and Python 3.14.
+
+```bash
+uv sync
+uv run lefthook install      # local hooks; needs gitleaks (brew install gitleaks)
+```
+
+## Checks
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest --cov          # coverage floor 95 %
+```
+
+CI runs the same and `uv audit`. The hooks run a subset: `pre-commit` stays under three seconds,
+`pre-push` runs mypy and the tests. If a hook is in your way, tell us in the pull request instead
+of reaching for `--no-verify`.
+
+## Commit messages: Conventional Commits
+
+Every pull request title follows [Conventional Commits](https://www.conventionalcommits.org/):
+
+```text
+<type>(<scope>): <description>
+```
+
+- `scope` is optional, lower case.
+- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`,
+  `revert`.
+- A breaking change is marked with `!` after the type or a `BREAKING CHANGE:` footer.
+
+Pull requests are squash-merged, so the **title** becomes the commit on `main`, and
+release-please reads it to pick the next version and the changelog entry. Commit messages,
+pull request texts and branch names are written in English.
+
+One pull request carries one kind of change. A fix that travels with a `feat` is filed under
+Features in the changelog, where nobody looks for it.
+
+## Branches
+
+`type/short-description`, with the same types as above, for example `feat/zone-control`.
+
+## Tests
+
+The tests run against a fake server (`tests/conftest.py`) whose answers follow the server's
+`openapi.json`. When you add an endpoint, add the fake route, a model if the response needs one,
+and a test for the success path and for each way it can fail.
+
+## License
+
+By contributing you agree that your work is licensed under the [Apache License 2.0](LICENSE).