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

kicad_sch_api/collections/wires.py

@@ -1,8 +1,8 @@
 """
-Wire collection with specialized indexing and wire-specific operations.
+Enhanced wire management with IndexRegistry integration.
 
-Extends the base IndexedCollection to provide wire-specific features like
-endpoint indexing, multi-point wire support, and connectivity management.
+Provides WireCollection using BaseCollection infrastructure with
+endpoint indexing and wire geometry queries.
 """
 
 import logging
@@ -10,397 +10,283 @@ import uuid as uuid_module
 from typing import Any, Dict, List, Optional, Tuple, Union
 
 from ..core.types import Point, Wire, WireType
-from .base import IndexedCollection
+from .base import BaseCollection, IndexSpec, ValidationLevel
 
 logger = logging.getLogger(__name__)
 
 
-class WireCollection(IndexedCollection[Wire]):
+class WireCollection(BaseCollection[Wire]):
     """
-    Professional wire collection with enhanced management features.
+    Wire collection with endpoint indexing and geometry queries.
 
-    Extends IndexedCollection with wire-specific features:
-    - Endpoint indexing for connectivity analysis
+    Inherits from BaseCollection for UUID indexing and adds wire-specific
+    functionality for endpoint queries and wire type filtering.
+
+    Features:
+    - Fast UUID lookup via IndexRegistry
     - Multi-point wire support
-    - Wire type classification (normal, bus, etc.)
-    - Bulk operations for performance
-    - Junction management integration
+    - Endpoint-based queries
+    - Horizontal/vertical wire detection
+    - Lazy index rebuilding
+    - Batch mode support
     """
 
-    def __init__(self, wires: Optional[List[Wire]] = None):
+    def __init__(
+        self,
+        wires: Optional[List[Wire]] = None,
+        validation_level: ValidationLevel = ValidationLevel.NORMAL,
+    ):
         """
         Initialize wire collection.
 
         Args:
             wires: Initial list of wires
+            validation_level: Validation level for operations
         """
-        self._endpoint_index: Dict[Tuple[float, float], List[Wire]] = {}
-        self._type_index: Dict[WireType, List[Wire]] = {}
+        super().__init__(validation_level=validation_level)
+
+        # Add initial wires
+        if wires:
+            with self.batch_mode():
+                for wire in wires:
+                    super().add(wire)
 
-        super().__init__(wires)
+        logger.debug(f"WireCollection initialized with {len(self)} wires")
 
-    # Abstract method implementations
+    # BaseCollection abstract method implementations
     def _get_item_uuid(self, item: Wire) -> str:
         """Extract UUID from wire."""
         return item.uuid
 
     def _create_item(self, **kwargs) -> Wire:
-        """Create a new wire with given parameters."""
-        # This will be called by add() methods
-        raise NotImplementedError("Use add() method instead")
-
-    def _build_additional_indexes(self) -> None:
-        """Build wire-specific indexes."""
-        # Clear existing indexes
-        self._endpoint_index.clear()
-        self._type_index.clear()
-
-        # Rebuild indexes from current items
-        for wire in self._items:
-            # Endpoint index - index by all endpoints
-            for point in wire.points:
-                endpoint = (point.x, point.y)
-                if endpoint not in self._endpoint_index:
-                    self._endpoint_index[endpoint] = []
-                self._endpoint_index[endpoint].append(wire)
-
-            # Type index
-            wire_type = getattr(wire, "wire_type", WireType.WIRE)
-            if wire_type not in self._type_index:
-                self._type_index[wire_type] = []
-            self._type_index[wire_type].append(wire)
-
-    # Wire-specific methods
+        """Create a new wire (not typically used directly)."""
+        raise NotImplementedError("Use add() method to create wires")
+
+    def _get_index_specs(self) -> List[IndexSpec]:
+        """Get index specifications for wire collection."""
+        return [
+            IndexSpec(
+                name="uuid",
+                key_func=lambda w: w.uuid,
+                unique=True,
+                description="UUID index for fast lookups",
+            ),
+        ]
+
+    # Wire-specific add method
     def add(
         self,
-        start: Union[Point, Tuple[float, float]],
-        end: Union[Point, Tuple[float, float]],
-        wire_type: WireType = WireType.WIRE,
-        stroke_width: float = 0.0,
-        stroke_type: str = "default",
-        wire_uuid: Optional[str] = None,
-    ) -> Wire:
-        """
-        Add a new wire to the collection.
-
-        Args:
-            start: Starting point of the wire
-            end: Ending point of the wire
-            wire_type: Type of wire (normal, bus, etc.)
-            stroke_width: Wire stroke width
-            stroke_type: Wire stroke type
-            wire_uuid: Specific UUID for wire (auto-generated if None)
-
-        Returns:
-            Newly created Wire
-        """
-        # Convert tuples to Points if needed
-        if isinstance(start, tuple):
-            start = Point(start[0], start[1])
-        if isinstance(end, tuple):
-            end = Point(end[0], end[1])
-
-        # Validate wire points
-        if start == end:
-            raise ValueError("Wire start and end points cannot be the same")
-
-        # Generate UUID if not provided
-        if wire_uuid is None:
-            wire_uuid = str(uuid_module.uuid4())
-
-        # Create wire
-        wire = Wire(
-            uuid=wire_uuid,
-            points=[start, end],
-            wire_type=wire_type,
-            stroke_width=stroke_width,
-            stroke_type=stroke_type,
-        )
-
-        # Add to collection using base class method
-        return super().add(wire)
-
-    def add_multi_point(
-        self,
-        points: List[Union[Point, Tuple[float, float]]],
+        start: Optional[Union[Point, Tuple[float, float]]] = None,
+        end: Optional[Union[Point, Tuple[float, float]]] = None,
+        points: Optional[List[Union[Point, Tuple[float, float]]]] = None,
         wire_type: WireType = WireType.WIRE,
         stroke_width: float = 0.0,
-        stroke_type: str = "default",
-        wire_uuid: Optional[str] = None,
-    ) -> Wire:
+        uuid: Optional[str] = None,
+    ) -> str:
         """
-        Add a multi-point wire to the collection.
+        Add a wire to the collection.
 
         Args:
-            points: List of points defining the wire path
-            wire_type: Type of wire (normal, bus, etc.)
-            stroke_width: Wire stroke width
-            stroke_type: Wire stroke type
-            wire_uuid: Specific UUID for wire (auto-generated if None)
+            start: Start point (for simple wires)
+            end: End point (for simple wires)
+            points: List of points (for multi-point wires)
+            wire_type: Wire type (wire or bus)
+            stroke_width: Line width
+            uuid: Optional UUID (auto-generated if not provided)
 
         Returns:
-            Newly created Wire
+            UUID of the created wire
 
         Raises:
-            ValueError: If less than 2 points provided
+            ValueError: If neither start/end nor points are provided
+            ValueError: If UUID already exists
         """
-        if len(points) < 2:
-            raise ValueError("Wire must have at least 2 points")
-
-        # Convert tuples to Points if needed
-        converted_points = []
-        for point in points:
-            if isinstance(point, tuple):
-                converted_points.append(Point(point[0], point[1]))
-            else:
-                converted_points.append(point)
-
         # Generate UUID if not provided
-        if wire_uuid is None:
-            wire_uuid = str(uuid_module.uuid4())
-
-        # Create wire
-        wire = Wire(
-            uuid=wire_uuid,
-            points=converted_points,
-            wire_type=wire_type,
-            stroke_width=stroke_width,
-            stroke_type=stroke_type,
-        )
-
-        # Add to collection using base class method
-        return super().add(wire)
-
-    def get_wires_at_point(self, point: Union[Point, Tuple[float, float]]) -> List[Wire]:
-        """
-        Get all wires that pass through a specific point.
-
-        Args:
-            point: Point to search at
-
-        Returns:
-            List of wires passing through the point
-        """
-        self._ensure_indexes_current()
-
-        if isinstance(point, Point):
-            endpoint = (point.x, point.y)
+        if uuid is None:
+            uuid = str(uuid_module.uuid4())
         else:
