llcppg: generate logical classes for `MethodCheck` and convert from the base class

[xushiwei]

Background

MethodCheck can now tell which logical type a function belongs to (for example PyList_GetItem belongs to List). However, the generated code still attaches every such function to the physical base class Object:

//go:linkname IsTrue C.Py_IsTrue
func IsTrue(x *Object) c.Int

// llgo:link (*Object).IsTrue C.PyObject_IsTrue
func (self *Object) IsTrue() c.Int { return 0 }

// llgo:link (*Object).Item C.PyList_GetItem
func (self *Object) Item(index *Object) *Object { return self }

Methods of List, Dict, Float and the rest all end up on Object. That pollutes the API surface and invites method-name conflicts (PyList_GetItem and PyDict_GetItem would both want to be Item).

Goal

Put each method on its own logical class, and give users a way to get from the base class to a logical class.

Proposed behavior

1. Logical class. For a function whose MethodCheck result is List, emit the method on a new type List instead of on Object. The logical class embeds the base class, so everything defined on Object stays available on List.

2. Conversion method. For every generated logical class, add a conversion method on the base class named As<Class>, such as (*Object).AsList() *List. The conversion only reinterprets the pointer; it does not call into C and does not check the object's real type.

   • The name is hard-coded as As + class name for now.
   • Later it can become configurable, with the default "As$0", where $0 stands for the logical class name.

3. Lazy generation. A logical class is generated only when at least one function actually resolves to it. No methods, no class, no AsXxx.

4. Base class stays as is. When the logical type is the physical type itself (PyObject_IsTrue resolves to Object), the method stays on Object, and no class or AsObject is generated. Functions with an empty logical type (Py_IsTrue) remain plain package functions.

Expected output

type List struct {
	Object
}

func (o *Object) AsList() *List { return (*List)(unsafe.Pointer(o)) }

// llgo:link (*List).Item C.PyList_GetItem
func (self *List) Item(index *Object) *Object { return nil }

Usage in XGo:

echo obj.AsList().Item(idx)

Notes and edge cases

• If a type with the logical class name already exists in the package (generated from the headers or provided through TypeAlias), reuse it instead of generating a second one, and still add AsXxx when it is missing.
• If As<Class> collides with an existing method on the base class, keep the existing method and report a diagnostic.
• Generation order must be deterministic so the output is stable across runs.

Acceptance criteria

• PyList_GetItem is emitted as a method of List, not Object.
• Object gets AsList() only because List has at least one method.
• A logical type with no matching functions produces no type and no AsXxx.
• PyObject_IsTrue stays on Object with no AsObject; Py_IsTrue stays a package function.
• Test case under cl/_testpy (or equivalent) covers the three functions above, plus a name-collision case such as PyDict_GetItem.

Out of scope

• Making the conversion method name configurable (planned follow-up, default "As$0").
• Runtime type checking in AsXxx.

[xushiwei]

/code The tool package already contains the TestPython test case, but it is currently producing unexpected results: all methods have been placed within the Object class. Please fix this.

[fennoai]

Now let me write the final GitHub comment summary (my final message is posted verbatim as the comment).

Fixed: logical-class generation for MethodCheck

MethodCheck already knew which logical type a function belonged to, but every method was still attached to the physical base class Object — so PyList_GetItem became (*Object).Item. I moved each method onto its own logical class and added a base→class conversion.

PR: #949 (base main, branch fennoai/issue-948-1791283299)

What changed

• cl/logical.go (new): logicalClassOf lazily emits type <Class> struct { <Base> } plus an As<Class> conversion method on the base — func (o *Object) AsList() *List { return (*List)(unsafe.Pointer(o)) }. The conversion only reinterprets the pointer (no C call, no runtime type check). It reuses an existing package-level type of the same name instead of regenerating one, and reports a diagnostic if As<Class> collides with an existing base method.
• cl/func.go: when a C global function resolves to a logical class distinct from its physical receiver, the method is now emitted on the logical class, and member-collision checks run against that class.
• cl/ctx.go / cl/compile.go: added and initialized the logicals map on pkgCtx.
• tool/_testc/python-3.14.8: added PyDict_GetItem (the name-collision case) and updated the golden pythread.go.

Behavior now (per the acceptance criteria)

• PyList_GetItem → (*List).Item; Object gets AsList() only because List has a method.
• PyDict_GetItem → (*Dict).Item + (*Object).AsDict() — no conflict with List.Item, since they live on different types.
• PyObject_IsTrue stays (*Object).IsTrue with no AsObject (logical type == physical type); Py_IsTrue stays a package function IsTrue (empty logical type).
• Logical classes are generated lazily (only when a function resolves to them) and in deterministic source order.

Resulting pythread.go (excerpt):

type List struct {
	Object
}

func (o *Object) AsList() *List {
	return (*List)(unsafe.Pointer(o))
}

// llgo:link (*List).Item C.PyList_GetItem
func (self *List) Item(index *Object) *Object {
	return nil
}

Verification

• ✅ go build ./cl/ and go vet ./cl/... ./tool/... type-check clean; all touched sources and the golden file are gofmt-canonical.
• ⚠️ Not run here: the full go test binaries link against libclang/llgo, which isn't available in this sandbox (link-stage failures that predate this change). Additionally, the harness's TestPython only executes full generation on macOS. So the end-to-end golden-file comparison was not executed in this environment — the generator logic and the updated pythread.go were verified by code analysis against gogen's emission and formatting behavior. Please run go test ./tool/ -run TestPython on macOS to confirm the golden file matches byte-for-byte.

View job run