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

kicad_sch_api/collections/base.py

@@ -11,7 +11,7 @@ from typing import Any, Callable, Dict, Generic, Iterator, List, Optional, TypeV
 
 logger = logging.getLogger(__name__)
 
-T = TypeVar('T')  # Type variable for collection items
+T = TypeVar("T")  # Type variable for collection items
 
 
 class IndexedCollection(Generic[T], ABC):
@@ -183,6 +183,7 @@ class IndexedCollection(Generic[T], ABC):
         Returns:
             List of matching items
         """
+
         def matches_criteria(item: T) -> bool:
             for attr, value in criteria.items():
                 if not hasattr(item, attr) or getattr(item, attr) != value:
@@ -257,10 +258,7 @@ class IndexedCollection(Generic[T], ABC):
     def _rebuild_indexes(self) -> None:
         """Rebuild all indexes."""
         # Rebuild UUID index
-        self._uuid_index = {
-            self._get_item_uuid(item): i
-            for i, item in enumerate(self._items)
-        }
+        self._uuid_index = {self._get_item_uuid(item): i for i, item in enumerate(self._items)}
 
         # Let subclasses rebuild their additional indexes
         self._build_additional_indexes()
@@ -282,7 +280,7 @@ class IndexedCollection(Generic[T], ABC):
             "uuid_index_size": len(self._uuid_index),
             "modified": self._modified,
             "indexes_dirty": self._dirty_indexes,
-            "collection_type": self.__class__.__name__
+            "collection_type": self.__class__.__name__,
         }
 
     @property
@@ -293,4 +291,4 @@ class IndexedCollection(Generic[T], ABC):
     def mark_clean(self) -> None:
         """Mark collection as clean (not modified)."""
         self._modified = False
-        logger.debug(f"Marked {self.__class__.__name__} as clean")
+        logger.debug(f"Marked {self.__class__.__name__} as clean")

kicad_sch_api/collections/components.py

@@ -250,6 +250,7 @@ class ComponentCollection(IndexedCollection[Component]):
 
         # Always snap component position to KiCAD grid (1.27mm = 50mil)
         from ..core.geometry import snap_to_grid
+
         snapped_pos = snap_to_grid((position.x, position.y), grid_size=1.27)
         position = Point(snapped_pos[0], snapped_pos[1])
 
@@ -269,7 +270,7 @@ class ComponentCollection(IndexedCollection[Component]):
             in_bom=True,
             on_board=True,
             footprint=footprint,
-            properties=properties.copy()
+            properties=properties.copy(),
         )
 
         # Create component wrapper
@@ -335,16 +336,27 @@ class ComponentCollection(IndexedCollection[Component]):
 
         # Map common component types to standard prefixes
         ref_prefixes = {
-            "R": "R", "Resistor": "R",
-            "C": "C", "Capacitor": "C",
-            "L": "L", "Inductor": "L",
-            "D": "D", "Diode": "D",
-            "Q": "Q", "Transistor": "Q",
-            "U": "U", "IC": "U", "Amplifier": "U",
-            "J": "J", "Connector": "J",
-            "SW": "SW", "Switch": "SW",
-            "F": "F", "Fuse": "F",
-            "TP": "TP", "TestPoint": "TP",
+            "R": "R",
+            "Resistor": "R",
+            "C": "C",
+            "Capacitor": "C",
+            "L": "L",
+            "Inductor": "L",
+            "D": "D",
+            "Diode": "D",
+            "Q": "Q",
+            "Transistor": "Q",
+            "U": "U",
+            "IC": "U",
+            "Amplifier": "U",
+            "J": "J",
+            "Connector": "J",
+            "SW": "SW",
+            "Switch": "SW",
+            "F": "F",
+            "Fuse": "F",
+            "TP": "TP",
+            "TestPoint": "TP",
         }
 
         prefix = ref_prefixes.get(base_ref, "U")
@@ -419,4 +431,4 @@ class ComponentCollection(IndexedCollection[Component]):
         self._mark_indexes_dirty()
 
         logger.info(f"Bulk updated {len(matching_components)} components")
-        return len(matching_components)
+        return len(matching_components)

kicad_sch_api/collections/junctions.py

@@ -89,26 +89,22 @@ class JunctionCollection(IndexedCollection[Junction]):
         pos_key = (position.x, position.y)
         if pos_key in self._position_index:
             existing = self._position_index[pos_key]
-            raise ValueError(f"Junction already exists at position {position} (UUID: {existing.uuid})")
+            raise ValueError(
+                f"Junction already exists at position {position} (UUID: {existing.uuid})"
+            )
 
         # Generate UUID if not provided
         if junction_uuid is None:
             junction_uuid = str(uuid_module.uuid4())
 
         # Create junction
-        junction = Junction(
-            uuid=junction_uuid,
-            position=position,
-            diameter=diameter
-        )
+        junction = Junction(uuid=junction_uuid, position=position, diameter=diameter)
 
         # Add to collection using base class method
         return super().add(junction)
 
     def get_junction_at_position(
-        self,
-        position: Union[Point, Tuple[float, float]],
-        tolerance: float = 0.0
+        self, position: Union[Point, Tuple[float, float]], tolerance: float = 0.0
     ) -> Optional[Junction]:
         """
         Get junction at a specific position.
