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

kicad_sch_api/parsers/elements/text_parser.py

@@ -0,0 +1,250 @@
+"""
+Text and text box elements parser for KiCAD schematics.
+
+Handles parsing and serialization of Text and text box elements.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+import sexpdata
+
+from ...core.config import config
+from ..base import BaseElementParser
+
+logger = logging.getLogger(__name__)
+
+
+class TextParser(BaseElementParser):
+    """Parser for Text and text box elements."""
+
+    def __init__(self):
+        """Initialize text parser."""
+        super().__init__("text")
+
+    def _parse_text(self, item: List[Any]) -> Optional[Dict[str, Any]]:
+        """Parse a text element."""
+        # Format: (text "text" (exclude_from_sim no) (at x y rotation) (effects ...) (uuid ...))
+        if len(item) < 2:
+            return None
+
+        text_data = {
+            "text": str(item[1]),
+            "exclude_from_sim": False,
+            "position": {"x": 0, "y": 0},
+            "rotation": 0,
+            "size": config.defaults.font_size,
+            "uuid": None,
+        }
+
+        for elem in item[2:]:
+            if not isinstance(elem, list):
+                continue
+
+            elem_type = str(elem[0]) if isinstance(elem[0], sexpdata.Symbol) else None
+
+            if elem_type == "exclude_from_sim":
+                if len(elem) >= 2:
+                    text_data["exclude_from_sim"] = str(elem[1]) == "yes"
+            elif elem_type == "at":
+                if len(elem) >= 3:
+                    text_data["position"] = {"x": float(elem[1]), "y": float(elem[2])}
+                if len(elem) >= 4:
+                    text_data["rotation"] = float(elem[3])
+            elif elem_type == "effects":
+                for effect_elem in elem[1:]:
+                    if isinstance(effect_elem, list) and str(effect_elem[0]) == "font":
+                        for font_elem in effect_elem[1:]:
+                            if isinstance(font_elem, list) and str(font_elem[0]) == "size":
+                                if len(font_elem) >= 2:
+                                    text_data["size"] = float(font_elem[1])
+            elif elem_type == "uuid":
+                text_data["uuid"] = str(elem[1]) if len(elem) > 1 else None
+
+        return text_data
+
+
+    def _parse_text_box(self, item: List[Any]) -> Optional[Dict[str, Any]]:
+        """Parse a text_box element."""
+        # Format: (text_box "text" (exclude_from_sim no) (at x y rotation) (size w h) (margins ...) (stroke ...) (fill ...) (effects ...) (uuid ...))
+        if len(item) < 2:
+            return None
+
+        text_box_data = {
+            "text": str(item[1]),
+            "exclude_from_sim": False,
+            "position": {"x": 0, "y": 0},
+            "rotation": 0,
+            "size": {"width": 0, "height": 0},
+            "margins": (0.9525, 0.9525, 0.9525, 0.9525),
+            "stroke_width": 0,
+            "stroke_type": "solid",
+            "fill_type": "none",
+            "font_size": config.defaults.font_size,
+            "justify_horizontal": "left",
+            "justify_vertical": "top",
+            "uuid": None,
+        }
+
+        for elem in item[2:]:
+            if not isinstance(elem, list):
+                continue
+
+            elem_type = str(elem[0]) if isinstance(elem[0], sexpdata.Symbol) else None
+
+            if elem_type == "exclude_from_sim":
+                if len(elem) >= 2:
+                    text_box_data["exclude_from_sim"] = str(elem[1]) == "yes"
+            elif elem_type == "at":
+                if len(elem) >= 3:
+                    text_box_data["position"] = {"x": float(elem[1]), "y": float(elem[2])}
+                if len(elem) >= 4:
+                    text_box_data["rotation"] = float(elem[3])
+            elif elem_type == "size":
+                if len(elem) >= 3:
+                    text_box_data["size"] = {"width": float(elem[1]), "height": float(elem[2])}
+            elif elem_type == "margins":
+                if len(elem) >= 5:
+                    text_box_data["margins"] = (
+                        float(elem[1]),
+                        float(elem[2]),
+                        float(elem[3]),
+                        float(elem[4]),
+                    )
+            elif elem_type == "stroke":
+                for stroke_elem in elem[1:]:
+                    if isinstance(stroke_elem, list):
+                        stroke_type = str(stroke_elem[0])
+                        if stroke_type == "width" and len(stroke_elem) >= 2:
+                            text_box_data["stroke_width"] = float(stroke_elem[1])
+                        elif stroke_type == "type" and len(stroke_elem) >= 2:
+                            text_box_data["stroke_type"] = str(stroke_elem[1])
+            elif elem_type == "fill":
+                for fill_elem in elem[1:]:
+                    if isinstance(fill_elem, list) and str(fill_elem[0]) == "type":
+                        text_box_data["fill_type"] = (
+                            str(fill_elem[1]) if len(fill_elem) >= 2 else "none"
+                        )
+            elif elem_type == "effects":
+                for effect_elem in elem[1:]:
+                    if isinstance(effect_elem, list):
+                        effect_type = str(effect_elem[0])
+                        if effect_type == "font":
+                            for font_elem in effect_elem[1:]:
+                                if isinstance(font_elem, list) and str(font_elem[0]) == "size":
+                                    if len(font_elem) >= 2:
+                                        text_box_data["font_size"] = float(font_elem[1])
+                        elif effect_type == "justify":
+                            if len(effect_elem) >= 2:
+                                text_box_data["justify_horizontal"] = str(effect_elem[1])
+                            if len(effect_elem) >= 3:
+                                text_box_data["justify_vertical"] = str(effect_elem[2])
+            elif elem_type == "uuid":
+                text_box_data["uuid"] = str(elem[1]) if len(elem) > 1 else None
+
+        return text_box_data
+
+
+    def _text_to_sexp(self, text_data: Dict[str, Any]) -> List[Any]:
+        """Convert text element to S-expression."""
+        sexp = [sexpdata.Symbol("text"), text_data["text"]]
+
+        # Add exclude_from_sim
+        exclude_sim = text_data.get("exclude_from_sim", False)
+        sexp.append(
+            [sexpdata.Symbol("exclude_from_sim"), sexpdata.Symbol("yes" if exclude_sim else "no")]
+        )
+
+        # Add position
+        pos = text_data["position"]
+        x, y = pos["x"], pos["y"]
+        rotation = text_data.get("rotation", 0)
+
+        # Format coordinates properly
+        if isinstance(x, float) and x.is_integer():
+            x = int(x)
+        if isinstance(y, float) and y.is_integer():
+            y = int(y)
+
+        sexp.append([sexpdata.Symbol("at"), x, y, rotation])
+
+        # Add effects (font properties)
+        size = text_data.get("size", config.defaults.font_size)
+        effects = [sexpdata.Symbol("effects")]
+        font = [sexpdata.Symbol("font"), [sexpdata.Symbol("size"), size, size]]
+        effects.append(font)
+        sexp.append(effects)
+
+        # Add UUID
+        if "uuid" in text_data:
+            sexp.append([sexpdata.Symbol("uuid"), text_data["uuid"]])
+
+        return sexp
+
+
+    def _text_box_to_sexp(self, text_box_data: Dict[str, Any]) -> List[Any]:
+        """Convert text box element to S-expression."""
+        sexp = [sexpdata.Symbol("text_box"), text_box_data["text"]]
+
+        # Add exclude_from_sim
+        exclude_sim = text_box_data.get("exclude_from_sim", False)
+        sexp.append(
+            [sexpdata.Symbol("exclude_from_sim"), sexpdata.Symbol("yes" if exclude_sim else "no")]
+        )
+
+        # Add position
+        pos = text_box_data["position"]
+        x, y = pos["x"], pos["y"]
+        rotation = text_box_data.get("rotation", 0)
+
+        # Format coordinates properly
+        if isinstance(x, float) and x.is_integer():
+            x = int(x)
+        if isinstance(y, float) and y.is_integer():
+            y = int(y)
+
+        sexp.append([sexpdata.Symbol("at"), x, y, rotation])
+
+        # Add size
+        size = text_box_data["size"]
+        w, h = size["width"], size["height"]
+        sexp.append([sexpdata.Symbol("size"), w, h])
+
+        # Add margins
+        margins = text_box_data.get("margins", (0.9525, 0.9525, 0.9525, 0.9525))
+        sexp.append([sexpdata.Symbol("margins"), margins[0], margins[1], margins[2], margins[3]])
+
+        # Add stroke
+        stroke_width = text_box_data.get("stroke_width", 0)
+        stroke_type = text_box_data.get("stroke_type", "solid")
+        stroke_sexp = [sexpdata.Symbol("stroke")]
+        stroke_sexp.append([sexpdata.Symbol("width"), stroke_width])
+        stroke_sexp.append([sexpdata.Symbol("type"), sexpdata.Symbol(stroke_type)])
+        sexp.append(stroke_sexp)
+
+        # Add fill
+        fill_type = text_box_data.get("fill_type", "none")
+        fill_sexp = [sexpdata.Symbol("fill")]
+        fill_sexp.append([sexpdata.Symbol("type"), sexpdata.Symbol(fill_type)])
+        sexp.append(fill_sexp)
+
+        # Add effects (font properties and justification)
+        font_size = text_box_data.get("font_size", config.defaults.font_size)
+        justify_h = text_box_data.get("justify_horizontal", "left")
+        justify_v = text_box_data.get("justify_vertical", "top")
+
+        effects = [sexpdata.Symbol("effects")]
+        font = [sexpdata.Symbol("font"), [sexpdata.Symbol("size"), font_size, font_size]]
+        effects.append(font)
+        effects.append(
+            [sexpdata.Symbol("justify"), sexpdata.Symbol(justify_h), sexpdata.Symbol(justify_v)]
+        )
+        sexp.append(effects)
+
+        # Add UUID
+        if "uuid" in text_box_data:
+            sexp.append([sexpdata.Symbol("uuid"), text_box_data["uuid"]])
+
+        return sexp
+
+

kicad_sch_api/parsers/elements/wire_parser.py

@@ -0,0 +1,242 @@
+"""
+Wire and connection element parsers for KiCAD schematics.
+
+Handles parsing and serialization of connection elements:
+- Wire
+- Junction
+- No-connect
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+import sexpdata
+
+from ...core.config import config
+from ..base import BaseElementParser
+
+logger = logging.getLogger(__name__)
+
+
+class WireParser(BaseElementParser):
+    """Parser for wire and connection elements."""
+
+    def __init__(self):
+        """Initialize wire parser."""
+        super().__init__("wire")
+
+    def _parse_wire(self, item: List[Any]) -> Optional[Dict[str, Any]]:
+        """Parse a wire definition."""
+        wire_data = {
+            "points": [],
+            "stroke_width": 0.0,
+            "stroke_type": config.defaults.stroke_type,
+            "uuid": None,
+            "wire_type": "wire",  # Default to wire (vs bus)
+        }
+
+        for elem in item[1:]:
+            if not isinstance(elem, list):
+                continue
+
+            elem_type = str(elem[0]) if isinstance(elem[0], sexpdata.Symbol) else None
+
+            if elem_type == "pts":
+                # Parse points: (pts (xy x1 y1) (xy x2 y2) ...)
+                for pt in elem[1:]:
+                    if isinstance(pt, list) and len(pt) >= 3:
+                        if str(pt[0]) == "xy":
+                            x, y = float(pt[1]), float(pt[2])
+                            wire_data["points"].append({"x": x, "y": y})
+
+            elif elem_type == "stroke":
+                # Parse stroke: (stroke (width 0) (type default))
+                for stroke_elem in elem[1:]:
+                    if isinstance(stroke_elem, list) and len(stroke_elem) >= 2:
+                        stroke_type = str(stroke_elem[0])
+                        if stroke_type == "width":
+                            wire_data["stroke_width"] = float(stroke_elem[1])
+                        elif stroke_type == "type":
+                            wire_data["stroke_type"] = str(stroke_elem[1])
+
+            elif elem_type == "uuid":
+                wire_data["uuid"] = str(elem[1]) if len(elem) > 1 else None
+
+        # Only return wire if it has at least 2 points
+        if len(wire_data["points"]) >= 2:
+            return wire_data
+        else:
+            logger.warning(f"Wire has insufficient points: {len(wire_data['points'])}")
+            return None
+
+
+    def _parse_junction(self, item: List[Any]) -> Optional[Dict[str, Any]]:
+        """Parse a junction definition."""
+        junction_data = {
+            "position": {"x": 0, "y": 0},
+            "diameter": 0,
+            "color": (0, 0, 0, 0),
+            "uuid": None,
+        }
+
+        for elem in item[1:]:
+            if not isinstance(elem, list):
+                continue
+
+            elem_type = str(elem[0]) if isinstance(elem[0], sexpdata.Symbol) else None
+
+            if elem_type == "at":
+                # Parse position: (at x y)
+                if len(elem) >= 3:
+                    junction_data["position"] = {"x": float(elem[1]), "y": float(elem[2])}
+
+            elif elem_type == "diameter":
+                # Parse diameter: (diameter value)
+                if len(elem) >= 2:
+                    junction_data["diameter"] = float(elem[1])
+
+            elif elem_type == "color":
+                # Parse color: (color r g b a)
+                if len(elem) >= 5:
+                    junction_data["color"] = (
+                        int(elem[1]),
+                        int(elem[2]),
+                        int(elem[3]),
+                        int(elem[4]),
+                    )
+
+            elif elem_type == "uuid":
+                junction_data["uuid"] = str(elem[1]) if len(elem) > 1 else None
+
+        return junction_data
+
+
+    def _parse_no_connect(self, item: List[Any]) -> Optional[Dict[str, Any]]:
+        """Parse a no_connect symbol."""
+        # Format: (no_connect (at x y) (uuid ...))
+        no_connect_data = {"position": {"x": 0, "y": 0}, "uuid": None}
+
+        for elem in item[1:]:
+            if not isinstance(elem, list):
+                continue
+
+            elem_type = str(elem[0]) if isinstance(elem[0], sexpdata.Symbol) else None
+
+            if elem_type == "at":
+                if len(elem) >= 3:
+                    no_connect_data["position"] = {"x": float(elem[1]), "y": float(elem[2])}
+            elif elem_type == "uuid":
+                no_connect_data["uuid"] = str(elem[1]) if len(elem) > 1 else None
+
+        return no_connect_data
+
+
+    def _wire_to_sexp(self, wire_data: Dict[str, Any]) -> List[Any]:
+        """Convert wire to S-expression."""
+        sexp = [sexpdata.Symbol("wire")]
+
+        # Add points (pts section)
+        points = wire_data.get("points", [])
+        if len(points) >= 2:
+            pts_sexp = [sexpdata.Symbol("pts")]
+            for point in points:
+                if isinstance(point, dict):
+                    x, y = point["x"], point["y"]
+                elif isinstance(point, (list, tuple)) and len(point) >= 2:
+                    x, y = point[0], point[1]
+                else:
+                    # Assume it's a Point object
+                    x, y = point.x, point.y
+
+                # Format coordinates properly (avoid unnecessary .0 for integers)
+                if isinstance(x, float) and x.is_integer():
+                    x = int(x)
+                if isinstance(y, float) and y.is_integer():
+                    y = int(y)
+
+                pts_sexp.append([sexpdata.Symbol("xy"), x, y])
+            sexp.append(pts_sexp)
+
+        # Add stroke information
+        stroke_width = wire_data.get("stroke_width", config.defaults.stroke_width)
+        stroke_type = wire_data.get("stroke_type", config.defaults.stroke_type)
+        stroke_sexp = [sexpdata.Symbol("stroke")]
+
+        # Format stroke width (use int for 0, preserve float for others)
+        if isinstance(stroke_width, float) and stroke_width == 0.0:
+            stroke_width = 0
+
+        stroke_sexp.append([sexpdata.Symbol("width"), stroke_width])
+        stroke_sexp.append([sexpdata.Symbol("type"), sexpdata.Symbol(stroke_type)])
+        sexp.append(stroke_sexp)
+
+        # Add UUID
+        if "uuid" in wire_data:
+            sexp.append([sexpdata.Symbol("uuid"), wire_data["uuid"]])
+
+        return sexp
+
+
+    def _junction_to_sexp(self, junction_data: Dict[str, Any]) -> List[Any]:
+        """Convert junction to S-expression."""
+        sexp = [sexpdata.Symbol("junction")]
+
+        # Add position
+        pos = junction_data["position"]
+        if isinstance(pos, dict):
+            x, y = pos["x"], pos["y"]
+        elif isinstance(pos, (list, tuple)) and len(pos) >= 2:
+            x, y = pos[0], pos[1]
+        else:
+            # Assume it's a Point object
+            x, y = pos.x, pos.y
+
+        # Format coordinates properly
+        if isinstance(x, float) and x.is_integer():
+            x = int(x)
+        if isinstance(y, float) and y.is_integer():
+            y = int(y)
+
+        sexp.append([sexpdata.Symbol("at"), x, y])
+
+        # Add diameter
+        diameter = junction_data.get("diameter", 0)
+        sexp.append([sexpdata.Symbol("diameter"), diameter])
+
+        # Add color (RGBA)
+        color = junction_data.get("color", (0, 0, 0, 0))
+        if isinstance(color, (list, tuple)) and len(color) >= 4:
+            sexp.append([sexpdata.Symbol("color"), color[0], color[1], color[2], color[3]])
+        else:
+            sexp.append([sexpdata.Symbol("color"), 0, 0, 0, 0])
+
+        # Add UUID
+        if "uuid" in junction_data:
+            sexp.append([sexpdata.Symbol("uuid"), junction_data["uuid"]])
+
+        return sexp
+
+
+    def _no_connect_to_sexp(self, no_connect_data: Dict[str, Any]) -> List[Any]:
+        """Convert no_connect to S-expression."""
+        sexp = [sexpdata.Symbol("no_connect")]
+
+        # Add position
+        pos = no_connect_data["position"]
+        x, y = pos["x"], pos["y"]
+
+        # Format coordinates properly
+        if isinstance(x, float) and x.is_integer():
+            x = int(x)
+        if isinstance(y, float) and y.is_integer():
+            y = int(y)
+
+        sexp.append([sexpdata.Symbol("at"), x, y])
+
+        # Add UUID
+        if "uuid" in no_connect_data:
+            sexp.append([sexpdata.Symbol("uuid"), no_connect_data["uuid"]])
+
+        return sexp
+
+

