pyinfra-tasmota 0.1.0__tar.gz

pyinfra_tasmota-0.1.0/.envrc

@@ -0,0 +1,2 @@
+layout uv
+source_env_if_exists .envrc.local

pyinfra_tasmota-0.1.0/.github/workflows/0-testing.yml

@@ -0,0 +1,43 @@
+name: Style and unit tests
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  run-tests:
+    name: Setup and run tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+
+    steps:
+      - name: Check out the source
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Style and formatting (ruff)
+        run: uv run ruff check .
+
+      - name: Unit and integration tests (pytest)
+        run: uv run pytest
+
+      - name: Mypy Check
+        run: uv run mypy .
+
+      - name: Bandit check
+        run: uv run bandit -c pyproject.toml -r .

pyinfra_tasmota-0.1.0/.github/workflows/1-build-and-publish.yml

@@ -0,0 +1,73 @@
+name: Build package, publish to PyPi, and make a release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch: # allows manual triggering
+
+jobs:
+  build:
+    name: "Build package"
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out the source
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Upload to PyPi
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Push to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*.whl dist/*.tar.gz
+          generate_release_notes: true

pyinfra_tasmota-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+/.venv/
+.coverage
+.*_cache/
+dist/
+build/
+*.egg-info/
+/.envrc.local

pyinfra_tasmota-0.1.0/AGENTS.md

@@ -0,0 +1,146 @@
+# `pyinfra-tasmota`
+
+Guidance for coding agents working in this repository. Read this together with
+the user-level `AGENTS.md`, which takes precedence where the two overlap.
+
+## Product
+
+A Pyinfra connector to handle Tasmota devices via their HTTP API.
+
+## Stack
+
+- Python, [`decode-config`](https://github.com/tasmota/decode-config)
+- `uv` for dependency management
+
+## Project Structure
+
+```raw
+./
+├── src/pyinfra_tasmota/  # package
+│   ├── connector.py        # Implementation of the connector
+│   └── __init__.py         # Export of public API
+├── tests/                  # pytest test suite
+├── pyproject.toml          # project metadata & tool config
+├── .editorconfig           # common editor configuration
+├── .gitignore              # Git ignore file
+└── .pre-commit-config.yaml # `pre-commit` configuration
+```
+
+## Setup & Build
+
+- `uv add <dependency>` to add a dependency (never `uv pip`).
+- `uv add --dev <dependency>` to add a development dependency.
+- `uv sync` to create the environment and install the package.
+- `uv build` for production wheels.
+- `uv run <tool>` to run any tool (`pytest`, `mypy`, `ruff`, `bandit`).
+
+## Quality Gates
+
+| Gate     | Tool                            |
+| -------- | ------------------------------- |
+| Format   | `ruff format --diff`            |
+| Lint     | `ruff check --show-fixes`       |
+| Types    | `mypy .`                        |
+| Security | `bandit -c pyproject.toml -r .` |
+| Tests    | `pytest`                        |
+
+All gates run via pre-commit hooks; only `pytest` needs a manual run (with
+`uv run`).
+
+The pre-commit config lives in `.pre-commit-config.yaml`.
+
+A task is done only when docstrings, other comments, README, and manpage are
+updated, and `uv run pytest` passes with 100% coverage.
+
+### Mypy configuration
+
+Set `warn_unreachable = true`.
+
+Set `ignore_missing_imports = true` for module `ipdb`.
+
+The Mypy pre-commit hook runs `uv run mypy .`, so it sees the project
+environment and its dependencies; there is no separate dependency list to
+maintain.
+
+### Coverage
+
+```toml
+exclude_also = [
+  'def __repr__',
+  'if TYPE_CHECKING:',
+  'class .*\bProtocol\):',
+  '@overload',
+  '@(abc\.)?abstractmethod',
+  'raise NotImplementedError',
+  'raise AssertionError',
+]
+```
+
+### Bandit
+
+Skip `assert_used` for test files.
+
+## Git Workflow
+
+Each task goes on a **separate feature branch** created from `main`:
+
+```sh
+git checkout main
+git checkout -b feature/<short-name>
+```
+
+Never commit to `main`.
+
+Always bundle commits which update the tests, change the code, and reflect the
+new behaviour in all documentation, docstrings, and comments. Do not split a
+change's tests, code, or documentation across separate commits.
+
+Scope-prefixed messages (e.g. `docs:`, `ci:`, `collector:`) commit messages, not
+Conventional Commits.
+
+While a feature branch has not been merged into `main`, related follow-up work
+(bugfixes, tweaks) should be appended to the appropriate feature branch. If it
+is not clear to you what branch to use, let me choose from a list of
+possibilities.
+
+## Coding Conventions
+
+- Google-style docstrings on every public function.
+- Strict formatting according to Ruff;
+  - Prefer test D211 over D203.
+  - Prefer test D213 over D212.
+- Type hints everywhere (use `| None` / `list[X]` / `dict[K, V]`).
+- Relative imports within the package (`from .foo import bar`).
+- Module-level imports preferred; inline imports only for tests, otherwise with
+  approval; Select Ruff test "PLC0415" except for tests.
+- EAFP: catch exceptions instead of pre-checking.
+- `pathlib` over `os.path`; f-strings over `%` / `.format()`.
+- Use comprehensions, generators, decorators where they fit.
+
+## Test Conventions
+
+- 100% line + branch coverage goal. `# pragma: no cover` only on defensive
+  branches that cannot be triggered (document why).
+- Red / green: write the test, make it pass, keep it green.
+- Prefer behaviour-based assertions over introspection of private attributes.
+- Deterministic fixtures (factories / `tmp_path` / `CliRunner`).
+- `pytest.mark.xfail` instead of commenting out a failing test.
+- Run affected tests before the full suite.
+
+## Text encoding
+
+- Write typographic characters directly as UTF-8 (for example ’ “ ” – — é © …),
+  not as HTML/XML entities or numeric references such as `&#8217;`, `&#x2019;`,
+  or `&rsquo;`.
+- Use escaping only where the target syntax requires it, such as `&`, `<`, and
+  `>` inside HTML or XML markup, or where a format explicitly needs ASCII.
+  - Save all text files as UTF-8.
+
+## Ignore
+
+Treat everything in `.gitignore` as off-limits to read or edit. On top of that,
+never open:
+
+- Secrets and `.env` files
+- Large data files unrelated to the current task
+- Vendored or generated code

pyinfra_tasmota-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: pyinfra-tasmota
+Version: 0.1.0
+Summary: A Pyinfra connector to manage Tasmota devices via their HTTP API
+Author: Martin F. Krafft
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: pyinfra>=3.10
+Requires-Dist: requests>=2.31
+Description-Content-Type: text/markdown
+
+# pyinfra-tasmota
+
+A [Pyinfra](https://pyinfra.com) connector for Tasmota devices.
+
+The connector talks to a Tasmota device over its HTTP API. It reads the
+device settings once at connect time, compares operation intent against
+that cache, and sends only the commands that are needed as batched
+`Backlog0` requests.
+
+## Install
+
+```sh
+uv add pyinfra-tasmota
+```
+
+## Usage
+
+Inventory:
+
+```py
+hosts = ["@tasmota/tasmota.example.org"]
+```
+
+Deploy:
+
+```py
+from pyinfra_tasmota.operations import apply, cmnd
+
+cmnd(SetOption114=1, SetOption120=0, Power="toggle")
+apply()
+```
+
+`cmnd` takes any number of commands as keyword arguments. It compares each
+desired value with the cache. It reads the current value from the device if
+the setting is not cached, and records a pending change only if the value
+differs. Every command is sent by `apply`, or on disconnect as a safety net.
+
+Command names are matched case-insensitively and resolve the `SO` alias of
+`SetOption`, so `SetOption114`, `setoption114`, and `so114` are the same
+command. Boolean values are folded, so a desired `0` matches a device value
+of `OFF`, and `1` matches `ON`.
+
+Non-rebooting commands are flushed as `Backlog0` batches, split to stay
+within Tasmota's limit of 30 commands and decode-config's limit of 320
+characters per command line. Reboot-triggering commands are sent on their own.
+
+## Reboots
+
+Some commands reboot the device, for example `Restart`, `Module`, and
+`Template`. The connector sends these commands on their own, after all other
+commands, and waits for the device to answer again before continuing. A
+device is considered back once it was seen to drop and is answering, or once
+its `BootCount` has advanced.
+
+If the device does not return within the timeout, `apply` reports an error.
+
+## Verbosity
+
+The connector follows pyinfra's `-v` flags:
+
+- `-v` reports every command sent to the device.
+- `-vv` also reports the observed state of each command, and any command
+  skipped because the device already matches the desired value.
+- `-vvv` also reports internal detail, such as the size of the status cache
+  and how commands are grouped into `Backlog0` batches.
+
+## Versioning
+
+The package version comes from Git via `uv-dynamic-versioning`. Tag a release
+as `vX.Y.Z`; commits after a tag get a `.postN.dev0+<hash>` suffix. A checkout
+with no tags reports `0.0.0`.
+
+## Connector data
+
+Set these on a host in the inventory:
+
+- `tasmota_friendly_name`: an optional human-readable name, used in logs.
+- `tasmota_reboot_timeout`: seconds to wait for a rebooted device to answer
+  again (default `60`).
+
+The connector registers itself with Pyinfra under the name `tasmota`, so use
+`@tasmota/<host>` anywhere a connector is expected.

pyinfra_tasmota-0.1.0/README.md

@@ -0,0 +1,82 @@
+# pyinfra-tasmota
+
+A [Pyinfra](https://pyinfra.com) connector for Tasmota devices.
+
+The connector talks to a Tasmota device over its HTTP API. It reads the
+device settings once at connect time, compares operation intent against
+that cache, and sends only the commands that are needed as batched
+`Backlog0` requests.
+
+## Install
+
+```sh
+uv add pyinfra-tasmota
+```
+
+## Usage
+
+Inventory:
+
+```py
+hosts = ["@tasmota/tasmota.example.org"]
+```
+
+Deploy:
+
+```py
+from pyinfra_tasmota.operations import apply, cmnd
+
+cmnd(SetOption114=1, SetOption120=0, Power="toggle")
+apply()
+```
+
+`cmnd` takes any number of commands as keyword arguments. It compares each
+desired value with the cache. It reads the current value from the device if
+the setting is not cached, and records a pending change only if the value
+differs. Every command is sent by `apply`, or on disconnect as a safety net.
+
+Command names are matched case-insensitively and resolve the `SO` alias of
+`SetOption`, so `SetOption114`, `setoption114`, and `so114` are the same
+command. Boolean values are folded, so a desired `0` matches a device value
+of `OFF`, and `1` matches `ON`.
+
+Non-rebooting commands are flushed as `Backlog0` batches, split to stay
+within Tasmota's limit of 30 commands and decode-config's limit of 320
+characters per command line. Reboot-triggering commands are sent on their own.
+
+## Reboots
+
+Some commands reboot the device, for example `Restart`, `Module`, and
+`Template`. The connector sends these commands on their own, after all other
+commands, and waits for the device to answer again before continuing. A
+device is considered back once it was seen to drop and is answering, or once
+its `BootCount` has advanced.
+
+If the device does not return within the timeout, `apply` reports an error.
+
+## Verbosity
+
+The connector follows pyinfra's `-v` flags:
+
+- `-v` reports every command sent to the device.
+- `-vv` also reports the observed state of each command, and any command
+  skipped because the device already matches the desired value.
+- `-vvv` also reports internal detail, such as the size of the status cache
+  and how commands are grouped into `Backlog0` batches.
+
+## Versioning
+
+The package version comes from Git via `uv-dynamic-versioning`. Tag a release
+as `vX.Y.Z`; commits after a tag get a `.postN.dev0+<hash>` suffix. A checkout
+with no tags reports `0.0.0`.
+
+## Connector data
+
+Set these on a host in the inventory:
+
+- `tasmota_friendly_name`: an optional human-readable name, used in logs.
+- `tasmota_reboot_timeout`: seconds to wait for a rebooted device to answer
+  again (default `60`).
+
+The connector registers itself with Pyinfra under the name `tasmota`, so use
+`@tasmota/<host>` anywhere a connector is expected.

pyinfra_tasmota-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "pyinfra-tasmota"
+dynamic = ["version"]
+description = "A Pyinfra connector to manage Tasmota devices via their HTTP API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Martin F. Krafft" }]
+dependencies = ["pyinfra>=3.10", "requests>=2.31"]
+
+[project.entry-points."pyinfra.connectors"]
+tasmota = "pyinfra_tasmota.connector:TasmotaConnector"
+
+[dependency-groups]
+dev = [
+  "bandit>=1.7",
+  "mypy>=1.11",
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.6",
+  "types-requests>=2.32",
+]
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyinfra_tasmota"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "A", "C4", "PT", "RET", "SIM", "PL", "RUF", "D"]
+ignore = ["D203", "D212", "PLR0913"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D101", "D102", "D103", "D104", "D107", "PLC0415", "PLR2004"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unreachable = true
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_untyped_calls = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=pyinfra_tasmota --cov-report=term-missing --cov-fail-under=100"
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+  'def __repr__',
+  'if TYPE_CHECKING:',
+  'class .*\bProtocol\):',
+  '@overload',
+  '@(abc\.)?abstractmethod',
+  'raise NotImplementedError',
+  'raise AssertionError',
+]
+
+[tool.bandit]
+skips = ["B101"]
+exclude_dirs = [".venv", "tests"]

pyinfra_tasmota-0.1.0/src/pyinfra_tasmota/__init__.py

@@ -0,0 +1,5 @@
+"""A Pyinfra connector to manage Tasmota devices via their HTTP API."""
+
+from .connector import TasmotaConnector
+
+__all__ = ["TasmotaConnector"]