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.
- poli_page-0.9.0/.github/dependabot.yml +33 -0
- poli_page-0.9.0/.github/workflows/ci.yml +81 -0
- poli_page-0.9.0/.github/workflows/codeql.yml +38 -0
- poli_page-0.9.0/.github/workflows/docs.yml +62 -0
- poli_page-0.9.0/.github/workflows/integration.yml +53 -0
- poli_page-0.9.0/.github/workflows/publish.yml +147 -0
- poli_page-0.9.0/.gitignore +75 -0
- poli_page-0.9.0/CHANGELOG.md +44 -0
- poli_page-0.9.0/CONTRIBUTING.md +145 -0
- poli_page-0.9.0/LICENSE +21 -0
- poli_page-0.9.0/MIGRATION.md +48 -0
- poli_page-0.9.0/PKG-INFO +454 -0
- poli_page-0.9.0/README.md +416 -0
- poli_page-0.9.0/SECURITY.md +12 -0
- poli_page-0.9.0/demo/README.md +54 -0
- poli_page-0.9.0/demo/_shared.py +172 -0
- poli_page-0.9.0/demo/async_demo.py +195 -0
- poli_page-0.9.0/demo/sync_demo.py +194 -0
- poli_page-0.9.0/pyproject.toml +126 -0
- poli_page-0.9.0/scripts/extract-api/main.py +789 -0
- poli_page-0.9.0/scripts/release.sh +184 -0
- poli_page-0.9.0/src/poli_page/__init__.py +84 -0
- poli_page-0.9.0/src/poli_page/_async_client.py +413 -0
- poli_page-0.9.0/src/poli_page/_client.py +419 -0
- poli_page-0.9.0/src/poli_page/_constants.py +50 -0
- poli_page-0.9.0/src/poli_page/_documents.py +161 -0
- poli_page-0.9.0/src/poli_page/_errors.py +183 -0
- poli_page-0.9.0/src/poli_page/_render.py +248 -0
- poli_page-0.9.0/src/poli_page/_transport.py +203 -0
- poli_page-0.9.0/src/poli_page/_version.py +1 -0
- poli_page-0.9.0/src/poli_page/error_codes.py +50 -0
- poli_page-0.9.0/src/poli_page/fs.py +61 -0
- poli_page-0.9.0/src/poli_page/py.typed +0 -0
- poli_page-0.9.0/src/poli_page/types.py +251 -0
- poli_page-0.9.0/tests/integration/__init__.py +0 -0
- poli_page-0.9.0/tests/integration/conftest.py +55 -0
- poli_page-0.9.0/tests/integration/test_async.py +118 -0
- poli_page-0.9.0/tests/integration/test_documents.py +70 -0
- poli_page-0.9.0/tests/integration/test_preview.py +44 -0
- poli_page-0.9.0/tests/integration/test_render.py +102 -0
- poli_page-0.9.0/tests/test_smoke.py +6 -0
- poli_page-0.9.0/tests/unit/test_async_client.py +471 -0
- poli_page-0.9.0/tests/unit/test_async_documents.py +171 -0
- poli_page-0.9.0/tests/unit/test_async_render.py +209 -0
- poli_page-0.9.0/tests/unit/test_client.py +865 -0
- poli_page-0.9.0/tests/unit/test_documents.py +318 -0
- poli_page-0.9.0/tests/unit/test_errors.py +238 -0
- poli_page-0.9.0/tests/unit/test_fs.py +169 -0
- poli_page-0.9.0/tests/unit/test_render.py +340 -0
- 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.
|