kicad-sch-api 0.3.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

kicad_sch_api/__init__.py

@@ -42,20 +42,27 @@ Advanced Usage:
         print(f"Found {len(issues)} validation issues")
 """
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 __author__ = "Circuit-Synth"
 __email__ = "info@circuit-synth.com"
 
 from .core.components import Component, ComponentCollection
 from .core.config import KiCADConfig, config
+from .core.types import PinInfo
 
 # Core imports for public API
 from .core.schematic import Schematic
 from .library.cache import SymbolLibraryCache, get_symbol_cache
 from .utils.validation import ValidationError, ValidationIssue
+# Commonly-used exceptions (ValidationError re-exported from utils for backward compat)
+from .core.exceptions import (
+    KiCadSchError,
+    ElementNotFoundError,
+    DuplicateElementError,
+)
 
 # Version info
-VERSION_INFO = (0, 3, 0)
+VERSION_INFO = (0, 4, 0)
 
 # Public API
 __all__ = [
@@ -63,14 +70,18 @@ __all__ = [
     "Schematic",
     "Component",
     "ComponentCollection",
+    "PinInfo",
     "SymbolLibraryCache",
     "get_symbol_cache",
     # Configuration
     "KiCADConfig",
     "config",
     # Exceptions
+    "KiCadSchError",
     "ValidationError",
     "ValidationIssue",
+    "ElementNotFoundError",
+    "DuplicateElementError",
     # Version info
     "__version__",
     "VERSION_INFO",
@@ -112,5 +123,59 @@ def create_schematic(name: str = "Untitled") -> "Schematic":
     return Schematic.create(name)
 
 
+def schematic_to_python(
+    input_path: str,
+    output_path: str,
+    template: str = 'default',
+    include_hierarchy: bool = True,
+    format_code: bool = True,
+    add_comments: bool = True
+):
+    """
+    Convert KiCad schematic to Python code (one-line convenience function).
+
+    Loads a KiCad schematic and generates executable Python code that
+    recreates it using the kicad-sch-api library.
+
+    Args:
+        input_path: Input .kicad_sch file
+        output_path: Output .py file
+        template: Code template style ('minimal', 'default', 'verbose', 'documented')
+        include_hierarchy: Include hierarchical sheets
+        format_code: Format code with Black
+        add_comments: Add explanatory comments
+
+    Returns:
+        Path to generated Python file
+
+    Raises:
+        FileNotFoundError: If input file doesn't exist
+        CodeGenerationError: If code generation fails
+
+    Example:
+        >>> import kicad_sch_api as ksa
+        >>> ksa.schematic_to_python('input.kicad_sch', 'output.py')
+        PosixPath('output.py')
+
+        >>> ksa.schematic_to_python('input.kicad_sch', 'output.py',
+        ...                         template='minimal',
+        ...                         add_comments=False)
+        PosixPath('output.py')
+    """
+    from pathlib import Path
+
+    # Load schematic
+    schematic = Schematic.load(input_path)
+
+    # Export to Python
+    return schematic.export_to_python(
+        output_path=output_path,
+        template=template,
+        include_hierarchy=include_hierarchy,
+        format_code=format_code,
+        add_comments=add_comments
+    )
+
+
 # Add convenience functions to __all__
-__all__.extend(["load_schematic", "create_schematic"])
+__all__.extend(["load_schematic", "create_schematic", "schematic_to_python"])

kicad_sch_api/cli/__init__.py

@@ -0,0 +1,45 @@
+"""
+KiCad CLI wrappers for schematic operations.
+
+This module provides Python wrappers around kicad-cli commands with automatic
+fallback to Docker when kicad-cli is not installed locally.
+
+Supported operations:
+- ERC (Electrical Rule Check)
+- Netlist export (8 formats)
+- BOM (Bill of Materials) export
+- PDF export
+- SVG export
+- DXF export
+
+Example:
+    >>> import kicad_sch_api as ksa
+    >>> sch = ksa.Schematic('circuit.kicad_sch')
+    >>> sch.run_erc()
+    >>> sch.export_netlist(format='spice')
+    >>> sch.export_bom(exclude_dnp=True)
+"""
+
+from kicad_sch_api.cli.base import (
+    ExecutionMode,
+    KiCadExecutor,
+    get_executor_info,
+    set_execution_mode,
+)
+from kicad_sch_api.cli.types import (
+    ErcFormat,
+    ErcSeverity,
+    NetlistFormat,
+    Units,
+)
+
+__all__ = [
+    "KiCadExecutor",
+    "ExecutionMode",
+    "get_executor_info",
+    "set_execution_mode",
+    "NetlistFormat",
+    "ErcFormat",
+    "ErcSeverity",
+    "Units",
+]

kicad_sch_api/cli/base.py

@@ -0,0 +1,302 @@
+"""
+Base KiCad CLI executor with Docker fallback support.
+
+This module provides the core infrastructure for executing kicad-cli commands
+either locally or via Docker containers.
+"""
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from kicad_sch_api.cli.types import ExecutionMode
+
+
+@dataclass
+class ExecutorInfo:
+    """Information about available execution modes."""
+    local_available: bool
+    local_version: Optional[str]
+    docker_available: bool
+    docker_image: str
+    active_mode: ExecutionMode
+
+
+class KiCadExecutor:
+    """
+    Core executor for KiCad CLI commands with Docker fallback.
+
+    Execution strategy:
+    1. AUTO mode (default): Try local kicad-cli, fall back to Docker
+    2. LOCAL mode: Force local kicad-cli (fail if not available)
+    3. DOCKER mode: Force Docker (fail if Docker not available)
+
+    Environment variables:
+    - KICAD_CLI_MODE: Set execution mode (auto|local|docker)
+    - KICAD_DOCKER_IMAGE: Override Docker image (default: kicad/kicad:latest)
+
+    Example:
+        >>> executor = KiCadExecutor()
+        >>> result = executor.run(['sch', 'export', 'netlist', 'circuit.kicad_sch'])
+    """
+
+    # Class-level cache for detection results
+    _local_available: Optional[bool] = None
+    _local_version: Optional[str] = None
+    _docker_available: Optional[bool] = None
+
+    def __init__(
+        self,
+        mode: ExecutionMode = "auto",
+        docker_image: str = "kicad/kicad:latest",
+        verbose: bool = False,
+    ):
+        """
+        Initialize KiCad executor.
+
+        Args:
+            mode: Execution mode (auto, local, or docker)
+            docker_image: Docker image to use
+            verbose: Print execution details
+        """
+        # Check environment variable override
+        env_mode = os.getenv("KICAD_CLI_MODE", "").lower()
+        if env_mode in ("auto", "local", "docker"):
+            mode = env_mode  # type: ignore
+
+        env_image = os.getenv("KICAD_DOCKER_IMAGE", "")
+        if env_image:
+            docker_image = env_image
+
+        self.mode = mode
+        self.docker_image = docker_image
+        self.verbose = verbose
+
+        # Detect capabilities on first use
+        if KiCadExecutor._local_available is None:
+            KiCadExecutor._detect_local()
+        if KiCadExecutor._docker_available is None:
+            KiCadExecutor._detect_docker()
+
+    @classmethod
+    def _detect_local(cls) -> None:
+        """Detect if kicad-cli is available locally."""
+        try:
+            result = subprocess.run(
+                ["kicad-cli", "version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode == 0:
+                cls._local_available = True
+                cls._local_version = result.stdout.strip()
+            else:
+                cls._local_available = False
+                cls._local_version = None
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            cls._local_available = False
+            cls._local_version = None
+
+    @classmethod
+    def _detect_docker(cls) -> None:
+        """Detect if Docker is available."""
+        try:
+            result = subprocess.run(
+                ["docker", "version"],
+                capture_output=True,
+                timeout=5,
+            )
+            cls._docker_available = result.returncode == 0
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            cls._docker_available = False
+
+    def _run_local(self, args: List[str], cwd: Optional[Path] = None) -> subprocess.CompletedProcess:
+        """Run kicad-cli locally."""
+        if not KiCadExecutor._local_available:
+            raise RuntimeError(
+                "kicad-cli not found. Install KiCad or use Docker mode.\n"
+                "Install: https://www.kicad.org/download/\n"
+                "Docker: export KICAD_CLI_MODE=docker"
+            )
+
+        cmd = ["kicad-cli"] + args
+        if self.verbose:
+            print(f"Running locally: {' '.join(cmd)}")
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+        )
+
+        return result
+
+    def _run_docker(self, args: List[str], cwd: Optional[Path] = None) -> subprocess.CompletedProcess:
+        """Run kicad-cli via Docker."""
+        if not KiCadExecutor._docker_available:
+            raise RuntimeError(
+                "Docker not found. Install Docker or use local mode.\n"
+                "Install: https://docs.docker.com/get-docker/\n"
+                "Local: Install KiCad from https://www.kicad.org/download/"
+            )
+
+        # Determine working directory
+        if cwd:
+            work_dir = cwd.resolve()
+        else:
+            work_dir = Path.cwd()
+
+        # Build Docker command
+        docker_cmd = [
+            "docker", "run",
+            "--rm",  # Remove container after execution
+            "-v", f"{work_dir}:/workspace",  # Mount working directory
+            "-w", "/workspace",  # Set working directory
+        ]
+
+        # Add user mapping on Linux/Mac to avoid permission issues
+        if os.name != "nt":  # Not Windows
+            uid = os.getuid()
+            gid = os.getgid()
+            docker_cmd.extend(["--user", f"{uid}:{gid}"])
+
+        docker_cmd.extend([
+            self.docker_image,
+            "kicad-cli",
+        ] + args)
+
+        if self.verbose:
+            print(f"Running via Docker: {' '.join(docker_cmd)}")
+
+        # Check if image exists, pull if needed
+        self._ensure_docker_image()
+
+        result = subprocess.run(
+            docker_cmd,
+            capture_output=True,
+            text=True,
+        )
+
+        return result
+
+    def _ensure_docker_image(self) -> None:
+        """Ensure Docker image is available, pull if needed."""
+        # Check if image exists
+        result = subprocess.run(
+            ["docker", "image", "inspect", self.docker_image],
+            capture_output=True,
+        )
+
+        if result.returncode != 0:
+            # Image not found, pull it
+            if self.verbose:
+                print(f"Pulling Docker image: {self.docker_image}")
+
+            pull_result = subprocess.run(
+                ["docker", "pull", self.docker_image],
+                capture_output=not self.verbose,
+            )
+
+            if pull_result.returncode != 0:
+                raise RuntimeError(f"Failed to pull Docker image: {self.docker_image}")
+
+    def run(
+        self,
+        args: List[str],
+        cwd: Optional[Path] = None,
+        check: bool = True,
+    ) -> subprocess.CompletedProcess:
+        """
+        Execute kicad-cli command.
+
+        Args:
+            args: Command arguments (e.g., ['sch', 'export', 'netlist', 'file.kicad_sch'])
+            cwd: Working directory (default: current directory)
+            check: Raise exception on non-zero exit code
+
+        Returns:
+            CompletedProcess with stdout, stderr, returncode
+
+        Raises:
+            RuntimeError: If execution fails or kicad-cli unavailable
+        """
+        if self.mode == "local":
+            result = self._run_local(args, cwd)
+        elif self.mode == "docker":
+            result = self._run_docker(args, cwd)
+        else:  # auto mode
+            if KiCadExecutor._local_available:
+                if self.verbose:
+                    print(f"Using local KiCad CLI ({KiCadExecutor._local_version})")
+                result = self._run_local(args, cwd)
+            elif KiCadExecutor._docker_available:
+                if self.verbose:
+                    print("Local KiCad CLI not found, using Docker")
+                result = self._run_docker(args, cwd)
+            else:
+                raise RuntimeError(
+                    "KiCad CLI not available in any mode.\n\n"
+                    "Install options:\n"
+                    "1. Install KiCad: https://www.kicad.org/download/\n"
+                    "2. Install Docker: https://docs.docker.com/get-docker/"
+                )
+
+        if check and result.returncode != 0:
+            error_msg = result.stderr if result.stderr else result.stdout
+            raise RuntimeError(f"KiCad CLI command failed:\n{error_msg}")
+
+        return result
+
+    @classmethod
+    def get_info(cls) -> ExecutorInfo:
+        """Get information about available execution modes."""
+        if cls._local_available is None:
+            cls._detect_local()
+        if cls._docker_available is None:
+            cls._detect_docker()
+
+        # Determine active mode
+        env_mode = os.getenv("KICAD_CLI_MODE", "auto").lower()
+        if env_mode not in ("auto", "local", "docker"):
+            env_mode = "auto"
+
+        return ExecutorInfo(
+            local_available=cls._local_available or False,
+            local_version=cls._local_version,
+            docker_available=cls._docker_available or False,
+            docker_image=os.getenv("KICAD_DOCKER_IMAGE", "kicad/kicad:latest"),
+            active_mode=env_mode,  # type: ignore
+        )
+
+
+# Convenience functions
+def get_executor_info() -> ExecutorInfo:
+    """
+    Get information about KiCad CLI availability.
+
+    Returns:
+        ExecutorInfo with details about local and Docker availability
+
+    Example:
+        >>> info = get_executor_info()
+        >>> print(f"Local: {info.local_available}, Docker: {info.docker_available}")
+    """
+    return KiCadExecutor.get_info()
+
+
+def set_execution_mode(mode: ExecutionMode) -> None:
+    """
+    Set the execution mode for all KiCad CLI operations.
+
+    Args:
+        mode: Execution mode (auto, local, or docker)
+
+    Example:
+        >>> set_execution_mode('docker')  # Force Docker mode
+    """
+    os.environ["KICAD_CLI_MODE"] = mode

kicad_sch_api/cli/bom.py

@@ -0,0 +1,164 @@
+"""Bill of Materials (BOM) export functionality using kicad-cli."""
+
+from pathlib import Path
+from typing import List, Optional
+
+from kicad_sch_api.cli.base import KiCadExecutor
+
+
+def export_bom(
+    schematic_path: Path,
+    output_path: Optional[Path] = None,
+    preset: Optional[str] = None,
+    format_preset: Optional[str] = None,
+    fields: Optional[List[str]] = None,
+    labels: Optional[List[str]] = None,
+    group_by: Optional[List[str]] = None,
+    sort_field: str = "Reference",
+    sort_asc: bool = True,
+    filter: Optional[str] = None,
+    exclude_dnp: bool = False,
+    include_excluded_from_bom: bool = False,
+    field_delimiter: str = ",",
+    string_delimiter: str = '"',
+    ref_delimiter: str = ",",
+    ref_range_delimiter: str = "",
+    keep_tabs: bool = False,
+    keep_line_breaks: bool = False,
+    executor: Optional[KiCadExecutor] = None,
+) -> Path:
+    """
+    Export Bill of Materials (BOM) from schematic using kicad-cli.
+
+    Generates a CSV file with component information, suitable for manufacturing
+    and procurement.
+
+    Args:
+        schematic_path: Path to .kicad_sch file
+        output_path: Output BOM path (auto-generated if None)
+        preset: Named BOM preset from schematic (e.g., "Grouped By Value")
+        format_preset: Named BOM format preset (e.g., "CSV")
+        fields: List of fields to export (default: Reference, Value, Footprint, Qty, DNP)
+        labels: List of labels for exported fields
+        group_by: Fields to group references by when values match
+        sort_field: Field name to sort by (default: "Reference")
+        sort_asc: Sort ascending (True) or descending (False)
+        filter: Filter string to remove output lines
+        exclude_dnp: Exclude components marked Do-Not-Populate
+        include_excluded_from_bom: Include components marked 'Exclude from BOM'
+        field_delimiter: Separator between fields/columns (default: ",")
+        string_delimiter: Character to surround fields with (default: '"')
+        ref_delimiter: Character between individual references (default: ",")
+        ref_range_delimiter: Character for reference ranges (default: "", use "-" for ranges like "R1-R5")
+        keep_tabs: Keep tab characters from input fields
+        keep_line_breaks: Keep line break characters from input fields
+        executor: Custom KiCadExecutor instance (creates default if None)
+
+    Returns:
+        Path to generated BOM file
+
+    Raises:
+        RuntimeError: If kicad-cli not found or BOM generation fails
+        FileNotFoundError: If schematic file doesn't exist
+
+    Example:
+        >>> from pathlib import Path
+        >>> bom = export_bom(
+        ...     Path('circuit.kicad_sch'),
+        ...     fields=['Reference', 'Value', 'Footprint', 'MPN'],
+        ...     group_by=['Value', 'Footprint'],
+        ...     exclude_dnp=True,
+        ... )
+        >>> print(f"BOM: {bom}")
+
+    Common use cases:
+        # Simple BOM with default fields
+        >>> export_bom(Path('circuit.kicad_sch'))
+
+        # Manufacturing BOM (exclude DNP, group by value)
+        >>> export_bom(
+        ...     Path('circuit.kicad_sch'),
+        ...     group_by=['Value', 'Footprint'],
+        ...     exclude_dnp=True,
+        ... )
+
+        # BOM with manufacturer part numbers
+        >>> export_bom(
+        ...     Path('circuit.kicad_sch'),
+        ...     fields=['Reference', 'Value', 'Footprint', 'MPN', 'Manufacturer'],
+        ...     group_by=['MPN'],
+        ... )
+    """
+    schematic_path = Path(schematic_path)
+
+    if not schematic_path.exists():
+        raise FileNotFoundError(f"Schematic not found: {schematic_path}")
+
+    # Auto-generate output path if not provided
+    if output_path is None:
+        output_path = schematic_path.with_suffix(".csv")
+    else:
+        output_path = Path(output_path)
+
+    # Create executor if not provided
+    if executor is None:
+        executor = KiCadExecutor()
+
+    # Build command
+    args = [
+        "sch", "export", "bom",
+        "--output", str(output_path),
+    ]
+
+    # Add optional parameters
+    if preset:
+        args.extend(["--preset", preset])
+
+    if format_preset:
+        args.extend(["--format-preset", format_preset])
+
+    if fields:
+        args.extend(["--fields", ",".join(fields)])
+
+    if labels:
+        args.extend(["--labels", ",".join(labels)])
+
+    if group_by:
+        args.extend(["--group-by", ",".join(group_by)])
+
+    if sort_field:
+        args.extend(["--sort-field", sort_field])
+
+    if sort_asc:
+        args.append("--sort-asc")
+
+    if filter:
+        args.extend(["--filter", filter])
+
+    if exclude_dnp:
+        args.append("--exclude-dnp")
+
+    if include_excluded_from_bom:
+        args.append("--include-excluded-from-bom")
+
+    # Delimiter options
+    args.extend(["--field-delimiter", field_delimiter])
+    args.extend(["--string-delimiter", string_delimiter])
+    args.extend(["--ref-delimiter", ref_delimiter])
+
+    if ref_range_delimiter:
+        args.extend(["--ref-range-delimiter", ref_range_delimiter])
+
+    if keep_tabs:
+        args.append("--keep-tabs")
+
+    if keep_line_breaks:
+        args.append("--keep-line-breaks")
+
+    # Add schematic path
+    args.append(str(schematic_path))
+
+    # Execute command
+    executor.run(args, cwd=schematic_path.parent)
+
+    return output_path