pyatv-http 0.1.0__tar.gz

pyatv_http-0.1.0/.github/workflows/hk.yml

@@ -0,0 +1,21 @@
+name: hk
+
+permissions:
+  contents: read
+  packages: read
+  statuses: write
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: hugoh/gh-workflows/setup@fe2707057b8da8fab2460fc1f0e816561fa8a958 # v1.3.0
+      - run: uv sync
+      - run: uv run pytest
+      - uses: hugoh/gh-workflows/hk-check@fe2707057b8da8fab2460fc1f0e816561fa8a958 # v1.3.0

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

@@ -0,0 +1,66 @@
+name: release
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      new_tag: ${{ steps.tag_version.outputs.new_tag }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Bump version and push tag
+        id: tag_version
+        uses: mathieudutour/github-tag-action@a22cf08638b34d5badda920f9daf6e72c477b07b # v6.2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          default_bump: false
+
+      - name: Create a GitHub release
+        if: steps.tag_version.outputs.new_tag != ''
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NEW_TAG: ${{ steps.tag_version.outputs.new_tag }}
+          CHANGELOG: ${{ steps.tag_version.outputs.changelog }}
+        run: |
+          gh release create "$NEW_TAG" \
+            --verify-tag \
+            --title "Release $NEW_TAG" \
+            --notes "$CHANGELOG"
+
+  publish-pypi:
+    needs: release
+    if: needs.release.outputs.new_tag != ''
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+          ref: ${{ needs.release.outputs.new_tag }}
+
+      - uses: hugoh/gh-workflows/setup@fe2707057b8da8fab2460fc1f0e816561fa8a958 # v1.3.0
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

pyatv_http-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# uv
+.venv/
+
+# Config with real credentials
+config.toml
+
+# atvremote's own storage file, if run with cwd here (its default
+# --storage-filename is relative, not $HOME-based like pyatv's library
+# default) -- can contain real pairing credentials.
+.pyatv.conf
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

pyatv_http-0.1.0/.yamllint

@@ -0,0 +1,8 @@
+extends: default
+
+rules:
+  comments: disable
+  comments-indentation: disable
+  document-start: disable
+  line-length: disable
+  truthy: disable

pyatv_http-0.1.0/LICENSE

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

pyatv_http-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: pyatv-http
+Version: 0.1.0
+Summary: HTTP interface for controlling Apple TVs via pyatv
+Project-URL: Homepage, https://github.com/hugoh/pyatv-http
+Project-URL: Repository, https://github.com/hugoh/pyatv-http
+Project-URL: Issues, https://github.com/hugoh/pyatv-http/issues
+Author: Hugo Haas
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.121.0
+Requires-Dist: pyatv>=0.16.0
+Requires-Dist: uvicorn>=0.38.0
+Description-Content-Type: text/markdown
+
+# pyatv-http
+
+An HTTP interface for controlling Apple TVs, built on top of
+[pyatv](https://github.com/postlund/pyatv).
+
+## Features
+
+- `POST /<name>/turnOn` and `POST /<name>/turnOff` — checks the Apple TV's current
+  power state and only sends a command if it differs from the desired state.
+- `GET /<name>/powerState` — reads the current power state without changing it.
+- `GET /devices` — lists the devices available in the config file.
+- `GET /health` — unauthenticated liveness check, for load balancers/uptime
+  monitors.
+- Every other request requires a bearer token, configured as a list of
+  accepted tokens in the config file.
+- Config-driven: one TOML file lists the port to listen on, accepted API
+  tokens, and the paired devices.
+- Pairing stays out-of-band, via pyatv's own `atvremote` CLI; a `pyatv-http gen-config`
+  helper turns a paired device's stored credentials into a config snippet.
+
+## Setup
+
+### 1. Find your Apple TV
+
+```sh
+uvx --from pyatv atvremote scan
+```
+
+This lists every Apple TV on the network along with its identifiers, IP
+address, and which protocols it supports (AirPlay, Companion, etc).
+
+### 2. Pair with `atvremote`
+
+Power control uses the **Companion** protocol, and pyatv-http talks to the
+device over **AirPlay** for the initial handshake, so pair both:
+
+```sh
+uvx --from pyatv atvremote --id <device-identifier> pair --protocol airplay
+uvx --from pyatv atvremote --id <device-identifier> pair --protocol companion
+```
+
+Follow the on-screen PIN prompt for each. Credentials are stored in pyatv's
+storage file (default `~/.pyatv.conf`).
+
+### 3. Generate a config entry
+
+```sh
+uv run pyatv-http gen-config \
+  --identifier <device-identifier> \
+  --address <device-ip-or-hostname> \
+  --key living_room
+```
+
+`<device-identifier>` and `<device-ip-or-hostname>` come from the `scan`
+output in step 1; `--key` is whatever short name you want to use in URLs
+(`--name` sets the human-readable display name too, defaulting to `--key`).
+
+This prints a `[devices.living_room]` TOML block built from the stored
+pairing. Paste it into your config file (see below). If the identifier
+doesn't match any paired device, the command lists the identifiers it does
+have on file.
+
+### 4. Write the config file
+
+```toml
+port = 8080
+
+[auth]
+tokens = ["a-long-random-token"]
+
+[devices.living_room]
+name = "Living Room"
+identifier = "AA:BB:CC:DD:EE:FF"
+address = "10.0.0.5"
+
+[devices.living_room.protocols.airplay]
+identifier = "AA:BB:CC:DD:EE:FF"
+credentials = "..."
+
+[devices.living_room.protocols.companion]
+identifier = "11:22:33:44:55:66"
+credentials = "..."
+```
+
+- `port` — port the HTTP server listens on.
+- `[auth].tokens` — required, non-empty list of bearer tokens accepted on every
+  request (see [API](#api) below). Generate one with e.g.
+  `python3 -c "import secrets; print(secrets.token_urlsafe(32))"`.
+- The `[devices.<key>]` table key (`living_room` above) is the URL path
+  segment used in requests, e.g. `POST /living_room/turnOn`.
+- `identifier` — the device's main pyatv identifier (from `atvremote scan`).
+- `address` — the Apple TV's IP address or hostname; used to connect
+  directly instead of relying on mDNS discovery at request time.
+- `[devices.<key>.protocols.<protocol>]` — one block per paired protocol,
+  exactly as generated by `gen-config`. Supported protocol names: `airplay`,
+  `companion`, `dmap`, `mrp`, `raop`.
+
+### 5. Run the server
+
+```sh
+uv run pyatv-http serve --config config.toml
+```
+
+`--config` is optional; if omitted, it defaults to
+`$XDG_CONFIG_HOME/pyatv-http/config.toml`, falling back to
+`~/.config/pyatv-http/config.toml` when `$XDG_CONFIG_HOME` isn't set.
+
+By default the server binds `0.0.0.0`; pass `--host` to bind a specific
+interface.
+
+## API
+
+Every request must include one of the configured tokens as a bearer token:
+
+```sh
+TOKEN=a-long-random-token
+
+curl -X POST http://localhost:8080/living_room/turnOn \
+  -H "Authorization: Bearer $TOKEN"
+
+curl -X POST http://localhost:8080/living_room/turnOff \
+  -H "Authorization: Bearer $TOKEN"
+
+curl http://localhost:8080/living_room/powerState \
+  -H "Authorization: Bearer $TOKEN"
+
+curl http://localhost:8080/devices \
+  -H "Authorization: Bearer $TOKEN"
+
+curl http://localhost:8080/health
+```
+
+`turnOn`/`turnOff`/`powerState` return a JSON body:
+`{"device": "living_room", "power_state": "on"}`.
+
+`GET /devices` returns the devices available in the config file:
+
+```json
+[{"device": "living_room", "name": "Living Room"}]
+```
+
+`GET /health` (no token required) returns `{"status": "ok"}`.
+
+| Status | Meaning                                                           |
+| ------ | ------------------------------------------------------------------ |
+| 200    | Command sent (or no-op, if the device was already in that state)   |
+| 401    | Missing or invalid bearer token                                    |
+| 404    | No device configured under that name                               |
+| 504    | Device could not be found/reached on the network                   |
+| 502    | pyatv raised an error while connecting or sending the command      |
+
+### Interactive API docs
+
+FastAPI auto-generates interactive documentation for the running server:
+
+- `GET /docs` — Swagger UI (use the "Authorize" button to set your bearer
+  token, then try requests directly from the browser).
+- `GET /redoc` — ReDoc view of the same schema.
+- `GET /openapi.json` — the raw OpenAPI schema.
+
+These three routes are not themselves behind the bearer-token check.
+
+## Notes
+
+- Each request opens a fresh connection to the Apple TV, checks its current
+  power state, and only sends `turnOn`/`turnOff` if it differs from the
+  desired state — there's no persistent connection or background polling.
+- Pairing is entirely out-of-band via `atvremote`; this project never
+  performs the pairing handshake itself.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+hk check --all
+```

pyatv_http-0.1.0/README.md

@@ -0,0 +1,177 @@
+# pyatv-http
+
+An HTTP interface for controlling Apple TVs, built on top of
+[pyatv](https://github.com/postlund/pyatv).
+
+## Features
+
+- `POST /<name>/turnOn` and `POST /<name>/turnOff` — checks the Apple TV's current
+  power state and only sends a command if it differs from the desired state.
+- `GET /<name>/powerState` — reads the current power state without changing it.
+- `GET /devices` — lists the devices available in the config file.
+- `GET /health` — unauthenticated liveness check, for load balancers/uptime
+  monitors.
+- Every other request requires a bearer token, configured as a list of
+  accepted tokens in the config file.
+- Config-driven: one TOML file lists the port to listen on, accepted API
+  tokens, and the paired devices.
+- Pairing stays out-of-band, via pyatv's own `atvremote` CLI; a `pyatv-http gen-config`
+  helper turns a paired device's stored credentials into a config snippet.
+
+## Setup
+
+### 1. Find your Apple TV
+
+```sh
+uvx --from pyatv atvremote scan
+```
+
+This lists every Apple TV on the network along with its identifiers, IP
+address, and which protocols it supports (AirPlay, Companion, etc).
+
+### 2. Pair with `atvremote`
+
+Power control uses the **Companion** protocol, and pyatv-http talks to the
+device over **AirPlay** for the initial handshake, so pair both:
+
+```sh
+uvx --from pyatv atvremote --id <device-identifier> pair --protocol airplay
+uvx --from pyatv atvremote --id <device-identifier> pair --protocol companion
+```
+
+Follow the on-screen PIN prompt for each. Credentials are stored in pyatv's
+storage file (default `~/.pyatv.conf`).
+
+### 3. Generate a config entry
+
+```sh
+uv run pyatv-http gen-config \
+  --identifier <device-identifier> \
+  --address <device-ip-or-hostname> \
+  --key living_room
+```
+
+`<device-identifier>` and `<device-ip-or-hostname>` come from the `scan`
+output in step 1; `--key` is whatever short name you want to use in URLs
+(`--name` sets the human-readable display name too, defaulting to `--key`).
+
+This prints a `[devices.living_room]` TOML block built from the stored
+pairing. Paste it into your config file (see below). If the identifier
+doesn't match any paired device, the command lists the identifiers it does
+have on file.
+
+### 4. Write the config file
+
+```toml
+port = 8080
+
+[auth]
+tokens = ["a-long-random-token"]
+
+[devices.living_room]
+name = "Living Room"
+identifier = "AA:BB:CC:DD:EE:FF"
+address = "10.0.0.5"
+
+[devices.living_room.protocols.airplay]
+identifier = "AA:BB:CC:DD:EE:FF"
+credentials = "..."
+
+[devices.living_room.protocols.companion]
+identifier = "11:22:33:44:55:66"
+credentials = "..."
+```
+
+- `port` — port the HTTP server listens on.
+- `[auth].tokens` — required, non-empty list of bearer tokens accepted on every
+  request (see [API](#api) below). Generate one with e.g.
+  `python3 -c "import secrets; print(secrets.token_urlsafe(32))"`.
+- The `[devices.<key>]` table key (`living_room` above) is the URL path
+  segment used in requests, e.g. `POST /living_room/turnOn`.
+- `identifier` — the device's main pyatv identifier (from `atvremote scan`).
+- `address` — the Apple TV's IP address or hostname; used to connect
+  directly instead of relying on mDNS discovery at request time.
+- `[devices.<key>.protocols.<protocol>]` — one block per paired protocol,
+  exactly as generated by `gen-config`. Supported protocol names: `airplay`,
+  `companion`, `dmap`, `mrp`, `raop`.
+
+### 5. Run the server
+
+```sh
+uv run pyatv-http serve --config config.toml
+```
+
+`--config` is optional; if omitted, it defaults to
+`$XDG_CONFIG_HOME/pyatv-http/config.toml`, falling back to
+`~/.config/pyatv-http/config.toml` when `$XDG_CONFIG_HOME` isn't set.
+
+By default the server binds `0.0.0.0`; pass `--host` to bind a specific
+interface.
+
+## API
+
+Every request must include one of the configured tokens as a bearer token:
+
+```sh
+TOKEN=a-long-random-token
+
+curl -X POST http://localhost:8080/living_room/turnOn \
+  -H "Authorization: Bearer $TOKEN"
+
+curl -X POST http://localhost:8080/living_room/turnOff \
+  -H "Authorization: Bearer $TOKEN"
+
+curl http://localhost:8080/living_room/powerState \
+  -H "Authorization: Bearer $TOKEN"
+
+curl http://localhost:8080/devices \
+  -H "Authorization: Bearer $TOKEN"
+
+curl http://localhost:8080/health
+```
+
+`turnOn`/`turnOff`/`powerState` return a JSON body:
+`{"device": "living_room", "power_state": "on"}`.
+
+`GET /devices` returns the devices available in the config file:
+
+```json
+[{"device": "living_room", "name": "Living Room"}]
+```
+
+`GET /health` (no token required) returns `{"status": "ok"}`.
+
+| Status | Meaning                                                           |
+| ------ | ------------------------------------------------------------------ |
+| 200    | Command sent (or no-op, if the device was already in that state)   |
+| 401    | Missing or invalid bearer token                                    |
+| 404    | No device configured under that name                               |
+| 504    | Device could not be found/reached on the network                   |
+| 502    | pyatv raised an error while connecting or sending the command      |
+
+### Interactive API docs
+
+FastAPI auto-generates interactive documentation for the running server:
+
+- `GET /docs` — Swagger UI (use the "Authorize" button to set your bearer
+  token, then try requests directly from the browser).
+- `GET /redoc` — ReDoc view of the same schema.
+- `GET /openapi.json` — the raw OpenAPI schema.
+
+These three routes are not themselves behind the bearer-token check.
+
+## Notes
+
+- Each request opens a fresh connection to the Apple TV, checks its current
+  power state, and only sends `turnOn`/`turnOff` if it differs from the
+  desired state — there's no persistent connection or background polling.
+- Pairing is entirely out-of-band via `atvremote`; this project never
+  performs the pairing handshake itself.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+hk check --all
+```

pyatv_http-0.1.0/biome.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.4/schema.json",
+  "formatter": {
+    "indentStyle": "space",
+    "indentWidth": 2
+  }
+}

pyatv_http-0.1.0/hk.pkl

@@ -0,0 +1,48 @@
+amends "package://github.com/jdx/hk/releases/download/v1.50.0/hk@1.50.0#/Config.pkl"
+import "package://github.com/jdx/hk/releases/download/v1.50.0/hk@1.50.0#/Builtins.pkl"
+import "package://github.com/hugoh/hk-config/releases/download/v1.0.0/hk-config@1.0.0#/base.pkl" as Base
+
+min_hk_version = Base.min_hk_version
+
+local linters = new Mapping<String, Step> {
+    ...Base.base
+
+    // Python - run via this project's own uv-managed tools, not PATH binaries
+    ...Base.python
+    ["ruff"] = (Builtins.ruff) {
+        check = "uv run ruff check --force-exclude {{ files }}"
+        fix = "uv run ruff check --force-exclude --fix {{ files }}"
+    }
+    ["ruff-format"] = (Builtins.ruff_format) {
+        check_diff = "uv run ruff format --quiet --force-exclude --diff {{ files }}"
+        fix = "uv run ruff format --quiet --force-exclude {{ files }}"
+    }
+    ["ty"] = (Builtins.ty) {
+        check = "uv run ty check {{ files }}"
+    }
+}
+
+hooks {
+    ["pre-commit"] {
+        fix = true
+        stash = "git"
+        steps = linters
+    }
+    ["pre-push"] {
+        steps = linters
+    }
+    ["check"] {
+        steps = linters
+    }
+    ["fix"] {
+        fix = true
+        steps = linters
+    }
+    // Enforces Conventional Commits, since release.yml's auto-tagging
+    // depends on commit messages following that format.
+    ["commit-msg"] {
+        steps {
+            ["conventional-commit"] = Builtins.check_conventional_commit
+        }
+    }
+}

pyatv_http-0.1.0/mise.toml

@@ -0,0 +1,13 @@
+[tools]
+uv = "0.11.26"
+hk = "1.50.0"
+biome = "2.5.4"
+actionlint = "1.7.12"
+pinact = "4.1.0"
+ghalint = "1.5.6"
+zizmor = "1.26.1"
+gitleaks = "8.30.1"
+typos = "1.48.0"
+rumdl = "0.2.31"
+"github:owenlamont/ryl" = "0.21.0"
+tombi = "1.2.0"

pyatv_http-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "pyatv-http"
+dynamic = ["version"]
+description = "HTTP interface for controlling Apple TVs via pyatv"
+authors = [
+  { name = "Hugo Haas" },
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Environment :: Web Environment",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Home Automation",
+]
+
+dependencies = [
+  "pyatv>=0.16.0",
+  "fastapi>=0.121.0",
+  "uvicorn>=0.38.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/hugoh/pyatv-http"
+Repository = "https://github.com/hugoh/pyatv-http"
+Issues = "https://github.com/hugoh/pyatv-http/issues"
+
+[project.scripts]
+pyatv-http = "pyatv_http.cli:main"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+  "ty>=0.0.57",
+  "ruff>=0.15.20",
+  "pytest>=9.1.1",
+  "pytest-asyncio>=1.3.0",
+  "httpx>=0.28.1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyatv_http"]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"