speedy-utils 2.0.2__tar.gz → 2.0.4__tar.gz

{speedy_utils-2.0.2 → speedy_utils-2.0.4}/.githooks/pre-commit

@@ -1,13 +1,5 @@
 #!/usr/bin/env python3
-"""
-Pre-commit hook to ensure import time is under 0.4 seconds.
-
-This enforces the project's performance requirement that speedy_utils
-must import quickly (< 0.4s). This is critical for user experience.
-
-Strategy: Use lazy imports for heavy modules (torch, ray, matplotlib, pandas)
-inside functions that need them, not at module level.
-"""
+"""Pre-commit hook to enforce import-time budgets with actionable output."""
 
 import os
 import subprocess
@@ -73,57 +65,39 @@ def _build_env() -> dict[str, str]:
     return env
 
 
-def check_import_time(module: str) -> tuple[bool, float, str]:
-    """Check import time for a module. Returns (passed, time_seconds)."""
-    code = f"import time; start=time.perf_counter(); import {module}; print(time.perf_counter()-start)"
+def _helper_script() -> Path:
+    return _REPO_ROOT / "scripts" / "debug_import_time.py"
+
+
+def main() -> int:
+    """Run import-time checks through the shared helper script."""
+    print("Checking import times... (max: {:.1f}s)".format(MAX_IMPORT_TIME))
+
+    helper = _helper_script()
     result = subprocess.run(
-        [_PYTHON, "-c", code],
-        capture_output=True,
-        text=True,
+        [
+            _PYTHON,
+            str(helper),
+            "--max-total-sec",
+            str(MAX_IMPORT_TIME),
+            "--min-sec",
+            "0.01",
+            "--top",
+            "12",
+            "--no-stdlib",
+            "--quiet-success",
+            *MODULES,
+        ],
         env=_build_env(),
         cwd=str(_REPO_ROOT),
     )
-    if result.returncode != 0:
-        err = (result.stderr or result.stdout or "").strip()
-        return False, -1, err
-    try:
-        import_time = float(result.stdout.strip())
-        return import_time <= MAX_IMPORT_TIME, import_time, ""
-    except ValueError:
-        err = (result.stderr or result.stdout or "").strip()
-        return False, -1, err
 
+    if result.returncode != 0:
+        print("\nImport time check failed.")
+        print("Rerun the helper above after moving heavy imports into function scope")
+        print("or a lazy __getattr__ export to pinpoint the slow path.")
 
-def main() -> int:
-    """Run import time checks."""
-    failed = False
-
-    print("Checking import times... (max: {:.1f}s)".format(MAX_IMPORT_TIME))
-
-    for module in MODULES:
-        passed, import_time, err = check_import_time(module)
-
-        if import_time < 0:
-            print(f"  {module}: FAILED - import error")
-            if err:
-                last_line = err.splitlines()[-1]
-                print(f"    ↳ {last_line}")
-            failed = True
-        elif passed:
-            print(f"  {module}: {import_time:.3f}s")
-        else:
-            print(f"  {module}: FAILED - {import_time:.3f}s exceeds {MAX_IMPORT_TIME:.1f}s")
-            failed = True
-
-    if failed:
-        print("\nImport time check failed! To fix:")
-        print("  1. Use lazy imports for heavy modules inside functions")
-        print("  2. Move heavy imports to function scope, not module level")
-        print("  3. Use the _LazyModule pattern from __imports.py")
-        print("\nHeavy modules to lazy-load: torch, ray, matplotlib, pandas")
-        return 1
-
-    return 0
+    return result.returncode
 
 
 if __name__ == "__main__":

