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

kicad_sch_api/core/texts.py

@@ -0,0 +1,316 @@
+"""
+Text element management for KiCAD schematics.
+
+This module provides collection classes for managing text elements,
+featuring fast lookup, bulk operations, and validation.
+"""
+
+import logging
+import uuid
+from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple, Union
+
+from ..utils.validation import SchematicValidator, ValidationError, ValidationIssue
+from .collections import BaseCollection
+from .types import Point, Text
+
+logger = logging.getLogger(__name__)
+
+
+class TextElement:
+    """
+    Enhanced wrapper for schematic text elements with modern API.
+
+    Provides intuitive access to text properties and operations
+    while maintaining exact format preservation.
+    """
+
+    def __init__(self, text_data: Text, parent_collection: "TextCollection"):
+        """
+        Initialize text element wrapper.
+
+        Args:
+            text_data: Underlying text data
+            parent_collection: Parent collection for updates
+        """
+        self._data = text_data
+        self._collection = parent_collection
+        self._validator = SchematicValidator()
+
+    # Core properties with validation
+    @property
+    def uuid(self) -> str:
+        """Text element UUID."""
+        return self._data.uuid
+
+    @property
+    def text(self) -> str:
+        """Text content."""
+        return self._data.text
+
+    @text.setter
+    def text(self, value: str):
+        """Set text content with validation."""
+        if not isinstance(value, str):
+            raise ValidationError(f"Text content must be string, got {type(value)}")
+        self._data.text = value
+        self._collection._mark_modified()
+
+    @property
+    def position(self) -> Point:
+        """Text position."""
+        return self._data.position
+
+    @position.setter
+    def position(self, value: Union[Point, Tuple[float, float]]):
+        """Set text 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:
+        """Text rotation in degrees."""
+        return self._data.rotation
+
+    @rotation.setter
+    def rotation(self, value: float):
+        """Set text rotation."""
+        self._data.rotation = float(value)
+        self._collection._mark_modified()
+
+    @property
+    def size(self) -> float:
+        """Text size."""
+        return self._data.size
+
+    @size.setter
+    def size(self, value: float):
+        """Set text size with validation."""
+        if value <= 0:
+            raise ValidationError(f"Text size must be positive, got {value}")
+        self._data.size = float(value)
+        self._collection._mark_modified()
+
+    @property
+    def exclude_from_sim(self) -> bool:
+        """Whether text is excluded from simulation."""
+        return self._data.exclude_from_sim
+
+    @exclude_from_sim.setter
+    def exclude_from_sim(self, value: bool):
+        """Set exclude from simulation flag."""
+        self._data.exclude_from_sim = bool(value)
+        self._collection._mark_modified()
+
+    def validate(self) -> List[ValidationIssue]:
+        """Validate this text element."""
+        return self._validator.validate_text(self._data.__dict__)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert text element to dictionary representation."""
+        return {
+            "uuid": self.uuid,
+            "text": self.text,
+            "position": {"x": self.position.x, "y": self.position.y},
+            "rotation": self.rotation,
+            "size": self.size,
+            "exclude_from_sim": self.exclude_from_sim,
+        }
+
+    def __str__(self) -> str:
+        """String representation."""
+        return f"<Text '{self.text}' @ {self.position}>"
+
+
+class TextCollection(BaseCollection[TextElement]):
+    """
+    Collection class for efficient text element management.
+
+    Inherits from BaseCollection for standard operations and adds text-specific
+    functionality including content-based indexing.
+
+    Provides fast lookup, filtering, and bulk operations for schematic text elements.
+    """
+
+    def __init__(self, texts: List[Text] = None):
+        """
+        Initialize text collection.
+
+        Args:
+            texts: Initial list of text data
+        """
+        # Initialize base collection with empty list (we'll add elements below)
+        super().__init__([], collection_name="texts")
+
+        # Additional text-specific index
+        self._content_index: Dict[str, List[TextElement]] = {}
+
+        # Add initial texts
+        if texts:
+            for text_data in texts:
+                self._add_to_indexes(TextElement(text_data, self))
+
+    def add(
+        self,
+        text: str,
+        position: Union[Point, Tuple[float, float]],
+        rotation: float = 0.0,
+        size: float = 1.27,
+        exclude_from_sim: bool = False,
+        text_uuid: Optional[str] = None,
+    ) -> TextElement:
+        """
+        Add a new text element to the schematic.
+
+        Args:
+            text: Text content
+            position: Text position
+            rotation: Text rotation in degrees
+            size: Text size
+            exclude_from_sim: Whether to exclude from simulation
+            text_uuid: Specific UUID for text (auto-generated if None)
+
+        Returns:
+            Newly created TextElement
+
+        Raises:
+            ValidationError: If text data is invalid
+        """
+        # Validate inputs
+        if not isinstance(text, str) or not text.strip():
+            raise ValidationError("Text content cannot be empty")
+
+        if isinstance(position, tuple):
+            position = Point(position[0], position[1])
+        elif not isinstance(position, Point):
+            raise ValidationError(f"Position must be Point or tuple, got {type(position)}")
+
+        if size <= 0:
+            raise ValidationError(f"Text size must be positive, got {size}")
+
+        # Generate UUID if not provided
+        if not text_uuid:
+            text_uuid = str(uuid.uuid4())
+
+        # Check for duplicate UUID
+        if text_uuid in self._uuid_index:
+            raise ValidationError(f"Text UUID {text_uuid} already exists")
+
+        # Create text data
+        text_data = Text(
+            uuid=text_uuid,
+            position=position,
+            text=text,
+            rotation=rotation,
+            size=size,
+            exclude_from_sim=exclude_from_sim,
+        )
+
+        # Create wrapper and add to collection
+        text_element = TextElement(text_data, self)
+        self._add_to_indexes(text_element)
+
+        logger.debug(f"Added text: {text_element}")
+        return text_element
+
+    def remove(self, text_uuid: str) -> bool:
+        """
+        Remove text by UUID.
+
+        Args:
+            text_uuid: UUID of text to remove
+
+        Returns:
+            True if text was removed, False if not found
+        """
+        text_element = self.get(text_uuid)
+        if not text_element:
+            return False
+
+        # Remove from content index
+        content = text_element.text
+        if content in self._content_index:
+            self._content_index[content].remove(text_element)
+            if not self._content_index[content]:
+                del self._content_index[content]
+
+        # Remove using base class method
+        super().remove(text_uuid)
+
+        logger.debug(f"Removed text: {text_element}")
+        return True
+
+    def find_by_content(self, content: str, exact: bool = True) -> List[TextElement]:
+        """
+        Find texts by content.
+
+        Args:
+            content: Content to search for
+            exact: If True, exact match; if False, substring match
+
+        Returns:
+            List of matching text elements
+        """
+        if exact:
+            return self._content_index.get(content, []).copy()
+        else:
+            matches = []
+            for text_element in self._items:
+                if content.lower() in text_element.text.lower():
+                    matches.append(text_element)
+            return matches
+
+    def filter(self, predicate: Callable[[TextElement], bool]) -> List[TextElement]:
+        """
+        Filter texts by predicate function (delegates to base class find).
+
+        Args:
+            predicate: Function that returns True for texts to include
+
+        Returns:
+            List of texts matching predicate
+        """
+        return self.find(predicate)
+
+    def bulk_update(self, criteria: Callable[[TextElement], bool], updates: Dict[str, Any]):
+        """
+        Update multiple texts matching criteria.
+
+        Args:
+            criteria: Function to select texts to update
+            updates: Dictionary of property updates
+        """
+        updated_count = 0
+        for text_element in self._items:
+            if criteria(text_element):
+                for prop, value in updates.items():
+                    if hasattr(text_element, prop):
+                        setattr(text_element, prop, value)
+                        updated_count += 1
+
+        if updated_count > 0:
+            self._mark_modified()
+            logger.debug(f"Bulk updated {updated_count} text properties")
+
+    def clear(self):
+        """Remove all texts from collection."""
+        self._content_index.clear()
+        super().clear()
+
+    def _add_to_indexes(self, text_element: TextElement):
+        """Add text to internal indexes (base + content index)."""
+        self._add_item(text_element)
+
+        # Add to content index
+        content = text_element.text
+        if content not in self._content_index:
+            self._content_index[content] = []
+        self._content_index[content].append(text_element)
+
+    # Collection interface methods - __len__, __iter__, __getitem__ inherited from BaseCollection
+    def __bool__(self) -> bool:
+        """Return True if collection has texts."""
+        return len(self._items) > 0

