importguardpy 0.1.0__py3-none-any.whl

importguard/__init__.py

@@ -0,0 +1,15 @@
+"""importguard - Measure and enforce import-time behavior in Python projects."""
+
+from .core import check_import, run_import_subprocess
+from .models import ImportResult, ImportTiming, SubprocessResult, Violation, ViolationType
+
+__version__ = "0.1.0"
+__all__ = [
+    "ImportResult",
+    "ImportTiming",
+    "SubprocessResult",
+    "Violation",
+    "ViolationType",
+    "check_import",
+    "run_import_subprocess",
+]

importguard/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running as python -m importguard."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

importguard/cli.py

@@ -0,0 +1,239 @@
+"""Command-line interface for importguard."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .config import ImportGuardConfig, find_config, load_config
+from .core import check_import
+from .models import ImportResult
+
+
+def _supports_unicode() -> bool:
+    """Check if the terminal supports Unicode output."""
+    # Check if stdout encoding supports common Unicode characters
+    try:
+        encoding = getattr(sys.stdout, "encoding", None) or "ascii"
+        # Try encoding our symbols
+        "✓✗→".encode(encoding)
+        return True
+    except (UnicodeEncodeError, LookupError):
+        return False
+
+
+# Use ASCII fallbacks on terminals that don't support Unicode (e.g., Windows cp1252)
+_UNICODE_OK = _supports_unicode()
+_CHECK = "✓" if _UNICODE_OK else "[OK]"
+_CROSS = "✗" if _UNICODE_OK else "[FAIL]"
+_ARROW = "→" if _UNICODE_OK else "->"
+
+
+def format_time(ms: float) -> str:
+    """Format time in milliseconds for display."""
+    if ms >= 1000:
+        return f"{ms / 1000:.1f}s"
+    return f"{ms:.0f}ms"
+
+
+def print_result(
+    result: ImportResult,
+    max_ms: float | None = None,
+    top_n: int = 10,
+    quiet: bool = False,
+) -> None:
+    """Print the result of an import check to stdout."""
+    if quiet and result.passed:
+        return
+
+    # Color codes
+    green = "\033[32m"
+    red = "\033[31m"
+    reset = "\033[0m"
+
+    # Handle import failure specially
+    if result.import_failed:
+        print(f"{red}{_CROSS} FAIL:{reset} {result.module} failed to import")
+        if result.error_message:
+            # Indent error message lines
+            for line in result.error_message.splitlines():
+                print(f"  {red}{_ARROW}{reset} {line}")
+        return
+
+    # Status line for successful import
+    if result.passed:
+        status = _CHECK
+        color = green
+    else:
+        status = f"{_CROSS} FAIL:"
+        color = red
+
+    time_str = format_time(result.total_ms)
+
+    # Build status message
+    msg_parts = [f"{result.module} imported in {time_str}"]
+
+    if max_ms is not None:
+        msg_parts.append(f"(budget: {format_time(max_ms)})")
+
+    if result.num_runs > 1 and result.median_ms is not None:
+        msg_parts.append(f"[median of {result.num_runs} runs]")
+
+    print(f"{color}{status}{reset} {' '.join(msg_parts)}")
+
+    # Print violations
+    for violation in result.violations:
+        print(f"  {color}{_ARROW}{reset} {violation}")
+
+    # Print top imports (only if showing details)
+    if result.imports and not quiet:
+        print()
+        print(f"Top {min(top_n, len(result.imports))} slowest imports:")
+        for i, timing in enumerate(result.top_imports(top_n), 1):
+            print(f"  {i:2}. {timing.module:<40} {format_time(timing.self_time_ms)}")
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="importguard",
+        description="Measure and enforce import-time behavior in Python projects",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # check command
+    check_parser = subparsers.add_parser(
+        "check",
+        help="Check import time and violations for a module",
+    )
+    check_parser.add_argument(
+        "module",
+        help="Python module to check (e.g., mypkg, mypkg.cli)",
+    )
+    check_parser.add_argument(
+        "--max-ms",
+        type=float,
+        metavar="MS",
+        help="Fail if import exceeds this threshold",
+    )
+    check_parser.add_argument(
+        "--ban",
+        action="append",
+        dest="banned",
+        metavar="MODULE",
+        help="Ban a module from being imported (can repeat)",
+    )
+    check_parser.add_argument(
+        "--config",
+        type=Path,
+        metavar="FILE",
+        help="Path to .importguard.toml config file",
+    )
+    check_parser.add_argument(
+        "--top",
+        type=int,
+        default=10,
+        metavar="N",
+        help="Show top N slowest imports (default: 10)",
+    )
+    check_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output results as JSON (for CI parsing)",
+    )
+    check_parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Only output on failure",
+    )
+    check_parser.add_argument(
+        "--fail-on-warning",
+        action="store_true",
+        help="Exit non-zero on warnings, not just errors",
+    )
+    check_parser.add_argument(
+        "--repeat",
+        type=int,
+        default=1,
+        metavar="K",
+        help="Run K times in fresh subprocesses, report median (reduces noise)",
+    )
+    check_parser.add_argument(
+        "--python",
+        type=str,
+        metavar="PATH",
+        help="Use specific Python interpreter (e.g., /usr/bin/python3.11)",
+    )
+
+    return parser
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    """Execute the check command."""
+    module: str = args.module
+    max_ms: float | None = args.max_ms
+    banned: list[str] = args.banned or []
+    config_path: Path | None = args.config
+    top_n: int = args.top
+    output_json: bool = args.json
+    quiet: bool = args.quiet
+    repeat: int = args.repeat
+    python_path: str | None = args.python
+
+    # Load config if specified or auto-discover
+    config: ImportGuardConfig | None = None
+    if config_path:
+        if not config_path.exists():
+            print(f"Error: Config file not found: {config_path}", file=sys.stderr)
+            return 1
+        config = load_config(config_path)
+    else:
+        found_config = find_config()
+        if found_config:
+            config = load_config(found_config)
+
+    # Merge config with CLI options
+    if config:
+        module_config = config.get_module_config(module)
+        if max_ms is None:
+            max_ms = module_config.max_ms
+        banned = list(set(banned) | module_config.banned)
+
+    # Run the check
+    result = check_import(
+        module=module,
+        max_ms=max_ms,
+        banned=set(banned) if banned else None,
+        python_path=python_path,
+        repeat=repeat,
+    )
+
+    # Output
+    if output_json:
+        print(json.dumps(result.to_dict(), indent=2))
+    else:
+        print_result(result, max_ms=max_ms, top_n=top_n, quiet=quiet)
+
+    # Exit code
+    return 0 if result.passed else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point."""
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    if args.command == "check":
+        return cmd_check(args)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

