bacnet-ip-rest-client 1.0.0__tar.gz

bacnet_ip_rest_client-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check package metadata
+        run: uvx twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run --locked pytest

bacnet_ip_rest_client-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "README.md"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "README.md"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+
+      # The API reference is generated from the docstrings in src/ by mkdocstrings.
+      - name: Build site
+        run: uv run --locked --only-group docs mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  # Publishing requires GitHub Pages to be enabled for the repository, with "GitHub Actions" as
+  # the source (Settings > Pages > Build and deployment).
+  deploy:
+    name: Publish to GitHub Pages
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

bacnet_ip_rest_client-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+
+      - name: Set package version from tag
+        run: uv version --frozen "${GITHUB_REF_NAME#v}"
+
+      - name: Run tests
+        run: uv run --frozen pytest
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check package metadata
+        run: uvx twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bacnet-ip-rest-client
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      # Uses PyPI Trusted Publishing (OIDC) -- no API token required. Before the first
+      # release, register this repo as a *pending* publisher (the project doesn't exist on
+      # PyPI yet) at https://pypi.org/manage/account/publishing/ with:
+      #   PyPI project name: bacnet-ip-rest-client
+      #   Owner: stblassitude   Repository: bacnet-ip-rest-client
+      #   Workflow name: publish.yml   Environment name: pypi
+      - uses: pypa/gh-action-pypi-publish@release/v1

bacnet_ip_rest_client-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 "${GITHUB_REF_NAME}^" 2>/dev/null || true)
+          RANGE="${PREV_TAG:+$PREV_TAG..}${GITHUB_REF_NAME}"
+          git log "$RANGE" --pretty=format:'- %s' > release-notes.md
+          gh release create "$GITHUB_REF_NAME" \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file release-notes.md

bacnet_ip_rest_client-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+site/

bacnet_ip_rest_client-1.0.0/LICENSE

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

