kicad-sch-api 0.0.2__py3-none-any.whl → 0.1.1__py3-none-any.whl

kicad_sch_api/core/components.py

@@ -12,6 +12,7 @@ from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple, Union
 from ..library.cache import SymbolDefinition, get_symbol_cache
 from ..utils.validation import SchematicValidator, ValidationError, ValidationIssue
 from .types import Point, SchematicPin, SchematicSymbol
+from .ic_manager import ICManager
 
 logger = logging.getLogger(__name__)
 
@@ -290,6 +291,7 @@ class ComponentCollection:
         value: str = "",
         position: Optional[Union[Point, Tuple[float, float]]] = None,
         footprint: Optional[str] = None,
+        unit: int = 1,
         **properties,
     ) -> Component:
         """
@@ -301,6 +303,7 @@ class ComponentCollection:
             value: Component value
             position: Component position (auto-placed if None)
             footprint: Component footprint
+            unit: Unit number for multi-unit components (1-based)
             **properties: Additional component properties
 
         Returns:
@@ -340,6 +343,7 @@ class ComponentCollection:
             reference=reference,
             value=value,
             footprint=footprint,
+            unit=unit,
             properties=properties,
         )
 
@@ -359,6 +363,65 @@ class ComponentCollection:
         logger.info(f"Added component: {reference} ({lib_id})")
         return component
 
+    def add_ic(
+        self,
+        lib_id: str,
+        reference_prefix: str,
+        position: Optional[Union[Point, Tuple[float, float]]] = None,
+        value: str = "",
+        footprint: Optional[str] = None,
+        layout_style: str = "vertical",
+        **properties,
+    ) -> ICManager:
+        """
+        Add a multi-unit IC with automatic unit placement.
+
+        Args:
+            lib_id: Library identifier for the IC (e.g., "74xx:7400")
+            reference_prefix: Base reference (e.g., "U1" → U1A, U1B, etc.)
+            position: Base position for auto-layout (auto-placed if None)
+            value: IC value (defaults to symbol name)
+            footprint: IC footprint
+            layout_style: Layout algorithm ("vertical", "grid", "functional")
+            **properties: Common properties for all units
+
+        Returns:
+            ICManager object for position overrides and management
+
+        Example:
+            ic = sch.components.add_ic("74xx:7400", "U1", position=(100, 100))
+            ic.place_unit(1, position=(150, 80))  # Override Gate A position
+        """
+        # Set default position if not provided
+        if position is None:
+            position = self._find_available_position()
+        elif isinstance(position, tuple):
+            position = Point(position[0], position[1])
+
+        # Set default value to symbol name if not provided
+        if not value:
+            value = lib_id.split(":")[-1]  # "74xx:7400" → "7400"
+
+        # Create IC manager for this multi-unit component
+        ic_manager = ICManager(lib_id, reference_prefix, position, self)
+        
+        # Generate all unit components
+        unit_components = ic_manager.generate_components(
+            value=value,
+            footprint=footprint,
+            properties=properties
+        )
+
+        # Add all units to the collection
+        for component_data in unit_components:
+            component = Component(component_data, self)
+            self._add_to_indexes(component)
+
+        self._modified = True
+        logger.info(f"Added multi-unit IC: {reference_prefix} ({lib_id}) with {len(unit_components)} units")
+        
+        return ic_manager
+
     def remove(self, reference: str) -> bool:
         """
         Remove component by reference.

kicad_sch_api/core/formatter.py

@@ -51,13 +51,15 @@ class ExactFormatter:
         self.rules["kicad_sch"] = FormatRule(inline=False, indent_level=0)
         self.rules["version"] = FormatRule(inline=True)
         self.rules["generator"] = FormatRule(inline=True, quote_indices={1})
+        self.rules["generator_version"] = FormatRule(inline=True, quote_indices={1})
         self.rules["uuid"] = FormatRule(inline=True, quote_indices={1})
+        self.rules["paper"] = FormatRule(inline=True, quote_indices={1})
 
         # Title block
         self.rules["title_block"] = FormatRule(inline=False)
         self.rules["title"] = FormatRule(inline=True, quote_indices={1})
         self.rules["company"] = FormatRule(inline=True, quote_indices={1})
-        self.rules["revision"] = FormatRule(inline=True, quote_indices={1})
+        self.rules["rev"] = FormatRule(inline=True, quote_indices={1})  # KiCAD uses "rev"
         self.rules["date"] = FormatRule(inline=True, quote_indices={1})
         self.rules["size"] = FormatRule(inline=True, quote_indices={1})
         self.rules["comment"] = FormatRule(inline=True, quote_indices={2})
