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

kicad_sch_api/collections/labels.py

@@ -1,404 +1,508 @@
 """
-Label collection with specialized indexing and label-specific operations.
+Enhanced label management with IndexRegistry integration.
 
-Extends the base IndexedCollection to provide label-specific features like
-text indexing, position-based queries, and label type classification.
+Provides LabelElement wrapper and LabelCollection using BaseCollection
+infrastructure with text indexing and position-based queries.
 """
 
 import logging
 import uuid as uuid_module
 from typing import Any, Dict, List, Optional, Tuple, Union
 
-from ..core.types import Point
-from .base import IndexedCollection
+from ..core.types import Label, Point
+from ..utils.validation import SchematicValidator, ValidationError, ValidationIssue
+from .base import BaseCollection, IndexSpec, ValidationLevel
 
 logger = logging.getLogger(__name__)
 
 
-class Label:
-    """Label data structure."""
+class LabelElement:
+    """
+    Enhanced wrapper for schematic label elements.
 
-    def __init__(
-        self,
-        uuid: str,
-        text: str,
-        position: Point,
-        rotation: float = 0.0,
-        label_type: str = "label",
-        effects: Optional[Dict[str, Any]] = None,
-    ):
-        self.uuid = uuid
-        self.text = text
-        self.position = position
-        self.rotation = rotation
-        self.label_type = label_type  # "label", "global_label", "hierarchical_label"
-        self.effects = effects or {}
+    Provides intuitive access to label properties and operations
+    while maintaining exact format preservation. All property
+    modifications automatically notify the parent collection.
+    """
+
+    def __init__(self, label_data: Label, parent_collection: "LabelCollection"):
+        """
+        Initialize label element wrapper.
+
+        Args:
+            label_data: Underlying label data
+            parent_collection: Parent collection for modification tracking
+        """
+        self._data = label_data
+        self._collection = parent_collection
+        self._validator = SchematicValidator()
+
+    # Core properties with validation
+    @property
+    def uuid(self) -> str:
+        """Label element UUID (read-only)."""
+        return self._data.uuid
+
+    @property
+    def text(self) -> str:
+        """Label text (net name)."""
+        return self._data.text
+
+    @text.setter
+    def text(self, value: str):
+        """
+        Set label text with validation.
+
+        Args:
+            value: New label text
+
+        Raises:
+            ValidationError: If text is empty
+        """
+        if not isinstance(value, str) or not value.strip():
+            raise ValidationError("Label text cannot be empty")
+
+        old_text = self._data.text
+        self._data.text = value.strip()
+        self._collection._update_text_index(old_text, self)
+        self._collection._mark_modified()
+        logger.debug(f"Updated label text: '{old_text}' -> '{value}'")
+
+    @property
+    def position(self) -> Point:
+        """Label position in schematic."""
+        return self._data.position
+
+    @position.setter
+    def position(self, value: Union[Point, Tuple[float, float]]):
+        """Set label position."""
+        if isinstance(value, tuple):
+            value = Point(value[0], value[1])
+        elif not isinstance(value, Point):
+            raise ValidationError(f"Position must be Point or tuple, got {type(value)}")
+
+        self._data.position = value
+        self._collection._mark_modified()
+
+    @property
+    def rotation(self) -> float:
+        """Label rotation in degrees."""
+        return self._data.rotation
+
+    @rotation.setter
+    def rotation(self, value: float):
+        """Set label rotation."""
+        self._data.rotation = float(value)
+        self._collection._mark_modified()
+
+    @property
+    def size(self) -> float:
+        """Label text size."""
+        return self._data.size
+
+    @size.setter
+    def size(self, value: float):
+        """
+        Set label size with validation.
+
+        Args:
+            value: New text size
+
+        Raises:
+            ValidationError: If size is not positive
+        """
+        if value <= 0:
+            raise ValidationError(f"Label size must be positive, got {value}")
+
+        self._data.size = float(value)
+        self._collection._mark_modified()
+
+    # Utility methods
+    def move(self, x: float, y: float):
+        """Move label to absolute position."""
+        self.position = Point(x, y)
+
+    def translate(self, dx: float, dy: float):
+        """Translate label by offset."""
+        current = self.position
+        self.position = Point(current.x + dx, current.y + dy)
+
+    def rotate_by(self, angle: float):
+        """Rotate label by angle (cumulative)."""
+        self.rotation = (self.rotation + angle) % 360
+
+    def validate(self) -> List[ValidationIssue]:
+        """
+        Validate this label element.
+
+        Returns:
+            List of validation issues (empty if valid)
+        """
+        issues = []
+
+        # Validate text is not empty
+        if not self.text or not self.text.strip():
+            issues.append(
+                ValidationIssue(
+                    category="label",
+                    message="Label text is empty",
+                    level="error"
+                )
+            )
+
+        # Validate size is positive
+        if self.size <= 0:
+            issues.append(
+                ValidationIssue(
+                    category="label",
+                    message=f"Label size must be positive, got {self.size}",
+                    level="error"
+                )
+            )
+
+        return issues
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert label to dictionary representation.
+
+        Returns:
+            Dictionary with label data
+        """
+        return {
+            "text": self.text,
+            "position": {"x": self.position.x, "y": self.position.y},
+            "rotation": self.rotation,
+            "size": self.size,
+        }
+
+    def __str__(self) -> str:
+        """String representation for display."""
+        return f"<Label '{self.text}' @ {self.position}>"
 
     def __repr__(self) -> str:
-        return f"Label(text='{self.text}', pos={self.position}, type='{self.label_type}')"
+        """Detailed representation for debugging."""
+        return f"LabelElement(text='{self.text}', pos={self.position}, rotation={self.rotation})"
 
 
-class LabelCollection(IndexedCollection[Label]):
+class LabelCollection(BaseCollection[LabelElement]):
     """
