kicad-sch-api 0.4.1__py3-none-any.whl → 0.5.1__py3-none-any.whl

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/factories/element_factory.py

@@ -126,7 +126,7 @@ class ElementFactory:
             uuid=label_dict.get("uuid", str(uuid.uuid4())),
             position=pos,
             text=label_dict.get("text", ""),
-            label_type=LabelType(label_dict.get("label_type", "local")),
+            label_type=LabelType(label_dict.get("label_type", "label")),
             rotation=label_dict.get("rotation", 0.0),
             size=label_dict.get("size", 1.27),
             shape=(
@@ -134,6 +134,8 @@ class ElementFactory:
                 if label_dict.get("shape")
                 else None
             ),
+            justify_h=label_dict.get("justify_h", "left"),
+            justify_v=label_dict.get("justify_v", "bottom"),
         )
 
     @staticmethod

kicad_sch_api/core/formatter.py

@@ -125,6 +125,10 @@ class ExactFormatter:
         self.rules["global_label"] = FormatRule(inline=False, quote_indices={1})
         self.rules["hierarchical_label"] = FormatRule(inline=False, quote_indices={1})
 
+        # Text elements
+        self.rules["text"] = FormatRule(inline=False, quote_indices={1})
+        self.rules["text_box"] = FormatRule(inline=False, quote_indices={1})
+
         # Effects and text formatting
         self.rules["effects"] = FormatRule(inline=False)
         self.rules["font"] = FormatRule(inline=False)
@@ -279,6 +283,8 @@ class ExactFormatter:
             "junction",
             "label",
             "hierarchical_label",
+            "text",
+            "text_box",
             "polyline",
             "rectangle",
         ):
@@ -384,7 +390,8 @@ class ExactFormatter:
                 result += f"\n{next_indent}{self._format_element(element, indent_level + 1)}"
             else:
                 if i in rule.quote_indices and isinstance(element, str):
-                    result += f' "{element}"'
+                    escaped_element = self._escape_string(element)
+                    result += f' "{escaped_element}"'
                 else:
                     result += f" {self._format_element(element, 0)}"
 
@@ -396,7 +403,8 @@ class ExactFormatter:
         indent = "\t" * indent_level
         next_indent = "\t" * (indent_level + 1)
 
-        result = f"({lst[0]}"
+        tag = str(lst[0])
+        result = f"({tag}"
 
         for i, element in enumerate(lst[1:], 1):
             if isinstance(element, list):
@@ -425,9 +433,18 @@ class ExactFormatter:
         return True
 
     def _escape_string(self, text: str) -> str:
-        """Escape quotes in string for S-expression formatting."""
-        # Replace double quotes with escaped quotes
-        return text.replace('"', '\\"')
+        """Escape special characters in string for S-expression formatting."""
+        # Escape backslashes first (must be done before other replacements)
+        text = text.replace('\\', '\\\\')
+        # Escape double quotes
+        text = text.replace('"', '\\"')
+        # Escape newlines (convert actual newlines to escaped representation)
+        text = text.replace('\n', '\\n')
+        # Escape carriage returns
+        text = text.replace('\r', '\\r')
+        # Escape tabs
+        text = text.replace('\t', '\\t')
+        return text
 
     def _needs_quoting(self, text: str) -> bool:
         """Check if string needs to be quoted."""
@@ -466,8 +483,8 @@ class ExactFormatter:
             for item in lst[1:]:
                 if isinstance(item, list) and len(item) >= 1:
                     tag = str(item[0])
-                    if tag in ["version", "generator", "generator_version"] and len(item) >= 2:
-                        if tag in ["generator", "generator_version"]:
+                    if tag in ["version", "generator", "generator_version", "uuid"] and len(item) >= 2:
+                        if tag in ["generator", "generator_version", "uuid"]:
                             header_parts.append(f'({tag} "{item[1]}")')
                         else:
                             header_parts.append(f"({tag} {item[1]})")

kicad_sch_api/core/geometry.py

@@ -7,7 +7,7 @@ migrated from circuit-synth for improved maintainability.
 
 import logging
 import math
-from typing import Optional, Tuple
+from typing import Optional, Tuple, Union
 
 from .types import Point
 