bacnet_ip_rest_client-1.0.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: bacnet-ip-rest-client
+Version: 1.0.0
+Summary: Async Python client for the BACnet/IP REST proxy
+Project-URL: Homepage, https://github.com/stblassitude/bacnet-ip-rest-client
+Project-URL: Documentation, https://stblassitude.github.io/bacnet-ip-rest-client/
+Project-URL: Issues, https://github.com/stblassitude/bacnet-ip-rest-client/issues
+Author-email: Stefan Bethke <stb@lassitu.de>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,bacnet,building-automation,httpx,rest
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.1
+Description-Content-Type: text/markdown
+
+# bacnet-ip-rest-client
+
+An async Python client for the
+[BACnet/IP REST proxy](https://github.com/stblassitude/bacnet-ip-rest-proxy).
+It is built on [httpx](https://www.python-httpx.org/).
+
+```python
+from bacnet_ip_rest_client import Client, ProxyError
+
+async with Client("https://bacnet-proxy.example.net", token) as client:
+    for obj in await client.list_objects("my-device"):
+        print(obj.objid, obj.name, obj.access)
+
+    temp = await client.read_property("my-device", "analog-input,1", "present-value")
+    slots = await client.read_property("my-device", "analog-value,5", "priority-array")
+    await client.write_property("my-device", "analog-value,5", "present-value", 21.5, priority=10)
+    await client.write_property("my-device", "analog-value,5", "present-value", None, priority=10)  # relinquish
+```
+
+## Relationship to bacpypes3
+
+`Client` has the same role as a bacpypes3 `Application`, and
+`read_property()` and `write_property()` take bacpypes3's arguments, with
+some exceptions. It doesn't try to hide the ways an HTTP proxy works
+differently from a BACnet/IP stack:
+
+| | bacpypes3 | this client |
+|---|---|---|
+| Addressing a device | BACnet `Address` | the proxy's device id: a configured alias, or a hostname/IP[:port] |
+| Object identifiers | `ObjectIdentifier` with an `ObjectType` enum | `ObjectIdentifier(type: str, instance: int)`, also a 2-tuple; parses `"analog-value,1"` |
+| Values | decoded into the property's BACnet datatype | JSON as the proxy sends it: enumerations as numbers, bit strings as lists of bools. REAL properties of analog objects are always `float`, including NaN/±Infinity |
+| Errors | `ErrorPDU`/`RejectPDU`/`AbortPDU`, which derive from `BaseException`, and are sometimes returned instead of raised | always raised, all derived from `ProxyError(Exception)`, see below |
+| Object discovery | read `object-list`, then each object's properties | `list_objects()`: the proxy's cached catalog with names, units and access, in one request |
+| ReadPropertyMultiple | one request, one transaction | none. `read_properties()` sends concurrent single reads, each with its own result |
+| WriteProperty with array index | supported | not supported by the proxy |
+| Authorization | none | a bearer token per `Client`. The proxy's rules decide what it may read and write (`ObjectSummary.access`) |
+
+## Errors
+
+| Exception | Cause | Retried |
+|---|---|---|
+| `CommunicationError` | proxy unreachable, or a reply that couldn't be decoded | yes |
+| `BadRequestError` | 400, malformed request | no |
+| `UnauthorizedError` | 401, token not accepted | no |
+| `ForbiddenError` | 403, the proxy's authorization denies the request | no |
+| `NotFoundError` | 404, unknown device, object or property | no |
+| `ValueRejectedError` | 422, the device rejected the written value | no |
+| `BACnetError` | 502, BACnet Error/Reject/Abort from the device; `error_class`/`error_code` hold its numeric Error_Class/Error_Code | yes, except unknown-object/unknown-property |
+| `BACnetTimeoutError` | 504, the device didn't answer | yes |
+
+`ProxyStatusError.is_unknown_object_or_property` is true when the proxy
+reports a missing object or property, whether it does so as a 404 or as a
+502 from the device. Code that probes for optional properties, such as
+`priority-array`, can check this one attribute.
+
+Retries use exponential backoff as configured by `RetryPolicy` (default:
+5 attempts, 1s doubling to at most 8s). Retry warnings are logged to the
+`bacnet_ip_rest_client` logger. Writes are retried too, since writing the
+same value at the same priority again has no further effect.
+
+`concurrency` (default 10) caps the number of requests one `Client` has in
+flight. The proxy serializes traffic to the device itself; this cap only
+keeps a large `read_properties()` from opening hundreds of connections to
+the proxy.
+
+## Development
+
+```sh
+uv run pytest
+```

bacnet_ip_rest_client-1.0.0/README.md

@@ -0,0 +1,70 @@
+# bacnet-ip-rest-client
+
+An async Python client for the
+[BACnet/IP REST proxy](https://github.com/stblassitude/bacnet-ip-rest-proxy).
+It is built on [httpx](https://www.python-httpx.org/).
+
+```python
+from bacnet_ip_rest_client import Client, ProxyError
+
+async with Client("https://bacnet-proxy.example.net", token) as client:
+    for obj in await client.list_objects("my-device"):
+        print(obj.objid, obj.name, obj.access)
+
+    temp = await client.read_property("my-device", "analog-input,1", "present-value")
+    slots = await client.read_property("my-device", "analog-value,5", "priority-array")
+    await client.write_property("my-device", "analog-value,5", "present-value", 21.5, priority=10)
+    await client.write_property("my-device", "analog-value,5", "present-value", None, priority=10)  # relinquish
+```
+
+## Relationship to bacpypes3
+
+`Client` has the same role as a bacpypes3 `Application`, and
+`read_property()` and `write_property()` take bacpypes3's arguments, with
+some exceptions. It doesn't try to hide the ways an HTTP proxy works
+differently from a BACnet/IP stack:
+
+| | bacpypes3 | this client |
+|---|---|---|
+| Addressing a device | BACnet `Address` | the proxy's device id: a configured alias, or a hostname/IP[:port] |
+| Object identifiers | `ObjectIdentifier` with an `ObjectType` enum | `ObjectIdentifier(type: str, instance: int)`, also a 2-tuple; parses `"analog-value,1"` |
+| Values | decoded into the property's BACnet datatype | JSON as the proxy sends it: enumerations as numbers, bit strings as lists of bools. REAL properties of analog objects are always `float`, including NaN/±Infinity |
+| Errors | `ErrorPDU`/`RejectPDU`/`AbortPDU`, which derive from `BaseException`, and are sometimes returned instead of raised | always raised, all derived from `ProxyError(Exception)`, see below |
+| Object discovery | read `object-list`, then each object's properties | `list_objects()`: the proxy's cached catalog with names, units and access, in one request |
+| ReadPropertyMultiple | one request, one transaction | none. `read_properties()` sends concurrent single reads, each with its own result |
+| WriteProperty with array index | supported | not supported by the proxy |
+| Authorization | none | a bearer token per `Client`. The proxy's rules decide what it may read and write (`ObjectSummary.access`) |
+
+## Errors
+
+| Exception | Cause | Retried |
+|---|---|---|
+| `CommunicationError` | proxy unreachable, or a reply that couldn't be decoded | yes |
+| `BadRequestError` | 400, malformed request | no |
+| `UnauthorizedError` | 401, token not accepted | no |
+| `ForbiddenError` | 403, the proxy's authorization denies the request | no |
+| `NotFoundError` | 404, unknown device, object or property | no |
+| `ValueRejectedError` | 422, the device rejected the written value | no |
+| `BACnetError` | 502, BACnet Error/Reject/Abort from the device; `error_class`/`error_code` hold its numeric Error_Class/Error_Code | yes, except unknown-object/unknown-property |
+| `BACnetTimeoutError` | 504, the device didn't answer | yes |
+
+`ProxyStatusError.is_unknown_object_or_property` is true when the proxy
+reports a missing object or property, whether it does so as a 404 or as a
+502 from the device. Code that probes for optional properties, such as
+`priority-array`, can check this one attribute.
+
+Retries use exponential backoff as configured by `RetryPolicy` (default:
+5 attempts, 1s doubling to at most 8s). Retry warnings are logged to the
+`bacnet_ip_rest_client` logger. Writes are retried too, since writing the
+same value at the same priority again has no further effect.
+
+`concurrency` (default 10) caps the number of requests one `Client` has in
+flight. The proxy serializes traffic to the device itself; this cap only
+keeps a large `read_properties()` from opening hundreds of connections to
+the proxy.
+
+## Development
+
+```sh
+uv run pytest
+```

bacnet_ip_rest_client-1.0.0/docs/api.md

@@ -0,0 +1,3 @@
+# API reference
+
+::: bacnet_ip_rest_client

bacnet_ip_rest_client-1.0.0/docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

bacnet_ip_rest_client-1.0.0/mkdocs.yml

@@ -0,0 +1,69 @@
+site_name: BACnet/IP REST Client
+site_description: Async Python client for the BACnet/IP REST proxy
+site_url: https://stblassitude.github.io/bacnet-ip-rest-client/
+repo_url: https://github.com/stblassitude/bacnet-ip-rest-client
+repo_name: stblassitude/bacnet-ip-rest-client
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  features:
+    - content.code.copy
+    - navigation.footer
+    - navigation.instant
+    - search.highlight
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: teal
+      accent: blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: teal
+      accent: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - pymdownx.details
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.snippets:
+      check_paths: true
+  - pymdownx.superfences
+  - tables
+  - toc:
+      permalink: true
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            docstring_style: google
+            members_order: source
+            merge_init_into_class: true
+            separate_signature: true
+            show_signature_annotations: true
+            signature_crossrefs: true
+            show_source: false
+            show_root_heading: false
+            show_root_toc_entry: false
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            filters: ["!^_"]
+          inventories:
+            - https://docs.python.org/3/objects.inv
+
+nav:
+  - Overview: index.md
+  - API reference: api.md

bacnet_ip_rest_client-1.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "bacnet-ip-rest-client"
+version = "1.0.0"
+authors = [
+    { name = "Stefan Bethke", email = "stb@lassitu.de" },
+]
+description = "Async Python client for the BACnet/IP REST proxy"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = ["bacnet", "building-automation", "rest", "httpx", "asyncio"]
+dependencies = [
+    "httpx>=0.28.1",
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/stblassitude/bacnet-ip-rest-client"
+Documentation = "https://stblassitude.github.io/bacnet-ip-rest-client/"
+Issues = "https://github.com/stblassitude/bacnet-ip-rest-client/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+]
+# MkDocs 2.0 is incompatible with Material for MkDocs
+docs = [
+    "mkdocs>=1.6,<2",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.29",
+    "ruff",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

bacnet_ip_rest_client-1.0.0/src/bacnet_ip_rest_client/__init__.py

@@ -0,0 +1,45 @@
+"""Client for the BACnet/IP REST proxy
+(https://github.com/stblassitude/bacnet-ip-rest-proxy)."""
+
+from .client import API_PATH, Client, RetryPolicy, is_transient
+from .errors import (
+    ERROR_CODE_UNKNOWN_OBJECT,
+    ERROR_CODE_UNKNOWN_PROPERTY,
+    BACnetError,
+    BACnetTimeoutError,
+    BadRequestError,
+    CommunicationError,
+    ForbiddenError,
+    NotFoundError,
+    ProxyError,
+    ProxyStatusError,
+    UnauthorizedError,
+    ValueRejectedError,
+)
+from .objects import PRIORITY_COUNT, Access, ObjectIdentifier, ObjectSummary
+from .values import decode_value, encode_value
+
+__all__ = [
+    "API_PATH",
+    "Access",
+    "BACnetError",
+    "BACnetTimeoutError",
+    "BadRequestError",
+    "Client",
+    "CommunicationError",
+    "ERROR_CODE_UNKNOWN_OBJECT",
+    "ERROR_CODE_UNKNOWN_PROPERTY",
+    "ForbiddenError",
+    "NotFoundError",
+    "ObjectIdentifier",
+    "ObjectSummary",
+    "PRIORITY_COUNT",
+    "ProxyError",
+    "ProxyStatusError",
+    "RetryPolicy",
+    "UnauthorizedError",
+    "ValueRejectedError",
+    "decode_value",
+    "encode_value",
+    "is_transient",
+]