oblidog-client 0.1.1__tar.gz

oblidog_client-0.1.1/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

oblidog_client-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Sync dependencies
+        run: uv sync --all-groups
+
+      - name: Ruff check
+        run: uv run ruff check src tests scripts
+
+      - name: Ruff format check
+        run: uv run ruff format --check src tests scripts
+
+      - name: Tests
+        run: uv run pytest -q
+
+      - name: Build documentation
+        run: uv run --group docs mkdocs build --strict
+
+      - name: Compile package
+        run: python -m compileall -q src/oblidog_client
+
+  distribution:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Verify distributions and installed API
+        run: ./scripts/verify-package.sh

oblidog_client-0.1.1/.github/workflows/docs-pages.yml

@@ -0,0 +1,61 @@
+name: Publish documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Sync locked documentation environment
+        run: uv sync --locked --group docs
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v6
+        with:
+          enablement: true
+
+      - name: Build documentation
+        run: uv run --group docs mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

oblidog_client-0.1.1/.github/workflows/prepare-release.yml

@@ -0,0 +1,111 @@
+name: Prepare release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: prepare-release-main
+  cancel-in-progress: false
+
+jobs:
+  prepare-release:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Sync locked dependencies
+        run: uv sync --all-groups --locked
+
+      - name: Check initial release is finalized
+        id: state
+        shell: bash
+        run: |
+          current_version="$(uv run cz version -p)"
+          if ! git rev-parse -q --verify "refs/tags/v${current_version}" >/dev/null; then
+            echo "v${current_version} is not tagged; create the initial release first."
+            echo "ready=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "ready=true" >> "$GITHUB_OUTPUT"
+
+      - name: Determine next version
+        if: steps.state.outputs.ready == 'true'
+        id: version
+        shell: bash
+        run: |
+          set +e
+          next_version="$(uv run cz bump --dry-run --yes --get-next)"
+          status=$?
+          set -e
+          if [[ $status -eq 3 || $status -eq 21 ]]; then
+            echo "No releasable Conventional Commit found."
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [[ $status -ne 0 ]]; then
+            exit "$status"
+          fi
+          echo "should_release=true" >> "$GITHUB_OUTPUT"
+          echo "version=$next_version" >> "$GITHUB_OUTPUT"
+
+      - name: Check release branch
+        if: steps.version.outputs.should_release == 'true'
+        id: branch
+        env:
+          RELEASE_BRANCH: release/v${{ steps.version.outputs.version }}
+        shell: bash
+        run: |
+          if git ls-remote --exit-code --heads origin "$RELEASE_BRANCH" >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Prepare and push release branch
+        if: steps.version.outputs.should_release == 'true' && steps.branch.outputs.exists == 'false'
+        env:
+          RELEASE_BRANCH: release/v${{ steps.version.outputs.version }}
+          RELEASE_VERSION: ${{ steps.version.outputs.version }}
+        shell: bash
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          uv run cz bump --yes --check-consistency
+          git tag -d "v${RELEASE_VERSION}"
+          uv lock
+          git add uv.lock
+          git commit --amend --no-edit
+          git push origin HEAD:"refs/heads/${RELEASE_BRANCH}"
+
+      - name: Ensure release pull request
+        if: steps.version.outputs.should_release == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_BRANCH: release/v${{ steps.version.outputs.version }}
+          RELEASE_VERSION: ${{ steps.version.outputs.version }}
+        shell: bash
+        run: |
+          if gh pr list --base main --head "$RELEASE_BRANCH" --state open --json url --jq '.[0].url' | grep -q .; then
+            exit 0
+          fi
+          gh pr create --base main --head "$RELEASE_BRANCH" \
+            --title "bump: version $RELEASE_VERSION" \
+            --body "Automated release preparation for v$RELEASE_VERSION. Merge after checks pass, then publish a GitHub Release for v$RELEASE_VERSION to release the package to PyPI."

