Skip to content

feat(parsers): add griffe-based Python public API surface parser - #36

Merged
grdsdev merged 10 commits into
mainfrom
claude/cool-chatterjee-c521b3
Jun 23, 2026
Merged

feat(parsers): add griffe-based Python public API surface parser#36
grdsdev merged 10 commits into
mainfrom
claude/cool-chatterjee-c521b3

Conversation

@grdsdev

@grdsdev grdsdev commented Jun 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

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 emits ParsedSymbol[]. Handles sub-module recursion, privacy filtering, property labels, nested classes, file inheritance, and sdk-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 integration

Modified:

  • .github/workflows/validate-sdk-compliance.yml: adds griffe-packages/griffe-search-paths workflow inputs and Python-specific steps (setup-python, pip install griffe, griffe dump, normalize-griffe); existing npm-based steps are guarded with if: inputs.language != 'python'
  • package.json: adds normalize-griffe script, removes parse-python

Deleted:

  • 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

CI step: pip install griffe
         python -m griffe dump <packages> --search <paths> -o api-raw.json
                    ↓
         npm run normalize-griffe -- api-raw.json --project-root <path>
                    ↓
             ParseResult (JSON to stdout)

griffe handles 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) and griffe-search-paths (comma-separated relative search paths).

Test plan

  • 22 tests added: test/normalize-griffe.test.ts
  • Full suite green: 121 tests passed (npm test)
  • TypeScript strict check clean (npm run typecheck)

Linear

