# KiCAD Schematic API
[](https://kicad-sch-api.readthedocs.io/en/latest/?badge=latest)
[](https://badge.fury.io/py/kicad-sch-api)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
**Professional Python library for KiCAD schematic file manipulation with exact format preservation**
## Overview
Create and manipulate KiCAD schematic files programmatically with guaranteed exact format preservation. This library serves as the foundation for EDA automation tools and AI agents that need reliable, professional-grade schematic manipulation capabilities.
## 🎯 Core Features
- **📋 Exact Format Preservation**: Byte-perfect KiCAD output that matches native formatting
- **🏗️ Professional Component Management**: Object-oriented collections with search and validation
- **⚡ High Performance**: Optimized for large schematics with intelligent caching
- **🔍 Real KiCAD Library Integration**: Access to actual KiCAD symbol libraries and validation
- **📐 Component Bounding Boxes**: Precise component boundary calculation and visualization
- **🎨 Colored Rectangle Graphics**: KiCAD-compatible rectangles with all stroke types and colors
- **🛣️ Manhattan Routing**: Intelligent wire routing with obstacle avoidance
- **🤖 AI Agent Ready**: MCP server for seamless integration with AI development tools
- **📚 Hierarchical Design**: Complete support for multi-sheet schematic projects
## 🚀 Quick Start
### Installation
```bash
# Install from PyPI
pip install kicad-sch-api
# Or install from source
git clone https://github.com/circuit-synth/kicad-sch-api.git
cd kicad-sch-api/python
uv pip install -e .
```
### Basic Usage
```python
import kicad_sch_api as ksa
# Create a new schematic
sch = ksa.create_schematic("My Circuit")
# Add components with proper validation
resistor = sch.components.add(
lib_id="Device:R",
reference="R1",
value="10k",
position=(100.0, 100.0),
footprint="Resistor_SMD:R_0603_1608Metric",
datasheet="~",
description="Resistor"
)
capacitor = sch.components.add(
lib_id="Device:C",
reference="C1",
value="100nF",
position=(150.0, 100.0),
footprint="Capacitor_SMD:C_0603_1608Metric"
)
# Add wires for connectivity
sch.wires.add(start=(100, 110), end=(150, 110))
# Pin-to-pin wiring (NEW in v0.3.1)
wire_uuid = sch.add_wire_between_pins("R1", "2", "C1", "1") # Connect R1 pin 2 to C1 pin 1
external_wire = sch.add_wire_to_pin((50, 100), "R1", "1") # Connect external point to R1 pin 1
# Add labels for nets
sch.add_label("VCC", position=(125, 110))
# Save with exact format preservation
sch.save("my_circuit.kicad_sch")
```
### Hierarchical Design
```python
# Create main schematic with hierarchical sheet
main_sch = ksa.create_schematic("Main Board")
# Add hierarchical sheet
power_sheet = main_sch.add_hierarchical_sheet(
name="Power Supply",
filename="power.kicad_sch",
position=(100, 100),
size=(80, 60)
)
# Add sheet pins for connectivity
power_sheet.add_pin("VIN", pin_type="input", position=(0, 10))
power_sheet.add_pin("VOUT", pin_type="output", position=(80, 10))
# Create the sub-schematic
power_sch = ksa.create_schematic("Power Supply")
power_sch.add_hierarchical_label("VIN", label_type="input", position=(50, 25))
power_sch.add_hierarchical_label("VOUT", label_type="output", position=(150, 25))
# Save both schematics
main_sch.save("main.kicad_sch")
power_sch.save("power.kicad_sch")
```
## 🔧 Advanced Features
### Component Bounding Boxes and Colored Graphics (NEW in v0.3.1)
```python
from kicad_sch_api.core.component_bounds import get_component_bounding_box
# Add components
resistor = sch.components.add("Device:R", "R1", "10k", (100, 100))
opamp = sch.components.add("Amplifier_Operational:LM358", "U1", "LM358", (150, 100))
# Get component bounding boxes
bbox_body = get_component_bounding_box(resistor, include_properties=False)
bbox_full = get_component_bounding_box(resistor, include_properties=True)
# Draw colored bounding box rectangles
sch.draw_bounding_box(bbox_body, stroke_width=0.5, stroke_color="blue", stroke_type="solid")
sch.draw_bounding_box(bbox_full, stroke_width=0.3, stroke_color="red", stroke_type="dash")
# Draw bounding boxes for all components at once
bbox_uuids = sch.draw_component_bounding_boxes(
include_properties=True,
stroke_width=0.4,
stroke_color="green",
stroke_type="dot"
)
```
### Manhattan Routing with Obstacle Avoidance (NEW in v0.3.1)
```python
from kicad_sch_api.core.manhattan_routing import ManhattanRouter
from kicad_sch_api.core.types import Point
# Create router
router = ManhattanRouter()
# Add components that act as obstacles
r1 = sch.components.add("Device:R", "R1", "1k", (50, 50))
r2 = sch.components.add("Device:R", "R2", "2k", (150, 150))
obstacle = sch.components.add("Device:C", "C1", "100nF", (100, 100))
# Get obstacle bounding boxes
obstacle_bbox = get_component_bounding_box(obstacle, include_properties=False)
# Route around obstacles
start_point = Point(r1.position.x, r1.position.y)
end_point = Point(r2.position.x, r2.position.y)
path = router.route_between_points(start_point, end_point, [obstacle_bbox], clearance=2.0)
# Add wires along the path
for i in range(len(path) - 1):
sch.wires.add(path[i], path[i + 1])
```
### Pin-to-Pin Wiring
```python
# Connect component pins directly - automatically calculates pin positions
wire_uuid = sch.add_wire_between_pins("R1", "2", "R2", "1") # R1 pin 2 to R2 pin 1
# Connect arbitrary point to component pin
external_wire = sch.add_wire_to_pin((75, 125), "R1", "1") # External point to R1 pin 1
tuple_wire = sch.add_wire_to_pin(Point(100, 150), "C1", "2") # Using Point object
# Get component pin positions for advanced operations
pin_position = sch.get_component_pin_position("R1", "1")
if pin_position:
print(f"R1 pin 1 is at ({pin_position.x:.2f}, {pin_position.y:.2f})")
# Error handling - returns None for invalid components/pins
invalid_wire = sch.add_wire_between_pins("R999", "1", "R1", "1") # Returns None
```
### Component Bounding Box Visualization (NEW in v0.3.1)
```python
from kicad_sch_api.core.component_bounds import get_component_bounding_box
# Get component bounding box (body only)
resistor = sch.components.get("R1")
bbox = get_component_bounding_box(resistor, include_properties=False)
print(f"R1 body size: {bbox.width:.2f}×{bbox.height:.2f}mm")
# Get bounding box including properties (reference, value, etc.)
bbox_with_props = get_component_bounding_box(resistor, include_properties=True)
print(f"R1 with labels: {bbox_with_props.width:.2f}×{bbox_with_props.height:.2f}mm")
# Draw bounding box as rectangle graphics (for visualization/debugging)
rect_uuid = sch.draw_bounding_box(bbox)
print(f"Drew bounding box rectangle: {rect_uuid}")
# Draw bounding boxes for all components
bbox_uuids = sch.draw_component_bounding_boxes(
include_properties=False # True to include reference/value labels
)
print(f"Drew {len(bbox_uuids)} component bounding boxes")
# Expand bounding box for clearance analysis
expanded_bbox = bbox.expand(2.54) # Expand by 2.54mm (0.1 inch)
clearance_rect = sch.draw_bounding_box(expanded_bbox)
```
### Manhattan Routing with Obstacle Avoidance (NEW in v0.3.1)
```python
# Automatic Manhattan routing between component pins
wire_segments = sch.auto_route_pins(
"R1", "2", # From component R1, pin 2
"R2", "1", # To component R2, pin 1
routing_mode="manhattan", # Manhattan (L-shaped) routing
avoid_components=True # Avoid component bounding boxes
)
# Direct routing (straight line)
direct_wire = sch.auto_route_pins("C1", "1", "C2", "2", routing_mode="direct")
# Manual obstacle avoidance using bounding boxes
bbox_r1 = get_component_bounding_box(sch.components.get("R1"))
bbox_r2 = get_component_bounding_box(sch.components.get("R2"))
# Check if routing path intersects with component
def path_clear(start, end, obstacles):
# Custom collision detection logic
return not any(bbox.intersects_line(start, end) for bbox in obstacles)
```
### Component Search and Management
```python
# Search for components
resistors = sch.components.find(lib_id_pattern='Device:R*')
power_components = sch.components.filter(reference_pattern=r'U[0-9]+')
# Bulk updates
sch.components.bulk_update(
criteria={'lib_id': 'Device:R'},
updates={'properties': {'Tolerance': '1%'}}
)
# Component validation
validation_result = sch.components.validate_component(
'Device:R',
'Resistor_SMD:R_0603_1608Metric'
)
```
### Component and Element Removal
```python
# Remove components by reference
removed = sch.components.remove("R1") # Returns True if removed
# Remove wires, labels, and other elements
sch.remove_wire(wire_uuid)
sch.remove_label(label_uuid)
sch.remove_hierarchical_label(label_uuid)
# Remove from collections
sch.wires.remove(wire_uuid)
sch.junctions.remove(junction_uuid)
# lib_symbols are automatically cleaned up when last component of type is removed
```
### Configuration and Customization
```python
import kicad_sch_api as ksa
# Access global configuration
config = ksa.config
# Customize property positioning
config.properties.reference_y = -2.0 # Move reference labels higher
config.properties.value_y = 2.0 # Move value labels lower
# Customize tolerances and precision
config.tolerance.position_tolerance = 0.05 # Tighter position matching
config.tolerance.wire_segment_min = 0.005 # Different wire segment threshold
# Customize defaults
config.defaults.project_name = "my_company_project"
config.defaults.stroke_width = 0.1
# Grid and spacing customization
config.grid.unit_spacing = 10.0 # Tighter multi-unit IC spacing
config.grid.component_spacing = 5.0 # Closer component placement
# Sheet settings for hierarchical designs
config.sheet.name_offset_y = -1.0 # Different sheet label position
config.sheet.file_offset_y = 1.0 # Different file label position
```
### KiCAD Integration
```python
# Run electrical rules check using KiCAD CLI
erc_result = sch.run_erc_check()
print(f"ERC Status: {erc_result.status}")
for violation in erc_result.violations:
print(f"- {violation.type}: {violation.message}")
# Generate netlist for connectivity analysis
netlist = sch.generate_netlist()
net_info = netlist.analyze_net("VCC")
```
## 🤖 AI Agent Integration
This library serves as the foundation for AI agent integration. For Claude Code or other AI agents, use the **[mcp-kicad-sch-api](https://github.com/circuit-synth/mcp-kicad-sch-api)** MCP server.
## 🏗️ Architecture
### Library Structure
```
kicad-sch-api/
├── kicad_sch_api/ # Core Python library
│ ├── core/ # Core schematic manipulation
│ ├── library/ # KiCAD library integration
│ ├── discovery/ # Component search and indexing
│ └── utils/ # Validation and utilities
├── tests/ # Comprehensive test suite
└── examples/ # Usage examples and tutorials
```
### Design Principles
- **Building Block First**: Designed to be the foundation for other tools
- **Exact Format Preservation**: Guaranteed byte-perfect KiCAD output
- **Professional Quality**: Comprehensive error handling and validation
- **MCP Foundation**: Designed as a stable foundation for MCP servers and AI agents
- **Performance Optimized**: Fast operations on large schematics
## 🧪 Testing & Quality
```bash
# Run all tests (29 tests covering all functionality)
uv run pytest tests/ -v
# Format preservation tests (critical - exact KiCAD output matching)
uv run pytest tests/reference_tests/ -v
# Component removal tests (comprehensive removal functionality)
uv run pytest tests/test_*_removal.py -v
# Code quality checks
uv run black kicad_sch_api/ tests/
uv run mypy kicad_sch_api/
uv run flake8 kicad_sch_api/ tests/
```
### Test Categories
- **Format Preservation**: Byte-for-byte compatibility with KiCAD native files
- **Component Management**: Creation, modification, and removal of components
- **Element Operations**: Wires, labels, junctions, hierarchical sheets
- **Configuration**: Customizable settings and behavior
- **Performance**: Large schematic handling and optimization
- **Integration**: Real KiCAD library compatibility
## 🆚 Why This Library?
### vs. Direct KiCAD File Editing
- **Professional API**: High-level operations vs low-level S-expression manipulation
- **Guaranteed Format**: Byte-perfect output vs manual formatting
- **Validation**: Real KiCAD library integration and component validation
- **Performance**: Optimized collections vs manual iteration
### vs. Other Python KiCAD Libraries
- **Format Preservation**: Exact KiCAD compatibility vs approximate output
- **Modern Design**: Object-oriented collections vs legacy patterns
- **AI Integration**: Purpose-built MCP server vs no agent support
- **Professional Focus**: Production-ready vs exploration tools
## 🔗 Ecosystem
This library serves as the foundation for specialized tools and MCP servers:
```python
# Foundation library
import kicad_sch_api as ksa
# MCP servers and specialized libraries built on this foundation:
# - mcp-kicad-sch-api: Full MCP server for AI agents
# - kicad_sourcing_tools: Component sourcing extensions
# - kicad_placement_optimizer: Layout optimization
# - kicad_dfm_checker: Manufacturing validation
# Foundation provides reliable schematic manipulation
sch = ksa.load_schematic('project.kicad_sch')
# All extensions use the same stable API
# mcp_server.use_schematic(sch) # MCP server integration
# sourcing.update_sourcing(sch) # Component sourcing
# placement.optimize_layout(sch) # Layout optimization
# Foundation ensures exact format preservation
sch.save() # Guaranteed exact KiCAD format
```
## 📖 Documentation
Full documentation is available at **[kicad-sch-api.readthedocs.io](https://kicad-sch-api.readthedocs.io/)**
Quick links:
- **[Getting Started Guide](https://kicad-sch-api.readthedocs.io/en/latest/GETTING_STARTED.html)**: Complete beginner's tutorial
- **[API Reference](https://kicad-sch-api.readthedocs.io/en/latest/API_REFERENCE.html)**: Complete API documentation
- **[Recipes & Patterns](https://kicad-sch-api.readthedocs.io/en/latest/RECIPES.html)**: Practical examples
- **[Why Use This Library?](https://kicad-sch-api.readthedocs.io/en/latest/WHY_USE_THIS_LIBRARY.html)**: Value proposition and use cases
- **[Architecture](https://kicad-sch-api.readthedocs.io/en/latest/ARCHITECTURE.html)**: Internal design details
- **[Examples](examples/)**: Code examples and tutorials
## 🤝 Contributing
We welcome contributions! Key areas:
- KiCAD library integration and component validation
- Performance optimizations for large schematics
- Additional MCP tools for AI agents
- Test coverage and format preservation validation
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
## 🔗 Related Projects
- **[mcp-kicad-sch-api](https://github.com/circuit-synth/mcp-kicad-sch-api)**: MCP server for AI agents built on this library
- **[circuit-synth](https://github.com/circuit-synth/circuit-synth)**: High-level circuit design automation using this library
- **[Claude Code](https://claude.ai/code)**: AI development environment with MCP support
- **[KiCAD](https://kicad.org/)**: Open source electronics design automation suite
---
**Professional KiCAD schematic manipulation for the AI age ⚡**
Raw data
{
"_id": null,
"home_page": null,
"name": "kicad-sch-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Circuit-Synth <shane@circuit-synth.com>",
"keywords": "kicad, schematic, eda, electronics, circuit-design, ai, automation, pcb",
"author": null,
"author_email": "Circuit-Synth <shane@circuit-synth.com>",
"download_url": "https://files.pythonhosted.org/packages/60/83/10efcd5df4f04e8ea5f2f951a1b86eee1ff08c18006394b502ed500527ea/kicad_sch_api-0.4.2.tar.gz",
"platform": null,
"description": "# KiCAD Schematic API\n\n[](https://kicad-sch-api.readthedocs.io/en/latest/?badge=latest)\n[](https://badge.fury.io/py/kicad-sch-api)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n**Professional Python library for KiCAD schematic file manipulation with exact format preservation**\n\n## Overview\n\nCreate and manipulate KiCAD schematic files programmatically with guaranteed exact format preservation. This library serves as the foundation for EDA automation tools and AI agents that need reliable, professional-grade schematic manipulation capabilities.\n\n## \ud83c\udfaf Core Features\n\n- **\ud83d\udccb Exact Format Preservation**: Byte-perfect KiCAD output that matches native formatting\n- **\ud83c\udfd7\ufe0f Professional Component Management**: Object-oriented collections with search and validation\n- **\u26a1 High Performance**: Optimized for large schematics with intelligent caching\n- **\ud83d\udd0d Real KiCAD Library Integration**: Access to actual KiCAD symbol libraries and validation\n- **\ud83d\udcd0 Component Bounding Boxes**: Precise component boundary calculation and visualization\n- **\ud83c\udfa8 Colored Rectangle Graphics**: KiCAD-compatible rectangles with all stroke types and colors\n- **\ud83d\udee3\ufe0f Manhattan Routing**: Intelligent wire routing with obstacle avoidance\n- **\ud83e\udd16 AI Agent Ready**: MCP server for seamless integration with AI development tools\n- **\ud83d\udcda Hierarchical Design**: Complete support for multi-sheet schematic projects\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\n# Install from PyPI\npip install kicad-sch-api\n\n# Or install from source\ngit clone https://github.com/circuit-synth/kicad-sch-api.git\ncd kicad-sch-api/python\nuv pip install -e .\n```\n\n### Basic Usage\n\n```python\nimport kicad_sch_api as ksa\n\n# Create a new schematic\nsch = ksa.create_schematic(\"My Circuit\")\n\n# Add components with proper validation\nresistor = sch.components.add(\n lib_id=\"Device:R\",\n reference=\"R1\", \n value=\"10k\",\n position=(100.0, 100.0),\n footprint=\"Resistor_SMD:R_0603_1608Metric\",\n datasheet=\"~\",\n description=\"Resistor\"\n)\n\ncapacitor = sch.components.add(\n lib_id=\"Device:C\",\n reference=\"C1\", \n value=\"100nF\",\n position=(150.0, 100.0),\n footprint=\"Capacitor_SMD:C_0603_1608Metric\"\n)\n\n# Add wires for connectivity\nsch.wires.add(start=(100, 110), end=(150, 110))\n\n# Pin-to-pin wiring (NEW in v0.3.1)\nwire_uuid = sch.add_wire_between_pins(\"R1\", \"2\", \"C1\", \"1\") # Connect R1 pin 2 to C1 pin 1\nexternal_wire = sch.add_wire_to_pin((50, 100), \"R1\", \"1\") # Connect external point to R1 pin 1\n\n# Add labels for nets\nsch.add_label(\"VCC\", position=(125, 110))\n\n# Save with exact format preservation\nsch.save(\"my_circuit.kicad_sch\")\n```\n\n### Hierarchical Design\n\n```python\n# Create main schematic with hierarchical sheet\nmain_sch = ksa.create_schematic(\"Main Board\")\n\n# Add hierarchical sheet\npower_sheet = main_sch.add_hierarchical_sheet(\n name=\"Power Supply\",\n filename=\"power.kicad_sch\",\n position=(100, 100),\n size=(80, 60)\n)\n\n# Add sheet pins for connectivity\npower_sheet.add_pin(\"VIN\", pin_type=\"input\", position=(0, 10))\npower_sheet.add_pin(\"VOUT\", pin_type=\"output\", position=(80, 10))\n\n# Create the sub-schematic\npower_sch = ksa.create_schematic(\"Power Supply\")\npower_sch.add_hierarchical_label(\"VIN\", label_type=\"input\", position=(50, 25))\npower_sch.add_hierarchical_label(\"VOUT\", label_type=\"output\", position=(150, 25))\n\n# Save both schematics\nmain_sch.save(\"main.kicad_sch\")\npower_sch.save(\"power.kicad_sch\")\n```\n\n## \ud83d\udd27 Advanced Features\n\n### Component Bounding Boxes and Colored Graphics (NEW in v0.3.1)\n\n```python\nfrom kicad_sch_api.core.component_bounds import get_component_bounding_box\n\n# Add components\nresistor = sch.components.add(\"Device:R\", \"R1\", \"10k\", (100, 100))\nopamp = sch.components.add(\"Amplifier_Operational:LM358\", \"U1\", \"LM358\", (150, 100))\n\n# Get component bounding boxes\nbbox_body = get_component_bounding_box(resistor, include_properties=False)\nbbox_full = get_component_bounding_box(resistor, include_properties=True)\n\n# Draw colored bounding box rectangles\nsch.draw_bounding_box(bbox_body, stroke_width=0.5, stroke_color=\"blue\", stroke_type=\"solid\")\nsch.draw_bounding_box(bbox_full, stroke_width=0.3, stroke_color=\"red\", stroke_type=\"dash\")\n\n# Draw bounding boxes for all components at once\nbbox_uuids = sch.draw_component_bounding_boxes(\n include_properties=True,\n stroke_width=0.4,\n stroke_color=\"green\", \n stroke_type=\"dot\"\n)\n```\n\n### Manhattan Routing with Obstacle Avoidance (NEW in v0.3.1)\n\n```python\nfrom kicad_sch_api.core.manhattan_routing import ManhattanRouter\nfrom kicad_sch_api.core.types import Point\n\n# Create router\nrouter = ManhattanRouter()\n\n# Add components that act as obstacles\nr1 = sch.components.add(\"Device:R\", \"R1\", \"1k\", (50, 50))\nr2 = sch.components.add(\"Device:R\", \"R2\", \"2k\", (150, 150))\nobstacle = sch.components.add(\"Device:C\", \"C1\", \"100nF\", (100, 100))\n\n# Get obstacle bounding boxes\nobstacle_bbox = get_component_bounding_box(obstacle, include_properties=False)\n\n# Route around obstacles\nstart_point = Point(r1.position.x, r1.position.y)\nend_point = Point(r2.position.x, r2.position.y)\npath = router.route_between_points(start_point, end_point, [obstacle_bbox], clearance=2.0)\n\n# Add wires along the path\nfor i in range(len(path) - 1):\n sch.wires.add(path[i], path[i + 1])\n```\n\n### Pin-to-Pin Wiring\n\n```python\n# Connect component pins directly - automatically calculates pin positions\nwire_uuid = sch.add_wire_between_pins(\"R1\", \"2\", \"R2\", \"1\") # R1 pin 2 to R2 pin 1\n\n# Connect arbitrary point to component pin\nexternal_wire = sch.add_wire_to_pin((75, 125), \"R1\", \"1\") # External point to R1 pin 1\ntuple_wire = sch.add_wire_to_pin(Point(100, 150), \"C1\", \"2\") # Using Point object\n\n# Get component pin positions for advanced operations\npin_position = sch.get_component_pin_position(\"R1\", \"1\")\nif pin_position:\n print(f\"R1 pin 1 is at ({pin_position.x:.2f}, {pin_position.y:.2f})\")\n\n# Error handling - returns None for invalid components/pins\ninvalid_wire = sch.add_wire_between_pins(\"R999\", \"1\", \"R1\", \"1\") # Returns None\n```\n\n### Component Bounding Box Visualization (NEW in v0.3.1)\n\n```python\nfrom kicad_sch_api.core.component_bounds import get_component_bounding_box\n\n# Get component bounding box (body only)\nresistor = sch.components.get(\"R1\")\nbbox = get_component_bounding_box(resistor, include_properties=False)\nprint(f\"R1 body size: {bbox.width:.2f}\u00d7{bbox.height:.2f}mm\")\n\n# Get bounding box including properties (reference, value, etc.)\nbbox_with_props = get_component_bounding_box(resistor, include_properties=True)\nprint(f\"R1 with labels: {bbox_with_props.width:.2f}\u00d7{bbox_with_props.height:.2f}mm\")\n\n# Draw bounding box as rectangle graphics (for visualization/debugging)\nrect_uuid = sch.draw_bounding_box(bbox)\nprint(f\"Drew bounding box rectangle: {rect_uuid}\")\n\n# Draw bounding boxes for all components\nbbox_uuids = sch.draw_component_bounding_boxes(\n include_properties=False # True to include reference/value labels\n)\nprint(f\"Drew {len(bbox_uuids)} component bounding boxes\")\n\n# Expand bounding box for clearance analysis\nexpanded_bbox = bbox.expand(2.54) # Expand by 2.54mm (0.1 inch) \nclearance_rect = sch.draw_bounding_box(expanded_bbox)\n```\n\n### Manhattan Routing with Obstacle Avoidance (NEW in v0.3.1)\n\n```python\n# Automatic Manhattan routing between component pins\nwire_segments = sch.auto_route_pins(\n \"R1\", \"2\", # From component R1, pin 2\n \"R2\", \"1\", # To component R2, pin 1 \n routing_mode=\"manhattan\", # Manhattan (L-shaped) routing\n avoid_components=True # Avoid component bounding boxes\n)\n\n# Direct routing (straight line)\ndirect_wire = sch.auto_route_pins(\"C1\", \"1\", \"C2\", \"2\", routing_mode=\"direct\")\n\n# Manual obstacle avoidance using bounding boxes\nbbox_r1 = get_component_bounding_box(sch.components.get(\"R1\"))\nbbox_r2 = get_component_bounding_box(sch.components.get(\"R2\"))\n\n# Check if routing path intersects with component\ndef path_clear(start, end, obstacles):\n # Custom collision detection logic\n return not any(bbox.intersects_line(start, end) for bbox in obstacles)\n```\n\n### Component Search and Management\n\n```python\n# Search for components\nresistors = sch.components.find(lib_id_pattern='Device:R*')\npower_components = sch.components.filter(reference_pattern=r'U[0-9]+')\n\n# Bulk updates\nsch.components.bulk_update(\n criteria={'lib_id': 'Device:R'},\n updates={'properties': {'Tolerance': '1%'}}\n)\n\n# Component validation\nvalidation_result = sch.components.validate_component(\n 'Device:R', \n 'Resistor_SMD:R_0603_1608Metric'\n)\n```\n\n### Component and Element Removal\n\n```python\n# Remove components by reference\nremoved = sch.components.remove(\"R1\") # Returns True if removed\n\n# Remove wires, labels, and other elements\nsch.remove_wire(wire_uuid)\nsch.remove_label(label_uuid)\nsch.remove_hierarchical_label(label_uuid)\n\n# Remove from collections\nsch.wires.remove(wire_uuid)\nsch.junctions.remove(junction_uuid)\n\n# lib_symbols are automatically cleaned up when last component of type is removed\n```\n\n### Configuration and Customization\n\n```python\nimport kicad_sch_api as ksa\n\n# Access global configuration\nconfig = ksa.config\n\n# Customize property positioning\nconfig.properties.reference_y = -2.0 # Move reference labels higher\nconfig.properties.value_y = 2.0 # Move value labels lower\n\n# Customize tolerances and precision\nconfig.tolerance.position_tolerance = 0.05 # Tighter position matching\nconfig.tolerance.wire_segment_min = 0.005 # Different wire segment threshold\n\n# Customize defaults\nconfig.defaults.project_name = \"my_company_project\"\nconfig.defaults.stroke_width = 0.1\n\n# Grid and spacing customization\nconfig.grid.unit_spacing = 10.0 # Tighter multi-unit IC spacing\nconfig.grid.component_spacing = 5.0 # Closer component placement\n\n# Sheet settings for hierarchical designs\nconfig.sheet.name_offset_y = -1.0 # Different sheet label position\nconfig.sheet.file_offset_y = 1.0 # Different file label position\n```\n\n### KiCAD Integration\n\n```python\n# Run electrical rules check using KiCAD CLI\nerc_result = sch.run_erc_check()\nprint(f\"ERC Status: {erc_result.status}\")\nfor violation in erc_result.violations:\n print(f\"- {violation.type}: {violation.message}\")\n\n# Generate netlist for connectivity analysis\nnetlist = sch.generate_netlist()\nnet_info = netlist.analyze_net(\"VCC\")\n```\n\n## \ud83e\udd16 AI Agent Integration\n\nThis library serves as the foundation for AI agent integration. For Claude Code or other AI agents, use the **[mcp-kicad-sch-api](https://github.com/circuit-synth/mcp-kicad-sch-api)** MCP server.\n\n## \ud83c\udfd7\ufe0f Architecture\n\n### Library Structure\n\n```\nkicad-sch-api/\n\u251c\u2500\u2500 kicad_sch_api/ # Core Python library\n\u2502 \u251c\u2500\u2500 core/ # Core schematic manipulation\n\u2502 \u251c\u2500\u2500 library/ # KiCAD library integration\n\u2502 \u251c\u2500\u2500 discovery/ # Component search and indexing\n\u2502 \u2514\u2500\u2500 utils/ # Validation and utilities\n\u251c\u2500\u2500 tests/ # Comprehensive test suite\n\u2514\u2500\u2500 examples/ # Usage examples and tutorials\n```\n\n### Design Principles\n\n- **Building Block First**: Designed to be the foundation for other tools\n- **Exact Format Preservation**: Guaranteed byte-perfect KiCAD output\n- **Professional Quality**: Comprehensive error handling and validation\n- **MCP Foundation**: Designed as a stable foundation for MCP servers and AI agents\n- **Performance Optimized**: Fast operations on large schematics\n\n## \ud83e\uddea Testing & Quality\n\n```bash\n# Run all tests (29 tests covering all functionality)\nuv run pytest tests/ -v\n\n# Format preservation tests (critical - exact KiCAD output matching)\nuv run pytest tests/reference_tests/ -v\n\n# Component removal tests (comprehensive removal functionality)\nuv run pytest tests/test_*_removal.py -v\n\n# Code quality checks\nuv run black kicad_sch_api/ tests/\nuv run mypy kicad_sch_api/\nuv run flake8 kicad_sch_api/ tests/\n```\n\n### Test Categories\n\n- **Format Preservation**: Byte-for-byte compatibility with KiCAD native files\n- **Component Management**: Creation, modification, and removal of components\n- **Element Operations**: Wires, labels, junctions, hierarchical sheets\n- **Configuration**: Customizable settings and behavior\n- **Performance**: Large schematic handling and optimization\n- **Integration**: Real KiCAD library compatibility\n\n## \ud83c\udd9a Why This Library?\n\n### vs. Direct KiCAD File Editing\n- **Professional API**: High-level operations vs low-level S-expression manipulation\n- **Guaranteed Format**: Byte-perfect output vs manual formatting\n- **Validation**: Real KiCAD library integration and component validation\n- **Performance**: Optimized collections vs manual iteration\n\n### vs. Other Python KiCAD Libraries\n- **Format Preservation**: Exact KiCAD compatibility vs approximate output\n- **Modern Design**: Object-oriented collections vs legacy patterns\n- **AI Integration**: Purpose-built MCP server vs no agent support\n- **Professional Focus**: Production-ready vs exploration tools\n\n## \ud83d\udd17 Ecosystem\n\nThis library serves as the foundation for specialized tools and MCP servers:\n\n```python\n# Foundation library\nimport kicad_sch_api as ksa\n\n# MCP servers and specialized libraries built on this foundation:\n# - mcp-kicad-sch-api: Full MCP server for AI agents\n# - kicad_sourcing_tools: Component sourcing extensions\n# - kicad_placement_optimizer: Layout optimization\n# - kicad_dfm_checker: Manufacturing validation\n\n# Foundation provides reliable schematic manipulation\nsch = ksa.load_schematic('project.kicad_sch')\n\n# All extensions use the same stable API\n# mcp_server.use_schematic(sch) # MCP server integration\n# sourcing.update_sourcing(sch) # Component sourcing\n# placement.optimize_layout(sch) # Layout optimization\n\n# Foundation ensures exact format preservation\nsch.save() # Guaranteed exact KiCAD format\n```\n\n## \ud83d\udcd6 Documentation\n\nFull documentation is available at **[kicad-sch-api.readthedocs.io](https://kicad-sch-api.readthedocs.io/)**\n\nQuick links:\n- **[Getting Started Guide](https://kicad-sch-api.readthedocs.io/en/latest/GETTING_STARTED.html)**: Complete beginner's tutorial\n- **[API Reference](https://kicad-sch-api.readthedocs.io/en/latest/API_REFERENCE.html)**: Complete API documentation\n- **[Recipes & Patterns](https://kicad-sch-api.readthedocs.io/en/latest/RECIPES.html)**: Practical examples\n- **[Why Use This Library?](https://kicad-sch-api.readthedocs.io/en/latest/WHY_USE_THIS_LIBRARY.html)**: Value proposition and use cases\n- **[Architecture](https://kicad-sch-api.readthedocs.io/en/latest/ARCHITECTURE.html)**: Internal design details\n- **[Examples](examples/)**: Code examples and tutorials\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Key areas:\n\n- KiCAD library integration and component validation\n- Performance optimizations for large schematics \n- Additional MCP tools for AI agents\n- Test coverage and format preservation validation\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## \ud83d\udd17 Related Projects\n\n- **[mcp-kicad-sch-api](https://github.com/circuit-synth/mcp-kicad-sch-api)**: MCP server for AI agents built on this library\n- **[circuit-synth](https://github.com/circuit-synth/circuit-synth)**: High-level circuit design automation using this library\n- **[Claude Code](https://claude.ai/code)**: AI development environment with MCP support\n- **[KiCAD](https://kicad.org/)**: Open source electronics design automation suite\n\n---\n\n**Professional KiCAD schematic manipulation for the AI age \u26a1**\n",
"bugtrack_url": null,
"license": null,
"summary": "Professional KiCAD schematic manipulation library with exact format preservation",
"version": "0.4.2",
"project_urls": {
"Bug Reports": "https://github.com/circuit-synth/kicad-sch-api/issues",
"Changelog": "https://github.com/circuit-synth/kicad-sch-api/blob/main/CHANGELOG.md",
"Documentation": "https://kicad-sch-api.readthedocs.io/",
"Homepage": "https://github.com/circuit-synth/kicad-sch-api",
"Repository": "https://github.com/circuit-synth/kicad-sch-api.git"
},
"split_keywords": [
"kicad",
" schematic",
" eda",
" electronics",
" circuit-design",
" ai",
" automation",
" pcb"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e112d8fc6c4ce1b2939854030f2a6f0e020aab376ee8f8204317b51050118f0e",
"md5": "f9690638444fc53febcf0591ff582415",
"sha256": "296a86b3088544fd910cce5837c51e8d6c0fd281fe5d6922ddcf15aa936ee602"
},
"downloads": -1,
"filename": "kicad_sch_api-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f9690638444fc53febcf0591ff582415",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 198223,
"upload_time": "2025-10-27T07:29:07",
"upload_time_iso_8601": "2025-10-27T07:29:07.628391Z",
"url": "https://files.pythonhosted.org/packages/e1/12/d8fc6c4ce1b2939854030f2a6f0e020aab376ee8f8204317b51050118f0e/kicad_sch_api-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "608310efcd5df4f04e8ea5f2f951a1b86eee1ff08c18006394b502ed500527ea",
"md5": "b57c082b38f4364b1cf84181739322e3",
"sha256": "9ea1229d47a6d0d50a8976bf6881cb627e5d9d907bf2c2aa0b08e8f513f2339b"
},
"downloads": -1,
"filename": "kicad_sch_api-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "b57c082b38f4364b1cf84181739322e3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 236584,
"upload_time": "2025-10-27T07:29:08",
"upload_time_iso_8601": "2025-10-27T07:29:08.793746Z",
"url": "https://files.pythonhosted.org/packages/60/83/10efcd5df4f04e8ea5f2f951a1b86eee1ff08c18006394b502ed500527ea/kicad_sch_api-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-27 07:29:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "circuit-synth",
"github_project": "kicad-sch-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kicad-sch-api"
}
JSON
