py-import-checker 0.2.0__py3-none-any.whl

py_import_checker/__init__.py

@@ -0,0 +1,4 @@
+"""py-import-checker: Fast, zero-dependency Python import health scanner."""
+
+__version__ = "0.1.0"
+__author__ = "matthieugraziani"

py_import_checker/checker.py

@@ -0,0 +1,96 @@
+"""Core import verification engine."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class ImportFailure:
+    """Represents a single import failure."""
+
+    file: Path
+    error_type: str
+    message: str
+
+
+@dataclass
+class CheckResult:
+    """Aggregated result from a full scan."""
+
+    checked: int = 0
+    errors: list[ImportFailure] = field(default_factory=list)
+
+    @property
+    def success(self) -> bool:
+        return len(self.errors) == 0
+
+
+_SKIP_PARTS = {".venv", "venv", "__pycache__", ".git", "node_modules", "dist", "build"}
+
+
+def _should_skip(path: Path, script_path: Path) -> bool:
+    if path.resolve() == script_path.resolve():
+        return True
+    return any(part in _SKIP_PARTS for part in path.parts)
+
+
+def check_directory(
+    root: Path,
+    extra_paths: list[Path] | None = None,
+    glob: str = "**/*.py",
+) -> CheckResult:
+    """
+    Scan all Python files under *root* and attempt to import each one.
+
+    Parameters
+    ----------
+    root:
+        Directory to scan recursively.
+    extra_paths:
+        Additional paths inserted at the front of sys.path before scanning
+        (e.g. the project ``src/`` directory).
+    glob:
+        Glob pattern used to find Python files (default: ``**/*.py``).
+    """
+    root = root.resolve()
+    script_path = Path(__file__).resolve()
+
+    paths_to_add = [root] + (extra_paths or [])
+    for p in reversed(paths_to_add):
+        p_str = str(p)
+        if p_str not in sys.path:
+            sys.path.insert(0, p_str)
+
+    result = CheckResult()
+
+    for file_path in sorted(root.glob(glob)):
+        if _should_skip(file_path, script_path):
+            continue
+
+        result.checked += 1
+        relative = file_path.relative_to(root)
+        module_name = ".".join(relative.with_suffix("").parts)
+
+        try:
+            spec = importlib.util.spec_from_file_location(module_name, file_path)
+            if spec and spec.loader:
+                module = importlib.util.module_from_spec(spec)
+                sys.modules[module_name] = module
+                spec.loader.exec_module(module)
+        except (ModuleNotFoundError, ImportError) as exc:
+            result.errors.append(
+                ImportFailure(
+                    file=relative,
+                    error_type=type(exc).__name__,
+                    message=str(exc),
+                )
+            )
+        except Exception:  # pylint: disable=broad-exception-caught
+            # Ignore pure runtime errors — only structural import issues matter.
+            pass
+
+    return result

py_import_checker/cli.py

@@ -0,0 +1,110 @@
+"""Command-line interface for py-import-checker."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .checker import CheckResult, check_directory
+
+RESET = "\033[0m"
+BOLD = "\033[1m"
+GREEN = "\033[32m"
+RED = "\033[31m"
+YELLOW = "\033[33m"
+CYAN = "\033[36m"
+DIM = "\033[2m"
+
+
+def _banner() -> None:
+    print(f"\n{BOLD}{CYAN}py-import-checker{RESET}  —  Python import health scanner\n")
+
+
+def _print_result(result: CheckResult, verbose: bool) -> None:
+    if verbose:
+        print(f"{DIM}Verbose mode enabled.{RESET}\n")
+
+    if result.errors:
+        print(f"{YELLOW}{'─' * 50}{RESET}")
+        for err in result.errors:
+            print(f"  {RED}✗{RESET}  {BOLD}{err.file}{RESET}")
+            print(f"     {DIM}{err.error_type}: {err.message}{RESET}\n")
+
+    print(f"{'─' * 50}")
+    total = result.checked
+    n_err = len(result.errors)
+
+    if result.success:
+        print(
+            f"{GREEN}{BOLD}✓ All clear!{RESET}"
+            f"  {total} file(s) checked — no broken imports.\n"
+        )
+    else:
+        print(
+            f"{RED}{BOLD}✗ {n_err} broken import(s){RESET}"
+            f" found in {total} file(s) scanned.\n"
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="py-import-checker",
+        description="Scan a Python project for broken imports.",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Root directory to scan (default: current directory).",
+    )
+    parser.add_argument(
+        "--src",
+        metavar="DIR",
+        action="append",
+        default=[],
+        help=(
+            "Extra directory to prepend to sys.path (repeatable). "
+            "Useful for src-layout projects."
+        ),
+    )
+    parser.add_argument(
+        "--glob",
+        default="**/*.py",
+        help="Glob pattern for file discovery (default: **/*.py).",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Show all scanned files, not just errors.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="%(prog)s 0.1.0",
+    )
+
+    args = parser.parse_args(argv)
+    root = Path(args.path).resolve()
+
+    if not root.exists():
+        print(f"{RED}Error: path '{root}' does not exist.{RESET}", file=sys.stderr)
+        return 2
+
+    extra = [Path(p).resolve() for p in args.src]
+
+    _banner()
+    print(f"  {DIM}Scanning  {root}{RESET}")
+    if extra:
+        print(f"  {DIM}sys.path  {', '.join(str(p) for p in extra)}{RESET}")
+    print()
+
+    result = check_directory(root, extra_paths=extra, glob=args.glob)
+    _print_result(result, args.verbose)
+
+    return 0 if result.success else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