kicad_sch_api/core/types.py

@@ -18,14 +18,14 @@ class Point:
     x: float
     y: float
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         # Ensure coordinates are float
         object.__setattr__(self, "x", float(self.x))
         object.__setattr__(self, "y", float(self.y))
 
     def distance_to(self, other: "Point") -> float:
         """Calculate distance to another point."""
-        return ((self.x - other.x) ** 2 + (self.y - other.y) ** 2) ** 0.5
+        return float(((self.x - other.x) ** 2 + (self.y - other.y) ** 2) ** 0.5)
 
     def offset(self, dx: float, dy: float) -> "Point":
         """Create new point offset by dx, dy."""
@@ -35,6 +35,43 @@ class Point:
         return f"({self.x:.3f}, {self.y:.3f})"
 
 
+def point_from_dict_or_tuple(
+    position: Union[Point, Dict[str, float], Tuple[float, float], List[float], Any]
+) -> Point:
+    """
+    Convert various position formats to a Point object.
+
+    Supports multiple input formats for maximum flexibility:
+    - Point: Returns as-is
+    - Dict with 'x' and 'y' keys: Extracts and creates Point
+    - Tuple/List with 2 elements: Creates Point from coordinates
+    - Other: Returns as-is (assumes it's already a Point-like object)
+
+    Args:
+        position: Position in any supported format
+
+    Returns:
+        Point object
+
+    Example:
+        >>> point_from_dict_or_tuple({"x": 10, "y": 20})
+        Point(x=10.0, y=20.0)
+        >>> point_from_dict_or_tuple((10, 20))
+        Point(x=10.0, y=20.0)
+        >>> point_from_dict_or_tuple(Point(10, 20))
+        Point(x=10.0, y=20.0)
+    """
+    if isinstance(position, Point):
+        return position
+    elif isinstance(position, dict):
+        return Point(position.get("x", 0), position.get("y", 0))
+    elif isinstance(position, (list, tuple)) and len(position) >= 2:
+        return Point(position[0], position[1])
+    else:
+        # Assume it's already a Point-like object or will be handled by caller
+        return position
+
+
 @dataclass(frozen=True)
 class Rectangle:
     """Rectangle defined by two corner points."""