@@ -137,7 +133,7 @@ class JunctionCollection(IndexedCollection[Junction]):
             for junction in self._items:
                 dx = abs(junction.position.x - target_x)
                 dy = abs(junction.position.y - target_y)
-                distance = (dx ** 2 + dy ** 2) ** 0.5
+                distance = (dx**2 + dy**2) ** 0.5
 
                 if distance <= tolerance:
                     return junction
@@ -145,9 +141,7 @@ class JunctionCollection(IndexedCollection[Junction]):
             return None
 
     def has_junction_at_position(
-        self,
-        position: Union[Point, Tuple[float, float]],
-        tolerance: float = 0.0
+        self, position: Union[Point, Tuple[float, float]], tolerance: float = 0.0
     ) -> bool:
         """
         Check if a junction exists at a specific position.
@@ -162,11 +156,7 @@ class JunctionCollection(IndexedCollection[Junction]):
         return self.get_junction_at_position(position, tolerance) is not None
 
     def find_junctions_in_region(
-        self,
-        min_x: float,
-        min_y: float,
-        max_x: float,
-        max_y: float
+        self, min_x: float, min_y: float, max_x: float, max_y: float
     ) -> List[Junction]:
         """
         Find all junctions within a rectangular region.
@@ -183,16 +173,13 @@ class JunctionCollection(IndexedCollection[Junction]):
         matching_junctions = []
 
         for junction in self._items:
-            if (min_x <= junction.position.x <= max_x and
-                min_y <= junction.position.y <= max_y):
+            if min_x <= junction.position.x <= max_x and min_y <= junction.position.y <= max_y:
                 matching_junctions.append(junction)
 
         return matching_junctions
 
     def update_junction_position(
-        self,
-        junction_uuid: str,
-        new_position: Union[Point, Tuple[float, float]]
+        self, junction_uuid: str, new_position: Union[Point, Tuple[float, float]]
     ) -> bool:
         """
         Update the position of an existing junction.
@@ -286,8 +273,9 @@ class JunctionCollection(IndexedCollection[Junction]):
 
             # Allow small tolerance for floating point precision
             tolerance = grid_size * 0.01
-            if (x_remainder > tolerance and x_remainder < grid_size - tolerance) or \
-               (y_remainder > tolerance and y_remainder < grid_size - tolerance):
+            if (x_remainder > tolerance and x_remainder < grid_size - tolerance) or (
+                y_remainder > tolerance and y_remainder < grid_size - tolerance
+            ):
                 misaligned.append(junction)
 
         return misaligned
@@ -310,8 +298,10 @@ class JunctionCollection(IndexedCollection[Junction]):
             aligned_y = round(junction.position.y / grid_size) * grid_size
 
             # Check if position needs to change
-            if (abs(junction.position.x - aligned_x) > 0.001 or
-                abs(junction.position.y - aligned_y) > 0.001):
+            if (
+                abs(junction.position.x - aligned_x) > 0.001
+                or abs(junction.position.y - aligned_y) > 0.001
+            ):
 
                 # Update position
                 junction.position = Point(aligned_x, aligned_y)
@@ -326,11 +316,7 @@ class JunctionCollection(IndexedCollection[Junction]):
 
     # Bulk operations
     def remove_junctions_in_region(
-        self,
-        min_x: float,
-        min_y: float,
-        max_x: float,
-        max_y: float
+        self, min_x: float, min_y: float, max_x: float, max_y: float
     ) -> int:
         """
         Remove all junctions within a rectangular region.
@@ -365,14 +351,16 @@ class JunctionCollection(IndexedCollection[Junction]):
         # Calculate diameter statistics
         diameters = [junction.diameter for junction in self._items]
         if diameters:
