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

kicad_sch_api/collections/base.py

@@ -1,51 +1,308 @@
 """
-Base collection class for unified schematic element management.
-
-Provides common functionality for indexing, searching, and managing
-collections of schematic elements with performance optimization.
+Base collection infrastructure with centralized index management.
+
+Provides:
+- IndexSpec: Index specification and declaration
+- IndexRegistry: Centralized index management with lazy rebuilding
+- PropertyDict: Auto-tracking dictionary for modification detection
+- ValidationLevel: Configurable validation levels
+- BaseCollection: Abstract base class for all collections
 """
 
 import logging
 from abc import ABC, abstractmethod
-from typing import Any, Callable, Dict, Generic, Iterator, List, Optional, TypeVar, Union
+from collections.abc import MutableMapping
+from dataclasses import dataclass
+from enum import Enum
+from functools import total_ordering
+from typing import Any, Callable, Dict, Generic, Iterator, List, Optional, Set, TypeVar, Union
 
 logger = logging.getLogger(__name__)
 
 T = TypeVar("T")  # Type variable for collection items
 
 
-class IndexedCollection(Generic[T], ABC):
+@total_ordering
+class ValidationLevel(Enum):
+    """
+    Validation level for collection operations.
+
+    Controls the amount of validation performed during collection operations.
+    Higher levels provide more safety but lower performance.
+    """
+    NONE = 0        # No validation (maximum performance)
+    BASIC = 1       # Basic checks (duplicates, nulls)
+    NORMAL = 2      # Standard validation (default)
+    STRICT = 3      # Strict validation (referential integrity)
+    PARANOID = 4    # Maximum validation (everything, very slow)
+
+    def __lt__(self, other):
+        """Compare validation levels by value."""
+        if isinstance(other, ValidationLevel):
+            return self.value < other.value
+        return NotImplemented
+
+
+@dataclass
+class IndexSpec:
+    """
+    Specification for a collection index.
+
+    Defines how to build and maintain an index for fast lookups.
+    """
+    name: str
+    key_func: Callable[[Any], Any]
+    unique: bool = True
+    description: str = ""
+
+    def __post_init__(self):
+        """Validate index specification."""
+        if not self.name:
+            raise ValueError("Index name cannot be empty")
+        if not callable(self.key_func):
+            raise ValueError("Index key_func must be callable")
+
+
+class IndexRegistry:
+    """
+    Centralized registry for managing collection indexes.
+
+    Provides:
+    - Lazy index rebuilding (only when needed)
+    - Multiple index support (uuid, reference, lib_id, etc.)
+    - Duplicate detection for unique indexes
+    - Unified index management API
+    """
+
+    def __init__(self, specs: List[IndexSpec]):
+        """
+        Initialize index registry.
+
+        Args:
+            specs: List of index specifications to manage
+        """
+        self.specs = {spec.name: spec for spec in specs}
+        self.indexes: Dict[str, Dict[Any, Any]] = {spec.name: {} for spec in specs}
+        self._dirty = False
+
+        logger.debug(f"IndexRegistry initialized with {len(specs)} indexes: {list(self.specs.keys())}")
+
+    def mark_dirty(self) -> None:
+        """Mark all indexes as needing rebuild."""
+        self._dirty = True
+        logger.debug("Indexes marked dirty")
+
+    def is_dirty(self) -> bool:
+        """Check if indexes need rebuilding."""
+        return self._dirty
+
+    def rebuild(self, items: List[Any]) -> None:
+        """
+        Rebuild all indexes from items.
+
+        Args:
+            items: List of items to index
+
+        Raises:
+            ValueError: If unique index has duplicates
+        """
+        logger.debug(f"Rebuilding {len(self.indexes)} indexes for {len(items)} items")
+
+        # Clear all indexes
+        for index_name in self.indexes:
+            self.indexes[index_name].clear()
+
+        # Rebuild each index
+        for spec in self.specs.values():
+            self._rebuild_index(spec, items)
+
+        self._dirty = False
+        logger.debug("Index rebuild complete")
+
+    def _rebuild_index(self, spec: IndexSpec, items: List[Any]) -> None:
+        """
+        Rebuild a single index.
+
+        Args:
+            spec: Index specification
+            items: Items to index
+
+        Raises:
+            ValueError: If unique index has duplicates
+        """
+        index = self.indexes[spec.name]
+
+        for i, item in enumerate(items):
+            try:
+                key = spec.key_func(item)
+
+                if spec.unique:
+                    if key in index:
+                        raise ValueError(
+                            f"Duplicate key '{key}' in unique index '{spec.name}'"
+                        )
+                    index[key] = i
+                else:
+                    # Non-unique index: multiple items per key
+                    if key not in index:
+                        index[key] = []
+                    index[key].append(i)
+
+            except ValueError:
+                # Re-raise ValueError (e.g., duplicate key)
+                raise
+            except Exception as e:
+                # Log and skip other errors (e.g., key_func failure)
+                logger.warning(f"Failed to index item {i} in '{spec.name}': {e}")
+                # Continue indexing other items
+
+    def get(self, index_name: str, key: Any) -> Optional[Any]:
+        """
+        Get value from an index.
+
+        Args:
+            index_name: Name of the index
+            key: Key to look up
+
+        Returns:
+            Index value if found, None otherwise
+        """
+        if index_name not in self.indexes:
+            raise KeyError(f"Unknown index: {index_name}")
+
+        return self.indexes[index_name].get(key)
+
+    def has_key(self, index_name: str, key: Any) -> bool:
+        """
+        Check if key exists in index.
+
+        Args:
+            index_name: Name of the index
+            key: Key to check
+
+        Returns:
+            True if key exists, False otherwise
+        """
+        if index_name not in self.indexes:
+            raise KeyError(f"Unknown index: {index_name}")
+
+        return key in self.indexes[index_name]
+
+    def add_spec(self, spec: IndexSpec) -> None:
+        """
+        Add a new index specification.
+
+        Args:
+            spec: Index specification to add
+        """
+        if spec.name in self.specs:
+            raise ValueError(f"Index '{spec.name}' already exists")
+
+        self.specs[spec.name] = spec
+        self.indexes[spec.name] = {}
+        self.mark_dirty()
+
+        logger.debug(f"Added index spec: {spec.name}")
+
+
+class PropertyDict(MutableMapping):
     """
-    Base class for all schematic element collections with automatic indexing.
+    Dictionary that automatically tracks modifications.
+
+    Wraps a dictionary and notifies a callback when any changes occur.
+    Implements the full MutableMapping interface.
+    """
+
+    def __init__(self, data: Optional[Dict[str, Any]] = None, on_modify: Optional[Callable[[], None]] = None):
+        """
+        Initialize property dictionary.
+
+        Args:
+            data: Initial dictionary data
+            on_modify: Callback to invoke when dict is modified
+        """
+        self._data = data or {}
+        self._on_modify = on_modify
+
+    def __getitem__(self, key: str) -> Any:
+        """Get item by key."""
+        return self._data[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set item and trigger modification callback."""
+        self._data[key] = value
+        if self._on_modify:
+            self._on_modify()
+
+    def __delitem__(self, key: str) -> None:
+        """Delete item and trigger modification callback."""
+        del self._data[key]
+        if self._on_modify:
+            self._on_modify()
+
+    def __iter__(self) -> Iterator[str]:
+        """Iterate over keys."""
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        """Number of items."""
+        return len(self._data)
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return f"PropertyDict({self._data!r})"
+
+    def set_callback(self, on_modify: Callable[[], None]) -> None:
+        """Set or update the modification callback."""
+        self._on_modify = on_modify
+
+
+class BaseCollection(Generic[T], ABC):
+    """
+    Abstract base class for all schematic element collections.
 
     Provides unified functionality for:
-    - UUID-based fast lookups
-    - Automatic index management
-    - Modification tracking
-    - Consistent iteration interface
-    - Performance optimization for large collections
+    - Lazy index rebuilding via IndexRegistry
+    - Automatic modification tracking
+    - Configurable validation levels
+    - Batch mode for performance
+    - Consistent collection operations (add, remove, get, filter)
+
+    Subclasses must implement:
+    - _get_item_uuid(item): Extract UUID from item
+    - _create_item(**kwargs): Create new item instance
+    - _get_index_specs(): Return list of IndexSpec for this collection
     """
 
-    def __init__(self, items: Optional[List[T]] = None):
+    def __init__(
+        self,
+        items: Optional[List[T]] = None,
+        validation_level: ValidationLevel = ValidationLevel.NORMAL
+    ):
         """
-        Initialize indexed collection.
+        Initialize base collection.
 
         Args:
-            items: Initial list of items to add to collection
+            items: Initial list of items
+            validation_level: Validation level for operations
         """
         self._items: List[T] = []
-        self._uuid_index: Dict[str, int] = {}
+        self._validation_level = validation_level
         self._modified = False
-        self._dirty_indexes = False
+        self._batch_mode = False
 
-        # Add initial items if provided
+        # Set up index registry with subclass-specific indexes
+        index_specs = self._get_index_specs()
+        self._index_registry = IndexRegistry(index_specs)
+
+        # Add initial items
         if items:
             for item in items:
                 self._add_item_to_collection(item)
 
         logger.debug(f"{self.__class__.__name__} initialized with {len(self._items)} items")
 
-    # Abstract methods for subclasses to implement
+    # Abstract methods for subclasses
     @abstractmethod
     def _get_item_uuid(self, item: T) -> str:
         """
@@ -55,7 +312,7 @@ class IndexedCollection(Generic[T], ABC):
             item: Item to extract UUID from
 
         Returns:
-            UUID string for the item
+            UUID string
         """
         pass
 
@@ -73,12 +330,12 @@ class IndexedCollection(Generic[T], ABC):
         pass
 
     @abstractmethod
-    def _build_additional_indexes(self) -> None:
+    def _get_index_specs(self) -> List[IndexSpec]:
         """
-        Build any additional indexes specific to the collection type.
+        Get index specifications for this collection.
 
-        Called after UUID index is rebuilt. Subclasses should implement
-        this to maintain their own specialized indexes.
+        Returns:
+            List of IndexSpec defining indexes for this collection
         """
         pass
 
@@ -96,14 +353,17 @@ class IndexedCollection(Generic[T], ABC):
         Raises:
             ValueError: If item with same UUID already exists
         """
-        uuid_str = self._get_item_uuid(item)
+        # Validation
+        if self._validation_level >= ValidationLevel.BASIC:
+            if item is None:
+                raise ValueError("Cannot add None item to collection")
 
-        # Ensure indexes are current before checking for duplicates
-        self._ensure_indexes_current()
+            uuid_str = self._get_item_uuid(item)
 
-        # Check for duplicate UUID
-        if uuid_str in self._uuid_index:
-            raise ValueError(f"Item with UUID {uuid_str} already exists")
+            # Check for duplicate UUID
+            self._ensure_indexes_current()
+            if self._index_registry.has_key("uuid", uuid_str):
+                raise ValueError(f"Item with UUID {uuid_str} already exists")
 
         return self._add_item_to_collection(item)
 
@@ -121,24 +381,22 @@ class IndexedCollection(Generic[T], ABC):
 
         if isinstance(identifier, str):
             # Remove by UUID
-            if identifier not in self._uuid_index:
+            index = self._index_registry.get("uuid", identifier)
+            if index is None:
                 return False
-
-            index = self._uuid_index[identifier]
             item = self._items[index]
         else:
             # Remove by item instance
             item = identifier
             uuid_str = self._get_item_uuid(item)
-            if uuid_str not in self._uuid_index:
+            index = self._index_registry.get("uuid", uuid_str)
+            if index is None:
                 return False
 
-            index = self._uuid_index[uuid_str]
-
         # Remove from main list
         self._items.pop(index)
         self._mark_modified()
-        self._mark_indexes_dirty()
+        self._index_registry.mark_dirty()
 
         logger.debug(f"Removed item with UUID {self._get_item_uuid(item)}")
         return True
@@ -155,8 +413,8 @@ class IndexedCollection(Generic[T], ABC):
         """
         self._ensure_indexes_current()
 
-        if uuid in self._uuid_index:
-            index = self._uuid_index[uuid]
+        index = self._index_registry.get("uuid", uuid)
+        if index is not None:
             return self._items[index]
 
         return None
@@ -183,7 +441,6 @@ 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:
@@ -195,10 +452,25 @@ class IndexedCollection(Generic[T], ABC):
     def clear(self) -> None:
         """Clear all items from the collection."""
         self._items.clear()
-        self._uuid_index.clear()
+        self._index_registry.mark_dirty()
         self._mark_modified()
         logger.debug(f"Cleared all items from {self.__class__.__name__}")
 
+    # Batch mode operations
+    def batch_mode(self):
+        """
+        Context manager for batch operations.
+
+        Defers index rebuilding until the batch is complete.
+
+        Example:
+            with collection.batch_mode():
+                for i in range(1000):
+                    collection.add(create_item(i))
+            # Indexes rebuilt only once here
+        """
+        return BatchContext(self)
+
     # Collection interface methods
     def __len__(self) -> int:
         """Number of items in collection."""
@@ -213,12 +485,12 @@ class IndexedCollection(Generic[T], ABC):
         if isinstance(item, str):
             # Check by UUID
             self._ensure_indexes_current()
-            return item in self._uuid_index
+            return self._index_registry.has_key("uuid", item)
         else:
             # Check by item instance
             uuid_str = self._get_item_uuid(item)
             self._ensure_indexes_current()
-            return uuid_str in self._uuid_index
+            return self._index_registry.has_key("uuid", uuid_str)
 
     def __getitem__(self, index: int) -> T:
         """Get item by index."""
@@ -237,7 +509,10 @@ class IndexedCollection(Generic[T], ABC):
         """
         self._items.append(item)
         self._mark_modified()
-        self._mark_indexes_dirty()
+
+        # Always mark indexes as dirty when items change
+        # Batch mode just defers the rebuild, not the dirty flag
+        self._index_registry.mark_dirty()
 
         logger.debug(f"Added item with UUID {self._get_item_uuid(item)}")
         return item
@@ -246,24 +521,14 @@ class IndexedCollection(Generic[T], ABC):
         """Mark collection as modified."""
         self._modified = True
 
-    def _mark_indexes_dirty(self) -> None:
-        """Mark indexes as needing rebuild."""
-        self._dirty_indexes = True
-
     def _ensure_indexes_current(self) -> None:
-        """Ensure all indexes are current."""
-        if self._dirty_indexes:
+        """Ensure all indexes are current (unless in batch mode)."""
+        if not self._batch_mode and self._index_registry.is_dirty():
             self._rebuild_indexes()
 
     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)}
