python-infrakit-dev 0.1.0__py3-none-any.whl

infrakit/core/logger/setup.py

@@ -0,0 +1,314 @@
+"""
+infrakit.core.logger.setup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Single entry point for configuring infrakit logging.
+
+Call setup() once at application startup. Every module then calls
+get_logger(__name__) — no configuration there.
+
+    from infrakit.core.logger import setup, get_logger
+
+    # Files only
+    setup(strategy="date_level", stream=None)
+
+    # Stream only
+    setup(strategy=None, stream="stdout")
+
+    # Files + stream (most common in prod)
+    setup(strategy="date_level", stream="stdout")
+
+    # Isolated session — new subfolder per run
+    setup(strategy="date_level", stream="stdout", session=True)
+    setup(strategy="date_level", stream="stdout", session="deploy-v1.2.0")
+
+    log = get_logger(__name__)
+    log.info("App started")
+
+Env var overrides (take priority over kwargs):
+    INFRAKIT_LOG_LEVEL      DEBUG | INFO | WARNING | ERROR | CRITICAL
+    INFRAKIT_LOG_FORMAT     human | json
+    INFRAKIT_LOG_FILE_FMT   human | json
+    INFRAKIT_LOG_STRATEGY   file | date | level | date_level | date_size | None
+    INFRAKIT_LOG_STREAM     stdout | stderr | none
+    INFRAKIT_LOG_RETENTION  <int days>
+    INFRAKIT_LOG_SESSION    <name> | true | false
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from infrakit.core.logger.handlers import FILE_STRATEGIES, build_handlers
+from infrakit.core.logger.retention import sweep
+
+
+# ---------------------------------------------------------------------------
+# Module-level state
+# ---------------------------------------------------------------------------
+
+_configured: bool = False
+_ROOT_LOGGER = "infrakit"
+
+_VALID_LEVELS  = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+_VALID_FORMATS = {"human", "json"}
+
+_DEFAULT_LEVEL     = "INFO"
+_DEFAULT_FMT       = "human"
+_DEFAULT_FILE_FMT  = "json"
+_DEFAULT_STRATEGY  = "date_level"
+_DEFAULT_STREAM    = "stdout"
+_DEFAULT_LOG_DIR   = "logs"
+_DEFAULT_RETENTION = 30
+_DEFAULT_MAX_BYTES = 10 * 1024 * 1024   # 10 MB
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def setup(
+    *,
+    level: str = _DEFAULT_LEVEL,
+    fmt: str = _DEFAULT_FMT,
+    file_fmt: str = _DEFAULT_FILE_FMT,
+    strategy: str | None = _DEFAULT_STRATEGY,
+    stream: str | None = _DEFAULT_STREAM,
+    log_dir: str | Path = _DEFAULT_LOG_DIR,
+    session: bool | str | None = None,
+    retention: int = _DEFAULT_RETENTION,
+    max_bytes: int = _DEFAULT_MAX_BYTES,
+    force: bool = False,
+) -> None:
+    """Configure infrakit logging. Call once at application startup.
+
+    Parameters
+    ----------
+    level:
+        Minimum log level: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``,
+        ``CRITICAL``. Overridden by ``INFRAKIT_LOG_LEVEL``.
+    fmt:
+        Format for stream output: ``"human"`` (default) or ``"json"``.
+        Overridden by ``INFRAKIT_LOG_FORMAT``.
+    file_fmt:
+        Format for file output: ``"json"`` (default) or ``"human"``.
+        JSON is recommended — easier to parse in log aggregators.
+        Overridden by ``INFRAKIT_LOG_FILE_FMT``.
+    strategy:
+        File storage strategy — controls folder + filename layout:
+
+        ``"file"``        logs/app.log  (size-rotating)
+        ``"date"``        logs/app.YYYY-MM-DD.log
+        ``"level"``       logs/<level>/<level>.log
+        ``"date_level"``  logs/<level>/<level>.YYYY-MM-DD.log
+        ``"date_size"``   logs/app.YYYY-MM-DD.log + size cap
+        ``None``          no file output
+
+        Overridden by ``INFRAKIT_LOG_STRATEGY``.
+    stream:
+        Stream to mirror all logs to, independent of strategy:
+
+        ``"stdout"``  write to stdout
+        ``"stderr"``  write to stderr
+        ``None``      no stream output
+
+        Overridden by ``INFRAKIT_LOG_STREAM``.
+    log_dir:
+        Base directory for file strategies. Created automatically.
+    session:
+        Isolate this run in its own subfolder inside *log_dir*:
+
+        ``True``        auto-generate timestamp folder:
+                        logs/2025-03-22_14-32-01/
+        ``"my-label"``  use named folder:
+                        logs/my-label/
+        ``None``        no isolation, write directly into log_dir (default)
+
+        Overridden by ``INFRAKIT_LOG_SESSION``.
+    retention:
+        Days to keep log files. Files older than this are deleted on startup.
+        Pass ``0`` to keep all files forever.
+        Overridden by ``INFRAKIT_LOG_RETENTION``.
+    max_bytes:
+        Max file size before rotation (for ``file`` and ``date_size``).
+        Default: 10 MB.
+    force:
+        Tear down existing handlers and reconfigure from scratch.
+        Required when calling setup() more than once (e.g. in tests).
+    """
+    global _configured
+
+    if _configured and not force:
+        return
+
+    # --- Resolve env var overrides ---
+    level    = _env_str("INFRAKIT_LOG_LEVEL",    level).upper()
+    fmt      = _env_str("INFRAKIT_LOG_FORMAT",   fmt)
+    file_fmt = _env_str("INFRAKIT_LOG_FILE_FMT", file_fmt)
+    retention = _env_int("INFRAKIT_LOG_RETENTION", retention)
+
+    raw_strategy = _env_str("INFRAKIT_LOG_STRATEGY", "" if strategy is None else strategy)
+    strategy = None if raw_strategy.lower() in ("none", "") else raw_strategy
+
+    raw_stream = _env_str("INFRAKIT_LOG_STREAM", "" if stream is None else stream)
+    stream = None if raw_stream.lower() in ("none", "") else raw_stream
+
+    raw_session = os.environ.get("INFRAKIT_LOG_SESSION", "").strip()
+    if raw_session:
+        if raw_session.lower() == "true":
+            session = True
+        elif raw_session.lower() in ("false", "none", ""):
+            session = None
+        else:
+            session = raw_session
+
+    # --- Validate ---
+    if level not in _VALID_LEVELS:
+        raise ValueError(
+            f"Invalid log level '{level}'. "
+            f"Choose one of: {', '.join(sorted(_VALID_LEVELS))}"
+        )
+    if fmt not in _VALID_FORMATS:
+        raise ValueError(f"Invalid log format '{fmt}'. Choose 'human' or 'json'.")
+    if file_fmt not in _VALID_FORMATS:
+        raise ValueError(f"Invalid file_fmt '{file_fmt}'. Choose 'human' or 'json'.")
+    if strategy is not None and strategy not in FILE_STRATEGIES:
+        raise ValueError(
+            f"Invalid strategy '{strategy}'. "
+            f"Valid: {', '.join(sorted(FILE_STRATEGIES))} or None."
+        )
+    if stream not in {None, "stdout", "stderr"}:
+        raise ValueError(
+            f"Invalid stream '{stream}'. Choose 'stdout', 'stderr', or None."
+        )
+    if strategy is None and stream is None:
+        raise ValueError(
+            "At least one of strategy or stream must be set — "
+            "otherwise nothing will be logged anywhere."
+        )
+
+    numeric_level = getattr(logging, level)
+    log_dir = Path(log_dir)
+
+    # --- Resolve session subfolder ---
+    resolved_log_dir = _resolve_session_dir(log_dir, session)
+
+    # --- Retention sweep (runs before handlers attach, on root log_dir) ---
+    if strategy is not None and retention > 0:
+        try:
+            sweep(log_dir, retention_days=retention)
+        except Exception as exc:
+            print(
+                f"[infrakit.logger] Retention sweep failed: {exc}",
+                file=sys.stderr,
+            )
+
+    # --- Configure root logger ---
+    root = logging.getLogger(_ROOT_LOGGER)
+
+    if force:
+        for h in root.handlers[:]:
+            h.close()
+            root.removeHandler(h)
+
+    root.setLevel(numeric_level)
+    root.propagate = False
+
+    # --- Build and attach handlers ---
+    handlers = build_handlers(
+        strategy=strategy,
+        stream=stream,
+        log_dir=resolved_log_dir,
+        fmt=fmt,
+        file_fmt=file_fmt,
+        max_bytes=max_bytes,
+        level=numeric_level,
+    )
+    for h in handlers:
+        root.addHandler(h)
+
+    _configured = True
+
+    root.debug(
+        "Logger configured: level=%s, fmt=%s, file_fmt=%s, "
+        "strategy=%s, stream=%s, log_dir='%s'",
+        level, fmt, file_fmt, strategy, stream, resolved_log_dir,
+    )
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a stdlib Logger for *name*.
+
+    Always call as ``get_logger(__name__)``.
+
+    If setup() has not been called, a minimal stderr handler is added
+    automatically so logs are never silently swallowed.
+    """
+    if not _configured:
+        _bootstrap()
+    return logging.getLogger(name)
+
+
+def reset() -> None:
+    """Tear down all handlers and reset configured state.
+
+    For use in tests only — lets each test start with a clean slate.
+    """
+    global _configured
+    root = logging.getLogger(_ROOT_LOGGER)
+    for h in root.handlers[:]:
+        h.close()
+        root.removeHandler(h)
+    _configured = False
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _resolve_session_dir(log_dir: Path, session: bool | str | None) -> Path:
+    """Return the effective log directory, incorporating the session subfolder.
+
+    session=None       → log_dir/
+    session=True       → log_dir/2025-03-22_14-32-01/
+    session="my-run"   → log_dir/my-run/
+    """
+    if session is None:
+        return log_dir
+    if session is True:
+        ts = datetime.now(tz=timezone.utc).strftime("%Y-%m-%d_%H-%M-%S")
+        return log_dir / ts
+    # String label — sanitise to avoid path traversal.
+    # Split on both separators, drop any ".." or "." components, rejoin
+    # with "-" so "../../evil" becomes "evil" and "../run" becomes "run".
+    raw = str(session).replace("\\", "/")
+    parts = [p for p in raw.split("/") if p and p not in ("..", ".")]
+    safe = "-".join(parts) if parts else "session"
+    return log_dir / safe
+
+
+def _bootstrap() -> None:
+    """Minimal fallback — add a WARNING stderr handler if setup() not called."""
+    root = logging.getLogger(_ROOT_LOGGER)
+    if not root.handlers:
+        h = logging.StreamHandler(sys.stderr)
+        h.setLevel(logging.WARNING)
+        root.addHandler(h)
+        root.setLevel(logging.WARNING)
+
+
+def _env_str(key: str, default: str) -> str:
+    return os.environ.get(key, "").strip() or default
+
+
+def _env_int(key: str, default: int) -> int:
+    raw = os.environ.get(key, "").strip()
+    if not raw:
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default

