kicad-sch-api 0.4.4__py3-none-any.whl → 0.4.5__py3-none-any.whl

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/core/__init__.py

@@ -5,6 +5,24 @@ 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",
@@ -20,4 +38,20 @@ __all__ = [
     "ExactFormatter",
     "load_schematic",
     "create_schematic",
+    # Exceptions
+    "KiCadSchError",
+    "ValidationError",
+    "ReferenceError",
+    "LibraryError",
+    "GeometryError",
+    "NetError",
+    "ParseError",
+    "FormatError",
+    "CollectionError",
+    "ElementNotFoundError",
+    "DuplicateElementError",
+    "CollectionOperationError",
+    "FileOperationError",
+    "CLIError",
+    "SchematicStateError",
 ]

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/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/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/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/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/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/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/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/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/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/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/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/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

kicad_sch_api/parsers/elements/symbol_parser.py

@@ -184,53 +184,83 @@ class SymbolParser(BaseElementParser):
         # Add instances section (required by KiCAD)
         from ...core.config import config
 
-        # Get project name from config or properties
-        project_name = symbol_data.get("properties", {}).get("project_name")
-        if not project_name:
-            project_name = getattr(self, "project_name", config.defaults.project_name)
-
-        # CRITICAL FIX: Use the FULL hierarchy_path from properties if available
-        # For hierarchical schematics, this contains the complete path: /root_uuid/sheet_symbol_uuid/...
-        # This ensures KiCad can properly annotate components in sub-sheets
-        hierarchy_path = symbol_data.get("properties", {}).get("hierarchy_path")
-        if hierarchy_path:
-            # Use the full hierarchical path (includes root + all sheet symbols)
-            instance_path = hierarchy_path
-            logger.debug(
-                f"🔧 Using FULL hierarchy_path: {instance_path} for component {symbol_data.get('reference', 'unknown')}"
-            )
+        # HIERARCHICAL FIX: Check if user explicitly set instances
+        # If so, preserve them exactly as-is (don't generate!)
+        user_instances = symbol_data.get("instances")
+        if user_instances:
+            logger.debug(f"🔍 HIERARCHICAL FIX: Component {symbol_data.get('reference')} has {len(user_instances)} user-set instance(s)")
+            # Build instances sexp from user data
+            instances_sexp = [sexpdata.Symbol("instances")]
+            for inst in user_instances:
+                project = inst.get('project', getattr(self, 'project_name', 'circuit'))
+                path = inst.get('path', '/')
+                reference = inst.get('reference', symbol_data.get('reference', 'U?'))
+                unit = inst.get('unit', 1)
+
+                logger.debug(f"   Instance: project={project}, path={path}, ref={reference}, unit={unit}")
+
+                instances_sexp.append([
+                    sexpdata.Symbol("project"),
+                    project,
+                    [
+                        sexpdata.Symbol("path"),
+                        path,  # PRESERVE user-set hierarchical path!
+                        [sexpdata.Symbol("reference"), reference],
+                        [sexpdata.Symbol("unit"), unit],
+                    ],
+                ])
+            sexp.append(instances_sexp)
         else:
-            # Fallback: use root_uuid or schematic_uuid for flat designs
-            root_uuid = (
-                symbol_data.get("properties", {}).get("root_uuid")
-                or schematic_uuid
-                or str(uuid.uuid4())
-            )
-            instance_path = f"/{root_uuid}"
+            # No user-set instances - generate default (backward compatibility)
+            logger.debug(f"🔍 HIERARCHICAL FIX: Component {symbol_data.get('reference')} has NO user instances, generating default")
+
+            # Get project name from config or properties
+            project_name = symbol_data.get("properties", {}).get("project_name")
+            if not project_name:
+                project_name = getattr(self, "project_name", config.defaults.project_name)
+
+            # CRITICAL FIX: Use the FULL hierarchy_path from properties if available
+            # For hierarchical schematics, this contains the complete path: /root_uuid/sheet_symbol_uuid/...
+            # This ensures KiCad can properly annotate components in sub-sheets
+            hierarchy_path = symbol_data.get("properties", {}).get("hierarchy_path")
+            if hierarchy_path:
+                # Use the full hierarchical path (includes root + all sheet symbols)
+                instance_path = hierarchy_path
+                logger.debug(
+                    f"🔧 Using FULL hierarchy_path: {instance_path} for component {symbol_data.get('reference', 'unknown')}"
+                )
+            else:
+                # Fallback: use root_uuid or schematic_uuid for flat designs
+                root_uuid = (
+                    symbol_data.get("properties", {}).get("root_uuid")
+                    or schematic_uuid
+                    or str(uuid.uuid4())
+                )
+                instance_path = f"/{root_uuid}"
+                logger.debug(
+                    f"🔧 Using root UUID path: {instance_path} for component {symbol_data.get('reference', 'unknown')}"
+                )
+
             logger.debug(
-                f"🔧 Using root UUID path: {instance_path} for component {symbol_data.get('reference', 'unknown')}"
+                f"🔧 Component properties keys: {list(symbol_data.get('properties', {}).keys())}"
             )
+            logger.debug(f"🔧 Using project name: '{project_name}'")
 
-        logger.debug(
-            f"🔧 Component properties keys: {list(symbol_data.get('properties', {}).keys())}"
-        )
-        logger.debug(f"🔧 Using project name: '{project_name}'")
-
-        sexp.append(
-            [
-                sexpdata.Symbol("instances"),
+            sexp.append(
                 [
-                    sexpdata.Symbol("project"),
-                    project_name,
+                    sexpdata.Symbol("instances"),
                     [
-                        sexpdata.Symbol("path"),
-                        instance_path,
-                        [sexpdata.Symbol("reference"), symbol_data.get("reference", "U?")],
-                        [sexpdata.Symbol("unit"), symbol_data.get("unit", 1)],
+                        sexpdata.Symbol("project"),
+                        project_name,
+                        [
+                            sexpdata.Symbol("path"),
+                            instance_path,
+                            [sexpdata.Symbol("reference"), symbol_data.get("reference", "U?")],
+                            [sexpdata.Symbol("unit"), symbol_data.get("unit", 1)],
+                        ],
                     ],
-                ],
-            ]
-        )
+                ]
+            )
 
         return sexp
 

kicad_sch_api/utils/validation.py

@@ -11,8 +11,21 @@ from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Dict, List, Optional, Set, Union
 
+# Import ValidationError from new exception hierarchy for backward compatibility
+from ..core.exceptions import ValidationError
+
 logger = logging.getLogger(__name__)
 
+# Export list for public API
+__all__ = [
+    'ValidationError',
+    'ValidationIssue',
+    'ValidationLevel',
+    'SchematicValidator',
+    'validate_schematic_file',
+    'collect_validation_errors',
+]
+
 
 class ValidationLevel(Enum):
     """Validation issue severity levels."""
@@ -43,28 +56,9 @@ class ValidationIssue:
         return f"{self.level.value.upper()}: {self.category}: {self.message}{context_str}{suggestion_str}"
 
 
-class ValidationError(Exception):
-    """Exception raised when critical validation errors are found."""
-
-    def __init__(self, message: str, issues: List[ValidationIssue] = None):
-        super().__init__(message)
-        self.issues = issues or []
-
-    def add_issue(self, issue: ValidationIssue):
-        """Add a validation issue to this error."""
-        self.issues.append(issue)
-
-    def get_errors(self) -> List[ValidationIssue]:
-        """Get only error-level issues."""
-        return [
-            issue
-            for issue in self.issues
-            if issue.level in (ValidationLevel.ERROR, ValidationLevel.CRITICAL)
-        ]
-
-    def get_warnings(self) -> List[ValidationIssue]:
-        """Get only warning-level issues."""
-        return [issue for issue in self.issues if issue.level == ValidationLevel.WARNING]
+# ValidationError is now imported from core.exceptions (see imports at top)
+# This provides backward compatibility for existing code while using the new
+# exception hierarchy
 
 
 class SchematicValidator:

kicad_sch_api/wrappers/__init__.py

@@ -0,0 +1,14 @@
+"""
+Wrapper classes for schematic elements.
+
+Provides enhanced element access with validation, parent tracking,
+and automatic change notification.
+"""
+
+from .base import ElementWrapper
+from .wire import WireWrapper
+
+__all__ = [
+    "ElementWrapper",
+    "WireWrapper",
+]

kicad_sch_api/wrappers/base.py

@@ -0,0 +1,89 @@
+"""Base wrapper class for schematic elements."""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Generic, Optional, TypeVar
+
+if TYPE_CHECKING:
+    from ..collections.base import IndexedCollection
+
+# Type variable for the wrapped data type
+T = TypeVar("T")
+
+
+class ElementWrapper(ABC, Generic[T]):
+    """Base class for all schematic element wrappers.
+
+    Wrappers enhance raw dataclasses with:
+    - Validation on property setters
+    - Parent collection tracking for automatic index updates
+    - Convenient methods and computed properties
+    - Consistent API across different element types
+    """
+
+    def __init__(self, data: T, parent_collection: Optional["IndexedCollection[Any]"]):
+        """Initialize the wrapper.
+
+        Args:
+            data: The underlying dataclass instance
+            parent_collection: The collection this element belongs to (can be None)
+        """
+        self._data = data
+        self._collection = parent_collection
+
+    @property
+    def data(self) -> T:
+        """Get the underlying data object.
+
+        Returns:
+            The wrapped dataclass instance
+        """
+        return self._data
+
+    @property
+    @abstractmethod
+    def uuid(self) -> str:
+        """Get the UUID of the element.
+
+        Returns:
+            UUID string
+        """
+        pass
+
+    def __eq__(self, other: object) -> bool:
+        """Compare wrappers by UUID.
+
+        Args:
+            other: Another wrapper to compare with
+
+        Returns:
+            True if UUIDs match
+        """
+        if not isinstance(other, ElementWrapper):
+            return False
+        return self.uuid == other.uuid
+
+    def __hash__(self) -> int:
+        """Hash wrapper by UUID.
+
+        Returns:
+            Hash of UUID
+        """
+        return hash(self.uuid)
+
+    def __repr__(self) -> str:
+        """Get string representation of wrapper.
+
+        Returns:
+            String representation
+        """
+        return f"{self.__class__.__name__}({self._data})"
+
+    def _mark_modified(self) -> None:
+        """Mark the parent collection as modified."""
+        if self._collection is not None:
+            self._collection._mark_modified()
+
+    def _invalidate_indexes(self) -> None:
+        """Invalidate parent collection indexes."""
+        if self._collection is not None:
+            self._collection._dirty_indexes = True

kicad_sch_api/wrappers/wire.py