-            endpoint = point
+            # Check for duplicate
+            self._ensure_indexes_current()
+            if self._index_registry.has_key("uuid", uuid):
+                raise ValueError(f"Wire with UUID '{uuid}' already exists")
+
+        # Convert points
+        wire_points = []
+        if points:
+            # Multi-point wire
+            for point in points:
+                if isinstance(point, tuple):
+                    wire_points.append(Point(point[0], point[1]))
+                else:
+                    wire_points.append(point)
+        elif start is not None and end is not None:
+            # Simple 2-point wire
+            if isinstance(start, tuple):
+                start = Point(start[0], start[1])
+            if isinstance(end, tuple):
+                end = Point(end[0], end[1])
+            wire_points = [start, end]
+        else:
+            raise ValueError("Must provide either start/end points or points list")
 
-        return self._endpoint_index.get(endpoint, []).copy()
+        # Validate wire has at least 2 points
+        if len(wire_points) < 2:
+            raise ValueError("Wire must have at least 2 points")
 
-    def get_wires_by_type(self, wire_type: WireType) -> List[Wire]:
-        """
-        Get all wires of a specific type.
+        # Create wire
+        wire = Wire(uuid=uuid, points=wire_points, wire_type=wire_type, stroke_width=stroke_width)
 
-        Args:
-            wire_type: Type of wires to find
+        # Add to collection
+        super().add(wire)
 
-        Returns:
-            List of wires of the specified type
-        """
-        self._ensure_indexes_current()
-        return self._type_index.get(wire_type, []).copy()
+        logger.debug(f"Added wire: {len(wire_points)} points, UUID={uuid}")
+        return uuid
 
-    def get_connected_wires(self, wire: Wire) -> List[Wire]:
+    # Endpoint-based queries
+    def get_by_endpoint(
+        self, point: Union[Point, Tuple[float, float]], tolerance: float = 0.01
+    ) -> List[Wire]:
         """
-        Get all wires connected to the given wire.
+        Find all wires with an endpoint near a given point.
 
         Args:
-            wire: Wire to find connections for
+            point: Point to search for
+            tolerance: Distance tolerance for matching
 
         Returns:
-            List of connected wires (excluding the input wire)
+            List of wires with endpoint near the point
         """
-        connected = set()
+        if isinstance(point, tuple):
+            point = Point(point[0], point[1])
 
-        # Check connections at all endpoints
-        for point in wire.points:
-            endpoint_wires = self.get_wires_at_point(point)
-            for endpoint_wire in endpoint_wires:
-                if endpoint_wire.uuid != wire.uuid:
-                    connected.add(endpoint_wire)
+        matching_wires = []
+        for wire in self._items:
+            # Check first and last point (endpoints)
+            if (wire.points[0].distance_to(point) <= tolerance or
+                wire.points[-1].distance_to(point) <= tolerance):
+                matching_wires.append(wire)
 
-        return list(connected)
+        return matching_wires
 
-    def find_wire_networks(self) -> List[List[Wire]]:
+    def get_at_point(
+        self, point: Union[Point, Tuple[float, float]], tolerance: float = 0.01
+    ) -> List[Wire]:
         """
-        Find all connected wire networks in the collection.
+        Find all wires that pass through or near a point.
+
+        Args:
+            point: Point to search for
+            tolerance: Distance tolerance for matching
 
         Returns:
-            List of wire networks, each network is a list of connected wires
+            List of wires passing through the point
         """
-        visited = set()
-        networks = []
+        if isinstance(point, tuple):
+            point = Point(point[0], point[1])
 
+        matching_wires = []
         for wire in self._items:
-            if wire.uuid in visited:
-                continue
-
-            # Start a new network with this wire
-            network = []
-            to_visit = [wire]
-
-            while to_visit:
-                current_wire = to_visit.pop()
-                if current_wire.uuid in visited:
-                    continue
-
-                visited.add(current_wire.uuid)
-                network.append(current_wire)
-
-                # Add all connected wires to visit list
-                connected = self.get_connected_wires(current_wire)
-                for connected_wire in connected:
-                    if connected_wire.uuid not in visited:
-                        to_visit.append(connected_wire)
-
-            if network:
-                networks.append(network)
+            # Check if any point in wire is near the search point
+            for wire_point in wire.points:
+                if wire_point.distance_to(point) <= tolerance:
+                    matching_wires.append(wire)
+                    break  # Found match, move to next wire
 
