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

kicad_sch_api/core/components.py

@@ -11,6 +11,8 @@ 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 .exceptions import LibraryError
 from .ic_manager import ICManager
 from .types import Point, SchematicPin, SchematicSymbol
 
@@ -38,6 +40,11 @@ class Component:
         self._validator = SchematicValidator()
 
     # Core properties with validation
+    @property
+    def uuid(self) -> str:
+        """Component UUID."""
+        return self._data.uuid
+
     @property
     def reference(self) -> str:
         """Component reference (e.g., 'R1')."""
@@ -100,8 +107,29 @@ class Component:
 
     @rotation.setter
     def rotation(self, value: float):
-        """Set component rotation."""
-        self._data.rotation = float(value) % 360
+        """Set component rotation (must be 0, 90, 180, or 270 degrees).
+
+        KiCad only supports these four rotation angles for components.
+
+        Args:
+            value: Rotation angle in degrees (0, 90, 180, or 270)
+
+        Raises:
+            ValueError: If rotation is not 0, 90, 180, or 270
+        """
+        # Normalize rotation to 0-360 range
+        normalized = float(value) % 360
+
+        # KiCad only accepts 0, 90, 180, or 270 degrees
+        VALID_ROTATIONS = {0, 90, 180, 270}
+        if normalized not in VALID_ROTATIONS:
+            raise ValueError(
+                f"Component rotation must be 0, 90, 180, or 270 degrees. "
+                f"Got {value}° (normalized to {normalized}°). "
+                f"KiCad does not support arbitrary rotation angles."
+            )
+
+        self._data.rotation = normalized
         self._collection._mark_modified()
 
     @property
@@ -256,34 +284,41 @@ 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.
     """
 
-    def __init__(self, components: List[SchematicSymbol] = None):
+    def __init__(self, components: List[SchematicSymbol] = None, parent_schematic=None):
         """
         Initialize component collection.
 
         Args:
             components: Initial list of component data
+            parent_schematic: Reference to parent Schematic object (for hierarchy context)
         """
-        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
+
+        # Store reference to parent schematic for hierarchy context
+        self._parent_schematic = parent_schematic
 
         # 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,
@@ -292,6 +327,7 @@ class ComponentCollection:
         position: Optional[Union[Point, Tuple[float, float]]] = None,
         footprint: Optional[str] = None,
         unit: int = 1,
+        rotation: float = 0.0,
         component_uuid: Optional[str] = None,
         **properties,
     ) -> Component:
@@ -305,6 +341,7 @@ class ComponentCollection:
             position: Component position (auto-placed if None)
             footprint: Component footprint
             unit: Unit number for multi-unit components (1-based)
+            rotation: Component rotation in degrees (0, 90, 180, 270)
             component_uuid: Specific UUID for component (auto-generated if None)
             **properties: Additional component properties
 
@@ -313,6 +350,7 @@ class ComponentCollection:
 
         Raises:
             ValidationError: If component data is invalid
+            LibraryError: If the KiCAD symbol library is not found
         """
         # Validate lib_id
         validator = SchematicValidator()
@@ -347,6 +385,28 @@ class ComponentCollection:
             f"Component {reference} position snapped to grid: ({position.x:.3f}, {position.y:.3f})"
         )
 
