xbloom-py 0.1.0__tar.gz

xbloom_py-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.12"
+      - run: uv sync --all-extras
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

xbloom_py-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,35 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+        extras: ["all", "none"]
+    name: py${{ matrix.python-version }} extras=${{ matrix.extras }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install with all extras
+        if: matrix.extras == 'all'
+        run: uv sync --all-extras
+
+      - name: Install with no extras
+        if: matrix.extras == 'none'
+        run: uv sync --only-group dev
+
+      - name: Run tests
+        run: uv run pytest -q

xbloom_py-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+.DS_Store

xbloom_py-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 — 2026-08-27
+
+First release. Extracted, with its history, from the vendored library inside the
+xBloom Studio Home Assistant integration, where it had lived since 2026-07-13.
+
+- BLE protocol: frame encode/decode, ACK-gated send/confirm, packet builders,
+  recipe blob encoding
+- `spec`: machine constants centralised as the single source of truth, with a
+  parity test guarding the values against their pre-refactor snapshot
+- Recipe validation, normalisation and scaling
+- Arm-gated OTA firmware flashing
+- Optional cloud account: login, recipe CRUD, firmware version check
+- BLE and cloud dependencies are extras, so the package installs alongside Home
+  Assistant without disturbing its pinned versions

xbloom_py-0.1.0/LICENSE

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

xbloom_py-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: xbloom-py
+Version: 0.1.0
+Summary: Async Python library for xBloom Studio coffee brewers: BLE protocol, recipes, OTA and cloud
+Project-URL: Homepage, https://github.com/Alshekhi/xbloom-py
+Project-URL: Issues, https://github.com/Alshekhi/xbloom-py/issues
+Author: Mansour Alshekhi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ble,bluetooth,brewing,coffee,home-assistant,xbloom
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: all
+Requires-Dist: aiohttp>=3.9; extra == 'all'
+Requires-Dist: bleak-retry-connector>=3.5; extra == 'all'
+Requires-Dist: bleak>=0.22; extra == 'all'
+Requires-Dist: cryptography>=42; extra == 'all'
+Provides-Extra: ble
+Requires-Dist: bleak-retry-connector>=3.5; extra == 'ble'
+Requires-Dist: bleak>=0.22; extra == 'ble'
+Provides-Extra: cloud
+Requires-Dist: aiohttp>=3.9; extra == 'cloud'
+Requires-Dist: cryptography>=42; extra == 'cloud'
+Description-Content-Type: text/markdown
+
+# xbloom-py
+
+Async Python library for [xBloom Studio](https://xbloom.com) coffee brewers:
+the BLE protocol, recipe validation, over-the-air firmware updates, and the
+optional cloud account API.
+
+Unofficial and not affiliated with xBloom. The protocol was derived by static
+analysis of the vendor's mobile applications.
+
+## Install
+
+```bash
+pip install xbloom-py            # pure-python core: spec, recipes, validation
+pip install "xbloom-py[ble]"     # + local Bluetooth control
+pip install "xbloom-py[cloud]"   # + cloud account, recipe sync, firmware check
+pip install "xbloom-py[all]"     # everything
+```
+
+Import as `xbloom`:
+
+```python
+from xbloom import spec, recipe_validate
+```
+
+Dependencies are declared with lower bounds only and no upper pins, so the
+package can be installed alongside Home Assistant without disturbing the
+versions it pins itself.
+
+## What is in it
+
+| Module | Needs | What it does |
+|---|---|---|
+| `spec` | — | Machine constants: ranges, enums, pattern and unit maps. The single source of truth. |
+| `recipe_validate` | — | Validate and normalise recipe dictionaries. |
+| `brew_scale` | — | Scale a recipe's dose and water. |
+| `models` | — | Recipe and reading dataclasses. |
+| `exceptions` | — | `XBloomError`, `XBloomAPIError`. |
+| `ble` | `[ble]` at runtime | Frame encoding/decoding, ACK-gated send/confirm, packet builders. |
+| `ota` | `[ble]` at runtime | Validated, arm-gated firmware flashing. |
+| `mode_listener` | `[ble]` at runtime | Live knob and scale event stream. |
+| `client` | `[cloud]` | Share-link recipe fetching. |
+| `cloud` | `[cloud]` | Account login, recipe CRUD, firmware version check. |
+
+`ble`, `ota` and `mode_listener` import their Bluetooth dependencies lazily, so
+they can be imported for packet construction with no extras installed.
+
+## Status
+
+`0.x` — the API is settling. It has one production consumer today (the
+[xBloom Studio Home Assistant integration](https://github.com/Alshekhi/xbloom-studio));
+`1.0.0` follows once a second consumer has proven the module boundaries.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+```
+
+The suite runs without extras too; `test_cloud.py` is skipped when `aiohttp`
+and `cryptography` are absent.
+
+## License
+
+MIT

xbloom_py-0.1.0/README.md

@@ -0,0 +1,65 @@
+# xbloom-py
+
+Async Python library for [xBloom Studio](https://xbloom.com) coffee brewers:
+the BLE protocol, recipe validation, over-the-air firmware updates, and the
+optional cloud account API.
+
+Unofficial and not affiliated with xBloom. The protocol was derived by static
+analysis of the vendor's mobile applications.
+
+## Install
+
+```bash
+pip install xbloom-py            # pure-python core: spec, recipes, validation
+pip install "xbloom-py[ble]"     # + local Bluetooth control
+pip install "xbloom-py[cloud]"   # + cloud account, recipe sync, firmware check
+pip install "xbloom-py[all]"     # everything
+```
+
+Import as `xbloom`:
+
+```python
+from xbloom import spec, recipe_validate
+```
+
+Dependencies are declared with lower bounds only and no upper pins, so the
+package can be installed alongside Home Assistant without disturbing the
+versions it pins itself.
+
+## What is in it
+
+| Module | Needs | What it does |
+|---|---|---|
+| `spec` | — | Machine constants: ranges, enums, pattern and unit maps. The single source of truth. |
+| `recipe_validate` | — | Validate and normalise recipe dictionaries. |
+| `brew_scale` | — | Scale a recipe's dose and water. |
+| `models` | — | Recipe and reading dataclasses. |
+| `exceptions` | — | `XBloomError`, `XBloomAPIError`. |
+| `ble` | `[ble]` at runtime | Frame encoding/decoding, ACK-gated send/confirm, packet builders. |
+| `ota` | `[ble]` at runtime | Validated, arm-gated firmware flashing. |
+| `mode_listener` | `[ble]` at runtime | Live knob and scale event stream. |
+| `client` | `[cloud]` | Share-link recipe fetching. |
+| `cloud` | `[cloud]` | Account login, recipe CRUD, firmware version check. |
+
+`ble`, `ota` and `mode_listener` import their Bluetooth dependencies lazily, so
+they can be imported for packet construction with no extras installed.
+
+## Status
+
+`0.x` — the API is settling. It has one production consumer today (the
+[xBloom Studio Home Assistant integration](https://github.com/Alshekhi/xbloom-studio));
+`1.0.0` follows once a second consumer has proven the module boundaries.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+```
+
+The suite runs without extras too; `test_cloud.py` is skipped when `aiohttp`
+and `cryptography` are absent.
+
+## License
+
+MIT