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

kicad_sch_api/core/schematic.py

@@ -14,17 +14,22 @@ from typing import Any, Dict, List, Optional, Tuple, Union
 
 import sexpdata
 
+from ..collections import (
+    ComponentCollection,
+    JunctionCollection,
+    LabelCollection,
+    LabelElement,
+    WireCollection,
+)
 from ..library.cache import get_symbol_cache
 from ..utils.validation import SchematicValidator, ValidationError, ValidationIssue
-from .components import ComponentCollection
 from .factories import ElementFactory
 from .formatter import ExactFormatter
-from .junctions import JunctionCollection
-from .labels import LabelCollection
 from .managers import (
     FileIOManager,
     FormatSyncManager,
     GraphicsManager,
+    HierarchyManager,
     MetadataManager,
     SheetManager,
     TextElementManager,
@@ -52,7 +57,6 @@ from .types import (
     WireType,
     point_from_dict_or_tuple,
 )
-from .wires import WireCollection
 
 logger = logging.getLogger(__name__)
 
@@ -105,7 +109,7 @@ class Schematic:
             SchematicSymbol(**comp) if isinstance(comp, dict) else comp
             for comp in self._data.get("components", [])
         ]
-        self._components = ComponentCollection(component_symbols)
+        self._components = ComponentCollection(component_symbols, parent_schematic=self)
 
         # Initialize wire collection
         wire_data = self._data.get("wires", [])
@@ -152,10 +156,11 @@ class Schematic:
         self._file_io_manager = FileIOManager()
         self._format_sync_manager = FormatSyncManager(self._data)
         self._graphics_manager = GraphicsManager(self._data)
+        self._hierarchy_manager = HierarchyManager(self._data)
         self._metadata_manager = MetadataManager(self._data)
         self._sheet_manager = SheetManager(self._data)
         self._text_element_manager = TextElementManager(self._data)
-        self._wire_manager = WireManager(self._data, self._wires, self._components)
+        self._wire_manager = WireManager(self._data, self._wires, self._components, self)
         self._validation_manager = ValidationManager(self._data, self._components, self._wires)
 
         # Track modifications for save optimization
@@ -166,6 +171,11 @@ class Schematic:
         self._operation_count = 0
         self._total_operation_time = 0.0
 
