Repository navigation
add the apisurface kind: a Python package's public API between releases (I19.10) - #218
Conversation
Python first: every release on PyPI, its wheel (or sdist) read in memory as text by pysurface (no import, no execution, no new dependency), and consecutive surfaces compared into removed and renamed symbols, removed parameters and parameters that lost their default. Registers openai/python-sdk, with a golden over two trimmed real wheels. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
|
Claude finished @adssib's task in 2m 25s —— View job Rules
Bugs (inline comments)
Bugs 1–3 should be fixed before merge. Each fix is small, and a drop test per case would pin it down. Verified
Non-blocking
Thanks for the careful write-up. The "Calls I made" section and the trimmed, byte-for-byte test data made this much easier to review. |
| for _, g := range byParent { | ||
| if len(g[0]) == 1 && len(g[1]) == 1 { | ||
| old, now := a[g[0][0]], b[g[1][0]] | ||
| if old.Params != nil && !old.Overloaded && !now.Overloaded && slices.Equal(old.Params, now.Params) && len(old.Params) > 0 { |
There was a problem hiding this comment.
Wrong renamed_symbol when the only parameter is self. len(old.Params) > 0 is meant to require real parameters, but methods (and a class's __init__) always start with self, so it holds trivially. Two examples of what this would report as renames:
- a class removes
def close(self)and addsdef aclose(self)in the same release openai.resourcesremoves one resource class and adds another; both have__init__(self, client: OpenAI), so they compare equal
Either case becomes "X was renamed to Y … Use Y, with the same parameters", which turns into a wrong PR in someone's repo. Suggestion: compare the parameters without a leading self/cls and require at least one left. Requiring the same signature apart from the name (header with the name swapped) would be safer still.
| now := env.Now().UTC() | ||
| var events []event.EventV2 | ||
| var rejected []error | ||
| for _, c := range Compare(a.Surface, b.Surface) { |
There was a problem hiding this comment.
Skipped files show up as removals. ReadAt stores Skipped (files over MaxFileBytes), but Extract never looks at it. If a module is under 4 MiB in release N and over it in N+1, or the cap changes, every symbol in that file gets a removed_symbol event, even though nothing was removed. Suggestion: drop any change whose Before.File is in b.Skipped (or in a.Skipped, for symbols that would show up as new), and log it as a gap. A drop test for this case would pin it down.
| add(n) | ||
| } | ||
| for _, s := range m.stars { | ||
| if t, ok := mods[s]; ok && t != m { |
There was a problem hiding this comment.
A star-import cycle recurses forever and crashes the process. public follows from X import * in __init__s with no hop limit, and the only guard is t != m, which catches direct self-imports only. Example:
pkg/__init__.py:from .sub import *pkg/sub/__init__.py:from .. import *
Unless one of them has __all__, this loops pkg → pkg.sub → pkg until the Go stack overflows. A stack overflow is a fatal runtime error, not a recoverable panic, so it takes down every plugin in the run. The input is untrusted, so public needs a visited set or a hop limit, as resolve already has.
| defLine = regexp.MustCompile(`^(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(`) | ||
| classLine = regexp.MustCompile(`^class\s+([A-Za-z_]\w*)\s*[(:]`) |
There was a problem hiding this comment.
PEP 695 generics aren't matched, so they read as removals. def first[T](xs: list[T]) -> T: fails defLine because [ comes before (. class Box[T](Base): fails classLine for the same reason. Both lines end in :, so they fall into the other block. The function disappears from the surface, and the class's methods get recorded as module-level functions. When a package moves to the 3.12 syntax, that produces removed_symbol events for names that are still there. OpenAI's SDK supports 3.8, so this doesn't affect it today, but the kind is generic. Suggestion: allow an optional \[…\] after the name. At minimum, treat an unmatched def/class line as unreadable and skip that module, rather than reading it as gone.
| switch { | ||
| case i < 0 && kwargs: | ||
| out = append(out, Change{Symbol: k, Note: fmt.Sprintf("%s: parameter %s gone, but **kwargs still takes it", k, op.Name)}) | ||
| case i < 0: |
There was a problem hiding this comment.
Renaming a positional-only parameter isn't breaking. With def f(a, /) → def f(b, /), callers can't pass a by name, so nothing breaks, yet this emits removed_parameter a. Suggestion: skip op.Kind == "positional" here. Comparing the positional count would be the right check, if anything.
…r a method moved up Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
Stacked on #217
Closes #181
What this changes
The
apisurfacekind (I19.10), Python first: for a package on PyPI,ListVersionslists every final release,ReadAtdownloads the release's wheel (or sdist) and reads its public API,Extractcompares two releases into events.archive/zip,archive/tar; nothing written to disk, links never followed,MaxFileBytes/MaxSourceBytescaps).plugins/apisurface/pysurfacereads the.py/.pyifiles as text: logical lines (strings kept, comments dropped, brackets joined), indentation, and the headers ofdef/async def/class,__all__andfrom … import. Bodies are skipped. A.pyistub wins over its.py.ast: reading what someone else publishes must never run it, and a Python interpreter would be a second runtime next to the plugins; the pure-Go Python parsers available follow old grammars (no f-strings,/,match…) and would be the module's second dependency. The import allowlist is unchanged (gopkg.in/yaml.v3only)._client.py), in__all__when there is one; an__init__'s re-exports (from ._client import OpenAI) count, followed to the definition.package_release):removed_symbol(a removed class's members aren't repeated),renamed_symbol(one removed, one added, same scope and kind, identical non-empty parameters),removed_parameter(not when the function now takes**kwargs),changed_default(a parameter lost its default: callers must pass it). Overloaded functions' parameters aren't compared. A new required parameter is logged, not an event: the contract has no subject for it. The source URL is the newer release's file; the excerpt quotes the definition's file and line in both releases.openai/python-sdk(pypi:openai, first nameopenai),providers/openai-python-sdk.md. Golden: openai 1.1.1 → 1.1.2, which renamed the misspelledAsssitantDeleted(2 events: its re-export and its module). The two wheels are real, trimmed toopenai/types/beta/and the__init__s, byte for byte (checked: the same surface underopenai.types.betaas the whole wheels)..d.ts) is the follow-up, I19.12 · apisurface for npm: a package's exported API from its .d.ts files #212 (Backlog, unassigned).Acceptance criteria
__all__;TestRead)Calls I made (please check)
ToolRetreival→ToolRetrieval-style renames of a class without its own__init__read as removals (no parameters to tell it's the same class): precision over recall.Checks
make checkpasses (tidy, build, gofmt, vet, import allowlist, net/http guard,go test -race, noTODO(new-plugin), leak guard);make contractagainst patch-it'smainfixtures passes (11 files).plugins/apisurface/testdata/golden/openai-1.1.2.json, 2 events); no existing golden changedRelated PRs
apps/plugins-repo.md)v0.3.0(see "What the next bump changes" in the combined PR); the contract change this stack prepares for: patch-it-dev/patch-it#58 (adopted in a separate PR after it merges)🤖 Generated with Claude Code