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

kicad_sch_api/core/component_bounds.py

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

kicad_sch_api/core/components.py

@@ -11,6 +11,7 @@ from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple, Union
 
 from ..library.cache import SymbolDefinition, get_symbol_cache
 from ..utils.validation import SchematicValidator, ValidationError, ValidationIssue
+from .collections import BaseCollection
 from .ic_manager import ICManager
 from .types import Point, SchematicPin, SchematicSymbol
 
@@ -38,6 +39,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')."""
@@ -256,10 +262,13 @@ class Component:
         )
 
 
-class ComponentCollection:
+class ComponentCollection(BaseCollection[Component]):
     """
     Collection class for efficient component management.
 
+    Inherits from BaseCollection for standard operations and adds component-specific
+    functionality including reference, lib_id, and value-based indexing.
+
     Provides fast lookup, filtering, and bulk operations for schematic components.
     Optimized for schematics with hundreds or thousands of components.
     """
@@ -271,19 +280,19 @@ class ComponentCollection:
         Args:
             components: Initial list of component data
         """
-        self._components: List[Component] = []
+        # Initialize base collection
+        super().__init__([], collection_name="components")
+
+        # Additional component-specific indexes
         self._reference_index: Dict[str, Component] = {}
         self._lib_id_index: Dict[str, List[Component]] = {}
         self._value_index: Dict[str, List[Component]] = {}
-        self._modified = False
 
         # Add initial components
         if components:
             for comp_data in components:
                 self._add_to_indexes(Component(comp_data, self))
 
-        logger.debug(f"ComponentCollection initialized with {len(self._components)} components")
-
     def add(
         self,
         lib_id: str,
@@ -370,7 +379,7 @@ class ComponentCollection:
 
         # Add to collection
         self._add_to_indexes(component)
-        self._modified = True
+        self._mark_modified()
 
         logger.info(f"Added component: {reference} ({lib_id})")
         return component
@@ -427,7 +436,7 @@ class ComponentCollection:
             component = Component(component_data, self)
             self._add_to_indexes(component)
 
-        self._modified = True
+        self._mark_modified()
         logger.info(
             f"Added multi-unit IC: {reference_prefix} ({lib_id}) with {len(unit_components)} units"
         )
@@ -448,9 +457,11 @@ class ComponentCollection:
         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
@@ -474,7 +485,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 +523,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 +538,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 +570,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 +592,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 +621,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 +632,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 +680,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 +701,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 +725,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 +747,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

kicad_sch_api/core/factories/__init__.py

@@ -0,0 +1,5 @@
+"""Factory classes for creating schematic elements."""
+
+from .element_factory import ElementFactory
+
+__all__ = ["ElementFactory"]

kicad_sch_api/core/factories/element_factory.py

@@ -0,0 +1,276 @@
+"""
+Element Factory for creating schematic elements from dictionaries.
+
+Centralizes object creation logic that was previously duplicated in Schematic.__init__.
+"""
+
+import uuid
+from typing import Any, Dict, List
+
+from ..types import (
+    HierarchicalLabelShape,
+    Junction,
+    Label,
+    LabelType,
+    Net,
+    NoConnect,
+    Point,
+    Text,
+    Wire,
+    WireType,
+)
+
+
+def point_from_dict_or_tuple(position: Any) -> Point:
+    """Convert position data (dict or tuple) to Point object."""
+    if isinstance(position, dict):
+        return Point(position.get("x", 0), position.get("y", 0))
+    elif isinstance(position, (list, tuple)):
+        return Point(position[0], position[1])
+    elif isinstance(position, Point):
+        return position
+    else:
+        return Point(0, 0)
+
+
+class ElementFactory:
+    """Factory for creating schematic elements from dictionary data."""
+
+    @staticmethod
+    def create_wire(wire_dict: Dict[str, Any]) -> Wire:
+        """
+        Create Wire object from dictionary.
+
+        Args:
+            wire_dict: Dictionary containing wire data
+
+        Returns:
+            Wire object
+        """
+        points = []
+        for point_data in wire_dict.get("points", []):
+            if isinstance(point_data, dict):
+                points.append(Point(point_data["x"], point_data["y"]))
+            elif isinstance(point_data, (list, tuple)):
+                points.append(Point(point_data[0], point_data[1]))
+            else:
+                points.append(point_data)
+
+        return Wire(
+            uuid=wire_dict.get("uuid", str(uuid.uuid4())),
+            points=points,
+            wire_type=WireType(wire_dict.get("wire_type", "wire")),
+            stroke_width=wire_dict.get("stroke_width", 0.0),
+            stroke_type=wire_dict.get("stroke_type", "default"),
+        )
+
+    @staticmethod
+    def create_junction(junction_dict: Dict[str, Any]) -> Junction:
+        """
+        Create Junction object from dictionary.
+
+        Args:
+            junction_dict: Dictionary containing junction data
+
+        Returns:
+            Junction object
+        """
+        position = junction_dict.get("position", {"x": 0, "y": 0})
+        pos = point_from_dict_or_tuple(position)
+
+        return Junction(
+            uuid=junction_dict.get("uuid", str(uuid.uuid4())),
+            position=pos,
+            diameter=junction_dict.get("diameter", 0),
+            color=junction_dict.get("color", (0, 0, 0, 0)),
+        )
+
+    @staticmethod
+    def create_text(text_dict: Dict[str, Any]) -> Text:
+        """
+        Create Text object from dictionary.
+
+        Args:
+            text_dict: Dictionary containing text data
+
+        Returns:
+            Text object
+        """
+        position = text_dict.get("position", {"x": 0, "y": 0})
+        pos = point_from_dict_or_tuple(position)
+
+        return Text(
+            uuid=text_dict.get("uuid", str(uuid.uuid4())),
+            position=pos,
+            text=text_dict.get("text", ""),
+            rotation=text_dict.get("rotation", 0.0),
+            size=text_dict.get("size", 1.27),
+            exclude_from_sim=text_dict.get("exclude_from_sim", False),
+        )
+
+    @staticmethod
+    def create_label(label_dict: Dict[str, Any]) -> Label:
+        """
+        Create Label object from dictionary.
+
+        Args:
+            label_dict: Dictionary containing label data
+
+        Returns:
+            Label object
+        """
+        position = label_dict.get("position", {"x": 0, "y": 0})
+        pos = point_from_dict_or_tuple(position)
+
+        return Label(
+            uuid=label_dict.get("uuid", str(uuid.uuid4())),
+            position=pos,
+            text=label_dict.get("text", ""),
+            label_type=LabelType(label_dict.get("label_type", "local")),
+            rotation=label_dict.get("rotation", 0.0),
+            size=label_dict.get("size", 1.27),
+            shape=(
+                HierarchicalLabelShape(label_dict.get("shape"))
+                if label_dict.get("shape")
+                else None
+            ),
+        )
+
+    @staticmethod
+    def create_no_connect(no_connect_dict: Dict[str, Any]) -> NoConnect:
+        """
+        Create NoConnect object from dictionary.
+
+        Args:
+            no_connect_dict: Dictionary containing no-connect data
+
+        Returns:
+            NoConnect object
+        """
+        position = no_connect_dict.get("position", {"x": 0, "y": 0})
+        pos = point_from_dict_or_tuple(position)
+
+        return NoConnect(
+            uuid=no_connect_dict.get("uuid", str(uuid.uuid4())),
+            position=pos,
+        )
+
+    @staticmethod
+    def create_net(net_dict: Dict[str, Any]) -> Net:
+        """
+        Create Net object from dictionary.
+
+        Args:
+            net_dict: Dictionary containing net data
+
+        Returns:
+            Net object
+        """
+        return Net(
+            name=net_dict.get("name", ""),
+            components=net_dict.get("components", []),
+            wires=net_dict.get("wires", []),
+            labels=net_dict.get("labels", []),
+        )
+
+    @staticmethod
+    def create_wires_from_list(wire_data: List[Any]) -> List[Wire]:
+        """
+        Create list of Wire objects from list of dictionaries.
+
+        Args:
+            wire_data: List of wire dictionaries
+
+        Returns:
+            List of Wire objects
+        """
+        wires = []
+        for wire_dict in wire_data:
+            if isinstance(wire_dict, dict):
+                wires.append(ElementFactory.create_wire(wire_dict))
+        return wires
+
+    @staticmethod
+    def create_junctions_from_list(junction_data: List[Any]) -> List[Junction]:
+        """
+        Create list of Junction objects from list of dictionaries.
+
+        Args:
+            junction_data: List of junction dictionaries
+
+        Returns:
+            List of Junction objects
+        """
+        junctions = []
+        for junction_dict in junction_data:
+            if isinstance(junction_dict, dict):
+                junctions.append(ElementFactory.create_junction(junction_dict))
+        return junctions
+
+    @staticmethod
+    def create_texts_from_list(text_data: List[Any]) -> List[Text]:
+        """
+        Create list of Text objects from list of dictionaries.
+
+        Args:
+            text_data: List of text dictionaries
+
+        Returns:
+            List of Text objects
+        """
+        texts = []
+        for text_dict in text_data:
+            if isinstance(text_dict, dict):
+                texts.append(ElementFactory.create_text(text_dict))
+        return texts
+
+    @staticmethod
+    def create_labels_from_list(label_data: List[Any]) -> List[Label]:
+        """
+        Create list of Label objects from list of dictionaries.
+
+        Args:
+            label_data: List of label dictionaries
+
+        Returns:
+            List of Label objects
+        """
+        labels = []
+        for label_dict in label_data:
+            if isinstance(label_dict, dict):
+                labels.append(ElementFactory.create_label(label_dict))
+        return labels
+
+    @staticmethod
+    def create_no_connects_from_list(no_connect_data: List[Any]) -> List[NoConnect]:
+        """
+        Create list of NoConnect objects from list of dictionaries.
+
+        Args:
+            no_connect_data: List of no-connect dictionaries
+
+        Returns:
+            List of NoConnect objects
+        """
+        no_connects = []
+        for no_connect_dict in no_connect_data:
+            if isinstance(no_connect_dict, dict):
+                no_connects.append(ElementFactory.create_no_connect(no_connect_dict))
+        return no_connects
+
+    @staticmethod
+    def create_nets_from_list(net_data: List[Any]) -> List[Net]:
+        """
+        Create list of Net objects from list of dictionaries.
+
+        Args:
+            net_data: List of net dictionaries
+
+        Returns:
+            List of Net objects
+        """
+        nets = []
+        for net_dict in net_data:
+            if isinstance(net_dict, dict):
+                nets.append(ElementFactory.create_net(net_dict))
+        return nets

kicad_sch_api/core/formatter.py

@@ -55,7 +55,9 @@ class ExactFormatter:
         self.rules["generator"] = FormatRule(inline=True, quote_indices={1})
         self.rules["generator_version"] = FormatRule(inline=True, quote_indices={1})
         self.rules["uuid"] = FormatRule(inline=True, quote_indices={1})
-        self.rules["paper"] = FormatRule(inline=True, quote_indices={1})  # Paper size should be quoted per KiCad format
+        self.rules["paper"] = FormatRule(
+            inline=True, quote_indices={1}
+        )  # Paper size should be quoted per KiCad format
 
         # Title block
         self.rules["title_block"] = FormatRule(inline=False)