kicad-sch-api 0.4.0__py3-none-any.whl → 0.4.2__py3-none-any.whl

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

@@ -125,6 +125,10 @@ class ExactFormatter:
         self.rules["global_label"] = FormatRule(inline=False, quote_indices={1})
         self.rules["hierarchical_label"] = FormatRule(inline=False, quote_indices={1})
 
+        # Text elements
+        self.rules["text"] = FormatRule(inline=False, quote_indices={1})
+        self.rules["text_box"] = FormatRule(inline=False, quote_indices={1})
+
         # Effects and text formatting
         self.rules["effects"] = FormatRule(inline=False)
         self.rules["font"] = FormatRule(inline=False)
@@ -279,6 +283,8 @@ class ExactFormatter:
             "junction",
             "label",
             "hierarchical_label",
+            "text",
+            "text_box",
             "polyline",
             "rectangle",
         ):
@@ -384,7 +390,8 @@ class ExactFormatter:
                 result += f"\n{next_indent}{self._format_element(element, indent_level + 1)}"
             else:
                 if i in rule.quote_indices and isinstance(element, str):
-                    result += f' "{element}"'
+                    escaped_element = self._escape_string(element)
+                    result += f' "{escaped_element}"'
                 else:
                     result += f" {self._format_element(element, 0)}"
 
@@ -396,7 +403,8 @@ class ExactFormatter:
         indent = "\t" * indent_level
         next_indent = "\t" * (indent_level + 1)
 
-        result = f"({lst[0]}"
+        tag = str(lst[0])
+        result = f"({tag}"
 
         for i, element in enumerate(lst[1:], 1):
             if isinstance(element, list):
@@ -425,9 +433,18 @@ class ExactFormatter:
         return True
 
     def _escape_string(self, text: str) -> str:
-        """Escape quotes in string for S-expression formatting."""
-        # Replace double quotes with escaped quotes
-        return text.replace('"', '\\"')
+        """Escape special characters in string for S-expression formatting."""
+        # Escape backslashes first (must be done before other replacements)
+        text = text.replace('\\', '\\\\')
+        # Escape double quotes
+        text = text.replace('"', '\\"')
+        # Escape newlines (convert actual newlines to escaped representation)
+        text = text.replace('\n', '\\n')
+        # Escape carriage returns
+        text = text.replace('\r', '\\r')
+        # Escape tabs
+        text = text.replace('\t', '\\t')
+        return text
 
     def _needs_quoting(self, text: str) -> bool:
         """Check if string needs to be quoted."""

kicad_sch_api/core/junctions.py

@@ -9,55 +9,34 @@ import logging
 import uuid as uuid_module
 from typing import Any, Dict, List, Optional, Tuple, Union
 
+from .collections import BaseCollection
 from .types import Junction, Point
 
 logger = logging.getLogger(__name__)
 
 
-class JunctionCollection:
+class JunctionCollection(BaseCollection[Junction]):
     """
     Professional junction collection with enhanced management features.
 
+    Inherits from BaseCollection for standard operations and adds junction-specific
+    functionality.
+
     Features:
-    - Fast UUID-based lookup and indexing
+    - Fast UUID-based lookup and indexing (inherited)
     - Position-based junction queries
-    - Bulk operations for performance
+    - Bulk operations for performance (inherited)
     - Validation and conflict detection
     """
 
-    def __init__(self, junctions: Optional[List[Junction]] = None):
+    def __init__(self, junctions: Optional[List[Junction]] = None) -> None:
         """
         Initialize junction collection.
 
         Args:
             junctions: Initial list of junctions
         """