@@ -110,7 +147,7 @@ class SchematicPin:
     length: float = 2.54  # Standard pin length in mm
     rotation: float = 0.0  # Rotation in degrees
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         # Ensure types are correct
         self.pin_type = PinType(self.pin_type) if isinstance(self.pin_type, str) else self.pin_type
         self.pin_shape = (
@@ -118,6 +155,54 @@ class SchematicPin:
         )
 
 
+@dataclass
+class PinInfo:
+    """
+    Complete pin information for a component pin.
+
+    This dataclass provides comprehensive pin metadata including position,
+    electrical properties, and graphical representation. Positions are in
+    schematic coordinates (absolute positions accounting for component
+    rotation and mirroring).
+    """
+
+    number: str  # Pin number (e.g., "1", "2", "A1")
+    name: str  # Pin name (e.g., "VCC", "GND", "CLK")
+    position: Point  # Absolute position in schematic coordinates (mm)
+    electrical_type: PinType = PinType.PASSIVE  # Electrical type (input, output, passive, etc.)
+    shape: PinShape = PinShape.LINE  # Graphical shape (line, inverted, clock, etc.)
+    length: float = 2.54  # Pin length in mm
+    orientation: float = 0.0  # Pin orientation in degrees (0, 90, 180, 270)
+    uuid: str = ""  # Unique identifier for this pin instance
+
+    def __post_init__(self) -> None:
+        """Validate and normalize pin information."""
+        # Ensure types are correct
+        self.electrical_type = (
+            PinType(self.electrical_type)
+            if isinstance(self.electrical_type, str)
+            else self.electrical_type
+        )
+        self.shape = PinShape(self.shape) if isinstance(self.shape, str) else self.shape
+
+        # Generate UUID if not provided
+        if not self.uuid:
+            self.uuid = str(uuid4())
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert pin info to dictionary representation."""
+        return {
+            "number": self.number,
+            "name": self.name,
+            "position": {"x": self.position.x, "y": self.position.y},
+            "electrical_type": self.electrical_type.value,
+            "shape": self.shape.value,
+            "length": self.length,
+            "orientation": self.orientation,
+            "uuid": self.uuid,
+        }
+
+
 @dataclass
 class SchematicSymbol:
     """Component symbol in a schematic."""
@@ -134,8 +219,9 @@ class SchematicSymbol:
     in_bom: bool = True
     on_board: bool = True
     unit: int = 1
+    instances: List["SymbolInstance"] = field(default_factory=list)  # FIX: Add instances field for hierarchical support
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         # Generate UUID if not provided
         if not self.uuid:
             self.uuid = str(uuid4())
@@ -158,12 +244,37 @@ class SchematicSymbol:
         return None
 
     def get_pin_position(self, pin_number: str) -> Optional[Point]:
-        """Get absolute position of a pin."""
+        """Get absolute position of a pin with rotation transformation.
+
+        Args:
+            pin_number: Pin number to get position for
+
+        Returns:
+            Absolute position of the pin in schematic coordinates, or None if pin not found
+
+        Note:
+            Applies standard 2D rotation matrix to transform pin position from
+            symbol's local coordinate system to schematic's global coordinate system.
+        """
+        import math
+
         pin = self.get_pin(pin_number)
         if not pin:
             return None
-        # TODO: Apply rotation and symbol position transformation
-        return Point(self.position.x + pin.position.x, self.position.y + pin.position.y)
+
+        # Apply rotation transformation using standard 2D rotation matrix
+        # [x'] = [cos(θ)  -sin(θ)] [x]
+        # [y']   [sin(θ)   cos(θ)] [y]
+        angle_rad = math.radians(self.rotation)
+        cos_a = math.cos(angle_rad)
+        sin_a = math.sin(angle_rad)
+
+        # Rotate pin position from symbol's local coordinates
+        rotated_x = pin.position.x * cos_a - pin.position.y * sin_a
+        rotated_y = pin.position.x * sin_a + pin.position.y * cos_a
+
+        # Add to component position to get absolute position
+        return Point(self.position.x + rotated_x, self.position.y + rotated_y)
 
 
 class WireType(Enum):
@@ -183,7 +294,7 @@ class Wire:
     stroke_width: float = 0.0
     stroke_type: str = "default"
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not self.uuid:
             self.uuid = str(uuid4())
 
@@ -196,7 +307,7 @@ class Wire:
             raise ValueError("Wire must have at least 2 points")
 
     @classmethod
-    def from_start_end(cls, uuid: str, start: Point, end: Point, **kwargs) -> "Wire":
+    def from_start_end(cls, uuid: str, start: Point, end: Point, **kwargs: Any) -> "Wire":
         """Create wire from start and end points (convenience method)."""
         return cls(uuid=uuid, points=[start, end], **kwargs)
 
@@ -244,7 +355,7 @@ class Junction:
     diameter: float = 0  # KiCAD default diameter
     color: Tuple[int, int, int, int] = (0, 0, 0, 0)  # RGBA color
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not self.uuid:
             self.uuid = str(uuid4())
 
@@ -279,8 +390,10 @@ class Label:
     rotation: float = 0.0
     size: float = 1.27
     shape: Optional[HierarchicalLabelShape] = None  # Only for hierarchical labels
+    justify_h: str = "left"  # Horizontal justification: "left", "right", "center"
+    justify_v: str = "bottom"  # Vertical justification: "top", "bottom", "center"
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not self.uuid:
             self.uuid = str(uuid4())
 
@@ -305,7 +418,7 @@ class Text:
     size: float = 1.27
     exclude_from_sim: bool = False
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not self.uuid:
             self.uuid = str(uuid4())
 
@@ -333,7 +446,7 @@ class TextBox:
     justify_vertical: str = "top"
     exclude_from_sim: bool = False
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not self.uuid:
             self.uuid = str(uuid4())
 
@@ -349,7 +462,7 @@ class SchematicRectangle:
     stroke_type: str = "default"
     fill_type: str = "none"
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not self.uuid:
             self.uuid = str(uuid4())
 
@@ -366,10 +479,33 @@ class SchematicRectangle:
     @property
     def center(self) -> Point:
         """Rectangle center point."""
-        return Point(
-            (self.start.x + self.end.x) / 2,
-            (self.start.y + self.end.y) / 2
-        )
+        return Point((self.start.x + self.end.x) / 2, (self.start.y + self.end.y) / 2)
+
+
+@dataclass
+class Image:
+    """Image element in schematic."""
+
+    uuid: str
+    position: Point
+    data: str  # Base64-encoded image data
+    scale: float = 1.0
+
+    def __post_init__(self) -> None:
+        if not self.uuid:
+            self.uuid = str(uuid4())
+
+
+@dataclass
+class NoConnect:
+    """No-connect symbol in schematic."""
+
+    uuid: str
+    position: Point
+
+    def __post_init__(self) -> None:
+        if not self.uuid:
+            self.uuid = str(uuid4())
 
 
 @dataclass
@@ -381,13 +517,13 @@ class Net:
     wires: List[str] = field(default_factory=list)  # Wire UUIDs
     labels: List[str] = field(default_factory=list)  # Label UUIDs
 
-    def add_connection(self, reference: str, pin: str):
+    def add_connection(self, reference: str, pin: str) -> None:
         """Add component pin to net."""
         connection = (reference, pin)
         if connection not in self.components:
             self.components.append(connection)
 
-    def remove_connection(self, reference: str, pin: str):
+    def remove_connection(self, reference: str, pin: str) -> None:
         """Remove component pin from net."""
         connection = (reference, pin)
         if connection in self.components:
@@ -413,7 +549,7 @@ class Sheet:
     stroke_type: str = "solid"
     fill_color: Tuple[float, float, float, float] = (0, 0, 0, 0.0)
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not self.uuid:
             self.uuid = str(uuid4())
 
@@ -428,7 +564,7 @@ class SheetPin:
     pin_type: PinType = PinType.BIDIRECTIONAL
     size: float = 1.27
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not self.uuid:
             self.uuid = str(uuid4())
 
@@ -471,7 +607,7 @@ class Schematic:
     rectangles: List[SchematicRectangle] = field(default_factory=list)
     lib_symbols: Dict[str, Any] = field(default_factory=dict)
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not self.uuid:
             self.uuid = str(uuid4())