Closes SDK-991 (partially — covers Python; TypeScript/Swift already done, Dart in #35)

@grdsdev
feat(parsers): add Python public API surface parser
e69d491 
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
@grdsdev
grdsdev requested review from a team as code owners June 19, 2026 09:23
@grdsdev grdsdev mentioned this pull request Jun 19, 2026
Merged
grdsdev added 4 commits June 19, 2026 10:59
@grdsdev
feat: add griffe JSON normalizer for Python public API surface
160b625
@grdsdev
feat: add normalize-griffe CLI and npm script
448aef4
@grdsdev
ci: replace regex Python parser with griffe-based approach
e448776 
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.
@grdsdev
ci: fix griffe-packages normalization and add empty-input guard
e90801c 
- 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 grdsdev changed the title feat(parsers): add Python public API surface parser feat(parsers): add griffe-based Python public API surface parser Jun 19, 2026
grdsdev added 2 commits June 19, 2026 11:35
@grdsdev
test: fix sdk-parse-ignore test cross-platform compatibility
d4e78c4 
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.
@grdsdev
test: fix sdk-parse-ignore test path to match pattern root
803c784 
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/").
@grdsdev
grdsdev requested a review from o-santi June 19, 2026 14:42
grdsdev added 3 commits June 19, 2026 11:48
@grdsdev
fix: update branch to use .sdk-parse-ignore (renamed in #37)
334b2a7 
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.
@grdsdev
test: use .sdk-parse-ignore in normalize-griffe test
52f969e 
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.
@grdsdev
chore: merge main — add Dart/Swift symbolgraph parsers, resolve confl…
d69bea1 
…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
@grdsdev
grdsdev merged commit c44f836 into main Jun 23, 2026
3 checks passed
@grdsdev
grdsdev deleted the claude/cool-chatterjee-c521b3 branch June 23, 2026 13:31
@supabase-releaser supabase-releaser Bot mentioned this pull request Aug 12, 2026
Merged
grdsdev pushed a commit that referenced this pull request Aug 12, 2026
@supabase-releaser
chore(main): release 1.0.0 (#81)
93b5258 
🤖 I have created a release *beep* *boop*
---


## [1.0.0](v1.0.0...v1.0.0)
(2026-08-12)


### ⚠ BREAKING CHANGES

* reconcile capability matrix inconsistencies from skill audit
([#74](#74))

### Features

* add capabilities based on supabase-js public methods
([#19](#19))
([8b07e38](8b07e38))
* add capability-matrix maintenance skill
([#73](#73))
([070e2c9](070e2c9))
* add review-spec and review-spec-compliance skills
([#6](#6))
([b2646c1](b2646c1))
* add SDK implementation status matrix to README and skill
([#4](#4))
([753f06c](753f06c))
* **api-check:** include file path and line number in compliance failure
messages ([#45](#45))
([2f4be47](2f4be47))
* **auth:** add sign-out reason capability
([#47](#47))
([51a3abd](51a3abd))
* canonical SDK capability matrix
([#8](#8))
([215bc3e](215bc3e))
* **capability-matrix:** strict cross-SDK parity score + coverage scope
([#63](#63))
([de1abe1](de1abe1))
* CI check 1 — block PRs adding public API not in capability matrix
([#31](#31))
([293440c](293440c))
* **compliance:** list undeclared features after validation
([#48](#48))
([29f396a](29f396a))
* **compliance:** list undeclared features as notes after validation
([29f396a](29f396a))
* **compliance:** split symbol evidence from symbol coverage
([#75](#75))
([abc8e71](abc8e71))
* initial SDK specs, skills, and install script
([e662b17](e662b17))
* move SDK compliance to per-repo files
([#15](#15))
([4d32675](4d32675))
* **parsers:** add Dart public API parser via package:analyzer
(alternative to [#35](#35))
([#41](#41))
([e3ba07a](e3ba07a))
* **parsers:** add griffe-based Python public API surface parser
([#36](#36))
([c44f836](c44f836))
* **parsers:** replace Swift regex parser with swift-symbolgraph-extract
([#38](#38))
([80529a7](80529a7))
* **realtime:** add multiple postgres_changes filters capability
([#70](#70))
([825ab0c](825ab0c))
* reconcile capability matrix inconsistencies from skill audit
([#74](#74))
([9c53a70](9c53a70))
* rename sdk-parse-ignore to .sdk-parse-ignore
([#37](#37))
([4f4ab61](4f4ab61))
* render symbol names as clickable links in capability matrix
([#14](#14))
([dcaf122](dcaf122))
* show feature description as visible sub-text in capability matrix
([#13](#13))
([3a750ab](3a750ab))
* **site:** serve compliance.json with precomputed parity from GitHub
Pages ([#46](#46))
([0d9106c](0d9106c))
* **storage:** add purge_cache and purge_bucket_cache canonical
capabilities ([#44](#44))
([9a6f864](9a6f864))
* **storage:** add storage.errors.error_codes capability
([#71](#71))
([fabb9a7](fabb9a7))
* **storage:** add the five missing Iceberg catalog capabilities
([#76](#76))
([c3c8f9e](c3c8f9e))


### Bug Fixes

* **aggregate:** point csharp and go SDKs at correct repo slugs
([#62](#62))
([8b7320f](8b7320f))
* **aggregate:** point kotlin SDK at supabase-community/supabase-kt
([#61](#61))
([b1a99e9](b1a99e9))
* **capability-matrix:** correct coverage scope metric description
([#64](#64))
([5daeaf5](5daeaf5))
* **ci:** repair python pipeline and simplify sdk-compliance workflow
([#42](#42))
([2140f44](2140f44))
* **ci:** use nx to run docs:json so workspace deps are built first
([#56](#56))
([9b449bb](9b449bb))
* **dart-extractor:** exclude
[@internal-annotated](https://github.com/internal-annotated) symbols
from the public API surface
([9bd358e](9bd358e))
* **dart-extractor:** exclude [@internal](https://github.com/internal)
symbols from the public API surface
([#54](#54))
([9bd358e](9bd358e))
* remove broken sticky thead, add scroll-margin-top and group-row
borders ([#10](#10))
([68761cd](68761cd))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: supabase-releaser[bot] <223506987+supabase-releaser[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@o-santi o-santi o-santi approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@grdsdev @o-santi