kicad-sch-api 0.4.4__tar.gz → 0.4.5__tar.gz

{kicad_sch_api-0.4.4/kicad_sch_api.egg-info → kicad_sch_api-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kicad-sch-api
-Version: 0.4.4
+Version: 0.4.5
 Summary: Professional KiCAD schematic manipulation library with exact format preservation
 Author-email: Circuit-Synth <shane@circuit-synth.com>
 Maintainer-email: Circuit-Synth <shane@circuit-synth.com>

{kicad_sch_api-0.4.4 → kicad_sch_api-0.4.5}/kicad_sch_api/__init__.py

@@ -53,6 +53,12 @@ from .core.config import KiCADConfig, config
 from .core.schematic import Schematic
 from .library.cache import SymbolLibraryCache, get_symbol_cache
 from .utils.validation import ValidationError, ValidationIssue
+# Commonly-used exceptions (ValidationError re-exported from utils for backward compat)
+from .core.exceptions import (
+    KiCadSchError,
+    ElementNotFoundError,
+    DuplicateElementError,
+)
 
 # Version info
 VERSION_INFO = (0, 4, 0)
@@ -69,8 +75,11 @@ __all__ = [
     "KiCADConfig",
     "config",
     # Exceptions
+    "KiCadSchError",
     "ValidationError",
     "ValidationIssue",
+    "ElementNotFoundError",
+    "DuplicateElementError",
     # Version info
     "__version__",
     "VERSION_INFO",

kicad_sch_api-0.4.5/kicad_sch_api/core/__init__.py

@@ -0,0 +1,57 @@
+"""Core kicad-sch-api functionality."""
+
+from .components import Component, ComponentCollection
+from .formatter import ExactFormatter
+from .parser import SExpressionParser
+from .schematic import Schematic, create_schematic, load_schematic
+from .types import Junction, Label, Net, Point, SchematicSymbol, Wire
+# Exception hierarchy
+from .exceptions import (
+    KiCadSchError,
+    ValidationError,
+    ReferenceError,
+    LibraryError,
+    GeometryError,
+    NetError,
+    ParseError,
+    FormatError,
+    CollectionError,
+    ElementNotFoundError,
+    DuplicateElementError,
+    CollectionOperationError,
+    FileOperationError,
+    CLIError,
+    SchematicStateError,
+)
+
+__all__ = [
+    "Schematic",
+    "Component",
+    "ComponentCollection",
+    "Point",
+    "SchematicSymbol",
+    "Wire",
+    "Junction",
+    "Label",
+    "Net",
+    "SExpressionParser",
+    "ExactFormatter",
+    "load_schematic",
+    "create_schematic",
+    # Exceptions
+    "KiCadSchError",
+    "ValidationError",
+    "ReferenceError",
+    "LibraryError",
+    "GeometryError",
+    "NetError",
+    "ParseError",
+    "FormatError",
+    "CollectionError",
+    "ElementNotFoundError",
+    "DuplicateElementError",
+    "CollectionOperationError",
+    "FileOperationError",
+    "CLIError",
+    "SchematicStateError",
+]

kicad_sch_api-0.4.5/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-0.4.4 → kicad_sch_api-0.4.5}/kicad_sch_api/core/managers/__init__.py

@@ -5,6 +5,7 @@ This package contains specialized managers for different aspects of schematic
 manipulation, enabling clean separation of concerns and better maintainability.
 """
 
+from .base import BaseManager
 from .file_io import FileIOManager
 from .format_sync import FormatSyncManager
 from .graphics import GraphicsManager
@@ -15,6 +16,7 @@ from .validation import ValidationManager
 from .wire import WireManager
 
 __all__ = [
+    "BaseManager",
     "FileIOManager",
     "FormatSyncManager",
     "GraphicsManager",

kicad_sch_api-0.4.5/kicad_sch_api/core/managers/base.py

@@ -0,0 +1,76 @@
+"""Base manager class for schematic operations.
+
+Provides a consistent interface for all manager classes and enforces
+common patterns for validation and data access.
+"""
+
+from abc import ABC
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+from ...utils.validation import ValidationIssue
+
+if TYPE_CHECKING:
+    from ..schematic import Schematic
+
+
+class BaseManager(ABC):
+    """Base class for all schematic managers.
+
+    Managers encapsulate complex operations and keep Schematic focused.
+    This base class provides a consistent interface and common utilities
+    for all managers.
+
+    Attributes:
+        _data: Reference to schematic data (optional, varies by manager)
+        _schematic: Reference to parent Schematic instance (optional)
+    """
+
+    def __init__(self, schematic_data: Optional[Dict[str, Any]] = None, **kwargs):
+        """Initialize manager with schematic data reference.
+
+        Args:
+            schematic_data: Reference to schematic data dictionary (optional)
+            **kwargs: Additional manager-specific parameters
+        """
+        self._data = schematic_data
+        self._schematic: Optional["Schematic"] = None
+
+    def set_schematic(self, schematic: "Schematic") -> None:
+        """Set reference to parent schematic.
+
+        This is called by Schematic after manager initialization to establish
+        bidirectional relationship.
+
+        Args:
+            schematic: The parent Schematic instance
+        """
+        self._schematic = schematic
+
+    @property
+    def schematic(self) -> Optional["Schematic"]:
+        """Get the parent schematic instance.
+
+        Returns:
+            The parent Schematic, or None if not set
+        """
+        return self._schematic
+
+    @property
+    def data(self) -> Optional[Dict[str, Any]]:
+        """Get the schematic data dictionary.
+
+        Returns:
+            The schematic data, or None if not set
+        """
+        return self._data
+
+    def validate(self) -> List[ValidationIssue]:
+        """Validate managed elements.
+
+        This is an optional method that managers can override to provide
+        validation. Default implementation returns empty list (no issues).
+
+        Returns:
+            List of validation issues found
+        """
+        return []

{kicad_sch_api-0.4.4 → kicad_sch_api-0.4.5}/kicad_sch_api/core/managers/file_io.py

@@ -14,11 +14,12 @@ from ...utils.validation import ValidationError
 from ..config import config
 from ..formatter import ExactFormatter
 from ..parser import SExpressionParser
+from .base import BaseManager
 
 logger = logging.getLogger(__name__)
 
 
-class FileIOManager:
+class FileIOManager(BaseManager):
     """
     Manages file I/O operations for KiCAD schematics.
 
@@ -31,6 +32,7 @@ class FileIOManager:
 
     def __init__(self):
         """Initialize the FileIOManager."""
+        super().__init__()
         self._parser = SExpressionParser(preserve_format=True)
         self._formatter = ExactFormatter()
 

{kicad_sch_api-0.4.4 → kicad_sch_api-0.4.5}/kicad_sch_api/core/managers/format_sync.py

@@ -11,11 +11,12 @@ from typing import Any, Dict, List, Optional, Set, Union
 
 from ..components import Component
 from ..types import Point, Wire
+from .base import BaseManager
 
 logger = logging.getLogger(__name__)
 
 
-class FormatSyncManager:
+class FormatSyncManager(BaseManager):
     """
     Manages synchronization between object models and S-expression data.
 
@@ -34,7 +35,7 @@ class FormatSyncManager:
         Args:
             schematic_data: Reference to schematic data
         """
-        self._data = schematic_data
+        super().__init__(schematic_data)
         self._dirty_flags: Set[str] = set()
         self._change_log: List[Dict[str, Any]] = []
         self._sync_lock = False

{kicad_sch_api-0.4.4 → kicad_sch_api-0.4.5}/kicad_sch_api/core/managers/graphics.py

@@ -11,11 +11,12 @@ import uuid
 from typing import Any, Dict, List, Optional, Tuple, Union
 
 from ..types import Point
+from .base import BaseManager
 
 logger = logging.getLogger(__name__)
 
 
-class GraphicsManager:
+class GraphicsManager(BaseManager):
     """
     Manages graphic elements and drawing shapes in KiCAD schematics.
 
@@ -34,7 +35,7 @@ class GraphicsManager:
         Args:
             schematic_data: Reference to schematic data
         """
-        self._data = schematic_data
+        super().__init__(schematic_data)
 
     def add_rectangle(
         self,

{kicad_sch_api-0.4.4 → kicad_sch_api-0.4.5}/kicad_sch_api/core/managers/metadata.py

@@ -8,10 +8,12 @@ paper size, title block, version information, and instance sections.
 import logging
 from typing import Any, Dict, List, Optional
 
+from .base import BaseManager
+
 logger = logging.getLogger(__name__)
 
 
-class MetadataManager:
+class MetadataManager(BaseManager):
     """
     Manages schematic metadata and configuration settings.
 
@@ -30,7 +32,7 @@ class MetadataManager:
         Args:
             schematic_data: Reference to schematic data dictionary
         """
-        self._data = schematic_data
+        super().__init__(schematic_data)
 
     def set_paper_size(self, paper: str) -> None:
         """

{kicad_sch_api-0.4.4 → kicad_sch_api-0.4.5}/kicad_sch_api/core/managers/sheet.py

@@ -11,11 +11,12 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple, Union
 
 from ..types import Point
+from .base import BaseManager
 
 logger = logging.getLogger(__name__)
 
 
-class SheetManager:
+class SheetManager(BaseManager):
     """
     Manages hierarchical sheets and multi-sheet project coordination.
 
@@ -34,7 +35,7 @@ class SheetManager:
         Args:
             schematic_data: Reference to schematic data
         """
-        self._data = schematic_data
+        super().__init__(schematic_data)
 
     def add_sheet(
         self,

{kicad_sch_api-0.4.4 → kicad_sch_api-0.4.5}/kicad_sch_api/core/managers/text_elements.py

@@ -11,11 +11,12 @@ import uuid
 from typing import Any, Dict, List, Optional, Tuple, Union
 
 from ..types import Point
+from .base import BaseManager
 
 logger = logging.getLogger(__name__)
 
 
-class TextElementManager:
+class TextElementManager(BaseManager):
     """
     Manages text elements and labeling in KiCAD schematics.
 
@@ -34,7 +35,7 @@ class TextElementManager:
         Args:
             schematic_data: Reference to schematic data
         """
-        self._data = schematic_data
+        super().__init__(schematic_data)
 
     def add_label(
         self,

{kicad_sch_api-0.4.4 → kicad_sch_api-0.4.5}/kicad_sch_api/core/managers/validation.py

@@ -11,11 +11,12 @@ from typing import Any, Dict, List, Optional, Set, Tuple
 
 from ...utils.validation import ValidationError, ValidationIssue
 from ..types import Point
+from .base import BaseManager
 
 logger = logging.getLogger(__name__)
 
 
-class ValidationManager:
+class ValidationManager(BaseManager):
     """
     Comprehensive validation manager for schematic integrity.
 
@@ -39,7 +40,7 @@ class ValidationManager:
             component_collection: Component collection for validation
             wire_collection: Wire collection for connectivity analysis
         """
-        self._data = schematic_data
+        super().__init__(schematic_data)
         self._components = component_collection
         self._wires = wire_collection
         self._validation_rules = self._initialize_validation_rules()

{kicad_sch_api-0.4.4 → kicad_sch_api-0.4.5}/kicad_sch_api/core/managers/wire.py

@@ -12,11 +12,12 @@ from typing import Any, Dict, List, Optional, Tuple, Union
 from ...library.cache import get_symbol_cache
 from ..types import Point, Wire, WireType
 from ..wires import WireCollection
+from .base import BaseManager
 
 logger = logging.getLogger(__name__)
 
 
-class WireManager:
+class WireManager(BaseManager):
     """
     Manages wire operations and pin connectivity in KiCAD schematics.
 
@@ -39,7 +40,7 @@ class WireManager:
             wire_collection: Wire collection for management
             component_collection: Component collection for pin lookups
         """
-        self._data = schematic_data
+        super().__init__(schematic_data)
         self._wires = wire_collection
         self._components = component_collection
         self._symbol_cache = get_symbol_cache()

{kicad_sch_api-0.4.4 → kicad_sch_api-0.4.5}/kicad_sch_api/core/schematic.py

@@ -1216,7 +1216,33 @@ class Schematic:
     # Internal sync methods (migrated from original implementation)
     def _sync_components_to_data(self):
         """Sync component collection state back to data structure."""
-        self._data["components"] = [comp._data.__dict__ for comp in self._components]
+        logger.debug("🔍 _sync_components_to_data: Syncing components to _data")
+
+        components_data = []
+        for comp in self._components:
+            # Start with base component data
+            comp_dict = {k: v for k, v in comp._data.__dict__.items() if not k.startswith('_')}
+
+            # CRITICAL FIX: Explicitly preserve instances if user set them
+            if hasattr(comp._data, 'instances') and comp._data.instances:
+                logger.debug(f"   Component {comp._data.reference} has {len(comp._data.instances)} instance(s)")
+                comp_dict['instances'] = [
+                    {
+                        'project': getattr(inst, 'project', self.name) if hasattr(inst, 'project') else self.name,
+                        'path': inst.path,  # PRESERVE exact path user set!
+                        'reference': inst.reference,
+                        'unit': inst.unit,
+                    }
+                    for inst in comp._data.instances
+                ]
+                logger.debug(f"      Instance paths: {[inst.path for inst in comp._data.instances]}")
+            else:
+                logger.debug(f"   Component {comp._data.reference} has NO instances (will be generated by parser)")
+
+            components_data.append(comp_dict)
+
+        self._data["components"] = components_data
+        logger.debug(f"   Synced {len(components_data)} components to _data")
 
         # Populate lib_symbols with actual symbol definitions used by components
         lib_symbols = {}

{kicad_sch_api-0.4.4 → kicad_sch_api-0.4.5}/kicad_sch_api/core/types.py

@@ -171,6 +171,7 @@ class SchematicSymbol:
     in_bom: bool = True
     on_board: bool = True
     unit: int = 1
+    instances: List["SymbolInstance"] = field(default_factory=list)  # FIX: Add instances field for hierarchical support
 
     def __post_init__(self) -> None:
         # Generate UUID if not provided