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

kicad_sch_api/core/exceptions.py

@@ -0,0 +1,175 @@
+"""
+Exception hierarchy for kicad-sch-api.
+
+Provides a structured exception hierarchy for better error handling and debugging.
+All exceptions inherit from the base KiCadSchError class.
+"""
+
+from typing import Any, List, Optional, TYPE_CHECKING
+
+# Import validation types for type hints
+# ValidationLevel is imported at runtime in methods that need it
+if TYPE_CHECKING:
+    from ..utils.validation import ValidationIssue
+
+
+class KiCadSchError(Exception):
+    """Base exception for all kicad-sch-api errors."""
+
+    pass
+
+
+class ValidationError(KiCadSchError):
+    """
+    Raised when validation fails.
+
+    Supports rich error context with field/value information and can collect
+    multiple validation issues.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        issues: Optional[List["ValidationIssue"]] = None,
+        field: str = "",
+        value: Any = None,
+    ):
+        """
+        Initialize validation error with context.
+
+        Args:
+            message: Error message describing the validation failure
+            issues: List of validation issues (for collecting multiple errors)
+            field: The field name that failed validation
+            value: The invalid value that was provided
+        """
+        self.issues = issues or []
+        self.field = field
+        self.value = value
+        super().__init__(message)
+
+    def add_issue(self, issue: "ValidationIssue") -> None:
+        """Add a validation issue to this error."""
+        self.issues.append(issue)
+
+    def get_errors(self) -> List["ValidationIssue"]:
+        """Get only error-level issues."""
+        # Import here to avoid circular dependency
+        from ..utils.validation import ValidationLevel
+
+        return [
+            issue
+            for issue in self.issues
+            if hasattr(issue, 'level') and issue.level in (ValidationLevel.ERROR, ValidationLevel.CRITICAL)
+        ]
+
+    def get_warnings(self) -> List["ValidationIssue"]:
+        """Get only warning-level issues."""
+        # Import here to avoid circular dependency
+        from ..utils.validation import ValidationLevel
+
+        return [issue for issue in self.issues if hasattr(issue, 'level') and issue.level == ValidationLevel.WARNING]
+
+
+class ReferenceError(ValidationError):
+    """Raised when a component reference is invalid."""
+
+    pass
+
+
+class LibraryError(ValidationError):
+    """Raised when a library or symbol reference is invalid."""
+
+    pass
+
+
+class GeometryError(ValidationError):
+    """Raised when geometry validation fails (positions, shapes, dimensions)."""
+
+    pass
+
+
+class NetError(ValidationError):
+    """Raised when a net specification or operation is invalid."""
+
+    pass
+
+
+class ParseError(KiCadSchError):
+    """Raised when parsing a schematic file fails."""
+
+    pass
+
+
+class FormatError(KiCadSchError):
+    """Raised when formatting a schematic file fails."""
+
+    pass
+
+
+class CollectionError(KiCadSchError):
+    """Raised when a collection operation fails."""
+
+    pass
+
+
+class ElementNotFoundError(CollectionError):
+    """Raised when an element is not found in a collection."""
+
+    def __init__(self, message: str, element_type: str = "", identifier: str = ""):
+        """
+        Initialize element not found error.
+
+        Args:
+            message: Error message
+            element_type: Type of element (e.g., 'component', 'wire', 'junction')
+            identifier: The identifier used to search (e.g., 'R1', UUID)
+        """
+        self.element_type = element_type
+        self.identifier = identifier
+        super().__init__(message)
+
+
+class DuplicateElementError(CollectionError):
+    """Raised when attempting to add a duplicate element."""
+
+    def __init__(self, message: str, element_type: str = "", identifier: str = ""):
+        """
+        Initialize duplicate element error.
+
+        Args:
+            message: Error message
+            element_type: Type of element (e.g., 'component', 'wire', 'junction')
+            identifier: The duplicate identifier (e.g., 'R1', UUID)
+        """
+        self.element_type = element_type
+        self.identifier = identifier
+        super().__init__(message)
+
+
+class CollectionOperationError(CollectionError):
+    """Raised when a collection operation fails for reasons other than not found/duplicate."""
+
+    pass
+
+
+class FileOperationError(KiCadSchError):
+    """Raised when a file I/O operation fails."""
+
+    pass
+
+
+class CLIError(KiCadSchError):
+    """Raised when KiCad CLI execution fails."""
+
+    pass
+
+
+class SchematicStateError(KiCadSchError):
+    """
+    Raised when an operation requires specific schematic state.
+
+    Examples: schematic must be saved before export, etc.
+    """
+
+    pass

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,278 @@
+"""
+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", "label")),
+            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
+            ),
+            justify_h=label_dict.get("justify_h", "left"),
+            justify_v=label_dict.get("justify_v", "bottom"),
+        )
+
+    @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)  # No quotes for paper size (A4, A3, etc.)
+        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)
@@ -123,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)
@@ -146,6 +152,9 @@ class ExactFormatter:
         self.rules["embedded_fonts"] = FormatRule(inline=True)
         self.rules["page"] = FormatRule(inline=True, quote_indices={1})
 
