From ab212be8943506958afeb0bb0eb1361b5ea7820b Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 18:07:18 -0500 Subject: [PATCH 1/3] add the apisurface kind: a package's public API between releases 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 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- AGENTS.md | 2 +- docs/how-it-works.md | 2 +- docs/plugins.schema.json | 2 +- docs/writing-a-plugin.md | 7 + plugins/all/all.go | 1 + plugins/apisurface/apisurface.go | 349 +++++++++++++ plugins/apisurface/apisurface_test.go | 179 +++++++ plugins/apisurface/artifact.go | 187 +++++++ plugins/apisurface/pysurface/lines.go | 170 ++++++ plugins/apisurface/pysurface/pysurface.go | 485 ++++++++++++++++++ .../apisurface/pysurface/pysurface_test.go | 117 +++++ plugins/apisurface/testdata/README.md | 10 + .../testdata/golden/openai-1.1.2.json | 50 ++ .../openai-1.1.1-py3-none-any.trimmed.whl | Bin 0 -> 41474 bytes .../openai-1.1.2-py3-none-any.trimmed.whl | Bin 0 -> 41470 bytes .../testdata/pypi-openai-1.1.1.json | 20 + .../testdata/pypi-openai-1.1.2.json | 20 + .../testdata/pypi-openai-excerpt.json | 63 +++ providers/openai-python-sdk.md | 32 ++ 19 files changed, 1693 insertions(+), 3 deletions(-) create mode 100644 plugins/apisurface/apisurface.go create mode 100644 plugins/apisurface/apisurface_test.go create mode 100644 plugins/apisurface/artifact.go create mode 100644 plugins/apisurface/pysurface/lines.go create mode 100644 plugins/apisurface/pysurface/pysurface.go create mode 100644 plugins/apisurface/pysurface/pysurface_test.go create mode 100644 plugins/apisurface/testdata/README.md create mode 100644 plugins/apisurface/testdata/golden/openai-1.1.2.json create mode 100644 plugins/apisurface/testdata/openai-1.1.1-py3-none-any.trimmed.whl create mode 100644 plugins/apisurface/testdata/openai-1.1.2-py3-none-any.trimmed.whl create mode 100644 plugins/apisurface/testdata/pypi-openai-1.1.1.json create mode 100644 plugins/apisurface/testdata/pypi-openai-1.1.2.json create mode 100644 plugins/apisurface/testdata/pypi-openai-excerpt.json create mode 100644 providers/openai-python-sdk.md diff --git a/AGENTS.md b/AGENTS.md index 565d096..c37e6bc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,7 +59,7 @@ core/event/ core/migrate/ the change-event types from patch-it's contract ( core/diff/ core/normalize/ core/hint/ the OpenAPI diff engine and its helpers plugins// one package per kind, with its providers: openapi (+ adapter/, one spec adapter per provider), notices (+ retire/, feed/, eol/), migrationguide (+ sdkguide/, - members/), changelog (Markdown, RST or JSON), catalog; + members/), changelog (Markdown, RST or JSON), catalog, apisurface (+ pysurface/); plugins/all imports every one plugins/removedmembers/ apichangelog/ retirements/ feed/ eol/ deprecated: merged into migrationguide, changelog and notices, they only forward there diff --git a/docs/how-it-works.md b/docs/how-it-works.md index eee82d1..642e17b 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -21,7 +21,7 @@ There's no list in this repo: `make plugins` prints every provider and source fr |---|---| | [`core/plugin/`](../core/plugin/) | The `Plugin` interface (`Run`; `ListVersions`, `ReadAt`, `Extract`), the registry of providers and sources (`RegisterProvider`, `Lookup`, `LookupSource`, `Providers`), `Env`, `Result` | | [`core/versions/`](../core/versions/) | Every version of a source: GitHub releases, tags and commits, PyPI, npm, a page's Web Archive captures (all, or the one at a date) | -| [`plugins/`](../plugins/) | One package per kind, with its providers; `plugins/all` imports every one | +| [`plugins/`](../plugins/) | One package per kind, with its providers (openapi, changelog, notices, migrationguide, catalog, apisurface); `plugins/all` imports every one | | [`cmd/new-plugin/`](../cmd/new-plugin/), [`cmd/list-plugins/`](../cmd/list-plugins/) | The starter for a new provider; the list of providers and sources, printed from the registry | | [`core/kit/`](../core/kit/), [`core/kit/kittest/`](../core/kit/kittest/), [`core/github/`](../core/github/), [`core/extract/`](../core/extract/) | What plugins share (the unchanged-page check, Wayback citing, the newest release or commit on GitHub, RSS/Atom and HTML text helpers) and the test kit (in-memory store, saved pages, golden files) | | [`core/event/`](../core/event/), [`core/migrate/`](../core/migrate/) | The change-event types of [patch-it's contract](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract), and the v1 → v2 conversion | diff --git a/docs/plugins.schema.json b/docs/plugins.schema.json index d935a39..c5af222 100644 --- a/docs/plugins.schema.json +++ b/docs/plugins.schema.json @@ -40,7 +40,7 @@ "first_name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$", "description": "The source's first name, its old slug: what fingerprints keep hashing after the contract switches to source ids." }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$" }, "description": "Every other name the source answers to." }, "packages": { "type": "array", "items": { "type": "string", "pattern": "^(pypi|npm|go|maven|nuget|rubygems|cargo|packagist):[^\\s]+$" }, "description": "The published packages this source covers, as ecosystem:name, so a lockfile entry finds its sources." }, - "kind": { "type": "string", "enum": ["openapi", "changelog", "notices", "migrationguide", "catalog"] }, + "kind": { "type": "string", "enum": ["openapi", "changelog", "notices", "migrationguide", "catalog", "apisurface"] }, "layer": { "type": "string", "enum": ["api", "sdk", "package", "runtime", "ci", "ai-models", "infra"] }, "watches": { "type": "string", "minLength": 1 }, "urls": { "type": "array", "items": { "type": "string", "pattern": "^https://" } }, diff --git a/docs/writing-a-plugin.md b/docs/writing-a-plugin.md index ca73552..62de359 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -80,6 +80,7 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp | `plugins/migrationguide` | A guide that lists what a release removed, at the release's tag: an SDK's migration guide per new major (removed request parameters), or a package's table of removed members (an RST simple table or a Markdown pipe table) | A `sdkguide.Guide` in `plugins/migrationguide/sdkguide/`, or a `members.Guide` in `plugins/migrationguide/members/` | | `plugins/changelog` | A changelog: a `CHANGELOG.md` / `CHANGES.rst` / `HISTORY.rst`, each release's section at its tag (releases from PyPI or npm), or a vendor's machine-readable API changelog in JSON (per day, endpoint and API version, oasdiff change codes), commit by commit | A `changelog.File` with its `TagPrefix`, or a `changelog.Log` | | `plugins/catalog` | A flat JSON catalog, one entry per name, with no release tags to pin — a commit SHA stands in | A `catalog.Catalog`, diffed between two snapshots for names that disappeared entirely | +| `plugins/apisurface` | A published package's public API, compared between two releases: the classes, functions, methods and parameters in each release's files (Python first: the wheel or sdist from PyPI) | A `apisurface.Package` (registry name, ecosystem, top-level module) and its `plugin.RegisterProvider` block | ## 4. The interface @@ -124,6 +125,12 @@ Extract(ctx, env, from, to Snapshot) (Result, error) // the changes fro A living page with no versions of its own (a deprecations page, a feed: a `notices` source) is read as it is now by `Run`, and each change to it is a dated version. Its history comes from the Web Archive: the `notices` kind lists every distinct capture (`WaybackCaptures`), reads each, and extracts what each one added, citing that capture, so a year of it can be backfilled by date with no stored copies. +### The `apisurface` kind: reading a package's API without running it + +`plugins/apisurface` downloads a release's wheel (or sdist) through `env.Get`, opens it in memory (`archive/zip`, `archive/tar`: nothing is written to disk) and hands the `.py` and `.pyi` files to `plugins/apisurface/pysurface`, which reads them as text: logical lines, indentation, and the headers of `def`, `class`, `__all__` and `from … import`. Nothing in the package is imported, compiled or run. That's the safest way to read code someone else publishes, and it needs no dependency: a Python interpreter (the `ast` module) would mean running a second runtime next to the plugins, and the pure-Go Python parsers available follow old grammars and pull in a large module for what is a few hundred lines here. The cost is that only signatures are read, never what a body does, and anything the reader can't be sure of is left out (see `providers/openai-python-sdk.md`). Archive and file sizes are capped (`MaxFileBytes`, `MaxSourceBytes`), so a crafted release can't exhaust the runner. + +An event cites the newer release's file, and its excerpt quotes the definition's path and line in both releases. npm packages (`.d.ts` files) are next. + ### Register the provider and its source In the kind's package `init`, with the metadata ([AGENTS.md](../AGENTS.md) rule 1): diff --git a/plugins/all/all.go b/plugins/all/all.go index 834349d..051a892 100644 --- a/plugins/all/all.go +++ b/plugins/all/all.go @@ -4,6 +4,7 @@ package all import ( + _ "github.com/patch-it-dev/patch-it-plugins/plugins/apisurface" _ "github.com/patch-it-dev/patch-it-plugins/plugins/catalog" _ "github.com/patch-it-dev/patch-it-plugins/plugins/changelog" _ "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide" diff --git a/plugins/apisurface/apisurface.go b/plugins/apisurface/apisurface.go new file mode 100644 index 0000000..b300ebf --- /dev/null +++ b/plugins/apisurface/apisurface.go @@ -0,0 +1,349 @@ +// Package apisurface is the kind for a published package with no changelog +// worth reading: its public API is compared between two releases, read from +// the released files themselves. A class, function or method that is gone, +// or renamed, a parameter that is gone, or one that lost its default (callers +// must now pass it), is an event. +// +// Python first: every release on PyPI (ListVersions), the release's wheel +// (or sdist) read without running any of it (ReadAt: pysurface/ reads the +// .py and .pyi files as text), and the two surfaces compared (Extract). Each +// event cites the release file and quotes the definition's file and line in +// both releases. npm (.d.ts) is a follow-up. +// +// What isn't read, on purpose (precision over recall): private names (a +// leading underscore, a private module, a name left out of __all__), +// classes nested in classes, overloaded functions' parameters, a removed +// parameter when the function now takes **kwargs (passing it still works), +// and a parameter newly added without a default (patch-it's change-event +// contract has no subject for it yet: logged). +package apisurface + +import ( + "context" + "encoding/json" + "fmt" + "log" + "slices" + "strings" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/versions" + "github.com/patch-it-dev/patch-it-plugins/plugins/apisurface/pysurface" +) + +func init() { + plugin.RegisterProvider(plugin.Provider{ + ID: "openai", Name: "OpenAI", Category: plugin.CategoryAI, Homepage: "https://openai.com", + Sources: []plugin.Source{{ + ID: "python-sdk", Layer: plugin.LayerSDK, Page: "providers/openai-python-sdk.md", + Watches: "Classes, functions, methods and parameters removed or renamed in the public API of the openai Python package, release by release, read from each release's wheel", + URLs: []string{"https://pypi.org/project/openai/", "https://github.com/openai/openai-python"}, + Packages: []string{"pypi:openai"}, + Plugin: Plugin{Package: OpenAIPython}, + }}, + }) +} + +// Package is one published package. +type Package struct { + Name string // on the registry, and the events' api: "openai" + Ecosystem string // "pypi" + Module string // the top-level import name: "openai" +} + +// OpenAIPython is the openai package on PyPI. +var OpenAIPython = Package{Name: "openai", Ecosystem: "pypi", Module: "openai"} + +// Plugin reads one package's releases. +type Plugin struct { + Package Package +} + +func (p Plugin) Name() string { return p.Package.Name } + +// Run reads the newest release and extracts it against the last one read +// (the baseline), or against nothing on a first run: the surface it stores +// as the baseline. +func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { + vs, err := p.ListVersions(ctx, env) + if err != nil { + return plugin.Result{}, err + } + if len(vs) == 0 { + return plugin.Result{}, fmt.Errorf("%s: no release listed", p.Package.Name) + } + v := vs[len(vs)-1] + last, err := env.Baselines.LastSpec(p.Package.Name) + if err != nil { + return plugin.Result{}, fmt.Errorf("loading the last baseline of %s: %w", p.Package.Name, err) + } + if last != nil && last.Version == v.ID { + log.Printf("%s: no new release since %s", p.Package.Name, v.ID) + return plugin.Result{}, nil + } + to, err := p.ReadAt(ctx, env, v) + if err != nil { + return plugin.Result{}, err + } + var from plugin.Snapshot + if last != nil { + from = plugin.Snapshot{Version: plugin.Version{ID: last.Version, Ref: last.Tag}, Content: last.Content, SourceURL: last.SourceURL} + } + res, err := p.Extract(ctx, env, from, to) + if err != nil { + return plugin.Result{}, err + } + res.Baselines = []plugin.Spec{plugin.Baseline(p.Package.Name, v.ID, v.Ref, to.SourceURL, to.Content, false, env.Now().UTC())} + return res, nil +} + +// ListVersions is every final release on the registry, oldest first. +func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { + switch p.Package.Ecosystem { + case "pypi": + return versions.PyPIReleases(ctx, env.Get, p.Package.Name) + default: + return nil, fmt.Errorf("%s: reading a %q package's API isn't supported yet", p.Package.Name, p.Package.Ecosystem) + } +} + +// snapshot is what ReadAt keeps of a release: its public surface, and +// what couldn't be read. +type snapshot struct { + Artifact string `json:"artifact"` + Surface pysurface.Surface `json:"surface"` + Skipped []string `json:"skipped,omitempty"` // files over the size limit +} + +// ReadAt downloads the release's wheel (or sdist) and reads its public +// surface. The snapshot's content is the surface as JSON, its SourceURL the +// file read. +func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) { + pkg := p.Package + a, err := pickArtifact(ctx, env, pkg.Name, v.ID) + if err != nil { + return plugin.Snapshot{}, err + } + body, err := env.Get(ctx, a.URL) + if err != nil { + return plugin.Snapshot{}, fmt.Errorf("fetching %s: %w", a.URL, err) + } + files, skipped, err := sourceFiles(a, body, pkg.Module) + if err != nil { + return plugin.Snapshot{}, err + } + if len(files) == 0 { + return plugin.Snapshot{}, fmt.Errorf("%s has no %s/ source files", a.Filename, pkg.Module) + } + for _, s := range skipped { + log.Printf("%s %s: %s skipped: over %d bytes", pkg.Name, v.ID, s, MaxFileBytes) + } + content, err := json.Marshal(snapshot{Artifact: a.Filename, Surface: pysurface.Read(files), Skipped: skipped}) + if err != nil { + return plugin.Snapshot{}, err + } + return plugin.Snapshot{Version: v, Content: content, SourceURL: a.URL}, nil +} + +// Extract compares from's surface with to's: an event per class, function or +// method gone or renamed, and per parameter gone or now required, with to's +// version and from's as previous_version. A zero from has nothing to compare: +// no events. +func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) { + if from.IsZero() { + return plugin.Result{Label: to.Version.ID}, nil + } + var a, b snapshot + if err := json.Unmarshal(from.Content, &a); err != nil { + return plugin.Result{}, fmt.Errorf("reading the %s %s surface: %w", p.Package.Name, from.Version.ID, err) + } + if err := json.Unmarshal(to.Content, &b); err != nil { + return plugin.Result{}, fmt.Errorf("reading the %s %s surface: %w", p.Package.Name, to.Version.ID, err) + } + now := env.Now().UTC() + var events []event.EventV2 + var rejected []error + for _, c := range Compare(a.Surface, b.Surface) { + if c.Change == "" { + log.Printf("%s %s: not an event: %s", p.Package.Name, to.Version.ID, c.Note) + continue + } + e := p.event(c, from, to, a.Artifact, b.Artifact, now) + e.Fingerprint = event.FingerprintV2(e.API, e.Version, e.ChangeType, e.Subject, "") + if err := e.Validate(); err != nil { + rejected = append(rejected, fmt.Errorf("%s %s %s: %w", p.Package.Name, to.Version.ID, c.Symbol, err)) + continue + } + events = append(events, e) + } + return plugin.Result{Label: to.SourceURL, Events: events, Rejected: rejected}, nil +} + +var _ plugin.Versioned = Plugin{} + +// event is one change as a change event. +func (p Plugin) event(c Change, from, to plugin.Snapshot, fromFile, toFile string, now time.Time) event.EventV2 { + pkg := p.Package + sym := p.local(c.Symbol) + subject := event.Subject{Type: event.SubjectPackageRelease, Ecosystem: pkg.Ecosystem, Package: pkg.Name, Change: c.Change, Symbols: []string{sym}} + var desc, hint string + switch c.Change { + case event.PackageRenamedSymbol: + subject.Replacement = p.local(c.Replacement) + desc = fmt.Sprintf("`%s` was renamed to `%s` in %s %s: code using the old name fails.", sym, subject.Replacement, pkg.Name, to.Version.ID) + hint = fmt.Sprintf("Use `%s`, with the same parameters.", subject.Replacement) + case event.PackageRemovedSymbol: + desc = fmt.Sprintf("The %s `%s` was removed in %s %s: code using it fails.", c.Kind, sym, pkg.Name, to.Version.ID) + hint = fmt.Sprintf("%s %s has no `%s`: see the package's release notes for what replaces it.", pkg.Name, to.Version.ID, sym) + case event.PackageRemovedParameter: + subject.Parameter = c.Parameter + desc = fmt.Sprintf("`%s` no longer takes the parameter `%s` in %s %s: passing it raises a TypeError.", sym, c.Parameter, pkg.Name, to.Version.ID) + hint = fmt.Sprintf("Stop passing `%s` to `%s`; its signature in %s is quoted in the source excerpt.", c.Parameter, sym, to.Version.ID) + case event.PackageChangedDefault: + subject.Parameter = c.Parameter + desc = fmt.Sprintf("`%s`'s parameter `%s` has no default in %s %s (it was `%s`): a call that leaves it out raises a TypeError.", sym, c.Parameter, pkg.Name, to.Version.ID, c.OldDefault) + hint = fmt.Sprintf("Pass `%s=%s` to `%s` to keep the old behavior.", c.Parameter, c.OldDefault, sym) + } + return event.EventV2{ + API: pkg.Name, + Version: to.Version.ID, + PreviousVersion: from.Version.ID, + ChangeType: event.ChangeTypeBreaking, + Breaking: true, + Subject: subject, + Description: desc, + MigrationHint: hint, + SourceURL: to.SourceURL, + SourceExcerpt: cap2000(excerpt(pkg.Name, from.Version.ID, fromFile, c.Before) + "\n" + excerpt(pkg.Name, to.Version.ID, toFile, c.After)), + Confidence: 1.0, + DetectedAt: now, + } +} + +// local is a symbol as code writes it after importing the package: +// "openai.OpenAI.with_options" is "OpenAI.with_options". +func (p Plugin) local(sym string) string { return strings.TrimPrefix(sym, p.Package.Module+".") } + +// excerpt quotes one release's definition: "openai 1.0.0, openai/_client.py +// line 12: def create(...)", or that the release has none. +func excerpt(pkg, version, file string, s *pysurface.Symbol) string { + if s == nil { + return fmt.Sprintf("%s %s (%s): not defined", pkg, version, file) + } + return fmt.Sprintf("%s %s (%s), %s line %d: %s", pkg, version, file, s.File, s.Line, s.Signature) +} + +func cap2000(s string) string { + if r := []rune(s); len(r) > 2000 { + return string(r[:1999]) + "…" + } + return s +} + +// Change is one difference between two surfaces: an event (Change set) or +// a difference that isn't one (Note says why). +type Change struct { + Change event.PackageChange + Kind string // the symbol's kind, for sentences + Symbol string // its full path: "openai.OpenAI.create" + Replacement string // renamed_symbol: the new path + Parameter string + OldDefault string + Before *pysurface.Symbol // its definition in the older release + After *pysurface.Symbol // in the newer one; nil when gone + Note string +} + +// Compare lists what changed from a to b, sorted by symbol: removed and +// renamed symbols (a member of a removed class isn't listed again), then +// for every symbol in both, removed parameters and parameters that lost +// their default. A rename is one removed and one added symbol of the same +// kind under the same parent with the same parameters; anything less sure +// is a removal. +func Compare(a, b pysurface.Surface) []Change { + var out []Change + removed := map[string]bool{} + byParent := map[string][2][]string{} // parent+kind -> removed, added + for k, s := range a { + if _, ok := b[k]; !ok { + removed[k] = true + key := parentOf(k) + " " + s.Kind + g := byParent[key] + g[0] = append(g[0], k) + byParent[key] = g + } + } + for k, s := range b { + if _, ok := a[k]; !ok { + key := parentOf(k) + " " + s.Kind + g := byParent[key] + g[1] = append(g[1], k) + byParent[key] = g + } + } + renamed := map[string]string{} + 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 { + renamed[g[0][0]] = g[1][0] + } + } + } + for k := range removed { + if removed[parentOf(k)] { + continue // its class is reported + } + before := a[k] + c := Change{Change: event.PackageRemovedSymbol, Kind: before.Kind, Symbol: k, Before: &before} + if r, ok := renamed[k]; ok { + after := b[r] + c.Change, c.Replacement, c.After = event.PackageRenamedSymbol, r, &after + } + out = append(out, c) + } + for k, old := range a { + now, ok := b[k] + if !ok || old.Overloaded || now.Overloaded || old.Params == nil || now.Params == nil { + continue + } + before, after := old, now + kwargs := slices.ContainsFunc(now.Params, func(p pysurface.Param) bool { return p.Kind == "kwargs" }) + for _, op := range old.Params { + if op.Kind == "args" || op.Kind == "kwargs" { + continue + } + i := slices.IndexFunc(now.Params, func(p pysurface.Param) bool { return p.Name == op.Name }) + 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: + out = append(out, Change{Change: event.PackageRemovedParameter, Kind: old.Kind, Symbol: k, Parameter: op.Name, Before: &before, After: &after}) + case op.HasDef && !now.Params[i].HasDef && now.Params[i].Kind != "args" && now.Params[i].Kind != "kwargs": + out = append(out, Change{Change: event.PackageChangedDefault, Kind: old.Kind, Symbol: k, Parameter: op.Name, OldDefault: op.Default, Before: &before, After: &after}) + } + } + for _, np := range now.Params { + if np.HasDef || np.Kind == "args" || np.Kind == "kwargs" { + continue + } + if !slices.ContainsFunc(old.Params, func(p pysurface.Param) bool { return p.Name == np.Name }) { + out = append(out, Change{Symbol: k, Note: fmt.Sprintf("%s: new required parameter %s (no subject for it in the contract yet)", k, np.Name)}) + } + } + } + slices.SortFunc(out, func(x, y Change) int { + return strings.Compare(x.Symbol+" "+x.Parameter+" "+x.Note, y.Symbol+" "+y.Parameter+" "+y.Note) + }) + return out +} + +// parentOf is "openai.OpenAI" for "openai.OpenAI.create". +func parentOf(sym string) string { + if i := strings.LastIndexByte(sym, '.'); i >= 0 { + return sym[:i] + } + return "" +} diff --git a/plugins/apisurface/apisurface_test.go b/plugins/apisurface/apisurface_test.go new file mode 100644 index 0000000..5723fa8 --- /dev/null +++ b/plugins/apisurface/apisurface_test.go @@ -0,0 +1,179 @@ +package apisurface + +import ( + "archive/zip" + "bytes" + "context" + "strings" + "testing" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/versions" + "github.com/patch-it-dev/patch-it-plugins/plugins/apisurface/pysurface" +) + +const ( + wheel111 = "https://files.pythonhosted.org/packages/f7/86/ea99e3f966a639a3256e2f79d78cd63d45d5eb651a5457ccbdcfd9eed24a/openai-1.1.1-py3-none-any.whl" + wheel112 = "https://files.pythonhosted.org/packages/dd/82/b92f73453ea318c0d46f31aeb56e9d94a42606c010fb72a513f4a3cd4bac/openai-1.1.2-py3-none-any.whl" +) + +// The saved releases (testdata/README.md): PyPI's answers and the two +// wheels, trimmed to the openai.types.beta package. +var saved = kittest.Pages{ + "https://pypi.org/pypi/openai/json": "testdata/pypi-openai-excerpt.json", + "https://pypi.org/pypi/openai/1.1.1/json": "testdata/pypi-openai-1.1.1.json", + "https://pypi.org/pypi/openai/1.1.2/json": "testdata/pypi-openai-1.1.2.json", + wheel111: "testdata/openai-1.1.1-py3-none-any.trimmed.whl", + wheel112: "testdata/openai-1.1.2-py3-none-any.trimmed.whl", +} + +// pair lists the releases, reads 1.1.1 and 1.1.2 and extracts the pair. +func pair(t *testing.T) []event.EventV2 { + t.Helper() + ctx, env := context.Background(), kittest.Env(t, saved) + p := Plugin{Package: OpenAIPython} + vs, err := p.ListVersions(ctx, env) + if err != nil { + t.Fatal(err) + } + var ids []string + for _, v := range vs { + ids = append(ids, v.ID) + } + if got := strings.Join(ids, " "); got != "1.1.0 1.1.1 1.1.2" { + t.Fatalf("versions %s", got) + } + last := versions.Pairs(vs)[1] + from, err := p.ReadAt(ctx, env, last[0]) + if err != nil { + t.Fatal(err) + } + to, err := p.ReadAt(ctx, env, last[1]) + if err != nil { + t.Fatal(err) + } + if to.SourceURL != wheel112 { + t.Errorf("source %s", to.SourceURL) + } + res, err := p.Extract(ctx, env, from, to) + if err != nil || len(res.Rejected) > 0 { + t.Fatalf("%v %v", err, res.Rejected) + } + return res.Events +} + +// openai 1.1.2 renamed the misspelled AsssitantDeleted to AssistantDeleted, +// module and all: the old name is gone from both places code could import +// it. (Not read as a rename: the class has no parameters to tell it's the +// same class.) +func TestGolden(t *testing.T) { + got := pair(t) + kittest.Golden(t, "testdata/golden/openai-1.1.2.json", got) + for _, e := range got { + if e.PreviousVersion != "1.1.1" || e.Version != "1.1.2" || !strings.Contains(e.SourceExcerpt, "openai/types/beta/asssitant_deleted.py line ") { + t.Errorf("%v: %s<-%s, excerpt %q", e.Subject.Symbols, e.Version, e.PreviousVersion, e.SourceExcerpt) + } + } +} + +// The pinned drop test: 1.1.2 adds AssistantDeleted and its module. A name +// that appears is no breaking change: no event names it. +func TestAnAddedNameIsNoEvent(t *testing.T) { + for _, e := range pair(t) { + for _, s := range e.Subject.Symbols { + if strings.Contains(s, "AssistantDeleted") || strings.Contains(s, "assistant_deleted") { + t.Errorf("event for %s, which 1.1.2 added", s) + } + } + } +} + +func TestRegistersItself(t *testing.T) { + kittest.Registered(t, Plugin{Package: OpenAIPython}) +} + +func sym(kind string, params ...pysurface.Param) pysurface.Symbol { + if params == nil { + params = []pysurface.Param{} + } + return pysurface.Symbol{Kind: kind, File: "acme/x.py", Line: 1, Signature: "def f()", Params: params} +} + +func prm(name, kind, def string) pysurface.Param { + return pysurface.Param{Name: name, Kind: kind, Default: def, HasDef: def != ""} +} + +// Each kind of change, and what isn't one. +func TestCompare(t *testing.T) { + a := pysurface.Surface{ + "acme.Gone": sym("class"), + "acme.Gone.method": sym("method"), + "acme.old_name": sym("function", prm("x", "either", "")), + "acme.f": sym("function", prm("a", "either", ""), prm("b", "keyword", "1"), prm("c", "keyword", "2")), + "acme.g": sym("function", prm("a", "either", "")), + "acme.h": sym("function", prm("a", "either", "")), + "acme.overloaded": {Kind: "function", Overloaded: true}, + "acme.Kept": sym("class", prm("self", "either", ""), prm("timeout", "either", "600")), + "acme.Kept.with_kwargs": sym("method", prm("self", "either", ""), prm("opt", "keyword", "None")), + } + b := pysurface.Surface{ + "acme.new_name": sym("function", prm("x", "either", "")), + "acme.f": sym("function", prm("a", "either", ""), prm("b", "keyword", "")), + "acme.g": sym("function", prm("a", "either", ""), prm("z", "keyword", "")), + "acme.h": sym("function", prm("a", "positional", "")), + "acme.overloaded": {Kind: "function", Overloaded: true}, + "acme.Kept": sym("class", prm("self", "either", ""), prm("timeout", "either", "600")), + "acme.Kept.with_kwargs": sym("method", prm("self", "either", ""), prm("kw", "kwargs", "")), + } + var got []string + for _, c := range Compare(a, b) { + if c.Change == "" { + got = append(got, "note "+c.Symbol) + continue + } + got = append(got, string(c.Change)+" "+c.Symbol+" "+c.Parameter+c.Replacement) + } + want := []string{ + "removed_symbol acme.Gone ", + "note acme.Kept.with_kwargs", + "changed_default acme.f b", + "removed_parameter acme.f c", + "note acme.g", + "renamed_symbol acme.old_name acme.new_name", + } + if strings.Join(got, "\n") != strings.Join(want, "\n") { + t.Errorf("got\n%s\nwant\n%s", strings.Join(got, "\n"), strings.Join(want, "\n")) + } +} + +// An archive is read, never unpacked or run: paths outside the package, a +// path climbing out, and an oversized file are left out. +func TestSourceFilesStayInThePackage(t *testing.T) { + var buf bytes.Buffer + zw := zip.NewWriter(&buf) + for name, body := range map[string]string{ + "acme/__init__.py": "def ok(): pass\n", + "acme/big.py": strings.Repeat("#", 64) + "\n", + "../acme/evil.py": "def evil(): pass\n", + "tests/test_acme.py": "def test(): pass\n", + "acme-1.0.dist-info/RECORD": "", + } { + w, _ := zw.Create(name) + w.Write([]byte(body)) + } + zw.Close() + old := MaxFileBytes + MaxFileBytes = 32 + t.Cleanup(func() { MaxFileBytes = old }) + files, skipped, err := sourceFiles(artifact{Filename: "acme-1.0-py3-none-any.whl", Kind: "bdist_wheel"}, buf.Bytes(), "acme") + if err != nil { + t.Fatal(err) + } + if len(files) != 1 || files[0].Path != "acme/__init__.py" || len(skipped) != 1 || skipped[0] != "acme/big.py" { + t.Errorf("files %v, skipped %v", files, skipped) + } +} + +var _ plugin.Versioned = Plugin{} diff --git a/plugins/apisurface/artifact.go b/plugins/apisurface/artifact.go new file mode 100644 index 0000000..010edc3 --- /dev/null +++ b/plugins/apisurface/artifact.go @@ -0,0 +1,187 @@ +package apisurface + +import ( + "archive/tar" + "archive/zip" + "bytes" + "compress/gzip" + "context" + "encoding/json" + "fmt" + "io" + "net/url" + "path" + "slices" + "strings" + + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/versions" + "github.com/patch-it-dev/patch-it-plugins/plugins/apisurface/pysurface" +) + +// The limits on what is read out of an archive: a release is data, and a +// crafted one (a zip bomb, a huge generated file) must not exhaust the +// runner. A file over MaxFileBytes is skipped (logged as a gap in the +// surface, never guessed at); an archive whose source files add up to more +// than MaxSourceBytes is refused. Variables only so a test can lower them. +var ( + MaxFileBytes int64 = 4 << 20 + MaxSourceBytes int64 = 128 << 20 +) + +// artifact is the file of a release that's read: a wheel if there is one +// (the files as installed), else the sdist. +type artifact struct { + URL string + Filename string + Kind string // "bdist_wheel", "sdist" +} + +// pickArtifact chooses the release file to read from PyPI's JSON for one +// release: a pure-Python wheel ("py3-none-any"), else any wheel (its .py +// files are the same), else the sdist (.tar.gz or .zip). +func pickArtifact(ctx context.Context, env plugin.Env, pkg, version string) (artifact, error) { + u := versions.PyPI + "/pypi/" + url.PathEscape(pkg) + "/" + url.PathEscape(version) + "/json" + body, err := env.Get(ctx, u) + if err != nil { + return artifact{}, fmt.Errorf("listing %s %s's files on PyPI: %w", pkg, version, err) + } + var doc struct { + URLs []struct { + URL string `json:"url"` + Filename string `json:"filename"` + PackageType string `json:"packagetype"` + Yanked bool `json:"yanked"` + } `json:"urls"` + } + if err := json.Unmarshal(body, &doc); err != nil { + return artifact{}, fmt.Errorf("parsing PyPI's %s %s: %w", pkg, version, err) + } + var wheels, sdists []artifact + for _, f := range doc.URLs { + a := artifact{URL: f.URL, Filename: f.Filename, Kind: f.PackageType} + switch { + case f.PackageType == "bdist_wheel" && strings.HasSuffix(f.Filename, ".whl"): + wheels = append(wheels, a) + case f.PackageType == "sdist" && (strings.HasSuffix(f.Filename, ".tar.gz") || strings.HasSuffix(f.Filename, ".zip")): + sdists = append(sdists, a) + } + } + byName := func(a, b artifact) int { return strings.Compare(a.Filename, b.Filename) } + slices.SortFunc(wheels, byName) + slices.SortFunc(sdists, byName) + for _, w := range wheels { + if strings.Contains(w.Filename, "-none-any.whl") { + return w, nil + } + } + if len(wheels) > 0 { + return wheels[0], nil + } + if len(sdists) > 0 { + return sdists[0], nil + } + return artifact{}, fmt.Errorf("%s %s has no wheel or sdist on PyPI", pkg, version) +} + +// sourceFiles are the .py and .pyi files of an archive, each with its path +// from the package's top directory ("openai/_client.py"): a wheel's paths +// as they are, an sdist's without its "-/" and "src/" +// prefixes. Nothing is written to disk and nothing in it is run. +func sourceFiles(a artifact, body []byte, module string) ([]pysurface.File, []string, error) { + var files []pysurface.File + var skipped []string + var total int64 + add := func(name string, size int64, open func() (io.Reader, error)) error { + if !strings.HasSuffix(name, ".py") && !strings.HasSuffix(name, ".pyi") { + return nil + } + rel, ok := packagePath(name, module, a.Kind == "sdist") + if !ok { + return nil + } + if size > MaxFileBytes { + skipped = append(skipped, rel) + return nil + } + total += size + if total > MaxSourceBytes { + return fmt.Errorf("%s: over %d bytes of source", a.Filename, MaxSourceBytes) + } + r, err := open() + if err != nil { + return err + } + b, err := io.ReadAll(io.LimitReader(r, MaxFileBytes+1)) + if err != nil { + return err + } + if int64(len(b)) > MaxFileBytes { + skipped = append(skipped, rel) + return nil + } + files = append(files, pysurface.File{Path: rel, Text: string(b)}) + return nil + } + switch { + case strings.HasSuffix(a.Filename, ".whl") || strings.HasSuffix(a.Filename, ".zip"): + zr, err := zip.NewReader(bytes.NewReader(body), int64(len(body))) + if err != nil { + return nil, nil, fmt.Errorf("reading %s: %w", a.Filename, err) + } + for _, f := range zr.File { + if f.FileInfo().IsDir() { + continue + } + if err := add(f.Name, int64(f.UncompressedSize64), func() (io.Reader, error) { return f.Open() }); err != nil { + return nil, nil, err + } + } + case strings.HasSuffix(a.Filename, ".tar.gz"): + gz, err := gzip.NewReader(bytes.NewReader(body)) + if err != nil { + return nil, nil, fmt.Errorf("reading %s: %w", a.Filename, err) + } + tr := tar.NewReader(gz) + for { + h, err := tr.Next() + if err == io.EOF { + break + } + if err != nil { + return nil, nil, fmt.Errorf("reading %s: %w", a.Filename, err) + } + if h.Typeflag != tar.TypeReg { + continue // links and devices are never followed + } + if err := add(h.Name, h.Size, func() (io.Reader, error) { return tr, nil }); err != nil { + return nil, nil, err + } + } + default: + return nil, nil, fmt.Errorf("%s: not a wheel, .tar.gz or .zip", a.Filename) + } + slices.SortFunc(files, func(x, y pysurface.File) int { return strings.Compare(x.Path, y.Path) }) + return files, skipped, nil +} + +// packagePath is name's path from the top module's directory, and false for +// a file outside it (tests, docs, setup.py, another top-level package, a +// path that climbs out with ".."). +func packagePath(name, module string, sdist bool) (string, bool) { + name = path.Clean(strings.TrimPrefix(name, "./")) + if strings.HasPrefix(name, "../") || path.IsAbs(name) { + return "", false + } + parts := strings.Split(name, "/") + if sdist && len(parts) > 1 { + parts = parts[1:] // "-/" + if len(parts) > 1 && parts[0] == "src" { + parts = parts[1:] + } + } + if len(parts) == 0 || (parts[0] != module && parts[0] != module+".py" && parts[0] != module+".pyi") { + return "", false + } + return strings.Join(parts, "/"), true +} diff --git a/plugins/apisurface/pysurface/lines.go b/plugins/apisurface/pysurface/lines.go new file mode 100644 index 0000000..1171994 --- /dev/null +++ b/plugins/apisurface/pysurface/lines.go @@ -0,0 +1,170 @@ +// Package pysurface reads the public API of a Python package from its source +// files, statically: the modules, classes, functions and methods code can +// import, with each one's parameters and their defaults. It never imports, +// compiles or runs the package's code: it reads the text, the way a person +// reading the files would. +// +// It is not a Python parser. It reads only what a signature needs: logical +// lines (comments dropped, strings kept whole, brackets and backslashes +// joining physical lines), their indentation, and the headers of `def`, +// `async def` and `class` statements, `__all__ = [...]` and +// `from ... import ...`. Function bodies are skipped. Whatever it can't read +// for sure (a dynamic `__all__`, a star import it can't resolve, an +// overloaded function's parameters) it leaves out: precision over recall. +package pysurface + +import ( + "strings" +) + +// line is one logical line of Python: its text with comments dropped and +// physical lines joined, its indentation, and the physical line it starts on. +type line struct { + text string + indent int + num int // 1-based +} + +// logicalLines splits a Python source file into logical lines. Strings +// (single, double, triple quoted, with any prefix) are kept verbatim, so a +// default value reads as written; a `#` inside one is not a comment. +func logicalLines(src string) []line { + src = strings.ReplaceAll(src, "\r\n", "\n") + var out []line + var cur strings.Builder + depth := 0 + startNum, num := 0, 1 + indent := -1 + atLineStart := true + col := 0 + flush := func() { + t := strings.TrimSpace(cur.String()) + if t != "" { + out = append(out, line{text: t, indent: indent, num: startNum}) + } + cur.Reset() + indent = -1 + depth = 0 + } + for i := 0; i < len(src); i++ { + c := src[i] + if atLineStart { + // Measure the indentation of a new logical line. + if c == ' ' || c == '\t' { + if c == '\t' { + col += 8 - col%8 + } else { + col++ + } + continue + } + atLineStart = false + if indent < 0 && c != '\n' && c != '#' { + indent, startNum = col, num + } + } + switch { + case c == '#': + for i < len(src) && src[i] != '\n' { + i++ + } + i-- // let the newline be handled + case c == '\'' || c == '"': + end := stringEnd(src, i) + lit := src[i:end] + num += strings.Count(lit, "\n") + cur.WriteString(lit) + i = end - 1 + case c == '\\' && i+1 < len(src) && src[i+1] == '\n': + cur.WriteByte(' ') + i++ + num++ + case c == '(' || c == '[' || c == '{': + depth++ + cur.WriteByte(c) + case c == ')' || c == ']' || c == '}': + if depth > 0 { + depth-- + } + cur.WriteByte(c) + case c == '\n': + num++ + if depth > 0 { + cur.WriteByte(' ') + continue + } + flush() + atLineStart, col = true, 0 + default: + cur.WriteByte(c) + } + } + flush() + return out +} + +// stringEnd is the index just past the string literal that starts at i (a +// quote): triple or single quoted, with backslash escapes. An unterminated +// one ends at the end of its line (single) or the file (triple). +func stringEnd(src string, i int) int { + q := src[i] + triple := strings.HasPrefix(src[i:], strings.Repeat(string(q), 3)) + j := i + 1 + if triple { + j = i + 3 + } + for j < len(src) { + switch { + case src[j] == '\\': + j += 2 + continue + case triple && strings.HasPrefix(src[j:], strings.Repeat(string(q), 3)): + return j + 3 + case !triple && src[j] == q: + return j + 1 + case !triple && src[j] == '\n': + return j + } + j++ + } + return len(src) +} + +// splitTop splits s on sep where it isn't inside brackets or a string. +func splitTop(s string, sep byte) []string { + var out []string + depth, start := 0, 0 + for i := 0; i < len(s); i++ { + switch c := s[i]; { + case c == '\'' || c == '"': + i = stringEnd(s, i) - 1 + case c == '(' || c == '[' || c == '{': + depth++ + case c == ')' || c == ']' || c == '}': + depth-- + case c == sep && depth == 0: + out = append(out, s[start:i]) + start = i + 1 + } + } + return append(out, s[start:]) +} + +// closing is the index of the bracket that closes the one at open, or -1. +func closing(s string, open int) int { + depth := 0 + for i := open; i < len(s); i++ { + switch c := s[i]; { + case c == '\'' || c == '"': + i = stringEnd(s, i) - 1 + case c == '(' || c == '[' || c == '{': + depth++ + case c == ')' || c == ']' || c == '}': + depth-- + if depth == 0 { + return i + } + } + } + return -1 +} diff --git a/plugins/apisurface/pysurface/pysurface.go b/plugins/apisurface/pysurface/pysurface.go new file mode 100644 index 0000000..9a84a43 --- /dev/null +++ b/plugins/apisurface/pysurface/pysurface.go @@ -0,0 +1,485 @@ +package pysurface + +import ( + "path" + "regexp" + "slices" + "strings" +) + +// Surface is a package's public API at one version: every public symbol by +// its import path ("openai.OpenAI", "openai.OpenAI.with_options"). +type Surface map[string]Symbol + +// Symbol is one class, function or method code can reach. +type Symbol struct { + Kind string `json:"kind"` // "class", "function", "method" + File string `json:"file"` // where it's defined, in the artifact + Line int `json:"line"` // its def or class line there + // Signature is the header as written, whitespace collapsed: "def + // create(self, *, model: str, n: int | None = None) -> Completion". A + // class's is its class line, then its __init__ when it has one. + Signature string `json:"signature"` + // Params are what a call passes, in order (a class's are its + // __init__'s); nil when they can't be read for sure (Overloaded). + Params []Param `json:"params,omitempty"` + // Overloaded is a function written as @overload variants: its + // parameters aren't compared. + Overloaded bool `json:"overloaded,omitempty"` +} + +// Param is one parameter. +type Param struct { + Name string `json:"name"` + Kind string `json:"kind"` // "positional" (before /), "either", "keyword" (after *), "args" (*a), "kwargs" (**k) + Default string `json:"default,omitempty"` // as written; "" with HasDefault false is no default + HasDef bool `json:"has_default,omitempty"` +} + +// File is one source file of the package: its path in the artifact, with the +// package's top directory first ("openai/_client.py"), and its text. +type File struct { + Path string + Text string +} + +// module is one file read: its own definitions and how it re-exports others. +type module struct { + name string // "openai.types.chat" + file string // its path + defs map[string]Symbol // by name in the module ("OpenAI", "OpenAI.with_options") + order []string // defs' names, in file order + all []string // __all__, when it's a plain list of strings + hasAll bool + imports map[string][2]string // local name -> {module, name} from "from M import name as local" + stars []string // modules of "from M import *" +} + +var ( + defLine = regexp.MustCompile(`^(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(`) + classLine = regexp.MustCompile(`^class\s+([A-Za-z_]\w*)\s*[(:]`) + allLine = regexp.MustCompile(`^__all__\s*(?::[^=]*)?=\s*[\[(](.*)[\])]\s*$`) + fromLine = regexp.MustCompile(`^from\s+(\.*[\w.]*)\s+import\s+(.+)$`) + strLit = regexp.MustCompile(`^[rRuU]?(?:"([^"\\]*)"|'([^'\\]*)')$`) + name = regexp.MustCompile(`^[A-Za-z_]\w*$`) + spaces = regexp.MustCompile(`\s+`) +) + +// Read is the public surface of the package whose files these are. A module +// is public when no part of its path starts with "_" (__init__ aside); its +// public names are its own definitions and, in a package's __init__, the +// names it imports from the package (re-exports, "from ._client import +// OpenAI"), less any starting with "_"; only those in __all__ when it has +// one (re-exports included, in any module). A .pyi stub next to a +// .py file is read instead of it. +func Read(files []File) Surface { + byPath := map[string]File{} + for _, f := range files { + byPath[f.Path] = f + } + mods := map[string]*module{} + for _, f := range files { + if !strings.HasSuffix(f.Path, ".py") && !strings.HasSuffix(f.Path, ".pyi") { + continue + } + if strings.HasSuffix(f.Path, ".py") { + if _, stub := byPath[f.Path+"i"]; stub { + continue + } + } + m := parse(f) + mods[m.name] = m + } + out := Surface{} + for _, m := range mods { + if private(m.name) { + continue + } + for _, n := range m.public(mods) { + for k, s := range resolve(mods, m, n, 0) { + out[m.name+"."+k] = s + } + } + } + return out +} + +// moduleName is "openai.types.chat" for "openai/types/chat/__init__.py". +func moduleName(p string) string { + p = strings.TrimSuffix(strings.TrimSuffix(p, ".pyi"), ".py") + p = strings.TrimSuffix(p, "/__init__") + return strings.ReplaceAll(p, "/", ".") +} + +// private is a module with a part starting with "_", or a test module. +func private(mod string) bool { + for _, part := range strings.Split(mod, ".") { + if strings.HasPrefix(part, "_") || part == "tests" || part == "test" || strings.HasPrefix(part, "test_") { + return true + } + } + return false +} + +// public are the module's public top-level names, in a stable order. +func (m *module) public(mods map[string]*module) []string { + if m.hasAll { + return m.all + } + var out []string + seen := map[string]bool{} + add := func(n string) { + if !strings.HasPrefix(n, "_") && !seen[n] { + seen[n] = true + out = append(out, n) + } + } + for _, n := range m.order { + if !strings.Contains(n, ".") { + add(n) + } + } + // Imported names are the package's API only where a package says so: + // its __init__ (re-exports) or __all__. Elsewhere an import is the + // module's own business. + if !m.isInit() { + return out + } + locals := make([]string, 0, len(m.imports)) + for n := range m.imports { + locals = append(locals, n) + } + slices.Sort(locals) + for _, n := range locals { + add(n) + } + for _, s := range m.stars { + if t, ok := mods[s]; ok && t != m { + for _, n := range t.public(mods) { + add(n) + } + } + } + return out +} + +// isInit is a package's __init__.py or __init__.pyi. +func (m *module) isInit() bool { + return path.Base(strings.TrimSuffix(strings.TrimSuffix(m.file, "i"), ".py")) == "__init__" +} + +// resolve is name in m and its members ("OpenAI", "OpenAI.with_options"), +// following re-exports a few hops; nothing for a name that isn't a class or +// function the package defines (a constant, a type alias, a module). +func resolve(mods map[string]*module, m *module, n string, hops int) map[string]Symbol { + if hops > 4 { + return nil + } + if s, ok := m.defs[n]; ok { + out := map[string]Symbol{n: s} + for k, v := range m.defs { + if strings.HasPrefix(k, n+".") { + out[k] = v + } + } + return out + } + if imp, ok := m.imports[n]; ok { + if t, ok := mods[imp[0]]; ok { + return rekey(resolve(mods, t, imp[1], hops+1), imp[1], n) + } + return nil + } + for _, s := range m.stars { + if t, ok := mods[s]; ok && t != m { + if got := resolve(mods, t, n, hops+1); got != nil { + return got + } + } + } + return nil +} + +// rekey renames the symbols of name from to name to: a re-export under +// another name ("AsyncClient as Async"). +func rekey(syms map[string]Symbol, from, to string) map[string]Symbol { + if from == to || syms == nil { + return syms + } + out := make(map[string]Symbol, len(syms)) + for k, v := range syms { + out[to+strings.TrimPrefix(k, from)] = v + } + return out +} + +// block is an open def or class while its body is read. +type block struct { + indent int + kind string // "class", "def", "other" + name string // the def's or class's path in the module: "OpenAI.with_options" +} + +// parse reads one file's definitions, __all__ and imports. +func parse(f File) *module { + m := &module{name: moduleName(f.Path), file: f.Path, defs: map[string]Symbol{}, imports: map[string][2]string{}} + var stack []block + var decorators []string + for _, l := range logicalLines(f.Text) { + for len(stack) > 0 && l.indent <= stack[len(stack)-1].indent { + stack = stack[:len(stack)-1] + } + // Where this line is: at module level (only if/try/with blocks + // around it), in a class body at module level, or anywhere else. + parent, inDef := "", false + for _, b := range stack { + switch b.kind { + case "def": + inDef = true + case "class": + parent = b.name + } + } + nested := strings.Count(parent, ".") > 0 // a class inside a class: not read + t := l.text + opens := strings.HasSuffix(t, ":") + switch { + case strings.HasPrefix(t, "@"): + decorators = append(decorators, strings.TrimSpace(t[1:])) + continue + case defLine.MatchString(t): + n := defLine.FindStringSubmatch(t)[1] + path := n + if parent != "" { + path = parent + "." + n + } + if !inDef && !nested { + m.addDef(path, parent, l, t, decorators) + } + stack = append(stack, block{indent: l.indent, kind: "def", name: path}) + case classLine.MatchString(t): + n := classLine.FindStringSubmatch(t)[1] + path := n + if parent != "" { + path = parent + "." + n + } + if !inDef && parent == "" { + m.defs[path] = Symbol{Kind: "class", File: f.Path, Line: l.num, Signature: header(t)} + m.order = append(m.order, path) + } + kind := "class" + if inDef { + kind = "def" + } + stack = append(stack, block{indent: l.indent, kind: kind, name: path}) + case opens && !strings.Contains(t, "lambda"): + // if/else/try/except/with/for: what's inside is still at + // this level. + stack = append(stack, block{indent: l.indent, kind: "other", name: parent}) + case parent == "" && !inDef && allLine.MatchString(t): + m.readAll(allLine.FindStringSubmatch(t)[1]) + case parent == "" && !inDef && fromLine.MatchString(t): + fm := fromLine.FindStringSubmatch(t) + m.readImport(fm[1], fm[2]) + } + decorators = nil + } + return m +} + +// addDef records a function, or a method of a module-level class; a +// class's __init__ becomes the class's own parameters. +func (m *module) addDef(path, parent string, l line, text string, decorators []string) { + n := path[strings.LastIndex(path, ".")+1:] + params, ok := params(text) + overloaded := slices.ContainsFunc(decorators, func(d string) bool { return d == "overload" || d == "typing.overload" }) + if !ok { + params = nil + } + if parent != "" && n == "__init__" { + c := m.defs[parent] + c.Signature = strings.TrimSuffix(c.Signature, ":") + " / " + header(text) + if overloaded || c.Overloaded { + c.Params, c.Overloaded = nil, true + } else { + c.Params = params + } + m.defs[parent] = c + return + } + if strings.HasPrefix(n, "_") { + return + } + kind := "function" + if parent != "" { + kind = "method" + } + if have, dup := m.defs[path]; dup && (overloaded || have.Overloaded) { + // @overload variants, then the implementation: one symbol, its + // parameters not compared. + have.Overloaded, have.Params = true, nil + if !overloaded { + have.Line, have.Signature = l.num, header(text) + } + m.defs[path] = have + return + } + s := Symbol{Kind: kind, File: m.file, Line: l.num, Signature: header(text), Params: params, Overloaded: overloaded} + if overloaded { + s.Params = nil + } + if _, dup := m.defs[path]; !dup { + m.order = append(m.order, path) + } + m.defs[path] = s +} + +// header is a def or class line without its body, whitespace collapsed. +func header(text string) string { + if open := strings.IndexByte(text, '('); open >= 0 { + if end := closing(text, open); end > 0 { + rest := text[end+1:] + if colon := indexTop(rest, ':'); colon >= 0 { + rest = rest[:colon] + } + return spaces.ReplaceAllString(strings.TrimSpace(text[:end+1]+rest), " ") + } + } + if colon := strings.IndexByte(text, ':'); colon >= 0 { + text = text[:colon] + } + return spaces.ReplaceAllString(strings.TrimSpace(text), " ") +} + +// indexTop is the first sep outside brackets and strings, or -1. +func indexTop(s string, sep byte) int { + parts := splitTop(s, sep) + if len(parts) < 2 { + return -1 + } + return len(parts[0]) +} + +// params reads a def line's parameter list. ok is false when the list +// can't be read for sure. +func params(text string) ([]Param, bool) { + open := strings.IndexByte(text, '(') + end := closing(text, open) + if open < 0 || end < 0 { + return nil, false + } + inner := strings.TrimSpace(text[open+1 : end]) + if inner == "" { + return []Param{}, true + } + var out []Param + kind := "either" + for _, raw := range splitTop(inner, ',') { + p := strings.TrimSpace(raw) + switch { + case p == "": + continue // a trailing comma + case p == "/": + for i := range out { + out[i].Kind = "positional" + } + continue + case p == "*": + kind = "keyword" + continue + } + var prm Param + if def := indexTop(p, '='); def >= 0 { + prm.Default, prm.HasDef = spaces.ReplaceAllString(strings.TrimSpace(p[def+1:]), " "), true + p = p[:def] + } + if colon := indexTop(p, ':'); colon >= 0 { + p = p[:colon] + } + p = strings.TrimSpace(p) + switch { + case strings.HasPrefix(p, "**"): + prm.Kind, p = "kwargs", p[2:] + case strings.HasPrefix(p, "*"): + prm.Kind, p = "args", p[1:] + kind = "keyword" + default: + prm.Kind = kind + } + if !name.MatchString(p) { + return nil, false + } + prm.Name = p + out = append(out, prm) + } + return out, true +} + +// readAll reads `__all__ = ["a", "b"]`; anything but plain strings leaves +// it unread (every public name counts then). +func (m *module) readAll(list string) { + var names []string + for _, item := range splitTop(list, ',') { + item = strings.TrimSpace(item) + if item == "" { + continue + } + s := strLit.FindStringSubmatch(item) + if s == nil { + return + } + names = append(names, s[1]+s[2]) + } + m.all, m.hasAll = names, true +} + +// readImport reads `from M import a, b as c` (or `*`), keeping imports from +// the package itself: relative ones, and absolute ones under its top module. +func (m *module) readImport(from, names string) { + target := absolute(m, from) + if target == "" { + return + } + names = strings.TrimSpace(strings.Trim(strings.TrimSpace(names), "()")) + if names == "*" { + m.stars = append(m.stars, target) + return + } + for _, item := range splitTop(names, ',') { + f := strings.Fields(item) + switch { + case len(f) == 1 && name.MatchString(f[0]): + m.imports[f[0]] = [2]string{target, f[0]} + case len(f) == 3 && f[1] == "as" && name.MatchString(f[0]) && name.MatchString(f[2]): + m.imports[f[2]] = [2]string{target, f[0]} + } + } +} + +// absolute is the module a from-import names, or "" for one outside the +// package. +func absolute(m *module, from string) string { + top := strings.SplitN(m.name, ".", 2)[0] + dots := len(from) - len(strings.TrimLeft(from, ".")) + if dots == 0 { + if from == top || strings.HasPrefix(from, top+".") { + return from + } + return "" + } + // The package a relative import starts from: the module's own for + // __init__, its parent otherwise; each further dot goes up one. + base := strings.Split(m.name, ".") + if !m.isInit() { + base = base[:len(base)-1] + } + if dots-1 > len(base) { + return "" + } + base = base[:len(base)-(dots-1)] + rest := from[dots:] + if rest != "" { + base = append(base, strings.Split(rest, ".")...) + } + return strings.Join(base, ".") +} diff --git a/plugins/apisurface/pysurface/pysurface_test.go b/plugins/apisurface/pysurface/pysurface_test.go new file mode 100644 index 0000000..b8402ca --- /dev/null +++ b/plugins/apisurface/pysurface/pysurface_test.go @@ -0,0 +1,117 @@ +package pysurface + +import ( + "encoding/json" + "testing" +) + +const initPy = `"""Acme.""" +from ._client import Client, AsyncClient as Async +from .version import __version__ +from . import types +from .helpers import * +from os import path + +__all__ = ["Client", "Async", "helper", "VERSION"] +VERSION = "1" +` + +const clientPy = `import typing +from typing import overload + +class Client(Base): + """A client. + + # not a comment + """ + + def __init__(self, api_key: str | None = None, *, timeout: float = 600.0, **kwargs) -> None: + self._x = "a # b" + + def create( + self, + model: str, # the model + /, + n: int = 1, + *, + stream: bool = False, + extra=("a", "b,c"), + ) -> "Result": + def inner(z): + pass + return None + + @property + def models(self) -> int: + return 1 + + def _private(self, x): + pass + + @overload + def get(self, a: int) -> int: ... + @overload + def get(self, a: str) -> str: ... + def get(self, a): + return a + + class Nested: + def deep(self, q): pass + +if typing.TYPE_CHECKING: + class AsyncClient: pass +else: + class AsyncClient(Client): \ + pass + +def _hidden(): pass +` + +const helpersPy = `__all__ = ["helper"] + +async def helper(x, *args, y=None, **kw): + pass + +def not_exported(): pass +` + +func TestRead(t *testing.T) { + s := Read([]File{ + {"acme/__init__.py", initPy}, + {"acme/_client.py", clientPy}, + {"acme/helpers.py", helpersPy}, + {"acme/tests/test_x.py", "def test_a(): pass\n"}, + }) + var keys []string + for k := range s { + keys = append(keys, k) + } + want := map[string]bool{ + "acme.Client": true, "acme.Client.create": true, "acme.Client.models": true, "acme.Client.get": true, + "acme.Async": true, "acme.helper": true, + "acme.helpers.helper": true, + } + if len(s) != len(want) { + b, _ := json.MarshalIndent(s, "", " ") + t.Fatalf("got %d symbols %v, want %v\n%s", len(s), keys, want, b) + } + for k := range want { + if _, ok := s[k]; !ok { + t.Errorf("missing %s (have %v)", k, keys) + } + } + c := s["acme.Client"] + if c.File != "acme/_client.py" || c.Line != 4 || len(c.Params) != 4 || c.Params[1].Name != "api_key" || c.Params[1].Default != "None" || c.Params[2].Kind != "keyword" || c.Params[3].Kind != "kwargs" { + t.Errorf("Client: %+v", c) + } + cr := s["acme.Client.create"] + if cr.Line != 13 || len(cr.Params) != 5 || cr.Params[1].Kind != "positional" || cr.Params[2].Kind != "either" || cr.Params[3].Kind != "keyword" || cr.Params[4].Default != `("a", "b,c")` { + t.Errorf("create: %+v", cr) + } + if g := s["acme.Client.get"]; !g.Overloaded || g.Params != nil || g.Line != 37 { + t.Errorf("get: %+v", g) + } + if h := s["acme.helper"]; h.Params[1].Kind != "args" || h.Params[2].Kind != "keyword" { + t.Errorf("helper: %+v", h) + } +} diff --git a/plugins/apisurface/testdata/README.md b/plugins/apisurface/testdata/README.md new file mode 100644 index 0000000..5392b88 --- /dev/null +++ b/plugins/apisurface/testdata/README.md @@ -0,0 +1,10 @@ +# Saved releases + +The golden file, `golden/openai-1.1.2.json`, is what the kind stores from the 1.1.1 → 1.1.2 pair (`go test ./plugins/apisurface -update`). + +| File | URL | Saved | License | Quote | +|---|---|---|---|---| +| `openai-1.1.1-py3-none-any.trimmed.whl` | https://files.pythonhosted.org/packages/f7/86/ea99e3f966a639a3256e2f79d78cd63d45d5eb651a5457ccbdcfd9eed24a/openai-1.1.1-py3-none-any.whl | 2026-11-20 | Apache-2.0 (openai-python; the wheel's `licenses/LICENSE` is kept in it). Trimmed: only `openai/__init__.py`, `openai/types/__init__.py`, every file under `openai/types/beta/`, and the dist-info `METADATA`, `WHEEL` and `LICENSE`, each copied byte for byte (46 of the wheel's files); the plugin reads the same symbols under `openai.types.beta` from it as from the whole wheel. | `class AsssitantDeleted(BaseModel):` (`openai/types/beta/asssitant_deleted.py`, line 10) | +| `openai-1.1.2-py3-none-any.trimmed.whl` | https://files.pythonhosted.org/packages/dd/82/b92f73453ea318c0d46f31aeb56e9d94a42606c010fb72a513f4a3cd4bac/openai-1.1.2-py3-none-any.whl | 2026-11-20 | The same, trimmed the same way. | `from .assistant_deleted import AssistantDeleted as AssistantDeleted` (`openai/types/beta/__init__.py`) | +| `pypi-openai-excerpt.json` | https://pypi.org/pypi/openai/json | 2026-11-20 | PyPI metadata. Trimmed: `releases` to 1.0.0rc1 (a pre-release, left out) and 1.1.0 to 1.1.2, each file to `filename`, `packagetype`, `upload_time_iso_8601`, `yanked` | | +| `pypi-openai-1.1.1.json`, `pypi-openai-1.1.2.json` | https://pypi.org/pypi/openai/1.1.1/json, …/1.1.2/json | 2026-11-20 | PyPI metadata. Trimmed: `info.name`, `info.version`, and `urls` to `filename`, `packagetype`, `url`, `yanked` | | diff --git a/plugins/apisurface/testdata/golden/openai-1.1.2.json b/plugins/apisurface/testdata/golden/openai-1.1.2.json new file mode 100644 index 0000000..903bdff --- /dev/null +++ b/plugins/apisurface/testdata/golden/openai-1.1.2.json @@ -0,0 +1,50 @@ +[ + { + "id": 0, + "fingerprint": "sha256:9e40f3b8a0940e9ffbdd4aca7642c5bfd240930d6ed176767a90b0a44de567b2", + "api": "openai", + "version": "1.1.2", + "previous_version": "1.1.1", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "package_release", + "ecosystem": "pypi", + "package": "openai", + "change": "removed_symbol", + "symbols": [ + "types.beta.AsssitantDeleted" + ] + }, + "description": "The class `types.beta.AsssitantDeleted` was removed in openai 1.1.2: code using it fails.", + "migration_hint": "openai 1.1.2 has no `types.beta.AsssitantDeleted`: see the package's release notes for what replaces it.", + "source_url": "https://files.pythonhosted.org/packages/dd/82/b92f73453ea318c0d46f31aeb56e9d94a42606c010fb72a513f4a3cd4bac/openai-1.1.2-py3-none-any.whl", + "source_excerpt": "openai 1.1.1 (openai-1.1.1-py3-none-any.whl), openai/types/beta/asssitant_deleted.py line 10: class AsssitantDeleted(BaseModel)\nopenai 1.1.2 (openai-1.1.2-py3-none-any.whl): not defined", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 0, + "fingerprint": "sha256:a709e97cddd82b737c84fe4ec727bc040aff0ece129f5517f30da8925b3fcdd9", + "api": "openai", + "version": "1.1.2", + "previous_version": "1.1.1", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "package_release", + "ecosystem": "pypi", + "package": "openai", + "change": "removed_symbol", + "symbols": [ + "types.beta.asssitant_deleted.AsssitantDeleted" + ] + }, + "description": "The class `types.beta.asssitant_deleted.AsssitantDeleted` was removed in openai 1.1.2: code using it fails.", + "migration_hint": "openai 1.1.2 has no `types.beta.asssitant_deleted.AsssitantDeleted`: see the package's release notes for what replaces it.", + "source_url": "https://files.pythonhosted.org/packages/dd/82/b92f73453ea318c0d46f31aeb56e9d94a42606c010fb72a513f4a3cd4bac/openai-1.1.2-py3-none-any.whl", + "source_excerpt": "openai 1.1.1 (openai-1.1.1-py3-none-any.whl), openai/types/beta/asssitant_deleted.py line 10: class AsssitantDeleted(BaseModel)\nopenai 1.1.2 (openai-1.1.2-py3-none-any.whl): not defined", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + } +] diff --git a/plugins/apisurface/testdata/openai-1.1.1-py3-none-any.trimmed.whl b/plugins/apisurface/testdata/openai-1.1.1-py3-none-any.trimmed.whl new file mode 100644 index 0000000000000000000000000000000000000000..8b93cc652291a0d230b3cb7f6bc8148d6ae43445 GIT binary patch literal 41474 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 literal 0 HcmV?d00001 diff --git a/plugins/apisurface/testdata/openai-1.1.2-py3-none-any.trimmed.whl b/plugins/apisurface/testdata/openai-1.1.2-py3-none-any.trimmed.whl new file mode 100644 index 0000000000000000000000000000000000000000..966486be25e98b2130ade9a58ce86b8b5b2a5f31 GIT binary patch literal 41470 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
    j(3v8EE8nG=* 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 M`2<2+()-{357@r+$^ZZW literal 0 HcmV?d00001 diff --git a/plugins/apisurface/testdata/pypi-openai-1.1.1.json b/plugins/apisurface/testdata/pypi-openai-1.1.1.json new file mode 100644 index 0000000..1647019 --- /dev/null +++ b/plugins/apisurface/testdata/pypi-openai-1.1.1.json @@ -0,0 +1,20 @@ +{ + "info": { + "name": "openai", + "version": "1.1.1" + }, + "urls": [ + { + "filename": "openai-1.1.1-py3-none-any.whl", + "packagetype": "bdist_wheel", + "url": "https://files.pythonhosted.org/packages/f7/86/ea99e3f966a639a3256e2f79d78cd63d45d5eb651a5457ccbdcfd9eed24a/openai-1.1.1-py3-none-any.whl", + "yanked": false + }, + { + "filename": "openai-1.1.1.tar.gz", + "packagetype": "sdist", + "url": "https://files.pythonhosted.org/packages/81/f3/77cea3da9cbee3cfd48ef86158a813ab0da4b1827d66537723f2abfc869c/openai-1.1.1.tar.gz", + "yanked": false + } + ] +} diff --git a/plugins/apisurface/testdata/pypi-openai-1.1.2.json b/plugins/apisurface/testdata/pypi-openai-1.1.2.json new file mode 100644 index 0000000..abeacfc --- /dev/null +++ b/plugins/apisurface/testdata/pypi-openai-1.1.2.json @@ -0,0 +1,20 @@ +{ + "info": { + "name": "openai", + "version": "1.1.2" + }, + "urls": [ + { + "filename": "openai-1.1.2-py3-none-any.whl", + "packagetype": "bdist_wheel", + "url": "https://files.pythonhosted.org/packages/dd/82/b92f73453ea318c0d46f31aeb56e9d94a42606c010fb72a513f4a3cd4bac/openai-1.1.2-py3-none-any.whl", + "yanked": false + }, + { + "filename": "openai-1.1.2.tar.gz", + "packagetype": "sdist", + "url": "https://files.pythonhosted.org/packages/ea/98/ee6972358bb7f3d6e2f1c375e6d7d56bf12d66c6547ec08eb627731f8530/openai-1.1.2.tar.gz", + "yanked": false + } + ] +} diff --git a/plugins/apisurface/testdata/pypi-openai-excerpt.json b/plugins/apisurface/testdata/pypi-openai-excerpt.json new file mode 100644 index 0000000..7b9bef8 --- /dev/null +++ b/plugins/apisurface/testdata/pypi-openai-excerpt.json @@ -0,0 +1,63 @@ +{ + "info": { + "name": "openai" + }, + "releases": { + "1.0.0rc1": [ + { + "filename": "openai-1.0.0rc1-py3-none-any.whl", + "packagetype": "bdist_wheel", + "upload_time_iso_8601": "2023-10-28T04:07:47.330003Z", + "yanked": false + }, + { + "filename": "openai-1.0.0rc1.tar.gz", + "packagetype": "sdist", + "upload_time_iso_8601": "2023-10-28T04:07:57.479454Z", + "yanked": false + } + ], + "1.1.0": [ + { + "filename": "openai-1.1.0-py3-none-any.whl", + "packagetype": "bdist_wheel", + "upload_time_iso_8601": "2023-11-06T20:36:42.478835Z", + "yanked": false + }, + { + "filename": "openai-1.1.0.tar.gz", + "packagetype": "sdist", + "upload_time_iso_8601": "2023-11-06T20:36:45.073097Z", + "yanked": false + } + ], + "1.1.1": [ + { + "filename": "openai-1.1.1-py3-none-any.whl", + "packagetype": "bdist_wheel", + "upload_time_iso_8601": "2023-11-06T22:18:59.867320Z", + "yanked": false + }, + { + "filename": "openai-1.1.1.tar.gz", + "packagetype": "sdist", + "upload_time_iso_8601": "2023-11-06T22:19:04.102221Z", + "yanked": false + } + ], + "1.1.2": [ + { + "filename": "openai-1.1.2-py3-none-any.whl", + "packagetype": "bdist_wheel", + "upload_time_iso_8601": "2023-11-08T18:05:27.665476Z", + "yanked": false + }, + { + "filename": "openai-1.1.2.tar.gz", + "packagetype": "sdist", + "upload_time_iso_8601": "2023-11-08T18:05:30.675572Z", + "yanked": false + } + ] + } +} diff --git a/providers/openai-python-sdk.md b/providers/openai-python-sdk.md new file mode 100644 index 0000000..3083449 --- /dev/null +++ b/providers/openai-python-sdk.md @@ -0,0 +1,32 @@ +# OpenAI Python SDK (`openai`) + +## What it watches + +The public API of the `openai` package on PyPI, release by release: classes, functions and methods removed or renamed, parameters removed, and parameters that lost their default (callers must now pass them). One `package_release` event per change. Every final release is listed from PyPI, and each consecutive pair is compared. + +Kind: `apisurface` (`plugins/apisurface`), with the Python reader (`plugins/apisurface/pysurface`). + +## Why this source + +- **Source:** the release files on PyPI (): each release's wheel, `openai--py3-none-any.whl`, read as published. Checked on 2026-11-20. +- **Why this one:** the wheel is exactly what `pip install openai==` installs, so its public names and signatures are what a customer's code calls. A published file never changes, so its URL is its own citation, and the line quoted is in it. +- **Alternatives considered:** the repo's CHANGELOG.md (generated from commit titles; it says "chore(types): rename" without the old and new names a fix needs); GitHub release notes (the same text); the API's OpenAPI spec (the HTTP API, not the Python names and parameters code uses; the `openai/models` source covers the models). +- **Quote:** `class AsssitantDeleted(BaseModel)`, `openai/types/beta/asssitant_deleted.py` line 10 at 1.1.1, gone at 1.1.2 (renamed `AssistantDeleted`). + +## How the provider announces changes + +- The SDK is generated from OpenAI's API spec and released often (several times a week at times). Type names follow the spec, so a renamed schema renames a class without a deprecation step. +- **Forced on upgrade**, for a repo whose pin reaches the release. + +## What the plugin reads and ignores + +- Reads the `.py` and `.pyi` files under `openai/` as text, never importing or running them: module-level classes and functions, the methods of module-level classes, their parameters and defaults, `__all__`, and an `__init__`'s re-exports. +- Ignores private names (a leading underscore, a module under a private one, a name left out of `__all__`), classes nested in classes, and tests. +- Drops (and logs): an overloaded function's parameters; a removed parameter when the function now takes `**kwargs`; a new parameter without a default (the change-event contract has no subject for it yet). +- A removal is a rename only when the same scope loses one and gains one of the same kind with identical parameters; anything less sure is a removal. + +## Known gaps + +- A class with no `__init__` of its own (the generated pydantic types) has no parameters to compare, so its rename reads as a removal of the old name, and its fields aren't compared. +- Inherited methods aren't followed to the base class. +- Type changes (an annotation narrowed) aren't events. From 00cf5748dd06bcff9ebfcf57e0f575e8eb0845f1 Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 18:26:54 -0500 Subject: [PATCH 2/3] apisurface: no rename on self alone, no removal from a skipped file or a method moved up Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- plugins/apisurface/apisurface.go | 91 +++++++++-- plugins/apisurface/apisurface_test.go | 99 +++++++++++- plugins/apisurface/pysurface/pysurface.go | 147 ++++++++++++++++-- .../apisurface/pysurface/pysurface_test.go | 18 +++ providers/openai-python-sdk.md | 5 +- 5 files changed, 334 insertions(+), 26 deletions(-) diff --git a/plugins/apisurface/apisurface.go b/plugins/apisurface/apisurface.go index b300ebf..66f9114 100644 --- a/plugins/apisurface/apisurface.go +++ b/plugins/apisurface/apisurface.go @@ -109,11 +109,12 @@ func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Vers } } -// snapshot is what ReadAt keeps of a release: its public surface, and -// what couldn't be read. -type snapshot struct { +// Release is what ReadAt keeps of a release: its public surface, the +// classes a method could move to, and what couldn't be read. +type Release struct { Artifact string `json:"artifact"` Surface pysurface.Surface `json:"surface"` + Classes pysurface.Classes `json:"classes,omitempty"` Skipped []string `json:"skipped,omitempty"` // files over the size limit } @@ -140,7 +141,7 @@ func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (p for _, s := range skipped { log.Printf("%s %s: %s skipped: over %d bytes", pkg.Name, v.ID, s, MaxFileBytes) } - content, err := json.Marshal(snapshot{Artifact: a.Filename, Surface: pysurface.Read(files), Skipped: skipped}) + content, err := json.Marshal(Release{Artifact: a.Filename, Surface: pysurface.Read(files), Classes: pysurface.ReadClasses(files), Skipped: skipped}) if err != nil { return plugin.Snapshot{}, err } @@ -155,7 +156,7 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps if from.IsZero() { return plugin.Result{Label: to.Version.ID}, nil } - var a, b snapshot + var a, b Release if err := json.Unmarshal(from.Content, &a); err != nil { return plugin.Result{}, fmt.Errorf("reading the %s %s surface: %w", p.Package.Name, from.Version.ID, err) } @@ -165,7 +166,7 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps now := env.Now().UTC() var events []event.EventV2 var rejected []error - for _, c := range Compare(a.Surface, b.Surface) { + for _, c := range Compare(a, b) { if c.Change == "" { log.Printf("%s %s: not an event: %s", p.Package.Name, to.Version.ID, c.Note) continue @@ -260,9 +261,16 @@ type Change struct { // renamed symbols (a member of a removed class isn't listed again), then // for every symbol in both, removed parameters and parameters that lost // their default. A rename is one removed and one added symbol of the same -// kind under the same parent with the same parameters; anything less sure -// is a removal. -func Compare(a, b pysurface.Surface) []Change { +// kind under the same parent with the same parameters, at least one of +// them besides self or cls; anything less sure is a removal. +// +// What looks removed but may not be is a note, not an event: a symbol +// defined in a file b couldn't read (over the size limit), and a method +// whose class is still there but whose bases changed, which one of its +// bases (or theirs) now defines, or which the class now defines as an +// attribute (create = _create, a property made a plain attribute). +func Compare(ra, rb Release) []Change { + a, b := ra.Surface, rb.Surface var out []Change removed := map[string]bool{} byParent := map[string][2][]string{} // parent+kind -> removed, added @@ -287,7 +295,7 @@ func Compare(a, b pysurface.Surface) []Change { 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 { + if old.Params != nil && !old.Overloaded && !now.Overloaded && slices.Equal(old.Params, now.Params) && len(callerParams(old.Params)) > 0 { renamed[g[0][0]] = g[1][0] } } @@ -297,6 +305,10 @@ func Compare(a, b pysurface.Surface) []Change { continue // its class is reported } before := a[k] + if why := notGone(k, before, ra, rb); why != "" { + out = append(out, Change{Symbol: k, Note: fmt.Sprintf("%s: not in the newer release, but %s", k, why)}) + continue + } c := Change{Change: event.PackageRemovedSymbol, Kind: before.Kind, Symbol: k, Before: &before} if r, ok := renamed[k]; ok { after := b[r] @@ -340,6 +352,65 @@ func Compare(a, b pysurface.Surface) []Change { return out } +// callerParams are the parameters a caller passes: a leading self or cls +// left out. +func callerParams(ps []pysurface.Param) []pysurface.Param { + if len(ps) > 0 && (ps[0].Name == "self" || ps[0].Name == "cls") { + return ps[1:] + } + return ps +} + +// notGone says why symbol k, defined as before in a and missing from b's +// surface, may still be there in b; "" when it's gone. +func notGone(k string, before pysurface.Symbol, a, b Release) string { + if slices.Contains(b.Skipped, before.File) { + return fmt.Sprintf("%s, where it was defined, was too big to read", before.File) + } + if before.Kind != "method" { + return "" + } + cls, ok := b.Surface[parentOf(k)] + if !ok || cls.Kind != "class" { + return "" + } + name := k[strings.LastIndexByte(k, '.')+1:] + oldBases, bases := pysurface.Bases(a.Surface[parentOf(k)].Signature), pysurface.Bases(cls.Signature) + if !slices.Equal(oldBases, bases) { + return fmt.Sprintf("its class's bases changed (%s to %s)", strings.Join(oldBases, ", "), strings.Join(bases, ", ")) + } + if own, ok := b.Classes[className(cls.Signature)]; ok && slices.Contains(own.Members, name) { + return "its class still defines the name (now an attribute)" + } + seen := map[string]bool{} + for len(bases) > 0 { + base := bases[0] + bases = bases[1:] + if seen[base] { + continue + } + seen[base] = true + c, ok := b.Classes[base] + if !ok { + continue // not the package's: unchanged, as the bases are + } + if slices.Contains(c.Members, name) { + return fmt.Sprintf("its base class %s defines it", base) + } + bases = append(bases, c.Bases...) + } + return "" +} + +// className is "Completions" for "class Completions(SyncAPIResource): ...". +func className(signature string) string { + n := strings.TrimPrefix(signature, "class ") + if i := strings.IndexAny(n, "(: "); i >= 0 { + n = n[:i] + } + return n +} + // parentOf is "openai.OpenAI" for "openai.OpenAI.create". func parentOf(sym string) string { if i := strings.LastIndexByte(sym, '.'); i >= 0 { diff --git a/plugins/apisurface/apisurface_test.go b/plugins/apisurface/apisurface_test.go index 5723fa8..eb182ba 100644 --- a/plugins/apisurface/apisurface_test.go +++ b/plugins/apisurface/apisurface_test.go @@ -128,7 +128,7 @@ func TestCompare(t *testing.T) { "acme.Kept.with_kwargs": sym("method", prm("self", "either", ""), prm("kw", "kwargs", "")), } var got []string - for _, c := range Compare(a, b) { + for _, c := range Compare(Release{Surface: a}, Release{Surface: b}) { if c.Change == "" { got = append(got, "note "+c.Symbol) continue @@ -148,6 +148,103 @@ func TestCompare(t *testing.T) { } } +// changes is Compare's output as lines, as TestCompare writes them. +func changes(a, b Release) []string { + var got []string + for _, c := range Compare(a, b) { + if c.Change == "" { + got = append(got, "note "+c.Symbol) + continue + } + got = append(got, string(c.Change)+" "+c.Symbol+" "+c.Parameter+c.Replacement) + } + return got +} + +func cls(sig string, params ...pysurface.Param) pysurface.Symbol { + s := sym("class", params...) + s.Signature = sig + return s +} + +// A method that keeps only self in common with the one added beside it +// isn't a rename: close(self) gone and aclose(self) added is a removal. +func TestSelfAloneIsNoRename(t *testing.T) { + self := prm("self", "either", "") + a := Release{Surface: pysurface.Surface{ + "acme.C": cls("class C:"), + "acme.C.close": sym("method", self), + "acme.C.send": sym("method", self, prm("body", "either", "")), + }} + b := Release{Surface: pysurface.Surface{ + "acme.C": cls("class C:"), + "acme.C.aclose": sym("method", self), + "acme.C.send_v2": sym("method", self, prm("body", "either", "")), + }} + // Two removed, two added: neither pairs one to one, so both are + // removals; then one of each, with a real parameter in common, is a + // rename. + want := "removed_symbol acme.C.close \nremoved_symbol acme.C.send " + if got := strings.Join(changes(a, b), "\n"); got != want { + t.Errorf("got\n%s\nwant\n%s", got, want) + } + delete(a.Surface, "acme.C.close") + delete(b.Surface, "acme.C.aclose") + if got := strings.Join(changes(a, b), "\n"); got != "renamed_symbol acme.C.send acme.C.send_v2" { + t.Errorf("with a real parameter: %s", got) + } + a.Surface = pysurface.Surface{"acme.C": cls("class C:"), "acme.C.close": sym("method", self)} + b.Surface = pysurface.Surface{"acme.C": cls("class C:"), "acme.C.aclose": sym("method", self)} + if got := strings.Join(changes(a, b), "\n"); got != "removed_symbol acme.C.close " { + t.Errorf("self only: %s", got) + } +} + +// A file the newer release couldn't read (over the size limit) is a gap, +// not a removal of everything in it. +func TestASkippedFileRemovesNothing(t *testing.T) { + big := sym("class") + big.File = "acme/big.py" + gone := sym("function") + a := Release{Surface: pysurface.Surface{"acme.Big": big, "acme.big.Big": big, "acme.gone": gone}} + b := Release{Surface: pysurface.Surface{}, Skipped: []string{"acme/big.py"}} + want := "note acme.Big\nnote acme.big.Big\nremoved_symbol acme.gone " + if got := strings.Join(changes(a, b), "\n"); got != want { + t.Errorf("got\n%s\nwant\n%s", got, want) + } +} + +// A method that left its class for a base class, or became an attribute, +// or whose class's bases changed, is still there: a note. One its class +// and bases don't define is gone. +func TestAMethodMovedUpIsNotRemoved(t *testing.T) { + self := prm("self", "either", "") + a := Release{Surface: pysurface.Surface{ + "acme.Completions": cls("class Completions(SyncAPIResource):"), + "acme.Completions.create": sym("method", self), + "acme.Completions.list": sym("method", self), + "acme.Completions.models": sym("method", self), + "acme.Completions.gone": sym("method", self), + "acme.Files": cls("class Files(SyncAPIResource):"), + "acme.Files.upload": sym("method", self), + }} + b := Release{ + Surface: pysurface.Surface{ + "acme.Completions": cls("class Completions(SyncAPIResource):"), + "acme.Files": cls("class Files(SyncAPIResource, _Uploads):"), + }, + Classes: pysurface.Classes{ + "Completions": {Bases: []string{"SyncAPIResource"}, Members: []string{"models"}}, + "SyncAPIResource": {Bases: []string{"_Base"}, Members: []string{"create"}}, + "_Base": {Members: []string{"list"}}, + }, + } + want := "note acme.Completions.create\nremoved_symbol acme.Completions.gone \nnote acme.Completions.list\nnote acme.Completions.models\nnote acme.Files.upload" + if got := strings.Join(changes(a, b), "\n"); got != want { + t.Errorf("got\n%s\nwant\n%s", got, want) + } +} + // An archive is read, never unpacked or run: paths outside the package, a // path climbing out, and an oversized file are left out. func TestSourceFilesStayInThePackage(t *testing.T) { diff --git a/plugins/apisurface/pysurface/pysurface.go b/plugins/apisurface/pysurface/pysurface.go index 9a84a43..e934db5 100644 --- a/plugins/apisurface/pysurface/pysurface.go +++ b/plugins/apisurface/pysurface/pysurface.go @@ -43,6 +43,22 @@ type File struct { Text string } +// Class is what one class's body defines, for following a method that left +// a class: its bases as written (the last part of a dotted name, without +// [...]: "SyncAPIResource", "Generic"), and every name its body defines (defs +// of any name, nested classes, attributes assigned or annotated). +type Class struct { + Bases []string `json:"bases,omitempty"` + Members []string `json:"members,omitempty"` +} + +// Classes are the classes a method could have moved to, by name: every +// module-level class in the package (private modules and names included) +// that another class names as a base. Classes of the same name in two +// modules are merged (their members together), which can only make a +// moved method more likely to be found, never less. +type Classes map[string]Class + // module is one file read: its own definitions and how it re-exports others. type module struct { name string // "openai.types.chat" @@ -53,6 +69,7 @@ type module struct { hasAll bool imports map[string][2]string // local name -> {module, name} from "from M import name as local" stars []string // modules of "from M import *" + classes map[string]*Class // module-level classes by name } var ( @@ -63,6 +80,8 @@ var ( strLit = regexp.MustCompile(`^[rRuU]?(?:"([^"\\]*)"|'([^'\\]*)')$`) name = regexp.MustCompile(`^[A-Za-z_]\w*$`) spaces = regexp.MustCompile(`\s+`) + attrLine = regexp.MustCompile(`^([A-Za-z_]\w*)\s*(?::|=[^=])`) + keywords = map[string]bool{"else": true, "try": true, "finally": true, "except": true, "elif": true, "if": true, "while": true, "for": true, "with": true, "match": true, "case": true} ) // Read is the public surface of the package whose files these are. A module @@ -73,6 +92,99 @@ var ( // one (re-exports included, in any module). A .pyi stub next to a // .py file is read instead of it. func Read(files []File) Surface { + mods := parseAll(files) + out := Surface{} + for _, m := range mods { + if private(m.name) { + continue + } + for _, n := range m.public(mods) { + for k, s := range resolve(mods, m, n, 0) { + out[m.name+"."+k] = s + } + } + } + return out +} + +// ReadClasses is the package's Classes: every module-level class named as +// another class's base. +func ReadClasses(files []File) Classes { + all := map[string]*Class{} + for _, m := range parseAll(files) { + for n, c := range m.classes { + have := all[n] + if have == nil { + have = &Class{} + all[n] = have + } + have.Bases = appendNew(have.Bases, c.Bases...) + have.Members = appendNew(have.Members, c.Members...) + } + } + named := map[string]bool{} + for _, c := range all { + for _, b := range c.Bases { + named[b] = true + } + } + out := Classes{} + for n, c := range all { + if named[n] { + slices.Sort(c.Bases) + slices.Sort(c.Members) + out[n] = *c + } + } + return out +} + +// appendNew appends the names list doesn't have yet. +func appendNew(list []string, names ...string) []string { + for _, n := range names { + if !slices.Contains(list, n) { + list = append(list, n) + } + } + return list +} + +// Bases are a class's bases as written in its signature ("class X(a.B[T], +// C, metaclass=M):" is B, C): the last part of each dotted name, without +// [...]; keyword arguments left out. +func Bases(signature string) []string { + sig, _, _ := strings.Cut(signature, " / ") // a class's __init__ follows + if !strings.HasPrefix(sig, "class ") { + return nil + } + open := strings.IndexByte(sig, '(') + if open < 0 { + return nil + } + end := closing(sig, open) + if end < 0 { + return nil + } + var out []string + for _, raw := range splitTop(sig[open+1:end], ',') { + b := strings.TrimSpace(raw) + if b == "" || indexTop(b, '=') >= 0 { + continue + } + if i := strings.IndexByte(b, '['); i >= 0 { + b = b[:i] + } + b = strings.TrimSpace(b[strings.LastIndexByte(b, '.')+1:]) + if b != "" { + out = append(out, b) + } + } + return out +} + +// parseAll parses every .py and .pyi file, by module name; a .pyi stub next +// to a .py file is read instead of it. +func parseAll(files []File) map[string]*module { byPath := map[string]File{} for _, f := range files { byPath[f.Path] = f @@ -90,18 +202,7 @@ func Read(files []File) Surface { m := parse(f) mods[m.name] = m } - out := Surface{} - for _, m := range mods { - if private(m.name) { - continue - } - for _, n := range m.public(mods) { - for k, s := range resolve(mods, m, n, 0) { - out[m.name+"."+k] = s - } - } - } - return out + return mods } // moduleName is "openai.types.chat" for "openai/types/chat/__init__.py". @@ -222,7 +323,7 @@ type block struct { // parse reads one file's definitions, __all__ and imports. func parse(f File) *module { - m := &module{name: moduleName(f.Path), file: f.Path, defs: map[string]Symbol{}, imports: map[string][2]string{}} + m := &module{name: moduleName(f.Path), file: f.Path, defs: map[string]Symbol{}, imports: map[string][2]string{}, classes: map[string]*Class{}} var stack []block var decorators []string for _, l := range logicalLines(f.Text) { @@ -243,6 +344,22 @@ func parse(f File) *module { nested := strings.Count(parent, ".") > 0 // a class inside a class: not read t := l.text opens := strings.HasSuffix(t, ":") + if c := m.classes[parent]; c != nil && !inDef { + // A name the class body defines: a def, a nested class, an + // attribute. + var n string + switch { + case defLine.MatchString(t): + n = defLine.FindStringSubmatch(t)[1] + case classLine.MatchString(t): + n = classLine.FindStringSubmatch(t)[1] + case attrLine.MatchString(t) && !keywords[attrLine.FindStringSubmatch(t)[1]]: + n = attrLine.FindStringSubmatch(t)[1] + } + if n != "" { + c.Members = appendNew(c.Members, n) + } + } switch { case strings.HasPrefix(t, "@"): decorators = append(decorators, strings.TrimSpace(t[1:])) @@ -266,6 +383,10 @@ func parse(f File) *module { if !inDef && parent == "" { m.defs[path] = Symbol{Kind: "class", File: f.Path, Line: l.num, Signature: header(t)} m.order = append(m.order, path) + if m.classes[path] == nil { + m.classes[path] = &Class{} + } + m.classes[path].Bases = appendNew(m.classes[path].Bases, Bases(header(t))...) } kind := "class" if inDef { diff --git a/plugins/apisurface/pysurface/pysurface_test.go b/plugins/apisurface/pysurface/pysurface_test.go index b8402ca..168e80a 100644 --- a/plugins/apisurface/pysurface/pysurface_test.go +++ b/plugins/apisurface/pysurface/pysurface_test.go @@ -2,6 +2,7 @@ package pysurface import ( "encoding/json" + "strings" "testing" ) @@ -115,3 +116,20 @@ func TestRead(t *testing.T) { t.Errorf("helper: %+v", h) } } + +// The class index: classes named as a base, with their bases and every name +// their bodies define; private modules and names included. +func TestReadClasses(t *testing.T) { + c := ReadClasses([]File{ + {"acme/_resource.py", "class _Base:\n def list(self): pass\n\nclass SyncAPIResource(_Base, Generic[T], metaclass=M):\n _client: Client\n create = _create\n if TYPE_CHECKING:\n def _hidden(self): pass\n else:\n pass\n def _create(self, x):\n y = 1\n return y\n"}, + {"acme/completions.py", "from ._resource import SyncAPIResource\n\nclass Completions(base.SyncAPIResource):\n pass\n"}, + }) + got, _ := json.Marshal(c) + want := `{"SyncAPIResource":{"bases":["Generic","_Base"],"members":["_client","_create","_hidden","create"]},"_Base":{"members":["list"]}}` + if string(got) != want { + t.Errorf("got %s\nwant %s", got, want) + } + if b := Bases("class X(a.B[T], C, metaclass=M): / def __init__(self, a=(1, 2))"); strings.Join(b, ",") != "B,C" { + t.Errorf("bases %v", b) + } +} diff --git a/providers/openai-python-sdk.md b/providers/openai-python-sdk.md index 3083449..d99a51c 100644 --- a/providers/openai-python-sdk.md +++ b/providers/openai-python-sdk.md @@ -23,10 +23,11 @@ Kind: `apisurface` (`plugins/apisurface`), with the Python reader (`plugins/apis - Reads the `.py` and `.pyi` files under `openai/` as text, never importing or running them: module-level classes and functions, the methods of module-level classes, their parameters and defaults, `__all__`, and an `__init__`'s re-exports. - Ignores private names (a leading underscore, a module under a private one, a name left out of `__all__`), classes nested in classes, and tests. - Drops (and logs): an overloaded function's parameters; a removed parameter when the function now takes `**kwargs`; a new parameter without a default (the change-event contract has no subject for it yet). -- A removal is a rename only when the same scope loses one and gains one of the same kind with identical parameters; anything less sure is a removal. +- A removal is a rename only when the same scope loses one and gains one of the same kind with identical parameters, at least one of them besides `self`/`cls`; anything less sure is a removal. +- Drops (and logs) a removal that may not be one: a symbol whose file the newer release has too big to read (`MaxFileBytes`); a method whose class is still there but whose bases changed, which one of its bases (followed through the package's own classes, private ones included) now defines, or which the class now defines as an attribute (`create = _create`, a property made a plain attribute). ## Known gaps - A class with no `__init__` of its own (the generated pydantic types) has no parameters to compare, so its rename reads as a removal of the old name, and its fields aren't compared. -- Inherited methods aren't followed to the base class. +- A method moved to a base class from outside the package (a dependency's class) is still read as removed when the bases themselves didn't change: the dependency's code isn't read. - Type changes (an annotation narrowed) aren't events. From f901430668680e3cd038dbff64f3651e2c06715c Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 19:11:45 -0500 Subject: [PATCH 3/3] apisurface: index every class, so a leaf class's new attribute is found Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- plugins/apisurface/apisurface_test.go | 37 ++++++++----------- plugins/apisurface/pysurface/pysurface.go | 27 +++++--------- .../apisurface/pysurface/pysurface_test.go | 8 ++-- 3 files changed, 29 insertions(+), 43 deletions(-) diff --git a/plugins/apisurface/apisurface_test.go b/plugins/apisurface/apisurface_test.go index eb182ba..c2a390f 100644 --- a/plugins/apisurface/apisurface_test.go +++ b/plugins/apisurface/apisurface_test.go @@ -216,29 +216,24 @@ func TestASkippedFileRemovesNothing(t *testing.T) { // A method that left its class for a base class, or became an attribute, // or whose class's bases changed, is still there: a note. One its class -// and bases don't define is gone. +// and bases don't define is gone. The two releases are read by the real +// reader, the leaf class included. func TestAMethodMovedUpIsNotRemoved(t *testing.T) { - self := prm("self", "either", "") - a := Release{Surface: pysurface.Surface{ - "acme.Completions": cls("class Completions(SyncAPIResource):"), - "acme.Completions.create": sym("method", self), - "acme.Completions.list": sym("method", self), - "acme.Completions.models": sym("method", self), - "acme.Completions.gone": sym("method", self), - "acme.Files": cls("class Files(SyncAPIResource):"), - "acme.Files.upload": sym("method", self), - }} - b := Release{ - Surface: pysurface.Surface{ - "acme.Completions": cls("class Completions(SyncAPIResource):"), - "acme.Files": cls("class Files(SyncAPIResource, _Uploads):"), - }, - Classes: pysurface.Classes{ - "Completions": {Bases: []string{"SyncAPIResource"}, Members: []string{"models"}}, - "SyncAPIResource": {Bases: []string{"_Base"}, Members: []string{"create"}}, - "_Base": {Members: []string{"list"}}, - }, + read := func(files map[string]string) Release { + var fs []pysurface.File + for p, text := range files { + fs = append(fs, pysurface.File{Path: p, Text: text}) + } + return Release{Surface: pysurface.Read(fs), Classes: pysurface.ReadClasses(fs)} } + a := read(map[string]string{ + "acme/_base.py": "class _Base:\n pass\n\nclass SyncAPIResource(_Base):\n pass\n", + "acme/__init__.py": "from ._base import SyncAPIResource\n\nclass Completions(SyncAPIResource):\n def create(self, a):\n pass\n def list(self):\n pass\n def models(self):\n pass\n def gone(self):\n pass\n\nclass Files(SyncAPIResource):\n def upload(self, f):\n pass\n", + }) + b := read(map[string]string{ + "acme/_base.py": "class _Base:\n def list(self):\n pass\n\nclass SyncAPIResource(_Base):\n def create(self, a):\n pass\n", + "acme/__init__.py": "from ._base import SyncAPIResource\n\nclass Completions(SyncAPIResource):\n models = _models\n\nclass Files(SyncAPIResource, _Uploads):\n pass\n", + }) want := "note acme.Completions.create\nremoved_symbol acme.Completions.gone \nnote acme.Completions.list\nnote acme.Completions.models\nnote acme.Files.upload" if got := strings.Join(changes(a, b), "\n"); got != want { t.Errorf("got\n%s\nwant\n%s", got, want) diff --git a/plugins/apisurface/pysurface/pysurface.go b/plugins/apisurface/pysurface/pysurface.go index e934db5..61ee7ee 100644 --- a/plugins/apisurface/pysurface/pysurface.go +++ b/plugins/apisurface/pysurface/pysurface.go @@ -52,11 +52,11 @@ type Class struct { Members []string `json:"members,omitempty"` } -// Classes are the classes a method could have moved to, by name: every -// module-level class in the package (private modules and names included) -// that another class names as a base. Classes of the same name in two -// modules are merged (their members together), which can only make a -// moved method more likely to be found, never less. +// Classes are the package's module-level classes by name (private modules +// and names included): where a method that left a class may still be, in +// the class itself (now an attribute) or in a base. Classes of the same +// name in two modules are merged (their members together), which can only +// make a moved method more likely to be found, never less. type Classes map[string]Class // module is one file read: its own definitions and how it re-exports others. @@ -107,8 +107,7 @@ func Read(files []File) Surface { return out } -// ReadClasses is the package's Classes: every module-level class named as -// another class's base. +// ReadClasses is the package's Classes: every module-level class. func ReadClasses(files []File) Classes { all := map[string]*Class{} for _, m := range parseAll(files) { @@ -122,19 +121,11 @@ func ReadClasses(files []File) Classes { have.Members = appendNew(have.Members, c.Members...) } } - named := map[string]bool{} - for _, c := range all { - for _, b := range c.Bases { - named[b] = true - } - } out := Classes{} for n, c := range all { - if named[n] { - slices.Sort(c.Bases) - slices.Sort(c.Members) - out[n] = *c - } + slices.Sort(c.Bases) + slices.Sort(c.Members) + out[n] = *c } return out } diff --git a/plugins/apisurface/pysurface/pysurface_test.go b/plugins/apisurface/pysurface/pysurface_test.go index 168e80a..880b5cd 100644 --- a/plugins/apisurface/pysurface/pysurface_test.go +++ b/plugins/apisurface/pysurface/pysurface_test.go @@ -117,15 +117,15 @@ func TestRead(t *testing.T) { } } -// The class index: classes named as a base, with their bases and every name -// their bodies define; private modules and names included. +// The class index: every module-level class, with its bases and every name +// its body defines; private modules and names included. func TestReadClasses(t *testing.T) { c := ReadClasses([]File{ {"acme/_resource.py", "class _Base:\n def list(self): pass\n\nclass SyncAPIResource(_Base, Generic[T], metaclass=M):\n _client: Client\n create = _create\n if TYPE_CHECKING:\n def _hidden(self): pass\n else:\n pass\n def _create(self, x):\n y = 1\n return y\n"}, - {"acme/completions.py", "from ._resource import SyncAPIResource\n\nclass Completions(base.SyncAPIResource):\n pass\n"}, + {"acme/completions.py", "from ._resource import SyncAPIResource\n\nclass Completions(base.SyncAPIResource):\n models = _models\n"}, }) got, _ := json.Marshal(c) - want := `{"SyncAPIResource":{"bases":["Generic","_Base"],"members":["_client","_create","_hidden","create"]},"_Base":{"members":["list"]}}` + want := `{"Completions":{"bases":["SyncAPIResource"],"members":["models"]},"SyncAPIResource":{"bases":["Generic","_Base"],"members":["_client","_create","_hidden","create"]},"_Base":{"members":["list"]}}` if string(got) != want { t.Errorf("got %s\nwant %s", got, want) }