kicad-sch-api 0.3.4__py3-none-any.whl → 0.4.0__py3-none-any.whl

kicad_sch_api/core/labels.py

@@ -0,0 +1,348 @@
+"""
+Label element management for KiCAD schematics.
+
+This module provides collection classes for managing label elements,
+featuring fast lookup, bulk operations, and validation.
+"""
+
+import logging
+import uuid
+from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple, Union
+
+from ..utils.validation import SchematicValidator, ValidationError, ValidationIssue
+from .types import Label, Point
+
+logger = logging.getLogger(__name__)
+
+
+class LabelElement:
+    """
+    Enhanced wrapper for schematic label elements with modern API.
+
+    Provides intuitive access to label properties and operations
+    while maintaining exact format preservation.
+    """
+
+    def __init__(self, label_data: Label, parent_collection: "LabelCollection"):
+        """
+        Initialize label element wrapper.
+
+        Args:
+            label_data: Underlying label data
+            parent_collection: Parent collection for updates
+        """
+        self._data = label_data
+        self._collection = parent_collection
+        self._validator = SchematicValidator()
+
+    # Core properties with validation
+    @property
+    def uuid(self) -> str:
+        """Label element UUID."""
+        return self._data.uuid
+
+    @property
+    def text(self) -> str:
+        """Label text (net name)."""
+        return self._data.text
+
+    @text.setter
+    def text(self, value: str):
+        """Set label text with validation."""
+        if not isinstance(value, str) or not value.strip():
+            raise ValidationError("Label text cannot be empty")
+        old_text = self._data.text
+        self._data.text = value.strip()
+        self._collection._update_text_index(old_text, self)
+        self._collection._mark_modified()
+
+    @property
+    def position(self) -> Point:
+        """Label position."""
+        return self._data.position
+
+    @position.setter
+    def position(self, value: Union[Point, Tuple[float, float]]):
+        """Set label position."""
+        if isinstance(value, tuple):
+            value = Point(value[0], value[1])
+        elif not isinstance(value, Point):
+            raise ValidationError(f"Position must be Point or tuple, got {type(value)}")
+        self._data.position = value
+        self._collection._mark_modified()
+
+    @property
+    def rotation(self) -> float:
+        """Label rotation in degrees."""
+        return self._data.rotation
+
+    @rotation.setter
+    def rotation(self, value: float):
+        """Set label rotation."""
+        self._data.rotation = float(value)
+        self._collection._mark_modified()
+
+    @property
+    def size(self) -> float:
+        """Label text size."""
+        return self._data.size
+
+    @size.setter
+    def size(self, value: float):
+        """Set label size with validation."""
+        if value <= 0:
+            raise ValidationError(f"Label size must be positive, got {value}")
+        self._data.size = float(value)
+        self._collection._mark_modified()
+
+    def validate(self) -> List[ValidationIssue]:
+        """Validate this label element."""
+        return self._validator.validate_label(self._data.__dict__)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert label element to dictionary representation."""
+        return {
+            "uuid": self.uuid,
+            "text": self.text,
+            "position": {"x": self.position.x, "y": self.position.y},
+            "rotation": self.rotation,
+            "size": self.size,
+        }
+
+    def __str__(self) -> str:
+        """String representation."""
+        return f"<Label '{self.text}' @ {self.position}>"
+
+
+class LabelCollection:
+    """
+    Collection class for efficient label element management.
+
+    Provides fast lookup, filtering, and bulk operations for schematic label elements.
+    """
+
+    def __init__(self, labels: List[Label] = None):
+        """
+        Initialize label collection.
+
+        Args:
+            labels: Initial list of label data
+        """
+        self._labels: List[LabelElement] = []
+        self._uuid_index: Dict[str, LabelElement] = {}
+        self._text_index: Dict[str, List[LabelElement]] = {}
+        self._modified = False
+
+        # Add initial labels
+        if labels:
+            for label_data in labels:
+                self._add_to_indexes(LabelElement(label_data, self))
+
+        logger.debug(f"LabelCollection initialized with {len(self._labels)} labels")
+
+    def add(
+        self,
+        text: str,
+        position: Union[Point, Tuple[float, float]],
+        rotation: float = 0.0,
+        size: float = 1.27,
+        label_uuid: Optional[str] = None,
+    ) -> LabelElement:
+        """
+        Add a new label element to the schematic.
+
+        Args:
+            text: Label text (net name)
+            position: Label position
+            rotation: Label rotation in degrees
+            size: Label text size
+            label_uuid: Specific UUID for label (auto-generated if None)
+
+        Returns:
+            Newly created LabelElement
+
+        Raises:
+            ValidationError: If label data is invalid
+        """
+        # Validate inputs
+        if not isinstance(text, str) or not text.strip():
+            raise ValidationError("Label text cannot be empty")
+
+        if isinstance(position, tuple):
+            position = Point(position[0], position[1])
+        elif not isinstance(position, Point):
+            raise ValidationError(f"Position must be Point or tuple, got {type(position)}")
+
+        if size <= 0:
+            raise ValidationError(f"Label size must be positive, got {size}")
+
+        # Generate UUID if not provided
+        if not label_uuid:
+            label_uuid = str(uuid.uuid4())
+
+        # Check for duplicate UUID
+        if label_uuid in self._uuid_index:
+            raise ValidationError(f"Label UUID {label_uuid} already exists")
+
+        # Create label data
+        label_data = Label(
+            uuid=label_uuid,
+            position=position,
+            text=text.strip(),
+            rotation=rotation,
+            size=size,
+        )
+
+        # Create wrapper and add to collection
+        label_element = LabelElement(label_data, self)
+        self._add_to_indexes(label_element)
+        self._mark_modified()
+
+        logger.debug(f"Added label: {label_element}")
+        return label_element
+
+    def get(self, label_uuid: str) -> Optional[LabelElement]:
+        """Get label by UUID."""
+        return self._uuid_index.get(label_uuid)
+
+    def get_by_text(self, text: str) -> List[LabelElement]:
+        """Get all labels with the given text."""
+        return self._text_index.get(text, []).copy()
+
+    def remove(self, label_uuid: str) -> bool:
+        """
+        Remove label by UUID.
+
+        Args:
+            label_uuid: UUID of label to remove
+
+        Returns:
+            True if label was removed, False if not found
+        """
+        label_element = self._uuid_index.get(label_uuid)
+        if not label_element:
+            return False
+
+        # Remove from indexes
+        self._remove_from_indexes(label_element)
+        self._mark_modified()
+
+        logger.debug(f"Removed label: {label_element}")
+        return True
+
+    def find_by_text(self, text: str, exact: bool = True) -> List[LabelElement]:
+        """
+        Find labels by text.
+
+        Args:
+            text: Text to search for
+            exact: If True, exact match; if False, substring match
+
+        Returns:
+            List of matching label elements
+        """
+        if exact:
+            return self._text_index.get(text, []).copy()
+        else:
+            matches = []
+            for label_element in self._labels:
+                if text.lower() in label_element.text.lower():
+                    matches.append(label_element)
+            return matches
+
+    def filter(self, predicate: Callable[[LabelElement], bool]) -> List[LabelElement]:
+        """
+        Filter labels by predicate function.
+
+        Args:
+            predicate: Function that returns True for labels to include
+
+        Returns:
+            List of labels matching predicate
+        """
+        return [label for label in self._labels if predicate(label)]
+
+    def bulk_update(self, criteria: Callable[[LabelElement], bool], updates: Dict[str, Any]):
+        """
+        Update multiple labels matching criteria.
+
+        Args:
+            criteria: Function to select labels to update
+            updates: Dictionary of property updates
+        """
+        updated_count = 0
+        for label_element in self._labels:
+            if criteria(label_element):
+                for prop, value in updates.items():
+                    if hasattr(label_element, prop):
+                        setattr(label_element, prop, value)
+                        updated_count += 1
+
+        if updated_count > 0:
+            self._mark_modified()
+            logger.debug(f"Bulk updated {updated_count} label properties")
+
+    def clear(self):
+        """Remove all labels from collection."""
+        self._labels.clear()
+        self._uuid_index.clear()
+        self._text_index.clear()
+        self._mark_modified()
+
+    def _add_to_indexes(self, label_element: LabelElement):
+        """Add label to internal indexes."""
+        self._labels.append(label_element)
+        self._uuid_index[label_element.uuid] = label_element
+
+        # Add to text index
+        text = label_element.text
+        if text not in self._text_index:
+            self._text_index[text] = []
+        self._text_index[text].append(label_element)
+
+    def _remove_from_indexes(self, label_element: LabelElement):
+        """Remove label from internal indexes."""
+        self._labels.remove(label_element)
+        del self._uuid_index[label_element.uuid]
+
+        # Remove from text index
+        text = label_element.text
+        if text in self._text_index:
+            self._text_index[text].remove(label_element)
+            if not self._text_index[text]:
+                del self._text_index[text]
+
+    def _update_text_index(self, old_text: str, label_element: LabelElement):
+        """Update text index when label text changes."""
+        # Remove from old text index
+        if old_text in self._text_index:
+            self._text_index[old_text].remove(label_element)
+            if not self._text_index[old_text]:
+                del self._text_index[old_text]
+
+        # Add to new text index
+        new_text = label_element.text
+        if new_text not in self._text_index:
+            self._text_index[new_text] = []
+        self._text_index[new_text].append(label_element)
+
+    def _mark_modified(self):
+        """Mark collection as modified."""
+        self._modified = True
+
+    # Collection interface methods
+    def __len__(self) -> int:
+        """Return number of labels."""
+        return len(self._labels)
+
+    def __iter__(self) -> Iterator[LabelElement]:
+        """Iterate over labels."""
+        return iter(self._labels)
+
+    def __getitem__(self, index: int) -> LabelElement:
+        """Get label by index."""
+        return self._labels[index]
+
+    def __bool__(self) -> bool:
+        """Return True if collection has labels."""
+        return len(self._labels) > 0

kicad_sch_api/core/managers/__init__.py

@@ -0,0 +1,26 @@
+"""
+Schematic management modules for separating responsibilities.
+
+This package contains specialized managers for different aspects of schematic
+manipulation, enabling clean separation of concerns and better maintainability.
+"""
+
+from .file_io import FileIOManager
+from .format_sync import FormatSyncManager
+from .graphics import GraphicsManager
+from .metadata import MetadataManager
+from .sheet import SheetManager
+from .text_elements import TextElementManager
+from .validation import ValidationManager
+from .wire import WireManager
+
+__all__ = [
+    "FileIOManager",
+    "FormatSyncManager",
+    "GraphicsManager",
+    "MetadataManager",
+    "SheetManager",
+    "TextElementManager",
+    "ValidationManager",
+    "WireManager",
+]

kicad_sch_api/core/managers/file_io.py

@@ -0,0 +1,243 @@
+"""
+File I/O Manager for KiCAD schematic operations.
+
+Handles all file system interactions including loading, saving, and backup operations
+while maintaining exact format preservation.
+"""
+
+import logging
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+from ...utils.validation import ValidationError
+from ..formatter import ExactFormatter
+from ..parser import SExpressionParser
+
+logger = logging.getLogger(__name__)
+
+
+class FileIOManager:
+    """
+    Manages file I/O operations for KiCAD schematics.
+
+    Responsible for:
+    - Loading schematic files with validation
+    - Saving with format preservation
+    - Creating backup files
+    - Managing file paths and metadata
+    """
+
+    def __init__(self):
+        """Initialize the FileIOManager."""
+        self._parser = SExpressionParser(preserve_format=True)
+        self._formatter = ExactFormatter()
+
+    def load_schematic(self, file_path: Union[str, Path]) -> Dict[str, Any]:
+        """
+        Load a KiCAD schematic file.
+
+        Args:
+            file_path: Path to .kicad_sch file
+
+        Returns:
+            Parsed schematic data
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValidationError: If file is invalid or corrupted
+        """
+        start_time = time.time()
+        file_path = Path(file_path)
+
+        if not file_path.exists():
+            raise FileNotFoundError(f"Schematic file not found: {file_path}")
+
+        if not file_path.suffix == ".kicad_sch":
+            raise ValidationError(f"Not a KiCAD schematic file: {file_path}")
+
+        logger.info(f"Loading schematic: {file_path}")
+
+        try:
+            schematic_data = self._parser.parse_file(file_path)
+            load_time = time.time() - start_time
+            logger.info(f"Loaded schematic in {load_time:.3f}s")
+
+            return schematic_data
+
+        except Exception as e:
+            logger.error(f"Failed to load schematic {file_path}: {e}")
+            raise ValidationError(f"Invalid schematic file: {e}") from e
+
+    def save_schematic(
+        self,
+        schematic_data: Dict[str, Any],
+        file_path: Union[str, Path],
+        preserve_format: bool = True,
+    ) -> None:
+        """
+        Save schematic data to file.
+
+        Args:
+            schematic_data: Schematic data to save
+            file_path: Target file path
+            preserve_format: Whether to preserve exact formatting
+
+        Raises:
+            PermissionError: If file cannot be written
+            ValidationError: If data is invalid
+        """
+        start_time = time.time()
+        file_path = Path(file_path)
+
+        logger.info(f"Saving schematic: {file_path}")
+
+        try:
+            # Ensure parent directory exists
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Convert to S-expression format and save
+            sexp_data = self._parser._schematic_data_to_sexp(schematic_data)
+            formatted_content = self._formatter.format(sexp_data)
+
+            with open(file_path, "w", encoding="utf-8") as f:
+                f.write(formatted_content)
+
+            save_time = time.time() - start_time
+            logger.info(f"Saved schematic in {save_time:.3f}s")
+
+        except PermissionError as e:
+            logger.error(f"Permission denied saving to {file_path}: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Failed to save schematic to {file_path}: {e}")
+            raise ValidationError(f"Save failed: {e}") from e
+
+    def create_backup(self, file_path: Union[str, Path], suffix: str = ".backup") -> Path:
+        """
+        Create a backup copy of the schematic file.
+
+        Args:
+            file_path: Source file to backup
+            suffix: Backup file suffix
+
+        Returns:
+            Path to backup file
+
+        Raises:
+            FileNotFoundError: If source file doesn't exist
+            PermissionError: If backup cannot be created
+        """
+        file_path = Path(file_path)
+
+        if not file_path.exists():
+            raise FileNotFoundError(f"Cannot backup non-existent file: {file_path}")
+
+        # Create backup with timestamp if suffix doesn't include one
+        if suffix == ".backup":
+            timestamp = time.strftime("%Y%m%d_%H%M%S")
+            backup_path = file_path.with_suffix(f".{timestamp}.backup")
+        else:
+            backup_path = file_path.with_suffix(f"{file_path.suffix}{suffix}")
+
+        try:
+            # Copy file content
+            backup_path.write_bytes(file_path.read_bytes())
+            logger.info(f"Created backup: {backup_path}")
+            return backup_path
+
+        except Exception as e:
+            logger.error(f"Failed to create backup {backup_path}: {e}")
+            raise PermissionError(f"Backup failed: {e}") from e
+
+    def validate_file_path(self, file_path: Union[str, Path]) -> Path:
+        """
+        Validate and normalize a file path for schematic operations.
+
+        Args:
+            file_path: Path to validate
+
+        Returns:
+            Normalized Path object
+
+        Raises:
+            ValidationError: If path is invalid
+        """
+        file_path = Path(file_path)
+
+        # Ensure .kicad_sch extension
+        if not file_path.suffix:
+            file_path = file_path.with_suffix(".kicad_sch")
+        elif file_path.suffix != ".kicad_sch":
+            raise ValidationError(f"Invalid schematic file extension: {file_path.suffix}")
+
+        # Validate path characters
+        try:
+            file_path.resolve()
+        except (OSError, ValueError) as e:
+            raise ValidationError(f"Invalid file path: {e}") from e
+
+        return file_path
+
+    def get_file_info(self, file_path: Union[str, Path]) -> Dict[str, Any]:
+        """
+        Get file system information about a schematic file.
+
+        Args:
+            file_path: Path to analyze
+
+        Returns:
+            Dictionary with file information
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+        """
+        file_path = Path(file_path)
+
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        stat = file_path.stat()
+
+        return {
+            "path": str(file_path.resolve()),
+            "size": stat.st_size,
+            "modified": stat.st_mtime,
+            "created": getattr(stat, "st_birthtime", stat.st_ctime),
+            "readable": file_path.is_file() and file_path.exists(),
+            "writable": file_path.parent.exists() and file_path.parent.is_dir(),
+            "extension": file_path.suffix,
+        }
+
+    def create_empty_schematic_data(self) -> Dict[str, Any]:
+        """
+        Create empty schematic data structure.
+
+        Returns:
+            Empty schematic data dictionary
+        """
+        return {
+            "kicad_sch": {
+                "version": 20230819,
+                "generator": "kicad-sch-api",
+                "uuid": None,  # Will be set by calling code
+                "paper": "A4",
+                "lib_symbols": {},
+                "symbol": [],
+                "wire": [],
+                "junction": [],
+                "label": [],
+                "hierarchical_label": [],
+                "global_label": [],
+                "text": [],
+                "text_box": [],
+                "polyline": [],
+                "rectangle": [],
+                "circle": [],
+                "arc": [],
+                "image": [],
+                "sheet": [],
+                "sheet_instances": [],
+                "symbol_instances": [],
+            }
+        }