speedy_utils-2.0.4/.github/skills/make-vscode-happy/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: 'make-vscode-happy'
+description: 'Reduce VS Code Python red squiggles to zero in this repository. Use when Pylance or pyright reports errors, when tools/check_syntax.py fails, or when a change should leave VS Code diagnostics clean.'
+argument-hint: 'Optional file path, module name, or failing area to fix'
+---
+
+# Make VS Code Happy
+
+Use this skill when the goal is to make VS Code and Pylance happy in this
+repository by driving Python diagnostics to zero with the repo's existing
+checker: `tools/check_syntax.py`.
+
+## When to Use
+
+Use this skill when you need to:
+- Fix Python red squiggles in VS Code.
+- Reconcile Pylance diagnostics with command-line validation.
+- Clean up pyright issues before committing.
+- Verify that a targeted change did not leave new diagnostics behind.
+
+## Primary Checker
+
+The authoritative checker for this repo is:
+
+```bash
+uv run python tools/check_syntax.py
+```
+
+Useful variants:
+
+```bash
+uv run python tools/check_syntax.py --file src/llm_utils/lm/llm_qwen3.py
+uv run python tools/check_syntax.py --include tests
+uv run python tools/check_syntax.py --json
+```
+
+This script mirrors the diagnostics VS Code Pylance shows for the repository's
+`pyrightconfig.json`.
+
+## Procedure
+
+1. Pick scope first.
+   - If the request names a file, start with `--file` for that file.
+   - If the issue sounds cross-cutting or unclear, run the full check first.
+2. Read diagnostics and group them by root cause instead of fixing them one by
+   one in isolation.
+3. Fix the real source of the type error.
+   - Prefer correcting annotations, overloads, return types, and control flow.
+   - Use repo-approved ignores only when the code is intentionally dynamic.
+4. Re-run the smallest relevant check after each edit.
+5. Before concluding, run the broader validation needed for the scope.
+   - If you touched one file, re-run that file and then a full check if the
+     change affects shared APIs.
+   - If you changed common utilities, package exports, or typing helpers, run
+     the full check.
+6. If the fix changes imports in public packages, protect the import-time
+   budget as well.
+
+## Decision Points
+
+- Single-file symptom vs shared typing pattern:
+  Start narrow for local regressions; go broad if the same diagnostic appears in
+  multiple files or stems from a shared helper.
+- True bug vs accepted dynamic pattern:
+  Prefer a real type fix first. Only use a targeted ignore when the repository
+  already treats that pattern as intentionally dynamic.
+- Typing fix vs performance regression:
+  Do not fix types by introducing heavy top-level imports in `__init__.py` or
+  other import-sensitive modules.
+
+## Completion Criteria
+
+- `tools/check_syntax.py` reports zero relevant errors for the changed scope.
+- Touched files do not introduce new warnings unless the user accepted them.
+- The fix matches repository typing conventions.
+- No eager heavy imports were added just to satisfy typing.
+
+## References
+
+- [Diagnostic playbook](./references/diagnostic-playbook.md)

speedy_utils-2.0.4/.github/skills/make-vscode-happy/references/diagnostic-playbook.md

@@ -0,0 +1,94 @@
+# Diagnostic Playbook
+
+This reference supports the `make-vscode-happy` skill for the `speedy_utils`
+repository.
+
+## Repo Rules That Matter
+
+- Use `uv run python tools/check_syntax.py` as the source of truth for Python
+  diagnostics.
+- Fix root causes instead of masking errors with broad ignores.
+- Keep public package import time under `0.4s`.
+- Do not introduce heavy top-level imports such as `torch`, `pandas`,
+  `matplotlib`, or `IPython` in `__init__.py` files.
+
+## Fast Triage
+
+### If the prompt names a specific file
+
+Run:
+
+```bash
+uv run python tools/check_syntax.py --file path/to/file.py
+```
+
+Then fix the reported issue and re-run the same command.
+
+### If the prompt is vague or broad
+
+Run:
+
+```bash
+uv run python tools/check_syntax.py
+```
+
+If the change touches tests or test helpers, consider:
+
+```bash
+uv run python tools/check_syntax.py --include tests
+```
+
+## Common Fix Patterns In This Repo
+
+### Overload ordering
+
+Put the `Awaitable[...]` overload before the generic non-awaitable overload to
+avoid overlapping-overload diagnostics.
+
+### Dynamic Pydantic-style attributes
+
+When the code intentionally sets attributes not declared in the model schema,
+use a narrow ignore such as:
+
+```python
+# type: ignore[attr-defined]
+```
+
+Do not apply it broadly if a better annotation is possible.
+
+### `tqdm` annotations
+
+Use the string literal form in annotations:
+
+```python
+"tqdm"
+```
+
+### Lazy exports
+
+For names loaded through `__getattr__`, follow the existing lazy-export pattern
+instead of forcing eager imports for type convenience.
+
+### `__all__` with heavy lazy names
+
+Do not add heavy lazy names to `__all__`, because star imports will defeat lazy
+loading and hurt import time.
+
+## When a Typing Fix Touches Imports
+
+If you changed imports in a public package, especially `speedy_utils`,
+`llm_utils`, or `vision_utils`, run:
+
+```bash
+uv run python scripts/debug_import_time.py speedy_utils llm_utils vision_utils --max-total-sec 0.4 --top 12 --min-sec 0.01 --no-stdlib
+```
+
+Use that output to move heavy imports behind lazy boundaries if needed.
+
+## Definition of Done
+
+- Targeted diagnostics are gone.
+- Shared changes were validated with a broader repo check.
+- The fix preserves existing lazy-import and typing conventions.
+- VS Code should agree with command-line output because the checker mirrors
+  Pylance behavior for this repository.

