chore: ban module-level imports of startup-heavy modules

[cloudsmith-iduffy]

Description

The perf work in this stack got mcp, httpx, cloudsmith_api, requests, rich, semver, urllib3 and keyring out of CLI startup. The startup tests guard the two main entry points, but someone could still add import requests to the top of any other eagerly-imported file and quietly hand every docker pull its ~30ms back.

This closes that gap with ruff's banned-module-level-import rule (TID253): the eight modules above can now only be imported inside functions. Files that are themselves loaded lazily — the command modules, the core/api/* call sites, the MCP server, and the session/rest/saml/download leaves — are allowlisted per file, so their existing top-level imports stay put. Anything new fails lint, in pre-commit and CI, via the existing ruff hook.

Turning the rule on immediately found two real problems:

1. The PyInstaller entrypoint (packaging/pyinstaller/entry.py) imported keyring.backend at module level, but only the packaging selftest uses it — every invocation of the frozen binary paid for an import it didn't need. It now lives inside the selftest helper. (Frozen imports are pre-compiled, so this one is below measurement noise — the binary clocks 0.26s before and after. Fixed because the rule is right, not because it's measurable.)
2. core/keyring.py imported the keyring library at module level, and that file is on the eager path (it's pulled in through the credential chain). My first instinct was to allowlist it; on review that was just papering over a real cost. The library is only used inside five functions, so the imports moved there — and cloudsmith --version dropped from 0.12s to 0.09s.

No flame graphs on this one — the only import-graph change is the small keyring subtree, and the numbers above tell the story. The real value is that the next accidental heavy import gets caught by the linter instead of a profiler.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Other (please describe)

Lint guard for startup performance, plus the two import deferrals it flagged.

Additional Notes

• Known hole: the allowlist covers cli/commands/* as a directory, which also exempts the eagerly-imported main.py and registry.py. The subprocess tests in cli/tests/test_startup_imports.py cover exactly that hole.
• The frozen binary was rebuilt and its packaging selftest passes (SELFTEST: OK, 129 modules).
• Full suite passes (801 passed, 40 skipped).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a Ruff lint guard (TID253) to prevent module-level imports of known startup-heavy dependencies across eagerly-imported CLI code paths, and fixes two existing eager imports that the new rule surfaced.

Changes:

• Enable Ruff TID253 and configure a banned module list for startup-heavy libraries, plus per-file allowlisting for known lazily-imported leaves.
• Defer keyring.backend import in the PyInstaller entrypoint so it’s only imported during the packaging selftest path.
• Defer keyring imports in cloudsmith_cli/core/keyring.py by moving them inside the functions that actually use keyring.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
pyproject.toml	Enables Ruff TID253, configures banned startup-heavy modules, and allowlists known lazy-import leaves via per-file ignores.
packaging/pyinstaller/entry.py	Moves keyring.backend import into the selftest-only helper to avoid eager import cost.
cloudsmith_cli/core/keyring.py	Refactors keyring imports into function scope to keep the eager import path lightweight.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.