lazysafe 0.1.0__tar.gz

lazysafe-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.experimental == true }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest, python: "3.11" }
+          - { os: ubuntu-latest, python: "3.12" }
+          - { os: ubuntu-latest, python: "3.13" }
+          - { os: ubuntu-latest, python: "3.14" }
+          - { os: macos-latest, python: "3.14" }
+          - { os: windows-latest, python: "3.14" }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync
+      - run: uv run pytest -q
+      - run: uv run ruff check .

lazysafe-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv run twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

lazysafe-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+.venv/
+venv/
+ENV/
+
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+.lazysafe/
+
+.DS_Store
+Thumbs.db
+uv.lock

lazysafe-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.0] - 2026-09-06
+
+### added
+
+- `lazysafe analyze` static analysis engine with SE01-SE08 side-effect rules
+- classification decision tree (SAFE / RISKY / UNSAFE / UNKNOWN)
+- JSON report output (`--save`, `--json` flags)
+- `lazysafe version` command with capability matrix
+- configuration via `lazysafe.toml` with unknown-key rejection
+- fixture corpus for side-effect rule testing
+
+### side-effect rules
+
+- SE01: module-level call expressions
+- SE02: foreign attribute assignment (monkeypatching)
+- SE03: sys.path / sys.modules / os.environ mutation
+- SE04: atexit / signal / logging registration
+- SE05: module-level file I/O
+- SE06: framework registration decorators
+- SE07: importlib.import_module with computed names
+- SE08: try/except ImportError with fallback patches