@@ -0,0 +1,198 @@
+"""Wire wrapper class for enhanced wire manipulation."""
+
+from typing import TYPE_CHECKING, List, Optional
+
+from ..core.types import Point, Wire, WireType
+from .base import ElementWrapper
+
+if TYPE_CHECKING:
+    from ..collections.wires import WireCollection
+
+
+class WireWrapper(ElementWrapper[Wire]):
+    """Enhanced wrapper for Wire with validation and parent tracking.
+
+    Provides:
+    - Validation on property setters (e.g., minimum 2 points for wires)
+    - Automatic parent collection notification on changes
+    - Convenient access to wire properties
+    - Type-safe operations
+    """
+
+    def __init__(self, wire: Wire, parent_collection: Optional["WireCollection"] = None):
+        """Initialize wire wrapper.
+
+        Args:
+            wire: The underlying Wire dataclass
+            parent_collection: Parent collection for modification tracking (optional)
+        """
+        super().__init__(wire, parent_collection)
+
+    @property
+    def uuid(self) -> str:
+        """Get wire UUID.
+
+        Returns:
+            Wire UUID string
+        """
+        return self._data.uuid
+
+    @property
+    def points(self) -> List[Point]:
+        """Get wire points.
+
+        Returns:
+            List of Point objects defining the wire path
+        """
+        return self._data.points
+
+    @points.setter
+    def points(self, value: List[Point]) -> None:
+        """Set wire points with validation.
+
+        Args:
+            value: List of points (must have at least 2 points)
+
+        Raises:
+            ValueError: If less than 2 points provided
+        """
+        if len(value) < 2:
+            raise ValueError("Wire must have at least 2 points")
+
+        # Create new Wire with updated points
+        self._data = Wire(
+            uuid=self._data.uuid,
+            points=value,
+            wire_type=self._data.wire_type,
+            stroke_width=self._data.stroke_width,
+            stroke_type=self._data.stroke_type,
+        )
+        self._mark_modified()
+
+    @property
+    def start(self) -> Point:
+        """Get start point (first point of wire).
+
+        Returns:
+            First point in the wire path
+        """
+        return self._data.points[0]
+
+    @property
+    def end(self) -> Point:
+        """Get end point (last point of wire).
+
+        Returns:
+            Last point in the wire path
+        """
+        return self._data.points[-1]
+
+    @property
+    def wire_type(self) -> WireType:
+        """Get wire type (WIRE or BUS).
+
+        Returns:
+            WireType enum value
+        """
+        return self._data.wire_type
+
+    @wire_type.setter
+    def wire_type(self, value: WireType) -> None:
+        """Set wire type.
+
+        Args:
+            value: WireType enum value (WIRE or BUS)
+        """
+        self._data = Wire(
+            uuid=self._data.uuid,
+            points=self._data.points,
+            wire_type=value,
+            stroke_width=self._data.stroke_width,
+            stroke_type=self._data.stroke_type,
+        )
+        self._mark_modified()
+
+    @property
+    def stroke_width(self) -> float:
+        """Get stroke width.
+
+        Returns:
+            Stroke width in mm
+        """
+        return self._data.stroke_width
+
+    @stroke_width.setter
+    def stroke_width(self, value: float) -> None:
+        """Set stroke width.
+
+        Args:
+            value: Stroke width in mm
+        """
+        self._data = Wire(
+            uuid=self._data.uuid,
+            points=self._data.points,
+            wire_type=self._data.wire_type,
+            stroke_width=value,
+            stroke_type=self._data.stroke_type,
+        )
+        self._mark_modified()
+
+    @property
+    def stroke_type(self) -> str:
+        """Get stroke type.
+
+        Returns:
+            Stroke type string
+        """
+        return self._data.stroke_type
+
+    @stroke_type.setter
+    def stroke_type(self, value: str) -> None:
+        """Set stroke type.
+
+        Args:
+            value: Stroke type string
+        """
+        self._data = Wire(
+            uuid=self._data.uuid,
+            points=self._data.points,
+            wire_type=self._data.wire_type,
+            stroke_width=self._data.stroke_width,
+            stroke_type=value,
+        )
+        self._mark_modified()
+
+    # Delegate methods to underlying Wire dataclass
+
+    @property
+    def length(self) -> float:
+        """Get total wire length.
+
+        Returns:
+            Total length of all wire segments in mm
+        """
+        return self._data.length
+
+    def is_simple(self) -> bool:
+        """Check if wire is a simple 2-point wire.
+
+        Returns:
+            True if wire has exactly 2 points, False otherwise
+        """
+        return self._data.is_simple()
+
+    def is_horizontal(self) -> bool:
+        """Check if wire is horizontal (delegates to Wire).
+
+        Returns:
+            True if wire is horizontal
+        """
+        return self._data.is_horizontal()
+
+    def is_vertical(self) -> bool:
+        """Check if wire is vertical (delegates to Wire).
+
+        Returns:
+            True if wire is vertical
+        """
+        return self._data.is_vertical()

