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

kicad_sch_api/core/managers/wire.py

@@ -0,0 +1,410 @@
+"""
+Wire Manager for KiCAD schematic wire operations.
+
+Handles wire creation, removal, pin connections, and auto-routing functionality
+while managing component pin position calculations and connectivity analysis.
+"""
+
+import logging
+import uuid
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from ...library.cache import get_symbol_cache
+from ..connectivity import ConnectivityAnalyzer, Net
+from ..types import Point, Wire, WireType
+from ..wires import WireCollection
+from .base import BaseManager
+
+logger = logging.getLogger(__name__)
+
+
+class WireManager(BaseManager):
+    """
+    Manages wire operations and pin connectivity in KiCAD schematics.
+
+    Responsible for:
+    - Wire creation and removal
+    - Pin position calculations
+    - Auto-routing between pins
+    - Connectivity analysis
+    - Wire-to-pin connections
+    """
+
+    def __init__(
+        self,
+        schematic_data: Dict[str, Any],
+        wire_collection: WireCollection,
+        component_collection,
+        schematic,
+    ):
+        """
+        Initialize WireManager.
+
+        Args:
+            schematic_data: Reference to schematic data
+            wire_collection: Wire collection for management
+            component_collection: Component collection for pin lookups
+            schematic: Reference to parent Schematic object for connectivity analysis
+        """
+        super().__init__(schematic_data)
+        self._wires = wire_collection
+        self._components = component_collection
+        self._schematic = schematic
+        self._symbol_cache = get_symbol_cache()
+
+        # Lazy-initialized connectivity analyzer (always hierarchical)
+        self._connectivity_analyzer: Optional[ConnectivityAnalyzer] = None
+        self._connectivity_valid = False
+
+    def add_wire(
+        self, start: Union[Point, Tuple[float, float]], end: Union[Point, Tuple[float, float]]
+    ) -> str:
+        """
+        Add a wire connection.
+
+        Args:
+            start: Start point
+            end: End point
+
+        Returns:
+            UUID of created wire
+        """
+        if isinstance(start, tuple):
+            start = Point(start[0], start[1])
+        if isinstance(end, tuple):
+            end = Point(end[0], end[1])
+
+        # Use the wire collection to add the wire
+        wire_uuid = self._wires.add(start=start, end=end)
+
+        # Invalidate connectivity cache
+        self._invalidate_connectivity()
+
+        logger.debug(f"Added wire: {start} -> {end}")
+        return wire_uuid
+
+    def remove_wire(self, wire_uuid: str) -> bool:
+        """
+        Remove wire by UUID.
+
+        Args:
+            wire_uuid: UUID of wire to remove
+
+        Returns:
+            True if wire was removed, False if not found
+        """
+        # Remove from wire collection
+        removed_from_collection = self._wires.remove(wire_uuid)
+
+        # Also remove from data structure for consistency
+        wires = self._data.get("wires", [])
+        removed_from_data = False
+        for i, wire in enumerate(wires):
+            if wire.get("uuid") == wire_uuid:
+                del wires[i]
+                removed_from_data = True
+                break
+
+        success = removed_from_collection or removed_from_data
+        if success:
+            # Invalidate connectivity cache
+            self._invalidate_connectivity()
+            logger.debug(f"Removed wire: {wire_uuid}")
+
+        return success
+
+    def add_wire_to_pin(
+        self, start: Union[Point, Tuple[float, float]], component_ref: str, pin_number: str
+    ) -> str:
+        """
+        Add wire from a point to a component pin.
+
+        Args:
+            start: Starting point
+            component_ref: Component reference (e.g., "R1")
+            pin_number: Pin number on component
+
+        Returns:
+            UUID of created wire
+
+        Raises:
+            ValueError: If component or pin not found
+        """
+        pin_position = self.get_component_pin_position(component_ref, pin_number)
+        if pin_position is None:
+            raise ValueError(f"Pin {pin_number} not found on component {component_ref}")
+
+        return self.add_wire(start, pin_position)
+
+    def add_wire_between_pins(
+        self, component1_ref: str, pin1_number: str, component2_ref: str, pin2_number: str
+    ) -> str:
+        """
+        Add wire between two component pins.
+
+        Args:
+            component1_ref: First component reference
+            pin1_number: First component pin number
+            component2_ref: Second component reference
+            pin2_number: Second component pin number
+
+        Returns:
+            UUID of created wire
+
+        Raises:
+            ValueError: If components or pins not found
+        """
+        pin1_pos = self.get_component_pin_position(component1_ref, pin1_number)
+        pin2_pos = self.get_component_pin_position(component2_ref, pin2_number)
+
+        if pin1_pos is None:
+            raise ValueError(f"Pin {pin1_number} not found on component {component1_ref}")
+        if pin2_pos is None:
+            raise ValueError(f"Pin {pin2_number} not found on component {component2_ref}")
+
+        return self.add_wire(pin1_pos, pin2_pos)
+
+    def get_component_pin_position(self, component_ref: str, pin_number: str) -> Optional[Point]:
+        """
+        Get absolute position of a component pin.
+
+        Uses the same geometry transformation as the connectivity analyzer
+        to ensure consistent pin positions.
+
+        Args:
+            component_ref: Component reference (e.g., "R1")
+            pin_number: Pin number
+
+        Returns:
+            Absolute pin position or None if not found
+        """
+        from ..pin_utils import list_component_pins
+
+        # Find component
+        component = self._components.get(component_ref)
+        if not component:
+            logger.warning(f"Component not found: {component_ref}")
+            return None
+
+        # Use pin_utils to get correct transformed positions
+        pins = list_component_pins(component)
+
+        for pin_num, pin_pos in pins:
+            if pin_num == pin_number:
+                return pin_pos
+
+        logger.warning(f"Pin {pin_number} not found on component {component_ref}")
+        return None
+
+    def list_component_pins(self, component_ref: str) -> List[Tuple[str, Point]]:
+        """
+        List all pins and their positions for a component.
+
+        Uses the same geometry transformation as the connectivity analyzer
+        to ensure consistent pin positions.
+
+        Args:
+            component_ref: Component reference
+
+        Returns:
+            List of (pin_number, absolute_position) tuples
+        """
+        from ..pin_utils import list_component_pins
+
+        # Find component
+        component = self._components.get(component_ref)
+        if not component:
+            return []
+
+        # Use pin_utils to get correct transformed positions
+        return list_component_pins(component)
+
+    def auto_route_pins(
+        self,
+        component1_ref: str,
+        pin1_number: str,
+        component2_ref: str,
+        pin2_number: str,
+        routing_strategy: str = "direct",
+    ) -> List[str]:
+        """
+        Auto-route between two pins with different strategies.
+
+        Args:
+            component1_ref: First component reference
+            pin1_number: First component pin number
+            component2_ref: Second component reference
+            pin2_number: Second component pin number
+            routing_strategy: "direct" or "manhattan"
+
+        Returns:
+            List of wire UUIDs created
+
+        Raises:
+            ValueError: If components or pins not found
+        """
+        pin1_pos = self.get_component_pin_position(component1_ref, pin1_number)
+        pin2_pos = self.get_component_pin_position(component2_ref, pin2_number)
+
+        if pin1_pos is None:
+            raise ValueError(f"Pin {pin1_number} not found on component {component1_ref}")
+        if pin2_pos is None:
+            raise ValueError(f"Pin {pin2_number} not found on component {component2_ref}")
+
+        wire_uuids = []
+
+        if routing_strategy == "direct":
+            # Direct wire between pins
+            wire_uuid = self.add_wire(pin1_pos, pin2_pos)
+            wire_uuids.append(wire_uuid)
+
+        elif routing_strategy == "manhattan":
+            # Manhattan routing (L-shaped path)
+            # Route horizontally first, then vertically
+            intermediate_point = Point(pin2_pos.x, pin1_pos.y)
+
+            # Only add intermediate wire if it has length
+            if abs(pin1_pos.x - pin2_pos.x) > 0.1:  # Minimum wire length
+                wire1_uuid = self.add_wire(pin1_pos, intermediate_point)
+                wire_uuids.append(wire1_uuid)
+
+            if abs(pin1_pos.y - pin2_pos.y) > 0.1:  # Minimum wire length
+                wire2_uuid = self.add_wire(intermediate_point, pin2_pos)
+                wire_uuids.append(wire2_uuid)
+
+        else:
+            raise ValueError(f"Unknown routing strategy: {routing_strategy}")
+
+        logger.info(
+            f"Auto-routed {component1_ref}:{pin1_number} to {component2_ref}:{pin2_number} using {routing_strategy}"
+        )
+        return wire_uuids
+
+    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:
+        - Direct wire connections
+        - Connections through junctions
+        - Connections through labels (local/global/hierarchical)
+        - Connections through power symbols
+        - Hierarchical sheet connections
+
+        Args:
+            component1_ref: First component reference
+            pin1_number: First component pin number
+            component2_ref: Second component reference
+            pin2_number: Second component pin number
+
+        Returns:
+            True if pins are electrically connected, False otherwise
+        """
+        self._ensure_connectivity()
+
+        if self._connectivity_analyzer:
+            return self._connectivity_analyzer.are_connected(
+                component1_ref, pin1_number, component2_ref, pin2_number
+            )
+
+        return False
+
+    def connect_pins_with_wire(
+        self, component1_ref: str, pin1_number: str, component2_ref: str, pin2_number: str
+    ) -> str:
+        """
+        Legacy alias for add_wire_between_pins.
+
+        Args:
+            component1_ref: First component reference
+            pin1_number: First component pin number
+            component2_ref: Second component reference
+            pin2_number: Second component pin number
+
+        Returns:
+            UUID of created wire
+        """
+        return self.add_wire_between_pins(component1_ref, pin1_number, component2_ref, pin2_number)
+
+    def get_wire_statistics(self) -> Dict[str, Any]:
+        """
+        Get statistics about wires in the schematic.
+
+        Returns:
+            Dictionary with wire statistics
+        """
+        total_wires = len(self._wires)
+        total_length = sum(wire.start.distance_to(wire.end) for wire in self._wires)
+
+        return {
+            "total_wires": total_wires,
+            "total_length": total_length,
+            "average_length": total_length / total_wires if total_wires > 0 else 0,
+            "wire_types": {
+                "normal": len([w for w in self._wires if w.wire_type == WireType.WIRE]),
+                "bus": len([w for w in self._wires if w.wire_type == WireType.BUS]),
+            },
+        }
+
+    def get_net_for_pin(self, component_ref: str, pin_number: str) -> Optional[Net]:
+        """
+        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
+        """
+        self._ensure_connectivity()
+
+        if self._connectivity_analyzer:
+            return self._connectivity_analyzer.get_net_for_pin(component_ref, pin_number)
+
+        return None
+
+    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
+        """
+        self._ensure_connectivity()
+
+        if self._connectivity_analyzer:
+            return self._connectivity_analyzer.get_connected_pins(component_ref, pin_number)
+
+        return []
+
+    def _ensure_connectivity(self):
+        """
+        Ensure connectivity analysis is up-to-date.
+
+        Lazily initializes and runs connectivity analyzer on first query.
+        Re-runs analysis if schematic has changed since last analysis.
+        """
+        if not self._connectivity_valid:
+            logger.debug("Running connectivity analysis (hierarchical)...")
+            self._connectivity_analyzer = ConnectivityAnalyzer()
+            self._connectivity_analyzer.analyze(self._schematic, hierarchical=True)
+            self._connectivity_valid = True
+            logger.debug("Connectivity analysis complete")
+
+    def _invalidate_connectivity(self):
+        """
+        Invalidate connectivity cache.
+
+        Called when schematic changes that affect connectivity (wires, components, etc.).
+        Next connectivity query will trigger re-analysis.
+        """
+        if self._connectivity_valid:
+            logger.debug("Invalidating connectivity cache")
+            self._connectivity_valid = False