+        # Image element
+        self.rules["image"] = FormatRule(inline=False, custom_handler=self._format_image)
+
     def format(self, data: Any) -> str:
         """
         Format S-expression data with exact KiCAD formatting.
@@ -189,7 +198,8 @@ class ExactFormatter:
         elif isinstance(element, str):
             # Quote strings that need quoting
             if self._needs_quoting(element):
-                return f'"{element}"'
+                escaped = self._escape_string(element)
+                return f'"{escaped}"'
             return element
         elif isinstance(element, float):
             # Custom float formatting for KiCAD compatibility
@@ -273,6 +283,8 @@ class ExactFormatter:
             "junction",
             "label",
             "hierarchical_label",
+            "text",
+            "text_box",
             "polyline",
             "rectangle",
         ):
@@ -378,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)}"
 
@@ -390,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):
@@ -419,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."""
@@ -460,8 +483,8 @@ class ExactFormatter:
             for item in lst[1:]:
                 if isinstance(item, list) and len(item) >= 1:
                     tag = str(item[0])
-                    if tag in ["version", "generator", "generator_version"] and len(item) >= 2:
-                        if tag in ["generator", "generator_version"]:
+                    if tag in ["version", "generator", "generator_version", "uuid"] and len(item) >= 2:
+                        if tag in ["generator", "generator_version", "uuid"]:
                             header_parts.append(f'({tag} "{item[1]}")')
                         else:
                             header_parts.append(f"({tag} {item[1]})")
@@ -510,6 +533,34 @@ class ExactFormatter:
         result += f"\n{indent})"
         return result
 
+    def _format_image(self, lst: List[Any], indent_level: int) -> str:
+        """Format image elements with base64 data split across lines."""
+        indent = "\t" * indent_level
+        next_indent = "\t" * (indent_level + 1)
+
+        result = f"({lst[0]}"
+
+        # Process each element
+        for element in lst[1:]:
+            if isinstance(element, list):
+                tag = str(element[0]) if element else ""
+                if tag == "data":
+                    # Special handling for data element
+                    # First chunk on same line as (data, rest on subsequent lines
+                    if len(element) > 1:
+                        result += f'\n{next_indent}({element[0]} "{element[1]}"'
+                        for chunk in element[2:]:
+                            result += f'\n{next_indent}\t"{chunk}"'
+                        result += f"\n{next_indent})"
+                    else:
+                        result += f"\n{next_indent}({element[0]})"
+                else:
+                    # Regular element formatting
+                    result += f"\n{next_indent}{self._format_element(element, indent_level + 1)}"
+
+        result += f"\n{indent})"
+        return result
+
 
 class CompactFormatter(ExactFormatter):
     """Compact formatter for minimal output size."""