{kicad_sch_api-0.4.4.dist-info → kicad_sch_api-0.4.5.dist-info}/METADATA

@@ -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.dist-info → kicad_sch_api-0.4.5.dist-info}/RECORD

@@ -1,4 +1,4 @@
-kicad_sch_api/__init__.py,sha256=RqnJXbVVuA10zIozkuqnqv42nWBF-opcjChSAPne6nw,2919
+kicad_sch_api/__init__.py,sha256=BK1u1-hOS-wEXOchr4Gvz62HMSMXj1QCgCf1gsKMXtM,3190
 kicad_sch_api/cli.py,sha256=ZzmwzfHEvPgGfCiQBU4G2LBAyRtMNiBRoY21pivJSYc,7621
 kicad_sch_api/py.typed,sha256=e4ldqxwpY7pNDG1olbvj4HSKr8sZ9vxgA_2ek8xXn-Q,70
 kicad_sch_api/cli/__init__.py,sha256=mflSYoGLMJw2EFEByw9GD79pgj_Hebi6htJy7cKV5qM,952
@@ -14,10 +14,11 @@ kicad_sch_api/collections/components.py,sha256=ofH3P38Ube3uxVvk_28gJwJPsdL6KA37r
 kicad_sch_api/collections/junctions.py,sha256=4bjuUKm-tCWSJJTtuPwgjYh0Xglg2SEG8IOAvhULgtg,11728
 kicad_sch_api/collections/labels.py,sha256=zg6_xe4ifwIbc8M1E5MDGTh8Ps57oBeqbS9MclrvxKU,12266
 kicad_sch_api/collections/wires.py,sha256=o2Y_KIwOmFMytdOc2MjgnoUrK4Woj7wR9ROj4uRTuY0,12394
-kicad_sch_api/core/__init__.py,sha256=ur_KeYBlGKl-e1hLpLdxAhGV2A-PCCGkcqd0r6KSeBA,566
+kicad_sch_api/core/__init__.py,sha256=YsNGh03VpriQbLIv6CLDey8NzTgwm3FeOvJVKd9K9T8,1285
 kicad_sch_api/core/component_bounds.py,sha256=Qc-Fazq_RvASVZ57eGg99NahCIgnWq8FFg1J4HfggK0,17917
 kicad_sch_api/core/components.py,sha256=powrqJGgqUBvMevMwhWSobrK6n8W525H7vzpPYCUXTs,28448
 kicad_sch_api/core/config.py,sha256=ECR6WLrC8i0itxRLJAZN3TDthbtOfd5NwNbiU6TSlW4,6224
+kicad_sch_api/core/exceptions.py,sha256=ceV6nKbxk4BjQAS-recAI7yNyiqyvtdnJoDePPuU2ek,4694
 kicad_sch_api/core/formatter.py,sha256=ci-URhZFVHdSV4rEfOgTGtJu1tvW5MZEzSI1j2vtexE,22910
 kicad_sch_api/core/geometry.py,sha256=27SgN0padLbQuTi8MV6UUCp6Pyaiv8V9gmYDOhfwny8,2947
 kicad_sch_api/core/ic_manager.py,sha256=Kg0HIOMU-TGXiIkrnwcHFQ1Kfv_3rW2U1cwBKJsKopc,7219
@@ -28,23 +29,24 @@ kicad_sch_api/core/no_connects.py,sha256=6HCXzdVO124AdUUsQbCv9Y0f7KWmObkQ4OZLimY
 kicad_sch_api/core/parser.py,sha256=uvFVdSVzv5-RZmD_OKnqm51DIatFfsKF7NzLcWx4gfg,28761
 kicad_sch_api/core/parsing_utils.py,sha256=tqQpuiNePNRx6Izsp9pnCBtlgiEYfMPkVFjkE5Uuofg,1776
 kicad_sch_api/core/pin_utils.py,sha256=XGEow3HzBTyT8a0B_ZC8foMvwzYaENSaqTUwDW1rz24,5417