kicad_sch_api/core/nets.py

@@ -0,0 +1,305 @@
+"""
+Net management for KiCAD schematics.
+
+This module provides collection classes for managing electrical nets,
+featuring fast lookup, bulk operations, and validation.
+"""
+
+import logging
+from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple, Union
+
+from ..utils.validation import SchematicValidator, ValidationError, ValidationIssue
+from .collections import BaseCollection
+from .types import Net
+
+logger = logging.getLogger(__name__)
+
+
+class NetElement:
+    """
+    Enhanced wrapper for schematic net elements with modern API.
+
+    Provides intuitive access to net properties and operations
+    while maintaining exact format preservation.
+    """
+
+    def __init__(self, net_data: Net, parent_collection: "NetCollection"):
+        """
+        Initialize net element wrapper.
+
+        Args:
+            net_data: Underlying net data
+            parent_collection: Parent collection for updates
+        """
+        self._data = net_data
+        self._collection = parent_collection
+        self._validator = SchematicValidator()
+
+    # Core properties with validation
+    @property
+    def uuid(self) -> str:
+        """Net UUID (uses name as unique identifier)."""
+        return self._data.name
+
+    @property
+    def name(self) -> str:
+        """Net name."""
+        return self._data.name
+
+    @name.setter
+    def name(self, value: str):
+        """Set net name with validation."""
+        if not isinstance(value, str) or not value.strip():
+            raise ValidationError("Net name cannot be empty")
+        old_name = self._data.name
+        self._data.name = value.strip()
+        # Update name index and rebuild base UUID index since UUID changed
+        self._collection._update_name_index(old_name, self)
+        self._collection._rebuild_index()
+        self._collection._mark_modified()
+
+    @property
+    def components(self) -> List[Tuple[str, str]]:
+        """List of component connections (reference, pin) tuples."""
+        return self._data.components.copy()
+
+    @property
+    def wires(self) -> List[str]:
+        """List of wire UUIDs in this net."""
+        return self._data.wires.copy()
+
+    @property
+    def labels(self) -> List[str]:
+        """List of label UUIDs in this net."""
+        return self._data.labels.copy()
+
+    def add_connection(self, reference: str, pin: str):
+        """Add component pin to net."""
+        self._data.add_connection(reference, pin)
+        self._collection._mark_modified()
+
+    def remove_connection(self, reference: str, pin: str):
+        """Remove component pin from net."""
+        self._data.remove_connection(reference, pin)
+        self._collection._mark_modified()
+
+    def add_wire(self, wire_uuid: str):
+        """Add wire to net."""
+        if wire_uuid not in self._data.wires:
+            self._data.wires.append(wire_uuid)
+            self._collection._mark_modified()
+
+    def remove_wire(self, wire_uuid: str):
+        """Remove wire from net."""
+        if wire_uuid in self._data.wires:
+            self._data.wires.remove(wire_uuid)
+            self._collection._mark_modified()
+
+    def add_label(self, label_uuid: str):
+        """Add label to net."""
+        if label_uuid not in self._data.labels:
+            self._data.labels.append(label_uuid)
+            self._collection._mark_modified()
+
+    def remove_label(self, label_uuid: str):
+        """Remove label from net."""
+        if label_uuid in self._data.labels:
+            self._data.labels.remove(label_uuid)
+            self._collection._mark_modified()
+
+    def validate(self) -> List[ValidationIssue]:
+        """Validate this net element."""
+        return self._validator.validate_net(self._data.__dict__)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert net element to dictionary representation."""
+        return {
+            "name": self.name,
+            "components": self.components,
+            "wires": self.wires,
+            "labels": self.labels,
+        }
+
+    def __str__(self) -> str:
+        """String representation."""
+        return f"<Net '{self.name}' ({len(self.components)} connections)>"
+
+
+class NetCollection(BaseCollection[NetElement]):
+    """
+    Collection class for efficient net management.
+
+    Inherits from BaseCollection for standard operations and adds net-specific
+    functionality including name-based indexing.
+
+    Provides fast lookup, filtering, and bulk operations for schematic nets.
+    Note: Nets use name as the unique identifier (exposed as .uuid for protocol compatibility).
+    """
+
+    def __init__(self, nets: List[Net] = None):
+        """
+        Initialize net collection.
+
+        Args:
+            nets: Initial list of net data
+        """
+        # Initialize base collection
+        super().__init__([], collection_name="nets")
+
+        # Additional net-specific index (for convenience, duplicates base UUID index)
+        self._name_index: Dict[str, NetElement] = {}
+
+        # Add initial nets
+        if nets:
+            for net_data in nets:
+                self._add_to_indexes(NetElement(net_data, self))
+
+    def add(
+        self,
+        name: str,
+        components: List[Tuple[str, str]] = None,
+        wires: List[str] = None,
+        labels: List[str] = None,
+    ) -> NetElement:
+        """
+        Add a new net to the schematic.
+
+        Args:
+            name: Net name
+            components: Initial component connections
+            wires: Initial wire UUIDs
+            labels: Initial label UUIDs
+
+        Returns:
+            Newly created NetElement
+
+        Raises:
+            ValidationError: If net data is invalid
+        """
+        # Validate inputs
+        if not isinstance(name, str) or not name.strip():
+            raise ValidationError("Net name cannot be empty")
+
+        name = name.strip()
+
+        # Check for duplicate name
+        if name in self._name_index:
+            raise ValidationError(f"Net name {name} already exists")
+
+        # Create net data
+        net_data = Net(
+            name=name,
+            components=components or [],
+            wires=wires or [],
+            labels=labels or [],
+        )
+
+        # Create wrapper and add to collection
+        net_element = NetElement(net_data, self)
+        self._add_to_indexes(net_element)
+        self._mark_modified()
+
+        logger.debug(f"Added net: {net_element}")
+        return net_element
+
+    def get_by_name(self, name: str) -> Optional[NetElement]:
+        """Get net by name (convenience method, equivalent to get(name))."""
+        return self.get(name)
+
+    # get() method inherited from BaseCollection (uses name as UUID)
+
+    def remove(self, name: str) -> bool:
+        """
+        Remove net by name.
+
+        Args:
+            name: Name of net to remove
+
+        Returns:
+            True if net was removed, False if not found
+        """
+        net_element = self.get(name)
+        if not net_element:
+            return False
+
+        # Remove from name index
+        if net_element.name in self._name_index:
+            del self._name_index[net_element.name]
+
+        # Remove using base class method
+        super().remove(name)
+
+        logger.debug(f"Removed net: {net_element}")
+        return True
+
+    def find_by_component(self, reference: str, pin: Optional[str] = None) -> List[NetElement]:
+        """
+        Find nets connected to a component.
+
+        Args:
+            reference: Component reference
+            pin: Specific pin (if None, returns all nets for component)
+
+        Returns:
+            List of matching net elements
+        """
+        matches = []
+        for net_element in self._items:
+            for comp_ref, comp_pin in net_element.components:
+                if comp_ref == reference and (pin is None or comp_pin == pin):
+                    matches.append(net_element)
+                    break
+        return matches
+
+    def filter(self, predicate: Callable[[NetElement], bool]) -> List[NetElement]:
+        """
+        Filter nets by predicate function (delegates to base class find).
+
+        Args:
+            predicate: Function that returns True for nets to include
+
+        Returns:
+            List of nets matching predicate
+        """
+        return self.find(predicate)
+
+    def bulk_update(self, criteria: Callable[[NetElement], bool], updates: Dict[str, Any]):
+        """
+        Update multiple nets matching criteria.
+
+        Args:
+            criteria: Function to select nets to update
+            updates: Dictionary of property updates
+        """
+        updated_count = 0
+        for net_element in self._items:
+            if criteria(net_element):
+                for prop, value in updates.items():
+                    if hasattr(net_element, prop):
+                        setattr(net_element, prop, value)
+                        updated_count += 1
+
+        if updated_count > 0:
+            self._mark_modified()
+            logger.debug(f"Bulk updated {updated_count} net properties")
+
+    def clear(self):
+        """Remove all nets from collection."""
+        self._name_index.clear()
+        super().clear()
+
+    def _add_to_indexes(self, net_element: NetElement):
+        """Add net to internal indexes (base + name index)."""
+        self._add_item(net_element)
+        self._name_index[net_element.name] = net_element
+
+    def _update_name_index(self, old_name: str, net_element: NetElement):
+        """Update name index when net name changes."""
+        if old_name in self._name_index:
+            del self._name_index[old_name]
+        self._name_index[net_element.name] = net_element
+
+    # Collection interface methods - __len__, __iter__, __getitem__ inherited from BaseCollection
+    def __bool__(self) -> bool:
+        """Return True if collection has nets."""
+        return len(self._items) > 0