+        # Normalize and validate rotation
+        rotation = rotation % 360
+
+        # KiCad only accepts 0, 90, 180, or 270 degrees
+        VALID_ROTATIONS = {0, 90, 180, 270}
+        if rotation not in VALID_ROTATIONS:
+            raise ValidationError(
+                f"Component rotation must be 0, 90, 180, or 270 degrees. "
+                f"Got {rotation}°. KiCad does not support arbitrary rotation angles."
+            )
+
+        # Check if parent schematic has hierarchy context set
+        # If so, add hierarchy_path to properties for proper KiCad instance paths
+        if self._parent_schematic and hasattr(self._parent_schematic, '_hierarchy_path'):
+            if self._parent_schematic._hierarchy_path:
+                properties = dict(properties)  # Make a copy to avoid modifying caller's dict
+                properties['hierarchy_path'] = self._parent_schematic._hierarchy_path
+                logger.debug(
+                    f"Setting hierarchy_path for component {reference}: "
+                    f"{self._parent_schematic._hierarchy_path}"
+                )
+
         # Create component data
         component_data = SchematicSymbol(
             uuid=component_uuid if component_uuid else str(uuid.uuid4()),
@@ -356,21 +416,31 @@ class ComponentCollection:
             value=value,
             footprint=footprint,
             unit=unit,
+            rotation=rotation,
             properties=properties,
         )
 
         # Get symbol definition and update pins
         symbol_cache = get_symbol_cache()
         symbol_def = symbol_cache.get_symbol(lib_id)
-        if symbol_def:
-            component_data.pins = symbol_def.pins.copy()
+        if not symbol_def:
+            # Provide helpful error message with library name
+            library_name = lib_id.split(":")[0] if ":" in lib_id else "unknown"
+            raise LibraryError(
+                f"Symbol '{lib_id}' not found in KiCAD libraries. "
+                f"Please verify the library name '{library_name}' and symbol name are correct. "
+                f"Common libraries include: Device, Connector_Generic, Regulator_Linear, RF_Module",
+                field="lib_id",
+                value=lib_id
+            )
+        component_data.pins = symbol_def.pins.copy()
 
         # Create component wrapper
         component = Component(component_data, self)
 
         # Add to collection
         self._add_to_indexes(component)
-        self._modified = True
+        self._mark_modified()
 
         logger.info(f"Added component: {reference} ({lib_id})")
         return component
@@ -427,7 +497,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"
         )
@@ -439,22 +509,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)
@@ -474,7 +624,7 @@ class ComponentCollection:
         Returns:
             List of matching components
         """
-        results = list(self._components)
+        results = list(self._items)
 
         # Apply filters
         if "lib_id" in criteria:
@@ -512,7 +662,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]:
@@ -527,7 +677,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
@@ -559,21 +709,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."""
@@ -581,12 +731,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()
@@ -610,7 +760,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
@@ -621,36 +771,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."""
@@ -658,8 +819,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
@@ -676,8 +840,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
@@ -700,10 +864,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."""
@@ -725,7 +886,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)

kicad_sch_api/core/config.py