-        self._junctions: List[Junction] = junctions or []
-        self._uuid_index: Dict[str, int] = {}
-        self._modified = False
-
-        # Build UUID index
-        self._rebuild_index()
-
-        logger.debug(f"JunctionCollection initialized with {len(self._junctions)} junctions")
-
-    def _rebuild_index(self):
-        """Rebuild UUID index for fast lookups."""
-        self._uuid_index = {junction.uuid: i for i, junction in enumerate(self._junctions)}
-
-    def __len__(self) -> int:
-        """Number of junctions in collection."""
-        return len(self._junctions)
-
-    def __iter__(self):
-        """Iterate over junctions."""
-        return iter(self._junctions)
-
-    def __getitem__(self, uuid: str) -> Junction:
-        """Get junction by UUID."""
-        if uuid not in self._uuid_index:
-            raise KeyError(f"Junction with UUID '{uuid}' not found")
-        return self._junctions[self._uuid_index[uuid]]
+        super().__init__(junctions, collection_name="junctions")
 
     def add(
         self,
@@ -94,35 +73,12 @@ class JunctionCollection:
         # Create junction
         junction = Junction(uuid=uuid, position=position, diameter=diameter, color=color)
 
-        # Add to collection
-        self._junctions.append(junction)
-        self._uuid_index[uuid] = len(self._junctions) - 1
-        self._modified = True
+        # Add to collection using base class method
+        self._add_item(junction)
 
         logger.debug(f"Added junction at {position}, UUID={uuid}")
         return uuid
 
-    def remove(self, uuid: str) -> bool:
-        """
-        Remove junction by UUID.
-
-        Args:
-            uuid: Junction UUID to remove
-
-        Returns:
-            True if junction was removed, False if not found
-        """
-        if uuid not in self._uuid_index:
-            return False
-
-        index = self._uuid_index[uuid]
-        del self._junctions[index]
-        self._rebuild_index()
-        self._modified = True
-
-        logger.debug(f"Removed junction: {uuid}")
-        return True
-
     def get_at_position(
         self, position: Union[Point, Tuple[float, float]], tolerance: float = 0.01
     ) -> Optional[Junction]:
@@ -139,7 +95,7 @@ class JunctionCollection:
         if isinstance(position, tuple):
             position = Point(position[0], position[1])
 
-        for junction in self._junctions:
+        for junction in self._items:
             if junction.position.distance_to(position) <= tolerance:
                 return junction
 
@@ -162,40 +118,35 @@ class JunctionCollection:
             point = Point(point[0], point[1])
 
         matching_junctions = []
-        for junction in self._junctions:
+        for junction in self._items:
             if junction.position.distance_to(point) <= tolerance:
                 matching_junctions.append(junction)
 
         return matching_junctions
 
     def get_statistics(self) -> Dict[str, Any]:
-        """Get junction collection statistics."""
-        if not self._junctions:
-            return {"total_junctions": 0, "avg_diameter": 0, "positions": []}
+        """Get junction collection statistics (extends base statistics)."""
+        base_stats = super().get_statistics()
+        if not self._items:
+            return {**base_stats, "total_junctions": 0, "avg_diameter": 0, "positions": []}
 
-        avg_diameter = sum(j.diameter for j in self._junctions) / len(self._junctions)
-        positions = [(j.position.x, j.position.y) for j in self._junctions]
+        avg_diameter = sum(j.diameter for j in self._items) / len(self._items)
+        positions = [(j.position.x, j.position.y) for j in self._items]
 
         return {
-            "total_junctions": len(self._junctions),
+            **base_stats,
+            "total_junctions": len(self._items),
             "avg_diameter": avg_diameter,
             "positions": positions,
-            "unique_diameters": len(set(j.diameter for j in self._junctions)),
-            "unique_colors": len(set(j.color for j in self._junctions)),
+            "unique_diameters": len(set(j.diameter for j in self._items)),
+            "unique_colors": len(set(j.color for j in self._items)),
         }
 
-    def clear(self):
-        """Remove all junctions from collection."""
-        self._junctions.clear()
-        self._uuid_index.clear()
-        self._modified = True
-        logger.debug("Cleared all junctions")
-
     @property
     def modified(self) -> bool:
         """Check if collection has been modified."""
-        return self._modified
+        return self.is_modified()
 
-    def mark_saved(self):
+    def mark_saved(self) -> None:
         """Mark collection as saved (reset modified flag)."""
-        self._modified = False
+        self.reset_modified_flag()