kicad-sch-api 0.0.2__tar.gz → 0.1.0__tar.gz

{kicad_sch_api-0.0.2 → kicad_sch_api-0.1.0}/.claude/commands/dev/review-implementation.md

@@ -29,7 +29,7 @@ Performs comprehensive code review and analysis of kicad-sch-api implementation,
 - **Error handling** comprehensiveness and clarity
 
 **Key Questions**:
-- Does the API feel intuitive compared to kicad-skip?
+- Does the API feel intuitive and pythonic?
 - Are bulk operations efficient for large schematics?
 - Is format preservation truly exact?
 - Do validation errors provide actionable feedback?
@@ -167,6 +167,6 @@ The review generates:
 - **Performance benchmarks** vs. targets
 - **API usability** assessment
 - **Improvement recommendations** prioritized by impact
-- **Comparison analysis** vs. kicad-skip and other alternatives
+- **Comparison analysis** vs. other schematic manipulation solutions
 
 This ensures kicad-sch-api maintains professional quality standards while providing superior functionality to existing solutions.

{kicad_sch_api-0.0.2 → kicad_sch_api-0.1.0}/MANIFEST.in

@@ -10,15 +10,15 @@ include LICENSE
 include pyproject.toml
 
 # Include Python package data
-recursive-include python/kicad_sch_api *.py
-recursive-include python/kicad_sch_api *.json
-recursive-include python/kicad_sch_api *.yaml
-recursive-include python/kicad_sch_api *.yml
+recursive-include kicad_sch_api *.py
+recursive-include kicad_sch_api *.json
+recursive-include kicad_sch_api *.yaml
+recursive-include kicad_sch_api *.yml
 
 # Include test data (for validation)
-recursive-include python/tests/reference_kicad_projects *.kicad_sch
-recursive-include python/tests/reference_kicad_projects *.kicad_pro
-recursive-include python/tests/reference_kicad_projects *.md
+recursive-include tests/reference_tests/reference_kicad_projects *.kicad_sch
+recursive-include tests/reference_tests/reference_kicad_projects *.kicad_pro
+recursive-include tests/reference_tests/reference_kicad_projects *.md
 
 # Include MCP server as documentation/examples
 recursive-include mcp-server/src *.ts

