ulogger-cloud 0.3.0__tar.gz

ulogger_cloud-0.3.0/.dockerignore

@@ -0,0 +1,29 @@
+# Version control
+.git/
+.gitignore
+
+# Build outputs
+build/
+dist/
+*.egg-info/
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+
+# IDE / OS
+.vscode/
+.idea/
+*.DS_Store
+Thumbs.db
+
+# Docker artifacts
+Dockerfile
+docker-compose.yml
+
+# CI
+.github/
+
+# Scripts (not needed inside the build container)
+scripts/

ulogger_cloud-0.3.0/.github/workflows/build.yml

@@ -0,0 +1,301 @@
+name: Build & Test
+
+on:
+  push:
+    branches: ["main", "release/**"]
+    tags:     ["v*"]
+  pull_request:
+    branches: ["main"]
+  # Allow manual trigger from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # ── Build the universal wheel + sdist ONCE ─────────────────────────────────
+  # ulogger-cloud is pure Python (no C extensions), so a single build produces
+  # a py3-none-any wheel that installs on every Python version, OS, and CPU
+  # architecture without recompilation.
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history is required so setuptools-scm can find the latest tag
+          # and compute the correct version (e.g. v1.2.3 or v1.2.3.dev4+gabcdef)
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build toolchain
+        run: pip install --upgrade pip build twine
+
+      - name: Build wheel and sdist
+        run: python -m build --outdir dist/
+
+      - name: Confirm wheel is universal (py3-none-any)
+        run: |
+          WHL=$(ls dist/*.whl)
+          echo "Built: $WHL"
+          echo "$WHL" | grep -E "py3-none-any" \
+            || { echo "ERROR: wheel is not universal — C extension may have been introduced"; exit 1; }
+
+      - name: Verify distributions
+        run: twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+          retention-days: 90
+
+  # ── Test matrix: every supported Python × every major OS ──────────────────
+  # Installs the single universal wheel built above and runs pytest to confirm
+  # runtime compatibility across the full support matrix.
+  test:
+    name: "Test · Python ${{ matrix.python-version }} · ${{ matrix.os }}"
+    needs: build
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+        python-version:
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Install wheel
+        shell: bash
+        run: pip install "$(ls dist/*.whl)[dev]"
+
+      - name: Run tests
+        run: pytest --tb=short
+
+  # ── Publish to PyPI (Trusted Publishing) ───────────────────────────────────
+  # Triggered only on version tags (e.g. v1.0.0).
+  # Uses PyPI Trusted Publishing — no API tokens or secrets required.
+  # See: https://docs.pypi.org/trusted-publishers/
+  #
+  # One-time setup required on pypi.org:
+  #   1. Go to https://pypi.org/manage/account/publishing/
+  #   2. Add a "pending publisher" for:
+  #        PyPI project name:  ulogger-cloud
+  #        Owner:              ulogger-ai
+  #        Repository:         py-ulogger-cloud
+  #        Workflow name:      build.yml
+  #        Environment name:   (leave blank)
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    permissions:
+      id-token: write   # mandatory for Trusted Publishing
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # ── Publish to S3 (acts as a private PyPI simple server) ──────────────────
+  # Triggered only on version tags (e.g. v1.0.0).
+  # After uploading the new distributions the job regenerates the PEP 503
+  # simple-index HTML files so that `pip install --extra-index-url` works.
+  #
+  # Required repository secrets:
+  #   AWS_ACCESS_KEY_ID      – IAM key with s3:PutObject / s3:GetObject / s3:ListBucket
+  #   AWS_SECRET_ACCESS_KEY  – matching secret
+  #   AWS_REGION             – e.g. us-east-1
+  #
+  # pip usage after publishing:
+  #   pip install ulogger-cloud \
+  #       --extra-index-url https://pyulogger.s3.<region>.amazonaws.com/simple/
+  publish-s3:
+    name: Publish to S3 PyPI
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    permissions:
+      contents: read    # checkout is not needed; artifact download only
+      id-token: write   # reserved for future OIDC-based auth
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id:     ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region:            ${{ secrets.AWS_REGION }}
+
+      # Upload wheel + sdist to s3://pyulogger/packages/
+      # Public read access is granted via the bucket policy (ACLs are disabled
+      # because the bucket uses "Bucket owner enforced" Object Ownership).
+      - name: Upload distributions to S3
+        run: |
+          for f in dist/*; do
+            echo "Uploading $f …"
+            aws s3 cp "$f" "s3://pyulogger/packages/$(basename "$f")"
+          done
+
+      # Re-generate PEP 503 simple-index HTML files that cover every file
+      # currently in s3://pyulogger/packages/ so that the index stays in sync
+      # even when multiple versions exist.
+      - name: Regenerate PyPI simple index
+        run: |
+          python3 - <<'PYEOF'
+          import hashlib
+          import json
+          import os
+          import pathlib
+          import subprocess
+
+          BUCKET  = "pyulogger"
+          PKG     = "ulogger-cloud"   # canonical package name
+          PKG_DIR = PKG               # directory name under simple/
+
+          # ── 1. List every distribution file already in s3://pyulogger/packages/ ──
+          result = subprocess.run(
+              [
+                  "aws", "s3api", "list-objects-v2",
+                  "--bucket", BUCKET,
+                  "--prefix", "packages/",
+              ],
+              capture_output=True, text=True, check=True,
+          )
+          data    = json.loads(result.stdout)
+          objects = data.get("Contents", [])
+          keys    = sorted(
+              o["Key"] for o in objects
+              if o["Key"].endswith((".whl", ".tar.gz", ".zip"))
+          )
+
+          if not keys:
+              raise SystemExit("No distribution files found in s3://pyulogger/packages/ — aborting.")
+
+          # ── 2. Download every file to compute its sha256 digest ──────────────────
+          dl_dir = pathlib.Path("_s3_dists")
+          dl_dir.mkdir(exist_ok=True)
+
+          entries = []   # list of (filename, href_with_hash)
+          for key in keys:
+              name  = pathlib.Path(key).name
+              local = dl_dir / name
+              subprocess.run(
+                  ["aws", "s3", "cp", f"s3://{BUCKET}/{key}", str(local)],
+                  check=True,
+              )
+              digest = hashlib.sha256(local.read_bytes()).hexdigest()
+              # Absolute-path href — resolves correctly regardless of how pip
+              # interprets the trailing-slash base URL.
+              href   = f"/packages/{name}#sha256={digest}"
+              entries.append((name, href))
+
+          # ── 3. Build simple/<pkg>/index.html (PEP 503) ───────────────────────────
+          file_links = "\n".join(
+              f'    <a href="{href}">{name}</a><br />' for name, href in entries
+          )
+          pkg_html = f"""<!DOCTYPE html>
+          <html>
+            <head><title>Links for {PKG}</title></head>
+            <body>
+              <h1>Links for {PKG}</h1>
+          {file_links}
+            </body>
+          </html>
+          """
+
+          out_pkg = pathlib.Path("simple") / PKG_DIR
+          out_pkg.mkdir(parents=True, exist_ok=True)
+          (out_pkg / "index.html").write_text(pkg_html)
+
+          # ── 4. Build simple/index.html (root listing) ─────────────────────────────
+          root_html = f"""<!DOCTYPE html>
+          <html>
+            <head><title>Simple index</title></head>
+            <body>
+              <h1>Simple index</h1>
+              <a href="{PKG_DIR}/">{PKG}</a><br />
+            </body>
+          </html>
+          """
+          pathlib.Path("simple").mkdir(exist_ok=True)
+          pathlib.Path("simple/index.html").write_text(root_html)
+
+          print("Generated index files:")
+          for p in pathlib.Path("simple").rglob("*.html"):
+              print(f"  {p}")
+              print(p.read_text())
+          PYEOF
+
+      # Upload simple-index HTML files to S3.
+      #
+      # KEY TRICK: pip requests  /simple/ulogger-cloud/  (trailing slash).
+      # `aws s3 cp dest/` appends the source filename → creates index.html, NOT "/".
+      # `aws s3api put-object --key "simple/ulogger-cloud/"` creates the key
+      # with a literal trailing slash, so pip's GET hits it directly.
+      - name: Upload simple index to S3
+        run: |
+          # Trailing-slash keys — exactly what pip GETs
+          aws s3api put-object \
+              --bucket pyulogger \
+              --key "simple/" \
+              --body simple/index.html \
+              --content-type "text/html; charset=utf-8"
+
+          aws s3api put-object \
+              --bucket pyulogger \
+              --key "simple/ulogger-cloud/" \
+              --body "simple/ulogger-cloud/index.html" \
+              --content-type "text/html; charset=utf-8"
+
+          # index.html variants — convenient for browser navigation
+          aws s3 cp simple/index.html \
+              "s3://pyulogger/simple/index.html" \
+              --content-type "text/html; charset=utf-8"
+
+          aws s3 cp "simple/ulogger-cloud/index.html" \
+              "s3://pyulogger/simple/ulogger-cloud/index.html" \
+              --content-type "text/html; charset=utf-8"
+
+          echo "Published. Install with:"
+          echo "  pip install ulogger-cloud \\"
+          echo "      --extra-index-url https://pyulogger.s3.${{ secrets.AWS_REGION }}.amazonaws.com/simple/"

ulogger_cloud-0.3.0/.gitignore

@@ -0,0 +1,26 @@
+# Build outputs
+dist/
+build/
+*.egg-info/
+
+# setuptools-scm generated version file (written at build time, not committed)
+ulogger_cloud/_version.py
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE / OS
+.vscode/
+.idea/
+*.DS_Store
+Thumbs.db

ulogger_cloud-0.3.0/Dockerfile

@@ -0,0 +1,44 @@
+# ── Build image for ulogger-cloud ──────────────────────────────────────────
+# ulogger-cloud is pure Python, so a single build produces a py3-none-any
+# wheel that works on every Python version, OS, and CPU architecture.
+#
+# The version is derived from the git tag via setuptools-scm.  Because the
+# Docker build context contains only source files (no .git directory), the
+# version must be supplied explicitly via --build-arg:
+#
+#   VERSION=$(git describe --tags --abbrev=0 | sed 's/^v//')
+#   docker build --build-arg VERSION=$VERSION -t ulogger-cloud-build .
+#   docker run --rm -v "$(pwd)/dist:/dist" ulogger-cloud-build
+#
+# If VERSION is omitted the build defaults to "0.0.0.dev0".
+
+ARG VERSION=0.0.0.dev0
+FROM python:3.12-slim
+
+# Make the version available to the build step below
+ARG VERSION
+ENV SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION}
+
+LABEL org.opencontainers.image.title="ulogger-cloud build"
+LABEL org.opencontainers.image.description="Builds universal py3-none-any wheel + sdist"
+
+WORKDIR /src
+
+
+# ── Python build toolchain ─────────────────────────────────────────────────
+RUN pip install --no-cache-dir --upgrade pip build twine
+
+# ── Copy source ────────────────────────────────────────────────────────────
+COPY pyproject.toml README.md ./
+COPY ulogger_cloud/ ulogger_cloud/
+
+# ── Build ──────────────────────────────────────────────────────────────────
+# Output lands in /src/dist/
+RUN python -m build --outdir /src/dist
+
+# ── Verify the distributions look correct ─────────────────────────────────
+RUN twine check /src/dist/*
+
+# ── Runtime: copy artefacts out to /dist (bind-mounted by caller) ──────────
+CMD ["sh", "-c", \
+     "cp -v /src/dist/* /dist/ && echo 'Build artefacts copied to /dist'"]

ulogger_cloud-0.3.0/LICENSE

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

ulogger_cloud-0.3.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: ulogger-cloud
+Version: 0.3.0
+Summary: uLogger cloud communication library – MQTT session management, binary log upload, and data validation.
+Author-email: Eric Ibarra <support@ulogger.ai>
+Maintainer-email: Eric Ibarra <support@ulogger.ai>
+License: MIT
+Project-URL: Homepage, https://ulogger.ai
+Project-URL: Documentation, https://ulogger.ai/documentation
+Project-URL: Release Notes, https://github.com/ulogger-ai/py-ulogger-cloud/releases
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt<3,>=1.6
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# ulogger-cloud
+
+A Python library for communicating with the [uLogger](https://ulogger.ai) cloud
+platform.  It handles:
+
+* **Device registration** – MQTT boot handshake to obtain a session token.
+* **Binary log upload** – publish raw log data to the cloud for server-side
+  parsing and visualisation.
+* **Header checksum validation** – verify the integrity of a firmware log
+  buffer before upload.
+* **Session token caching** – persist tokens to disk so re-registration is
+  skipped on subsequent runs (or across firmware upgrades).
+
+## Installation
+
+```bash
+pip install ulogger-cloud
+```
+
+Requires Python 3.9 or later.  The only runtime dependency is
+[paho-mqtt](https://pypi.org/project/paho-mqtt/) (`>=1.6`), which is
+installed automatically.
+
+## Quick start
+
+### High-level API (recommended)
+
+`upload_log` handles everything in one call: checksum validation, session-token
+retrieval (with caching), header patching, and MQTT publish.
+
+```python
+from pathlib import Path
+from ulogger_cloud import DeviceInfo, MqttConfig, upload_log
+
+# Device identification – normally parsed from a BLE characteristic
+device = DeviceInfo(
+    application_id=42,
+    device_serial="ABC123",
+    device_type="my_board",
+    git_version="v1.0.0",
+    git_hash="abcdef0",
+)
+
+# MQTT broker configuration
+mqtt_cfg = MqttConfig(
+    cert_file=Path("certificate.pem.crt"),
+    key_file=Path("private.pem.key"),
+    customer_id=975773647,
+)
+
+# buf is a bytearray received over BLE
+success = upload_log(device, buf, mqtt_cfg)
+print("Upload OK" if success else "Upload failed")
+```
+
+### Persistent session-token cache
+
+By default `upload_log` uses an **in-memory** token store that is discarded
+when the process exits.  To avoid a new MQTT boot handshake on every run,
+pass a file-backed `SessionStore`:
+
+```python
+from ulogger_cloud import (
+    DeviceInfo, MqttConfig, SessionStore,
+    DEFAULT_FILE_STORE_PATH, upload_log,
+)
+
+store = SessionStore(path=DEFAULT_FILE_STORE_PATH)  # ~/.ulogger/session_tokens.json
+
+success = upload_log(device, buf, mqtt_cfg, store=store)
+```
+
+Tokens are automatically invalidated whenever the device firmware's
+`git_hash` changes, triggering a fresh registration transparently.
+
+### Low-level building blocks
+
+If you need finer control you can call each step individually:
+
+```python
+from pathlib import Path
+from ulogger_cloud import (
+    DeviceInfo,
+    MqttConfig,
+    get_session_token,
+    patch_session_token,
+    publish_binary_log,
+    validate_checksum,
+)
+
+device = DeviceInfo(
+    application_id=42,
+    device_serial="ABC123",
+    device_type="my_board",
+    git_version="v1.0.0",
+    git_hash="abcdef0",
+)
+
+mqtt_cfg = MqttConfig(
+    cert_file=Path("certificate.pem.crt"),
+    key_file=Path("private.pem.key"),
+    customer_id=975773647,
+)
+
+buf = bytearray(raw_ble_transfer)
+if validate_checksum(bytes(buf)):
+    token = get_session_token(device, mqtt_cfg)
+    if token is not None:
+        patch_session_token(buf, token)
+    publish_binary_log(device, bytes(buf), mqtt_cfg)
+```
+
+## API reference
+
+### `DeviceInfo`
+
+Dataclass holding device identification read from the firmware:
+
+| Field | Type | Description |
+|---|---|---|
+| `application_id` | `int` | Application ID (uint32) |
+| `device_serial` | `str` | Unique device serial string |
+| `device_type` | `str` | Board / product type string |
+| `git_version` | `str` | Human-readable firmware version tag |
+| `git_hash` | `str` | Short git commit hash of the firmware |
+
+### `MqttConfig`
+
+Dataclass for MQTT broker connection parameters:
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `broker` | `str` | `"mqtt.ulogger.ai"` | Broker hostname |
+| `port` | `int` | `8883` | Broker port (TLS) |
+| `cert_file` | `Path \| None` | `None` | Path to client certificate (`.pem.crt`) |
+| `key_file` | `Path \| None` | `None` | Path to private key (`.pem.key`) |
+| `customer_id` | `int` | `0` | Customer account ID |
+| `token_timeout` | `float` | `15.0` | Seconds to wait for session-token response |
+
+### `SessionStore`
+
+Thread-safe mapping of device serial numbers to session tokens.
+
+```python
+from ulogger_cloud import SessionStore, DEFAULT_FILE_STORE_PATH
+
+# In-memory only (default)
+store = SessionStore()
+
+# File-backed persistence
+store = SessionStore(path=DEFAULT_FILE_STORE_PATH)
+
+# Memory-capped + file-backed (keeps the 1 000 most-recently-used tokens)
+store = SessionStore(path=DEFAULT_FILE_STORE_PATH, max_entries=1000)
+```
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `upload_log(device, buf, cfg, store=None)` | Validate, patch, and publish a binary log buffer. Returns `True` on success. |
+| `get_or_fetch_token(device, cfg, store=None)` | Return a cached token or perform a fresh MQTT boot registration. |
+| `get_session_token(device, cfg)` | Perform an MQTT boot registration and return the server-issued token. |
+| `validate_checksum(buf)` | Return `True` if the binary log header checksum is valid. |
+| `patch_session_token(buf, token)` | Write a session token into the binary log header in-place. |
+| `publish_binary_log(device, buf, cfg)` | Publish a raw binary log buffer to the MQTT broker. |
+
+## Development
+
+```bash
+git clone https://github.com/your-org/ulogger-cloud.git
+cd ulogger-cloud
+pip install -e ".[dev]"
+pytest
+```