-    Collection class for efficient label management.
-
-    Extends IndexedCollection with label-specific features:
-    - Text indexing for finding labels by text content
-    - Position indexing for spatial queries
-    - Type classification (local, global, hierarchical)
-    - Net name management
-    - Connectivity analysis support
+    Label collection with text indexing and position queries.
+
+    Inherits from BaseCollection for UUID indexing and adds label-specific
+    functionality including text-based searches and filtering.
+
+    Features:
+    - Fast UUID lookup via IndexRegistry
+    - Text-based label indexing
+    - Position-based queries
+    - Lazy index rebuilding
+    - Batch mode support
     """
 
-    def __init__(self, labels: Optional[List[Label]] = None):
+    def __init__(
+        self,
+        labels: Optional[List[Label]] = None,
+        validation_level: ValidationLevel = ValidationLevel.NORMAL,
+    ):
         """
         Initialize label collection.
 
         Args:
-            labels: Initial list of labels
+            labels: Initial list of label data
+            validation_level: Validation level for operations
         """
-        self._text_index: Dict[str, List[Label]] = {}
-        self._position_index: Dict[Tuple[float, float], List[Label]] = {}
-        self._type_index: Dict[str, List[Label]] = {}
+        super().__init__(validation_level=validation_level)
 
-        super().__init__(labels)
+        # Manual text index (non-unique - multiple labels can have same text)
+        self._text_index: Dict[str, List[LabelElement]] = {}
 
-    # Abstract method implementations
-    def _get_item_uuid(self, item: Label) -> str:
-        """Extract UUID from label."""
-        return item.uuid
+        # Add initial labels
+        if labels:
+            with self.batch_mode():
+                for label_data in labels:
+                    label_element = LabelElement(label_data, self)
+                    super().add(label_element)
+                    self._add_to_text_index(label_element)
 
-    def _create_item(self, **kwargs) -> Label:
-        """Create a new label with given parameters."""
-        # This will be called by add() methods
-        raise NotImplementedError("Use add() method instead")
+        logger.debug(f"LabelCollection initialized with {len(self)} labels")
 
-    def _build_additional_indexes(self) -> None:
-        """Build label-specific indexes."""
-        # Clear existing indexes
-        self._text_index.clear()
-        self._position_index.clear()
-        self._type_index.clear()
+    # BaseCollection abstract method implementations
+    def _get_item_uuid(self, item: LabelElement) -> str:
+        """Extract UUID from label element."""
+        return item.uuid
 
-        # Rebuild indexes from current items
-        for label in self._items:
-            # Text index
-            text_key = label.text.lower()  # Case-insensitive
-            if text_key not in self._text_index:
-                self._text_index[text_key] = []
-            self._text_index[text_key].append(label)
-
-            # Position index
-            pos_key = (label.position.x, label.position.y)
-            if pos_key not in self._position_index:
-                self._position_index[pos_key] = []
-            self._position_index[pos_key].append(label)
-
-            # Type index
-            if label.label_type not in self._type_index:
-                self._type_index[label.label_type] = []
-            self._type_index[label.label_type].append(label)
-
-    # Label-specific methods
+    def _create_item(self, **kwargs) -> LabelElement:
+        """Create a new label (not typically used directly)."""
+        raise NotImplementedError("Use add() method to create labels")
+
+    def _get_index_specs(self) -> List[IndexSpec]:
+        """Get index specifications for label collection."""
+        return [
+            IndexSpec(
+                name="uuid",
+                key_func=lambda l: l.uuid,
+                unique=True,
+                description="UUID index for fast lookups",
+            ),
+        ]
+
+    # Label-specific add method
     def add(
         self,
         text: str,
         position: Union[Point, Tuple[float, float]],
-        label_type: str = "label",
         rotation: float = 0.0,
-        effects: Optional[Dict[str, Any]] = None,
-        label_uuid: Optional[str] = None,
-    ) -> Label:
+        size: float = 1.27,
+        justify_h: str = "left",
+        justify_v: str = "bottom",
+        uuid: Optional[str] = None,
+    ) -> LabelElement:
         """