-        return networks
+        return matching_wires
 
-    def modify_wire_path(
-        self, wire_uuid: str, new_points: List[Union[Point, Tuple[float, float]]]
-    ) -> bool:
+    # Wire geometry queries
+    def get_horizontal(self) -> List[Wire]:
         """
-        Modify the path of an existing wire.
-
-        Args:
-            wire_uuid: UUID of wire to modify
-            new_points: New points for the wire path
+        Get all horizontal wires (Y coordinates equal).
 
         Returns:
-            True if wire was modified, False if not found
-
-        Raises:
-            ValueError: If less than 2 points provided
+            List of horizontal wires
         """
-        if len(new_points) < 2:
-            raise ValueError("Wire must have at least 2 points")
-
-        wire = self.get(wire_uuid)
-        if not wire:
-            return False
-
-        # Convert tuples to Points if needed
-        converted_points = []
-        for point in new_points:
-            if isinstance(point, tuple):
-                converted_points.append(Point(point[0], point[1]))
-            else:
-                converted_points.append(point)
-
-        # Update wire points
-        wire.points = converted_points
-        self._mark_modified()
-        self._mark_indexes_dirty()
+        horizontal = []
+        for wire in self._items:
+            if len(wire.points) == 2:
+                # Simple 2-point wire
+                if abs(wire.points[0].y - wire.points[1].y) < 0.01:
+                    horizontal.append(wire)
 
-        logger.debug(f"Modified wire {wire_uuid} path with {len(new_points)} points")
-        return True
+        return horizontal
 
-    # Bulk operations for performance
-    def remove_wires_at_point(self, point: Union[Point, Tuple[float, float]]) -> int:
+    def get_vertical(self) -> List[Wire]:
         """
-        Remove all wires passing through a specific point.
-
-        Args:
-            point: Point where wires should be removed
+        Get all vertical wires (X coordinates equal).
 
         Returns:
-            Number of wires removed
+            List of vertical wires
         """
-        wires_to_remove = self.get_wires_at_point(point)
-
-        for wire in wires_to_remove:
-            self.remove(wire.uuid)
+        vertical = []
+        for wire in self._items:
+            if len(wire.points) == 2:
+                # Simple 2-point wire
+                if abs(wire.points[0].x - wire.points[1].x) < 0.01:
+                    vertical.append(wire)
 
-        logger.info(f"Removed {len(wires_to_remove)} wires at point {point}")
-        return len(wires_to_remove)
+        return vertical
 
-    def bulk_update_stroke(
-        self,
-        wire_type: Optional[WireType] = None,
-        stroke_width: Optional[float] = None,
-        stroke_type: Optional[str] = None,
-    ) -> int:
+    def get_by_type(self, wire_type: WireType) -> List[Wire]:
         """
-        Bulk update stroke properties for wires.
+        Get all wires of a specific type.
 
         Args:
-            wire_type: Filter by wire type (None for all)
-            stroke_width: New stroke width (None to keep existing)
-            stroke_type: New stroke type (None to keep existing)
+            wire_type: Wire type to filter by
 
         Returns:
-            Number of wires updated
+            List of wires matching the type
         """
-        # Get wires to update
-        if wire_type is not None:
-            wires_to_update = self.get_wires_by_type(wire_type)
-        else:
-            wires_to_update = list(self._items)
-
-        # Apply updates
-        for wire in wires_to_update:
-            if stroke_width is not None:
-                wire.stroke_width = stroke_width
-            if stroke_type is not None:
-                wire.stroke_type = stroke_type
-
-        if wires_to_update:
-            self._mark_modified()
+        return [w for w in self._items if w.wire_type == wire_type]
 