lazysafe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rahul Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lazysafe-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.3
+Name: lazysafe
+Version: 0.1.0
+Summary: safely adopt python 3.15 lazy imports: analyze, probe, apply, verify, measure
+Project-URL: Homepage, https://github.com/rahulxs/lazysafe
+Project-URL: Repository, https://github.com/rahulxs/lazysafe
+Project-URL: Issues, https://github.com/rahulxs/lazysafe/issues
+Project-URL: Changelog, https://github.com/rahulxs/lazysafe/blob/main/CHANGELOG.md
+Author-email: Rahul Sharma <rahulxsh@gmail.com>
+License: MIT
+Keywords: cpython315,import-time,lazy-imports,pep810,performance,python,side-effects,startup,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# lazysafe
+
+safely adopt python 3.15 lazy imports.
+
+## why it exists
+
+python 3.15 ships [PEP 810](https://peps.python.org/pep-0810/) explicit lazy
+imports. `lazy import json` defers loading until first use. reported wins: ~2.9x
+faster startup for import-heavy applications.
+
+the catch: laziness changes *when* import-time side effects run. some libraries
+depend on them. under lazy mode, programs break in confusing ways.
+
+lazysafe answers that question empirically.
+
+## install
+
+```
+pip install lazysafe
+```
+
+## quickstart
+
+```bash
+# see which imports are safe to make lazy
+lazysafe analyze src/
+
+# show all modules including safe ones
+lazysafe analyze src/ --all
+
+# save a JSON report
+lazysafe analyze src/ --save report.json
+```
+
+## what it does
+
+lazysafe scans your Python source files and classifies every import statement
+by its side-effect risk:
+
+| finding | meaning | action |
+|---------|---------|--------|
+| SAFE | no side effects detected | safe to make lazy |
+| RISKY | might have side effects | investigate before lazy |
+| UNSAFE | side effect detected | keep eager |
+| UNKNOWN | can't determine statically | needs probing (v0.3.0) |
+
+### side-effect rules
+
+| code | what it detects | confidence |
+|------|-----------------|------------|
+| SE01 | module-level function calls | 0.6 |
+| SE02 | foreign attribute assignment (monkeypatching) | 0.9 |
+| SE03 | sys.path / sys.modules / os.environ mutation | 0.95 |
+| SE04 | atexit / signal / logging registration | 0.85-0.9 |
+| SE05 | module-level file I/O | 0.8 |
+| SE06 | framework registration decorators (2+) | 0.5 |
+| SE07 | importlib.import_module with computed names | 0.9 |
+| SE08 | try/except ImportError with fallback patches | 0.7 |
+
+## what it does not do
+
+- runtime lazy-loading for older pythons (no backport of PEP 810)
+- patching third-party packages' code
+- function-level profiling (use [Tachyon](https://docs.python.org/3.15/whatsnew/3.15.html#tachyon) in 3.15)
+- general linting/formatting (use [ruff](https://docs.astral.sh/ruff/))
+
+## requirements
+
+- python >= 3.11 (host running lazysafe)
+- target programs using lazy import semantics require python >= 3.15
+- linux, macos, windows
+
+## links
+
+- [changelog](https://github.com/rahulxs/lazysafe/blob/main/CHANGELOG.md)
+- [issue tracker](https://github.com/rahulxs/lazysafe/issues)
+
+## license
+
+MIT

lazysafe-0.1.0/README.md

@@ -0,0 +1,80 @@
+# lazysafe
+
+safely adopt python 3.15 lazy imports.
+
+## why it exists
+
+python 3.15 ships [PEP 810](https://peps.python.org/pep-0810/) explicit lazy
+imports. `lazy import json` defers loading until first use. reported wins: ~2.9x
+faster startup for import-heavy applications.
+
+the catch: laziness changes *when* import-time side effects run. some libraries
+depend on them. under lazy mode, programs break in confusing ways.
+
+lazysafe answers that question empirically.
+
+## install
+
+```
+pip install lazysafe
+```
+
+## quickstart
+
+```bash
+# see which imports are safe to make lazy
+lazysafe analyze src/
+
+# show all modules including safe ones
+lazysafe analyze src/ --all
+
+# save a JSON report
+lazysafe analyze src/ --save report.json
+```
+
+## what it does
+
+lazysafe scans your Python source files and classifies every import statement
+by its side-effect risk:
+
+| finding | meaning | action |
+|---------|---------|--------|
+| SAFE | no side effects detected | safe to make lazy |
+| RISKY | might have side effects | investigate before lazy |
+| UNSAFE | side effect detected | keep eager |
+| UNKNOWN | can't determine statically | needs probing (v0.3.0) |
+
+### side-effect rules
+
+| code | what it detects | confidence |
+|------|-----------------|------------|
+| SE01 | module-level function calls | 0.6 |
+| SE02 | foreign attribute assignment (monkeypatching) | 0.9 |
+| SE03 | sys.path / sys.modules / os.environ mutation | 0.95 |
+| SE04 | atexit / signal / logging registration | 0.85-0.9 |
+| SE05 | module-level file I/O | 0.8 |
+| SE06 | framework registration decorators (2+) | 0.5 |
+| SE07 | importlib.import_module with computed names | 0.9 |
+| SE08 | try/except ImportError with fallback patches | 0.7 |
+
+## what it does not do
+
+- runtime lazy-loading for older pythons (no backport of PEP 810)
+- patching third-party packages' code
+- function-level profiling (use [Tachyon](https://docs.python.org/3.15/whatsnew/3.15.html#tachyon) in 3.15)
+- general linting/formatting (use [ruff](https://docs.astral.sh/ruff/))
+
+## requirements
+
+- python >= 3.11 (host running lazysafe)
+- target programs using lazy import semantics require python >= 3.15
+- linux, macos, windows
+
+## links
+
+- [changelog](https://github.com/rahulxs/lazysafe/blob/main/CHANGELOG.md)
+- [issue tracker](https://github.com/rahulxs/lazysafe/issues)
+
+## license
+
+MIT

lazysafe-0.1.0/conftest.py

@@ -0,0 +1,6 @@
+"""pytest configuration -- adds src/ to sys.path for imports."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent / "src"))

lazysafe-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lazysafe"
+dynamic = ["version"]
+description = "safely adopt python 3.15 lazy imports: analyze, probe, apply, verify, measure"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Rahul Sharma", email = "rahulxsh@gmail.com" }]
+keywords = [
+    "python", "lazy-imports", "pep810", "startup", "performance",
+    "import-time", "side-effects", "verification", "cpython315",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.scripts]
+lazysafe = "lazysafe.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/rahulxs/lazysafe"
+Repository = "https://github.com/rahulxs/lazysafe"
+Issues = "https://github.com/rahulxs/lazysafe/issues"
+Changelog = "https://github.com/rahulxs/lazysafe/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/lazysafe/_version.py"
+
+[tool.hatch.build.targets.sdist]
+core-metadata-version = "2.3"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lazysafe"]
+core-metadata-version = "2.3"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF", "C901"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q --tb=short"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.5",
+    "build>=1.2",
+    "twine>=6",
+]

lazysafe-0.1.0/src/lazysafe/__init__.py

@@ -0,0 +1,5 @@
+"""lazysafe -- safely adopt Python 3.15 lazy imports."""
+
+from lazysafe._version import __version__
+
+__all__ = ["__version__"]

lazysafe-0.1.0/src/lazysafe/__main__.py

@@ -0,0 +1,5 @@
+"""allow running as: python -m lazysafe"""
+
+from lazysafe.cli import main
+
+main()

lazysafe-0.1.0/src/lazysafe/_version.py

@@ -0,0 +1,3 @@
+"""single source of truth for the version."""
+
+__version__ = "0.1.0"

lazysafe-0.1.0/src/lazysafe/cli.py

@@ -0,0 +1,128 @@
+"""CLI entry point -- argparse wiring only."""
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+from lazysafe._version import __version__
+from lazysafe.config import load_config
+from lazysafe.discovery import scan_directory
+from lazysafe.report import write_analysis_report
+from lazysafe.static import run_static
+from lazysafe.static.classify import classify_all
+
+
+def _cmd_analyze(args: argparse.Namespace) -> None:
+    """run static analysis on target directories."""
+    config = load_config(Path.cwd())
+    targets = args.targets or config.targets
+
+    start = time.monotonic()
+    model = scan_directory(targets, Path.cwd())
+    duration_ms = (time.monotonic() - start) * 1000
+
+    for node in model.modules:
+        if node.file:
+            try:
+                source = Path(node.file).read_text(encoding="utf-8")
+                node.findings = run_static(node, source)
+            except (OSError, UnicodeDecodeError):
+                pass
+
+    classify_all(model)
+
+    report = write_analysis_report(
+        model, targets, duration_ms, output=Path(args.save) if args.save else None
+    )
+
+    _print_analysis_table(report, args)
+
+
+def _print_analysis_table(report: dict, args: argparse.Namespace) -> None:
+    """print analysis results as a table."""
+    stats = report["stats"]
+    print(f"\nscanned {stats['files_scanned']} files, {stats['top_level_imports']} imports")
+    print(
+        f"classified: {stats['by_class']['safe']} safe, "
+        f"{stats['by_class']['risky']} risky, "
+        f"{stats['by_class']['unsafe']} unsafe, "
+        f"{stats['by_class']['unknown']} unknown"
+    )
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+        return
+
+    has_findings = any(mod["reasons"] for mod in report["modules"])
+    if not has_findings and not args.all:
+        print("\n  all imports look safe. use --all to see every module.\n")
+        return
+
+    for mod in report["modules"]:
+        cls = mod["class"]
+        if cls == "safe" and not args.all:
+            continue
+
+        symbol = {"safe": "+", "risky": "?", "unsafe": "!", "unknown": "?"}.get(
+            cls, "?"
+        )
+        imports = mod["imports_top_level"]
+        import_str = f" ({len(imports)} imports)" if imports else ""
+        print(f"  {symbol} {mod['module']} ({mod['origin']}) [{cls}]{import_str}")
+        for reason in mod["reasons"]:
+            print(f"    {reason['rule']}@{reason['lineno']}: {reason['evidence']}")
+
+    print()
+
+
+def _cmd_version(_args: argparse.Namespace) -> None:
+    """show version and capability matrix."""
+    print(f"lazysafe {__version__} \xb7 python {sys.version.split()[0]}")
+    print()
+    print("capabilities:")
+    print("  analyze   yes")
+    print("  measure   no  (v0.2.0)")
+    print("  probe     no  (v0.3.0)")
+    print("  apply     no  (v0.4.0)")
+    print("  verify    no  (v0.5.0)")
+
+
+def main(argv: list[str] | None = None) -> None:
+    """main entry point."""
+    parser = argparse.ArgumentParser(
+        prog="lazysafe",
+        description="safely adopt python 3.15 lazy imports.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    p_analyze = sub.add_parser("analyze", help="analyze imports for side effects")
+    p_analyze.add_argument("targets", nargs="*", help="directories to scan")
+    p_analyze.add_argument("--save", metavar="FILE", help="save JSON report")
+    p_analyze.add_argument("--json", action="store_true", help="output as JSON")
+    p_analyze.add_argument(
+        "--all", action="store_true", help="show safe modules too"
+    )
+
+    sub.add_parser("version", help="show capability matrix")
+
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    commands = {
+        "analyze": _cmd_analyze,
+        "version": _cmd_version,
+    }
+
+    if args.command in commands:
+        commands[args.command](args)
+    else:
+        print(f"command '{args.command}' not yet implemented.")
+        sys.exit(1)

lazysafe-0.1.0/src/lazysafe/config.py

@@ -0,0 +1,51 @@
+"""configuration loading and merging."""
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Config:
+    """lazysafe configuration."""
+
+    targets: list[str] = field(default_factory=lambda: ["src"])
+    budget_ms: float | None = None
+    measure_runs: int = 15
+    measure_warmup: int = 2
+    probe_timeout: float = 30.0
+    apply_mode: str = "dunder"
+    allowlist: list[str] = field(default_factory=list)
+
+
+_KNOWN_KEYS = {
+    "targets",
+    "budget_ms",
+    "measure_runs",
+    "measure_warmup",
+    "probe_timeout",
+    "apply_mode",
+    "allowlist",
+}
+
+
+def load_config(project_root: Path) -> Config:
+    """load lazysafe.toml from project root, falling back to defaults."""
+    config = Config()
+    config_path = project_root / "lazysafe.toml"
+
+    if not config_path.exists():
+        return config
+
+    with open(config_path, "rb") as f:
+        raw = tomllib.load(f)
+
+    unknown = set(raw.keys()) - _KNOWN_KEYS
+    if unknown:
+        raise ValueError(f"unknown config key: {unknown.pop()!r}")
+
+    for key in _KNOWN_KEYS:
+        if key in raw:
+            setattr(config, key, raw[key])
+
+    return config