kicad-sch-api 0.4.0__py3-none-any.whl → 0.4.2__py3-none-any.whl

kicad_sch_api/cli/erc.py

@@ -0,0 +1,229 @@
+"""Electrical Rule Check (ERC) functionality using kicad-cli."""
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from kicad_sch_api.cli.base import KiCadExecutor
+from kicad_sch_api.cli.types import ErcFormat, ErcSeverity, Units
+
+
+@dataclass
+class ErcViolation:
+    """Represents a single ERC violation."""
+    severity: str
+    type: str
+    description: str
+    sheet: str
+    position: Optional[Dict[str, float]] = None
+
+
+@dataclass
+class ErcReport:
+    """ERC report with violations and summary."""
+    violations: List[ErcViolation]
+    error_count: int
+    warning_count: int
+    exclusion_count: int
+    schematic_path: Path
+    raw_output: str
+
+    def has_errors(self) -> bool:
+        """Check if report contains any errors."""
+        return self.error_count > 0
+
+    def has_warnings(self) -> bool:
+        """Check if report contains any warnings."""
+        return self.warning_count > 0
+
+    def has_violations(self) -> bool:
+        """Check if report contains any violations."""
+        return len(self.violations) > 0
+
+    def get_errors(self) -> List[ErcViolation]:
+        """Get all error-level violations."""
+        return [v for v in self.violations if v.severity == "error"]
+
+    def get_warnings(self) -> List[ErcViolation]:
+        """Get all warning-level violations."""
+        return [v for v in self.violations if v.severity == "warning"]
+
+
+def run_erc(
+    schematic_path: Path,
+    output_path: Optional[Path] = None,
+    format: ErcFormat = "json",
+    severity: ErcSeverity = "all",
+    units: Units = "mm",
+    exit_code_violations: bool = False,
+    variables: Optional[Dict[str, str]] = None,
+    executor: Optional[KiCadExecutor] = None,
+) -> ErcReport:
+    """
+    Run Electrical Rule Check (ERC) on schematic using kicad-cli.
+
+    Validates schematic for electrical errors like unconnected pins,
+    conflicting drivers, etc.
+
+    Args:
+        schematic_path: Path to .kicad_sch file
+        output_path: Output report path (auto-generated if None)
+        format: Report format ('json' or 'report')
+        severity: Severity levels to report ('all', 'error', 'warning', 'exclusions')
+        units: Measurement units for coordinates ('mm', 'in', 'mils')
+        exit_code_violations: Return non-zero exit code if violations exist
+        variables: Project variables to override (key=value pairs)
+        executor: Custom KiCadExecutor instance (creates default if None)
+
+    Returns:
+        ErcReport with violations and summary
+
+    Raises:
+        RuntimeError: If kicad-cli not found or ERC fails
+        FileNotFoundError: If schematic file doesn't exist
+
+    Example:
+        >>> from pathlib import Path
+        >>> report = run_erc(Path('circuit.kicad_sch'))
+        >>> if report.has_errors():
+        ...     print(f"Found {report.error_count} errors:")
+        ...     for error in report.get_errors():
+        ...         print(f"  - {error.description}")
+
+        >>> # Check for specific severity
+        >>> report = run_erc(
+        ...     Path('circuit.kicad_sch'),
+        ...     severity='error',  # Only errors
+        ... )
+
+        >>> # Generate human-readable report
+        >>> report = run_erc(
+        ...     Path('circuit.kicad_sch'),
+        ...     format='report',
+        ... )
+        >>> print(report.raw_output)
+    """
+    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:
+        ext = ".json" if format == "json" else ".rpt"
+        output_path = schematic_path.with_stem(f"{schematic_path.stem}_erc").with_suffix(ext)
+    else:
+        output_path = Path(output_path)
+
+    # Create executor if not provided
+    if executor is None:
+        executor = KiCadExecutor()
+
+    # Build command
+    args = [
+        "sch", "erc",
+        "--output", str(output_path),
+        "--format", format,
+        "--units", units,
+    ]
+
+    # Add severity flags
+    if severity == "all":
+        args.append("--severity-all")
+    elif severity == "error":
+        args.append("--severity-error")
+    elif severity == "warning":
+        args.append("--severity-warning")
+    elif severity == "exclusions":
+        args.append("--severity-exclusions")
+
+    # Add optional parameters
+    if exit_code_violations:
+        args.append("--exit-code-violations")
+
+    if variables:
+        for key, value in variables.items():
+            args.extend(["--define-var", f"{key}={value}"])
+
+    # Add schematic path
+    args.append(str(schematic_path))
+
+    # Execute command (don't check return code if exit_code_violations is True)
+    result = executor.run(args, cwd=schematic_path.parent, check=not exit_code_violations)
+
+    # Read output file
+    output_content = output_path.read_text()
+
+    # Parse report
+    if format == "json":
+        report = _parse_json_report(output_content, schematic_path)
+    else:
+        report = _parse_text_report(output_content, schematic_path)
+
+    return report
+
+
+def _parse_json_report(content: str, schematic_path: Path) -> ErcReport:
+    """Parse JSON ERC report."""
+    try:
+        data = json.loads(content)
+    except json.JSONDecodeError:
+        # If JSON parsing fails, return empty report
+        return ErcReport(
+            violations=[],
+            error_count=0,
+            warning_count=0,
+            exclusion_count=0,
+            schematic_path=schematic_path,
+            raw_output=content,
+        )
+
+    violations = []
+    error_count = 0
+    warning_count = 0
+    exclusion_count = 0
+
+    # Parse violations from JSON
+    for violation_data in data.get("violations", []):
+        violation = ErcViolation(
+            severity=violation_data.get("severity", "unknown"),
+            type=violation_data.get("type", "unknown"),
+            description=violation_data.get("description", ""),
+            sheet=violation_data.get("sheet", ""),
+            position=violation_data.get("position"),
+        )
+        violations.append(violation)
+
+        if violation.severity == "error":
+            error_count += 1
+        elif violation.severity == "warning":
+            warning_count += 1
+        elif violation.severity == "exclusion":
+            exclusion_count += 1
+
+    return ErcReport(
+        violations=violations,
+        error_count=error_count,
+        warning_count=warning_count,
+        exclusion_count=exclusion_count,
+        schematic_path=schematic_path,
+        raw_output=content,
+    )
+
+
+def _parse_text_report(content: str, schematic_path: Path) -> ErcReport:
+    """Parse text ERC report."""
+    # For text reports, do simple counting
+    lines = content.split("\n")
+    error_count = sum(1 for line in lines if "error" in line.lower())
+    warning_count = sum(1 for line in lines if "warning" in line.lower())
+
+    return ErcReport(
+        violations=[],  # Text format doesn't provide structured violations
+        error_count=error_count,
+        warning_count=warning_count,
+        exclusion_count=0,
+        schematic_path=schematic_path,
+        raw_output=content,
+    )