{kicad_sch_api-0.0.2 → kicad_sch_api-0.1.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: kicad-sch-api
-Version: 0.0.2
+Version: 0.1.0
 Summary: Professional KiCAD schematic manipulation library with exact format preservation and AI agent integration
 Author-email: Circuit-Synth <info@circuit-synth.com>
 Maintainer-email: Circuit-Synth <info@circuit-synth.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/circuit-synth/kicad-sch-api
 Project-URL: Documentation, https://circuit-synth.github.io/kicad-sch-api/
 Project-URL: Repository, https://github.com/circuit-synth/kicad-sch-api.git
@@ -15,7 +15,6 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
@@ -59,13 +58,13 @@ Dynamic: license-file
 
 ## 🆚 vs. Existing Solutions
 
-| Feature | kicad-sch-api | kicad-skip | KiCAD Official API |
-|---------|---------------|------------|-------------------|
-| **Schematic Support** | ✅ Full | ✅ Full | ❌ PCB Only |
+| Feature | kicad-sch-api | Other Solutions | KiCAD Official API |
+|---------|---------------|-----------------|-------------------|
+| **Schematic Support** | ✅ Full | ⚠️ Varies | ❌ PCB Only |
 | **Format Preservation** | ✅ Exact | ❌ Basic | N/A |
 | **Performance** | ✅ Optimized | ⚠️ Basic | N/A |
-| **Library Management** | ✅ Advanced | ⚠️ Basic | N/A |
-| **Runtime Dependencies** | ❌ None | ❌ None | ✅ KiCAD Required |
+| **Library Management** | ✅ Advanced | ⚠️ Limited | N/A |
+| **Runtime Dependencies** | ❌ None | ⚠️ Varies | ✅ KiCAD Required |
 
 ## 📦 Installation
 
@@ -89,22 +88,19 @@ npm run build
 ```python
 import kicad_sch_api as ksa
 
-# Load existing schematic
-sch = ksa.load_schematic('my_circuit.kicad_sch')
+# Create new schematic
+sch = ksa.create_schematic('My Circuit')
 
 # Add components
-resistor = sch.components.add('Device:R', ref='R1', value='10k', pos=(100, 100))
-capacitor = sch.components.add('Device:C', ref='C1', value='0.1uF', pos=(150, 100))
+resistor = sch.components.add('Device:R', reference='R1', value='10k', position=(100, 100))
+capacitor = sch.components.add('Device:C', reference='C1', value='0.1uF', position=(150, 100))
 
 # Update properties
 resistor.footprint = 'Resistor_SMD:R_0603_1608Metric'
 resistor.set_property('MPN', 'RC0603FR-0710KL')
 
-# Connect components
-sch.add_wire(resistor.get_pin_position('2'), capacitor.get_pin_position('1'))
-
 # Save with exact format preservation
-sch.save()  # Preserves original formatting exactly
+sch.save('my_circuit.kicad_sch')
 ```
 
 ### Advanced Operations
@@ -204,7 +200,7 @@ MIT License - see [LICENSE](LICENSE) for details.
 ## 🔗 Related Projects
 
 - **[circuit-synth](https://github.com/circuit-synth/circuit-synth)**: Comprehensive circuit design automation
-- **[kicad-skip](https://github.com/psychogenic/kicad-skip)**: Foundation S-expression parser
+- **[sexpdata](https://github.com/jd-boyd/sexpdata)**: S-expression parsing library
 
 ---
 

{kicad_sch_api-0.0.2 → kicad_sch_api-0.1.0}/README.md

@@ -14,13 +14,13 @@
 
 ## 🆚 vs. Existing Solutions
 
-| Feature | kicad-sch-api | kicad-skip | KiCAD Official API |
-|---------|---------------|------------|-------------------|
-| **Schematic Support** | ✅ Full | ✅ Full | ❌ PCB Only |
+| Feature | kicad-sch-api | Other Solutions | KiCAD Official API |
+|---------|---------------|-----------------|-------------------|
+| **Schematic Support** | ✅ Full | ⚠️ Varies | ❌ PCB Only |
 | **Format Preservation** | ✅ Exact | ❌ Basic | N/A |
 | **Performance** | ✅ Optimized | ⚠️ Basic | N/A |
-| **Library Management** | ✅ Advanced | ⚠️ Basic | N/A |
-| **Runtime Dependencies** | ❌ None | ❌ None | ✅ KiCAD Required |
+| **Library Management** | ✅ Advanced | ⚠️ Limited | N/A |
+| **Runtime Dependencies** | ❌ None | ⚠️ Varies | ✅ KiCAD Required |
 
 ## 📦 Installation
 
@@ -44,22 +44,19 @@ npm run build
 ```python
 import kicad_sch_api as ksa
 
-# Load existing schematic
-sch = ksa.load_schematic('my_circuit.kicad_sch')
+# Create new schematic
+sch = ksa.create_schematic('My Circuit')
 
 # Add components
-resistor = sch.components.add('Device:R', ref='R1', value='10k', pos=(100, 100))
-capacitor = sch.components.add('Device:C', ref='C1', value='0.1uF', pos=(150, 100))
+resistor = sch.components.add('Device:R', reference='R1', value='10k', position=(100, 100))
+capacitor = sch.components.add('Device:C', reference='C1', value='0.1uF', position=(150, 100))
 
 # Update properties
 resistor.footprint = 'Resistor_SMD:R_0603_1608Metric'
 resistor.set_property('MPN', 'RC0603FR-0710KL')
 
-# Connect components
-sch.add_wire(resistor.get_pin_position('2'), capacitor.get_pin_position('1'))
-
 # Save with exact format preservation
-sch.save()  # Preserves original formatting exactly
+sch.save('my_circuit.kicad_sch')
 ```
 
 ### Advanced Operations
@@ -159,7 +156,7 @@ MIT License - see [LICENSE](LICENSE) for details.
 ## 🔗 Related Projects
 
 - **[circuit-synth](https://github.com/circuit-synth/circuit-synth)**: Comprehensive circuit design automation
-- **[kicad-skip](https://github.com/psychogenic/kicad-skip)**: Foundation S-expression parser
+- **[sexpdata](https://github.com/jd-boyd/sexpdata)**: S-expression parsing library
 
 ---
 

kicad_sch_api-0.1.0/examples/advanced_usage.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""
+Advanced usage example for kicad-sch-api.
+
+Demonstrates advanced features like bulk operations, filtering,
+validation, and performance optimization for large schematics.
+"""
+
+import time
+
+import kicad_sch_api as ksa
+from kicad_sch_api.core.types import Point
+
+
+def create_resistor_network():
+    """Create a large resistor network to demonstrate performance."""
+    print("🏗️ Creating large resistor network...")
+
+    sch = ksa.create_schematic("Resistor Network")
+
+    # Create a 10x10 grid of resistors (100 total)
+    resistors = []
+    start_time = time.time()
+
+    for row in range(10):
+        for col in range(10):
+            ref = f"R{row*10 + col + 1}"
+            value = f"{(row + 1) * (col + 1)}k"  # Varied values
+            position = (col * 15 + 50, row * 15 + 50)  # 15mm spacing
+
+            resistor = sch.components.add(
+                lib_id="Device:R",
+                reference=ref,
+                value=value,
+                position=position,
+                footprint="Resistor_SMD:R_0603_1608Metric",
+            )
+            resistors.append(resistor)
+
+    creation_time = time.time() - start_time
+    print(f"✅ Created {len(resistors)} resistors in {creation_time:.3f}s")
+
+    return sch, resistors
+
+
+def demonstrate_filtering():
+    """Demonstrate advanced component filtering capabilities."""
+    print("\n🔍 Advanced Component Filtering:")
+
+    sch, resistors = create_resistor_network()
+
+    # Filter by lib_id
+    all_resistors = sch.components.filter(lib_id="Device:R")
+    print(f"  All resistors: {len(all_resistors)}")
+
+    # Filter by value pattern
+    high_value = sch.components.filter(value_pattern="k")
+    print(f"  High value (k-ohm): {len(high_value)}")
+
+    # Filter by reference pattern
+    import re
+
+    top_row = sch.components.filter(reference_pattern=r"R[1-9]$")  # R1-R9
+    print(f"  Top row (R1-R9): {len(top_row)}")
+
+    # Spatial filtering
+    center_area = sch.components.in_area(80, 80, 120, 120)
+    print(f"  Components in center area: {len(center_area)}")
+
+    # Proximity filtering
+    center_point = Point(100, 100)
+    nearby = sch.components.near_point(center_point, radius=30)
+    print(f"  Components near center: {len(nearby)}")
+
+    return sch
+
+
+def demonstrate_bulk_operations():
+    """Demonstrate bulk update operations for large schematics."""
+    print("\n⚡ Bulk Operations Performance:")
+
+    sch = demonstrate_filtering()
+
+    # Bulk update all resistors
+    start_time = time.time()
+
+    updated_count = sch.components.bulk_update(
+        criteria={"lib_id": "Device:R"},
+        updates={
+            "properties": {
+                "Tolerance": "1%",
+                "Power": "0.1W",
+                "Manufacturer": "Yageo",
+                "Temperature_Coefficient": "100ppm/K",
+            }
+        },
+    )
+
+    bulk_time = time.time() - start_time
+    print(f"✅ Bulk updated {updated_count} components in {bulk_time:.3f}s")
+    print(f"  Performance: {bulk_time/updated_count*1000:.2f}ms per component")
+
+    # Verify updates applied
+    sample_resistor = sch.components.get("R1")
+    if sample_resistor:
+        print(f"  Sample properties: {len(sample_resistor.properties)} properties set")
+        print(f"    Tolerance: {sample_resistor.get_property('Tolerance')}")
+        print(f"    Power: {sample_resistor.get_property('Power')}")
+
+    return sch
+
+
+def demonstrate_performance_monitoring():
+    """Demonstrate performance monitoring and statistics."""
+    print("\n📊 Performance Monitoring:")
+
+    sch = demonstrate_bulk_operations()
+
+    # Get comprehensive performance statistics
+    stats = sch.get_performance_stats()
+
+    print("  Schematic Performance:")
+    schematic_stats = stats.get("schematic", {})
+    print(f"    Operations: {schematic_stats.get('operation_count', 0)}")
+    print(f"    Avg time: {schematic_stats.get('avg_operation_time_ms', 0):.2f}ms")
+
+    print("  Component Collection:")
+    component_stats = stats.get("components", {})
+    print(f"    Total components: {component_stats.get('total_components', 0)}")
+    print(f"    Unique references: {component_stats.get('unique_references', 0)}")
+    print(f"    Libraries used: {component_stats.get('libraries_used', 0)}")
+
+    print("  Symbol Cache:")
+    cache_stats = stats.get("symbol_cache", {})
+    print(f"    Cache hit rate: {cache_stats.get('hit_rate_percent', 0):.1f}%")
+    print(f"    Symbols cached: {cache_stats.get('total_symbols_cached', 0)}")
+    print(f"    Total load time: {cache_stats.get('total_load_time_ms', 0):.1f}ms")
+
+    return sch
+
+
+def demonstrate_validation_and_error_handling():
+    """Demonstrate comprehensive validation and error handling."""
+    print("\n✅ Validation and Error Handling:")
+
+    sch = ksa.create_schematic("Validation Test")
+
+    # Add valid components
+    sch.components.add("Device:R", "R1", "10k", (100, 50))
+    sch.components.add("Device:C", "C1", "0.1uF", (150, 50))
+
+    # Test validation
+    issues = sch.validate()
+    print(f"  Validation issues found: {len(issues)}")
+
+    # Categorize issues
+    errors = [issue for issue in issues if issue.level.value in ("error", "critical")]
+    warnings = [issue for issue in issues if issue.level.value == "warning"]
+
+    print(f"    Errors: {len(errors)}")
+    print(f"    Warnings: {len(warnings)}")
+
+    if issues:
+        print("  Issue details:")
+        for issue in issues[:3]:  # Show first 3
+            print(f"    {issue.level.value.upper()}: {issue.message}")
+
+    # Demonstrate error handling
+    print("\n🛡️ Error Handling Examples:")
+
+    try:
+        # Try to add component with invalid reference
+        sch.components.add("Device:R", "1R", "10k")  # Invalid reference
+    except ksa.ValidationError as e:
+        print(f"  ✅ Caught validation error: {e}")
+
+    try:
+        # Try to add duplicate reference
+        sch.components.add("Device:C", "R1", "22uF")  # Duplicate reference
+    except ksa.ValidationError as e:
+        print(f"  ✅ Caught duplicate reference: {e}")
+
+    try:
+        # Try invalid lib_id
+        sch.components.add("InvalidFormat", "R5", "10k")  # Missing colon
+    except ksa.ValidationError as e:
+        print(f"  ✅ Caught invalid lib_id: {e}")
+
+    return sch
+
+
+def demonstrate_format_preservation():
+    """Demonstrate exact format preservation capabilities."""
+    print("\n💎 Format Preservation:")
+
+    sch = ksa.create_schematic("Format Test")
+    sch.components.add("Device:R", "R1", "10k", (100, 50))
+
+    import os
+    import tempfile
+
+    # Save with format preservation
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".kicad_sch", delete=False) as f:
+        output_path = f.name
+
+    try:
+        start_time = time.time()
+        sch.save(output_path, preserve_format=True)
+        save_time = time.time() - start_time
+
+        print(f"  ✅ Saved with format preservation in {save_time:.3f}s")
+
+        # Reload and verify
+        start_time = time.time()
+        sch2 = ksa.load_schematic(output_path)
+        load_time = time.time() - start_time
+
+        print(f"  ✅ Reloaded in {load_time:.3f}s")
+        print(f"  ✅ Component preservation: {len(sch2.components)} components")
+
+        # Verify component data preserved
+        r1_original = sch.components.get("R1")
+        r1_reloaded = sch2.components.get("R1")
+
+        if r1_original and r1_reloaded:
+            print(f"    Reference: {r1_reloaded.reference} ✅")
+            print(f"    Value: {r1_reloaded.value} ✅")
+            print(f"    Position: {r1_reloaded.position} ✅")
+            print(f"    Lib ID: {r1_reloaded.lib_id} ✅")
+
+    finally:
+        if os.path.exists(output_path):
+            os.unlink(output_path)
+
+
+def demonstrate_library_integration():
+    """Demonstrate symbol library integration."""
+    print("\n📚 Symbol Library Integration:")
+
+    # Get global symbol cache
+    cache = ksa.get_symbol_cache()
+
+    # Library discovery
+    discovered = cache.discover_libraries()
+    print(f"  Libraries discovered: {discovered}")
+
+    # Symbol search
+    symbols = cache.search_symbols("resistor", limit=5)
+    print(f"  Resistor symbols found: {len(symbols)}")
+
+    for symbol in symbols[:3]:  # Show first 3
+        print(f"    {symbol.lib_id}: {symbol.description}")
+
+    # Cache performance
+    cache_stats = cache.get_performance_stats()
+    print(f"  Cache performance:")
+    print(f"    Hit rate: {cache_stats.get('hit_rate_percent', 0):.1f}%")
+    print(f"    Total symbols: {cache_stats.get('total_symbols_cached', 0)}")
+
+
+def main():
+    """Run all advanced usage examples."""
+    print("🚀 kicad-sch-api Advanced Usage Examples")
+    print("=" * 60)
+
+    try:
+        # Run all demonstrations
+        demonstrate_filtering()
+        demonstrate_bulk_operations()
+        demonstrate_performance_monitoring()
+        demonstrate_validation_and_error_handling()
+        demonstrate_format_preservation()
+        demonstrate_library_integration()
+
+        print("\n🎉 All advanced examples completed successfully!")
+        print("\nAdvanced features demonstrated:")
+        print("  ✅ High-performance component collections")
+        print("  ✅ Bulk operations for large schematics")
+        print("  ✅ Comprehensive validation and error handling")
+        print("  ✅ Exact format preservation")
+        print("  ✅ Symbol library caching and discovery")
+        print("  ✅ Performance monitoring and statistics")
+
+    except Exception as e:
+        print(f"\n❌ Example failed: {e}")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()

kicad_sch_api-0.1.0/examples/basic_usage.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""
+Basic usage example for kicad-sch-api.
+
+This example demonstrates the core functionality of kicad-sch-api,
+showing how to create, manipulate, and save KiCAD schematic files.
+"""
+
+import kicad_sch_api as ksa
+
+
+def main():
+    """Demonstrate basic kicad-sch-api usage."""
+    print("🚀 kicad-sch-api Basic Usage Example")
+    print("=" * 50)
+
+    # 1. Create a new schematic
+    print("\n📋 Creating new schematic...")
+    sch = ksa.create_schematic("Voltage Divider Example")
+    print(f"✅ Created schematic: {sch.title_block.get('title', 'Untitled')}")
+
+    # 2. Add components
+    print("\n🔧 Adding components...")
+
+    # Add input resistor
+    r1 = sch.components.add(
+        lib_id="Device:R",
+        reference="R1",
+        value="10k",
+        position=(100, 100),
+        footprint="Resistor_SMD:R_0603_1608Metric",
+    )
+    print(f"✅ Added {r1.reference}: {r1.value} at {r1.position}")
+
+    # Add output resistor
+    r2 = sch.components.add(
+        lib_id="Device:R",
+        reference="R2",
+        value="10k",
+        position=(100, 150),
+        footprint="Resistor_SMD:R_0603_1608Metric",
+    )
+    print(f"✅ Added {r2.reference}: {r2.value} at {r2.position}")
+
+    # Add input capacitor for filtering
+    c1 = sch.components.add(
+        lib_id="Device:C",
+        reference="C1",
+        value="0.1uF",
+        position=(50, 125),
+        footprint="Capacitor_SMD:C_0603_1608Metric",
+    )
+    print(f"✅ Added {c1.reference}: {c1.value} at {c1.position}")
+
+    # 3. Set component properties
+    print("\n📝 Setting component properties...")
+
+    r1.set_property("MPN", "RC0603FR-0710KL")
+    r1.set_property("Tolerance", "1%")
+    r2.set_property("MPN", "RC0603FR-0710KL")
+    r2.set_property("Tolerance", "1%")
+    c1.set_property("MPN", "CL10B104KB8NNNC")
+    c1.set_property("Voltage", "50V")
+
+    print(f"✅ Set properties for all components")
+
+    # 4. Add connections
+    print("\n🔗 Adding wire connections...")
+
+    # Get pin positions for connections
+    r1_pin1 = r1.get_pin_position("1")  # Top of R1
+    r1_pin2 = r1.get_pin_position("2")  # Bottom of R1
+    r2_pin1 = r2.get_pin_position("1")  # Top of R2
+    r2_pin2 = r2.get_pin_position("2")  # Bottom of R2
+    c1_pin1 = c1.get_pin_position("1")  # Left of C1
+
+    if all([r1_pin1, r1_pin2, r2_pin1, r2_pin2, c1_pin1]):
+        # Connect R1 bottom to R2 top (voltage divider middle)
+        wire1 = sch.add_wire(r1_pin2, r2_pin1)
+        print(f"✅ Connected R1 pin 2 to R2 pin 1")
+
+        # Connect input capacitor to R1 top
+        wire2 = sch.add_wire(c1_pin1, r1_pin1)
+        print(f"✅ Connected C1 to R1 input")
+    else:
+        print("⚠️ Could not determine pin positions for connections")
+
+    # 5. Display schematic information
+    print("\n📊 Schematic Summary:")
+    summary = sch.get_summary()
+    print(f"  Components: {summary['component_count']}")
+    print(f"  Title: {summary['title']}")
+    print(f"  Modified: {summary['modified']}")
+
+    # 6. Component analysis
+    print("\n🔍 Component Analysis:")
+
+    # Find all resistors
+    resistors = sch.components.filter(lib_id="Device:R")
+    print(f"  Resistors found: {len(resistors)}")
+
+    # Find components by value
+    ten_k_components = sch.components.filter(value="10k")
+    print(f"  10k components: {len(ten_k_components)}")
+
+    # Find components in area
+    left_side = sch.components.in_area(40, 90, 80, 160)
+    print(f"  Components on left side: {len(left_side)}")
+
+    # 7. Bulk operations
+    print("\n⚡ Bulk Operations:")
+
+    # Update all resistors with tolerance
+    updated_count = sch.components.bulk_update(
+        criteria={"lib_id": "Device:R"}, updates={"properties": {"Power": "0.1W"}}
+    )
+    print(f"✅ Updated {updated_count} resistors with power rating")
+
+    # 8. Validation
+    print("\n✅ Validation:")
+    issues = sch.validate()
+    errors = [issue for issue in issues if issue.level.value in ("error", "critical")]
+    warnings = [issue for issue in issues if issue.level.value == "warning"]
+
+    print(f"  Validation issues: {len(issues)} total")
+    print(f"  Errors: {len(errors)}")
+    print(f"  Warnings: {len(warnings)}")
+
+    if errors:
+        print("  ❌ Critical errors found:")
+        for error in errors[:3]:  # Show first 3
+            print(f"    - {error}")
+    else:
+        print("  ✅ No critical errors found")
+
+    # 9. Performance statistics
+    print("\n⚡ Performance Statistics:")
+    perf_stats = sch.get_performance_stats()
+
+    if "symbol_cache" in perf_stats:
+        cache_stats = perf_stats["symbol_cache"]
+        print(f"  Symbol cache hit rate: {cache_stats.get('hit_rate_percent', 0)}%")
+        print(f"  Symbols cached: {cache_stats.get('total_symbols_cached', 0)}")
+
+    comp_stats = perf_stats.get("components", {})
+    print(f"  Total components: {comp_stats.get('total_components', 0)}")
+
+    # 10. Save schematic
+    print("\n💾 Saving schematic...")
+    import os
+    import tempfile
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".kicad_sch", delete=False) as f:
+        output_path = f.name
+
+    try:
+        sch.save(output_path, preserve_format=True)
+        print(f"✅ Saved schematic to: {output_path}")
+
+        # Verify file was created and has content
+        file_size = os.path.getsize(output_path)
+        print(f"  File size: {file_size} bytes")
+
+        # Quick validation by reloading
+        sch2 = ksa.load_schematic(output_path)
+        print(f"✅ Reload verification: {len(sch2.components)} components")
+
+    finally:
+        # Clean up temporary file
+        if os.path.exists(output_path):
+            os.unlink(output_path)
+            print(f"🧹 Cleaned up temporary file")
+
+    print("\n🎉 Basic usage example completed successfully!")
+    print("\nKey takeaways:")
+    print("  • Modern API: Clean, pythonic interface for schematic manipulation")
+    print("  • Fast operations: O(1) component lookup and bulk updates")
+    print("  • Format preservation: Exact KiCAD compatibility guaranteed")
+    print("  • Professional validation: Comprehensive error detection")
+    print("  • Performance monitoring: Built-in statistics and optimization")
+
+
+if __name__ == "__main__":
+    main()