0.16 namespace-package split causes ~2x pyright memory

[sirianni]

Note

AI-assisted bug report, reviewed by me

Summary

Since the schema split in 0.16.0, type-checking a project that imports githubkit schemas costs ~2× the memory and ~16× the import-resolution time compared to 0.15.x. The cause is that githubkit_schemas ships as a PEP 420 namespace package (no __init__.py). Adding a single __init__.py fully restores the old behavior.

Measurements

Same project, same basedpyright 1.29.5 (pyright 1.1.402), only the githubkit version differs:

githubkit	Resolve Imports	pyright peak RSS
0.15.2	0.51 s	1.50 GB
0.16.0	8.17 s	3.16 GB

Total files parsed and bound is nearly identical (5467 vs 5605) and files checked is identical (532) — the regression is entirely in import resolution, not in how much code is analyzed.

Root cause

githubkit_schemas has no top-level __init__.py, so it's an implicit namespace package. For namespace packages, the import resolver cannot short-circuit on first match — it must scan every entry on the search path to assemble the package (vs. a regular package, which resolves immediately once found).

Adding one empty __init__.py to the installed githubkit_schemas/ and re-running pyright reverts both metrics to 0.15 levels:

githubkit_schemas	Resolve Imports	pyright peak RSS
namespace package (default)	8.17 s	3.16 GB
+ __init__.py (regular package)	0.54 s	1.60 GB

Proposed fix

Ship an __init__.py in the githubkit_schemas package(s) so it's a regular package rather than an implicit namespace package.

Relationship to #312

This shares the same root cause as #312 (githubkit_schemas being a namespace package with no __init__.py): there it means the lazy-import hook isn't bootstrapped unless githubkit is imported first; here it means type checkers pay a large namespace-resolution penalty. A real __init__.py would address both — it could both install the lazy hook and make the package non-namespace.

[sirianni]

Note (commenting on behalf of @sirianni): adding context after digging into #296 — the namespace-package layout looks intentional, so the fix here is likely more involved than "just add an __init__.py".

Per the discussion in #296, the schema split was chosen specifically to make API versions independently installable via extras (githubkit-schemas[all-schemas], etc.). The installed layout reflects this: the githubkit-schemas core distribution ships githubkit_schemas/{core,latest}, while each version (e.g. githubkit-schemas-2026-03-10) is a separate wheel shipping githubkit_schemas/v2026_03_10. Multiple independent distributions overlaying one import namespace is exactly what PEP 420 namespace packages are for, so dropping a single __init__.py into githubkit_schemas/ would conflict with that multi-distribution design.

So this is a real tradeoff of the split rather than a simple oversight. A fix would need to preserve independent version installation — e.g. having only the always-present core distribution own the __init__.py (if that's compatible with how the version sub-packages are laid out), or another packaging-level approach. Sharing in case it informs the right fix; the namespace-resolution cost itself (the ~2x pyright memory / OOM) reproduces regardless.

[yanyongyu]

I’m not entirely sure why pyright sees such a large performance regression here, though I have also observed the increased memory usage.

githubkit_schemas is indeed intentionally shipped as a namespace package, so adding an __init__.py is unfortunately not an option at the moment.

I’m not sure whether there is a better fix for this yet, but I’ll keep looking into possible alternatives.

[sirianni]

I'm not too familiar with how namespace packages work and how you're splitting things out. But is there a workaround that we can "op in" to if we don't care about the discovery? Like importing a specific hardcoded version of the schemas?

[yanyongyu]

It seems there’s no available pyright configuration to resolve this issue, so we’ll likely need to get help from pyright.

[yanyongyu]

I’ve started a discussion about this in the Pyright repository: microsoft/pyright#11540