Drop the sillo.graphql alias; sillo_graphql is the import path - #1
Merged
Merged
Conversation
The package shipped under two names. `sillo_graphql` is where the code
lives; `sillo.graphql` was an alias so an import could read as part of
the framework, built from a meta-path finder in
`_sillo_graphql_bootstrap.py`, a `sillo_graphql.pth` registering it at
interpreter startup, and PEP 561 stubs in `sillo-stubs/` because static
analysis never runs import hooks.
That is three mechanisms, a `.pth` executing on every interpreter start
in every environment the package is installed in, and a second set of
type declarations to keep in step with the real ones. A plain top-level
package needs none of it.
Adds `sillo_graphql/py.typed`, which was missing. The package claimed
`Typing :: Typed` but delivered types only through `sillo-stubs/`, so
removing the stubs without this would have silently made it untyped for
consumers. Verified with mypy against a real install: its own inline
annotations now resolve.
Logger names are deliberately left alone. `logging.getLogger("sillo.graphql")`
and `"sillo.graphql.operations"` are a logging hierarchy nested under the
framework's own `sillo` logger -- the same convention as `sillo.record`
and `sillo.mail` -- so they inherit handlers and level from
`setup_logging()`. They are not import paths, and renaming them would
detach the package from the framework's logging configuration.
CI's `alias` job becomes a `wheel` job: same wheel-not-checkout approach,
now asserting `sillo_graphql` imports, `sillo.graphql` does not resolve,
no `.pth` or stubs are back in the wheel, and `py.typed` is present. The
uninstall-isolation checks are kept as they were. Header comments that
said `sillo-framework>=1.0` cannot resolve on PyPI are updated: 1.0.0a1
is published now, though CI still tracks `main` rather than that tag.
Verified: 467 passed, ruff clean, and the built wheel installs into a
clean venv beside sillo-framework 1.0.0a1 where sillo_graphql imports
and type-checks, sillo.graphql raises ImportError, and no .pth is
installed.
This was referenced Sep 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Companion to sillohq/wire#1, which does the same for
sillo-wire.sillo-graphqlshipped under two names.sillo_graphqlis where the code lives;sillo.graphqlwas an alias so an import could read as part of the framework. It took three pieces of machinery:_sillo_graphql_bootstrap.py— a meta-path finder mappingsillo.graphql→sillo_graphqlsillo_graphql.pth— registering it at interpreter startupsillo-stubs/— PEP 561 partial stubs, because static analysis never runs import hooksThe cost is a
.pthexecuting on every interpreter start in every environment the package is installed in, plus a second set of type declarations to keep in step with the real ones.Breaking
Free here:
sillo-graphqlhas never been published — no tags in this repo, and the PyPI JSON API returns nothing for the name. No user is on the old path.Two things worth a look
py.typedwas missing. The package claimedTyping :: Typedin its classifiers but shipped no PEP 561 marker of its own — type checkers were served entirely bysillo-stubs/. Removing the stubs without adding the marker would have silently madesillo_graphqluntyped for every consumer. Added, and verified with mypy against a real install that the inline annotations now resolve.Logger names are deliberately unchanged.
logging.getLogger("sillo.graphql")and"sillo.graphql.operations"look like the alias, but they are not import paths — they are a logging hierarchy nested under the framework's ownsillologger, the same convention assillo.record,sillo.mailandsillo.storage. They inherit handlers and level fromsetup_logging(logger_name="sillo"). Renaming them tosillo_graphqlwould detach this package from the framework's logging configuration, so they stay as they are.CI
aliasjob becomes awheeljob. Same approach — verify against a built wheel, not the editable checkout, since an editable install can import what the wheel does not ship — but it now assertssillo_graphqlimports,sillo.graphqldoes not resolve, no.pthor stubs have crept back in, andpy.typedis present. The uninstall-isolation checks are kept unchanged.release.yml's wheel assertions flipped from requiring the.pth/bootstrap/stubs to forbidding them.sillo-framework>=1.0"cannot resolve against PyPI" are now wrong —1.0.0a1was published today. Corrected, though CI still installs the framework frommainon purpose, since this package tracks the branch rather than the last tag.Verification
ruffcleansillo_graphql+py.typedand nothing elsesillo-framework 1.0.0a1:sillo_graphqlimports,sillo.graphqlraisesImportError, no.pthinstalled,sillo/untouchedmypyresolvesGraph,Limitsandnot_foundfrom the installed package with no stubs present🤖 Generated with Claude Code