kicad_sch_api/parsers/utils.py

@@ -0,0 +1,80 @@
+"""
+Utility functions for S-expression parsing.
+
+Common helper functions used across multiple element parsers,
+extracted from monolithic parser.py for reusability.
+"""
+
+from typing import List
+
+
+def color_to_rgba(color_name: str) -> List[float]:
+    """
+    Convert color name to RGBA values (0.0-1.0) for KiCAD compatibility.
+
+    Args:
+        color_name: Color name (e.g., "red", "blue", "green")
+
+    Returns:
+        List of 4 floats [R, G, B, A] in range 0.0-1.0
+
+    Example:
+        >>> color_to_rgba("red")
+        [1.0, 0.0, 0.0, 1.0]
+        >>> color_to_rgba("unknown")
+        [0.0, 0.0, 0.0, 1.0]  # defaults to black
+    """
+    # Basic color mapping for common colors (0.0-1.0 range)
+    color_map = {
+        "red": [1.0, 0.0, 0.0, 1.0],
+        "blue": [0.0, 0.0, 1.0, 1.0],
+        "green": [0.0, 1.0, 0.0, 1.0],
+        "yellow": [1.0, 1.0, 0.0, 1.0],
+        "magenta": [1.0, 0.0, 1.0, 1.0],
+        "cyan": [0.0, 1.0, 1.0, 1.0],
+        "black": [0.0, 0.0, 0.0, 1.0],
+        "white": [1.0, 1.0, 1.0, 1.0],
+        "gray": [0.5, 0.5, 0.5, 1.0],
+        "grey": [0.5, 0.5, 0.5, 1.0],
+        "orange": [1.0, 0.5, 0.0, 1.0],
+        "purple": [0.5, 0.0, 0.5, 1.0],
+    }
+
+    # Return RGBA values, default to black if color not found
+    return color_map.get(color_name.lower(), [0.0, 0.0, 0.0, 1.0])
+
+
+def color_to_rgb255(color_name: str) -> List[int]:
+    """
+    Convert color name to RGB values (0-255) for KiCAD rectangle graphics.
+
+    Args:
+        color_name: Color name (e.g., "red", "blue", "green")
+
+    Returns:
+        List of 3 integers [R, G, B] in range 0-255
+
+    Example:
+        >>> color_to_rgb255("red")
+        [255, 0, 0]
+        >>> color_to_rgb255("unknown")
+        [0, 0, 0]  # defaults to black
+    """
+    # Basic color mapping for common colors (0-255 range)
+    color_map = {
+        "red": [255, 0, 0],
+        "blue": [0, 0, 255],
+        "green": [0, 255, 0],
+        "yellow": [255, 255, 0],
+        "magenta": [255, 0, 255],
+        "cyan": [0, 255, 255],
+        "black": [0, 0, 0],
+        "white": [255, 255, 255],
+        "gray": [128, 128, 128],
+        "grey": [128, 128, 128],
+        "orange": [255, 128, 0],
+        "purple": [128, 0, 128],
+    }
+
+    # Return RGB values, default to black if color not found
+    return color_map.get(color_name.lower(), [0, 0, 0])

kicad_sch_api/validation/__init__.py

@@ -0,0 +1,25 @@
+"""
+Electrical Rules Check (ERC) validation module.
+
+Provides comprehensive electrical validation for KiCAD schematics.
+"""
+
+from kicad_sch_api.validation.erc import ElectricalRulesChecker
+from kicad_sch_api.validation.erc_models import (
+    ERCConfig,
+    ERCResult,
+    ERCViolation,
+)
+from kicad_sch_api.validation.pin_matrix import (
+    PinConflictMatrix,
+    PinSeverity,
+)
+
+__all__ = [
+    "ERCViolation",
+    "ERCResult",
+    "ERCConfig",
+    "PinConflictMatrix",
+    "PinSeverity",
+    "ElectricalRulesChecker",
+]