-
-        # Let subclasses rebuild their additional indexes
-        self._build_additional_indexes()
-
-        self._dirty_indexes = False
+        self._index_registry.rebuild(self._items)
         logger.debug(f"Rebuilt indexes for {self.__class__.__name__}")
 
     # Collection statistics and debugging
@@ -277,10 +542,12 @@ class IndexedCollection(Generic[T], ABC):
         self._ensure_indexes_current()
         return {
             "item_count": len(self._items),
-            "uuid_index_size": len(self._uuid_index),
+            "index_count": len(self._index_registry.indexes),
             "modified": self._modified,
-            "indexes_dirty": self._dirty_indexes,
+            "indexes_dirty": self._index_registry.is_dirty(),
             "collection_type": self.__class__.__name__,
+            "validation_level": self._validation_level.name,
+            "batch_mode": self._batch_mode,
         }
 
     @property
@@ -292,3 +559,46 @@ class IndexedCollection(Generic[T], ABC):
         """Mark collection as clean (not modified)."""
         self._modified = False
         logger.debug(f"Marked {self.__class__.__name__} as clean")
+
+    @property
+    def validation_level(self) -> ValidationLevel:
+        """Current validation level."""
+        return self._validation_level
+
+    def set_validation_level(self, level: ValidationLevel) -> None:
+        """
+        Set validation level.
+
+        Args:
+            level: New validation level
+        """
+        self._validation_level = level
+        logger.debug(f"Set validation level to {level.name}")
+
+
+class BatchContext:
+    """Context manager for batch operations."""
+
+    def __init__(self, collection: BaseCollection):
+        """
+        Initialize batch context.
+
+        Args:
+            collection: Collection to batch operations on
+        """
+        self.collection = collection
+
+    def __enter__(self):
+        """Enter batch mode - defers index rebuilds."""
+        self.collection._batch_mode = True
+        logger.debug(f"Entered batch mode for {self.collection.__class__.__name__}")
+        return self.collection
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit batch mode and rebuild indexes if needed."""
+        self.collection._batch_mode = False
+        # Indexes are already marked dirty by add operations
+        # Just ensure they're rebuilt now
+        self.collection._ensure_indexes_current()
+        logger.debug(f"Exited batch mode for {self.collection.__class__.__name__}")
+        return False