oblidog_client-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,138 @@
+name: Release
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: Existing vX.Y.Z or vX.Y.ZrcN tag to publish to TestPyPI
+        required: true
+        type: string
+      target:
+        description: Manual runs are restricted to TestPyPI
+        required: true
+        type: choice
+        options:
+          - testpypi
+
+permissions:
+  contents: read
+
+concurrency:
+  group: oblidog-client-package-release
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      release-tag: ${{ steps.release.outputs.tag }}
+      target: ${{ steps.release.outputs.target }}
+    steps:
+      - name: Resolve release target
+        id: release
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          MANUAL_TAG: ${{ inputs.release_tag }}
+        shell: bash
+        run: |
+          if [[ "$EVENT_NAME" == "release" ]]; then
+            echo "tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
+            echo "target=pypi" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=$MANUAL_TAG" >> "$GITHUB_OUTPUT"
+            echo "target=testpypi" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout release tag
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ steps.release.outputs.tag }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Sync locked dependencies
+        run: uv sync --all-groups --locked
+
+      - name: Verify tag and publication order
+        env:
+          RELEASE_TAG: ${{ steps.release.outputs.tag }}
+          RELEASE_TARGET: ${{ steps.release.outputs.target }}
+        run: uv run python scripts/verify_release.py "$RELEASE_TAG" "$RELEASE_TARGET"
+
+      - name: Ruff check
+        run: uv run ruff check src tests scripts
+
+      - name: Ruff format check
+        run: uv run ruff format --check src tests scripts
+
+      - name: Tests
+        run: uv run pytest -q
+
+      - name: Compile package
+        run: python -m compileall -q src/oblidog_client
+
+      - name: Build and verify distributions
+        run: ./scripts/verify-package.sh
+
+      - name: Upload verified distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-testpypi:
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/oblidog-client/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download verified distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: github.event_name == 'release' && github.event.action == 'published'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/oblidog-client/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download verified distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

oblidog_client-0.1.1/.github/workflows/update-from-ledger.yml

@@ -0,0 +1,124 @@
+name: Update client from Oblidog Ledger
+
+on:
+  repository_dispatch:
+    types:
+      - ledger-release
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: Oblidog Ledger release tag, for example v0.2.0
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: update-client-from-ledger
+  cancel-in-progress: false
+
+jobs:
+  regenerate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Resolve Ledger release tag
+        id: release
+        env:
+          DISPATCH_TAG: ${{ github.event.client_payload.tag_name }}
+          MANUAL_TAG: ${{ inputs.release_tag }}
+        shell: bash
+        run: |
+          tag="${DISPATCH_TAG:-$MANUAL_TAG}"
+          if [[ -z "$tag" ]]; then
+            echo "Ledger release tag is required" >&2
+            exit 1
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Download integration OpenAPI schema
+        env:
+          RELEASE_TAG: ${{ steps.release.outputs.tag }}
+        shell: bash
+        run: |
+          mkdir -p openapi
+          base_url="https://github.com/oblidog/oblidog-ledger/releases/download/${RELEASE_TAG}"
+
+          if curl --fail --location --retry 3 \
+            "${base_url}/integration-openapi.json" \
+            --output openapi/integration.json; then
+            echo "Downloaded integration-openapi.json"
+          else
+            echo "Canonical asset not found; trying legacy integration.json"
+            curl --fail --location --retry 3 \
+              "${base_url}/integration.json" \
+              --output openapi/integration.json
+          fi
+
+      - name: Generate client
+        run: |
+          uvx --from openapi-python-client==0.29.0 openapi-python-client generate \
+            --fail-on-warning \
+            --path openapi/integration.json \
+            --config openapi-client.yaml \
+            --meta none \
+            --output-path src/oblidog_client/generated \
+            --overwrite
+
+      - name: Validate generated client
+        run: |
+          python -m compileall -q src/oblidog_client/generated
+          uv build
+
+      - name: Create update pull request
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ steps.release.outputs.tag }}
+        shell: bash
+        run: |
+          changes="$(git status --porcelain -- openapi/integration.json src/oblidog_client/generated)"
+          if [[ -z "$changes" ]]; then
+            echo "No client changes for ${RELEASE_TAG}."
+            exit 0
+          fi
+
+          branch="bot/update-from-ledger-${RELEASE_TAG}"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -B "$branch"
+          git add openapi/integration.json src/oblidog_client/generated
+          git commit -m "chore: regenerate client from ledger ${RELEASE_TAG}"
+          git push --force origin "$branch"
+
+          existing_pr="$(gh pr list \
+            --base main \
+            --head "$branch" \
+            --state open \
+            --json url \
+            --jq '.[0].url // empty')"
+
+          if [[ -n "$existing_pr" ]]; then
+            echo "Update PR already exists: $existing_pr"
+            exit 0
+          fi
+
+          gh pr create \
+            --base main \
+            --head "$branch" \
+            --title "chore: update client from ledger ${RELEASE_TAG}" \
+            --body "Regenerates the low-level Python client from the integration OpenAPI contract published with Oblidog Ledger ${RELEASE_TAG}."

