kicad-sch-api 0.3.4__tar.gz → 0.4.0__tar.gz

{kicad_sch_api-0.3.4 → kicad_sch_api-0.4.0}/CHANGELOG.md

@@ -5,6 +5,71 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2025-10-26
+
+### Added
+- **Phase 4 Manager Architecture**: Complete refactoring of schematic data management
+  - Introduced `ComponentManager` for component operations and lib_symbols synchronization
+  - Introduced `WireManager` for wire and bus operations
+  - Introduced `JunctionManager` for junction operations
+  - Introduced `SheetManager` for hierarchical sheet management
+  - Introduced `TextElementManager` for label and text operations
+  - Introduced `GraphicsManager` for graphical elements (rectangles, circles, arcs, polylines)
+  - Composition-based architecture replacing monolithic schematic class
+
+- **Text Box Support**: Full text box functionality with complete KiCAD compatibility
+  - `add_text_box()` method with rotation, font size, margins, and justification
+  - Support for stroke styling and fill options
+  - Proper serialization matching KiCAD format exactly
+
+- **Enhanced Hierarchical Sheet Support**: Complete sheet management functionality
+  - Sheet creation with proper position, size, and styling
+  - Sheet pin management with multiple pin types (input, output, bidirectional, tri_state, passive)
+  - Sheet hierarchy validation and traversal
+  - Proper data structure matching KiCAD parser expectations
+
+- **Rectangle Color Support**: Full color support for graphical rectangles
+  - Stroke color customization (RGBA)
+  - Fill color customization (RGBA)
+  - Proper color serialization in S-expression output
+
+### Fixed
+- **Hierarchical Sheet Data Structure**: Fixed sheet serialization format
+  - Changed storage key from "sheet" (singular) to "sheets" (plural)
+  - Fixed position format from lists to dictionaries: `{"x": x, "y": y}`
+  - Fixed size format from lists to dictionaries: `{"width": w, "height": h}`
+  - Fixed fill_color default from white (255,255,255,0.0) to transparent black (0,0,0,0.0)
+  - Fixed sheet pin structure: "pin" → "pins", "shape" → "pin_type"
+
+- **Rectangle Color Flow**: Fixed color parameter propagation through managers and parser
+  - GraphicsManager now extracts and stores stroke_color and fill_color from stroke/fill dicts
+  - Parser now serializes colors in stroke and fill S-expression sections
+  - Complete color support for bounding box visualization
+
+- **Text Box Data Structure**: Fixed text box format to match parser expectations
+  - Changed storage key from "text_box" to "text_boxes" (plural)
+  - Implemented complete parameter set (rotation, font_size, margins, stroke, fill, justification)
+  - Fixed position/size format to use dictionaries instead of lists
+
+### Changed
+- **Schematic Class Refactoring**: Delegated operations to specialized managers
+  - Schematic class now composes managers instead of implementing all operations
+  - Cleaner separation of concerns and improved maintainability
+  - All existing APIs maintained for backward compatibility
+
+- **Test Suite**: All 302 tests passing (295 run, 7 skipped)
+  - Added tests for hierarchical sheets with proper serialization
+  - Added tests for rectangle colors with stroke and fill
+  - Added tests for text boxes with full parameter support
+  - Format preservation tests validate exact KiCAD compatibility
+
+### Technical Notes
+- Manager architecture enables easier feature additions and maintenance
+- All data structures now properly synchronized between managers and parser
+- Singular/plural key consistency enforced throughout codebase
+- Position and size formats standardized to dictionary format
+- 100% backward compatibility maintained - no breaking changes
+
 ## [0.3.0] - 2025-10-12
 
 ### Added

