Latest Tag PyPI Version Python Versions License CI Status CodeQL Status OpenSSF Best Practices Docs Status Documentation Renovate Code Style: Ruff Type Checked: mypy Security: Bandit Release Status Last Commit Repo Size PyPI Downloads

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 pybragerone

Pre-release (TestPyPI):

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

Optional extras:

pip install "pybragerone[cli]"      # CLI with typer, rich, aiofiles
pip install "pybragerone[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:

pybragerone-cli --email YOU@example.com --password "***"

Select platform (useful for TiSConnect installations):

pybragerone-cli --platform tisconnect --email YOU@example.com --password "***"

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.

Project links

Data verified by PyPI on Aug 8, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2026.9.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for marpi82 from gravatar.com marpi82

Credits

Author/Maintainer: MarPi82

GitHub Statistics

Data verified by PyPI on Aug 8, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python <3.15, >=3.13.2

Provides Extra

cli keyring

Tags

automation brager bragerone home home-assistant httpx pydantic socket.io websocket

Classifiers

Report project as malware

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.1.tar.gz (92.6 kB view details)

Uploaded Source

Built Distribution

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

py_bragerone-2026.8.1-py3-none-any.whl (98.3 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: py_bragerone-2026.8.1.tar.gz
  • Upload date:
  • Size: 92.6 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.1.tar.gz
Algorithm Hash digest
SHA256 c5f0569fc67881d38af8edab695a393ce71a88c01d3d3145865ee6c27f12f201
MD5 147018d3316c8ee53b4d3363a246ac41
BLAKE2b-256 48d144bd17dc2706f5b7ad8286715c2db09ecfcf6c26e26a0fa444dac2654027

See more details on using hashes here.

Provenance

The following attestation bundles were made for py_bragerone-2026.8.1.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.

File details

Details for the file py_bragerone-2026.8.1-py3-none-any.whl.

File metadata

File hashes

Hashes for py_bragerone-2026.8.1-py3-none-any.whl
Algorithm Hash digest
SHA256 2e0e2bbfc642296dab3128c6548d34361ad3227a5edaeac3488d5227627bdedd
MD5 cef58f923f13a45dee12e1bf6f935f57
BLAKE2b-256 9d5d22ff3fe28d68b46b7d83f634d2619dc26f418acde78ec0dc180af3406ef1

See more details on using hashes here.

Provenance

The following attestation bundles were made for py_bragerone-2026.8.1-py3-none-any.whl:

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.
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page