-        Add a new label to the collection.
+        Add a label to the collection.
 
         Args:
-            text: Label text content
+            text: Label text (net name)
             position: Label position
-            label_type: Type of label ("label", "global_label", "hierarchical_label")
             rotation: Label rotation in degrees
-            effects: Label effects (font, size, etc.)
-            label_uuid: Specific UUID for label (auto-generated if None)
+            size: Text size
+            justify_h: Horizontal justification ("left", "right", "center")
+            justify_v: Vertical justification ("top", "bottom", "center")
+            uuid: Optional UUID (auto-generated if not provided)
 
         Returns:
-            Newly created Label
+            LabelElement wrapper for the created label
 
         Raises:
-            ValueError: If invalid parameters provided
+            ValueError: If UUID already exists or text is empty
         """
         # Validate text
-        if not text.strip():
+        if not text or not text.strip():
             raise ValueError("Label text cannot be empty")
 
-        # Convert tuple to Point if needed
+        # Generate UUID if not provided
+        if uuid is None:
+            uuid = str(uuid_module.uuid4())
+        else:
+            # Check for duplicate
+            self._ensure_indexes_current()
+            if self._index_registry.has_key("uuid", uuid):
+                raise ValueError(f"Label with UUID '{uuid}' already exists")
+
+        # Convert position
         if isinstance(position, tuple):
             position = Point(position[0], position[1])
 
-        # Validate label type
-        valid_types = ["label", "global_label", "hierarchical_label"]
-        if label_type not in valid_types:
-            raise ValueError(f"Invalid label type: {label_type}. Must be one of {valid_types}")
-
-        # Generate UUID if not provided
-        if label_uuid is None:
-            label_uuid = str(uuid_module.uuid4())
-
-        # Create label
-        label = Label(
-            uuid=label_uuid,
-            text=text,
+        # Create label data
+        label_data = Label(
+            uuid=uuid,
+            text=text.strip(),
             position=position,
             rotation=rotation,
-            label_type=label_type,
-            effects=effects or {},
+            size=size,
+            justify_h=justify_h,
+            justify_v=justify_v,
         )
 
-        # Add to collection using base class method
-        return super().add(label)
-
-    def get_labels_by_text(self, text: str, case_sensitive: bool = False) -> List[Label]:
-        """
-        Get all labels with specific text.
+        # Create label element wrapper
+        label_element = LabelElement(label_data, self)
 
-        Args:
-            text: Text to search for
-            case_sensitive: Whether search should be case sensitive
+        # Add to collection
+        super().add(label_element)
 
-        Returns:
-            List of matching labels
-        """
-        self._ensure_indexes_current()
+        # Add to text index
+        self._add_to_text_index(label_element)
 
-        if case_sensitive:
-            return [label for label in self._items if label.text == text]
-        else:
-            text_key = text.lower()
-            return self._text_index.get(text_key, []).copy()
+        logger.debug(f"Added label '{text}' at {position}, UUID={uuid}")
+        return label_element
 
-    def get_labels_at_position(
-        self, position: Union[Point, Tuple[float, float]], tolerance: float = 0.0
-    ) -> List[Label]:
+    # Remove operation (override to update text index)
+    def remove(self, uuid: str) -> bool:
         """
-        Get all labels at a specific position.
+        Remove label by UUID.
 
         Args:
-            position: Position to search at
-            tolerance: Position tolerance for matching
+            uuid: Label UUID to remove
 
         Returns:
-            List of labels at the position
-        """
-        self._ensure_indexes_current()
-
-        if isinstance(position, Point):
-            pos_key = (position.x, position.y)
-        else:
-            pos_key = position
-
-        if tolerance == 0.0:
-            # Exact match
-            return self._position_index.get(pos_key, []).copy()
-        else:
-            # Tolerance-based search
-            matching_labels = []
-            target_x, target_y = pos_key
-
-            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
-
-                if distance <= tolerance:
-                    matching_labels.append(label)
-
-            return matching_labels
-
-    def get_labels_by_type(self, label_type: str) -> List[Label]:
+            True if label was removed, False if not found
         """
-        Get all labels of a specific type.
+        # Get label before removing
+        label = self.get(uuid)
+        if not label:
+            return False
 
-        Args:
-            label_type: Type of labels to find
+        # Remove from text index
+        self._remove_from_text_index(label)
 
-        Returns:
-            List of labels of the specified type
-        """
-        self._ensure_indexes_current()
-        return self._type_index.get(label_type, []).copy()
+        # Remove from base collection
+        result = super().remove(uuid)
 
-    def get_net_names(self) -> List[str]:
-        """
-        Get all unique net names from labels.
+        if result:
+            logger.info(f"Removed label '{label.text}'")
 
-        Returns:
-            List of unique net names
-        """
-        return list(set(label.text for label in self._items))
+        return result
 
-    def get_labels_for_net(self, net_name: str, case_sensitive: bool = False) -> List[Label]:
+    # Text-based queries
+    def get_by_text(self, text: str) -> List[LabelElement]:
         """
-        Get all labels for a specific net.
+        Find all labels with specific text.
 
         Args:
-            net_name: Net name to search for
-            case_sensitive: Whether search should be case sensitive
+            text: Text to search for
 
         Returns:
-            List of labels for the net
+            List of labels with matching text
         """
-        return self.get_labels_by_text(net_name, case_sensitive)
+        return self._text_index.get(text, [])
 
-    def find_labels_in_region(
-        self, min_x: float, min_y: float, max_x: float, max_y: float
-    ) -> List[Label]:
+    def filter_by_text_pattern(self, pattern: str) -> List[LabelElement]:
         """
-        Find all labels within a rectangular region.
+        Find labels with text containing a pattern.
 
         Args:
-            min_x: Minimum X coordinate
-            min_y: Minimum Y coordinate
-            max_x: Maximum X coordinate
-            max_y: Maximum Y coordinate
+            pattern: Text pattern to search for (case-insensitive)
 
         Returns:
-            List of labels in the region
+            List of labels with matching text
         """
-        matching_labels = []
+        pattern_lower = pattern.lower()
+        matching = []
 
         for label in self._items:
-            if min_x <= label.position.x <= max_x and min_y <= label.position.y <= max_y:
-                matching_labels.append(label)
-
-        return matching_labels
-
-    def update_label_text(self, label_uuid: str, new_text: str) -> bool:
-        """
-        Update the text of an existing label.
-
-        Args:
-            label_uuid: UUID of label to update
-            new_text: New text content
-
-        Returns:
-            True if label was updated, False if not found
-
-        Raises:
-            ValueError: If new text is empty
-        """
-        if not new_text.strip():
-            raise ValueError("Label text cannot be empty")
+            if pattern_lower in label.text.lower():
+                matching.append(label)
 
-        label = self.get(label_uuid)
-        if not label:
-            return False
-
-        # Update text
-        label.text = new_text
-        self._mark_modified()
-        self._mark_indexes_dirty()
-
-        logger.debug(f"Updated label {label_uuid} text to '{new_text}'")
-        return True
+        return matching
 
-    def update_label_position(
-        self, label_uuid: str, new_position: Union[Point, Tuple[float, float]]
-    ) -> bool:
+    # Position-based queries
+    def get_at_position(
+        self, position: Union[Point, Tuple[float, float]], tolerance: float = 0.01
+    ) -> Optional[LabelElement]:
         """
-        Update the position of an existing label.
+        Find label at or near a specific position.
 
         Args:
-            label_uuid: UUID of label to update
-            new_position: New position
+            position: Position to search
+            tolerance: Distance tolerance for matching
 
         Returns:
-            True if label was updated, False if not found
+            Label if found, None otherwise
         """
-        label = self.get(label_uuid)
-        if not label:
-            return False
-
-        # Convert tuple to Point if needed
-        if isinstance(new_position, tuple):
-            new_position = Point(new_position[0], new_position[1])
+        if isinstance(position, tuple):
+            position = Point(position[0], position[1])
 
-        # Update position
-        label.position = new_position
-        self._mark_modified()
-        self._mark_indexes_dirty()
+        for label in self._items:
+            if label.position.distance_to(position) <= tolerance:
+                return label
 
-        logger.debug(f"Updated label {label_uuid} position to {new_position}")
-        return True
+        return None
 
-    # Bulk operations
-    def rename_net(self, old_name: str, new_name: str, case_sensitive: bool = False) -> int:
+    def get_near_point(
+        self, point: Union[Point, Tuple[float, float]], radius: float
+    ) -> List[LabelElement]:
         """
-        Rename all labels for a net.
+        Find all labels within radius of a point.
 
         Args:
-            old_name: Current net name
-            new_name: New net name
-            case_sensitive: Whether search should be case sensitive
+            point: Center point
+            radius: Search radius
 
         Returns:
-            Number of labels renamed
-
-        Raises:
-            ValueError: If new name is empty
+            List of labels within radius
         """
-        if not new_name.strip():
-            raise ValueError("New net name cannot be empty")
-
-        labels_to_rename = self.get_labels_by_text(old_name, case_sensitive)
-
-        for label in labels_to_rename:
-            label.text = new_name
+        if isinstance(point, tuple):
+            point = Point(point[0], point[1])
 
-        if labels_to_rename:
-            self._mark_modified()
-            self._mark_indexes_dirty()
+        matching = []
+        for label in self._items:
+            if label.position.distance_to(point) <= radius:
+                matching.append(label)
 
-        logger.info(f"Renamed {len(labels_to_rename)} labels from '{old_name}' to '{new_name}'")
-        return len(labels_to_rename)
+        return matching
 
-    def remove_labels_for_net(self, net_name: str, case_sensitive: bool = False) -> int:
+    # Validation
+    def validate_all(self) -> List[ValidationIssue]:
         """
-        Remove all labels for a specific net.
-
-        Args:
-            net_name: Net name to remove labels for
-            case_sensitive: Whether search should be case sensitive
+        Validate all labels in collection.
 
         Returns:
-            Number of labels removed
+            List of validation issues found
         """
-        labels_to_remove = self.get_labels_by_text(net_name, case_sensitive)
+        all_issues = []
 
-        for label in labels_to_remove:
-            self.remove(label.uuid)
+        for label in self._items:
+            issues = label.validate()
+            all_issues.extend(issues)
 
-        logger.info(f"Removed {len(labels_to_remove)} labels for net '{net_name}'")
-        return len(labels_to_remove)
+        return all_issues
 
-    # Collection statistics
-    def get_label_statistics(self) -> Dict[str, Any]:
+    # Statistics
+    def get_statistics(self) -> Dict[str, Any]:
         """
-        Get label statistics for the collection.
+        Get label collection statistics.
 
         Returns:
             Dictionary with label statistics
         """
-        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
+        if not self._items:
+            base_stats = super().get_statistics()
+            base_stats.update({
+                "total_labels": 0,
+                "unique_texts": 0,
+                "avg_size": 0,
+            })
+            return base_stats
+
+        unique_texts = len(self._text_index)
+        avg_size = sum(l.size for l in self._items) / len(self._items)
+
+        base_stats = super().get_statistics()
+        base_stats.update({
+            "total_labels": len(self._items),
+            "unique_texts": unique_texts,
+            "avg_size": avg_size,
+            "text_distribution": {text: len(labels) for text, labels in self._text_index.items()},
+        })
+
+        return base_stats
+
+    # Internal helper methods
+    def _add_to_text_index(self, label: LabelElement):
+        """Add label to text index."""
+        text = label.text
+        if text not in self._text_index:
+            self._text_index[text] = []
+        self._text_index[text].append(label)
+
+    def _remove_from_text_index(self, label: LabelElement):
+        """Remove label from text index."""
+        text = label.text
+        if text in self._text_index:
+            self._text_index[text].remove(label)
+            if not self._text_index[text]:
+                del self._text_index[text]
+
+    def _update_text_index(self, old_text: str, label: LabelElement):
+        """Update text index when label text changes."""
+        # Remove from old text
+        if old_text in self._text_index:
+            self._text_index[old_text].remove(label)
+            if not self._text_index[old_text]:
+                del self._text_index[old_text]
+
+        # Add to new text
+        new_text = label.text
+        if new_text not in self._text_index:
+            self._text_index[new_text] = []
+        self._text_index[new_text].append(label)
+
+    # 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()