oblidog_client-0.1.1/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+site/
+*.egg-info/
+.env

oblidog_client-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+## Branching
+
+`main` is the only long-lived branch and should stay releasable.
+
+Create short-lived branches for all changes, for example:
+
+- `feat/...` for features
+- `fix/...` for fixes
+- `chore/...` for maintenance
+- `bot/update-from-ledger-vX.Y.Z` for generated client updates
+
+All changes should reach `main` through pull requests.
+
+## Generated code
+
+`src/oblidog_client/generated/` is generated from the Oblidog Ledger integration OpenAPI contract. Do not edit files in that directory by hand.
+
+The source snapshot used for generation lives in `openapi/integration.json`.
+
+## Local checks
+
+Run before opening a pull request:
+
+```bash
+uv sync --all-groups
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv run pytest -q
+uv run --group docs mkdocs build --strict
+uv run --group docs mkdocs serve
+python -m compileall -q src/oblidog_client
+uv build
+```
+
+Generated code is excluded from handwritten Ruff checks and is instead validated by compilation and package build.
+
+Use `mkdocs serve` to preview the documentation locally; it watches the source
+files and prints the local URL.

oblidog_client-0.1.1/LICENSE

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

oblidog_client-0.1.1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: oblidog-client
+Version: 0.1.1
+Summary: Python client for the Oblidog integration API
+Project-URL: Homepage, https://github.com/oblidog/oblidog-client-python
+Project-URL: Documentation, https://oblidog.github.io/oblidog-client-python/
+Project-URL: Repository, https://github.com/oblidog/oblidog-client-python
+Project-URL: Issues, https://github.com/oblidog/oblidog-client-python/issues
+Project-URL: Changelog, https://github.com/oblidog/oblidog-client-python/releases
+Author: Oblidog contributors
+Maintainer: wini83
+License-Expression: MIT
+License-File: LICENSE
+Keywords: integration,oblidog,openapi,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: attrs>=23.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# oblidog-client
+
+Python client for the Oblidog integration API.
+
+Use the handwritten `OblidogClient` facade in application code. The
+`oblidog_client.generated` namespace is OpenAPI-generated transport code and is
+an implementation detail, not the recommended SDK API.
+
+## Installation
+
+```bash
+pip install oblidog-client
+```
+
+## Usage
+
+```python
+import datetime
+
+from oblidog_client import OblidogClient
+
+with OblidogClient(base_url="https://oblidog.example.com", api_key="fdg_live_...") as client:
+    with client.integrations.run() as run:
+        client.category_data.create(
+            observed_at=datetime.datetime.now(datetime.UTC),
+            data={"meter_reading_kwh": 1234.5},
+        )
+        run.finish_success(changes_detected=True)
+```
+
+The integration API key selects its integration and category. Use
+`client.integrations.run()` around synchronization work: it reads context and
+starts a run before the block, then reports a sanitized failure if the block
+raises.
+
+## Documentation
+
+The full documentation is published at
+[oblidog.github.io/oblidog-client-python](https://oblidog.github.io/oblidog-client-python/).
+It includes a quickstart, public API reference, and supported API boundary; it
+intentionally excludes generated endpoints and transport classes.
+
+## Development
+
+This project uses `uv` for dependency and environment management. The low-level client is generated from the Oblidog Ledger integration OpenAPI contract; generated code should not be edited manually.
+
+Use Commitizen to create Conventional Commit messages interactively, or to
+validate one non-interactively:
+
+```bash
+uv run cz commit
+uv run cz check -m "feat: add a new capability"
+```
+
+Run the same distribution verification used by CI locally:
+
+```bash
+./scripts/verify-package.sh
+```
+
+The command builds the wheel and source distribution, validates their metadata and contents, installs the wheel into a clean environment, and checks the installed public API. It does not publish any artifacts.
+
+Release maintainers should follow the [Trusted Publishing setup and release procedure](docs/releasing.md).