@@ -81,11 +83,13 @@ class ExactFormatter:
             inline=False, quote_indices={1, 2}, custom_handler=self._format_property
         )
 
-        # Pins and connections
-        self.rules["pin"] = FormatRule(inline=False, quote_indices={1, 2})
+        # Pins and connections  
+        self.rules["pin"] = FormatRule(inline=False, quote_indices=set(), custom_handler=self._format_pin)
+        self.rules["number"] = FormatRule(inline=True, quote_indices={1})  # Pin numbers should be quoted
+        self.rules["name"] = FormatRule(inline=True, quote_indices={1})    # Pin names should be quoted
         self.rules["instances"] = FormatRule(inline=False)
-        self.rules["project"] = FormatRule(inline=True, quote_indices={1})
-        self.rules["path"] = FormatRule(inline=True, quote_indices={1})
+        self.rules["project"] = FormatRule(inline=False, quote_indices={1})
+        self.rules["path"] = FormatRule(inline=False, quote_indices={1})
         self.rules["reference"] = FormatRule(inline=True, quote_indices={1})
 
         # Wire elements
@@ -113,6 +117,12 @@ class ExactFormatter:
         self.rules["justify"] = FormatRule(inline=True)
         self.rules["hide"] = FormatRule(inline=True)
 
+        # Sheet instances and metadata
+        self.rules["sheet_instances"] = FormatRule(inline=False)
+        self.rules["symbol_instances"] = FormatRule(inline=False)
+        self.rules["embedded_fonts"] = FormatRule(inline=True)
+        self.rules["page"] = FormatRule(inline=True, quote_indices={1})
+
     def format(self, data: Any) -> str:
         """
         Format S-expression data with exact KiCAD formatting.
@@ -181,7 +191,8 @@ class ExactFormatter:
         elements = []
         for i, element in enumerate(lst):
             if i in rule.quote_indices and isinstance(element, str):
-                elements.append(f'"{element}"')
+                escaped_element = self._escape_string(element)
+                elements.append(f'"{escaped_element}"')
             else:
                 elements.append(self._format_element(element, 0))
         return f"({' '.join(elements)})"
@@ -203,7 +214,9 @@ class ExactFormatter:
         # Handle different multiline formats based on tag
         if tag == "property":
             return self._format_property(lst, indent_level)
-        elif tag in ("symbol", "wire", "junction", "label"):
+        elif tag == "pin":
+            return self._format_pin(lst, indent_level)
+        elif tag in ("symbol", "wire", "junction", "label", "hierarchical_label"):
             return self._format_component_like(lst, indent_level, rule)
         else:
             return self._format_generic_multiline(lst, indent_level, rule)
@@ -217,7 +230,9 @@ class ExactFormatter:
         next_indent = "\t" * (indent_level + 1)
 
         # Property format: (property "Name" "Value" (at x y rotation) (effects ...))
-        result = f'({lst[0]} "{lst[1]}" "{lst[2]}"'
+        escaped_name = self._escape_string(str(lst[1]))
+        escaped_value = self._escape_string(str(lst[2]))
+        result = f'({lst[0]} "{escaped_name}" "{escaped_value}"'
 
         # Add position and effects on separate lines
         for element in lst[3:]:
@@ -226,7 +241,33 @@ class ExactFormatter:
             else:
                 result += f" {element}"
 
-        result += ")"
+        result += f"\n{indent})"
+        return result
+
+    def _format_pin(self, lst: List[Any], indent_level: int) -> str:
+        """Format pin elements with context-aware quoting."""
+        if len(lst) < 2:
+            return self._format_inline(lst, FormatRule())
+            
+        indent = "\t" * indent_level
+        next_indent = "\t" * (indent_level + 1)
+        
+        # Check if this is a lib_symbols pin (passive/line) or component pin ("1")
+        if len(lst) >= 3 and isinstance(lst[2], sexpdata.Symbol):
+            # lib_symbols context: (pin passive line ...)
+            result = f"({lst[0]} {lst[1]} {lst[2]}"
+            start_index = 3
+        else:
+            # component context: (pin "1" ...)  
+            result = f'({lst[0]} "{lst[1]}"'
+            start_index = 2
+            
+        # Add remaining elements on separate lines
+        for element in lst[start_index:]:
+            if isinstance(element, list):
+                result += f"\n{next_indent}{self._format_element(element, indent_level + 1)}"
+        
+        result += f"\n{indent})"
         return result
 
     def _format_component_like(self, lst: List[Any], indent_level: int, rule: FormatRule) -> str:
@@ -248,7 +289,7 @@ class ExactFormatter:
                 else:
                     result += f" {self._format_element(element, 0)}"
 
-        result += ")"
+        result += f"\n{indent})"
         return result
 
     def _format_generic_multiline(self, lst: List[Any], indent_level: int, rule: FormatRule) -> str:
@@ -263,11 +304,12 @@ 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)}"
 
-        result += ")"
+        result += f"\n{indent})"
         return result
 
     def _should_format_inline(self, lst: List[Any], rule: FormatRule) -> bool:
@@ -283,6 +325,11 @@ 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('"', '\\"')
+
     def _needs_quoting(self, text: str) -> bool:
         """Check if string needs to be quoted."""
         # Quote if contains spaces, special characters, or is empty

kicad_sch_api/core/ic_manager.py

@@ -0,0 +1,187 @@
+"""
+IC management for multi-unit components with auto-layout capabilities.
+
+This module provides intelligent placement and management for multi-unit ICs
+like op-amps, logic gates, and other complex components.
+"""
+
+import logging
+import uuid as uuid_module
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from .types import Point, SchematicSymbol
+from ..library.cache import get_symbol_cache
+
+logger = logging.getLogger(__name__)
+
+
+class ICManager:
+    """
+    Manager for multi-unit IC components with auto-layout capabilities.
+    
+    Features:
+    - Automatic unit detection and placement
+    - Smart layout algorithms (vertical, grid, functional)
+    - Individual unit position override
+    - Professional spacing and alignment
+    """
+
+    def __init__(self, lib_id: str, reference_prefix: str, position: Point, 
+                 component_collection: "ComponentCollection"):
+        """
+        Initialize IC manager.
+        
+        Args:
+            lib_id: IC library ID (e.g., "74xx:7400")
+            reference_prefix: Base reference (e.g., "U1" → U1A, U1B, etc.)
+            position: Base position for auto-layout
+            component_collection: Parent collection for component management
+        """
+        self.lib_id = lib_id
+        self.reference_prefix = reference_prefix
+        self.base_position = position
+        self._collection = component_collection
+        self._units: Dict[int, SchematicSymbol] = {}
+        self._unit_positions: Dict[int, Point] = {}
+        
+        # Detect available units from symbol library
+        self._detect_available_units()
+        
+        # Auto-place all units with default layout
+        self._auto_layout_units()
+        
+        logger.debug(f"ICManager initialized for {lib_id} with {len(self._units)} units")
+
+    def _detect_available_units(self):
+        """Detect available units from symbol library definition."""
+        cache = get_symbol_cache()
+        symbol_def = cache.get_symbol(self.lib_id)
+        
+        if not symbol_def or not hasattr(symbol_def, 'raw_kicad_data'):
+            logger.warning(f"Could not detect units for {self.lib_id}")
+            return
+        
+        # Parse symbol data to find unit definitions
+        symbol_data = symbol_def.raw_kicad_data
+        if isinstance(symbol_data, list):
+            for item in symbol_data[1:]:
+                if isinstance(item, list) and len(item) >= 2:
+                    if item[0] == getattr(item[0], 'value', str(item[0])) == 'symbol':
+                        unit_name = str(item[1]).strip('"')
+                        # Extract unit number from name like "7400_1_1" → unit 1
+                        unit_num = self._extract_unit_number(unit_name)
+                        if unit_num and unit_num not in self._units:
+                            logger.debug(f"Detected unit {unit_num} from {unit_name}")
+
+    def _extract_unit_number(self, unit_name: str) -> Optional[int]:
+        """Extract unit number from symbol unit name like '7400_1_1' → 1."""
+        parts = unit_name.split('_')
+        if len(parts) >= 3:
+            try:
+                return int(parts[-2])  # Second to last part is unit number
+            except ValueError:
+                pass
+        return None
+
+    def _auto_layout_units(self):
+        """Auto-place all units using vertical layout algorithm."""
+        # Define unit layout based on detected units
+        self._place_default_units()
+
+    def _place_default_units(self):
+        """Place default units for common IC types."""
+        # For 74xx logic ICs, typically have units 1-4 (logic) + unit 5 (power)
+        unit_spacing = 12.7  # Tight vertical spacing (0.5 inch in mm)
+        power_offset = (25.4, 0)  # Power unit offset (1 inch right)
+        
+        # Place logic units (1-4) vertically in a tight column
+        for unit in range(1, 5):
+            unit_pos = Point(
+                self.base_position.x,
+                self.base_position.y + (unit - 1) * unit_spacing
+            )
+            self._unit_positions[unit] = unit_pos
+            
+        # Place power unit (5) to the right of logic units
+        if 5 not in self._unit_positions:
+            power_pos = Point(
+                self.base_position.x + power_offset[0],
+                self.base_position.y + unit_spacing  # Align with second gate
+            )
+            self._unit_positions[5] = power_pos
+
+        logger.debug(f"Auto-placed {len(self._unit_positions)} units with tight spacing")
+
+    def place_unit(self, unit: int, position: Union[Point, Tuple[float, float]]):
+        """
+        Override the position of a specific unit.
+        
+        Args:
+            unit: Unit number to place
+            position: New position for the unit
+        """
+        if isinstance(position, tuple):
+            position = Point(position[0], position[1])
+            
+        self._unit_positions[unit] = position
+        
+        # If component already exists, update its position
+        if unit in self._units:
+            self._units[unit].position = position
+            self._collection._mark_modified()
+            
+        logger.debug(f"Placed unit {unit} at {position}")
+
+    def get_unit_position(self, unit: int) -> Optional[Point]:
+        """Get the position of a specific unit."""
+        return self._unit_positions.get(unit)
+
+    def get_all_units(self) -> Dict[int, Point]:
+        """Get all unit positions."""
+        return self._unit_positions.copy()
+
+    def generate_components(self, **common_properties) -> List[SchematicSymbol]:
+        """
+        Generate all component instances for this IC.
+        
+        Args:
+            **common_properties: Properties to apply to all units
+            
+        Returns:
+            List of component symbols for all units
+        """
+        components = []
+        
+        for unit, position in self._unit_positions.items():
+            # Generate unit reference (U1 → U1A, U1B, etc.)
+            if unit <= 4:
+                unit_ref = f"{self.reference_prefix}{chr(ord('A') + unit - 1)}"  # U1A, U1B, U1C, U1D
+            else:
+                unit_ref = f"{self.reference_prefix}{chr(ord('A') + unit - 1)}"  # U1E for power
+            
+            component = SchematicSymbol(
+                uuid=str(uuid_module.uuid4()),
+                lib_id=self.lib_id,
+                position=position,
+                reference=unit_ref,
+                value=common_properties.get('value', self.lib_id.split(':')[-1]),
+                footprint=common_properties.get('footprint'),
+                unit=unit,
+                properties=common_properties.get('properties', {})
+            )
+            
+            components.append(component)
+            self._units[unit] = component
+            
+        logger.debug(f"Generated {len(components)} component instances")
+        return components
+
+    def get_unit_references(self) -> Dict[int, str]:
+        """Get mapping of unit numbers to references."""
+        references = {}
+        for unit in self._unit_positions.keys():
+            if unit <= 4:
+                references[unit] = f"{self.reference_prefix}{chr(ord('A') + unit - 1)}"
+            else:
+                references[unit] = f"{self.reference_prefix}{chr(ord('A') + unit - 1)}"
+        return references

kicad_sch_api/core/junctions.py

@@ -0,0 +1,206 @@
+"""
+Junction collection and management for KiCAD schematics.
+
+This module provides enhanced junction management for wire intersections
+and connection points with performance optimization and validation.
+"""
+
+import logging
+import uuid as uuid_module
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from .types import Point, Junction
+
+logger = logging.getLogger(__name__)
+
+
+class JunctionCollection:
+    """
+    Professional junction collection with enhanced management features.
+
+    Features:
+    - Fast UUID-based lookup and indexing
+    - Position-based junction queries
+    - Bulk operations for performance
+    - Validation and conflict detection
+    """
+
+    def __init__(self, junctions: Optional[List[Junction]] = None):
+        """
+        Initialize junction collection.
+
+        Args:
+            junctions: Initial list of junctions
+        """
+        self._junctions: List[Junction] = junctions or []
+        self._uuid_index: Dict[str, int] = {}
+        self._modified = False
+        
+        # Build UUID index
+        self._rebuild_index()
+        
+        logger.debug(f"JunctionCollection initialized with {len(self._junctions)} junctions")
+
+    def _rebuild_index(self):
+        """Rebuild UUID index for fast lookups."""
+        self._uuid_index = {junction.uuid: i for i, junction in enumerate(self._junctions)}
+
+    def __len__(self) -> int:
+        """Number of junctions in collection."""
+        return len(self._junctions)
+
+    def __iter__(self):
+        """Iterate over junctions."""
+        return iter(self._junctions)
+
+    def __getitem__(self, uuid: str) -> Junction:
+        """Get junction by UUID."""
+        if uuid not in self._uuid_index:
+            raise KeyError(f"Junction with UUID '{uuid}' not found")
+        return self._junctions[self._uuid_index[uuid]]
+
+    def add(
+        self,
+        position: Union[Point, Tuple[float, float]],
+        diameter: float = 0,
+        color: Tuple[int, int, int, int] = (0, 0, 0, 0),
+        uuid: Optional[str] = None
+    ) -> str:
+        """
+        Add a junction to the collection.
+
+        Args:
+            position: Junction position
+            diameter: Junction diameter (0 is KiCAD default)
+            color: RGBA color tuple (0,0,0,0 is default)
+            uuid: Optional UUID (auto-generated if not provided)
+
+        Returns:
+            UUID of the created junction
+
+        Raises:
+            ValueError: If UUID already exists
+        """
+        # Generate UUID if not provided
+        if uuid is None:
+            uuid = str(uuid_module.uuid4())
+        elif uuid in self._uuid_index:
+            raise ValueError(f"Junction with UUID '{uuid}' already exists")
+
+        # Convert position
+        if isinstance(position, tuple):
+            position = Point(position[0], position[1])
+
+        # Create junction
+        junction = Junction(
+            uuid=uuid,
+            position=position,
+            diameter=diameter,
+            color=color
+        )
+
+        # Add to collection
+        self._junctions.append(junction)
+        self._uuid_index[uuid] = len(self._junctions) - 1
+        self._modified = True
+
+        logger.debug(f"Added junction at {position}, UUID={uuid}")
+        return uuid
+
+    def remove(self, uuid: str) -> bool:
+        """
+        Remove junction by UUID.
+
+        Args:
+            uuid: Junction UUID to remove
+
+        Returns:
+            True if junction was removed, False if not found
+        """
+        if uuid not in self._uuid_index:
+            return False
+
+        index = self._uuid_index[uuid]
+        del self._junctions[index]
+        self._rebuild_index()
+        self._modified = True
+
+        logger.debug(f"Removed junction: {uuid}")
+        return True
+
+    def get_at_position(self, position: Union[Point, Tuple[float, float]], tolerance: float = 0.01) -> Optional[Junction]:
+        """
+        Find junction at or near a specific position.
+
+        Args:
+            position: Position to search
+            tolerance: Distance tolerance for matching
+
+        Returns:
+            Junction if found, None otherwise
+        """
+        if isinstance(position, tuple):
+            position = Point(position[0], position[1])
+
+        for junction in self._junctions:
+            if junction.position.distance_to(position) <= tolerance:
+                return junction
+        
+        return None
+
+    def get_by_point(self, point: Union[Point, Tuple[float, float]], tolerance: float = 0.01) -> List[Junction]:
+        """
+        Find all junctions near a point.
+
+        Args:
+            point: Point to search near
+            tolerance: Distance tolerance
+
+        Returns:
+            List of junctions near the point
+        """
+        if isinstance(point, tuple):
+            point = Point(point[0], point[1])
+
+        matching_junctions = []
+        for junction in self._junctions:
+            if junction.position.distance_to(point) <= tolerance:
+                matching_junctions.append(junction)
+
+        return matching_junctions
+
+    def get_statistics(self) -> Dict[str, Any]:
+        """Get junction collection statistics."""
+        if not self._junctions:
+            return {
+                "total_junctions": 0,
+                "avg_diameter": 0,
+                "positions": []
+            }
+        
+        avg_diameter = sum(j.diameter for j in self._junctions) / len(self._junctions)
+        positions = [(j.position.x, j.position.y) for j in self._junctions]
+        
+        return {
+            "total_junctions": len(self._junctions),
+            "avg_diameter": avg_diameter,
+            "positions": positions,
+            "unique_diameters": len(set(j.diameter for j in self._junctions)),
+            "unique_colors": len(set(j.color for j in self._junctions))
+        }
+
+    def clear(self):
+        """Remove all junctions from collection."""
+        self._junctions.clear()
+        self._uuid_index.clear()
+        self._modified = True
+        logger.debug("Cleared all junctions")
+
+    @property
+    def modified(self) -> bool:
+        """Check if collection has been modified."""
+        return self._modified
+
+    def mark_saved(self):
+        """Mark collection as saved (reset modified flag)."""
+        self._modified = False