coderpad-py 2026.9.7__tar.gz

coderpad_py-2026.9.7/.git_archival.txt

@@ -0,0 +1 @@
+ref-names: $Format:%D$

coderpad_py-2026.9.7/.gitattributes

@@ -0,0 +1,2 @@
+.git_archival.txt  export-subst
+* text=auto eol=lf

coderpad_py-2026.9.7/.github/dependabot.yml

@@ -0,0 +1,19 @@
+---
+version: 2
+
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: pre-commit
+    directory: /
+    schedule:
+      interval: daily

coderpad_py-2026.9.7/.github/workflows/autofix.yml

@@ -0,0 +1,37 @@
+---
+name: autofix.ci
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  autofix:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+
+      - name: Run fixers
+        uses: j178/prek-action@v3.0.0
+        with:
+          prek-version: 0.4.11
+          extra-args: >-
+            --all-files --hook-stage pre-commit --no-fail-fast --verbose
+        env:
+          UV_NO_CACHE: '1'
+          UV_PYTHON: 3.13
+
+      - uses: autofix-ci/action@v1.3.4
+        if: always()

coderpad_py-2026.9.7/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+---
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # * is a special character in YAML so you have to quote this string
+    # Run at 1:00 every day
+    - cron: 0 1 * * *
+
+permissions: {}
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13', '3.14']
+        platform: [ubuntu-latest, windows-latest]
+
+    runs-on: ${{ matrix.platform }}
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          cache-dependency-glob: '**/pyproject.toml'
+
+      - name: Run tests
+        run: |
+          # We run tests against "." and not the tests directory as we test the README
+          # and documentation.
+          uv run --extra=dev --python=${{ matrix.python-version }} pytest -s -vvv --cov-fail-under 100 --cov=src/ --cov=tests/ .
+
+  completion-ci:
+    needs: build
+    runs-on: ubuntu-latest
+    if: always()  # Run even if one matrix job fails
+    steps:
+      - name: Check matrix job status
+        run: |-
+          if ! ${{ needs.build.result == 'success' }}; then
+            echo "One or more matrix jobs failed"
+            exit 1
+          fi

coderpad_py-2026.9.7/.github/workflows/dependabot-merge.yml

@@ -0,0 +1,19 @@
+---
+
+name: Dependabot auto-merge
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependabot:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    steps:
+      - name: Enable auto-merge for Dependabot PRs
+        run: gh pr merge --auto --merge "$PR_URL"
+        env:
+          PR_URL: ${{github.event.pull_request.html_url}}
+          GH_TOKEN: ${{secrets.GITHUB_TOKEN}}

coderpad_py-2026.9.7/.github/workflows/lint.yml

@@ -0,0 +1,57 @@
+---
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # * is a special character in YAML so you have to quote this string
+    # Run at 1:00 every day
+    - cron: 0 1 * * *
+
+permissions: {}
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        python-version: ['3.13']
+        platform: [ubuntu-latest, windows-latest]
+        hook-stage: [pre-commit, pre-push, manual]
+
+    runs-on: ${{ matrix.platform }}
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          cache-dependency-glob: '**/pyproject.toml'
+
+      - name: Lint
+        uses: j178/prek-action@v3.0.0
+        with:
+          prek-version: 0.4.11
+          extra-args: >-
+            --all-files --hook-stage ${{ matrix.hook-stage }} --verbose
+        env:
+          UV_NO_CACHE: '1'
+          UV_PYTHON: ${{ matrix.python-version }}
+
+  completion-lint:
+    needs: build
+    runs-on: ubuntu-latest
+    if: always()  # Run even if one matrix job fails
+    steps:
+      - name: Check matrix job status
+        run: |-
+          if ! ${{ needs.build.result == 'success' }}; then
+            echo "One or more matrix jobs failed"
+            exit 1
+          fi

coderpad_py-2026.9.7/.github/workflows/publish-site.yml