@@ -6,8 +6,8 @@ This module centralizes all magic numbers and configuration values
 to make them easily configurable and maintainable.
 """
 
-from dataclasses import dataclass
-from typing import Any, Dict, Tuple
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Tuple
 
 
 @dataclass
@@ -57,20 +57,102 @@ class DefaultValues:
 
     project_name: str = "untitled"
     stroke_width: float = 0.0
+    stroke_type: str = "default"
+    fill_type: str = "none"
     font_size: float = 1.27
     pin_name_size: float = 1.27
     pin_number_size: float = 1.27
 
 
+@dataclass
+class FileFormatConstants:
+    """KiCAD file format identifiers and version strings."""
+
+    file_type: str = "kicad_sch"
+    generator_default: str = "eeschema"
+    version_default: str = "20250114"
+    generator_version_default: str = "9.0"
+
+
+@dataclass
+class PaperSizeConstants:
+    """Standard paper size definitions."""
+
+    default: str = "A4"
+    valid_sizes: List[str] = field(
+        default_factory=lambda: ["A4", "A3", "A2", "A1", "A0", "Letter", "Legal", "Tabloid"]
+    )
+
+
+@dataclass
+class FieldNames:
+    """Common S-expression field names to avoid typos."""
+
+    # File structure
+    version: str = "version"
+    generator: str = "generator"
+    generator_version: str = "generator_version"
+    uuid: str = "uuid"
+    paper: str = "paper"
+
+    # Positioning
+    at: str = "at"
+    xy: str = "xy"
+    pts: str = "pts"
+    start: str = "start"
+    end: str = "end"
+    mid: str = "mid"
+    center: str = "center"
+    radius: str = "radius"
+
+    # Styling
+    stroke: str = "stroke"
+    fill: str = "fill"
+    width: str = "width"
+    type: str = "type"
+    color: str = "color"
+
+    # Text/Font
+    font: str = "font"
+    size: str = "size"
+    effects: str = "effects"
+
+    # Components
+    pin: str = "pin"
+    property: str = "property"
+    symbol: str = "symbol"
+    lib_id: str = "lib_id"
+
+    # Graphics
+    polyline: str = "polyline"
+    arc: str = "arc"
+    circle: str = "circle"
+    rectangle: str = "rectangle"
+    bezier: str = "bezier"
+
+    # Connection elements
+    wire: str = "wire"
+    junction: str = "junction"
+    no_connect: str = "no_connect"
+    label: str = "label"
+
+    # Hierarchical
+    sheet: str = "sheet"
+    sheet_instances: str = "sheet_instances"
+
+
 class KiCADConfig:
     """Central configuration class for KiCAD schematic API."""
 
-    def __init__(self):
+    def __init__(self) -> None:
         self.properties = PropertyOffsets()
         self.grid = GridSettings()
         self.sheet = SheetSettings()
         self.tolerance = ToleranceSettings()
         self.defaults = DefaultValues()
+        self.file_format = FileFormatConstants()
+        self.paper = PaperSizeConstants()
+        self.fields = FieldNames()
 
         # Names that should not generate title_block (for backward compatibility)
         # Include test schematic names to maintain reference compatibility
@@ -92,35 +174,48 @@ class KiCADConfig:
         return name.lower() not in self.no_title_block_names
 
     def get_property_position(
-        self, property_name: str, component_pos: Tuple[float, float], offset_index: int = 0
+        self, property_name: str, component_pos: Tuple[float, float], offset_index: int = 0, component_rotation: float = 0
     ) -> Tuple[float, float, float]:
         """
-        Calculate property position relative to component.
+        Calculate property position relative to component, accounting for component rotation.
+
+        Args:
+            property_name: Name of the property (Reference, Value, etc.)
+            component_pos: (x, y) position of component
+            offset_index: Stacking offset for multiple properties
+            component_rotation: Rotation of the component in degrees (0, 90, 180, 270)
 
         Returns:
             Tuple of (x, y, rotation) for the property
         """
+        import math
+
         x, y = component_pos
 
+        # Get base offsets (for 0° rotation)
         if property_name == "Reference":
-            return (x + self.properties.reference_x, y + self.properties.reference_y, 0)
+            dx, dy = self.properties.reference_x, self.properties.reference_y
         elif property_name == "Value":
-            return (x + self.properties.value_x, y + self.properties.value_y, 0)
+            dx, dy = self.properties.value_x, self.properties.value_y
         elif property_name == "Footprint":
             # Footprint positioned to left of component, rotated 90 degrees
-            return (x - 1.778, y, self.properties.footprint_rotation)  # Exact match for reference
+            return (x - 1.778, y, self.properties.footprint_rotation)
         elif property_name in ["Datasheet", "Description"]:
             # Hidden properties at component center
             return (x, y, 0)
         else:
             # Other properties stacked vertically below
-            return (
-                x + self.properties.reference_x,
-                y
-                + self.properties.value_y
-                + (self.properties.hidden_property_offset * offset_index),
-                0,
-            )
+            dx = self.properties.reference_x
+            dy = self.properties.value_y + (self.properties.hidden_property_offset * offset_index)
+
+        # Apply rotation transform to offsets
+        # Text stays at 0° rotation (readable), but position rotates around component
+        # KiCad uses clockwise rotation, so negate the angle
+        rotation_rad = math.radians(-component_rotation)
+        dx_rotated = dx * math.cos(rotation_rad) - dy * math.sin(rotation_rad)
+        dy_rotated = dx * math.sin(rotation_rad) + dy * math.cos(rotation_rad)
+
+        return (x + dx_rotated, y + dy_rotated, 0)
 
 
 # Global configuration instance