@@ -71,20 +71,29 @@ def apply_transformation(
 
     Migrated from circuit-synth for accurate pin position calculation.
 
+    CRITICAL: Symbol coordinates use normal Y-axis (+Y is up), but schematic
+    coordinates use inverted Y-axis (+Y is down). We must negate Y from symbol
+    space before applying transformations.
+
     Args:
-        point: Point to transform (x, y) relative to origin
-        origin: Component origin point
+        point: Point to transform (x, y) relative to origin in SYMBOL space
+        origin: Component origin point in SCHEMATIC space
         rotation: Rotation in degrees (0, 90, 180, 270)
         mirror: Mirror axis ("x" or "y" or None)
 
     Returns:
-        Transformed absolute position (x, y)
+        Transformed absolute position (x, y) in SCHEMATIC space
     """
     x, y = point
 
     logger.debug(f"Transforming point ({x}, {y}) with rotation={rotation}°, mirror={mirror}")
 
-    # Apply mirroring first
+    # CRITICAL: Negate Y to convert from symbol space (normal Y) to schematic space (inverted Y)
+    # This must happen BEFORE rotation/mirroring
+    y = -y
+    logger.debug(f"After Y-axis inversion (symbol→schematic): ({x}, {y})")
+
+    # Apply mirroring
     if mirror == "x":
         x = -x
         logger.debug(f"After X mirror: ({x}, {y})")
@@ -109,3 +118,83 @@ def apply_transformation(
 
     logger.debug(f"Final absolute position: ({final_x}, {final_y})")
     return (final_x, final_y)
+
+
+def calculate_position_for_pin(
+    pin_local_position: Union[Point, Tuple[float, float]],
+    desired_pin_position: Union[Point, Tuple[float, float]],
+    rotation: float = 0.0,
+    mirror: Optional[str] = None,
+    grid_size: float = 1.27,
+) -> Point:
+    """
+    Calculate component position needed to place a specific pin at a desired location.
+
+    This is the inverse of get_pin_position() - given where you want a pin to be,
+    it calculates where the component center needs to be placed.
+
+    Useful for aligning components by their pins rather than their centers, which
+    is essential for clean horizontal signal flows without unnecessary wire jogs.
+
+    Args:
+        pin_local_position: Pin position in symbol space (from symbol definition)
+        desired_pin_position: Where you want the pin to be in schematic space
+        rotation: Component rotation in degrees (0, 90, 180, 270)
+        mirror: Mirror axis ("x" or "y" or None) - currently unused
+        grid_size: Grid size for snapping result (default 1.27mm = 50mil)
+
+    Returns:
+        Component position that will place the pin at desired_pin_position
+
+    Example:
+        >>> # Place resistor so pin 2 is at (150, 100)
+        >>> pin_pos = Point(0, -3.81)  # Pin 2 local position from symbol
+        >>> comp_pos = calculate_position_for_pin(pin_pos, (150, 100))
+        >>> # Now add component at comp_pos, and pin 2 will be at (150, 100)
+
+    Note:
+        The result is automatically snapped to the KiCAD grid for proper connectivity.
+        This function matches the behavior of SchematicSymbol.get_pin_position().
+    """
+    # Convert inputs to proper types
+    if isinstance(pin_local_position, Point):
+        pin_x, pin_y = pin_local_position.x, pin_local_position.y
+    else:
+        pin_x, pin_y = pin_local_position
+
+    if isinstance(desired_pin_position, Point):
+        target_x, target_y = desired_pin_position.x, desired_pin_position.y
+    else:
+        target_x, target_y = desired_pin_position
+
+    logger.debug(
+        f"Calculating component position for pin at local ({pin_x}, {pin_y}) "
+        f"to reach target ({target_x}, {target_y}) with rotation={rotation}°"
+    )
+
+    # Apply the same transformation that get_pin_position() uses
+    # This is a standard 2D rotation matrix (NO Y-axis inversion)
+    angle_rad = math.radians(rotation)
+    cos_a = math.cos(angle_rad)
+    sin_a = math.sin(angle_rad)
+
+    # Calculate rotated offset (same as get_pin_position)
+    rotated_x = pin_x * cos_a - pin_y * sin_a
+    rotated_y = pin_x * sin_a + pin_y * cos_a
+
+    logger.debug(f"Pin offset after rotation: ({rotated_x:.3f}, {rotated_y:.3f})")
+
+    # Calculate component origin
+    # Since: target = component + rotated_offset
+    # Therefore: component = target - rotated_offset
+    component_x = target_x - rotated_x
+    component_y = target_y - rotated_y
+
+    logger.debug(f"Calculated component position (before grid snap): ({component_x:.3f}, {component_y:.3f})")
+
+    # Snap to grid for proper KiCAD connectivity
+    snapped_x, snapped_y = snap_to_grid((component_x, component_y), grid_size=grid_size)
+
+    logger.debug(f"Final component position (after grid snap): ({snapped_x:.3f}, {snapped_y:.3f})")
+
+    return Point(snapped_x, snapped_y)

kicad_sch_api/core/managers/__init__.py

@@ -5,9 +5,11 @@ 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
+from .hierarchy import HierarchyManager
 from .metadata import MetadataManager
 from .sheet import SheetManager
 from .text_elements import TextElementManager
@@ -15,9 +17,11 @@ from .validation import ValidationManager
 from .wire import WireManager
 
 __all__ = [
+    "BaseManager",
     "FileIOManager",
     "FormatSyncManager",
     "GraphicsManager",
+    "HierarchyManager",
     "MetadataManager",
     "SheetManager",
     "TextElementManager",

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,