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

kicad_sch_api/parsers/registry.py

@@ -0,0 +1,155 @@
+"""
+Parser registry for managing S-expression element parsers.
+
+Provides a central registry for all element parsers and handles
+dispatching parsing requests to the appropriate parser.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from ..interfaces.parser import IElementParser
+
+logger = logging.getLogger(__name__)
+
+
+class ElementParserRegistry:
+    """
+    Central registry for all S-expression element parsers.
+
+    This class manages the registration of element-specific parsers
+    and provides a unified interface for parsing any S-expression element.
+    """
+
+    def __init__(self):
+        """Initialize the parser registry."""
+        self._parsers: Dict[str, IElementParser] = {}
+        self._fallback_parser: Optional[IElementParser] = None
+        self._logger = logger.getChild(self.__class__.__name__)
+
+    def register(self, element_type: str, parser: IElementParser) -> None:
+        """
+        Register a parser for a specific element type.
+
+        Args:
+            element_type: The S-expression element type (e.g., "symbol", "wire")
+            parser: Parser instance that handles this element type
+
+        Raises:
+            ValueError: If element_type is already registered
+        """
+        if element_type in self._parsers:
+            self._logger.warning(f"Overriding existing parser for element type: {element_type}")
+
+        self._parsers[element_type] = parser
+        self._logger.debug(f"Registered parser for element type: {element_type}")
+
+    def unregister(self, element_type: str) -> bool:
+        """
+        Unregister a parser for a specific element type.
+
+        Args:
+            element_type: The element type to unregister
+
+        Returns:
+            True if parser was removed, False if not found
+        """
+        if element_type in self._parsers:
+            del self._parsers[element_type]
+            self._logger.debug(f"Unregistered parser for element type: {element_type}")
+            return True
+        return False
+
+    def set_fallback_parser(self, parser: IElementParser) -> None:
+        """
+        Set a fallback parser for unknown element types.
+
+        Args:
+            parser: Parser to use when no specific parser is registered
+        """
+        self._fallback_parser = parser
+        self._logger.debug("Set fallback parser")
+
+    def parse_element(self, element: List[Any]) -> Optional[Dict[str, Any]]:
+        """
+        Parse an S-expression element using the appropriate registered parser.
+
+        Args:
+            element: S-expression element to parse
+
+        Returns:
+            Parsed element data or None if parsing failed
+        """
+        if not element or not isinstance(element, list):
+            self._logger.debug("Invalid element: not a list or empty")
+            return None
+
+        element_type = element[0] if element else None
+        # Convert sexpdata.Symbol to string for lookup
+        element_type_str = str(element_type) if element_type else None
+        if not element_type_str:
+            self._logger.debug(f"Invalid element type: {element_type}")
+            return None
+
+        # Try specific parser first
+        parser = self._parsers.get(element_type_str)
+        if parser:
+            self._logger.debug(f"Using registered parser for element type: {element_type_str}")
+            return parser.parse(element)
+
+        # Try fallback parser
+        if self._fallback_parser:
+            self._logger.debug(
+                f"Using fallback parser for unknown element type: {element_type_str}"
+            )
+            return self._fallback_parser.parse(element)
+
+        # No parser available
+        self._logger.warning(f"No parser available for element type: {element_type_str}")
+        return None
+
+    def parse_elements(self, elements: List[List[Any]]) -> List[Dict[str, Any]]:
+        """
+        Parse multiple S-expression elements.
+
+        Args:
+            elements: List of S-expression elements to parse
+
+        Returns:
+            List of parsed element data (excluding failed parses)
+        """
+        results = []
+        for element in elements:
+            parsed = self.parse_element(element)
+            if parsed is not None:
+                results.append(parsed)
+
+        self._logger.debug(f"Parsed {len(results)} of {len(elements)} elements")
+        return results
+
+    def get_registered_types(self) -> List[str]:
+        """
+        Get list of all registered element types.
+
+        Returns:
+            List of registered element type names
+        """
+        return list(self._parsers.keys())
+
+    def has_parser(self, element_type: str) -> bool:
+        """
+        Check if a parser is registered for the given element type.
+
+        Args:
+            element_type: Element type to check
+
+        Returns:
+            True if parser is registered
+        """
+        return element_type in self._parsers
+
+    def clear(self) -> None:
+        """Clear all registered parsers."""
+        self._parsers.clear()
+        self._fallback_parser = None
+        self._logger.debug("Cleared all registered parsers")

kicad_sch_api/parsers/symbol_parser.py

@@ -0,0 +1,222 @@
+"""
+Symbol element parser for S-expression symbol definitions.
+
+Handles parsing of symbol elements with properties, positions, and library references.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+import sexpdata
+
+from .base import BaseElementParser
+
+logger = logging.getLogger(__name__)
+
+
+class SymbolParser(BaseElementParser):
+    """Parser for symbol S-expression elements."""
+
+    def __init__(self):
+        """Initialize symbol parser."""
+        super().__init__("symbol")
+
+    def parse_element(self, element: List[Any]) -> Optional[Dict[str, Any]]:
+        """
+        Parse a symbol S-expression element.
+
+        Expected format:
+        (symbol (lib_id "Device:R") (at x y angle) (property "Reference" "R1" ...)...)
+
+        Args:
+            element: Symbol S-expression element
+
+        Returns:
+            Parsed symbol data with library ID, position, and properties
+        """
+        symbol_data = {
+            "lib_id": "",
+            "position": {"x": 0, "y": 0, "angle": 0},
+            "mirror": "",
+            "unit": 1,
+            "in_bom": True,
+            "on_board": True,
+            "fields_autoplaced": False,
+            "uuid": None,
+            "properties": [],
+            "instances": [],
+        }
+
+        for elem in element[1:]:
+            if not isinstance(elem, list):
+                continue
+
+            elem_type = str(elem[0]) if isinstance(elem[0], sexpdata.Symbol) else None
+
+            if elem_type == "lib_id":
+                symbol_data["lib_id"] = str(elem[1]) if len(elem) > 1 else ""
+            elif elem_type == "at":
+                self._parse_position(elem, symbol_data)
+            elif elem_type == "mirror":
+                symbol_data["mirror"] = str(elem[1]) if len(elem) > 1 else ""
+            elif elem_type == "unit":
+                symbol_data["unit"] = int(elem[1]) if len(elem) > 1 else 1
+            elif elem_type == "in_bom":
+                symbol_data["in_bom"] = self._parse_boolean(elem[1]) if len(elem) > 1 else True
+            elif elem_type == "on_board":
+                symbol_data["on_board"] = self._parse_boolean(elem[1]) if len(elem) > 1 else True
+            elif elem_type == "fields_autoplaced":
+                symbol_data["fields_autoplaced"] = True
+            elif elem_type == "uuid":
+                symbol_data["uuid"] = str(elem[1]) if len(elem) > 1 else None
+            elif elem_type == "property":
+                prop = self._parse_property(elem)
+                if prop:
+                    symbol_data["properties"].append(prop)
+            elif elem_type == "instances":
+                symbol_data["instances"] = self._parse_instances(elem)
+
+        return symbol_data
+
+    def _parse_position(self, at_element: List[Any], symbol_data: Dict[str, Any]) -> None:
+        """
+        Parse position from at element.
+
+        Args:
+            at_element: (at x y [angle])
+            symbol_data: Symbol data dictionary to update
+        """
+        try:
+            if len(at_element) >= 3:
+                symbol_data["position"]["x"] = float(at_element[1])
+                symbol_data["position"]["y"] = float(at_element[2])
+            if len(at_element) >= 4:
+                symbol_data["position"]["angle"] = float(at_element[3])
+        except (ValueError, IndexError) as e:
+            self._logger.warning(f"Invalid position coordinates: {at_element}, error: {e}")
+
+    def _parse_property(self, prop_element: List[Any]) -> Optional[Dict[str, Any]]:
+        """
+        Parse a property element.
+
+        Args:
+            prop_element: (property "name" "value" (at x y angle) ...)
+
+        Returns:
+            Parsed property data or None if invalid
+        """
+        if len(prop_element) < 3:
+            return None
+
+        prop_data = {
+            "name": str(prop_element[1]),
+            "value": str(prop_element[2]),
+            "position": {"x": 0, "y": 0, "angle": 0},
+            "effects": {},
+        }
+
+        # Parse additional property elements
+        for elem in prop_element[3:]:
+            if isinstance(elem, list) and len(elem) > 0:
+                elem_type = str(elem[0])
+                if elem_type == "at":
+                    self._parse_property_position(elem, prop_data)
+                elif elem_type == "effects":
+                    prop_data["effects"] = self._parse_effects(elem)
+
+        return prop_data
+
+    def _parse_property_position(self, at_element: List[Any], prop_data: Dict[str, Any]) -> None:
+        """Parse property position from at element."""
+        try:
+            if len(at_element) >= 3:
+                prop_data["position"]["x"] = float(at_element[1])
+                prop_data["position"]["y"] = float(at_element[2])
+            if len(at_element) >= 4:
+                prop_data["position"]["angle"] = float(at_element[3])
+        except (ValueError, IndexError) as e:
+            self._logger.warning(f"Invalid property position: {at_element}, error: {e}")
+
+    def _parse_effects(self, effects_element: List[Any]) -> Dict[str, Any]:
+        """Parse effects element for text formatting."""
+        effects = {
+            "font_size": 1.27,
+            "font_thickness": 0.15,
+            "bold": False,
+            "italic": False,
+            "hide": False,
+            "justify": [],
+        }
+
+        for elem in effects_element[1:]:
+            if isinstance(elem, list) and len(elem) > 0:
+                elem_type = str(elem[0])
+                if elem_type == "font":
+                    self._parse_font(elem, effects)
+                elif elem_type == "justify":
+                    effects["justify"] = [str(j) for j in elem[1:]]
+                elif elem_type == "hide":
+                    effects["hide"] = True
+
+        return effects
+
+    def _parse_font(self, font_element: List[Any], effects: Dict[str, Any]) -> None:
+        """Parse font element within effects."""
+        for elem in font_element[1:]:
+            if isinstance(elem, list) and len(elem) > 0:
+                elem_type = str(elem[0])
+                if elem_type == "size":
+                    try:
+                        if len(elem) >= 3:
+                            effects["font_size"] = float(elem[1])
+                    except (ValueError, IndexError):
+                        pass
+                elif elem_type == "thickness":
+                    try:
+                        effects["font_thickness"] = float(elem[1])
+                    except (ValueError, IndexError):
+                        pass
+                elif elem_type == "bold":
+                    effects["bold"] = True
+                elif elem_type == "italic":
+                    effects["italic"] = True
+
+    def _parse_instances(self, instances_element: List[Any]) -> List[Dict[str, Any]]:
+        """Parse instances element for symbol instances."""
+        instances = []
+        for elem in instances_element[1:]:
+            if isinstance(elem, list) and len(elem) > 0 and str(elem[0]) == "instance":
+                instance = self._parse_instance(elem)
+                if instance:
+                    instances.append(instance)
+        return instances
+
+    def _parse_instance(self, instance_element: List[Any]) -> Optional[Dict[str, Any]]:
+        """Parse a single instance element."""
+        instance = {"project": "", "path": "", "reference": "", "unit": 1}
+
+        for elem in instance_element[1:]:
+            if isinstance(elem, list) and len(elem) >= 2:
+                elem_type = str(elem[0])
+                if elem_type == "project":
+                    instance["project"] = str(elem[1])
+                elif elem_type == "path":
+                    instance["path"] = str(elem[1])
+                elif elem_type == "reference":
+                    instance["reference"] = str(elem[1])
+                elif elem_type == "unit":
+                    try:
+                        instance["unit"] = int(elem[1])
+                    except (ValueError, IndexError):
+                        pass
+
+        return instance if instance["reference"] else None
+
+    def _parse_boolean(self, value: Any) -> bool:
+        """Parse boolean value from S-expression."""
+        if isinstance(value, str):
+            return value.lower() in ("yes", "true", "1")
+        elif isinstance(value, sexpdata.Symbol):
+            return str(value).lower() in ("yes", "true", "1")
+        else:
+            return bool(value)