-kicad_sch_api/core/schematic.py,sha256=W3URcKzjUrsTy3MfDejGuhuLmV2WM2YmFnGTihzGgt0,56489
+kicad_sch_api/core/schematic.py,sha256=C6ujNEdftSmcpRhhGRg_g9IdY0gbYMHztczigy-z8L4,57816
 kicad_sch_api/core/texts.py,sha256=kBwUxwftqncl-yauiJjdnLXauV6EWq2oLhKw2bAxD_c,9990
-kicad_sch_api/core/types.py,sha256=Rx3Q9PTmzP2RYEJhnb3bw0Gs2N1Gvn27KOPtqTph0hU,15853
+kicad_sch_api/core/types.py,sha256=SQNvl4JLxgHYht7c3W4jsCll99OdkptURyMjBhWyg-8,15974
 kicad_sch_api/core/wires.py,sha256=lLqcpRodErD4fD4_VMB1HgC9ViPnYPGcT8b-N9S0q-g,7139
 kicad_sch_api/core/collections/__init__.py,sha256=i75_p9v330S2hxi4LrAGLmcVjrF8O0nTlGjCCjNbkq0,118
 kicad_sch_api/core/collections/base.py,sha256=H-g1SC7hKD5QvbXPKVQotCK2e5pn04-y1ipkBQGcy3I,7076
 kicad_sch_api/core/factories/__init__.py,sha256=qFx_rAgcTgWRZ572hvzzKNAze-jE0BOLqLrSFzj7T6M,130
 kicad_sch_api/core/factories/element_factory.py,sha256=zUmV1dnMXJl3fxXHdU9OJhqsHf_0D_DBOzWRLFYdG0c,8059
