kicad-sch-api 0.3.0__py3-none-any.whl → 0.5.1__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 .base import BaseElementParser
+from .registry import ElementParserRegistry
+
+__all__ = [
+    "ElementParserRegistry",
+    "BaseElementParser",
+]

kicad_sch_api/parsers/base.py

@@ -0,0 +1,145 @@
+"""
+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/elements/__init__.py

@@ -0,0 +1,22 @@
+"""
+Element-specific parsers for KiCAD schematic elements.
+
+This module contains specialized parsers for different schematic element types,
+extracted from the monolithic parser.py for better maintainability.
+"""
+
+from .graphics_parser import GraphicsParser
+
+# Additional element parsers will be imported here as they are created
+# from .wire_parser import WireParser
+# from .label_parser import LabelParser
+# from .text_parser import TextParser
+# from .sheet_parser import SheetParser
+# from .library_parser import LibraryParser
+# from .symbol_parser import SymbolParser
+# from .metadata_parser import MetadataParser
+
+__all__ = [
+    "GraphicsParser",
+    # Will be populated as parsers are added
+]