Update the Python SDK docs for permit 3.0 and 3.1

[zeevmoney]

Linear issues

• PER-16341: Update the docs for the permit-python 3.0.0 and 3.1.0 releases and align every Python SDK snippet with them

Why

permit 3.0.0 is the current Python SDK release on PyPI, and 3.1.0 is next. The docs still described 2.8.3 in several places, and Python snippets across the site used calls that 3.x deprecates or that did not work as written:

• The SDK parity and version tables, the install steps and the prerequisites did not reflect 3.x or its Python 3.10 requirement.
• Two pages called the deprecated flat permit.api.sync_user().
• The FastAPI quick-start's /register returned the SDK's models directly, which current FastAPI answers with 500.
• Step 5 of the first-user walkthrough added an existing user to a second tenant with POST /tenants/{tenant}/users, which answers 409 for a key that already exists.
• The PydanticAI tools caught PermitApiError, which check() and filter_objects() never raise.
• Some Python examples did not parse because of lost indentation or stray leading spaces.
• The features new in 3.1 had no docs.

What changed

permit 3.0

• SDK overview: Python is ✅ for Role Derivations and Create User + Assign Roles. The version table lists the Python release, with a sentence on the Python 3.10 requirement and a link to the 3.0 migration guide at the v3.0.0 tag.
• Cloud PDP capabilities: the Edge-PDP-only list adds POST /user-tenants, POST /allowed_url and the Local Facts API. It says that with proxy_facts_via_pdp=True the Python SDK sends facts reads to the PDP as well as writes, and that tenants.create_user() always goes to the Permit API.
• Send Consistent Updates: the synced route list includes DELETE /facts/users/{user_id}/roles and DELETE /facts/role_assignments.
• Python install steps and prerequisites: the shared asyncio and sync install steps state the Python 3.10 requirement before pip install permit, and note that pip on Python 3.8 or 3.9 installs 2.x. The policy-script page, the FastAPI, Flask and Django quick-starts and the AWS API Gateway page require Python 3.10 or later.
• User permissions how-to: Python tabs for the basic call and the filter example.

permit 3.1 (each marked "permit 3.1 or later")

• Groups API page: a Python section for permit.api.groups. The group-to-group cURL example sends the other group's key alone, because the type:instance form returns 404.
• Python SDK examples: tenants.create_user(), permit.get_user_tenants(), list_detailed(), permit.api.pdps.refresh(), connection reuse with close() and async with/with, and the log settings. A table lists the APIs that permit 4.0 removes. It says which deprecations need 3.1, and gives the PermitException warning text and filter for 3.1 and for 3.0.
• User permissions how-to: a Python tab for ABAC permissions with the context argument.
• Cloud PDP capabilities, list role assignments, Send Consistent Updates: how the SDK reports routes that only a container PDP serves, which facts writes wait for the PDP, and what a sync timeout of 0 does.
• SDK overview: Python is ✅ for Groups, Get User Tenant and Get User Permission (ABAC) from 3.1.0, and the version table lists 3.1.0.

Snippets aligned with 3.x

• v2 migration guide and Access Request MCP implementation guide: permit.api.users.sync() replaces the flat permit.api.sync_user(). The v2 guide says the flat method takes the same single argument, is deprecated, and is removed in permit 4.0.
• Quick-starts: FastAPI returns user.dict() and role_assignment.dict(). Flask uses the blocking client (permit.sync.Permit) and links the sync quickstart. Django and Flask call .dict() directly.
• First-user walkthrough, step 5: the cURL assigns the manager role in the marketing tenant with POST /users/{id}/roles, as the Node.js tab does. The tenant users endpoint is gone from the page's endpoint table.
• PydanticAI: the tools catch PermitConnectionError. A paragraph says when it is raised, says a timeout raises TimeoutError, and shows how to catch both. The versions note says the example's lock file installs permit 2.7.2.
• LangChain: the version warning says langchain-permit 0.1.4 requires permit 2.x, so the tutorial stays on 2.x. It links "Staying on 2.x for now" in the migration guide.
• AWS API Gateway: the Lambda layer is built for the Lambda runtime (manylinux, CPython 3.12, binary wheels only), with an arm64 variant. The authorizer denies a request that has no x-user-key header. The page names the blocking client.
• Elements API snippets (src/components/elements/codeBlock.json): the Python login routes parse, and the client snippet uses from permit import Permit.
• Smaller fixes: authorized-users and sync-applications-data say the blocking client takes the same calls without await. local-facts-uploader mentions the policy argument of wait_for_sync(). data-filtering says what the Python sample prints. The policy script's lists are typed. The ABAC check examples indent with spaces. Two Permit(...) placeholders get real arguments. The Flask example in the auth partial has its indentation back.

Formatting

• Prettier 2.8.8 (.prettierrc.json) runs on every changed page and on codeBlock.json. Tables are realigned, and whitespace changes inside some JSON, JS and Python code blocks.
• Two What's next lists keep one-line links under {/* prettier-ignore */}, so MDX does not wrap the link text in <p>.
• The MCP implementation guide's install commands are indented to match their fences.
• The auth partial's Node.js example keeps its original text under {/* prettier-ignore */}.

