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

kicad_sch_api/__init__.py

@@ -42,17 +42,24 @@ Advanced Usage:
         print(f"Found {len(issues)} validation issues")
 """
 
-__version__ = "0.4.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, 4, 0)
@@ -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/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())

kicad_sch_api/collections/__init__.py

@@ -1,21 +1,36 @@
 """
 Modern collection architecture for KiCAD schematic elements.
 
-This module provides a unified collection framework that eliminates code duplication
-across component, wire, and junction collections while providing consistent
-indexing, performance optimization, and management capabilities.
+This module provides a unified collection framework with:
+- Centralized index management via IndexRegistry
+- Lazy index rebuilding for performance
+- Configurable validation levels
+- Auto-tracking property dictionaries
+- Batch mode for bulk operations
 """
 
-from .base import IndexedCollection
-from .components import ComponentCollection
+from .base import (
+    BaseCollection,
+    IndexSpec,
+    IndexRegistry,
+    PropertyDict,
+    ValidationLevel,
+)
+from .components import Component, ComponentCollection
 from .junctions import JunctionCollection
-from .labels import LabelCollection
+from .labels import LabelCollection, LabelElement
 from .wires import WireCollection
 
 __all__ = [
-    "IndexedCollection",
+    "BaseCollection",
+    "IndexSpec",
+    "IndexRegistry",
+    "PropertyDict",
+    "ValidationLevel",
+    "Component",
     "ComponentCollection",
-    "WireCollection",
     "JunctionCollection",
     "LabelCollection",
+    "LabelElement",
+    "WireCollection",
 ]