kicad-sch-api 0.4.0__py3-none-any.whl → 0.4.2__py3-none-any.whl

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)

kicad_sch_api/core/component_bounds.py

@@ -384,6 +384,11 @@ def get_component_bounding_box(
 
     # Transform to world coordinates
     # TODO: Handle component rotation in the future
+    # NOTE: Currently assumes 0° rotation. For rotated components, bounding box
+    # would need to be recalculated after applying rotation matrix. This is a
+    # known limitation but doesn't affect most use cases since components are
+    # typically placed without rotation, and routing avoids components regardless.
+    # Priority: LOW - Would improve accuracy for rotated component placement validation
     world_bbox = BoundingBox(
         component.position.x + symbol_bbox.min_x,
         component.position.y + symbol_bbox.min_y,

kicad_sch_api/core/components.py

@@ -11,6 +11,7 @@ from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple, Union
 
 from ..library.cache import SymbolDefinition, get_symbol_cache
 from ..utils.validation import SchematicValidator, ValidationError, ValidationIssue
+from .collections import BaseCollection
 from .ic_manager import ICManager
 from .types import Point, SchematicPin, SchematicSymbol
 
@@ -261,10 +262,13 @@ class Component:
         )
 
 
-class ComponentCollection:
+class ComponentCollection(BaseCollection[Component]):
     """
     Collection class for efficient component management.
 
+    Inherits from BaseCollection for standard operations and adds component-specific
+    functionality including reference, lib_id, and value-based indexing.
+
     Provides fast lookup, filtering, and bulk operations for schematic components.
     Optimized for schematics with hundreds or thousands of components.
     """
@@ -276,19 +280,19 @@ class ComponentCollection:
         Args:
             components: Initial list of component data
         """
-        self._components: List[Component] = []
+        # Initialize base collection
+        super().__init__([], collection_name="components")
+
+        # Additional component-specific indexes
         self._reference_index: Dict[str, Component] = {}
         self._lib_id_index: Dict[str, List[Component]] = {}
         self._value_index: Dict[str, List[Component]] = {}
-        self._modified = False
 
         # Add initial components
         if components:
             for comp_data in components:
                 self._add_to_indexes(Component(comp_data, self))
 
-        logger.debug(f"ComponentCollection initialized with {len(self._components)} components")
-
     def add(
         self,
         lib_id: str,
@@ -375,7 +379,7 @@ class ComponentCollection:
 
         # Add to collection
         self._add_to_indexes(component)
-        self._modified = True
+        self._mark_modified()
 
         logger.info(f"Added component: {reference} ({lib_id})")
         return component
@@ -432,7 +436,7 @@ class ComponentCollection:
             component = Component(component_data, self)
             self._add_to_indexes(component)
 
-        self._modified = True
+        self._mark_modified()
         logger.info(
             f"Added multi-unit IC: {reference_prefix} ({lib_id}) with {len(unit_components)} units"
         )
@@ -444,22 +448,102 @@ class ComponentCollection:
         Remove component by reference.
 
         Args:
-            reference: Component reference to remove
+            reference: Component reference to remove (e.g., "R1")
 
         Returns:
-            True if component was removed
+            True if component was removed, False if not found
+
+        Raises:
+            TypeError: If reference is not a string
+
+        Examples:
+            sch.components.remove("R1")
+            sch.components.remove("C2")
+
+        Note:
+            For removing by UUID or component object, use remove_by_uuid() or remove_component()
+            respectively. This maintains a clear, simple API contract.
         """
+        if not isinstance(reference, str):
+            raise TypeError(f"reference must be a string, not {type(reference).__name__}")
+
         component = self._reference_index.get(reference)
         if not component:
             return False
 
-        # Remove from all indexes
+        # Remove from component-specific indexes
         self._remove_from_indexes(component)
-        self._modified = True
+
+        # Remove from base collection using UUID
+        super().remove(component.uuid)
 
         logger.info(f"Removed component: {reference}")
         return True
 
+    def remove_by_uuid(self, component_uuid: str) -> bool:
+        """
+        Remove component by UUID.
+
+        Args:
+            component_uuid: Component UUID to remove
+
+        Returns:
+            True if component was removed, False if not found
+
+        Raises:
+            TypeError: If UUID is not a string
+        """
+        if not isinstance(component_uuid, str):
+            raise TypeError(f"component_uuid must be a string, not {type(component_uuid).__name__}")
+
+        if component_uuid not in self._uuid_index:
+            return False
+
+        component = self._items[self._uuid_index[component_uuid]]
+
+        # Remove from component-specific indexes
+        self._remove_from_indexes(component)
+
+        # Remove from base collection
+        super().remove(component_uuid)
+
+        logger.info(f"Removed component by UUID: {component_uuid}")
+        return True
+
+    def remove_component(self, component: "Component") -> bool:
+        """
+        Remove component by component object.
+
+        Args:
+            component: Component object to remove
+
+        Returns:
+            True if component was removed, False if not found
+
+        Raises:
+            TypeError: If component is not a Component instance
+
+        Examples:
+            comp = sch.components.get("R1")
+            sch.components.remove_component(comp)
+        """
+        if not isinstance(component, Component):
+            raise TypeError(
+                f"component must be a Component instance, not {type(component).__name__}"
+            )
+
+        if component.uuid not in self._uuid_index:
+            return False
+
+        # Remove from component-specific indexes
+        self._remove_from_indexes(component)
+
+        # Remove from base collection
+        super().remove(component.uuid)
+
+        logger.info(f"Removed component: {component.reference}")
+        return True
+
     def get(self, reference: str) -> Optional[Component]:
         """Get component by reference."""
         return self._reference_index.get(reference)
@@ -479,7 +563,7 @@ class ComponentCollection:
         Returns:
             List of matching components
         """
-        results = list(self._components)
+        results = list(self._items)
 
         # Apply filters
         if "lib_id" in criteria:
@@ -517,7 +601,7 @@ class ComponentCollection:
     def filter_by_type(self, component_type: str) -> List[Component]:
         """Filter components by type (e.g., 'R' for resistors)."""
         return [
-            c for c in self._components if c.symbol_name.upper().startswith(component_type.upper())
+            c for c in self._items if c.symbol_name.upper().startswith(component_type.upper())
         ]
 
     def in_area(self, x1: float, y1: float, x2: float, y2: float) -> List[Component]:
@@ -532,7 +616,7 @@ class ComponentCollection:
             point = Point(point[0], point[1])
 
         results = []
-        for component in self._components:
+        for component in self._items:
             if component.position.distance_to(point) <= radius:
                 results.append(component)
         return results
@@ -564,21 +648,21 @@ class ComponentCollection:
                     component.set_property(key, str(value))
 
         if matching:
-            self._modified = True
+            self._mark_modified()
 
         logger.info(f"Bulk updated {len(matching)} components")
         return len(matching)
 
     def sort_by_reference(self):
         """Sort components by reference designator."""
-        self._components.sort(key=lambda c: c.reference)
+        self._items.sort(key=lambda c: c.reference)
 
     def sort_by_position(self, by_x: bool = True):
         """Sort components by position."""
         if by_x:
-            self._components.sort(key=lambda c: (c.position.x, c.position.y))
+            self._items.sort(key=lambda c: (c.position.x, c.position.y))
         else:
-            self._components.sort(key=lambda c: (c.position.y, c.position.x))
+            self._items.sort(key=lambda c: (c.position.y, c.position.x))
 
     def validate_all(self) -> List[ValidationIssue]:
         """Validate all components in collection."""
@@ -586,12 +670,12 @@ class ComponentCollection:
         validator = SchematicValidator()
 
         # Validate individual components
-        for component in self._components:
+        for component in self._items:
             issues = component.validate()
             all_issues.extend(issues)
 
         # Validate collection-level rules
-        references = [c.reference for c in self._components]
+        references = [c.reference for c in self._items]
         if len(references) != len(set(references)):
             # Find duplicates
             seen = set()
@@ -615,7 +699,7 @@ class ComponentCollection:
         lib_counts = {}
         value_counts = {}
 
-        for component in self._components:
+        for component in self._items:
             # Count by library
             lib = component.library
             lib_counts[lib] = lib_counts.get(lib, 0) + 1
@@ -626,36 +710,47 @@ class ComponentCollection:
                 value_counts[value] = value_counts.get(value, 0) + 1
 
         return {
-            "total_components": len(self._components),
+            "total_components": len(self._items),
             "unique_references": len(self._reference_index),
             "libraries_used": len(lib_counts),
             "library_breakdown": lib_counts,
             "most_common_values": sorted(value_counts.items(), key=lambda x: x[1], reverse=True)[
                 :10
             ],
-            "modified": self._modified,
+            "modified": self.is_modified(),
         }
 
     # Collection interface
-    def __len__(self) -> int:
-        """Number of components."""
-        return len(self._components)
-
-    def __iter__(self) -> Iterator[Component]:
-        """Iterate over components."""
-        return iter(self._components)
+    # __len__, __iter__ inherited from BaseCollection
 
     def __getitem__(self, key: Union[int, str]) -> Component:
-        """Get component by index or reference."""
-        if isinstance(key, int):
-            return self._components[key]
-        elif isinstance(key, str):
+        """
+        Get component by index, UUID, or reference.
+
+        Args:
+            key: Integer index, UUID string, or reference string
+
+        Returns:
+            Component at the specified location
+
+        Raises:
+            KeyError: If UUID or reference not found
+            IndexError: If index out of range
+            TypeError: If key is invalid type
+        """
+        if isinstance(key, str):
+            # Try reference first (most common use case)
             component = self._reference_index.get(key)
-            if component is None:
+            if component is not None:
+                return component
+            # Fall back to UUID lookup (from base class)
+            try:
+                return super().__getitem__(key)
+            except KeyError:
                 raise KeyError(f"Component not found: {key}")
-            return component
         else:
-            raise TypeError(f"Invalid key type: {type(key)}")
+            # Integer index (from base class)
+            return super().__getitem__(key)
 
     def __contains__(self, reference: str) -> bool:
         """Check if reference exists."""
@@ -663,8 +758,11 @@ class ComponentCollection:
 
     # Internal methods
     def _add_to_indexes(self, component: Component):
-        """Add component to all indexes."""
-        self._components.append(component)
+        """Add component to all indexes (base + component-specific)."""
+        # Add to base collection (UUID index)
+        self._add_item(component)
+
+        # Add to reference index
         self._reference_index[component.reference] = component
 
         # Add to lib_id index
@@ -681,8 +779,8 @@ class ComponentCollection:
             self._value_index[value].append(component)
 
     def _remove_from_indexes(self, component: Component):
-        """Remove component from all indexes."""
-        self._components.remove(component)
+        """Remove component from component-specific indexes (not base UUID index)."""
+        # Remove from reference index
         del self._reference_index[component.reference]
 
         # Remove from lib_id index
@@ -705,10 +803,7 @@ class ComponentCollection:
             component = self._reference_index[old_ref]
             del self._reference_index[old_ref]
             self._reference_index[new_ref] = component
-
-    def _mark_modified(self):
-        """Mark collection as modified."""
-        self._modified = True
+            # Note: UUID doesn't change when reference changes, so base index is unaffected
 
     def _generate_reference(self, lib_id: str) -> str:
         """Generate unique reference for component."""
@@ -730,7 +825,7 @@ class ComponentCollection:
         grid_size = 10.0  # 10mm grid
         max_per_row = 10
 
-        row = len(self._components) // max_per_row
-        col = len(self._components) % max_per_row
+        row = len(self._items) // max_per_row
+        col = len(self._items) % max_per_row
 
         return Point(col * grid_size, row * grid_size)