Deprecate PermitException for removal in 4.0, warning only when it is read

[zeevmoney]

Linear issues

• PER-16331: Deprecate PermitException for removal in permit 4.0, warning only when user code reads it.

Why

Base: #143 (stacked on #142 down to #128). This is the last 3.x PR of the stack.

permit 4.0 removes PermitException and makes PermitConnectionError a direct subclass of PermitError (PER-16236), and 3.x has to say so. On the base, PermitException carried a runtime @deprecated("Use PermitError instead") whose message does not mention 4.0. Reading the name did not warn. Instantiating or subclassing the class did, and so did subclassing PermitConnectionError, which is not deprecated. import permit was already silent, because the SDK created its own subclass under catch_warnings.

What changed

• permit/exceptions.py: PermitException keeps its public name and carries the PEP 702 marker (typing_extensions.deprecated) with category=None and this message: "PermitException is deprecated and will be removed in permit 4.0; catch PermitConnectionError instead (in 4.0 it becomes a PermitError)." Type checkers flag it, and the class issues no warning of its own at runtime. The SDK refers to it as _PermitException. At runtime the public name is removed from the module dict and served by a PEP 562 __getattr__, which warns. The warning text is read from the marker's __deprecated__, so type checkers and the runtime show the same string.
• permit/__init__.py: the same __getattr__ serves permit.PermitException and from permit import PermitException, and a TYPE_CHECKING re-export lets type checkers see the deprecated name on the package.
  • Neither __getattr__ is visible to type checkers, so a misspelled name on permit or permit.exceptions is still an error.
  • Neither module overrides __dir__. help(), inspect.getmembers() and mock.create_autospec() read every name dir() lists, so they never read PermitException.
• permit/utils/deprecation.py: _warn_deprecated_name() attributes the warning to the reading line (stacklevel 3). It skips importlib's _handle_fromlist check, so from permit import PermitException warns once, not twice.
• __all__: permit and permit.exceptions now define __all__, listing every SDK name a star import bound before, plus PermitException. So from permit import * and from permit.exceptions import * still bind PermitException, and a handler for it after a star import still catches PermitConnectionError. The star import reads the name through the module __getattr__, so it warns once, at the star-import line, even when the code never uses the name; importing the names the code uses avoids the warning. A test fails when a public name is missing from __all__.
• Static marker: the PER-16331 plan declares PermitException under TYPE_CHECKING. Here the one runtime class carries the marker instead. mypy recognises the marker only when its message is a string literal, so this keeps one class and one message.
• Typed surface:
  • tests/type_check/mypy.ini enables mypy's deprecated error code; strict alone does not report PEP 702 deprecations.
  • tests/type_check/consumer.py imports PermitException from permit.exceptions and reads permit.PermitException, each with a # type: ignore[deprecated] that must stay used. It also checks that missing names on both modules stay attr-defined errors.
  • The sync stub declares no exceptions and is unchanged.
• Docs:
  • README Deprecations lists PermitException as the next 4.0 removal. The entry says which reads warn, what a star import does, and the filter for the new message.
  • MIGRATION.md and the migration skill drop ignore:Use PermitError instead from their -W error commands. They keep it as a note for the releases where import permit itself warns: permit 2.7.0 to 3.0.0 in MIGRATION.md, permit 3.0.0 in the skill.
  • MIGRATION.md's filter list gains the new message.
  • No CI workflow, pyproject setting or test had the old filter on the base.
• Tests: tests/test_fix_permit_exception_deprecation.py (26 tests) replaces 5 tests in tests/test_offline_regressions.py that were written for the runtime decorator.

Behaviour changes

• Each read of PermitException warns once, at the reading line. That covers from permit import PermitException, from permit.exceptions import PermitException, permit.PermitException, permit.exceptions.PermitException, getattr and hasattr.
  • A read warns only when its line runs: an except permit.PermitException: clause only when an exception reaches it, and an annotation never on Python 3.14, which does not evaluate it.
  • Later uses of an imported name do not warn.