+        # Hierarchical design context (for child schematics)
+        self._parent_uuid: Optional[str] = None
+        self._sheet_uuid: Optional[str] = None
+        self._hierarchy_path: Optional[str] = None
+
         logger.debug(
             f"Schematic initialized with {len(self._components)} components, {len(self._wires)} wires, "
             f"{len(self._junctions)} junctions, {len(self._texts)} texts, {len(self._labels)} labels, "
@@ -314,12 +324,12 @@ class Schematic:
         """Whether schematic has been modified since last save."""
         return (
             self._modified
-            or self._components._modified
-            or self._wires._modified
-            or self._junctions._modified
+            or self._components.modified
+            or self._wires.modified
+            or self._junctions.modified
             or self._texts._modified
-            or self._labels._modified
-            or self._hierarchical_labels._modified
+            or self._labels.modified
+            or self._hierarchical_labels.modified
             or self._no_connects._modified
             or self._nets._modified
             or self._format_sync_manager.is_dirty()
@@ -350,6 +360,71 @@ class Schematic:
         """Collection of all electrical nets in the schematic."""
         return self._nets
 
+    @property
+    def sheets(self):
+        """Sheet manager for hierarchical sheet operations."""
+        return self._sheet_manager
+
+    @property
+    def hierarchy(self):
+        """
+        Advanced hierarchy manager for complex hierarchical designs.
+
+        Provides features for:
+        - Sheet reuse tracking (sheets used multiple times)
+        - Cross-sheet signal tracking
+        - Sheet pin validation
+        - Hierarchy flattening
+        - Signal tracing through hierarchy
+        """
+        return self._hierarchy_manager
+
+    def set_hierarchy_context(self, parent_uuid: str, sheet_uuid: str) -> None:
+        """
+        Set hierarchical context for this schematic (for child schematics in hierarchical designs).
+
+        This method configures a child schematic to be part of a hierarchical design.
+        Components added after this call will automatically have the correct hierarchical
+        instance path for proper annotation in KiCad.
+
+        Args:
+            parent_uuid: UUID of the parent schematic
+            sheet_uuid: UUID of the sheet instance in the parent schematic
+
+        Example:
+            >>> # Create parent schematic
+            >>> main = ksa.create_schematic("MyProject")
+            >>> parent_uuid = main.uuid
+            >>>
+            >>> # Add sheet to parent and get its UUID
+            >>> sheet_uuid = main.sheets.add_sheet(
+            ...     name="Power Supply",
+            ...     filename="power.kicad_sch",
+            ...     position=(50, 50),
+            ...     size=(100, 100),
+            ...     project_name="MyProject"
+            ... )
+            >>>
+            >>> # Create child schematic with hierarchy context
+            >>> power = ksa.create_schematic("MyProject")
+            >>> power.set_hierarchy_context(parent_uuid, sheet_uuid)
+            >>>
+            >>> # Components added now will have correct hierarchical path
+            >>> vreg = power.components.add('Device:R', 'U1', 'AMS1117-3.3')
+
+        Note:
+            - This must be called BEFORE adding components to the child schematic
+            - Both parent and child schematics must use the same project name
+            - The hierarchical path will be: /{parent_uuid}/{sheet_uuid}
+        """
+        self._parent_uuid = parent_uuid
+        self._sheet_uuid = sheet_uuid
+        self._hierarchy_path = f"/{parent_uuid}/{sheet_uuid}"
+
+        logger.info(
+            f"Set hierarchy context: parent={parent_uuid}, sheet={sheet_uuid}, path={self._hierarchy_path}"
+        )
+
     # Pin positioning methods (delegated to WireManager)
     def get_component_pin_position(self, reference: str, pin_number: str) -> Optional[Point]:
         """
@@ -376,6 +451,59 @@ class Schematic:
         """
         return self._wire_manager.list_component_pins(reference)
 
+    # Connectivity methods (delegated to WireManager)
+    def are_pins_connected(
+        self, component1_ref: str, pin1_number: str, component2_ref: str, pin2_number: str
+    ) -> bool:
+        """
+        Check if two pins are electrically connected.
+
+        Performs full connectivity analysis including connections through:
+        - Direct wires
+        - Junctions
+        - Labels (local/global/hierarchical)
+        - Power symbols
+        - Hierarchical sheets
+
+        Args:
+            component1_ref: First component reference (e.g., "R1")
+            pin1_number: First pin number
+            component2_ref: Second component reference (e.g., "R2")
+            pin2_number: Second pin number
+
+        Returns:
+            True if pins are electrically connected, False otherwise
+        """
+        return self._wire_manager.are_pins_connected(
+            component1_ref, pin1_number, component2_ref, pin2_number
+        )
+
+    def get_net_for_pin(self, component_ref: str, pin_number: str):
+        """
+        Get the electrical net connected to a specific pin.
+
+        Args:
+            component_ref: Component reference (e.g., "R1")
+            pin_number: Pin number
+
+        Returns:
+            Net object if pin is connected, None otherwise
+        """
+        return self._wire_manager.get_net_for_pin(component_ref, pin_number)
+
+    def get_connected_pins(self, component_ref: str, pin_number: str) -> List[Tuple[str, str]]:
+        """
+        Get all pins electrically connected to a specific pin.
+
+        Args:
+            component_ref: Component reference (e.g., "R1")
+            pin_number: Pin number
+
+        Returns:
+            List of (reference, pin_number) tuples for all connected pins
+        """
+        return self._wire_manager.get_connected_pins(component_ref, pin_number)
+
     # File operations (delegated to FileIOManager)
     def save(self, file_path: Optional[Union[str, Path]] = None, preserve_format: bool = True):
         """
@@ -423,7 +551,11 @@ class Schematic:
 
         # Update state
         self._modified = False
-        self._components._modified = False
+        self._components.mark_saved()
+        self._wires.mark_saved()
+        self._junctions.mark_saved()
+        self._labels.mark_saved()
+        self._hierarchical_labels.mark_saved()
         self._format_sync_manager.clear_dirty_flags()
         self._last_save_time = time.time()
 
@@ -449,6 +581,59 @@ class Schematic:
 
         return self._file_io_manager.create_backup(self._file_path, suffix)
 
+    def export_to_python(
+        self,
+        output_path: Union[str, Path],
+        template: str = 'default',
+        include_hierarchy: bool = True,
+        format_code: bool = True,
+        add_comments: bool = True
+    ) -> Path:
+        """
+        Export schematic to executable Python code.
+
+        Generates Python code that uses kicad-sch-api to recreate this
+        schematic programmatically.
+
+        Args:
+            output_path: Output .py file path
+            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:
+            CodeGenerationError: If code generation fails
+
+        Example:
+            >>> sch = Schematic.load('circuit.kicad_sch')
+            >>> sch.export_to_python('circuit.py')
+            PosixPath('circuit.py')
+
+            >>> sch.export_to_python('circuit.py',
+            ...                      template='verbose',
+            ...                      add_comments=True)
+            PosixPath('circuit.py')
+        """
+        from ..exporters.python_generator import PythonCodeGenerator
+
+        generator = PythonCodeGenerator(
+            template=template,
+            format_code=format_code,
+            add_comments=add_comments
+        )
+
+        generator.generate(
+            schematic=self,
+            include_hierarchy=include_hierarchy,
+            output_path=Path(output_path)
+        )
+
+        return Path(output_path)
+
     # Wire operations (delegated to WireManager)
     def add_wire(
         self, start: Union[Point, Tuple[float, float]], end: Union[Point, Tuple[float, float]]
@@ -577,9 +762,10 @@ class Schematic:
     def add_label(
         self,
         text: str,
-        position: Union[Point, Tuple[float, float]],
+        position: Optional[Union[Point, Tuple[float, float]]] = None,
+        pin: Optional[Tuple[str, str]] = None,
         effects: Optional[Dict[str, Any]] = None,
-        rotation: float = 0,
+        rotation: Optional[float] = None,
         size: Optional[float] = None,
         uuid: Optional[str] = None,
     ) -> str:
@@ -588,19 +774,84 @@ class Schematic:
 
         Args:
             text: Label text content
-            position: Label position
+            position: Label position (required if pin not provided)
+            pin: Pin to attach label to as (component_ref, pin_number) tuple (alternative to position)
             effects: Text effects (size, font, etc.)
-            rotation: Label rotation in degrees (default 0)
+            rotation: Label rotation in degrees (default 0, or auto-calculated if pin provided)
             size: Text size override (default from effects)
             uuid: Specific UUID for label (auto-generated if None)
 
         Returns:
             UUID of created label
-        """
+
+        Raises:
+            ValueError: If neither position nor pin is provided, or if pin is not found
+        """
+        from .pin_utils import get_component_pin_info
+
+        # Validate arguments
+        if position is None and pin is None:
+            raise ValueError("Either position or pin must be provided")
+        if position is not None and pin is not None:
+            raise ValueError("Cannot provide both position and pin")
+
+        # Handle pin-based placement
+        justify_h = "left"
+        justify_v = "bottom"
+
+        if pin is not None:
+            component_ref, pin_number = pin
+
+            # Get component
+            component = self._components.get(component_ref)
+            if component is None:
+                raise ValueError(f"Component {component_ref} not found")
+
+            # Get pin position and rotation
+            pin_info = get_component_pin_info(component, pin_number)
+            if pin_info is None:
+                raise ValueError(f"Pin {pin_number} not found on component {component_ref}")
+
+            pin_position, pin_rotation = pin_info
+            position = pin_position
+
+            # Calculate label rotation if not explicitly provided
+            if rotation is None:
+                # Label should face away from component:
+                # Pin rotation indicates where pin points INTO the component
+                # Label should face OPPOSITE direction
+                rotation = (pin_rotation + 180) % 360
+                logger.info(
+                    f"Auto-calculated label rotation: {rotation}° (pin rotation: {pin_rotation}°)"
+                )
+
+            # Calculate justification based on pin angle
+            # This determines which corner of the text is anchored to the pin position
+            if pin_rotation == 0:  # Pin points right into component
+                justify_h = "left"
+                justify_v = "bottom"
+            elif pin_rotation == 90:  # Pin points up into component
+                justify_h = "right"
+                justify_v = "bottom"
+            elif pin_rotation == 180:  # Pin points left into component
+                justify_h = "right"
+                justify_v = "bottom"
+            elif pin_rotation == 270:  # Pin points down into component
+                justify_h = "left"
+                justify_v = "bottom"
+            logger.info(f"Auto-calculated justification: {justify_h} {justify_v} (pin angle: {pin_rotation}°)")
+
+        # Use default rotation if still not set
+        if rotation is None:
+            rotation = 0
+
         # Use the new labels collection instead of manager
         if size is None:
             size = 1.27  # Default size
-        label = self._labels.add(text, position, rotation=rotation, size=size, label_uuid=uuid)
+        label = self._labels.add(
+            text, position, rotation=rotation, size=size,
+            justify_h=justify_h, justify_v=justify_v, uuid=uuid
+        )
         self._sync_labels_to_data()  # Sync immediately
         self._format_sync_manager.mark_dirty("label", "add", {"uuid": label.uuid})
         self._modified = True
@@ -837,28 +1088,42 @@ class Schematic:
         sheet_uuid: str,
         name: str,
         pin_type: str,
-        position: Union[Point, Tuple[float, float]],
-        rotation: float = 0,
-        justify: str = "left",
+        edge: str,
+        position_along_edge: float,
         uuid: Optional[str] = None,
     ) -> str:
         """
-        Add a pin to a hierarchical sheet.
+        Add a pin to a hierarchical sheet using edge-based positioning.
 
         Args:
             sheet_uuid: UUID of the sheet to add pin to
             name: Pin name
-            pin_type: Pin type (input, output, bidirectional, etc.)
-            position: Pin position
-            rotation: Pin rotation in degrees
-            justify: Text justification
+            pin_type: Pin type (input, output, bidirectional, tri_state, passive)
+            edge: Edge to place pin on ("right", "bottom", "left", "top")
+            position_along_edge: Distance along edge from reference corner (mm)
             uuid: Optional UUID for the pin
 
         Returns:
             UUID of created sheet pin
+
+        Edge positioning (clockwise from right):
+            - "right": Pins face right (0°), position measured from top edge
+            - "bottom": Pins face down (270°), position measured from left edge
+            - "left": Pins face left (180°), position measured from bottom edge
+            - "top": Pins face up (90°), position measured from left edge
+
+        Example:
+            >>> # Sheet at (100, 100) with size (50, 40)
+            >>> sch.add_sheet_pin(
+            ...     sheet_uuid=sheet_id,
+            ...     name="DATA_IN",
+            ...     pin_type="input",
+            ...     edge="left",
+            ...     position_along_edge=20  # 20mm from top on left edge
+            ... )
         """
         pin_uuid = self._sheet_manager.add_sheet_pin(
-            sheet_uuid, name, pin_type, position, rotation, justify, uuid_str=uuid
+            sheet_uuid, name, pin_type, edge, position_along_edge, uuid_str=uuid
         )
         self._format_sync_manager.mark_dirty("sheet", "modify", {"uuid": sheet_uuid})
         self._modified = True
@@ -898,7 +1163,7 @@ class Schematic:
             start: Top-left corner position
             end: Bottom-right corner position
             stroke_width: Line width
-            stroke_type: Line type (solid, dashed, etc.)
+            stroke_type: Line type (solid, dash, dash_dot, dash_dot_dot, dot, or default)
             fill_type: Fill type (none, background, etc.)
             stroke_color: Stroke color as (r, g, b, a)
             fill_color: Fill color as (r, g, b, a)
@@ -906,6 +1171,14 @@ class Schematic:
         Returns:
             UUID of created rectangle
         """
+        # Validate stroke_type
+        valid_stroke_types = ["solid", "dash", "dash_dot", "dash_dot_dot", "dot", "default"]
+        if stroke_type not in valid_stroke_types:
+            raise ValueError(
+                f"Invalid stroke_type '{stroke_type}'. "
+                f"Must be one of: {', '.join(valid_stroke_types)}"
+            )
+
         # Convert individual parameters to stroke/fill dicts
         stroke = {"width": stroke_width, "type": stroke_type}
         if stroke_color:
@@ -1159,10 +1432,13 @@ class Schematic:
     @staticmethod
     def _create_empty_schematic_data() -> Dict[str, Any]:
         """Create empty schematic data structure."""
+        from uuid import uuid4
+
         return {
             "version": "20250114",
             "generator": "eeschema",
             "generator_version": "9.0",
+            "uuid": str(uuid4()),
             "paper": "A4",
             "lib_symbols": {},
             "symbol": [],
@@ -1216,7 +1492,43 @@ class Schematic:
     # Internal sync methods (migrated from original implementation)
     def _sync_components_to_data(self):
         """Sync component collection state back to data structure."""
-        self._data["components"] = [comp._data.__dict__ for comp in self._components]
+        logger.debug("🔍 _sync_components_to_data: Syncing components to _data")
+
+        components_data = []
+        for comp in self._components:
+            # Start with base component data
+            comp_dict = {k: v for k, v in comp._data.__dict__.items() if not k.startswith("_")}
+
+            # CRITICAL FIX: Explicitly preserve instances if user set them
+            if hasattr(comp._data, "instances") and comp._data.instances:
+                logger.debug(
+                    f"   Component {comp._data.reference} has {len(comp._data.instances)} instance(s)"
+                )
+                comp_dict["instances"] = [
+                    {
+                        "project": (
+                            getattr(inst, "project", self.name)
+                            if hasattr(inst, "project")
+                            else self.name
+                        ),
+                        "path": inst.path,  # PRESERVE exact path user set!
+                        "reference": inst.reference,
+                        "unit": inst.unit,
+                    }
+                    for inst in comp._data.instances
+                ]
+                logger.debug(
+                    f"      Instance paths: {[inst.path for inst in comp._data.instances]}"
+                )
+            else:
+                logger.debug(
+                    f"   Component {comp._data.reference} has NO instances (will be generated by parser)"
+                )
+
+            components_data.append(comp_dict)
+
+        self._data["components"] = components_data
+        logger.debug(f"   Synced {len(components_data)} components to _data")
 
         # Populate lib_symbols with actual symbol definitions used by components
         lib_symbols = {}
@@ -1297,6 +1609,8 @@ class Schematic:
                 "position": {"x": label_element.position.x, "y": label_element.position.y},
                 "rotation": label_element.rotation,
                 "size": label_element.size,
+                "justify_h": label_element._data.justify_h,
+                "justify_v": label_element._data.justify_v,
             }
             label_data.append(label_dict)
 

kicad_sch_api/core/types.py

@@ -155,6 +155,54 @@ class SchematicPin:
         )
 
 
+@dataclass
+class PinInfo:
+    """
+    Complete pin information for a component pin.
+
+    This dataclass provides comprehensive pin metadata including position,
+    electrical properties, and graphical representation. Positions are in
+    schematic coordinates (absolute positions accounting for component
+    rotation and mirroring).
+    """
+
+    number: str  # Pin number (e.g., "1", "2", "A1")
+    name: str  # Pin name (e.g., "VCC", "GND", "CLK")
+    position: Point  # Absolute position in schematic coordinates (mm)
+    electrical_type: PinType = PinType.PASSIVE  # Electrical type (input, output, passive, etc.)
+    shape: PinShape = PinShape.LINE  # Graphical shape (line, inverted, clock, etc.)
+    length: float = 2.54  # Pin length in mm
+    orientation: float = 0.0  # Pin orientation in degrees (0, 90, 180, 270)
+    uuid: str = ""  # Unique identifier for this pin instance
+
+    def __post_init__(self) -> None:
+        """Validate and normalize pin information."""
+        # Ensure types are correct
+        self.electrical_type = (
+            PinType(self.electrical_type)
+            if isinstance(self.electrical_type, str)
+            else self.electrical_type
+        )
+        self.shape = PinShape(self.shape) if isinstance(self.shape, str) else self.shape
+
+        # Generate UUID if not provided
+        if not self.uuid:
+            self.uuid = str(uuid4())
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert pin info to dictionary representation."""
+        return {
+            "number": self.number,
+            "name": self.name,
+            "position": {"x": self.position.x, "y": self.position.y},
+            "electrical_type": self.electrical_type.value,
+            "shape": self.shape.value,
+            "length": self.length,
+            "orientation": self.orientation,
+            "uuid": self.uuid,
+        }
+
+
 @dataclass
 class SchematicSymbol:
     """Component symbol in a schematic."""
@@ -171,6 +219,7 @@ class SchematicSymbol:
     in_bom: bool = True
     on_board: bool = True
     unit: int = 1
+    instances: List["SymbolInstance"] = field(default_factory=list)  # FIX: Add instances field for hierarchical support
 
     def __post_init__(self) -> None:
         # Generate UUID if not provided
@@ -195,16 +244,37 @@ class SchematicSymbol:
         return None
 
     def get_pin_position(self, pin_number: str) -> Optional[Point]:
-        """Get absolute position of a pin."""
+        """Get absolute position of a pin with rotation transformation.
+
+        Args:
+            pin_number: Pin number to get position for
+
+        Returns:
+            Absolute position of the pin in schematic coordinates, or None if pin not found
+
+        Note:
+            Applies standard 2D rotation matrix to transform pin position from
+            symbol's local coordinate system to schematic's global coordinate system.
+        """
+        import math
+
         pin = self.get_pin(pin_number)
         if not pin:
             return None
-        # TODO: Apply rotation and symbol position transformation
-        # NOTE: Currently assumes 0° rotation. For rotated components, pin positions
-        # would need to be transformed using rotation matrix before adding to component position.
-        # This affects pin-to-pin wiring accuracy for rotated components.
-        # Priority: MEDIUM - Would improve wiring accuracy for rotated components
-        return Point(self.position.x + pin.position.x, self.position.y + pin.position.y)
+
+        # Apply rotation transformation using standard 2D rotation matrix
+        # [x'] = [cos(θ)  -sin(θ)] [x]
+        # [y']   [sin(θ)   cos(θ)] [y]
+        angle_rad = math.radians(self.rotation)
+        cos_a = math.cos(angle_rad)
+        sin_a = math.sin(angle_rad)
+
+        # Rotate pin position from symbol's local coordinates
+        rotated_x = pin.position.x * cos_a - pin.position.y * sin_a
+        rotated_y = pin.position.x * sin_a + pin.position.y * cos_a
+
+        # Add to component position to get absolute position
+        return Point(self.position.x + rotated_x, self.position.y + rotated_y)
 
 
 class WireType(Enum):
@@ -320,6 +390,8 @@ class Label:
     rotation: float = 0.0
     size: float = 1.27
     shape: Optional[HierarchicalLabelShape] = None  # Only for hierarchical labels
+    justify_h: str = "left"  # Horizontal justification: "left", "right", "center"
+    justify_v: str = "bottom"  # Vertical justification: "top", "bottom", "center"
 
     def __post_init__(self) -> None:
         if not self.uuid:

kicad_sch_api/exporters/__init__.py

@@ -0,0 +1,10 @@
+"""
+Exporters module for kicad-sch-api.
+
+This module provides functionality to export KiCad schematics to various formats,
+starting with Python code export.
+"""
+
+from .python_generator import PythonCodeGenerator
+
+__all__ = ['PythonCodeGenerator']