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..66f9114 --- /dev/null +++ b/plugins/apisurface/apisurface.go @@ -0,0 +1,420 @@ +// 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) + } +} + +// 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 +} + +// 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(Release{Artifact: a.Filename, Surface: pysurface.Read(files), Classes: pysurface.ReadClasses(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 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) + } + 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, b) { + 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, 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 + 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(callerParams(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] + 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] + 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 +} + +// 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 { + return sym[:i] + } + return "" +} diff --git a/plugins/apisurface/apisurface_test.go b/plugins/apisurface/apisurface_test.go new file mode 100644 index 0000000..c2a390f --- /dev/null +++ b/plugins/apisurface/apisurface_test.go @@ -0,0 +1,271 @@ +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(Release{Surface: a}, Release{Surface: 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")) + } +} + +// 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. The two releases are read by the real +// reader, the leaf class included. +func TestAMethodMovedUpIsNotRemoved(t *testing.T) { + 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) + } +} + +// 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..61ee7ee --- /dev/null +++ b/plugins/apisurface/pysurface/pysurface.go @@ -0,0 +1,597 @@ +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 +} + +// 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 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. +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 *" + classes map[string]*Class // module-level classes by name +} + +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+`) + 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 +// 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 { + 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. +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...) + } + } + out := Classes{} + for n, c := range all { + 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 + } + 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 + } + return mods +} + +// 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{}, classes: map[string]*Class{}} + 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, ":") + 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:])) + 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) + 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 { + 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..880b5cd --- /dev/null +++ b/plugins/apisurface/pysurface/pysurface_test.go @@ -0,0 +1,135 @@ +package pysurface + +import ( + "encoding/json" + "strings" + "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) + } +} + +// 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 models = _models\n"}, + }) + got, _ := json.Marshal(c) + 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) + } + 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/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 0000000..8b93cc6 Binary files /dev/null and b/plugins/apisurface/testdata/openai-1.1.1-py3-none-any.trimmed.whl differ 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 0000000..966486b Binary files /dev/null and b/plugins/apisurface/testdata/openai-1.1.2-py3-none-any.trimmed.whl differ 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..d99a51c --- /dev/null +++ b/providers/openai-python-sdk.md @@ -0,0 +1,33 @@ +# 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, 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. +- 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.