{kicad_sch_api-0.3.4/kicad_sch_api.egg-info → kicad_sch_api-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kicad-sch-api
-Version: 0.3.4
+Version: 0.4.0
 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.0/examples/parser_demo.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+Demonstration of the new modular parser system.
+
+This example shows how to use the new ElementParserRegistry
+and specialized parsers for different S-expression elements.
+"""
+
+import logging
+import sexpdata
+
+from kicad_sch_api.parsers.registry import ElementParserRegistry
+from kicad_sch_api.parsers.wire_parser import WireParser
+from kicad_sch_api.parsers.symbol_parser import SymbolParser
+from kicad_sch_api.parsers.label_parser import LabelParser, HierarchicalLabelParser
+
+# Enable debug logging to see what's happening
+logging.basicConfig(level=logging.WARNING)  # Reduce noise
+
+
+def main():
+    """Demonstrate the new parser system."""
+    print("🔧 KiCAD Schematic API - New Parser System Demo")
+    print("=" * 50)
+
+    # Create registry and register specialized parsers
+    registry = ElementParserRegistry()
+    registry.register("wire", WireParser())
+    registry.register("symbol", SymbolParser())
+    registry.register("label", LabelParser())
+    registry.register("hierarchical_label", HierarchicalLabelParser())
+
+    print(f"📋 Registered parsers: {registry.get_registered_types()}")
+    print()
+
+    # Example S-expression elements (using sexpdata.Symbol for type names)
+    test_elements = [
+        # Wire element
+        [sexpdata.Symbol("wire"),
+         [sexpdata.Symbol("pts"), [sexpdata.Symbol("xy"), 100.0, 100.0], [sexpdata.Symbol("xy"), 150.0, 100.0]],
+         [sexpdata.Symbol("stroke"), [sexpdata.Symbol("width"), 0.0], [sexpdata.Symbol("type"), sexpdata.Symbol("default")]],
+         [sexpdata.Symbol("uuid"), "12345678-1234-5678-9abc-123456789abc"]],
+
+        # Label element
+        [sexpdata.Symbol("label"), "VCC",
+         [sexpdata.Symbol("at"), 125.0, 95.0, 0],
+         [sexpdata.Symbol("effects"), [sexpdata.Symbol("font"), [sexpdata.Symbol("size"), 1.27, 1.27]]],
+         [sexpdata.Symbol("uuid"), "87654321-4321-8765-cba9-876543210987"]],
+
+        # Unknown element (will be skipped)
+        [sexpdata.Symbol("unknown_element"), "some_data"]
+    ]
+
+    # Parse elements using the registry
+    print("🔍 Parsing S-expression elements:")
+    print()
+
+    for i, element in enumerate(test_elements, 1):
+        element_type = element[0] if element else "unknown"
+        print(f"Element {i}: {element_type}")
+
+        result = registry.parse_element(element)
+        if result:
+            print(f"  ✅ Successfully parsed")
+            print(f"  📊 Result keys: {list(result.keys())}")
+            if "points" in result:
+                print(f"  📍 Points: {len(result['points'])} points")
+            if "text" in result:
+                print(f"  📝 Text: '{result['text']}'")
+        else:
+            print(f"  ❌ No parser available")
+        print()
+
+    # Demonstrate batch parsing
+    print("📦 Batch parsing multiple elements:")
+    results = registry.parse_elements(test_elements)
+    print(f"  ✅ Successfully parsed {len(results)} of {len(test_elements)} elements")
+
+    # Show parsing statistics
+    successful_types = [r.get("type", "unknown") for r in results if "type" in r]
+    print(f"  📊 Parsed types: {set(successful_types)}")
+
+    print()
+    print("✨ New parser system benefits:")
+    print("  • Modular and testable parsers")
+    print("  • Easy to add new element types")
+    print("  • Clear separation of concerns")
+    print("  • Comprehensive error handling")
+    print("  • Extensible with fallback parsers")
+
+
+if __name__ == "__main__":
+    main()

kicad_sch_api-0.4.0/kicad_sch_api/collections/__init__.py

@@ -0,0 +1,21 @@
+"""
+Modern collection architecture for KiCAD schematic elements.
+
+This module provides a unified collection framework that eliminates code duplication
+across component, wire, and junction collections while providing consistent
+indexing, performance optimization, and management capabilities.
+"""
+
+from .base import IndexedCollection
+from .components import ComponentCollection
+from .junctions import JunctionCollection
+from .labels import LabelCollection
+from .wires import WireCollection
+
+__all__ = [
+    "IndexedCollection",
+    "ComponentCollection",
+    "WireCollection",
+    "JunctionCollection",
+    "LabelCollection",
+]

kicad_sch_api-0.4.0/kicad_sch_api/collections/base.py

@@ -0,0 +1,294 @@
+"""
+Base collection class for unified schematic element management.
+
+Provides common functionality for indexing, searching, and managing
+collections of schematic elements with performance optimization.
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Dict, Generic, Iterator, List, Optional, TypeVar, Union
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")  # Type variable for collection items
+
+
+class IndexedCollection(Generic[T], ABC):
+    """
+    Base class for all schematic element collections with automatic indexing.
+
+    Provides unified functionality for:
+    - UUID-based fast lookups
+    - Automatic index management
+    - Modification tracking
+    - Consistent iteration interface
+    - Performance optimization for large collections
+    """
+
+    def __init__(self, items: Optional[List[T]] = None):
+        """
+        Initialize indexed collection.
+
+        Args:
+            items: Initial list of items to add to collection
+        """
+        self._items: List[T] = []
+        self._uuid_index: Dict[str, int] = {}
+        self._modified = False
+        self._dirty_indexes = False
+
+        # Add initial items if provided
+        if items:
+            for item in items:
+                self._add_item_to_collection(item)
+
+        logger.debug(f"{self.__class__.__name__} initialized with {len(self._items)} items")
+
+    # Abstract methods for subclasses to implement
+    @abstractmethod
+    def _get_item_uuid(self, item: T) -> str:
+        """
+        Extract UUID from an item.
+
+        Args:
+            item: Item to extract UUID from
+
+        Returns:
+            UUID string for the item
+        """
+        pass
+
+    @abstractmethod
+    def _create_item(self, **kwargs) -> T:
+        """
+        Create a new item with given parameters.
+
+        Args:
+            **kwargs: Parameters for item creation
+
+        Returns:
+            Newly created item
+        """
+        pass
+
+    @abstractmethod
+    def _build_additional_indexes(self) -> None:
+        """
+        Build any additional indexes specific to the collection type.
+
+        Called after UUID index is rebuilt. Subclasses should implement
+        this to maintain their own specialized indexes.
+        """
+        pass
+
+    # Core collection operations
+    def add(self, item: T) -> T:
+        """
+        Add an item to the collection.
+
+        Args:
+            item: Item to add
+
+        Returns:
+            The added item
+
+        Raises:
+            ValueError: If item with same UUID already exists
+        """
+        uuid_str = self._get_item_uuid(item)
+
+        # Ensure indexes are current before checking for duplicates
+        self._ensure_indexes_current()
+
+        # Check for duplicate UUID
+        if uuid_str in self._uuid_index:
+            raise ValueError(f"Item with UUID {uuid_str} already exists")
+
+        return self._add_item_to_collection(item)
+
+    def remove(self, identifier: Union[str, T]) -> bool:
+        """
+        Remove an item from the collection.
+
+        Args:
+            identifier: UUID string or item instance to remove
+
+        Returns:
+            True if item was removed, False if not found
+        """
+        self._ensure_indexes_current()
+
+        if isinstance(identifier, str):
+            # Remove by UUID
+            if identifier not in self._uuid_index:
+                return False
+
+            index = self._uuid_index[identifier]
+            item = self._items[index]
+        else:
+            # Remove by item instance
+            item = identifier
+            uuid_str = self._get_item_uuid(item)
+            if uuid_str not in self._uuid_index:
+                return False
+
+            index = self._uuid_index[uuid_str]
+
+        # Remove from main list
+        self._items.pop(index)
+        self._mark_modified()
+        self._mark_indexes_dirty()
+
+        logger.debug(f"Removed item with UUID {self._get_item_uuid(item)}")
+        return True
+
+    def get(self, uuid: str) -> Optional[T]:
+        """
+        Get an item by UUID.
+
+        Args:
+            uuid: UUID to search for
+
+        Returns:
+            Item if found, None otherwise
+        """
+        self._ensure_indexes_current()
+
+        if uuid in self._uuid_index:
+            index = self._uuid_index[uuid]
+            return self._items[index]
+
+        return None
+
+    def find(self, predicate: Callable[[T], bool]) -> List[T]:
+        """
+        Find all items matching a predicate.
+
+        Args:
+            predicate: Function that returns True for matching items
+
+        Returns:
+            List of matching items
+        """
+        return [item for item in self._items if predicate(item)]
+
+    def filter(self, **criteria) -> List[T]:
+        """
+        Filter items by attribute criteria.
+
+        Args:
+            **criteria: Attribute name/value pairs to match
+
+        Returns:
+            List of matching items
+        """
+
+        def matches_criteria(item: T) -> bool:
+            for attr, value in criteria.items():
+                if not hasattr(item, attr) or getattr(item, attr) != value:
+                    return False
+            return True
+
+        return self.find(matches_criteria)
+
+    def clear(self) -> None:
+        """Clear all items from the collection."""
+        self._items.clear()
+        self._uuid_index.clear()
+        self._mark_modified()
+        logger.debug(f"Cleared all items from {self.__class__.__name__}")
+
+    # Collection interface methods
+    def __len__(self) -> int:
+        """Number of items in collection."""
+        return len(self._items)
+
+    def __iter__(self) -> Iterator[T]:
+        """Iterate over items in collection."""
+        return iter(self._items)
+
+    def __contains__(self, item: Union[str, T]) -> bool:
+        """Check if item or UUID is in collection."""
+        if isinstance(item, str):
+            # Check by UUID
+            self._ensure_indexes_current()
+            return item in self._uuid_index
+        else:
+            # Check by item instance
+            uuid_str = self._get_item_uuid(item)
+            self._ensure_indexes_current()
+            return uuid_str in self._uuid_index
+
+    def __getitem__(self, index: int) -> T:
+        """Get item by index."""
+        return self._items[index]
+
+    # Internal methods
+    def _add_item_to_collection(self, item: T) -> T:
+        """
+        Internal method to add item to collection.
+
+        Args:
+            item: Item to add
+
+        Returns:
+            The added item
+        """
+        self._items.append(item)
+        self._mark_modified()
+        self._mark_indexes_dirty()
+
+        logger.debug(f"Added item with UUID {self._get_item_uuid(item)}")
+        return item
+
+    def _mark_modified(self) -> None:
+        """Mark collection as modified."""
+        self._modified = True
+
+    def _mark_indexes_dirty(self) -> None:
+        """Mark indexes as needing rebuild."""
+        self._dirty_indexes = True
+
+    def _ensure_indexes_current(self) -> None:
+        """Ensure all indexes are current."""
+        if self._dirty_indexes:
+            self._rebuild_indexes()
+
+    def _rebuild_indexes(self) -> None:
+        """Rebuild all indexes."""
+        # Rebuild UUID index
+        self._uuid_index = {self._get_item_uuid(item): i for i, item in enumerate(self._items)}
+
+        # Let subclasses rebuild their additional indexes
+        self._build_additional_indexes()
+
+        self._dirty_indexes = False
+        logger.debug(f"Rebuilt indexes for {self.__class__.__name__}")
+
+    # Collection statistics and debugging
+    def get_statistics(self) -> Dict[str, Any]:
+        """
+        Get collection statistics for debugging and monitoring.
+
+        Returns:
+            Dictionary with collection statistics
+        """
+        self._ensure_indexes_current()
+        return {
+            "item_count": len(self._items),
+            "uuid_index_size": len(self._uuid_index),
+            "modified": self._modified,
+            "indexes_dirty": self._dirty_indexes,
+            "collection_type": self.__class__.__name__,
+        }
+
+    @property
+    def is_modified(self) -> bool:
+        """Whether collection has been modified."""
+        return self._modified
+
+    def mark_clean(self) -> None:
+        """Mark collection as clean (not modified)."""
+        self._modified = False
+        logger.debug(f"Marked {self.__class__.__name__} as clean")