@@ -0,0 +1,28 @@
+---
+name: Deploy documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  pages:
+    runs-on: ubuntu-latest
+    environment:
+      name: ${{ github.ref_name == 'main' && 'github-pages' || 'development' }}
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: sphinx-notes/pages@v3
+        with:
+          documentation_path: docs/source
+          pyproject_extras: dev
+          python_version: '3.13'
+          sphinx_build_options: -W
+          cache: false
+          publish: ${{ github.ref_name == 'main' }}

coderpad_py-2026.9.7/.github/workflows/release.yml

@@ -0,0 +1,105 @@
+---
+name: Release
+
+on: workflow_dispatch
+
+jobs:
+  build:
+    name: Publish a release
+    runs-on: ubuntu-latest
+
+    # Specifying an environment is strongly recommended by PyPI.
+    # See https://github.com/pypa/gh-action-pypi-publish/tree/release/v1/?tab=readme-ov-file#trusted-publishing.
+    environment: release
+
+    permissions:
+      # This is needed for PyPI publishing.
+      # See https://github.com/pypa/gh-action-pypi-publish/tree/release/v1/?tab=readme-ov-file#trusted-publishing.
+      id-token: write
+      # This is needed for https://github.com/stefanzweifel/git-auto-commit-action.
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v7
+        with:  # zizmor: ignore[artipacked] git-auto-commit-action requires credentials
+          # See
+          # https://github.com/stefanzweifel/git-auto-commit-action?tab=readme-ov-file#push-to-protected-branches
+          token: ${{ secrets.RELEASE_PAT }}
+          # Fetch all history including tags.
+          # Needed to find the latest tag.
+          #
+          # Also, avoids
+          # https://github.com/stefanzweifel/git-auto-commit-action/issues/99.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          cache-dependency-glob: '**/pyproject.toml'
+
+      - name: Calver calculate version
+        uses: StephaneBour/actions-calver@master
+        id: calver
+        with:
+          date_format: '%Y.%m.%d'
+          release: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # towncrier writes the rendered notes to stdout (informational
+      # chatter goes to stderr), so this is the curated release body for
+      # this version, not github-tag-action's commit-derived changelog.
+      - name: Generate the GitHub release notes
+        env:
+          RELEASE: ${{ steps.calver.outputs.release }}
+        run: uv run --extra=release towncrier build --draft --version "$RELEASE" >
+          release-notes.md
+
+      # Assemble the same fragments into CHANGELOG.rst under a new
+      # ``$RELEASE`` section and delete the consumed fragment files.
+      - name: Update the changelog
+        env:
+          RELEASE: ${{ steps.calver.outputs.release }}
+        run: uv run --extra=release towncrier build --yes --version "$RELEASE"
+
+      - uses: stefanzweifel/git-auto-commit-action@v7
+        id: commit
+        with:
+          commit_message: Bump CHANGELOG
+          file_pattern: CHANGELOG.rst newsfragments
+          # Error if there are no changes.
+          skip_dirty_check: true
+
+      - name: Bump version and push tag
+        id: tag_version
+        uses: mathieudutour/github-tag-action@v6.2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          custom_tag: ${{ steps.calver.outputs.release }}
+          tag_prefix: ''
+          commit_sha: ${{ steps.commit.outputs.commit_hash }}
+
+      - name: Create a GitHub release
+        uses: ncipollo/release-action@v1
+        with:
+          tag: ${{ steps.tag_version.outputs.new_tag }}
+          makeLatest: true
+          name: Release ${{ steps.tag_version.outputs.new_tag }}
+          bodyFile: release-notes.md
+
+      - name: Build a binary wheel and a source tarball
+        env:
+          NEW_TAG: ${{ steps.tag_version.outputs.new_tag }}
+        run: |
+          git fetch --tags
+          git checkout "$NEW_TAG"
+          uv build --sdist --wheel --out-dir dist/
+          uv run --extra=release check-wheel-contents dist/*.whl
+
+      - name: Publish distribution to PyPI
+        # We use PyPI trusted publishing rather than a PyPI API token.
+        # See https://github.com/pypa/gh-action-pypi-publish/tree/release/v1/?tab=readme-ov-file#trusted-publishing.
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true

coderpad_py-2026.9.7/.gitignore

@@ -0,0 +1,112 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# dotenv
+.env
+
+# virtualenv
+.venv/
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+
+# Rope project settings
+.ropeproject
+
+# mypy
+.mypy_cache/
+
+# Ignore Mac DS_Store files
+.DS_Store
+**/.DS_Store
+
+# pyre
+.pyre/
+
+# pytest
+.pytest_cache/
+
+# setuptools_scm
+src/*/_setuptools_scm_version.txt
+
+uv.lock
+
+# Vale styles downloaded by ``vale sync``
+styles/

coderpad_py-2026.9.7/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "overrides": [
+    {
+      "files": ["*.yaml", "*.yml"],
+      "options": {
+        "singleQuote": true,
+        "printWidth": 100
+      }
+    }
+  ]
+}

coderpad_py-2026.9.7/.vale.ini

@@ -0,0 +1,13 @@
+StylesPath = styles
+MinAlertLevel = error
+
+Packages = https://github.com/tbhb/vale-ai-tells/releases/download/v1.29.0/ai-tells.zip
+
+[*.{rst,md}]
+BasedOnStyles = ai-tells
+
+# These rules misclassify established technical, example, or release-note prose
+# in this repository. All other ai-tells rules remain enforced.
+ai-tells.FigurativeLands = NO
+ai-tells.FormalTransitions = NO
+ai-tells.VerbTricolon = NO

coderpad_py-2026.9.7/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+    "recommendations": [
+        "charliermarsh.ruff",
+        "ms-python.python"
+    ]
+}

coderpad_py-2026.9.7/.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+    "[python]": {
+        "editor.codeActionsOnSave": {
+            "source.fixAll": "explicit"
+        },
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnSave": true
+    },
+    "esbonio.sphinx.confDir": "",
+    "python.testing.pytestArgs": [
+        "."
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

coderpad_py-2026.9.7/CHANGELOG.rst

@@ -0,0 +1,159 @@
+Changelog
+=========
+
+.. towncrier release notes start
+
+2026.09.07
+----------
+
+- Removed ``client.quota.get()``. Use ``client.organization.get_quota()``,
+  which it only delegated to.
+
+- Removed ``PadHistory.replay_to_file`` and ``coderpad.screen.save_screen_report``.
+  Callers can write replayed contents or report bytes with ``pathlib.Path``
+  directly.
+
+- Add synchronous and asynchronous HTTPX2 transports while retaining HTTPX as
+  the default client family.
+
+2026.08.23
+----------
+
+- Add ``pads.all()`` to iterate Interview pads across paginated responses.
+
+- Add ``screen.tests.all()`` to iterate Screen tests across paginated responses.
+
+- Expose ``prev_page`` on Interview API ``PaginatedList`` responses.
+
+- Interview API types such as ``Pad``, ``Question``, and ``Language`` are now available from ``coderpad``.
+
+- Exception classes such as ``CoderPadError`` and ``NotFoundError`` are now available from ``coderpad``.
+
+- Documented which ``Question`` and ``Pad`` fields are writable versus read-only in a new "Writable and read-only fields" reference page.
+
+- Validate that ``contents``, ``file_contents``, and ``zip_file`` are mutually exclusive on question create/update.
+
+- Support configurable ``httpx`` timeouts on ``CoderPad`` and ``AsyncCoderPad``.
+
+- Parse JSON API error bodies into optional ``CoderPadError.code`` and ``CoderPadError.message`` attributes.
+
+- Added ``BadGatewayError``, ``ServiceUnavailableError``, and ``GatewayTimeoutError`` for HTTP 502, 503, and 504 responses.
+
+- Defer Screen namespace initialization until first access on CoderPad clients.
+
+- Fail fast with a clear error when Screen methods are called without a ``screen_api_key``.
+
+- Support custom default headers on ``CoderPad`` and ``AsyncCoderPad``.
+
+- Support configuring an ``httpx`` proxy on ``CoderPad`` and ``AsyncCoderPad``.
+
+- Bump PyPI development status classifier from Planning to Beta.
+
+- Fixed the README minimum Python version badge to match ``requires-python`` (3.12).
+
+- Add Screen API usage documentation.
+
+- Document the exception hierarchy in the Sphinx API reference.
+
+- Add ``save_screen_report`` to write Screen report bytes to a file.
+
+- ``SortOrder`` is now a ``StrEnum``, so its values work directly as query strings.
+
+- ``Language`` is now a ``StrEnum``, so its values work directly in API requests.
+
+- Add ``scripts/sync_openapi.py`` to normalize Postman OpenAPI exports
+  into the bundled ``openapi.json``.
+
+- Load API keys from ``CODERPAD_API_KEY`` and ``CODERPAD_SCREEN_API_KEY`` via ``from_env()``.
+
+- ``PaginatedList`` and ``ScreenTestsPage`` now include concise ``__repr__`` output for debugging.
+
+- Add ``tests.report_json`` (sync and async) returning a typed
+  ``ScreenReport`` from the Screen test session payload.
+
+- Document the public API stability policy.
+
+- Add ``PadHistory.replay_to_file`` to write replayed editor contents to disk.
+
+- Support configuring ``httpx`` connection pool limits on CoderPad clients.
+
+- Document the maintainer workflow for empirically observed API variants
+  and link it to towncrier news fragments and the API drift issue template.
+
+- Add ``client.quota.get()`` as an alias for ``client.organization.get_quota()``.
+
+- Validate that Screen invitations include ``candidate_email`` and ``candidate_name`` before send.
+
+2026.08.16
+----------
+
+- Add typed synchronous and asynchronous CoderPad Screen clients covering
+  campaigns, invitations, tests, reports, pagination, regions, and webhooks.
+
+- Add synchronous and asynchronous organization user listing, with optional
+  server-side email filtering.
+
+- Validate client form requests against request-body definitions in the bundled
+  OpenAPI specification during tests.
+
+- API resource types are now strict, frozen Pydantic v2 models.  Responses are
+  validated with ``model_validate`` and request models support
+  ``model_dump``.  Beartype continues to provide runtime type checking
+  alongside Pydantic.
+
+2026.07.24
+----------
+
+- Expose the optional ``ai_assist_custom_system_prompt`` field on question
+  responses so custom AI Assist prompts can be read and synchronized.
+
+2026.07.22.1
+------------
+
+- Add ``ai_assist_custom_system_prompt`` to ``questions.update`` so AI Assist
+  system prompts can be synchronized for existing questions.
+
+2026.07.22
+----------
+
+- Add synchronous and asynchronous support for retrieving and replaying per-file pad editor history.
+
+- Support empirically observed API response variants for binary files, organization metadata, pad interviewer notifications, and question custom databases.
+
+- Add an ``ai_assist_custom_system_prompt`` parameter to ``questions.create``
+  to configure AI Assist's system prompt for a question.
+
+2026.06.29
+----------
+
+- Add a ``candidate_instructions`` parameter to ``questions.create`` and ``questions.update`` so progressively-revealed candidate instruction blocks can be authored via the API.
+
+2026.05.04
+----------
+
+
+2026.04.01
+----------
+
+
+2026.03.31.2
+------------
+
+
+- Removed support for Python 3.11.
+- Changed default ``base_url`` from ``https://api.interview.coderpad.io`` to ``https://app.coderpad.io``.
+
+2026.03.31.1
+------------
+
+
+2026.03.31
+----------
+
+
+2026.03.29.1
+------------
+
+
+2026.03.29
+----------

coderpad_py-2026.9.7/LICENSE

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