philips-airctrl 1.0.0__tar.gz

philips_airctrl-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

philips_airctrl-1.0.0/.gitignore

@@ -0,0 +1,157 @@
+# 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/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Home Assistant setup wizard output
+philips_airpurifier_config/
+
+# Temporary files
+*.tmp
+*.temp
+
+# Local configuration files
+config.local.*
+.env.local

philips_airctrl-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,38 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.8.3
+    hooks:
+      - id: bandit
+        args: ["-c", "pyproject.toml", "-r", "src"]
+        additional_dependencies: ["bandit[toml]"]
+
+ci:
+  autofix_commit_msg: |
+    [pre-commit.ci] auto fixes from pre-commit.com hooks
+
+    for more information, see https://pre-commit.ci
+  autofix_prs: true
+  autoupdate_branch: ''
+  autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate'
+  autoupdate_schedule: weekly
+  skip: []
+  submodules: false

philips_airctrl-1.0.0/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog - philips-airctrl (Enhanced Home Assistant Fork)
+
+All notable changes to this enhanced fork will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Note**: This is an enhanced fork of the original aioairctrl package with significant additional features for Home Assistant integration. Version numbers start from 0.3.0 to distinguish from the original package.
+
+## [0.3.0] - 2025-01-27 - **Major Home Assistant Integration Release**
+
+### Added - **🏠 Home Assistant Integration Features**
+- **🔍 Automatic Device Discovery** - Network scanning for Philips air purifiers
+- **📊 Comprehensive Device Analysis** - Extract 70+ data points with capability detection
+- **🧙‍♂️ Interactive Setup Wizard** - User-friendly guided setup for non-technical users
+- **📁 Multiple Export Formats** - JSON and YAML output for easy integration
+- **🏠 Home Assistant Configuration Generation** - Ready-to-use HA configs
+- **📋 Device Information Export** - Complete device analysis for integration development
+- **🤝 Community Contribution Workflow** - Easy device info sharing for ha-philips-airpurifier project
+
+### Added - **🛠️ Development & Quality Improvements**
+- Comprehensive test suite with 75%+ coverage
+- Type hints throughout the codebase
+- Modern pyproject.toml configuration
+- Pre-commit hooks configuration
+- GitHub Actions CI/CD pipeline
+- Detailed README with usage examples
+- Development documentation
+- Code quality tools (Black, Flake8, MyPy)
+
+### Changed - **🔄 Fork & Package Changes**
+- **BREAKING**: Package renamed to `philips-airctrl` to distinguish from original
+- **BREAKING**: No longer available on PyPI - must install from source
+- **BREAKING**: CLI argument structure updated for new commands
+- **BREAKING**: Migrated from setup.py to pyproject.toml
+- Updated Python version requirement to 3.8+
+- Enhanced CLI argument parsing for better testability
+- Modernized code formatting with Black
+- Updated project metadata and maintainer information
+
+### Changed - **🛠️ Technical Improvements**
+- Improved error handling in client code
+- Fixed encryption key overflow handling
+- Enhanced async/await patterns throughout codebase
+
+### Fixed
+- Fixed bare except clause in client.py
+- Fixed f-string without placeholders
+- Fixed module imports organization
+- Fixed encryption context key incrementation overflow
+- Improved async/await patterns in tests
+
+### Security
+- Updated dependencies to latest versions
+- Added security scanning configuration
+- Improved error handling to prevent information leakage
+
+### Development
+- Added comprehensive test suite for all modules
+- Set up automated testing with pytest
+- Added code coverage reporting
+- Implemented pre-commit hooks for code quality
+- Added development environment setup documentation
+
+## [0.2.5] - Previous Release
+
+### Features
+- Basic CoAP client functionality
+- Encrypted communication with Philips air purifiers
+- Command-line interface
+- Status monitoring and control
+- Device observation capabilities
+
+### Known Issues
+- Limited test coverage
+- No type hints
+- Basic error handling
+- Manual dependency management
+
+---
+
+## Development Notes
+
+### Version 0.2.6 Improvements Summary
+
+This release represents a major modernization and quality improvement of the philips-airctrl library:
+
+1. **Testing Infrastructure**: Added comprehensive test suite covering encryption, client functionality, and CLI operations with proper async mocking.
+
+2. **Code Quality**: Implemented modern Python development practices including type hints, code formatting, and linting.
+
+3. **Project Structure**: Migrated to modern pyproject.toml configuration and removed deprecated setup.py.
+
+4. **Documentation**: Significantly enhanced README with detailed usage examples, API reference, and development guidelines.
+
+5. **Development Workflow**: Added pre-commit hooks, CI/CD pipeline, and automated quality checks.
+
+6. **Maintainability**: Improved error handling, fixed code quality issues, and added proper async patterns.
+
+### Migration Guide from 0.2.5 to 0.2.6
+
+The API remains backward compatible, but there are some development-related changes:
+
+- **Python Version**: Now requires Python 3.8+ (was 3.6+)
+- **Installation**: No changes to installation process
+- **API**: All existing API calls remain the same
+- **CLI**: All existing CLI commands work unchanged
+
+For developers:
+- Use `pip install -e ".[dev]"` for development dependencies
+- Run tests with `pytest` instead of manual testing
+- Use `black` for code formatting
+- Use `pre-commit` for automated quality checks
+
+### Future Roadmap
+
+- Add support for more Philips air purifier models
+- Implement device discovery functionality
+- Add configuration file support
+- Enhance error messages and user feedback
+- Add integration with home automation systems