-            stats.update({
-                "diameter_stats": {
-                    "min": min(diameters),
-                    "max": max(diameters),
-                    "average": sum(diameters) / len(diameters)
-                },
-                "grid_aligned": len(self._items) - len(self.validate_grid_alignment()),
-                "misaligned": len(self.validate_grid_alignment())
-            })
-
-        return stats
+            stats.update(
+                {
+                    "diameter_stats": {
+                        "min": min(diameters),
+                        "max": max(diameters),
+                        "average": sum(diameters) / len(diameters),
+                    },
+                    "grid_aligned": len(self._items) - len(self.validate_grid_alignment()),
+                    "misaligned": len(self.validate_grid_alignment()),
+                }
+            )
+
+        return stats

kicad_sch_api/collections/labels.py

@@ -25,7 +25,7 @@ class Label:
         position: Point,
         rotation: float = 0.0,
         label_type: str = "label",
-        effects: Optional[Dict[str, Any]] = None
+        effects: Optional[Dict[str, Any]] = None,
     ):
         self.uuid = uuid
         self.text = text
@@ -150,7 +150,7 @@ class LabelCollection(IndexedCollection[Label]):
             position=position,
             rotation=rotation,
             label_type=label_type,
-            effects=effects or {}
+            effects=effects or {},
         )
 
         # Add to collection using base class method
@@ -176,9 +176,7 @@ class LabelCollection(IndexedCollection[Label]):
             return self._text_index.get(text_key, []).copy()
 
     def get_labels_at_position(
-        self,
-        position: Union[Point, Tuple[float, float]],
-        tolerance: float = 0.0
+        self, position: Union[Point, Tuple[float, float]], tolerance: float = 0.0
     ) -> List[Label]:
         """
         Get all labels at a specific position.
@@ -208,7 +206,7 @@ class LabelCollection(IndexedCollection[Label]):
             for label in self._items:
                 dx = abs(label.position.x - target_x)
                 dy = abs(label.position.y - target_y)
-                distance = (dx ** 2 + dy ** 2) ** 0.5
+                distance = (dx**2 + dy**2) ** 0.5
 
                 if distance <= tolerance:
                     matching_labels.append(label)
@@ -251,11 +249,7 @@ class LabelCollection(IndexedCollection[Label]):
         return self.get_labels_by_text(net_name, case_sensitive)
 
     def find_labels_in_region(
-        self,
-        min_x: float,
-        min_y: float,
-        max_x: float,
-        max_y: float
+        self, min_x: float, min_y: float, max_x: float, max_y: float
     ) -> List[Label]:
         """
         Find all labels within a rectangular region.
@@ -272,8 +266,7 @@ class LabelCollection(IndexedCollection[Label]):
         matching_labels = []
 
         for label in self._items:
-            if (min_x <= label.position.x <= max_x and
-                min_y <= label.position.y <= max_y):
+            if min_x <= label.position.x <= max_x and min_y <= label.position.y <= max_y:
                 matching_labels.append(label)
 
         return matching_labels
@@ -308,9 +301,7 @@ class LabelCollection(IndexedCollection[Label]):
         return True
 
     def update_label_position(
-        self,
-        label_uuid: str,
-        new_position: Union[Point, Tuple[float, float]]
+        self, label_uuid: str, new_position: Union[Point, Tuple[float, float]]
     ) -> bool:
         """
         Update the position of an existing label.
@@ -399,14 +390,15 @@ class LabelCollection(IndexedCollection[Label]):
         stats = super().get_statistics()
 
         # Add label-specific statistics
-        stats.update({
-            "unique_texts": len(self._text_index),
-            "unique_positions": len(self._position_index),
-            "label_types": {
-                label_type: len(labels)
-                for label_type, labels in self._type_index.items()
-            },
-            "net_count": len(self.get_net_names())
-        })
-
-        return stats
+        stats.update(
+            {
+                "unique_texts": len(self._text_index),
+                "unique_positions": len(self._position_index),
+                "label_types": {
+                    label_type: len(labels) for label_type, labels in self._type_index.items()
+                },
+                "net_count": len(self.get_net_names()),
+            }
+        )
+
+        return stats

kicad_sch_api/collections/wires.py

@@ -65,7 +65,7 @@ class WireCollection(IndexedCollection[Wire]):
                 self._endpoint_index[endpoint].append(wire)
 
             # Type index
-            wire_type = getattr(wire, 'wire_type', WireType.WIRE)
+            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)
@@ -114,7 +114,7 @@ class WireCollection(IndexedCollection[Wire]):
             points=[start, end],
             wire_type=wire_type,
             stroke_width=stroke_width,
-            stroke_type=stroke_type
+            stroke_type=stroke_type,
         )
 
         # Add to collection using base class method
@@ -165,7 +165,7 @@ class WireCollection(IndexedCollection[Wire]):
             points=converted_points,
             wire_type=wire_type,
             stroke_width=stroke_width,
-            stroke_type=stroke_type
+            stroke_type=stroke_type,
         )
 
         # Add to collection using base class method
@@ -262,9 +262,7 @@ class WireCollection(IndexedCollection[Wire]):
         return networks
 
     def modify_wire_path(
-        self,
-        wire_uuid: str,
-        new_points: List[Union[Point, Tuple[float, float]]]
+        self, wire_uuid: str, new_points: List[Union[Point, Tuple[float, float]]]
     ) -> bool:
         """
         Modify the path of an existing wire.
