Python
Dynamic Regex since v1.0🐍 Respects __all__ when present; falls back to top-level defs and classes without underscore prefixes.
.py What gets detected
The public surface spec-sync tracks for Python.
- __all__ list (authoritative when present)
- Top-level def / async def without _ prefix (fallback)
- Top-level class without _ prefix (fallback)
Detection rules
__all__ list (authoritative)
If __all__ is defined, it is the sole source of exported names. Both double-quoted and single-quoted strings in the list are captured.
__all__ = ["create_auth", "AuthService", "DEFAULT_TTL"]
# Even underscore names are exported if listed:
__all__ = ["_special", "Public"]Top-level def / async def (fallback)
When __all__ is absent, any top-level function whose name does not start with _ is captured. Includes async def.
def create_auth(config):
pass
async def fetch_token():
pass
def _internal(): # excluded
passTop-level class (fallback)
Top-level class declarations without _ prefix are captured as exports.
class AuthService:
pass
class _Hidden: # excluded
passExample: spec & source
The *.spec.md contract on the left,
the Python source it documents on the right. spec-sync matches the two.
Spec (*.spec.md)
---
module: auth
version: 1
status: stable
files:
- src/auth/service.py
---
## Purpose
Handles authentication and session management.
## Public API
| Symbol | Kind | Description |
|--------|------|-------------|
| `create_auth` | function | Creates an auth context |
| `AuthService` | class | Auth service class |
| `DEFAULT_TTL` | constant | Default TTL in seconds |
## Change Log
| Date | Change |
|------|--------|
| 2026-01-01 | Initial |Source
__all__ = ["create_auth", "AuthService", "DEFAULT_TTL"]
DEFAULT_TTL = 3600
def create_auth(config):
return AuthService(config)
class AuthService:
def __init__(self, config):
self.config = config
def _internal_helper():
passTest-file patterns
Files matching these are excluded from the detected surface.
| Pattern | Explanation |
|---|---|
test_*.py | pytest-style test files: auto-excluded |
*_test.py | Alternate test naming: auto-excluded |
Caveats
- Only the top-level __all__ assignment is captured; dynamic or conditional __all__ assignments may not be found.
- Nested class definitions (inside another class or function) are not detected.
- Decorator-only exports (e.g., Flask route functions registered via @app.route) are included as normal functions.
- Type-alias assignments (MyType = Dict[str, Any]) are not captured. Only def and class.