• Instantiating, raising or subclassing the class no longer warns by itself (the base warned "Use PermitError instead"). Subclassing PermitConnectionError no longer warns.
• A star import of permit or permit.exceptions warns once (the PermitException deprecation) and binds the same SDK names as before. It no longer binds names the modules import for their own use: typing, datetime, enum, uuid, http, functools, pydantic and aiohttp names, permit.exceptions' type variables P and R, PYDANTIC_VERSION, sdk_logger, and the package's submodules.
• dir(permit) and dir(permit.exceptions) no longer list PermitException.
• Warning filters for "Use PermitError instead" no longer match. The new filter is ignore:PermitException is deprecated:DeprecationWarning.
• PermitException.__deprecated__, which PermitConnectionError inherits, holds the new message.
• Pickling or unpickling a bare PermitException instance warns, because pickle looks the class up by its public name; the pickle bytes are unchanged. PermitConnectionError pickles without a warning.
• Unchanged:
  • except PermitException still catches PermitConnectionError, and isinstance still holds.
  • PermitConnectionError.__mro__, reprs and pickle bytes are the same.
  • import permit emits no warning. On pydantic 1 it still issues only "Support for pydantic 1 is deprecated".

Release notes

PermitException is deprecated and will be removed in permit 4.0: catch PermitConnectionError instead. Importing PermitException, or reading permit.PermitException or permit.exceptions.PermitException, now warns at that line, and mypy (--enable-error-code deprecated) and pyright (strict) flag it. import permit does not warn. A star import of permit or permit.exceptions still binds PermitException and warns once at the star-import line. Filters for the old message, "Use PermitError instead", no longer match; use ignore:PermitException is deprecated:DeprecationWarning. permit 4.0 moves PermitConnectionError under PermitError and removes PermitException.

How it was tested

• Offline suite (pytest -m "not e2e"): 1912 passed, 3 skipped, 0 warnings on each pydantic lane. The base had 1891 passed and 3 skipped.
• tests/test_typing_surface.py: 4 passed on each lane. mypy: no issues in 122 source files on each lane.
• The PR's test files (test_fix_permit_exception_deprecation.py, test_typing_surface.py, test_offline_regressions.py): 125 passed on Python 3.10, 3.12 and 3.14, on both lanes.
• python -W error::DeprecationWarning -c 'import permit' on Python 3.10, 3.12 and 3.14: silent on pydantic 2. On pydantic 1 the only warning recorded is "Support for pydantic 1 is deprecated".
• pyright 1.1.411 in strict mode on a probe file:
  • flags both import lines, permit.PermitException, permit.exceptions.PermitException and an except PermitException clause;
  • does not flag subclassing PermitConnectionError;
  • still reports permit.NoSuchName as an error.
    pyright is not a repo check.
• Mutation check: 21 mutations of the runtime code, the helper and the type-check config, all caught by the tests. They cover:
  • the import warning returning;
  • a wrong message, or a marker message that is not a literal;
  • each guard of the helper, and stacklevel;
  • the name cached after the first read, or kept in the module dict;
  • either __getattr__ serving nothing, not warning, or visible to type checkers;
  • __dir__ added back;
  • PermitConnectionError moved under PermitError;
  • the package re-export removed;
  • the consumer's deprecated error code removed.
• Repo checks:
  • pre-commit (all hooks), uv lock --check, actionlint and zizmor (no findings) pass.
  • CI script tests: 223 passed.
  • Migration skill tests: 86 passed, 1 skipped on each lane.
  • API coverage report, run as the API Coverage job runs it with the offline record: exit 0.
• e2e: 45 tests collected and type-checked, not run locally; CI runs them.

Owner actions before merge

• Let CI run the e2e, compatibility and floor lanes.
• In the test-harnesses repository, drop the python-sdk harness's ignore:Use PermitError instead:DeprecationWarning filter (separate PR there).
• Decide whether the "Use PermitError instead" filter notes stay in MIGRATION.md (permit 2.7.0 to 3.0.0) and the migration skill (permit 3.0.0).

🤖 Generated with Claude Code

[linear-code]

PER-16331

[github-actions]

Dependency Security Audit

Scanned: pyproject.toml dependencies + dev group, resolved at Python 3.10 (the current resolution, and the lowest versions the published specs permit under each pydantic major)

✅ No known vulnerabilities found.

Both the resolved dependency set and the lowest versions the published specs permit are clean at HIGH and CRITICAL.