Repository navigation
Description
We encountered this issue while migrating cuda-core from stubgen-pyx 0.2.6 to 0.2.19.
An LLM-generated summary is below:
Summary
When stubgen-pyx encounters a module-level assignment whose RHS is a
function/attribute call (e.g. X = namedtuple("X", (...)), X = int(some_c_enum)),
it strips the assignment out of the generated .pyi entirely
(strip_artifacts.py::_is_runtime_assignment), even for public names and even
with --include-private. This has three compounding, user-visible effects:
- Public names silently disappear from the stub. If another module does
from pkg.repro import Point, the generated stub for the importing module
still emits that import, butPointis simply gone fromrepro.pyi-- the
import now points at nothing, which mypy flags as an import error. - Dangling references in other, still-emitted assignments. If a dropped
name is referenced inside a dict/list/tuple literal that itself survives
(because such literals aren't classified as "runtime assignments"), the
literal is copied into the stub verbatim, including the now-undefined name.
mypy then reports "Name is not defined". - Invalid
...annotations for TypedDict-style struct fields. Separately
(but for a related reason -- an annotation referencing a name that's absent
from the stub, here a C function-pointerctypedeffrom acdef extern
block),trim_not_defined.pyreplaces the undefined annotation with a bare
ast.Constant(...)rather thanAny.strip_artifacts.py's own
_AnnotationRewriterusesAnyfor the equivalent case just a few frames
away in the same pipeline, so the two undefined-name-repair passes disagree,
and the...-annotation is invalid Python typing syntax outside of a
Callable[..., X]/tuple context -- mypy rejects it with
error: Unexpected "..." [misc].
Minimal repro
pkg/repro.pyx:
from collections import namedtuple
# (1) Public, Call-valued module assignment: silently dropped from the stub,
# even though it's part of the module's public surface.
Point = namedtuple("Point", ("x", "y"))
# (2) Private, Call-valued module assignment: also dropped ...
_UNIT = int(1)
# ... but this dict literal (kept verbatim, since dict literals aren't
# "runtime assignments") still references it, leaving a dangling name.
LOOKUP = {"a": _UNIT}
cdef extern from "repro.h":
ctypedef int (*Callback)(int)
ctypedef struct Foo:
Callback cb$ stubgen-pyx pkg --continue-on-error --include-private
2026-08-17 11:17:22,130 - INFO - stubgen-pyx v0.2.19
2026-08-17 11:17:22,286 - WARNING - Replaced undefined name 'Callback' with '...'
2026-08-17 11:17:22,290 - INFO - Successfully converted 1 file(s)
pkg/repro.pyi (generated):
# This file was generated by stubgen-pyx v0.2.19 from pkg/repro.pyx
from typing import TypedDict
LOOKUP = {'a': _UNIT}
class Foo(TypedDict):
cb: ...Note:
Pointis entirely absent (no trace at all) -- any downstream module doing
from pkg.repro import Pointnow gets a broken stub-only import.LOOKUPsurvived, but_UNIT(referenced inside it) did not --_UNITis
undefined in the stub, somypyreports
error: Name "_UNIT" is not defined [name-defined].Foo.cb: ...is not valid as a plain annotation --mypyreports
error: Unexpected "..." [misc].
Versions: stubgen-pyx 0.2.19, Cython 3.2.9, Python 3.14, mypy 1.20.0.
Where this comes from
conversion/strip_artifacts.py::_is_runtime_assignmenttreats any
module-levelast.Assignwhose value is anast.Callorast.Attribute
(and isn't aTypeVar(...)call) as removable "runtime-only" state, via
_keep_node. This runs regardless of whether the target name is public,
and regardless of--include-private.- Other module-level statements (e.g. dict/list/tuple literals) that
reference a name removed this way are not rewritten -- only
ast.Name/ast.Attributenodes that occur in annotation positions get
swept up by_AnnotationRewriter(which correctly substitutesAny).
PlainAssignvalues are never passed through that rewriter, so dangling
references in kept literals are left untouched. - Separately,
conversion/trim_not_defined.py::_NotDefinedRemoverruns
earlier(?) in the pipeline and also repairs "undefined name in annotation"
situations, but substitutesast.Constant(...)(bareEllipsis) instead of
Any. This is inconsistent withstrip_artifacts.py's own repair (Any)
and produces syntactically-invalid-for-mypy annotations whenever the
undefined name occurs as a bare field/variable annotation rather than inside
aCallable[...].
Suggested fixes
- In
_is_runtime_assignment, don't dropAssignnodes whose target is
referenced elsewhere in the kept AST (or, more simply, don't drop
Assignnodes at all when their target name is used by any other kept
statement -- compute this after the initial pass, similar to how
strip_artifacts.pyalready tracksdefined). - At minimum, when a
Call/Attribute-valued assignment is dropped, also
rewrite (or drop) any surviving statement that references the removed
name, the same way_AnnotationRewriterdoes for annotations. - Make
trim_not_defined.py's undefined-name substitution useAny(like
strip_artifacts.pydoes) instead of bareast.Constant(...), at least
forAnnAssign/annotation contexts outside ofCallable[...]....is
only valid as a type-expression fragment insideCallable[..., X],
tuple[X, ...], etc. -- never as the entire annotation.
Impact
We hit all three of these while working through the .pyi output for a
larger Cython package (cuda_core in NVIDIA/cuda-python) migrating from
stubgen-pyx 0.2.6 -> 0.2.19. We were able to work around (1) and (2) locally
by adding explicit type annotations (turning Assign into AnnAssign, which
_is_runtime_assignment doesn't touch), but that's not viable for (3) -- the
struct fields have named C function-pointer ctypedefs that have no
reasonable Python-level annotation we can add ourselves.
Activity
jon-edward commentedon Aug 18, 2026
strip_artifactspostprocessing pass definitely needs to be reworked, thank you for reporting this. I’ll work on fixing the behaviorjon-edward commentedon Aug 18, 2026
I think the
c?import cython/cpython.*(andfrom) should probably be discarded through thestubgen_pyx.conversion.Converterby something similar to_is_cxx_importThen, we can remove the
strip_artifactsstep completely and maketrim_not_definedmore robust toAnyover...and undefined decorator deletion. I really don't like dangling names being handled independently by two steps as it introduces conflicting behaviorI’ll work on this over the next couple days (work is pretty busy these days, sorry!), just wanted to get my thoughts out there
jon-edward commentedon Aug 21, 2026
@mdboom This should be fixed with v0.2.20, and now produces the following output for your sample:
Would you mind verifying that all is good for the cuda-core usage and closing if satisfactory? I opted for
_typeshed.Incompleteovertyping.Anyto distinguish between the two cases for thetrim_not_definedpassmdboom commentedon Aug 25, 2026
I think this issue can be closed. I ran into a different issue upgrading to
v0.2.20, reported in #69.