philips_airctrl-1.0.0/CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Async Python library and CLI for controlling Philips air purifiers over encrypted CoAP. Provides network discovery, device data extraction, and an interactive Home Assistant setup wizard.
+
+## Development Commands
+
+```bash
+# Setup
+uv sync --extra dev              # Install all dependencies including dev
+
+# Testing (100% coverage required — enforced via fail_under = 100)
+uv run pytest                    # Run full suite with coverage
+uv run pytest tests/test_cli.py  # Run a single test file
+uv run pytest tests/test_cli.py::TestParseArgs::test_status  # Run a single test
+uv run pytest -k "test_discover" # Run tests matching a pattern
+uv run pytest -m "not slow"      # Skip slow tests
+
+# Linting & Formatting
+uv run ruff check src/ tests/    # Lint
+uv run ruff check --fix src/ tests/  # Lint with auto-fix
+uv run ruff format src/ tests/   # Format
+uv run mypy                      # Type check (strict mode)
+
+# Security
+uv run bandit -c pyproject.toml -r src/
+
+# Pre-commit
+uv run pre-commit run --all-files
+```
+
+## Architecture
+
+```text
+src/philips_airctrl/
+├── __main__.py          # CLI entry point → calls cli.main()
+├── cli.py               # Argument parsing and command dispatch (argparse)
+├── coap/
+│   ├── client.py        # Async CoAP client (Client class) — device communication
+│   └── encryption.py    # AES-CBC encryption/decryption for CoAP payloads
+├── discovery.py         # Network scanning for Philips devices (DeviceDiscovery)
+├── device_info.py       # Device capability analysis and reporting (DeviceInfoExtractor)
+├── models.py            # All Pydantic v2 data models (DeviceInfo, DeviceReport, HAConfig, etc.)
+├── setup_wizard.py      # Interactive CLI wizard using click (SetupWizard)
+└── _version.py          # Single source of truth for package version
+```
+
+**Data flow:** CLI → Discovery/Client → Encryption → Device. Models are shared across all modules.
+
+## Key Conventions
+
+- **Python >=3.11** with src/ layout, built with hatchling
+- **Pydantic v2** for all data models — use `model_validate()`, not `parse_obj()`
+- **Async/await** throughout — tests use `asyncio_mode = "auto"` (no manual decorator needed)
+- **Line length**: 100 characters (ruff)
+- **Ruff rules**: E, W, F, I, N, UP, B, SIM, TCH, RUF, S (bandit security checks)
+- **mypy strict**: `disallow_untyped_defs=true` — all functions need type annotations
+- **Test style**: pytest class-based organization with `unittest.mock` (AsyncMock for async)
+- **Version**: Edit `src/philips_airctrl/_version.py` — hatch reads it dynamically

philips_airctrl-1.0.0/LICENSE

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