kicad_sch_api/cli/export_docs.py

@@ -0,0 +1,289 @@
+"""Document export functionality (PDF, SVG, DXF) using kicad-cli."""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from kicad_sch_api.cli.base import KiCadExecutor
+
+
+def export_pdf(
+    schematic_path: Path,
+    output_path: Optional[Path] = None,
+    theme: Optional[str] = None,
+    black_and_white: bool = False,
+    drawing_sheet: Optional[Path] = None,
+    exclude_drawing_sheet: bool = False,
+    default_font: str = "KiCad Font",
+    exclude_pdf_property_popups: bool = False,
+    exclude_pdf_hierarchical_links: bool = False,
+    exclude_pdf_metadata: bool = False,
+    no_background_color: bool = False,
+    pages: Optional[List[int]] = None,
+    variables: Optional[Dict[str, str]] = None,
+    executor: Optional[KiCadExecutor] = None,
+) -> Path:
+    """
+    Export schematic as PDF using kicad-cli.
+
+    Args:
+        schematic_path: Path to .kicad_sch file
+        output_path: Output PDF path (auto-generated if None)
+        theme: Color theme to use (default: schematic settings)
+        black_and_white: Export in black and white
+        drawing_sheet: Path to custom drawing sheet
+        exclude_drawing_sheet: Don't include drawing sheet
+        default_font: Default font name (default: "KiCad Font")
+        exclude_pdf_property_popups: Don't generate property popups
+        exclude_pdf_hierarchical_links: Don't generate clickable hierarchical links
+        exclude_pdf_metadata: Don't generate PDF metadata from variables
+        no_background_color: Don't set background color
+        pages: List of page numbers to export (None = all pages)
+        variables: Project variables to override
+        executor: Custom KiCadExecutor instance
+
+    Returns:
+        Path to generated PDF file
+
+    Example:
+        >>> from pathlib import Path
+        >>> pdf = export_pdf(
+        ...     Path('circuit.kicad_sch'),
+        ...     theme='KiCad Classic',
+        ... )
+    """
+    schematic_path = Path(schematic_path)
+
+    if not schematic_path.exists():
+        raise FileNotFoundError(f"Schematic not found: {schematic_path}")
+
+    if output_path is None:
+        output_path = schematic_path.with_suffix(".pdf")
+    else:
+        output_path = Path(output_path)
+
+    if executor is None:
+        executor = KiCadExecutor()
+
+    # Build command
+    args = ["sch", "export", "pdf", "--output", str(output_path)]
+
+    if theme:
+        args.extend(["--theme", theme])
+
+    if black_and_white:
+        args.append("--black-and-white")
+
+    if drawing_sheet:
+        args.extend(["--drawing-sheet", str(drawing_sheet)])
+
+    if exclude_drawing_sheet:
+        args.append("--exclude-drawing-sheet")
+
+    args.extend(["--default-font", default_font])
+
+    if exclude_pdf_property_popups:
+        args.append("--exclude-pdf-property-popups")
+
+    if exclude_pdf_hierarchical_links:
+        args.append("--exclude-pdf-hierarchical-links")
+
+    if exclude_pdf_metadata:
+        args.append("--exclude-pdf-metadata")
+
+    if no_background_color:
+        args.append("--no-background-color")
+
+    if pages:
+        args.extend(["--pages", ",".join(map(str, pages))])
+
+    if variables:
+        for key, value in variables.items():
+            args.extend(["--define-var", f"{key}={value}"])
+
+    args.append(str(schematic_path))
+
+    # Execute command
+    executor.run(args, cwd=schematic_path.parent)
+
+    return output_path
+
+
+def export_svg(
+    schematic_path: Path,
+    output_dir: Optional[Path] = None,
+    theme: Optional[str] = None,
+    black_and_white: bool = False,
+    drawing_sheet: Optional[Path] = None,
+    exclude_drawing_sheet: bool = False,
+    default_font: str = "KiCad Font",
+    no_background_color: bool = False,
+    pages: Optional[List[int]] = None,
+    variables: Optional[Dict[str, str]] = None,
+    executor: Optional[KiCadExecutor] = None,
+) -> List[Path]:
+    """
+    Export schematic as SVG using kicad-cli.
+
+    Args:
+        schematic_path: Path to .kicad_sch file
+        output_dir: Output directory (default: schematic directory)
+        theme: Color theme to use (default: schematic settings)
+        black_and_white: Export in black and white
+        drawing_sheet: Path to custom drawing sheet
+        exclude_drawing_sheet: Don't include drawing sheet
+        default_font: Default font name (default: "KiCad Font")
+        no_background_color: Don't set background color
+        pages: List of page numbers to export (None = all pages)
+        variables: Project variables to override
+        executor: Custom KiCadExecutor instance
+
+    Returns:
+        List of paths to generated SVG files
+
+    Example:
+        >>> from pathlib import Path
+        >>> svgs = export_svg(
+        ...     Path('circuit.kicad_sch'),
+        ...     theme='KiCad Classic',
+        ... )
+        >>> for svg in svgs:
+        ...     print(f"Generated: {svg}")
+    """
+    schematic_path = Path(schematic_path)
+
+    if not schematic_path.exists():
+        raise FileNotFoundError(f"Schematic not found: {schematic_path}")
+
+    if output_dir is None:
+        output_dir = schematic_path.parent
+    else:
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+    if executor is None:
+        executor = KiCadExecutor()
+
+    # Build command
+    args = ["sch", "export", "svg", "--output", str(output_dir)]
+
+    if theme:
+        args.extend(["--theme", theme])
+
+    if black_and_white:
+        args.append("--black-and-white")
+
+    if drawing_sheet:
+        args.extend(["--drawing-sheet", str(drawing_sheet)])
+
+    if exclude_drawing_sheet:
+        args.append("--exclude-drawing-sheet")
+
+    args.extend(["--default-font", default_font])
+
+    if no_background_color:
+        args.append("--no-background-color")
+
+    if pages:
+        args.extend(["--pages", ",".join(map(str, pages))])
+
+    if variables:
+        for key, value in variables.items():
+            args.extend(["--define-var", f"{key}={value}"])
+
+    args.append(str(schematic_path))
+
+    # Execute command
+    executor.run(args, cwd=schematic_path.parent)
+
+    # Find generated SVG files
+    svg_files = list(output_dir.glob(f"{schematic_path.stem}*.svg"))
+
+    return svg_files
+
+
+def export_dxf(
+    schematic_path: Path,
+    output_dir: Optional[Path] = None,
+    theme: Optional[str] = None,
+    black_and_white: bool = False,
+    drawing_sheet: Optional[Path] = None,
+    exclude_drawing_sheet: bool = False,
+    default_font: str = "KiCad Font",
+    no_background_color: bool = False,
+    pages: Optional[List[int]] = None,
+    variables: Optional[Dict[str, str]] = None,
+    executor: Optional[KiCadExecutor] = None,
+) -> List[Path]:
+    """
+    Export schematic as DXF using kicad-cli.
+
+    Args:
+        schematic_path: Path to .kicad_sch file
+        output_dir: Output directory (default: schematic directory)
+        theme: Color theme to use (default: schematic settings)
+        black_and_white: Export in black and white
+        drawing_sheet: Path to custom drawing sheet
+        exclude_drawing_sheet: Don't include drawing sheet
+        default_font: Default font name (default: "KiCad Font")
+        no_background_color: Don't set background color
+        pages: List of page numbers to export (None = all pages)
+        variables: Project variables to override
+        executor: Custom KiCadExecutor instance
+
+    Returns:
+        List of paths to generated DXF files
+
+    Example:
+        >>> from pathlib import Path
+        >>> dxfs = export_dxf(Path('circuit.kicad_sch'))
+    """
+    schematic_path = Path(schematic_path)
+
+    if not schematic_path.exists():
+        raise FileNotFoundError(f"Schematic not found: {schematic_path}")
+
+    if output_dir is None:
+        output_dir = schematic_path.parent
+    else:
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+    if executor is None:
+        executor = KiCadExecutor()
+
+    # Build command
+    args = ["sch", "export", "dxf", "--output", str(output_dir)]
+
+    if theme:
+        args.extend(["--theme", theme])
+
+    if black_and_white:
+        args.append("--black-and-white")
+
+    if drawing_sheet:
+        args.extend(["--drawing-sheet", str(drawing_sheet)])
+
+    if exclude_drawing_sheet:
+        args.append("--exclude-drawing-sheet")
+
+    args.extend(["--default-font", default_font])
+
+    if no_background_color:
+        args.append("--no-background-color")
+
+    if pages:
+        args.extend(["--pages", ",".join(map(str, pages))])
+
+    if variables:
+        for key, value in variables.items():
+            args.extend(["--define-var", f"{key}={value}"])
+
+    args.append(str(schematic_path))
+
+    # Execute command
+    executor.run(args, cwd=schematic_path.parent)
+
+    # Find generated DXF files
+    dxf_files = list(output_dir.glob(f"{schematic_path.stem}*.dxf"))
+
+    return dxf_files

