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

kicad_sch_api/interfaces/repository.py

@@ -0,0 +1,70 @@
+"""
+Repository interfaces for schematic data persistence.
+
+These interfaces define the contract for loading and saving schematic data,
+abstracting away the specific file format and storage mechanisms.
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, Protocol, Union
+
+
+class ISchematicRepository(Protocol):
+    """Interface for schematic data persistence operations."""
+
+    def load(self, filepath: Union[str, Path]) -> Dict[str, Any]:
+        """
+        Load schematic data from a file.
+
+        Args:
+            filepath: Path to the schematic file
+
+        Returns:
+            Complete schematic data structure
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            RepositoryError: If file cannot be loaded
+        """
+        ...
+
+    def save(self, data: Dict[str, Any], filepath: Union[str, Path]) -> None:
+        """
+        Save schematic data to a file.
+
+        Args:
+            data: Complete schematic data structure
+            filepath: Path where to save the file
+
+        Raises:
+            RepositoryError: If file cannot be saved
+        """
+        ...
+
+    def exists(self, filepath: Union[str, Path]) -> bool:
+        """
+        Check if a schematic file exists.
+
+        Args:
+            filepath: Path to check
+
+        Returns:
+            True if file exists and is accessible
+        """
+        ...
+
+    def validate_format(self, filepath: Union[str, Path]) -> bool:
+        """
+        Validate that a file is in the correct format.
+
+        Args:
+            filepath: Path to the file to validate
+
+        Returns:
+            True if file format is valid
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+        """
+        ...

kicad_sch_api/interfaces/resolver.py

@@ -0,0 +1,117 @@
+"""
+Symbol resolver interfaces for symbol library operations.
+
+These interfaces define the contract for resolving symbols from libraries,
+handling inheritance chains, and managing symbol caching.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Protocol
+
+
+class ISymbolResolver(Protocol):
+    """Interface for symbol resolution and inheritance operations."""
+
+    def resolve_symbol(self, lib_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Resolve a symbol with full inheritance chain applied.
+
+        Args:
+            lib_id: Library identifier (e.g., "Device:R")
+
+        Returns:
+            Fully resolved symbol data with inheritance applied,
+            or None if symbol not found
+
+        Raises:
+            SymbolError: If symbol resolution fails
+        """
+        ...
+
+    def get_symbol_raw(self, lib_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get raw symbol data without inheritance resolution.
+
+        Args:
+            lib_id: Library identifier
+
+        Returns:
+            Raw symbol data as stored in library,
+            or None if symbol not found
+        """
+        ...
+
+    def resolve_inheritance_chain(self, lib_id: str) -> List[str]:
+        """
+        Get the complete inheritance chain for a symbol.
+
+        Args:
+            lib_id: Library identifier
+
+        Returns:
+            List of lib_ids in inheritance order (base to derived)
+
+        Raises:
+            SymbolError: If circular inheritance detected
+        """
+        ...
+
+    def is_symbol_available(self, lib_id: str) -> bool:
+        """
+        Check if a symbol is available in the libraries.
+
+        Args:
+            lib_id: Library identifier
+
+        Returns:
+            True if symbol exists and can be resolved
+        """
+        ...
+
+    def clear_cache(self) -> None:
+        """Clear any cached symbol data."""
+        ...
+
+
+class ISymbolCache(Protocol):
+    """Interface for symbol library caching operations."""
+
+    def get_symbol(self, lib_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get a symbol from cache or load from library.
+
+        Args:
+            lib_id: Library identifier
+
+        Returns:
+            Symbol data or None if not found
+        """
+        ...
+
+    def cache_symbol(self, lib_id: str, symbol_data: Dict[str, Any]) -> None:
+        """
+        Cache symbol data.
+
+        Args:
+            lib_id: Library identifier
+            symbol_data: Symbol data to cache
+        """
+        ...
+
+    def invalidate(self, lib_id: Optional[str] = None) -> None:
+        """
+        Invalidate cache entries.
+
+        Args:
+            lib_id: Specific symbol to invalidate, or None for all
+        """
+        ...
+
+    def get_cache_stats(self) -> Dict[str, Any]:
+        """
+        Get cache statistics.
+
+        Returns:
+            Dictionary with cache statistics (hits, misses, size, etc.)
+        """
+        ...

kicad_sch_api/parsers/__init__.py

@@ -0,0 +1,14 @@
+"""
+Modular S-expression parsers for KiCAD elements.
+
+This package provides specialized parsers for different types of KiCAD
+S-expression elements, organized by responsibility and testable in isolation.
+"""
+
+from .registry import ElementParserRegistry
+from .base import BaseElementParser
+
+__all__ = [
+    "ElementParserRegistry",
+    "BaseElementParser",
+]

kicad_sch_api/parsers/base.py

@@ -0,0 +1,148 @@
+"""
+Base parser implementation for S-expression elements.
+
+Provides common functionality and utilities for all element parsers.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from ..interfaces.parser import IElementParser
+
+logger = logging.getLogger(__name__)
+
+
+class BaseElementParser(IElementParser):
+    """Base implementation for S-expression element parsers."""
+
+    def __init__(self, element_type: str):
+        """
+        Initialize base parser.
+
+        Args:
+            element_type: The S-expression element type this parser handles
+        """
+        self.element_type = element_type
+        self._logger = logger.getChild(self.__class__.__name__)
+
+    def can_parse(self, element: List[Any]) -> bool:
+        """Check if this parser can handle the given element type."""
+        if not element or not isinstance(element, list):
+            return False
+
+        element_type = element[0] if element else None
+        # Convert sexpdata.Symbol to string for comparison
+        element_type_str = str(element_type) if element_type else None
+        return element_type_str == self.element_type
+
+    def parse(self, element: List[Any]) -> Optional[Dict[str, Any]]:
+        """
+        Parse an S-expression element with error handling.
+
+        This method provides common error handling and validation,
+        then delegates to the specific parse_element implementation.
+        """
+        if not self.can_parse(element):
+            return None
+
+        try:
+            result = self.parse_element(element)
+            if result is not None:
+                self._logger.debug(f"Successfully parsed {self.element_type} element")
+            return result
+        except Exception as e:
+            self._logger.error(f"Failed to parse {self.element_type} element: {e}")
+            return None
+
+    def parse_element(self, element: List[Any]) -> Optional[Dict[str, Any]]:
+        """
+        Parse the specific element type.
+
+        This method should be implemented by subclasses to handle
+        the specific parsing logic for their element type.
+
+        Args:
+            element: S-expression element to parse
+
+        Returns:
+            Parsed element data or None if parsing failed
+
+        Raises:
+            NotImplementedError: If not implemented by subclass
+        """
+        raise NotImplementedError(f"parse_element not implemented for {self.element_type}")
+
+    def _extract_position(self, element: List[Any]) -> Optional[Dict[str, float]]:
+        """
+        Extract position information from common S-expression formats.
+
+        Many KiCAD elements have position info in formats like:
+        (at x y [angle])
+
+        Args:
+            element: S-expression sub-element containing position
+
+        Returns:
+            Dictionary with x, y, and optionally angle, or None if not found
+        """
+        if not isinstance(element, list) or len(element) < 3:
+            return None
+
+        if element[0] != "at":
+            return None
+
+        try:
+            result = {
+                "x": float(element[1]),
+                "y": float(element[2])
+            }
+
+            # Optional angle parameter
+            if len(element) > 3:
+                result["angle"] = float(element[3])
+
+            return result
+        except (ValueError, IndexError):
+            return None
+
+    def _extract_property_list(self, elements: List[Any], property_name: str) -> List[Dict[str, Any]]:
+        """
+        Extract all instances of a property from a list of elements.
+
+        Args:
+            elements: List of S-expression elements
+            property_name: Name of property to extract
+
+        Returns:
+            List of parsed property dictionaries
+        """
+        properties = []
+        for element in elements:
+            if (isinstance(element, list) and
+                len(element) > 0 and
+                element[0] == property_name):
+                prop = self._parse_property_element(element)
+                if prop:
+                    properties.append(prop)
+        return properties
+
+    def _parse_property_element(self, element: List[Any]) -> Optional[Dict[str, Any]]:
+        """
+        Parse a generic property element.
+
+        Override this method in subclasses for property-specific parsing.
+
+        Args:
+            element: S-expression property element
+
+        Returns:
+            Parsed property data or None
+        """
+        if len(element) < 2:
+            return None
+
+        return {
+            "type": element[0],
+            "value": element[1] if len(element) > 1 else None,
+            "raw": element
+        }

kicad_sch_api/parsers/label_parser.py

@@ -0,0 +1,254 @@
+"""
+Label element parser for S-expression label definitions.
+
+Handles parsing of text labels, hierarchical labels, and other text elements.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+import sexpdata
+
+from .base import BaseElementParser
+
+logger = logging.getLogger(__name__)
+
+
+class LabelParser(BaseElementParser):
+    """Parser for label S-expression elements."""
+
+    def __init__(self):
+        """Initialize label parser."""
+        super().__init__("label")
+
+    def parse_element(self, element: List[Any]) -> Optional[Dict[str, Any]]:
+        """
+        Parse a label S-expression element.
+
+        Expected format:
+        (label "text" (at x y angle) (effects (font (size s s))))
+
+        Args:
+            element: Label S-expression element
+
+        Returns:
+            Parsed label data with text, position, and formatting
+        """
+        if len(element) < 2:
+            return None
+
+        label_data = {
+            "text": str(element[1]),
+            "position": {"x": 0, "y": 0, "angle": 0},
+            "effects": {
+                "font_size": 1.27,
+                "font_thickness": 0.15,
+                "bold": False,
+                "italic": False,
+                "hide": False,
+                "justify": []
+            },
+            "uuid": None
+        }
+
+        for elem in element[2:]:
+            if not isinstance(elem, list):
+                continue
+
+            elem_type = str(elem[0]) if isinstance(elem[0], sexpdata.Symbol) else None
+
+            if elem_type == "at":
+                self._parse_position(elem, label_data)
+            elif elem_type == "effects":
+                label_data["effects"] = self._parse_effects(elem)
+            elif elem_type == "uuid":
+                label_data["uuid"] = str(elem[1]) if len(elem) > 1 else None
+
+        return label_data
+
+    def _parse_position(self, at_element: List[Any], label_data: Dict[str, Any]) -> None:
+        """
+        Parse position from at element.
+
+        Args:
+            at_element: (at x y [angle])
+            label_data: Label data dictionary to update
+        """
+        try:
+            if len(at_element) >= 3:
+                label_data["position"]["x"] = float(at_element[1])
+                label_data["position"]["y"] = float(at_element[2])
+            if len(at_element) >= 4:
+                label_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_effects(self, effects_element: List[Any]) -> Dict[str, Any]:
+        """
+        Parse effects element for text formatting.
+
+        Args:
+            effects_element: (effects (font ...) (justify ...) ...)
+
+        Returns:
+            Parsed effects data
+        """
+        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.
+
+        Args:
+            font_element: (font (size w h) (thickness t) ...)
+            effects: Effects dictionary to update
+        """
+        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:
+                            # Usually (size width height), use width for font_size
+                            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
+
+
+class HierarchicalLabelParser(BaseElementParser):
+    """Parser for hierarchical label S-expression elements."""
+
+    def __init__(self):
+        """Initialize hierarchical label parser."""
+        super().__init__("hierarchical_label")
+
+    def parse_element(self, element: List[Any]) -> Optional[Dict[str, Any]]:
+        """
+        Parse a hierarchical label S-expression element.
+
+        Expected format:
+        (hierarchical_label "text" (shape input) (at x y angle) ...)
+
+        Args:
+            element: Hierarchical label S-expression element
+
+        Returns:
+            Parsed hierarchical label data
+        """
+        if len(element) < 2:
+            return None
+
+        label_data = {
+            "text": str(element[1]),
+            "shape": "input",  # Default shape
+            "position": {"x": 0, "y": 0, "angle": 0},
+            "effects": {
+                "font_size": 1.27,
+                "font_thickness": 0.15,
+                "bold": False,
+                "italic": False,
+                "hide": False,
+                "justify": []
+            },
+            "uuid": None
+        }
+
+        for elem in element[2:]:
+            if not isinstance(elem, list):
+                continue
+
+            elem_type = str(elem[0]) if isinstance(elem[0], sexpdata.Symbol) else None
+
+            if elem_type == "shape":
+                label_data["shape"] = str(elem[1]) if len(elem) > 1 else "input"
+            elif elem_type == "at":
+                self._parse_position(elem, label_data)
+            elif elem_type == "effects":
+                label_data["effects"] = self._parse_effects(elem)
+            elif elem_type == "uuid":
+                label_data["uuid"] = str(elem[1]) if len(elem) > 1 else None
+
+        return label_data
+
+    def _parse_position(self, at_element: List[Any], label_data: Dict[str, Any]) -> None:
+        """Parse position from at element."""
+        try:
+            if len(at_element) >= 3:
+                label_data["position"]["x"] = float(at_element[1])
+                label_data["position"]["y"] = float(at_element[2])
+            if len(at_element) >= 4:
+                label_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_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