feat(parsers): add griffe-based Python public API surface parser#36
Merged
Conversation
Regex-based TypeScript parser that extracts the public API surface from Python SDK source files. Follows the same design as swift-parser.ts. Key behaviors: - Extracts public classes, methods, properties (@Property), and top-level functions based on Python's leading-underscore privacy convention - Skips dunder methods (__init__, __repr__, etc.), private names (_*), and property setters/deleters (@name.setter) - Tracks indentation-based context to scope members to their enclosing class and prevent method-body content from leaking as false symbols - Supports src-layout (src/package/) and flat-layout (package/) - Respects sdk-parse-ignore for file/directory exclusions - Skips generated directories (__pycache__, venv, build, dist, etc.) Adds parse-python npm script and wires python as a supported language in the reusable validate-sdk-compliance CI workflow. Linear: SDK-991
Add griffe-packages and griffe-search-paths workflow inputs, add Python-specific steps (setup-python, install griffe, run griffe dump, normalize output) with if: inputs.language == 'python' guards, restrict existing Resolve/Parse steps with if: inputs.language != 'python', and remove the old regex-based python-parser.ts, parse-python.ts, and related tests.
- Normalize griffe-packages input to handle both comma and space-separated values by adding a normalization step that converts commas to spaces and removes extra whitespace - Add early-exit guard in both griffe dump steps to require griffe-packages when language=python - Add test case for skipping dunder methods (__init__) in normalize-griffe
grdsdev
changed the title
Anchored patterns with an internal slash (e.g. "src/tests/") behave
inconsistently in ignore@6.x across macOS and Ubuntu — the pattern
fails to match file paths under that directory on Linux. Use a
non-anchored directory pattern ("tests/") instead, which matches at
any depth and is consistent across platforms, matching the approach
already used in parse-ignore.test.ts.
The ignore@6.x package on Linux only matches directory patterns against
the leading path component. Change the test filepath from
src/tests/test_client.py to tests/test_client.py so the "tests/"
pattern matches the first component, consistent with how
parse-ignore.test.ts structures its fixtures ("Tests/AuthTests.swift"
for pattern "Tests/").
PR #37 renamed sdk-parse-ignore to .sdk-parse-ignore on main after this branch was cut. Update parse-ignore.ts and all test files to use the new name so the branch is consistent both locally and on the CI merge commit.
The filename was renamed in #37 after this branch was cut. Update normalize-griffe.test.ts to write .sdk-parse-ignore so the CI merge commit (which picks up the rename from main) finds the file.
…icts Merge origin/main (PRs #37–#40) into this branch: - #37: sdk-parse-ignore → .sdk-parse-ignore (already synced) - #38: Dart symbol extractor - #39: Swift symbolgraph parser (replaces regex parser, deletes swift-parser.test.ts) - #40: CODEOWNERS, README, CLAUDE.md updates Conflict resolutions: - package.json: keep both normalize-griffe (ours) and normalize-symbolgraph (main) - validate-sdk-compliance.yml: add Python steps alongside Dart/Swift symbolgraph steps; conditions on Resolve/Parse steps now exclude python, swift, and dart
o-santi
approved these changes
Jun 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a griffe-based Python public API surface parser, replacing the initial hand-rolled regex approach with a native Python tool (same pattern as the Dart parser in #35). Part of SDK-991.
Changes
New files:
src/normalize-griffe.ts: Core normalizer — walks griffe's hierarchical JSON and emitsParsedSymbol[]. Handles sub-module recursion, privacy filtering, property labels, nested classes, file inheritance, andsdk-parse-ignore.src/normalize-griffe-cli.ts: CLI entry point (npm run normalize-griffe <api-raw.json> [--project-root <path>])test/normalize-griffe.test.ts: 22 tests covering all symbol types, privacy rules, sub-module traversal, and ignore integrationModified:
.github/workflows/validate-sdk-compliance.yml: addsgriffe-packages/griffe-search-pathsworkflow inputs and Python-specific steps (setup-python, pip install griffe, griffe dump, normalize-griffe); existing npm-based steps are guarded withif: inputs.language != 'python'package.json: addsnormalize-griffescript, removesparse-pythonDeleted:
src/python-parser.ts(regex parser, superseded)src/parse-python.ts(old CLI)test/python-parser.test.ts(old tests)test/fixtures/python-sample/(old fixture)How it works
griffehandles all Python AST parsing (properties, decorators, nested classes, src-layouts). The TypeScript normalizer is ~75 lines. It recurses through the module tree, tracking class context for qualified names (AsyncGoTrueClient.sign_up). Privacy rule: skip names starting with_at emit time; always recurse into sub-modules regardless of their name (e.g.,_async,_sync).Calling SDK repos pass
griffe-packages(space- or comma-separated package names) andgriffe-search-paths(comma-separated relative search paths).Test plan
test/normalize-griffe.test.tsnpm test)npm run typecheck)Linear
Closes SDK-991 (partially — covers Python; TypeScript/Swift already done, Dart in #35)