kicad_sch_api/cli/netlist.py

@@ -0,0 +1,94 @@
+"""Netlist export functionality using kicad-cli."""
+
+from pathlib import Path
+from typing import Optional
+
+from kicad_sch_api.cli.base import KiCadExecutor
+from kicad_sch_api.cli.types import NetlistFormat
+
+
+def export_netlist(
+    schematic_path: Path,
+    output_path: Optional[Path] = None,
+    format: NetlistFormat = "kicadsexpr",
+    executor: Optional[KiCadExecutor] = None,
+) -> Path:
+    """
+    Export netlist from schematic using kicad-cli.
+
+    Supports 8 different netlist formats for PCB layout and simulation.
+
+    Args:
+        schematic_path: Path to .kicad_sch file
+        output_path: Output netlist path (auto-generated if None)
+        format: Netlist format (see NetlistFormat for options)
+        executor: Custom KiCadExecutor instance (creates default if None)
+
+    Returns:
+        Path to generated netlist file
+
+    Raises:
+        RuntimeError: If kicad-cli not found or netlist generation fails
+        FileNotFoundError: If schematic file doesn't exist
+
+    Example:
+        >>> from pathlib import Path
+        >>> netlist = export_netlist(
+        ...     Path('circuit.kicad_sch'),
+        ...     format='spice'
+        ... )
+        >>> print(f"Netlist: {netlist}")
+
+    Supported formats:
+        - kicadsexpr: KiCad S-expression netlist (default)
+        - kicadxml: KiCad XML netlist
+        - cadstar: Cadstar format
+        - orcadpcb2: OrCAD PCB2 format
+        - spice: SPICE netlist
+        - spicemodel: SPICE with models
+        - pads: PADS format
+        - allegro: Allegro format
+    """
+    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:
+        ext = _get_extension_for_format(format)
+        output_path = schematic_path.with_suffix(ext)
+    else:
+        output_path = Path(output_path)
+
+    # Create executor if not provided
+    if executor is None:
+        executor = KiCadExecutor()
+
+    # Build command
+    args = [
+        "sch", "export", "netlist",
+        "--format", format,
+        "--output", str(output_path),
+        str(schematic_path),
+    ]
+
+    # Execute command
+    executor.run(args, cwd=schematic_path.parent)
+
+    return output_path
+
+
+def _get_extension_for_format(format: NetlistFormat) -> str:
+    """Get file extension for netlist format."""
+    extensions = {
+        "kicadsexpr": ".net",
+        "kicadxml": ".xml",
+        "cadstar": ".frp",
+        "orcadpcb2": ".net",
+        "spice": ".cir",
+        "spicemodel": ".cir",
+        "pads": ".asc",
+        "allegro": ".alg",
+    }
+    return extensions.get(format, ".net")

