qbvisor 0.3.0__tar.gz

qbvisor-0.3.0/.env.example

@@ -0,0 +1,13 @@
+# Runtime configuration
+QB_REALM_HOSTNAME=your-realm.quickbase.com
+QB_REALM_API_KEY=QB-USER-TOKEN replace-with-your-token
+QB_APP_IDS={"Sandbox":"replace-with-your-app-id"}
+
+# Dedicated persistent sandbox used by live integration tests
+QBVISOR_TEST_REALM=your-realm.quickbase.com
+QBVISOR_TEST_TOKEN=QB-USER-TOKEN replace-with-your-sandbox-token
+QBVISOR_TEST_APP_ID=replace-with-your-sandbox-app-id
+
+# Set only for an intentional live test run. Mutations must target an isolated sandbox.
+QBVISOR_RUN_INTEGRATION=0
+QBVISOR_ALLOW_SANDBOX_MUTATIONS=0

qbvisor-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,115 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation:
+    name: Documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-groups
+
+      - name: Verify documentation sources
+        run: uv run --frozen python scripts/verify_docs.py
+
+      - name: Build documentation
+        run: uv run --frozen mkdocs build --strict
+
+  quality:
+    name: Quality (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-groups
+
+      - name: Check linting
+        run: uv run --frozen ruff check .
+
+      - name: Check formatting
+        run: uv run --frozen ruff format --check .
+
+      - name: Check typing
+        run: uv run --frozen mypy src/qbvisor
+
+      - name: Run tests
+        run: uv run --frozen pytest
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Build package
+        run: uv build
+
+      - name: Validate distribution metadata and contents
+        run: |
+          uv run --frozen twine check --strict dist/*
+          uv run --frozen python scripts/verify_distribution.py dist
+
+      - name: Verify wheel installation
+        run: |
+          wheel_path="$(find dist -name '*.whl' -print -quit)"
+          uv run --isolated --no-project --with "$wheel_path" \
+            python -c "import qbvisor; print(qbvisor.__version__)"
+
+      - name: Verify installed type information
+        run: |
+          wheel_path="$(find dist -name '*.whl' -print -quit)"
+          mypy_version="$(uv run --frozen mypy --version | awk '{print $2}')"
+          uv run --isolated --no-project --with "$wheel_path" --with "mypy==$mypy_version" \
+            mypy --config-file=/dev/null --strict tests/typing/installed_package.py

qbvisor-0.3.0/.github/workflows/pages.yml

@@ -0,0 +1,73 @@
+name: Documentation site
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/pages.yml"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "scripts/verify_docs.py"
+      - "src/qbvisor/**"
+      - "uv.lock"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build documentation site
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-groups
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - name: Verify documentation sources
+        run: uv run --frozen python scripts/verify_docs.py
+
+      - name: Build documentation
+        run: uv run --frozen mkdocs build --strict
+
+      - name: Upload documentation site
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site/
+
+  deploy:
+    name: Deploy documentation site
+    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@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

qbvisor-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,76 @@
+name: Release
+
+on:
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build release distributions
+    if: ${{ !github.event.release.prerelease }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out the release tag
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Verify the release commit is on main
+        run: git merge-base --is-ancestor "$GITHUB_SHA" origin/main
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Validate release identity and distributions
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          uv run --frozen twine check --strict dist/*
+          uv run --frozen python scripts/verify_distribution.py \
+            dist --release-tag "$RELEASE_TAG"
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish distributions to PyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/qbvisor
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions with attestations
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1

qbvisor-0.3.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+.venv/
+.venv.nosync/
+.uv-cache.nosync/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+build/
+dist/
+site/
+*.egg-info/
+*.whl
+*.py[cod]
+*.pyo
+*.pyd
+.env
+.env.*
+!.env.example
+*.log
+*.csv
+*.json
+!docs/api/*.json
+
+# Temp files
+tmp/
+temp/
+
+# Log directories
+logs/
+
+# OS/IDE specific files
+.DS_Store
+.vscode/
+.idea/
+
+# Local API specifications and audit inputs
+.cache/
+.qbvisor/

qbvisor-0.3.0/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+This file records user-visible changes to qbvisor. The project follows
+[Semantic Versioning](https://semver.org/) and keeps unreleased work under the `Unreleased`
+heading.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-07-19
+
+### Added
+
+- Add public package metadata, inline typing, release and security policies, and distribution
+  artifact validation ([#18]).
+- Add trusted PyPI publishing with isolated OpenID Connect permissions, release identity checks,
+  artifact attestations, and a documented maintainer procedure ([#20]).
+- Add task-focused guides, a generated public API reference, strict documentation validation, and
+  the `0.3.0` migration guide ([#19]).
+- Publish the reviewed documentation site through GitHub Pages and expose its canonical URL in
+  package metadata ([#21]).
+- Add a shared synchronous transport with pooled connections, explicit timeouts, structured
+  exceptions, and operation-aware retries ([#3]).
+- Add app events, app roles, field usage, relationship lookup, relationship summary, and record
+  change endpoints ([#5], [#11], [#12]).
+- Add versioned application backups with manifests, attachment capture, integrity verification,
+  and consistency checks ([#7]).
+- Add declarative application and table schemas with reviewable plans, durable resource bindings,
+  relationship management, and native Quickbase formula fields ([#8], [#10]).
+- Add a tracked Quickbase OpenAPI response-shape manifest and opt-in persistent sandbox contract
+  tests ([#2], [#3]).
+
+### Changed
+
+- Move app, table, field, and relationship operations behind private resource services while
+  preserving `QuickBaseClient` as the public facade ([#6]).
+- Return complete DataFrame queries and report results by default without changing their public
+  method signatures ([#14]).
+- Scan record exports in stable Record ID order and write through temporary files before publishing
+  completed CSV files ([#13]).
+- Batch record upserts by the exact serialized payload size, aggregate complete Quickbase outcomes,
+  and report partially completed or uncertain ranges ([#16], [#17]).
+- Use bounded asynchronous I/O for attachment downloads while preserving the existing synchronous
+  entry points and result fields ([#4], [#15]).
+
+### Fixed
+
+- Report the installed package version in the HTTP `User-Agent` instead of a stale hard-coded
+  version.
+- Preserve attachment bytes across response encodings and base64 conversion ([#9]).
+- Continue attachment discovery until Quickbase metadata confirms that all matching records have
+  been scanned ([#15]).
+- Normalize record-change timestamps to conservative whole-second UTC values ([#12]).
+- Invalidate and reuse table and field metadata without returning stale schema state ([#11]).
+
+### Security
+
+- Keep authorization values and request bodies out of transport logs and public exception messages
+  ([#3]).
+- Validate backup paths, attachment paths, and downloaded filenames before publishing files ([#7],
+  [#15]).
+
+## [0.2.0] - 2025-12-30
+
+### Added
+
+- Add small logging entry hooks and publish the `0.2.0` package metadata.
+
+## [0.1.1] - 2025-06-19
+
+### Changed
+
+- Expand query options, lower attachment concurrency for reliability, and expose more upsert
+  response information.
+
+## [0.1.0] - 2025-05-13
+
+### Added
+
+- Publish the initial Quickbase client, query helpers, transport, tests, and project documentation.
+
+[Unreleased]: https://github.com/ChrisEMetcalf/qbvisor/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/ChrisEMetcalf/qbvisor/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/ChrisEMetcalf/qbvisor/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/ChrisEMetcalf/qbvisor/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/ChrisEMetcalf/qbvisor/releases/tag/v0.1.0
+[#2]: https://github.com/ChrisEMetcalf/qbvisor/pull/2
+[#3]: https://github.com/ChrisEMetcalf/qbvisor/pull/3
+[#4]: https://github.com/ChrisEMetcalf/qbvisor/pull/4
+[#5]: https://github.com/ChrisEMetcalf/qbvisor/pull/5
+[#6]: https://github.com/ChrisEMetcalf/qbvisor/pull/6
+[#7]: https://github.com/ChrisEMetcalf/qbvisor/pull/7
+[#8]: https://github.com/ChrisEMetcalf/qbvisor/pull/8
+[#9]: https://github.com/ChrisEMetcalf/qbvisor/pull/9
+[#10]: https://github.com/ChrisEMetcalf/qbvisor/pull/10
+[#11]: https://github.com/ChrisEMetcalf/qbvisor/pull/11
+[#12]: https://github.com/ChrisEMetcalf/qbvisor/pull/12
+[#13]: https://github.com/ChrisEMetcalf/qbvisor/pull/13
+[#14]: https://github.com/ChrisEMetcalf/qbvisor/pull/14
+[#15]: https://github.com/ChrisEMetcalf/qbvisor/pull/15
+[#16]: https://github.com/ChrisEMetcalf/qbvisor/pull/16
+[#17]: https://github.com/ChrisEMetcalf/qbvisor/pull/17
+[#18]: https://github.com/ChrisEMetcalf/qbvisor/pull/18
+[#19]: https://github.com/ChrisEMetcalf/qbvisor/pull/19
+[#20]: https://github.com/ChrisEMetcalf/qbvisor/pull/20
+[#21]: https://github.com/ChrisEMetcalf/qbvisor/pull/21

qbvisor-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to qbvisor
+
+qbvisor is shared infrastructure for developers who build on Quickbase. Changes should improve reliability, performance, idempotency, or developer experience.
+
+## Requirements
+
+- Python 3.12, 3.13, or 3.14
+- [uv](https://docs.astral.sh/uv/)
+
+## Setup
+
+```bash
+uv sync --all-groups
+```
+
+Run the local checks before opening a pull request:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src/qbvisor
+uv run pytest
+uv run python scripts/verify_docs.py
+uv run mkdocs build --strict
+uv build
+uv run twine check --strict dist/*
+uv run python scripts/verify_distribution.py dist
+```
+
+## Compatibility
+
+Existing public method names and call signatures should remain stable when practical. Clearly broken behavior may be corrected when the change includes regression tests and release notes.
+
+`QuickBaseClient` is the supported high-level client. Preserve its public method names and call signatures unless a documented major release provides a migration path.
+
+Record user-visible behavior in [CHANGELOG.md](CHANGELOG.md). Follow the versioning, Python support,
+deprecation, and artifact requirements in [docs/release-policy.md](docs/release-policy.md).
+Maintainers should use the controlled procedure in [docs/releasing.md](docs/releasing.md) for tags,
+GitHub Releases, and PyPI publication.
+
+## Client architecture
+
+`QuickBaseClient` is the stable public facade. Private modules under `qbvisor._resources` own request construction for apps, tables, fields, and relationships. These resource classes are implementation details: do not export them from `qbvisor`, document them as public interfaces, or require callers to construct them.
+
+Public client methods should remain thin delegates while preserving their established signature, return shape, retry policy, error behavior, and metadata-cache effects. Resource services receive shared transport and metadata behavior through `ClientContext`; they must continue using the centralized client request path rather than creating sessions or duplicating error handling.
+
+When moving an existing operation across this boundary, add a compatibility test for its exact request path, parameters, body, and documented top-level response shape. Schema mutations also require focused verification of label-to-ID resolution and cache invalidation.
+
+## Pull requests
+
+Keep each pull request focused on one reviewable change. Describe:
+
+- The problem being solved
+- The direct and downstream effects
+- Compatibility or migration concerns
+- The checks used to verify the change
+
+Changes require passing automated checks and an approving review before merge.
+
+## Integration testing
+
+Unit tests and HTTP contract tests must not require Quickbase credentials.
+
+Integration tests use a dedicated persistent sandbox application. Configure `QBVISOR_TEST_REALM`, `QBVISOR_TEST_TOKEN`, and `QBVISOR_TEST_APP_ID` locally; these values must never be committed.
+
+Run the established sandbox contract without allowing fixture changes:
+
+```bash
+QBVISOR_RUN_INTEGRATION=1 uv run pytest -m integration --no-cov
+```
+
+Bootstrap missing persistent fixtures and run mutation contracts only with explicit approval:
+
+```bash
+QBVISOR_RUN_INTEGRATION=1 QBVISOR_ALLOW_SANDBOX_MUTATIONS=1 \
+  uv run pytest -m integration --no-cov
+```
+
+Mutation tests are outside the default suite. They must verify the configured realm and application ID, use uniquely named temporary resources, and clean up after themselves. Never run integration tests against a production application.
+
+## Quickbase API contract audit
+
+The official Quickbase OAS is cached locally and excluded from version control. Refresh it and update the tracked response manifest with:
+
+```bash
+uv run python scripts/audit_quickbase_oas.py --refresh --write
+```
+
+Audit the existing cached document without network access with:
+
+```bash
+uv run python scripts/audit_quickbase_oas.py
+```
+
+Review changes to `docs/api/quickbase-oas-manifest.json` as API contract changes, not generated noise.

qbvisor-0.3.0/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2025 Chris Metcalf
+
+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.