kicad-sch-api 0.3.0__py3-none-any.whl → 0.5.1__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/kicad_to_python.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""
+KiCad-to-Python CLI Command
+
+Convert KiCad schematic files to executable Python code.
+
+Usage:
+    kicad-to-python input.kicad_sch output.py
+    kicad-to-python input.kicad_sch output.py --template verbose
+    kicad-to-python project.kicad_pro output_dir/ --include-hierarchy
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+import kicad_sch_api as ksa
+from kicad_sch_api.exporters.python_generator import (
+    PythonCodeGenerator,
+    CodeGenerationError,
+    TemplateNotFoundError
+)
+
+
+def main(argv: Optional[list] = None) -> int:
+    """
+    Main CLI entry point.
+
+    Args:
+        argv: Command-line arguments (None = sys.argv)
+
+    Returns:
+        Exit code (0 = success, 1 = error)
+    """
+    parser = argparse.ArgumentParser(
+        prog='kicad-to-python',
+        description='Convert KiCad schematics to Python code',
+        epilog='For more information: https://github.com/circuit-synth/kicad-sch-api'
+    )
+
+    # Positional arguments
+    parser.add_argument(
+        'input',
+        type=Path,
+        help='Input KiCad schematic (.kicad_sch) or project (.kicad_pro)'
+    )
+
+    parser.add_argument(
+        'output',
+        type=Path,
+        help='Output Python file (.py) or directory (for hierarchical)'
+    )
+
+    # Options
+    parser.add_argument(
+        '--template',
+        choices=['minimal', 'default', 'verbose', 'documented'],
+        default='default',
+        help='Code template style (default: default)'
+    )
+
+    parser.add_argument(
+        '--include-hierarchy',
+        action='store_true',
+        help='Include hierarchical sheets'
+    )
+
+    parser.add_argument(
+        '--no-format',
+        action='store_true',
+        help='Skip Black code formatting'
+    )
+
+    parser.add_argument(
+        '--no-comments',
+        action='store_true',
+        help='Skip explanatory comments'
+    )
+
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Verbose output'
+    )
+
+    args = parser.parse_args(argv)
+
+    try:
+        # Validate input file
+        if not args.input.exists():
+            print(f"❌ Error: Input file not found: {args.input}", file=sys.stderr)
+            return 1
+
+        if args.input.suffix not in ['.kicad_sch', '.kicad_pro']:
+            print(
+                f"❌ Error: Input must be .kicad_sch or .kicad_pro file",
+                file=sys.stderr
+            )
+            return 1
+
+        # Load schematic
+        if args.verbose:
+            print(f"📖 Loading schematic: {args.input}")
+
+        schematic = ksa.Schematic.load(args.input)
+
+        if args.verbose:
+            comp_count = len(list(schematic.components))
+            wire_count = len(list(schematic.wires))
+            label_count = len(list(schematic.labels))
+            print(f"   Found {comp_count} components")
+            print(f"   Found {wire_count} wires")
+            print(f"   Found {label_count} labels")
+
+        # Generate Python code
+        if args.verbose:
+            print(f"🔨 Generating Python code...")
+
+        generator = PythonCodeGenerator(
+            template=args.template,
+            format_code=not args.no_format,
+            add_comments=not args.no_comments
+        )
+
+        code = generator.generate(
+            schematic=schematic,
+            include_hierarchy=args.include_hierarchy,
+            output_path=args.output
+        )
+
+        # Report success
+        lines = len(code.split('\n'))
+        print(f"✅ Generated {args.output} ({lines} lines)")
+
+        if args.verbose:
+            print(f"   Template: {args.template}")
+            print(f"   Formatted: {not args.no_format}")
+            print(f"   Comments: {not args.no_comments}")
+
+        return 0
+
+    except FileNotFoundError as e:
+        print(f"❌ File not found: {e}", file=sys.stderr)
+        return 1
+
+    except CodeGenerationError as e:
+        print(f"❌ Code generation error: {e}", file=sys.stderr)
+        return 1
+
+    except TemplateNotFoundError as e:
+        print(f"❌ Template error: {e}", file=sys.stderr)
+        return 1
+
+    except Exception as e:
+        print(f"❌ Unexpected error: {e}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        return 1
+
+
+def entry_point():
+    """Entry point for setuptools console_scripts."""
+    sys.exit(main())
+
+
+if __name__ == '__main__':
+    sys.exit(main())