poli-page 0.9.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. poli_page-0.9.0/.github/dependabot.yml +33 -0
  2. poli_page-0.9.0/.github/workflows/ci.yml +81 -0
  3. poli_page-0.9.0/.github/workflows/codeql.yml +38 -0
  4. poli_page-0.9.0/.github/workflows/docs.yml +62 -0
  5. poli_page-0.9.0/.github/workflows/integration.yml +53 -0
  6. poli_page-0.9.0/.github/workflows/publish.yml +147 -0
  7. poli_page-0.9.0/.gitignore +75 -0
  8. poli_page-0.9.0/CHANGELOG.md +44 -0
  9. poli_page-0.9.0/CONTRIBUTING.md +145 -0
  10. poli_page-0.9.0/LICENSE +21 -0
  11. poli_page-0.9.0/MIGRATION.md +48 -0
  12. poli_page-0.9.0/PKG-INFO +454 -0
  13. poli_page-0.9.0/README.md +416 -0
  14. poli_page-0.9.0/SECURITY.md +12 -0
  15. poli_page-0.9.0/demo/README.md +54 -0
  16. poli_page-0.9.0/demo/_shared.py +172 -0
  17. poli_page-0.9.0/demo/async_demo.py +195 -0
  18. poli_page-0.9.0/demo/sync_demo.py +194 -0
  19. poli_page-0.9.0/pyproject.toml +126 -0
  20. poli_page-0.9.0/scripts/extract-api/main.py +789 -0
  21. poli_page-0.9.0/scripts/release.sh +184 -0
  22. poli_page-0.9.0/src/poli_page/__init__.py +84 -0
  23. poli_page-0.9.0/src/poli_page/_async_client.py +413 -0
  24. poli_page-0.9.0/src/poli_page/_client.py +419 -0
  25. poli_page-0.9.0/src/poli_page/_constants.py +50 -0
  26. poli_page-0.9.0/src/poli_page/_documents.py +161 -0
  27. poli_page-0.9.0/src/poli_page/_errors.py +183 -0
  28. poli_page-0.9.0/src/poli_page/_render.py +248 -0
  29. poli_page-0.9.0/src/poli_page/_transport.py +203 -0
  30. poli_page-0.9.0/src/poli_page/_version.py +1 -0
  31. poli_page-0.9.0/src/poli_page/error_codes.py +50 -0
  32. poli_page-0.9.0/src/poli_page/fs.py +61 -0
  33. poli_page-0.9.0/src/poli_page/py.typed +0 -0
  34. poli_page-0.9.0/src/poli_page/types.py +251 -0
  35. poli_page-0.9.0/tests/integration/__init__.py +0 -0
  36. poli_page-0.9.0/tests/integration/conftest.py +55 -0
  37. poli_page-0.9.0/tests/integration/test_async.py +118 -0
  38. poli_page-0.9.0/tests/integration/test_documents.py +70 -0
  39. poli_page-0.9.0/tests/integration/test_preview.py +44 -0
  40. poli_page-0.9.0/tests/integration/test_render.py +102 -0
  41. poli_page-0.9.0/tests/test_smoke.py +6 -0
  42. poli_page-0.9.0/tests/unit/test_async_client.py +471 -0
  43. poli_page-0.9.0/tests/unit/test_async_documents.py +171 -0
  44. poli_page-0.9.0/tests/unit/test_async_render.py +209 -0
  45. poli_page-0.9.0/tests/unit/test_client.py +865 -0
  46. poli_page-0.9.0/tests/unit/test_documents.py +318 -0
  47. poli_page-0.9.0/tests/unit/test_errors.py +238 -0
  48. poli_page-0.9.0/tests/unit/test_fs.py +169 -0
  49. poli_page-0.9.0/tests/unit/test_render.py +340 -0
  50. poli_page-0.9.0/tests/unit/test_transport.py +311 -0