importguard/config.py

@@ -0,0 +1,199 @@
+"""Configuration loading from .importguard.toml."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    # For Python 3.9 and 3.10, we need to handle TOML differently
+    # We'll use a simple fallback that works without external deps
+    tomllib = None
+
+
+@dataclass
+class ModuleConfig:
+    """Configuration for a specific module."""
+
+    max_ms: float | None = None
+    banned: set[str] = field(default_factory=set)
+
+
+@dataclass
+class ImportGuardConfig:
+    """Full importguard configuration."""
+
+    max_total_ms: float | None = None
+    modules: dict[str, ModuleConfig] = field(default_factory=dict)
+
+    def get_module_config(self, module: str) -> ModuleConfig:
+        """Get configuration for a specific module, with inheritance."""
+        # Try exact match first
+        if module in self.modules:
+            config = self.modules[module]
+            # Apply global max if module doesn't have one
+            if config.max_ms is None and self.max_total_ms is not None:
+                config.max_ms = self.max_total_ms
+            return config
+
+        # Try parent modules
+        parts = module.split(".")
+        for i in range(len(parts) - 1, 0, -1):
+            parent = ".".join(parts[:i])
+            if parent in self.modules:
+                config = self.modules[parent]
+                if config.max_ms is None and self.max_total_ms is not None:
+                    config.max_ms = self.max_total_ms
+                return config
+
+        # Return default with global settings
+        return ModuleConfig(max_ms=self.max_total_ms)
+
+
+def _parse_toml_simple(content: str) -> dict[str, Any]:
+    """
+    Simple TOML parser for basic configs (fallback for Python < 3.11).
+
+    This handles only the subset of TOML we need:
+    - [section] headers
+    - key = value pairs (strings, numbers, arrays)
+    """
+    result: dict[str, Any] = {}
+    current_section: list[str] | None = None
+
+    for line in content.splitlines():
+        line = line.strip()
+
+        # Skip empty lines and comments
+        if not line or line.startswith("#"):
+            continue
+
+        # Section header
+        if line.startswith("[") and line.endswith("]"):
+            section_name = line[1:-1].strip()
+            current_section = section_name.split(".")
+            # Create nested structure
+            current: dict[str, Any] = result
+            for part in current_section:
+                part = part.strip('"')
+                if part not in current:
+                    current[part] = {}
+                current = current[part]
+            continue
+
+        # Key = value
+        if "=" in line:
+            key, value = line.split("=", 1)
+            key = key.strip().strip('"')
+            value = value.strip()
+
+            # Parse value
+            parsed_value: Any
+            if value.startswith('"') and value.endswith('"'):
+                parsed_value = value[1:-1]
+            elif value.startswith("[") and value.endswith("]"):
+                # Simple array parsing
+                array_content = value[1:-1]
+                if array_content.strip():
+                    items: list[str] = []
+                    for item in array_content.split(","):
+                        item = item.strip().strip('"')
+                        if item:
+                            items.append(item)
+                    parsed_value = items
+                else:
+                    parsed_value = []
+            elif value.isdigit():
+                parsed_value = int(value)
+            elif value.replace(".", "").isdigit():
+                parsed_value = float(value)
+            else:
+                parsed_value = value
+
+            # Set value in nested structure
+            if current_section:
+                current = result
+                for part in current_section:
+                    part = part.strip('"')
+                    current = current[part]
+                current[key] = parsed_value
+            else:
+                result[key] = parsed_value
+
+    return result
+
+
+def load_config(path: Path) -> ImportGuardConfig:
+    """
+    Load configuration from a .importguard.toml file.
+
+    Args:
+        path: Path to the config file
+
+    Returns:
+        ImportGuardConfig object
+    """
+    content = path.read_text()
+
+    data: dict[str, Any]
+    if tomllib is not None:
+        data = tomllib.loads(content)
+    else:
+        data = _parse_toml_simple(content)
+
+    config = ImportGuardConfig()
+
+    ig_data: dict[str, Any] = data.get("importguard", {})
+
+    # Global settings
+    if "max_total_ms" in ig_data:
+        config.max_total_ms = float(ig_data["max_total_ms"])
+
+    # Per-module budgets
+    budgets = ig_data.get("budgets", {})
+    for module, max_ms in budgets.items():
+        if module not in config.modules:
+            config.modules[module] = ModuleConfig()
+        config.modules[module].max_ms = float(max_ms)
+
+    # Per-module banned imports
+    banned = ig_data.get("banned", {})
+    for module, banned_list in banned.items():
+        if module not in config.modules:
+            config.modules[module] = ModuleConfig()
+        config.modules[module].banned = set(banned_list)
+
+    return config
+
+
+def find_config(start_path: Path | None = None) -> Path | None:
+    """
+    Find .importguard.toml by walking up from start_path.
+
+    Args:
+        start_path: Starting directory (default: current directory)
+
+    Returns:
+        Path to config file if found, None otherwise
+    """
+    if start_path is None:
+        start_path = Path.cwd()
+
+    current = start_path.resolve()
+
+    while current != current.parent:
+        config_path = current / ".importguard.toml"
+        if config_path.exists():
+            return config_path
+        current = current.parent
+
+    # Check root
+    config_path = current / ".importguard.toml"
+    if config_path.exists():
+        return config_path
+
+    return None