infrakit/deps/__init__.py

@@ -0,0 +1,239 @@
+"""
+infrakit.deps
+~~~~~~~~~~~~~
+Dependency management module for infrakit.
+
+Public API
+----------
+scan(root, ...)         → ScanResult
+export(root, ...)       → exports used deps to file
+check(packages, ...)    → HealthReport
+clean(root, ...)        → CleanResult
+optimise(root, ...)     → list[OptimizeResult]
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+from typing import Optional
+
+from infrakit.deps.scanner import ScanResult, scan_project
+from infrakit.deps.depfile import (
+    DepFile,
+    find_dep_files,
+    all_declared_packages,
+    write_requirements,
+    update_requirements_inplace,
+    update_pyproject_inplace,
+)
+from .health import HealthReport, run_health_check
+from infrakit.deps.clean import CleanResult, clean_environment
+from infrakit.deps.optimizer import OptimizeResult, optimise_project
+
+
+# ---------------------------------------------------------------------------
+# Gitignore integration
+# ---------------------------------------------------------------------------
+
+def _build_gitignore_filter(root: Path):
+    """
+    Returns a callable(rel_posix: str, parts: tuple) → bool that returns
+    True when a path should be excluded.
+
+    Tries to reuse infrakit's existing module-tree gitignore logic first;
+    falls back to a simple pattern matcher.
+
+    The filter receives:
+      rel_posix — forward-slash relative path string, e.g. "ignored/secret.py"
+      parts     — tuple of path components, e.g. ("ignored", "secret.py")
+    """
+    try:
+        from infrakit.module.tree import build_gitignore_filter as _ext  # type: ignore
+
+        _inner = _ext(root)
+
+        def _wrapped(rel_posix: str, parts: tuple) -> bool:
+            # The existing infrakit filter expects a Path object
+            return _inner(root / Path(rel_posix))
+
+        return _wrapped
+    except ImportError:
+        pass
+
+    # ── Fallback: simple .gitignore parser ────────────────────────────────
+    gitignore = root / ".gitignore"
+    if not gitignore.exists():
+        return None
+
+    patterns: list[str] = []
+    for line in gitignore.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line and not line.startswith("#"):
+            # Strip trailing slash — we'll check directory components directly
+            patterns.append(line.rstrip("/"))
+
+    if not patterns:
+        return None
+
+    def _filter(rel_posix: str, parts: tuple) -> bool:
+        # Check each component of the path against all patterns.
+        # This correctly handles "ignored/" matching any directory named "ignored"
+        # regardless of OS path separator.
+        for pat in patterns:
+            # Match against full relative path (forward slashes)
+            if fnmatch.fnmatch(rel_posix, pat):
+                return True
+            # Match against filename
+            if parts and fnmatch.fnmatch(parts[-1], pat):
+                return True
+            # Match against each directory component (handles "ignored/" patterns)
+            for part in parts[:-1]:
+                if fnmatch.fnmatch(part, pat):
+                    return True
+        return False
+
+    return _filter
+
+
+# ---------------------------------------------------------------------------
+# High-level API
+# ---------------------------------------------------------------------------
+
+def scan(
+    root: Path,
+    include_notebooks: bool = False,
+    use_gitignore: bool = True,
+) -> ScanResult:
+    """Scan *root* for Python dependencies."""
+    gi_filter = _build_gitignore_filter(root) if use_gitignore else None
+    return scan_project(root, include_notebooks=include_notebooks, gitignore_filter=gi_filter)
+
+
+def export(
+    root: Path,
+    output: Optional[Path] = None,
+    inplace: bool = False,
+    keep_versions: bool = True,
+    include_notebooks: bool = False,
+    use_gitignore: bool = True,
+) -> tuple[ScanResult, list[DepFile]]:
+    """
+    Scan project and export only used dependencies.
+
+    Parameters
+    ----------
+    root:
+        Project root directory.
+    output:
+        Path for new file to write (when inplace=False).
+    inplace:
+        When True, updates existing dep files in-place.
+    keep_versions:
+        Preserve version specifiers from existing dep files.
+    include_notebooks:
+        Also scan .ipynb files.
+    use_gitignore:
+        Skip files matched by .gitignore.
+    """
+    result = scan(root, include_notebooks=include_notebooks, use_gitignore=use_gitignore)
+    dep_files = find_dep_files(root)
+    declared = all_declared_packages(dep_files)
+
+    used_normalised = {
+        pkg.lower().replace("_", "-")
+        for pkg in result.used_packages
+    }
+
+    if inplace:
+        for df in dep_files:
+            if df.format == "requirements":
+                update_requirements_inplace(df, used_normalised)
+            elif df.format == "pyproject":
+                update_pyproject_inplace(df, used_normalised)
+    elif output:
+        write_requirements(
+            packages=list(result.used_packages.keys()),
+            declared=declared,
+            output_path=output,
+            keep_versions=keep_versions,
+        )
+
+    return result, dep_files
+
+
+def check(
+    root: Optional[Path] = None,
+    packages: Optional[list[str]] = None,
+    outdated: bool = True,
+    security: bool = True,
+    licenses: bool = True,
+) -> HealthReport:
+    """
+    Run health checks on packages.
+    If *packages* is None and *root* is given, scans root first.
+    """
+    if packages is None:
+        if root is None:
+            raise ValueError("Provide either root or packages")
+        result = scan(root)
+        packages = list(result.used_packages.keys())
+
+    return run_health_check(
+        packages=packages,
+        check_outdated_flag=outdated,
+        check_vulns_flag=security,
+        check_licenses_flag=licenses,
+    )
+
+
+def clean(
+    root: Path,
+    protected: Optional[set[str]] = None,
+    dry_run: bool = True,
+) -> CleanResult:
+    """
+    Find and optionally remove unused packages from the venv.
+    Always dry-run by default — pass dry_run=False to actually uninstall.
+    """
+    result = scan(root)
+    dep_files = find_dep_files(root)
+    declared = all_declared_packages(dep_files)
+
+    return clean_environment(
+        used_packages=set(result.used_packages.keys()),
+        declared_packages={d.name for d in declared.values()},
+        protected=protected,
+        dry_run=dry_run,
+    )
+
+
+def optimise(
+    root: Path,
+    files: Optional[list[Path]] = None,
+    convert_to: Optional[str] = None,
+    use_isort: bool = True,
+    dry_run: bool = False,
+) -> list[OptimizeResult]:
+    """Optimise imports across the project."""
+    local_pkgs: set[str] = set()
+    for p in root.iterdir():
+        if p.is_dir() and (p / "__init__.py").exists():
+            local_pkgs.add(p.name)
+        if p.is_file() and p.suffix == ".py":
+            local_pkgs.add(p.stem)
+
+    return optimise_project(
+        root=root,
+        files=files,
+        local_packages=local_pkgs,
+        convert_to=convert_to,
+        use_isort=use_isort,
+        dry_run=dry_run,
+    )
+
+
+__all__ = [
+    "scan", "export", "check", "clean", "optimise",
+    "ScanResult", "HealthReport", "CleanResult", "OptimizeResult",
+]

infrakit/deps/clean.py

@@ -0,0 +1,141 @@
+"""
+infrakit.deps.clean
+~~~~~~~~~~~~~~~~~~~~
+Remove unused packages from the active virtual environment.
+Never touches dependency files — that is the user's job via `ik deps export`.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from typing import Optional
+
+from infrakit.deps.health import get_all_installed
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class CleanResult:
+    to_remove: list[str] = field(default_factory=list)
+    removed: list[str] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    dry_run: bool = True
+
+
+# ---------------------------------------------------------------------------
+# Protected / never-uninstall packages
+# These are pip / setuptools / wheel and infrakit itself.
+# ---------------------------------------------------------------------------
+
+_ALWAYS_KEEP: frozenset[str] = frozenset({
+    "pip", "setuptools", "wheel", "pkg-resources", "pkg_resources",
+    "distribute", "infrakit",
+    # Common tools users always want
+    "build", "twine", "flit", "hatch", "hatchling", "poetry",
+    "pip-tools", "pip_tools",
+})
+
+
+def _normalise(name: str) -> str:
+    return name.lower().replace("_", "-")
+
+
+# ---------------------------------------------------------------------------
+# Core logic
+# ---------------------------------------------------------------------------
+
+def compute_removable(
+    used_packages: set[str],   # pip names actually used in code
+    declared_packages: set[str],   # pip names in dep file
+    protected: Optional[set[str]] = None,
+) -> list[str]:
+    """
+    Return a list of installed packages that are:
+      - NOT in used_packages
+      - NOT in declared_packages (user explicitly declared = keep)
+      - NOT in _ALWAYS_KEEP
+      - NOT protected by the caller
+    """
+    installed = get_all_installed()
+    extra_protect = {_normalise(p) for p in (protected or set())}
+    used_norm = {_normalise(p) for p in used_packages}
+    declared_norm = {_normalise(p) for p in declared_packages}
+    keep = {_normalise(p) for p in _ALWAYS_KEEP} | extra_protect
+
+    removable: list[str] = []
+    for pkg_name in installed:
+        norm = _normalise(pkg_name)
+        if norm in keep:
+            continue
+        if norm in used_norm or norm in declared_norm:
+            continue
+        removable.append(pkg_name)
+
+    return sorted(removable, key=str.lower)
+
+
+def uninstall_packages(
+    packages: list[str],
+    dry_run: bool = True,
+) -> CleanResult:
+    """
+    Uninstall packages from the current Python environment.
+    When dry_run=True, only reports what would be removed.
+    """
+    result = CleanResult(to_remove=packages, dry_run=dry_run)
+
+    if dry_run or not packages:
+        return result
+
+    for pkg in packages:
+        try:
+            proc = subprocess.run(
+                [sys.executable, "-m", "pip", "uninstall", "-y", pkg],
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+            if proc.returncode == 0:
+                result.removed.append(pkg)
+            else:
+                err = proc.stderr.strip() or proc.stdout.strip()
+                result.errors.append(f"{pkg}: {err}")
+                result.skipped.append(pkg)
+        except subprocess.TimeoutExpired:
+            result.errors.append(f"{pkg}: uninstall timed out")
+            result.skipped.append(pkg)
+        except Exception as exc:
+            result.errors.append(f"{pkg}: {exc}")
+            result.skipped.append(pkg)
+
+    return result
+
+
+def clean_environment(
+    used_packages: set[str],
+    declared_packages: set[str],
+    protected: Optional[set[str]] = None,
+    dry_run: bool = True,
+) -> CleanResult:
+    """
+    High-level entry: compute what to remove and optionally remove it.
+
+    Parameters
+    ----------
+    used_packages:
+        Packages confirmed used in source code (from scanner).
+    declared_packages:
+        Packages explicitly declared in requirements.txt / pyproject.toml.
+    protected:
+        Additional package names the caller wants to keep regardless.
+    dry_run:
+        When True (default), only compute + report — don't uninstall.
+    """
+    removable = compute_removable(used_packages, declared_packages, protected)
+    return uninstall_packages(removable, dry_run=dry_run)