-kicad_sch_api/core/managers/__init__.py,sha256=Ec9H9RSBFt2MeJIhnZFUN9sa2ql0BSrO8FNOa1XsXeU,731
-kicad_sch_api/core/managers/file_io.py,sha256=k7yAfOvS5SqHrn1bCOH_wmOqDQnQe25wvhSPDmI8Cjk,7670
-kicad_sch_api/core/managers/format_sync.py,sha256=ar0FfhwXrU2l5ATV0aW5KtVRfIM2iM1WoyGvXQh-ShY,16963
-kicad_sch_api/core/managers/graphics.py,sha256=-jd-JL1TOuDntNEQcSeJ56Ccrkuudmj1dJkRtLUtRog,18370
-kicad_sch_api/core/managers/metadata.py,sha256=9oJK8UgnzpjDwZ-46I1eW3_P9ZoJsDvutEsgROFmTwc,8004
-kicad_sch_api/core/managers/sheet.py,sha256=jnnEBon0QmMh22-Ls7ZP5A_4FxM7bCyaJOF9AzZT1Kg,14816
-kicad_sch_api/core/managers/text_elements.py,sha256=utZIg488x9NLQID6ALbOcI0ZM2PfvgADVJ1jcbGP9jk,17319
-kicad_sch_api/core/managers/validation.py,sha256=-ZP_9odFsBmFG4CkNc00ZJq6bm_VtyjJHYDkMDku3l4,15757
-kicad_sch_api/core/managers/wire.py,sha256=WZSycnkI7CCBTsYKai7TPBULXi0gs2XE1Xxs-d87IfU,12027
+kicad_sch_api/core/managers/__init__.py,sha256=bofU_wrxSOU08dPxKlXMa9BNp_x7_O-hbrVo7JytLxo,780
+kicad_sch_api/core/managers/base.py,sha256=xLKP3Y_sImUA9EdsH0xwjT3dst6tIoh4vFk1ZzDpg18,2275
+kicad_sch_api/core/managers/file_io.py,sha256=4Ne9uRuEbGdBcKojkROxhVvbB4dPM_Luh-5JhZqkTPk,7740
+kicad_sch_api/core/managers/format_sync.py,sha256=SEOU9Ppv-0V5-4kA1MR1Haz04TYuMu-OmUpmfc6uWcY,17011
+kicad_sch_api/core/managers/graphics.py,sha256=TKffEW9IKXztSfDLassRGHiV8qBr8MYe3Hf6zhLI7Ww,18418
+kicad_sch_api/core/managers/metadata.py,sha256=pqIINUbaJACEmVfUruTUekN8mFra0uHbWz7_VPdBRy0,8053
+kicad_sch_api/core/managers/sheet.py,sha256=5rRY4xC5oCk4wMRyOFD6DH904-X7g-LUYt9sRXaJNls,14864
+kicad_sch_api/core/managers/text_elements.py,sha256=vqBsj6zkE7139xLUk2vDinMm2Jq42cqOh2ZzU_B6_ns,17367
+kicad_sch_api/core/managers/validation.py,sha256=n4bj6h6yTOuWrTQH8PIhzH1l84brxKPVzd1fJitDZWU,15805
+kicad_sch_api/core/managers/wire.py,sha256=dfviwrg-LHSp0jMevjXVQqyhhynBHh6g-f7DqqCACQw,12075
 kicad_sch_api/discovery/__init__.py,sha256=qSuCsnC-hVtaLYE8fwd-Gea6JKwEVGPQ-hSNDNJYsIU,329
 kicad_sch_api/discovery/search_index.py,sha256=KgQT8ipT9OU6ktUwhDZ37Mao0Cba0fJOsxUk9m8ZKbY,15856
 kicad_sch_api/geometry/__init__.py,sha256=hTBXkn8mZZCjzDIrtPv67QsnCYB77L67JjthQgEIX7o,716
@@ -66,7 +68,7 @@ kicad_sch_api/parsers/elements/label_parser.py,sha256=KL_AV_-BhA_KV1FLlqNpMj1Nu-
 kicad_sch_api/parsers/elements/library_parser.py,sha256=qHQMI3PatLgHtUWvWhQxbKC-NXJqgOVW33hVkMQ9sEU,6321
 kicad_sch_api/parsers/elements/metadata_parser.py,sha256=IFpgk5eLqp1kcjhpZB-jPThBCVyvdgsLo4YRydlvYD4,1897
 kicad_sch_api/parsers/elements/sheet_parser.py,sha256=xZld-yzW7r1FKABaK89K7U-Zenqz2cHUqtMnADhxCeQ,14246
-kicad_sch_api/parsers/elements/symbol_parser.py,sha256=G_N1kbTY2kCBG08gBHuXtmsFcw_dWMzwmVxOaO7F3Gw,12433
+kicad_sch_api/parsers/elements/symbol_parser.py,sha256=9eidmBsL0fC3DPXHBCnWiyYnDRsB8hzlx-zHdS4PaMs,14175
 kicad_sch_api/parsers/elements/text_parser.py,sha256=n5G_3czchmPCEdvTVoQsATTW1PQW7KcSjzglqzPlOKQ,9820
 kicad_sch_api/parsers/elements/wire_parser.py,sha256=geWI3jMXM7lZF26k7n7c6RQ55x4gsO4j8Ou0fk0O2j8,8271
 kicad_sch_api/symbols/__init__.py,sha256=NfakJ5-8AQxq5vi8nZVuaUtDpWHfwHm5AD4rC-p9BZI,501