kicad_sch_api/cli/types.py

@@ -0,0 +1,43 @@
+"""Type definitions for KiCad CLI operations."""
+
+from typing import Literal
+
+# Netlist export formats
+NetlistFormat = Literal[
+    "kicadsexpr",  # KiCad S-expression netlist (default)
+    "kicadxml",    # KiCad XML netlist
+    "cadstar",     # Cadstar format
+    "orcadpcb2",   # OrCAD PCB2 format
+    "spice",       # SPICE netlist
+    "spicemodel",  # SPICE with models
+    "pads",        # PADS format
+    "allegro",     # Allegro format
+]
+
+# ERC (Electrical Rule Check) formats
+ErcFormat = Literal[
+    "json",    # JSON format (machine-readable)
+    "report",  # Human-readable text report
+]
+
+# ERC severity levels
+ErcSeverity = Literal[
+    "all",         # Report all violations
+    "error",       # Error level only
+    "warning",     # Warning level only
+    "exclusions",  # Excluded violations only
+]
+
+# Units for measurements
+Units = Literal[
+    "mm",    # Millimeters (default)
+    "in",    # Inches
+    "mils",  # Mils (1/1000 inch)
+]
+
+# Execution modes
+ExecutionMode = Literal[
+    "auto",   # Auto-detect (try local, fall back to Docker)
+    "local",  # Force local kicad-cli
+    "docker", # Force Docker mode
+]

kicad_sch_api/core/collections/__init__.py

@@ -0,0 +1,5 @@
+"""Collection base classes for schematic elements."""
+
+from .base import BaseCollection
+
+__all__ = ["BaseCollection"]