py-bragerone

Status: Stable | Python 3.13.2+ required

Python library for integrating with BragerOne-compatible cloud and realtime APIs.

Supported platforms:

BragerOne (default): one.brager.pl / io.brager.pl
TiSConnect: www.tisconnect.info / io.tisconnect.info

Features: - Async REST client (httpx, not aiohttp) - Realtime updates (python-socketio, namespace /ws) - Event bus for updates - ParamStore (lightweight, key→value with optional rich metadata via LiveAssetsCatalog) - CLI for diagnostics - Home Assistant ready

Installation

Stable (PyPI):

pip install py-bragerone

Pre-release (TestPyPI):

pip install -i https://test.pypi.org/simple/ py-bragerone

Optional extras:

pip install "py-bragerone[cli]"      # CLI with typer, rich, aiofiles
pip install "py-bragerone[keyring]"  # Secure token storage with keyring

Development Dependencies

For building documentation with architectural diagrams:

# Ubuntu/Debian
sudo apt-get install graphviz

# macOS
brew install graphviz

# Windows (via Chocolatey)
choco install graphviz

CLI usage

Run the CLI for guided login and WS session (the password is prompted securely when omitted):

pybragerone-cli --email YOU@example.com

Select platform (useful for TiSConnect installations):

pybragerone-cli --platform tisconnect --email YOU@example.com

Examples

Basic login and device listing

Minimal async example showing login and listing objects/modules:

import asyncio
import os
from pybragerone.api import BragerOneApiClient

async def main() -> None:
    email = os.getenv("PYBO_EMAIL", "user@example.com")
    password = os.getenv("PYBO_PASSWORD", "password")
    client = BragerOneApiClient()
    try:
        print(f"Logging in as {email}...")
        await client.ensure_auth(email, password)
        print("✓ Login successful")

        objects = await client.get_objects()
        print(f"Found {len(objects)} heating system(s)")
        for obj in objects:
            print(f"- {obj.name} (id={obj.id})")
            modules = await client.get_modules(obj.id)
            for m in modules:
                devid = m.devid or f"id:{m.id}"
                version = m.moduleVersion or (m.gateway.version if m.gateway else "unknown")
                print(f"  • {m.name} (devid={devid}, version={version})")
    finally:
        await client.close()

if __name__ == "__main__":
    asyncio.run(main())

Real-time parameter monitoring

Subscribing to updates via BragerOneGateway and printing changes:

import asyncio
import os
from contextlib import suppress
from pybragerone import BragerOneGateway

async def main() -> None:
    email = os.getenv("PYBO_EMAIL")
    password = os.getenv("PYBO_PASSWORD")
    object_id = int(os.getenv("PYBO_OBJECT_ID", "0"))
    modules = [m.strip() for m in os.getenv("PYBO_MODULES", "").split(",") if m.strip()]

    if not (email and password and object_id and modules):
        print("Set PYBO_EMAIL, PYBO_PASSWORD, PYBO_OBJECT_ID, PYBO_MODULES")
        return

       gateway = await BragerOneGateway.from_credentials(
             email=email,
             password=password,
             object_id=object_id,
             modules=modules,
       )

    async def monitor() -> None:
        async for ev in gateway.bus.subscribe():
            if ev.value is None:
                continue
            key = f"{ev.pool}.{ev.chan}{ev.idx}"
            print(f"{ev.devid:12} {key:15} = {ev.value}")

      task: asyncio.Task[None] | None = None
      try:
         await gateway.start()
         task = asyncio.create_task(monitor())
         await asyncio.sleep(10)   # demo run
      finally:
         if task is not None:
            task.cancel()
            with suppress(asyncio.CancelledError):
               await task
         await gateway.stop()

if __name__ == "__main__":
    asyncio.run(main())

ParamStore lightweight mode

Attaching ParamStore to the EventBus and reading values:

import asyncio
import os
from contextlib import suppress
from pybragerone import BragerOneGateway
from pybragerone.models.param import ParamStore

async def main() -> None:
    email = os.getenv("PYBO_EMAIL")
    password = os.getenv("PYBO_PASSWORD")
    object_id = int(os.getenv("PYBO_OBJECT_ID", "0"))
    modules = [m.strip() for m in os.getenv("PYBO_MODULES", "").split(",") if m.strip()]

    if not (email and password and object_id and modules):
        print("Set PYBO_EMAIL, PYBO_PASSWORD, PYBO_OBJECT_ID, PYBO_MODULES")
        return

      gateway = await BragerOneGateway.from_credentials(
         email=email,
         password=password,
         object_id=object_id,
         modules=modules,
      )
    store = ParamStore()

    task = asyncio.create_task(store.run_with_bus(gateway.bus))
    try:
        await gateway.start()
        await asyncio.sleep(2)
        params = store.flatten()
        print(f"Total params: {len(params)}")
        for k, v in list(params.items())[:10]:
            print(f"{k:20} = {v}")
    finally:
        task.cancel()
        with suppress(asyncio.CancelledError):
            await task
        await gateway.stop()

if __name__ == "__main__":
    asyncio.run(main())

Documentation

Full documentation: https://marpi82.github.io/py-bragerone

Security

For information about security policies, vulnerability reporting, and known security exceptions, see SECURITY.md.

This project uses property-based testing (Hypothesis) and an optional Atheris fuzz harness under fuzz/ for parser resilience.

Development Status
- 5 - Production/Stable
Intended Audience
- Developers
Operating System
- OS Independent
Programming Language
- Python :: 3 :: Only
- Python :: 3.13
Topic
- Home Automation
Typing
- Typed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py_bragerone-2026.8.7.tar.gz (112.2 kB view details)

Uploaded Aug 15, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

py_bragerone-2026.8.7-py3-none-any.whl (117.9 kB view details)

Uploaded Aug 15, 2026 Python 3

File details

Details for the file py_bragerone-2026.8.7.tar.gz.

File metadata

Download URL: py_bragerone-2026.8.7.tar.gz
Upload date: Aug 15, 2026
Size: 112.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for py_bragerone-2026.8.7.tar.gz
Algorithm	Hash digest
SHA256	`5f183c7b2fc566dfbaf8cc5feb72853ca51ebedf5555550cc6ef59d3de9ced1a`
MD5	`f6908d6ce81a4de6407a6fd2fddeea7a`
BLAKE2b-256	`086d57d954e76e73ac00949f61429b65c20d8ed857c8272a4658ac4f28049146`

See more details on using hashes here.

Provenance

The following attestation bundles were made for py_bragerone-2026.8.7.tar.gz:

Publisher: release.yml on marpi82/py-bragerone

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: py_bragerone-2026.8.7.tar.gz
- Subject digest: 5f183c7b2fc566dfbaf8cc5feb72853ca51ebedf5555550cc6ef59d3de9ced1a
- Sigstore transparency entry: 2474977565
- Sigstore integration time: Aug 15, 2026
Source repository:
- Permalink: marpi82/py-bragerone@03b7d56a56b5953dc3cd1b018d29b207242ef502
- Branch / Tag: refs/tags/2026.8.7
- Owner: https://github.com/marpi82
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@03b7d56a56b5953dc3cd1b018d29b207242ef502
- Trigger Event: push