@@ -74,15 +76,18 @@ kicad_sch_api/symbols/cache.py,sha256=pKFjmuyId-9gGPAue-1Rzy4MRsecoC4TMn0hn2n0Yq
 kicad_sch_api/symbols/resolver.py,sha256=w0jqepp9RwWqlwQHX28FpTn1aSz8iOf7kcJUOBMHwqE,12074
 kicad_sch_api/symbols/validators.py,sha256=5Ryt4rLHxDF3ALViaNLRrI3pYvOreVT51gpvhECTZms,17216
 kicad_sch_api/utils/__init__.py,sha256=1V_yGgI7jro6MUc4Pviux_WIeJ1wmiYFID186SZwWLQ,277
-kicad_sch_api/utils/validation.py,sha256=XlWGRZJb3cOPYpU9sLQQgC_NASwbi6W-LCN7PzUmaPY,15626
+kicad_sch_api/utils/validation.py,sha256=xszXVD9a1x5TuAq-X8h1djVBOTuFs7AnHzGcnTSikUI,15300
 kicad_sch_api/validation/__init__.py,sha256=YZ2KDTpBN9BloD7I__gsw6IiW-g5tZPux0kgyXb3TjU,524
 kicad_sch_api/validation/erc.py,sha256=6WMHyMakKpn1-jXkfO9ltayLRA0OaU1N7GQm-pbZTLg,5160
 kicad_sch_api/validation/erc_models.py,sha256=wFYMH-cbcdRX1j9LPn28IGUYBLioPDr4lP0m2QuhAnI,6628
 kicad_sch_api/validation/pin_matrix.py,sha256=AdBCvEmOByXACOUoskYxYMcwKvIasxrtJOqWM-WgVi0,7456
 kicad_sch_api/validation/validators.py,sha256=3txkQpR3qAUzp0-m-FnDYf3-_GGj6iaGZj4kSYu-Fe4,13166
-kicad_sch_api-0.4.4.dist-info/licenses/LICENSE,sha256=Em65Nvte1G9MHc0rHqtYuGkCPcshD588itTa358J6gs,1070
-kicad_sch_api-0.4.4.dist-info/METADATA,sha256=JlL-yhkt577MRogTnhRj441fplcHMNrejWxKDOksXq4,17953
-kicad_sch_api-0.4.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kicad_sch_api-0.4.4.dist-info/entry_points.txt,sha256=VWKsFi2Jv7G_tmio3cNVhhIBfv_OZFaKa-T_ED84lc8,57
-kicad_sch_api-0.4.4.dist-info/top_level.txt,sha256=n0ex4gOJ1b_fARowcGqRzyOGZcHRhc5LZa6_vVgGxcI,14
-kicad_sch_api-0.4.4.dist-info/RECORD,,
+kicad_sch_api/wrappers/__init__.py,sha256=Leu_fgWwyeKMfqKv5K4nYbzaIQD5T8-u6HXTMq7Ccr8,271
+kicad_sch_api/wrappers/base.py,sha256=VZlfyRBrhGXtgg7RbZYpIRKRYRBR8j4uiaXfcP8TgKM,2386
+kicad_sch_api/wrappers/wire.py,sha256=cK3zkQJdujRQ_jKYU1Jxai7alhrVwzeHzgcnl4KTvi8,5102
+kicad_sch_api-0.4.5.dist-info/licenses/LICENSE,sha256=Em65Nvte1G9MHc0rHqtYuGkCPcshD588itTa358J6gs,1070
+kicad_sch_api-0.4.5.dist-info/METADATA,sha256=KVxIh6lOV00hCMUAINehj1GFrIg-52iYBwInBAqx3jY,17953
+kicad_sch_api-0.4.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kicad_sch_api-0.4.5.dist-info/entry_points.txt,sha256=VWKsFi2Jv7G_tmio3cNVhhIBfv_OZFaKa-T_ED84lc8,57
+kicad_sch_api-0.4.5.dist-info/top_level.txt,sha256=n0ex4gOJ1b_fARowcGqRzyOGZcHRhc5LZa6_vVgGxcI,14
+kicad_sch_api-0.4.5.dist-info/RECORD,,