py_import_checker-0.2.0.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: py-import-checker
+Version: 0.2.0
+Summary: Fast, zero-dependency Python import health scanner
+Project-URL: Homepage, https://github.com/matthieugraziani/py-import-checker
+Project-URL: Repository, https://github.com/matthieugraziani/py-import-checker
+Project-URL: Issues, https://github.com/matthieugraziani/py-import-checker/issues
+Project-URL: Changelog, https://github.com/matthieugraziani/py-import-checker/blob/main/CHANGELOG.md
+Author-email: Matthieu Graziani <matthieu.graziani@proton.me>
+License: MIT
+License-File: LICENSE
+Keywords: cli,debugging,developer-tools,import-checker,imports,linting,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <h1 align="center">py-import-checker</h1>
+  <p align="center">
+    <strong>Fast, zero-dependency Python import health scanner.</strong>
+  </p>
+
+  <p align="center">
+    Recursively scan any Python project and instantly surface every broken or missing import — 
+    <strong>before your tests run, before CI fails, before runtime surprises you.</strong>
+  </p>
+
+  <p align="center">
+    <a href="https://pypi.org/project/py-import-checker/">
+      <img src="https://img.shields.io/pypi/v/py-import-checker.svg" alt="PyPI version">
+    </a>
+    <a href="https://github.com/matthieugraziani/py-import-checker/actions">
+      <img src="https://github.com/matthieugraziani/py-import-checker/actions/workflows/ci.yml/badge.svg" alt="Tests">
+    </a>
+    <a href="https://opensource.org/licenses/MIT">
+      <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+    </a>
+    <img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python 3.10+">
+  </p>
+</p>
+
+```text
+py-import-checker src/ --src src/
+
+  py-import-checker  —  Python import health scanner
+
+  Scanning  /home/user/myproject/src
+
+──────────────────────────────────────────────────
+  ✗  mypackage/broken_module.py
+     ModuleNotFoundError: No module named 'nonexistent_lib'
+
+──────────────────────────────────────────────────
+✗ 1 broken import(s) found in 14 file(s) scanned.
+
+```
+
+## Features
+
+- **Zero dependencies** — uses only the Python standard library (`importlib`, `pathlib`, `sys`)
+- **src-layout aware** — pass `--src` to add extra directories to `sys.path`
+- **Noise-free** — only reports `ImportError` / `ModuleNotFoundError`; ignores runtime exceptions
+- **Auto-skips** virtual environments (`.venv`, `venv`) and build artefacts
+- **CI-friendly** — exits with code `1` on any broken import, `0` on success
+- **Self-checking** — the CI pipeline scans itself with `py-import-checker`
+
+
+## Installation
+
+```bash
+pip install py-import-checker
+```
+
+Or install from source (editable):
+
+```bash
+git clone https://github.com/matthieugraziani/py-import-checker
+cd py-import-checker
+pip install -e .
+```
+
+## Usage
+
+### Command line
+
+```bash
+# Scan the current directory
+py-import-checker
+
+# Scan a specific directory
+py-import-checker path/to/project
+
+# src-layout project (adds src/ to sys.path)
+py-import-checker . --src src/
+
+# Multiple extra paths
+py-import-checker . --src src/ --src lib/
+
+# Custom file glob
+py-import-checker . --glob "app/**/*.py"
+
+# Verbose output (show all files, not just errors)
+py-import-checker . -v
+```
+
+### Python API
+
+```python
+from pathlib import Path
+from py_import_checker.checker import check_directory
+
+result = check_directory(
+    root=Path("src/"),
+    extra_paths=[Path("src/")],
+)
+
+if not result.success:
+    for err in result.errors:
+        print(f"{err.file}: {err.error_type}: {err.message}")
+```
+
+### Pre-commit hook
+Ajoutez ceci à votre fichier .pre-commit-config.yaml :
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/matthieugraziani/py-import-checker
+    rev: v0.1.0
+    hooks:
+      - id: py-import-checker
+        args: [--src, src/]
+```
+
+### GitHub Actions
+
+```yaml
+- name: Check imports
+  run: |
+    pip install py-import-checker
+    py-import-checker . --src src/
+```
+
+
+
+## How it works
+
+py-import-checker utilise importlib.util.spec_from_file_location pour charger chaque fichier .py dans un namespace isolé. Seules les erreurs d’import sont capturées — tout le reste (erreurs runtime, variables manquantes, etc.) est ignoré.
+
+
+## Roadmap (suggestions)
+
+- Mode --fix (suggestions d’imports)
+- Support des packages namespace (__init__.py moins strict)
+- Intégration VS Code / LSP
+- Rapport HTML / JSON
+- Détection de circular imports (optionnel)
+
+---
+
+## Development
+
+```bash
+# Install with dev extras
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check src/ tests/
+
+# Type-check
+mypy src/
+```
+
+---
+
+## License - MIT
+
+Auteur : Matthieu Graziani
+```text
+### Améliorations apportées
+- En-tête centré + badges propres
+- Démo plus visible
+- Sections plus aérées
+- Roadmap ajoutée (pour montrer l’évolution)
+- Meilleure lisibilité
+
+### Actions prioritaires maintenant
+1. **Publier sur PyPI** (version 0.1.0 ou 0.2.0) :
+   ```bash
+   hatch build
+   hatch publish
+```