@@ -0,0 +1,33 @@
1
+ version: 2
2
+
3
+ updates:
4
+ - package-ecosystem: pip
5
+ directory: "/"
6
+ schedule:
7
+ interval: weekly
8
+ day: monday
9
+ time: "06:00"
10
+ timezone: "Etc/UTC"
11
+ open-pull-requests-limit: 5
12
+ groups:
13
+ pip-deps:
14
+ applies-to: version-updates
15
+ patterns:
16
+ - "*"
17
+ pip-security:
18
+ applies-to: security-updates
19
+ patterns:
20
+ - "*"
21
+
22
+ - package-ecosystem: github-actions
23
+ directory: "/"
24
+ schedule:
25
+ interval: weekly
26
+ day: monday
27
+ time: "06:00"
28
+ timezone: "Etc/UTC"
29
+ open-pull-requests-limit: 5
30
+ groups:
31
+ actions:
32
+ patterns:
33
+ - "*"
@@ -0,0 +1,81 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ pull_request:
6
+ branches: [main]
7
+
8
+ permissions:
9
+ contents: read
10
+ id-token: write # Why: codecov-action v5 uses OIDC for tokenless uploads on public repos.
11
+
12
+ jobs:
13
+ test:
14
+ runs-on: ${{ matrix.os }}
15
+ strategy:
16
+ fail-fast: false
17
+ matrix:
18
+ os: [ubuntu-latest, macos-latest, windows-latest]
19
+ python-version: ['3.11', '3.12', '3.13']
20
+ defaults:
21
+ run:
22
+ # Bash on every runner — keeps the auto-skip conditionals portable on Windows.
23
+ shell: bash
24
+ steps:
25
+ - uses: actions/checkout@v6
26
+
27
+ - uses: actions/setup-python@v6
28
+ with:
29
+ python-version: ${{ matrix.python-version }}
30
+ cache: pip
31
+ cache-dependency-path: pyproject.toml
32
+
33
+ - name: Install
34
+ run: |
35
+ python -m pip install --upgrade pip
36
+ if [ -f pyproject.toml ]; then
37
+ pip install -e ".[dev]" 2>/dev/null || pip install -e . || echo "pyproject.toml exists but install failed — check it"
38
+ elif [ -f requirements-dev.txt ]; then
39
+ pip install -r requirements-dev.txt
40
+ elif [ -f requirements.txt ]; then
41
+ pip install -r requirements.txt
42
+ else
43
+ echo "No manifest yet — skipping install"
44
+ fi
45
+
46
+ - name: Lint
47
+ run: |
48
+ if python -m ruff --version >/dev/null 2>&1; then
49
+ python -m ruff check .
50
+ python -m ruff format --check .
51
+ else
52
+ echo "ruff not installed — skipping lint"
53
+ fi
54
+
55
+ - name: Test
56
+ run: |
57
+ if python -m pytest --version >/dev/null 2>&1; then
58
+ if [ -d tests ] && find tests \( -name "test_*.py" -o -name "*_test.py" \) | grep -q .; then
59
+ if python -c "import pytest_cov" 2>/dev/null; then
60
+ python -m pytest -v --cov=poli_page --cov-report=xml --cov-report=term
61
+ else
62
+ python -m pytest -v
63
+ fi
64
+ else
65
+ echo "pytest available but no tests yet — skipping"
66
+ fi
67
+ else
68
+ echo "pytest not installed — skipping test"
69
+ fi
70
+
71
+ - name: Upload coverage to Codecov
72
+ # Why: only upload from one matrix slot to avoid duplicate reports;
73
+ # skip silently when coverage.xml wasn't produced (e.g. pytest-cov absent).
74
+ # use_oidc is required: Codecov rejects tokenless uploads on the default
75
+ # (protected) branch, and we've granted id-token: write at the job level.
76
+ if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' && hashFiles('coverage.xml') != ''
77
+ uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5
78
+ with:
79
+ files: coverage.xml
80
+ fail_ci_if_error: false
81
+ use_oidc: true
@@ -0,0 +1,38 @@
1
+ name: CodeQL
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+ schedule:
9
+ # Weekly scan against main so we still get findings on a quiet repo.
10
+ - cron: "23 7 * * 1"
11
+
12
+ permissions:
13
+ actions: read
14
+ contents: read
15
+ security-events: write
16
+
17
+ jobs:
18
+ analyze:
19
+ name: Analyze (${{ matrix.language }})
20
+ runs-on: ubuntu-latest
21
+ strategy:
22
+ fail-fast: false
23
+ matrix:
24
+ language: [python]
25
+
26
+ steps:
27
+ - uses: actions/checkout@v6
28
+
29
+ - name: Initialize CodeQL
30
+ uses: github/codeql-action/init@v4
31
+ with:
32
+ languages: ${{ matrix.language }}
33
+ queries: security-and-quality
34
+
35
+ - name: Perform analysis
36
+ uses: github/codeql-action/analyze@v4
37
+ with:
38
+ category: "/language:${{ matrix.language }}"
@@ -0,0 +1,62 @@
1
+ name: Docs
2
+ on:
3
+ push:
4
+ branches: [main]
5
+ paths:
6
+ - 'src/**'
7
+ - 'examples/**'
8
+ - 'docs/**'
9
+ - 'scripts/extract-api/**'
10
+ - 'pyproject.toml'
11
+ - 'CHANGELOG.md'
12
+ - 'MIGRATION.md'
13
+ - 'LICENSE'
14
+ - '.github/workflows/docs.yml'
15
+ release: { types: [published] }
16
+ workflow_dispatch:
17
+
18
+ permissions:
19
+ contents: read
20
+ pages: write
21
+ id-token: write
22
+
23
+ concurrency:
24
+ group: pages
25
+ cancel-in-progress: false
26
+
27
+ jobs:
28
+ build:
29
+ runs-on: ubuntu-latest
30
+ steps:
31
+ - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
32
+ - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
33
+ with:
34
+ python-version: '3.12'
35
+ - name: Install SDK (extractor reads src/poli_page via ast — no install needed)
36
+ run: python -m pip install --upgrade pip
37
+ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
38
+ with:
39
+ node-version: '22'
40
+ cache: 'npm'
41
+ cache-dependency-path: docs/package-lock.json
42
+ - name: Install docs deps
43
+ working-directory: docs
44
+ run: npm ci || npm install --no-audit --no-fund
45
+ - name: Build docs site (extract + astro build)
46
+ working-directory: docs
47
+ run: npm run build
48
+ - name: Verify index exists
49
+ run: test -s docs/dist/index.html
50
+ - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
51
+ with:
52
+ path: docs/dist
53
+
54
+ deploy:
55
+ needs: build
56
+ runs-on: ubuntu-latest
57
+ environment:
58
+ name: github-pages
59
+ url: ${{ steps.deployment.outputs.page_url }}
60
+ steps:
61
+ - id: deployment
62
+ uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
@@ -0,0 +1,53 @@
1
+ name: Integration
2
+
3
+ # Live-API integration tests. Gated on the repository secret POLI_PAGE_API_KEY
4
+ # (pp_test_*); jobs no-op when unset. Runs on push to main + nightly so PRs
5
+ # stay snappy.
6
+
7
+ on:
8
+ push:
9
+ branches: [main]
10
+ schedule:
11
+ # Daily at 06:00 UTC.
12
+ - cron: "0 6 * * *"
13
+ workflow_dispatch:
14
+
15
+ permissions:
16
+ contents: read
17
+
18
+ jobs:
19
+ integration:
20
+ runs-on: ubuntu-latest
21
+ if: ${{ vars.RUN_INTEGRATION != 'false' }}
22
+ strategy:
23
+ fail-fast: false
24
+ matrix:
25
+ python-version: ["3.11", "3.12", "3.13"]
26
+ env:
27
+ POLI_PAGE_API_KEY: ${{ secrets.POLI_PAGE_API_KEY }}
28
+ POLI_PAGE_TEST_BASE_URL: ${{ secrets.POLI_PAGE_TEST_BASE_URL }}
29
+ POLI_PAGE_TEST_PROJECT: ${{ vars.POLI_PAGE_TEST_PROJECT || 'getting-started' }}
30
+ POLI_PAGE_TEST_TEMPLATE: ${{ vars.POLI_PAGE_TEST_TEMPLATE || 'welcome' }}
31
+ POLI_PAGE_TEST_VERSION: ${{ vars.POLI_PAGE_TEST_VERSION || '1.0.0' }}
32
+ steps:
33
+ - uses: actions/checkout@v6
34
+
35
+ - name: Setup Python ${{ matrix.python-version }}
36
+ uses: actions/setup-python@v6
37
+ with:
38
+ python-version: ${{ matrix.python-version }}
39
+
40
+ - name: Install
41
+ run: |
42
+ python -m pip install --upgrade pip
43
+ pip install --only-binary=:all: -e ".[dev]"
44
+
45
+ - name: Skip when API key is missing
46
+ if: env.POLI_PAGE_API_KEY == ''
47
+ run: |
48
+ echo "POLI_PAGE_API_KEY secret is not set — integration suite cannot run." >&2
49
+ echo "Set the repository secret to enable this workflow." >&2
50
+
51
+ - name: Integration tests
52
+ if: env.POLI_PAGE_API_KEY != ''
53
+ run: python -m pytest tests/integration/ -m integration -v
@@ -0,0 +1,147 @@
1
+ name: Publish to PyPI
2
+
3
+ # Tag-driven release. Pushing a `vX.Y.Z` tag publishes that version to PyPI
4
+ # via PEP 740 Trusted Publishing (OIDC; no long-lived token) and cuts the
5
+ # matching GitHub Release. A manual `workflow_dispatch` run publishes to
6
+ # TestPyPI only — for rehearsing the pipeline without burning a real
7
+ # version on pypi.org (PyPI uploads are immutable).
8
+ #
9
+ # One-time setup before this workflow can publish:
10
+ # 1. Register the PyPI Trusted Publisher for this repo:
11
+ # project: poli-page
12
+ # owner: poli-page
13
+ # repo: sdk-python
14
+ # workflow: publish.yml
15
+ # environment: pypi-publish
16
+ # 2. For rehearsals, register the same pending publisher on test.pypi.org.
17
+ # 3. Configure the `pypi-publish` repository environment with required
18
+ # reviewers (so the run pauses for human approval before upload).
19
+ #
20
+ # Per release:
21
+ # 1. Bump src/poli_page/_version.py, move [Unreleased] in CHANGELOG.md,
22
+ # commit (`chore(release): X.Y.Z`) and push to main; wait for CI green.
23
+ # 2. (Optional) Rehearse: run this workflow manually -> TestPyPI.
24
+ # 3. Tag and push: git tag vX.Y.Z && git push origin vX.Y.Z
25
+ # The tag version must match _version.py exactly, or the run fails.
26
+
27
+ on:
28
+ push:
29
+ tags:
30
+ - "v*"
31
+ workflow_dispatch:
32
+ inputs:
33
+ target:
34
+ description: "Manual runs publish to TestPyPI only (production goes through a vX.Y.Z tag push)."
35
+ required: true
36
+ default: "testpypi"
37
+ type: choice
38
+ options:
39
+ - testpypi
40
+
41
+ permissions:
42
+ contents: write # to create the GitHub Release
43
+ id-token: write # required for PyPI Trusted Publishing (OIDC)
44
+
45
+ defaults:
46
+ run:
47
+ shell: bash
48
+
49
+ jobs:
50
+ publish:
51
+ runs-on: ubuntu-latest
52
+ environment: pypi-publish
53
+ steps:
54
+ - uses: actions/checkout@v6
55
+
56
+ - name: Setup Python 3.12
57
+ uses: actions/setup-python@v6
58
+ with:
59
+ python-version: "3.12"
60
+
61
+ - name: Resolve version and target
62
+ id: rel
63
+ run: |
64
+ set -euo pipefail
65
+ PKG_VERSION="$(python -c 'import re; print(re.search(r"__version__\s*=\s*\"([^\"]+)\"", open("src/poli_page/_version.py").read()).group(1))')"
66
+ if [[ "${{ github.event_name }}" == "push" ]]; then
67
+ # Tag push -> production release to PyPI. The tag version must
68
+ # match _version.py exactly (PEP 440 normalized form, no hyphen).
69
+ TAG_VERSION="${GITHUB_REF_NAME#v}"
70
+ if [[ "$TAG_VERSION" != "$PKG_VERSION" ]]; then
71
+ echo "Refusing to publish: tag ${GITHUB_REF_NAME} does not match _version.py ($PKG_VERSION)." >&2
72
+ exit 1
73
+ fi
74
+ echo "target=pypi" >> "$GITHUB_OUTPUT"
75
+ else
76
+ echo "target=testpypi" >> "$GITHUB_OUTPUT"
77
+ fi
78
+ echo "version=$PKG_VERSION" >> "$GITHUB_OUTPUT"
79
+ echo "Releasing poli-page@$PKG_VERSION via ${{ github.event_name }}."
80
+
81
+ - name: Install dependencies
82
+ run: |
83
+ python -m pip install --upgrade pip
84
+ pip install --only-binary=:all: -e ".[dev]"
85
+
86
+ - name: Lint
87
+ run: python -m ruff check .
88
+
89
+ - name: Format check
90
+ run: python -m ruff format --check .
91
+
92
+ - name: Typecheck (pyright)
93
+ run: python -m pyright
94
+
95
+ - name: Unit tests
96
+ run: python -m pytest tests/unit/ tests/test_smoke.py -q
97
+
98
+ - name: Build wheel + sdist
99
+ run: python -m build
100
+
101
+ - name: Inspect with twine check
102
+ run: python -m twine check dist/*
103
+
104
+ - name: Publish to PyPI via Trusted Publishing
105
+ if: steps.rel.outputs.target == 'pypi'
106
+ uses: pypa/gh-action-pypi-publish@release/v1
107
+ with:
108
+ attestations: true
109
+
110
+ - name: Publish to TestPyPI via Trusted Publishing
111
+ if: steps.rel.outputs.target == 'testpypi'
112
+ uses: pypa/gh-action-pypi-publish@release/v1
113
+ with:
114
+ repository-url: https://test.pypi.org/legacy/
115
+ attestations: true
116
+
117
+ - name: Extract CHANGELOG section for this version
118
+ if: steps.rel.outputs.target == 'pypi'
119
+ id: changelog
120
+ run: |
121
+ set -euo pipefail
122
+ # Slice between `## [X.Y.Z]` and the next `## [` heading. Falls back
123
+ # to a stub note if the version isn't documented yet — so the
124
+ # release never blocks on copy.
125
+ NOTES_FILE="$RUNNER_TEMP/release-notes.md"
126
+ awk -v ver="${{ steps.rel.outputs.version }}" '
127
+ $0 ~ "^## \\[" ver "\\]" { capture = 1; next }
128
+ capture && /^## \[/ { exit }
129
+ capture { print }
130
+ ' CHANGELOG.md > "$NOTES_FILE"
131
+ if [ ! -s "$NOTES_FILE" ]; then
132
+ echo "_See [CHANGELOG.md](CHANGELOG.md) for details._" > "$NOTES_FILE"
133
+ fi
134
+ echo "notes_file=$NOTES_FILE" >> "$GITHUB_OUTPUT"
135
+
136
+ - name: Create GitHub Release
137
+ if: steps.rel.outputs.target == 'pypi'
138
+ env:
139
+ GH_TOKEN: ${{ github.token }}
140
+ run: |
141
+ set -euo pipefail
142
+ # The tag already exists (it triggered this run); attach the built
143
+ # artifacts and the carved release notes to it.
144
+ gh release create "v${{ steps.rel.outputs.version }}" \
145
+ --title "v${{ steps.rel.outputs.version }}" \
146
+ --notes-file "${{ steps.changelog.outputs.notes_file }}" \
147
+ dist/*
@@ -0,0 +1,75 @@
1
+ # OS
2
+ .DS_Store
3
+ Thumbs.db
4
+
5
+ # Editors
6
+ .vscode/
7
+ .idea/
8
+ *.swp
9
+
10
+ # Node
11
+ node_modules/
12
+ dist/
13
+ build/
14
+ .next/
15
+ *.log
16
+ .npm/
17
+
18
+ # Python
19
+ __pycache__/
20
+ *.py[cod]
21
+ *.egg-info/
22
+ .venv/
23
+ venv/
24
+ .ruff_cache/
25
+ .pytest_cache/
26
+ .tox/
27
+ .coverage
28
+ .coverage.*
29
+ coverage.xml
30
+ htmlcov/
31
+
32
+ # PHP
33
+ vendor/
34
+ composer.lock
35
+ .phpunit.cache/
36
+
37
+ # Go
38
+ bin/
39
+ *.test
40
+ *.out
41
+
42
+ # Env
43
+ .env
44
+ .env.local
45
+
46
+ # Demo artifacts
47
+ demo/output-sync/
48
+ demo/output-async/
49
+
50
+ # Local agent config
51
+ .claude/
52
+
53
+ # Distribution artifacts
54
+ dist/
55
+ build/
56
+ *.egg-info/
57
+
58
+ # Local-only handoff docs (live in sdk-node or the platform repo)
59
+ sdk-python-plan.md
60
+ sdk-engineering-guide.md
61
+ sdk-roadmap.md
62
+
63
+ # Astro / Starlight docs site
64
+ docs/node_modules/
65
+ docs/dist/
66
+ docs/.astro/
67
+ docs/src/content/docs/reference/
68
+
69
+ # Extractor cache
70
+ scripts/extract-api/.cache/
71
+ CLAUDE.md
72
+ docs/plan/
73
+ docs/spec/
74
+ sdk-*-plan.md
75
+ sdk-*-specifications.md
@@ -0,0 +1,44 @@
1
+ # Changelog
2
+
3
+ All notable changes to `poli-page` (Python SDK) are documented here.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+ Breaking changes between major versions are summarized in [MIGRATION.md](MIGRATION.md).
8
+
9
+ ## [Unreleased]
10
+
11
+ ## [0.9.0] - 2026-06-19
12
+
13
+ First public release (pre-1.0). Behavior parity with `@poli-page/sdk@1.0.0` (Node).
14
+
15
+ ### Added
16
+
17
+ - **`PoliPage`** synchronous client + **`AsyncPoliPage`** asyncio-native client, parallel surfaces backed by `httpx.Client` / `httpx.AsyncClient`. Use either; the SDK does not auto-detect.
18
+ - **`render.*` namespace**: `pdf(input) → bytes`, `pdf_stream(input)` (sync / async context manager yielding chunks), `preview(input) → PreviewResult`, `document(input) → DocumentDescriptor`. `render.pdf` and `render.pdf_stream` make two HTTP calls (`POST /v1/render` + `GET presigned_pdf_url`) — the auto-download is an SDK convenience.
19
+ - **`documents.*` namespace**: `get(id)`, `preview(id)`, `thumbnails(id, options)`, `delete(id)`. All `{id}` segments URL-encoded.
20
+ - **`DocumentDescriptor.download_pdf()`** (sync) / **`AsyncDocumentDescriptor.download_pdf()`** (async) — fetch PDF bytes from the descriptor's `presigned_pdf_url`.
21
+ - **Project-mode enforcement**: `render.pdf` / `pdf_stream` / `document` reject inline-shaped input with `PoliPageError(code='PROJECT_REQUIRED_FOR_DOCUMENT')` before the HTTP call. `render.preview` accepts either mode. Type-level enforcement via `ProjectModeInput` / `InlineModeInput` TypedDicts.
22
+ - **`metadata`** pass-through on all render inputs; echoed verbatim on `DocumentDescriptor.metadata`.
23
+ - **`poli_page.fs.render_to_file`** + **`async_render_to_file`** — stream a PDF directly to disk; creates parent dirs, overwrites existing.
24
+ - **Auto-generated `Idempotency-Key`** (UUID4) on every POST; per-call override via `idempotency_key` in the input dict.
25
+ - **Retry policy**: 5xx, 429, network errors, timeouts. Exponential backoff with `[0.5, 1.5)` jitter; honors `Retry-After` and `Retry-After-Ms` (sub-second precision wins over seconds), capped at 30 s.
26
+ - **Typed error hierarchy** (`PoliPageError` base; `APIConnectionError` / `APITimeoutError` / `APIStatusError` with per-status subclasses for 400/401/403/404/409/410/422/429/5xx). Predicate helpers `is_auth_error` / `is_rate_limit_error` / `is_validation_error` / `is_network_error` / `is_retryable` kept for cross-language parity.
27
+ - **`error_codes`** module with named constants for every known API code (`MISSING_API_KEY`, `PAYMENT_REQUIRED`, `QUOTA_EXCEEDED`, …) and reserved SDK codes (`INVALID_OPTIONS`, `NETWORK_ERROR`, `TIMEOUT`, `ABORTED`, `UNKNOWN_ERROR`, `DOWNLOAD_FAILED`).
28
+ - **Observability**: silent-by-default `logging.getLogger('poli_page')` logger driven by `POLI_PAGE_LOG=debug|info|warning|error`. SDK-level hooks `on_retry` / `on_error` are sync callables; their exceptions never break the request. For request/response wiretapping, pass your own `httpx.Client` with `event_hooks={...}`.
29
+ - **Env-var fallbacks** mirroring `anthropic-sdk-python` / `openai-python`: `POLI_PAGE_API_KEY` (constructor falls back here when `api_key=` is omitted); `POLI_PAGE_BASE_URL` (default `https://api.poli.page`).
30
+ - **Context-manager lifecycle**: `with PoliPage(...) as client:` (sync) / `async with AsyncPoliPage(...) as client:` (async). Sockets close deterministically.
31
+ - **Injected `http_client`**: pass a pre-configured `httpx.Client` / `httpx.AsyncClient` for proxies, custom TLS, shared connection pools, or test transports. Caller-owned clients are not closed on `close()` / `aclose()`.
32
+ - **`py.typed`** marker — pyright `strict` and mypy `--strict` on `src/` are both green.
33
+ - **PyPI Trusted Publishing** workflow (tag-driven) for signed-attestation releases; pushing a `vX.Y.Z` tag publishes to PyPI, a manual run rehearses on TestPyPI. `scripts/release.sh` remains a local fallback.
34
+ - **Runnable demos** at `demo/sync_demo.py` and `demo/async_demo.py` — walk every public method end-to-end against the live API; outputs are byte-equivalent across sync / async.
35
+
36
+ ### Contract
37
+
38
+ - **Wire format**: snake_case in Python, camelCase on the wire. The SDK translates at top level only — user-supplied `data` and `metadata` keys reach the wire and back verbatim.
39
+ - **Spec parity**: same retry policy, error codes, predicates, project-mode constraint, primitive-only `RenderMetadata`, thumbnails wire wrap/unwrap, and `documents.preview` text/html + `X-Document-Page-Count` parsing as `@poli-page/sdk@1.0.0`.
40
+
41
+ ### Runtime requirements
42
+
43
+ - Python 3.11 or later.
44
+ - `httpx>=0.25,<1.0` — the only runtime dependency. No `pydantic`, no `typing-extensions`, no `requests`.
@@ -0,0 +1,145 @@
1
+ # Contributing to `poli-page`
2
+
3
+ Thanks for your interest. A few short rules:
4
+
5
+ ## Working method
6
+
7
+ We use **TDD**: write a failing test first, then the minimum code to pass.
8
+ See the platform `agent-guide.md` for the full methodology.
9
+
10
+ ## Commit messages
11
+
12
+ [Conventional Commits](https://www.conventionalcommits.org/):
13
+ `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
14
+
15
+ ## Local development
16
+
17
+ ```bash
18
+ python -m venv .venv
19
+ source .venv/bin/activate
20
+ pip install -e ".[dev]"
21
+
22
+ pytest # unit tests
23
+ ruff check . && ruff format --check . # lint + format
24
+ pyright # strict on src/, basic on tests/
25
+ mypy src/ # secondary type-checker (not a CI gate; informational)
26
+ python -m build # build wheel + sdist into dist/
27
+ ```
28
+
29
+ The `dev` extra installs `pytest`, `pytest-asyncio`, `respx`, `ruff`,
30
+ `pyright`, `mypy`, and `build`. No other dev tooling is required.
31
+
32
+ ## API reference site
33
+
34
+ The reference at https://docs.poli.page/reference/sdk/python/ is built
35
+ from docstrings by [`pdoc`](https://pdoc.dev/) and deployed via
36
+ `.github/workflows/docs.yml` on every push to `main` and every published
37
+ release. There are no hand-written pages — every section in the site
38
+ comes from a docstring in `src/poli_page/`. To preview locally:
39
+
40
+ ```bash
41
+ python -m pdoc poli_page --output-directory docs-site
42
+ open docs-site/index.html
43
+ ```
44
+
45
+ If your change touches the public API, eyeball the generated page for
46
+ the modified module before merging.
47
+
48
+ ## Lockfile (`uv.lock`)
49
+
50
+ The repo ships a `uv.lock` for reproducible dev environments. CI does not
51
+ yet consume it (see `.github/workflows/ci.yml`), but contributors who want
52
+ the exact same dependency set can use [`uv`](https://docs.astral.sh/uv/):
53
+
54
+ ```bash
55
+ uv sync --all-extras # creates .venv from uv.lock
56
+ uv run pytest # runs tests against the locked set
57
+ ```
58
+
59
+ Regenerate after editing `pyproject.toml` dependencies:
60
+
61
+ ```bash
62
+ uv lock # rewrite uv.lock to match pyproject.toml
63
+ ```
64
+
65
+ Commit the resulting `uv.lock` change in the same PR as the dependency edit.
66
+
67
+ ## Integration tests
68
+
69
+ Integration tests hit the live API. They're gated on `POLI_PAGE_API_KEY`
70
+ and skipped when the env var is unset:
71
+
72
+ ```bash
73
+ export POLI_PAGE_API_KEY=pp_test_...
74
+ pytest tests/integration/ -m integration
75
+ ```
76
+
77
+ The full set of integration tests round-trips every public method against
78
+ the auto-provisioned `getting-started/welcome/1.0.0` template.
79
+
80
+ ## Releasing
81
+
82
+ Releases are **manual**. There is no CI workflow that auto-publishes — by
83
+ design. The only supported publishing path is `scripts/release.sh`.
84
+
85
+ 1. Bump version in `src/poli_page/_version.py` (`__version__ = "X.Y.Z"`).
86
+ 2. Move `[Unreleased]` to `[X.Y.Z] - YYYY-MM-DD` in `CHANGELOG.md`.
87
+ 3. Commit `chore(release): X.Y.Z`.
88
+ 4. From a clean main branch, run:
89
+ ```bash
90
+ ./scripts/release.sh # full release to PyPI
91
+ ./scripts/release.sh --dry-run # everything except the actual publish
92
+ ./scripts/release.sh --testpypi # publish to TestPyPI instead
93
+ ```
94
+ The script runs pre-flight checks (clean tree, on main, tag doesn't
95
+ exist), lint / typecheck / unit tests, builds the wheel + sdist,
96
+ inspects with `twine check`, prints contents + size, and asks you to
97
+ confirm before publishing. On success, it creates a local `vX.Y.Z` tag.
98
+ 5. Push the tag manually when you're ready: `git push origin vX.Y.Z`.
99
+
100
+ You must have a PyPI token in `~/.pypirc` (or be using `twine`'s OS-keychain
101
+ support). The script does not touch CI secrets — it's a local-machine
102
+ release.
103
+
104
+ ### Stable vs. prerelease channels
105
+
106
+ PyPI natively supports prereleases — `pip install` ignores them unless
107
+ `--pre` is passed. Suffix scheme (PEP 440): `1.2.3rc1`, `2.0.0b0`,
108
+ `1.3.0a2`.
109
+
110
+ #### Cutting a prerelease
111
+
112
+ 1. Bump `__version__` in `src/poli_page/_version.py` to e.g. `2.0.0rc1`.
113
+ 2. Move `[Unreleased]` entries under `[2.0.0rc1] - YYYY-MM-DD` in
114
+ `CHANGELOG.md`.
115
+ 3. Commit, then run `./scripts/release.sh`. PyPI auto-detects the suffix
116
+ and ships it to the prerelease channel; stable installs are
117
+ unaffected.
118
+ 4. Tag the commit locally and push: `git tag v2.0.0rc1 && git push origin v2.0.0rc1`.
119
+
120
+ Users opt in:
121
+
122
+ ```bash
123
+ pip install --pre poli-page # latest prerelease
124
+ pip install poli-page==2.0.0rc1 # specific prerelease
125
+ ```
126
+
127
+ #### Promoting a prerelease to stable
128
+
129
+ When the prerelease is ready, cut a stable release at the same semver
130
+ minus the suffix:
131
+
132
+ 1. Bump `__version__` to `2.0.0` (drop the suffix).
133
+ 2. Move the prerelease entries in `CHANGELOG.md` under `[2.0.0] - YYYY-MM-DD`.
134
+ 3. Run `./scripts/release.sh`.
135
+
136
+ Stable and prerelease channels must never point at the same version —
137
+ once a prerelease is promoted, the next prerelease starts a new pre-suffix
138
+ sequence (e.g. `2.1.0b0`).
139
+
140
+ ## PyPI Trusted Publishing
141
+
142
+ The `workflow_dispatch`-gated `.github/workflows/publish.yml` provides a
143
+ signed-attestation path for releases that want PEP 740 attestations
144
+ attached automatically. The local `scripts/release.sh` remains the
145
+ primary, recommended path; the workflow is the optional augment.