quilt-hp-python 0.1.1__tar.gz

quilt_hp_python-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  proto-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          allow-prereleases: true
+      - run: pip install -e ".[dev]"
+      - name: Verify generated protobuf stubs are up to date
+        run: |
+          ./scripts/regen_protos.sh
+          git diff --exit-code -- src/quilt_hp/_proto
+
+  lint:
+    needs: proto-sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          allow-prereleases: true
+      - run: pip install -e ".[dev,cli]"
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+      - run: mypy src/quilt_hp/
+
+  test:
+    needs: proto-sync
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.14"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      - run: pip install -e ".[dev,cli]"
+      - run: pytest
+
+  package:
+    needs: proto-sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          allow-prereleases: true
+      - run: pip install -e ".[dev]"
+      - run: python -m build
+      - run: twine check dist/*
+
+  docs:
+    needs: proto-sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          allow-prereleases: true
+      - run: pip install -e ".[docs]"
+      - run: python scripts/check_docs_nav.py
+      - run: mkdocs build --strict

quilt_hp_python-0.1.1/.github/workflows/docs-deploy.yml

@@ -0,0 +1,45 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          allow-prereleases: true
+      - name: Install docs dependencies
+        run: pip install -e ".[docs]"
+      - name: Validate docs nav
+        run: python scripts/check_docs_nav.py
+      - name: Build docs
+        run: mkdocs build --strict
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

quilt_hp_python-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,114 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  quality-gates:
+    name: Quality gates
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          allow-prereleases: true
+      - name: Install dependencies
+        run: pip install -e ".[dev,cli,docs]"
+      - name: Verify generated protobuf stubs are up to date
+        run: |
+          ./scripts/regen_protos.sh
+          git diff --exit-code -- src/quilt_hp/_proto
+      - name: Validate tag, package version, and changelog
+        env:
+          TAG_VERSION: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import pathlib
+          import re
+          import tomllib
+
+          tag = os.environ["TAG_VERSION"]
+          if tag.startswith("v"):
+              tag = tag[1:]
+
+          if not re.fullmatch(r"\d+\.\d+\.\d+", tag):
+              raise SystemExit(f"Tag must be SemVer (vX.Y.Z). Got: {os.environ['TAG_VERSION']}")
+
+          pyproject = tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))
+          version = pyproject["project"]["version"]
+          if version != tag:
+              raise SystemExit(
+                  f"Tag version ({tag}) must match pyproject.toml project.version ({version})"
+              )
+
+          changelog = pathlib.Path("CHANGELOG.md").read_text(encoding="utf-8")
+          if "## [Unreleased]" not in changelog:
+              raise SystemExit("CHANGELOG.md must keep an [Unreleased] section")
+          if f"## [{tag}]" not in changelog:
+              raise SystemExit(f"CHANGELOG.md must contain a section for version [{tag}]")
+
+          print("Tag, package version, and changelog validation passed")
+          PY
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+      - run: mypy src/quilt_hp/
+      - run: pytest
+      - run: python -m build
+      - run: twine check dist/*
+      - run: python scripts/check_docs_nav.py
+      - run: mkdocs build --strict
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  github-release:
+    name: Create GitHub release
+    needs: quality-gates
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+      - id: semver
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+      - id: changelog
+        uses: mindsers/changelog-reader-action@v2
+        with:
+          version: ${{ steps.semver.outputs.version }}
+          path: ./CHANGELOG.md
+      - uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.changelog.outputs.changes }}
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs:
+      - quality-gates
+      - github-release
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      id-token: write
+    environment:
+      name: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

quilt_hp_python-0.1.1/.gitignore

@@ -0,0 +1,50 @@
+# Virtual environments
+.venv/
+venv/
+
+# Python bytecode
+__pycache__/
+*.pyc
+*.pyo
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+src/*.egg-info/
+
+# Tool caches
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# MkDocs build output
+site/
+
+# Keep source protos in-repo for standalone regeneration
+!proto/
+!proto/cleaned/
+!proto/cleaned/*.proto
+
+# Local API reference files — not for version control
+/reference
+tokens.json
+*.pem
+*.key
+*.crt
+*.p12
+.env
+.env.*
+

quilt_hp_python-0.1.1/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-05-08
+
+## [0.1.0]
+
+### Added
+- GitHub Actions release automation for SemVer tags (`vX.Y.Z`) that enforces quality gates, creates a GitHub Release, and publishes distribution artifacts to PyPI via trusted publishing
+- Initial async client for Quilt cloud gRPC API
+- Cognito OTP authentication with token caching
+- HomeDatastoreService: spaces, indoor units, comfort settings, schedules
+- SystemInformationService: system listing, energy metrics
+- NotifierService: real-time streaming subscriptions
+- CLI for interactive use (`quilt` command)

quilt_hp_python-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

quilt_hp_python-0.1.1/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: quilt-hp-python
+Version: 0.1.1
+Summary: Async Python client for Quilt mini-split HVAC systems
+Project-URL: Repository, https://github.com/eman/quilt-hp-python
+Project-URL: Issues, https://github.com/eman/quilt-hp-python/issues
+Project-URL: Changelog, https://github.com/eman/quilt-hp-python/blob/main/CHANGELOG.md
+Author: Emmanuel
+License: MIT License
+        
+        Copyright (c) 2026
+        
+        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.
+License-File: LICENSE
+Keywords: grpc,home-automation,hvac,mini-split,quilt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: boto3>=1.35
+Requires-Dist: grpcio>=1.70
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: protobuf>=5.0
+Provides-Extra: cli
+Requires-Dist: rich>=13.0; extra == 'cli'
+Requires-Dist: textual>=0.80; extra == 'cli'
+Requires-Dist: typer>=0.12; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: boto3-stubs[cognito-idp]; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: grpcio-tools>=1.70; extra == 'dev'
+Requires-Dist: mypy-protobuf>=3.6; extra == 'dev'
+Requires-Dist: mypy>=1.15; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.29; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# quilt-hp-python
+
+Async Python client library for [Quilt](https://www.quilt.com/) mini-split HVAC systems.
+
+Communicates with the Quilt cloud API via gRPC to control spaces (rooms), indoor units,
+comfort presets, schedules, and stream real-time updates.
+
+## Installation
+
+```bash
+pip install quilt-hp-python
+```
+
+With the optional CLI:
+
+```bash
+pip install "quilt-hp-python[cli]"
+```
+
+## Quick Start
+
+```python
+import asyncio
+from quilt_hp import QuiltClient
+
+async def main():
+    async with QuiltClient("user@example.com") as client:
+        await client.login(otp_callback=lambda email: input(f"OTP for {email}: "))
+
+        # List spaces
+        for space in await client.list_spaces():
+            print(f"{space.name}: {space.state.ambient_temperature_c}°C")
+
+        # Set a room to COOL at 22°C
+        from quilt_hp.models.enums import HVACMode
+        spaces = await client.list_spaces()
+        await client.set_space(spaces[0].id, mode=HVACMode.COOL, cool_setpoint_c=22.0)
+
+        # Stream real-time updates
+        spaces = await client.list_spaces()
+        topics = [f"hds/space/{s.id}" for s in spaces]
+        async with client.stream(topics) as stream:
+            stream.on_space_update(lambda s: print(f"{s.name}: {s.state.ambient_temperature_c}°C"))
+            await asyncio.sleep(60)
+
+asyncio.run(main())
+```
+
+## CLI
+
+```bash
+# Authenticate (caches tokens for subsequent commands)
+quilt login --email user@example.com
+
+# Full system inventory + telemetry (summary)
+quilt info
+
+# Full system snapshot as JSON for automation
+quilt info --output json
+
+# All device/entity IDs (includes update entities)
+quilt devices
+
+# Current sensor values + setpoints
+quilt values
+
+# Machine-readable values for scripting
+quilt values --output json
+
+# Energy usage
+quilt energy --period week
+
+# Set a room to cooling mode
+quilt set "Living Room" --mode cool --cool 22
+```
+
+## Development
+
+```bash
+git clone https://github.com/eman/quilt-hp-python.git
+cd quilt-hp-python
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,cli]"
+
+# Run checks
+ruff check src/ tests/
+ruff format --check src/ tests/
+mypy src/quilt_hp/
+pytest
+python -m build
+twine check dist/*
+
+# Recompile protobuf stubs (requires grpcio-tools)
+# Proto sources are vendored in ./proto/cleaned for standalone use.
+# Optional but recommended: install protobuf includes (e.g. `brew install protobuf`)
+./scripts/regen_protos.sh
+
+# Build project docs (MkDocs Material)
+pip install -e ".[docs]"
+python scripts/check_docs_nav.py
+mkdocs build --strict
+```
+
+## License
+
+MIT

quilt_hp_python-0.1.1/README.md

@@ -0,0 +1,107 @@
+# quilt-hp-python
+
+Async Python client library for [Quilt](https://www.quilt.com/) mini-split HVAC systems.
+
+Communicates with the Quilt cloud API via gRPC to control spaces (rooms), indoor units,
+comfort presets, schedules, and stream real-time updates.
+
+## Installation
+
+```bash
+pip install quilt-hp-python
+```
+
+With the optional CLI:
+
+```bash
+pip install "quilt-hp-python[cli]"
+```
+
+## Quick Start
+
+```python
+import asyncio
+from quilt_hp import QuiltClient
+
+async def main():
+    async with QuiltClient("user@example.com") as client:
+        await client.login(otp_callback=lambda email: input(f"OTP for {email}: "))
+
+        # List spaces
+        for space in await client.list_spaces():
+            print(f"{space.name}: {space.state.ambient_temperature_c}°C")
+
+        # Set a room to COOL at 22°C
+        from quilt_hp.models.enums import HVACMode
+        spaces = await client.list_spaces()
+        await client.set_space(spaces[0].id, mode=HVACMode.COOL, cool_setpoint_c=22.0)
+
+        # Stream real-time updates
+        spaces = await client.list_spaces()
+        topics = [f"hds/space/{s.id}" for s in spaces]
+        async with client.stream(topics) as stream:
+            stream.on_space_update(lambda s: print(f"{s.name}: {s.state.ambient_temperature_c}°C"))
+            await asyncio.sleep(60)
+
+asyncio.run(main())
+```
+
+## CLI
+
+```bash
+# Authenticate (caches tokens for subsequent commands)
+quilt login --email user@example.com
+
+# Full system inventory + telemetry (summary)
+quilt info
+
+# Full system snapshot as JSON for automation
+quilt info --output json
+
+# All device/entity IDs (includes update entities)
+quilt devices
+
+# Current sensor values + setpoints
+quilt values
+
+# Machine-readable values for scripting
+quilt values --output json
+
+# Energy usage
+quilt energy --period week
+
+# Set a room to cooling mode
+quilt set "Living Room" --mode cool --cool 22
+```
+
+## Development
+
+```bash
+git clone https://github.com/eman/quilt-hp-python.git
+cd quilt-hp-python
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,cli]"
+
+# Run checks
+ruff check src/ tests/
+ruff format --check src/ tests/
+mypy src/quilt_hp/
+pytest
+python -m build
+twine check dist/*
+
+# Recompile protobuf stubs (requires grpcio-tools)
+# Proto sources are vendored in ./proto/cleaned for standalone use.
+# Optional but recommended: install protobuf includes (e.g. `brew install protobuf`)
+./scripts/regen_protos.sh
+
+# Build project docs (MkDocs Material)
+pip install -e ".[docs]"
+python scripts/check_docs_nav.py
+mkdocs build --strict
+```
+
+## License
+
+MIT