kicad_sch_api/parsers/wire_parser.py

@@ -0,0 +1,99 @@
+"""
+Wire element parser for S-expression wire definitions.
+
+Handles parsing of wire elements with points, stroke properties, and UUIDs.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+import sexpdata
+
+from .base import BaseElementParser
+
+logger = logging.getLogger(__name__)
+
+
+class WireParser(BaseElementParser):
+    """Parser for wire S-expression elements."""
+
+    def __init__(self):
+        """Initialize wire parser."""
+        super().__init__("wire")
+
+    def parse_element(self, element: List[Any]) -> Optional[Dict[str, Any]]:
+        """
+        Parse a wire S-expression element.
+
+        Expected format:
+        (wire (pts (xy x1 y1) (xy x2 y2) ...) (stroke (width w) (type t)) (uuid "..."))
+
+        Args:
+            element: Wire S-expression element
+
+        Returns:
+            Parsed wire data with points, stroke, and UUID information
+        """
+        wire_data = {
+            "points": [],
+            "stroke_width": 0.0,
+            "stroke_type": "default",
+            "uuid": None,
+            "wire_type": "wire",  # Default to wire (vs bus)
+        }
+
+        for elem in element[1:]:
+            if not isinstance(elem, list):
+                continue
+
+            elem_type = str(elem[0]) if isinstance(elem[0], sexpdata.Symbol) else None
+
+            if elem_type == "pts":
+                self._parse_points(elem, wire_data)
+            elif elem_type == "stroke":
+                self._parse_stroke(elem, wire_data)
+            elif elem_type == "uuid":
+                wire_data["uuid"] = str(elem[1]) if len(elem) > 1 else None
+
+        # Validate wire has sufficient points
+        if len(wire_data["points"]) >= 2:
+            return wire_data
+        else:
+            self._logger.warning(f"Wire has insufficient points: {len(wire_data['points'])}")
+            return None
+
+    def _parse_points(self, pts_element: List[Any], wire_data: Dict[str, Any]) -> None:
+        """
+        Parse points from pts element.
+
+        Args:
+            pts_element: (pts (xy x1 y1) (xy x2 y2) ...)
+            wire_data: Wire data dictionary to update
+        """
+        for pt in pts_element[1:]:
+            if isinstance(pt, list) and len(pt) >= 3:
+                if str(pt[0]) == "xy":
+                    try:
+                        x, y = float(pt[1]), float(pt[2])
+                        wire_data["points"].append({"x": x, "y": y})
+                    except (ValueError, IndexError) as e:
+                        self._logger.warning(f"Invalid point coordinates: {pt}, error: {e}")
+
+    def _parse_stroke(self, stroke_element: List[Any], wire_data: Dict[str, Any]) -> None:
+        """
+        Parse stroke properties from stroke element.
+
+        Args:
+            stroke_element: (stroke (width w) (type t))
+            wire_data: Wire data dictionary to update
+        """
+        for stroke_elem in stroke_element[1:]:
+            if isinstance(stroke_elem, list) and len(stroke_elem) >= 2:
+                stroke_type = str(stroke_elem[0])
+                try:
+                    if stroke_type == "width":
+                        wire_data["stroke_width"] = float(stroke_elem[1])
+                    elif stroke_type == "type":
+                        wire_data["stroke_type"] = str(stroke_elem[1])
+                except (ValueError, IndexError) as e:
+                    self._logger.warning(f"Invalid stroke property: {stroke_elem}, error: {e}")

kicad_sch_api/symbols/__init__.py

@@ -0,0 +1,18 @@
+"""
+Symbol resolution and caching architecture for KiCAD schematic API.
+
+This module provides a unified symbol resolution system that separates concerns
+between caching, inheritance resolution, and validation while maintaining
+high performance and exact format preservation.
+"""
+
+from .cache import ISymbolCache, SymbolCache
+from .resolver import SymbolResolver
+from .validators import SymbolValidator
+
+__all__ = [
+    "ISymbolCache",
+    "SymbolCache",
+    "SymbolResolver",
+    "SymbolValidator",
+]