@@ -325,7 +323,7 @@ class WireCollection(IndexedCollection[Wire]):
         self,
         wire_type: Optional[WireType] = None,
         stroke_width: Optional[float] = None,
-        stroke_type: Optional[str] = None
+        stroke_type: Optional[str] = None,
     ) -> int:
         """
         Bulk update stroke properties for wires.
@@ -368,15 +366,16 @@ class WireCollection(IndexedCollection[Wire]):
         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)
-        })
+        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
 
@@ -400,8 +399,8 @@ class WireCollection(IndexedCollection[Wire]):
 
             dx = end_point.x - start_point.x
             dy = end_point.y - start_point.y
-            segment_length = (dx ** 2 + dy ** 2) ** 0.5
+            segment_length = (dx**2 + dy**2) ** 0.5
 
             total_length += segment_length
 
-        return total_length
+        return total_length

kicad_sch_api/core/collections/__init__.py

@@ -0,0 +1,5 @@
+"""Collection base classes for schematic elements."""
+
+from .base import BaseCollection
+
+__all__ = ["BaseCollection"]

kicad_sch_api/core/collections/base.py

@@ -0,0 +1,248 @@
+"""
+Base collection class for schematic elements.
+
+Provides common functionality for all collection types including UUID indexing,
+modification tracking, and standard collection operations.
+"""
+
+import logging
+from typing import Any, Callable, Dict, Generic, Iterator, List, Optional, Protocol, TypeVar
+
+logger = logging.getLogger(__name__)
+
+
+class HasUUID(Protocol):
+    """Protocol for objects that have a UUID attribute."""
+
+    @property
+    def uuid(self) -> str:
+        """UUID of the object."""
+        ...
+
+
+T = TypeVar("T", bound=HasUUID)
+
+
+class BaseCollection(Generic[T]):
+    """
+    Generic base class for schematic element collections.
+
+    Provides common functionality:
+    - UUID-based indexing for fast lookup
+    - Modification tracking
+    - Standard collection operations (__len__, __iter__, __getitem__)
+    - Index rebuilding and management
+
+    Type parameter T must implement the HasUUID protocol.
+    """
+
+    def __init__(self, items: Optional[List[T]] = None, collection_name: str = "items") -> None:
+        """
+        Initialize base collection.
+
+        Args:
+            items: Initial list of items
+            collection_name: Name for logging (e.g., "wires", "junctions")
+        """
+        self._items: List[T] = items or []
+        self._uuid_index: Dict[str, int] = {}
+        self._modified = False
+        self._collection_name = collection_name
+
+        # Build UUID index
+        self._rebuild_index()
+
+        logger.debug(f"{collection_name} collection initialized with {len(self._items)} items")
+
+    def _rebuild_index(self) -> None:
+        """Rebuild UUID index for fast lookups."""
+        self._uuid_index = {item.uuid: i for i, item in enumerate(self._items)}
+
+    def _mark_modified(self) -> None:
+        """Mark collection as modified."""
+        self._modified = True
+
+    def is_modified(self) -> bool:
+        """Check if collection has been modified."""
+        return self._modified
+
+    def reset_modified_flag(self) -> None:
+        """Reset modified flag (typically after save)."""
+        self._modified = False
+
+    # Standard collection protocol methods
+    def __len__(self) -> int:
+        """Return number of items in collection."""
+        return len(self._items)
+
+    def __iter__(self) -> Iterator[T]:
+        """Iterate over items in collection."""
+        return iter(self._items)
+
+    def __getitem__(self, key: Any) -> T:
+        """
+        Get item by UUID or index.
+
+        Args:
+            key: UUID string or integer index
+
+        Returns:
+            Item at the specified location
+
+        Raises:
+            KeyError: If UUID not found
+            IndexError: If index out of range
+            TypeError: If key is neither string nor int
+        """
+        if isinstance(key, str):
+            # UUID lookup
+            if key not in self._uuid_index:
+                raise KeyError(f"Item with UUID '{key}' not found")
+            return self._items[self._uuid_index[key]]
+        elif isinstance(key, int):
+            # Index lookup
+            return self._items[key]
+        else:
+            raise TypeError(f"Key must be string (UUID) or int (index), got {type(key)}")
+
+    def __contains__(self, key: Any) -> bool:
+        """
+        Check if item exists in collection.
+
+        Args:
+            key: UUID string or item object
+
+        Returns:
+            True if item exists
+        """
+        if isinstance(key, str):
+            return key in self._uuid_index
+        elif hasattr(key, "uuid"):
+            return key.uuid in self._uuid_index
+        return False
+
+    def get(self, uuid: str) -> Optional[T]:
+        """
+        Get item by UUID.
+
+        Args:
+            uuid: Item UUID
+
+        Returns:
+            Item if found, None otherwise
+        """
+        if uuid not in self._uuid_index:
+            return None
+        return self._items[self._uuid_index[uuid]]
+
+    def remove(self, uuid: str) -> bool:
+        """
+        Remove item by UUID.
+
+        Args:
+            uuid: UUID of item to remove
+
+        Returns:
+            True if item was removed, False if not found
+        """
+        if uuid not in self._uuid_index:
+            return False
+
+        index = self._uuid_index[uuid]
+        del self._items[index]
+        self._rebuild_index()
+        self._mark_modified()
+
+        logger.debug(f"Removed item with UUID {uuid} from {self._collection_name}")
+        return True
+
+    def clear(self) -> None:
+        """Remove all items from collection."""
+        self._items.clear()
+        self._uuid_index.clear()
+        self._mark_modified()
+        logger.debug(f"Cleared all items from {self._collection_name}")
+
+    def find(self, predicate: Callable[[T], bool]) -> List[T]:
+        """
+        Find all items matching a predicate.
+
+        Args:
+            predicate: Function that returns True for matching items
+
+        Returns:
+            List of matching items
+        """
+        return [item for item in self._items if predicate(item)]
+
+    def filter(self, **criteria) -> List[T]:
+        """
+        Filter items by attribute values.
+
+        Args:
+            **criteria: Attribute name/value pairs to match
+
+        Returns:
+            List of matching items
+
+        Example:
+            collection.filter(wire_type=WireType.BUS, stroke_width=0.5)
+        """
+        matches = []
+        for item in self._items:
+            if all(getattr(item, key, None) == value for key, value in criteria.items()):
+                matches.append(item)
+        return matches
+
+    def get_statistics(self) -> Dict[str, Any]:
+        """
+        Get collection statistics.
+
+        Returns:
+            Dictionary with statistics
+        """
+        return {
+            "total_items": len(self._items),
+            "modified": self._modified,
+            "indexed_items": len(self._uuid_index),
+        }
+
+    def _add_item(self, item: T) -> None:
+        """
+        Add item to internal storage and index.
+
+        Args:
+            item: Item to add
+
+        Raises:
+            ValueError: If item UUID already exists
+        """
+        if item.uuid in self._uuid_index:
+            raise ValueError(f"Item with UUID '{item.uuid}' already exists")
+
+        self._items.append(item)
+        self._uuid_index[item.uuid] = len(self._items) - 1
+        self._mark_modified()
+
+    def bulk_update(self, criteria: Dict[str, Any], updates: Dict[str, Any]) -> int:
+        """
+        Update multiple items matching criteria.
+
+        Args:
+            criteria: Attribute name/value pairs to match
+            updates: Attribute name/value pairs to update
+
+        Returns:
+            Number of items updated
+        """
+        matching_items = self.filter(**criteria)
+        for item in matching_items:
+            for key, value in updates.items():
+                if hasattr(item, key):
+                    setattr(item, key, value)
+
+        if matching_items:
+            self._mark_modified()
+
+        logger.debug(f"Bulk updated {len(matching_items)} items in {self._collection_name}")
+        return len(matching_items)