-        logger.info(f"Bulk updated stroke properties for {len(wires_to_update)} wires")
-        return len(wires_to_update)
-
-    # Collection statistics
-    def get_connection_statistics(self) -> Dict[str, Any]:
+    # Statistics
+    def get_statistics(self) -> Dict[str, Any]:
         """
-        Get connection statistics for the wire collection.
+        Get wire collection statistics.
 
         Returns:
-            Dictionary with connection statistics
-        """
-        stats = super().get_statistics()
-
-        # Add wire-specific statistics
-        stats.update(
-            {
-                "endpoint_count": len(self._endpoint_index),
-                "wire_types": {
-                    wire_type.value: len(wires) for wire_type, wires in self._type_index.items()
-                },
-                "networks": len(self.find_wire_networks()),
-                "total_length": sum(self._calculate_wire_length(wire) for wire in self._items),
-            }
-        )
-
-        return stats
-
-    def _calculate_wire_length(self, wire: Wire) -> float:
+            Dictionary with wire statistics
         """
-        Calculate the total length of a wire.
-
-        Args:
-            wire: Wire to calculate length for
-
-        Returns:
-            Total wire length
-        """
-        if len(wire.points) < 2:
-            return 0.0
-
-        total_length = 0.0
-        for i in range(len(wire.points) - 1):
-            start_point = wire.points[i]
-            end_point = wire.points[i + 1]
-
-            dx = end_point.x - start_point.x
-            dy = end_point.y - start_point.y
-            segment_length = (dx**2 + dy**2) ** 0.5
-
-            total_length += segment_length
-
-        return total_length
+        if not self._items:
+            base_stats = super().get_statistics()
+            base_stats.update({
+                "total_wires": 0,
+                "total_segments": 0,
+                "wire_count": 0,
+                "bus_count": 0,
+                "horizontal_count": 0,
+                "vertical_count": 0,
+                "avg_points_per_wire": 0,
+            })
+            return base_stats
+
+        wire_count = sum(1 for w in self._items if w.wire_type == WireType.WIRE)
+        bus_count = sum(1 for w in self._items if w.wire_type == WireType.BUS)
+        total_segments = sum(len(w.points) - 1 for w in self._items)
+        avg_points = sum(len(w.points) for w in self._items) / len(self._items)
+
+        horizontal = len(self.get_horizontal())
+        vertical = len(self.get_vertical())
+
+        base_stats = super().get_statistics()
+        base_stats.update({
+            "total_wires": len(self._items),
+            "total_segments": total_segments,
+            "wire_count": wire_count,
+            "bus_count": bus_count,
+            "horizontal_count": horizontal,
+            "vertical_count": vertical,
+            "avg_points_per_wire": avg_points,
+        })
+
+        return base_stats
+
+    # Compatibility methods
+    @property
+    def modified(self) -> bool:
+        """Check if collection has been modified (compatibility)."""
+        return self.is_modified
+
+    def mark_saved(self) -> None:
+        """Mark collection as saved (reset modified flag)."""
+        self.mark_clean()

kicad_sch_api/core/__init__.py

@@ -1,10 +1,28 @@
 """Core kicad-sch-api functionality."""
 
-from .components import Component, ComponentCollection
+from ..collections import Component, ComponentCollection
 from .formatter import ExactFormatter
 from .parser import SExpressionParser
 from .schematic import Schematic, create_schematic, load_schematic
-from .types import Junction, Label, Net, Point, SchematicSymbol, Wire
+from .types import Junction, Label, Net, PinInfo, Point, SchematicSymbol, Wire
+# Exception hierarchy
+from .exceptions import (
+    KiCadSchError,
+    ValidationError,
+    ReferenceError,
+    LibraryError,
+    GeometryError,
+    NetError,
+    ParseError,
+    FormatError,
+    CollectionError,
+    ElementNotFoundError,
+    DuplicateElementError,
+    CollectionOperationError,
+    FileOperationError,
+    CLIError,
+    SchematicStateError,
+)
 
 __all__ = [
     "Schematic",
@@ -16,8 +34,25 @@ __all__ = [
     "Junction",
     "Label",
     "Net",
+    "PinInfo",
     "SExpressionParser",
     "ExactFormatter",
     "load_schematic",
     "create_schematic",
+    # Exceptions
+    "KiCadSchError",
+    "ValidationError",
+    "ReferenceError",
+    "LibraryError",
+    "GeometryError",
+    "NetError",
+    "ParseError",
+    "FormatError",
+    "CollectionError",
+    "ElementNotFoundError",
+    "DuplicateElementError",
+    "CollectionOperationError",
+    "FileOperationError",
+    "CLIError",
+    "SchematicStateError",
 ]