{speedy_utils-2.0.2 → speedy_utils-2.0.4}/.gitignore

@@ -125,4 +125,5 @@ dmypy.json
 edu_results.json
 .playwright-mcp
 .DS_Store
-.chainlit
+.chainlit
+chainlit.md

{speedy_utils-2.0.2 → speedy_utils-2.0.4}/CLAUDE.md

@@ -9,19 +9,22 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 uv sync
 
 # Run tests
-uv run pytest -n 32
+./tools/uv_test.sh -n 32
 
 # Run a single test file
-uv run pytest tests/test_thread.py
+./tools/uv_test.sh tests/test_thread.py
 
 # Run with verbose output
-uv run pytest -v
+./tools/uv_test.sh -v
 
 # Check import time (must be < 0.4s)
 uv run python -c "import time; start=time.perf_counter(); import speedy_utils; print(f'{time.perf_counter()-start:.3f}s')"
 
-# Detailed import analysis
-uv run python scripts/debug_import_time.py speedy_utils --min-sec 0.05 --no-stdlib
+# Detailed import analysis / import budget check
+uv run python scripts/debug_import_time.py speedy_utils --max-total-sec 0.4 --top 12 --min-sec 0.01 --no-stdlib
+
+# Check all public packages with the same helper used by pre-commit
+uv run python scripts/debug_import_time.py speedy_utils llm_utils vision_utils --max-total-sec 0.4 --top 12 --min-sec 0.01 --no-stdlib
 
 # Lint with ruff
 uv run ruff check .
@@ -40,6 +43,16 @@ uv run ruff format .
 
 **CRITICAL:** All modules must import in under 0.4 seconds. This is enforced by a git pre-commit hook.
 
+When the import-time hook fails, rerun `scripts/debug_import_time.py` with the
+same package list and budget. The helper now prints both:
+
+- top-level contributors by aggregated self time
+- slowest full import paths from `python -X importtime`
+
+Use that output to pinpoint which import chain needs to be moved behind a lazy
+import. Keep the helper's default package list and thresholds aligned with the
+packages this repo exports as the project evolves.
+
 ### Lazy Import Strategy
 
 Import heavy modules inside functions, NOT at module level:
@@ -170,6 +183,50 @@ The package provides these CLI commands:
 - Ignore rules `E402`, `F401`, `F403` in `__init__.py` files for lazy import patterns
 - Quote style: double quotes
 - Avoid hacky workarounds like sys.path.insert
+- Follow `CODE_STYLE.md` for general style guidelines
+
+## Type Checking with Pyright
+
+**CRITICAL:** Before committing, always run `uv run python tools/check_syntax.py` to
+verify there are **zero** pyright errors.  This tool mirrors exactly what VS Code
+Pylance shows as red diagnostics.
+
+```bash
+# Full check (src/ + tests/, honours pyrightconfig.json)
+uv run python tools/check_syntax.py
+
+# Import-time budget check with root-cause breakdown
+uv run python scripts/debug_import_time.py speedy_utils llm_utils vision_utils --max-total-sec 0.4 --top 12 --min-sec 0.01 --no-stdlib
+
+# Check a single file
+uv run python tools/check_syntax.py --file src/llm_utils/lm/llm_qwen3.py
+
+# Machine-readable JSON output
+uv run python tools/check_syntax.py --json
+```
+
+### pyright config (`pyrightconfig.json`)
+
+The config lives at the repo root.  Key rules that are **suppressed** (because
+they produce false positives in this codebase):
+
+| Rule | Why suppressed |
+|------|---------------|
+| `reportMissingImports` | Optional GPU deps (`torch`, `nvidia.dali`) not installed everywhere |
+| `reportAttributeAccessIssue` | Dynamic attrs on OpenAI pydantic models (`choice.usage`, `message.call_count`) |
+| `reportUnsupportedDunderAll` | Lazy `__getattr__` exports listed in `__all__` |
+
+### Common type-annotation patterns
+
+- **Lazy-loaded `__all__` entries** — never trigger `__getattr__`; use `# type: ignore[override]`
+  only on the `__getitem__` override pattern in datasets.
+- **Dynamic pydantic attrs** — use `# type: ignore[attr-defined]` when setting attrs
+  not in the schema (e.g. `message.call_count = …`).
+- **Overload ordering** — put the `Awaitable[R]` overload **before** the generic `R`
+  overload; otherwise pyright reports `reportOverlappingOverload`.
+- **`tqdm` in type hints** — use string literal `"tqdm"` to avoid `reportInvalidTypeForm`.
+- **Future custom attrs** — `concurrent.futures.Future` doesn't declare custom attrs;
+  suppress with `reportAttributeAccessIssue: "none"` in config.
 
 
 ## Version Management