Behaviour changes

Most changes are to docs content. One data file under src/ changes: src/components/elements/codeBlock.json, which holds the Elements API snippets. These changes alter what the documented code does:

• FastAPI quick-start: /register answers 200 with the user and the role assignment as JSON, instead of 500.
• Flask quick-start: the app uses permit.sync.Permit and calls it directly, instead of wrapping each asyncio call in asyncio.run().
• First-user walkthrough, step 5: the cURL sends POST /v2/facts/{proj}/{env}/users/user%7C123456789/roles with {"role": "manager", "tenant": "marketing"}.
• AWS API Gateway: the authorizer returns a Deny policy without calling the PDP when x-user-key is missing, and the layer contains Linux wheels for the Lambda runtime.
• PydanticAI: a PDP connection or status error becomes the tool's SecurityError.
• Elements API: the Python login route snippets parse.

How it was tested

• npm run build on the final head: exit 0.
  • Redirect lint, relative links and private paths (656 tracked files) pass.
  • The Docusaurus build succeeds. Its one webpack warning comes from src/components/code-block/CodeBlock.js, which this PR does not change.
  • Hyperlink checked 29,626 links in 2,114 files: 0 bad links, 0 bad anchors.
  • All 526 baseline routes resolve (0 new), and sidebar coverage passes (343 docs).
• Prettier: prettier --check passes on all 24 changed files.
• Python snippets: 106 Python blocks on the 23 changed pages, plus the 3 Python snippets in codeBlock.json.
  • All of them parse.
  • Each of the 81 blocks that use the SDK gets a preamble that creates the client its page uses. All 81 type-check with mypy 2.3.1 against the 3.1 SDK source, including the bodies of untyped functions. The one exception is the v2 guide's v1 sample, which shows the v1 API on purpose.
  • Against permit 3.0.0 from PyPI, 9 blocks fail. Each fails on a feature its page marks "permit 3.1 or later".
  • A scan for the 21 deprecated flat permit.api methods, tenants.add_user(), detailed_key= and PermitException finds only the v1 sample.
  • 7 of 7 mutations on copies of the snippets make a check fail: the flat sync_user() on two pages, a dropped await, tenants.add_user(), the Flask routes on the asyncio client, list(detailed=True), and stray leading spaces in an Elements snippet.
• Claims checked by running the SDK:
  • permit 3.0.0 under -W error::DeprecationWarning: import permit fails with "Use PermitError instead" and passes with ignore:Use PermitError instead:DeprecationWarning. On the 3.1 source, the page's 3.1 filter silences from permit import PermitException.
  • Against a socket that accepts and never answers (pdp_timeout=1), check() and filter_objects() raise TimeoutError. A refused connection raises PermitConnectionError on 3.0.0 and on 2.7.2.
  • FastAPI quick-start on FastAPI 0.142.2: /register answers 200 with the expected JSON. Before the change it answered 500.
  • uv cannot resolve langchain-permit==0.1.4 together with permit>=3.0.0,<4. On its own it resolves to permit 2.8.3.
  • With permit 3.0.0 and proxy_facts_via_pdp=True, the facts reads sent GET /facts/... to the PDP. With the option off, they went to /v2/facts/... on the API.
  • The new user-permissions tabs ran with permit 3.0.0 on Python 3.10.19 and 3.13.9 against a stub PDP. 7 of 7 mutations made the run fail.
• Rendering:
  • For the first formatting commit, I built the site before and after and compared the rendered articles of 360 pages. 354 are byte-identical, and the other 6 differ only in whitespace and commas inside code blocks.
  • For each later Prettier commit, I compiled the changed pages before and after with @mdx-js/mdx 3.1.0. The prose is identical, apart from the two What's next lists, which the prettier-ignore commit fixes. The final build has 0 links that wrap a <p>.

Owner actions before merge

• Merge only after permit 3.1.0 is on PyPI.
• Choose the migration guide link target. This PR pins it to the v3.0.0 tag, which never moves; main would pick up later edits.
• Delete or fix these unused files, which are wrong for 3.x:
  • src/sdks/walkthroughs/authz-queries/getAuthorizedUsers/example.py is missing an await.
  • src/sdks/walkthroughs/sync-first-user/add-user-to-tenant/example.bash sends POST /tenants/{tenant}/users, which answers 409 for an existing user.
  • The bearer key in codeBlock.json tuple-unpacks login_as().
  • docs/tutorials/_connecting_to_authentication.mdx is not imported by any page.
• Not verified without a backend: whether POST /users/{id}/roles answers 409 for a role the user already has. This decides whether the sync quickstart's "safe to restart" sentence needs a try/except.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for permitio-docs ready!

Name	Link
🔨 Latest commit	deebadc
🔍 Latest deploy log	https://app.netlify.com/projects/permitio-docs/deploys/6ac118304f54da00085d28d9
😎 Deploy Preview	https://deploy-preview-662--permitio-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[linear-code]

PER-16341