py_import_checker-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+py_import_checker/__init__.py,sha256=_Kqs_c_gOezQLrrUtJzqCIPzAUhvptLTiNpTQL0ATbA,132
+py_import_checker/checker.py,sha256=ufMx73ln1izcXDaVCFmzLFRkAGoE9Wlg59rkRg2fYig,2636
+py_import_checker/cli.py,sha256=Bp-lIjN0PvDOYG3copfT9Yk1mKlwhQkaQf7FDzcX-_I,2837
+py_import_checker-0.2.0.dist-info/METADATA,sha256=THXNzQFaxLhGw_KCNGOIidXMVESLUEULqSQ6NPpkZ7I,5933
+py_import_checker-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+py_import_checker-0.2.0.dist-info/entry_points.txt,sha256=v3aRM_0I1dsUqInJORiGMAolzWrl-lUsEMR_UAb3-uU,65
+py_import_checker-0.2.0.dist-info/licenses/LICENSE,sha256=T1pyG9Juy8e2d-i9ga0XhleFuGWgDqu4sWjeUIUaXIM,1073
+py_import_checker-0.2.0.dist-info/RECORD,,

py_import_checker-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

py_import_checker-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+py-import-checker = py_import_checker.cli:main

py_import_checker-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 matthieugraziani
+
+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.