Metadata-Version: 2.4
Name: pyschemaelectrical
Version: 0.1.1
Summary: A Python library for creating electrical schematic diagrams programmatically
Author: Ole Johan Bondahl
License: MIT License
        
        Copyright (c) 2026 OleJBondahl
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/OleJBondahl/PySchemaElectrical
Project-URL: Repository, https://github.com/OleJBondahl/PySchemaElectrical
Project-URL: Issues, https://github.com/OleJBondahl/PySchemaElectrical/issues
Keywords: electrical,schematic,diagram,svg,iec
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PySchemaElectrical

A Python library for creating electrical schematic diagrams programmatically following **IEC 60617** standards.

PySchemaElectrical provides a clean, functional API for generating professional electrical schematics as SVG files. Built with immutability and type safety in mind, it offers both a simple high-level API for common use cases and a powerful lower-level API for custom designs.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://img.shields.io/pypi/v/pyschemaelectrical.svg)](https://pypi.org/project/pyschemaelectrical/)

## Features

🎨 **IEC 60617 Compliant** - Industry-standard symbols  
🔒 **Type Safe** - Full type hints throughout  
🧊 **Immutable** - Functional programming principles  
📐 **Auto-Layout** - Automatic component positioning and wiring  
🏷️ **Wire Labels** - Add color and size specifications  
📊 **CSV Export** - Generate terminal connection lists  
🎯 **Modular** - Compose complex circuits from simple symbols

## Installation

### Using `uv` (recommended)

```bash
uv pip install pyschemaelectrical
```

### Using `pip`

```bash
pip install pyschemaelectrical
```

### From source

```bash
git clone https://github.com/OleJBondahl/PySchemaElectrical.git
cd PySchemaElectrical
uv pip install -e .
```

## Quick Start

### Simple Helper API Example

Create circuits easily using the helper functions:

```python
from pyschemaelectrical.system import Circuit, add_symbol, auto_connect_circuit, render_system
from pyschemaelectrical.symbols.terminals import three_pole_terminal
from pyschemaelectrical.symbols.breakers import three_pole_circuit_breaker
from pyschemaelectrical.symbols.assemblies import contactor

# Create a circuit container
c = Circuit()

# Add symbols at specific positions
# Symbols are automatically added to the circuit and translated
add_symbol(c, three_pole_terminal("X1", pins=("1", "2", "3", "4", "5", "6")), 50, 50)
add_symbol(c, three_pole_circuit_breaker("Q1", pins=("1", "2", "3", "4", "5", "6")), 50, 100)
add_symbol(c, contactor("K1", poles=3), 50, 150)
add_symbol(c, three_pole_terminal("X2", pins=("1", "2", "3", "4", "5", "6")), 50, 200)

# Automatically connect symbols in order
auto_connect_circuit(c)

# Render to SVG
render_system(c, "my_circuit.svg", width="297mm", height="210mm")
```

**Output:**

![Motor Circuit Example](examples/output/demo_system.svg)

## API Overview

### API Modules

For advanced usage:

- **`core`** - Core data structures (Point, Symbol, Port, Element)
- **`symbols/`** - IEC 60617 symbol library (contacts, coils, terminals, etc.)
- **`primitives`** - Geometric primitives (Line, Circle, Text, etc.)
- **`layout`** - Auto-connection and layout functions
- **`transform`** - Translation, rotation, scaling
- **`renderer`** - SVG rendering
- **`system_analysis`** - CSV export for terminal lists

## Available Symbols

### Contacts
- Normally Open (NO)
- Normally Closed (NC)
- SPDT (Single Pole Double Throw)
- Three-pole variants

### Terminals
- Single-pole terminal
- Three-pole terminal block
- Custom terminal boxes

### Protection & Switching
- Circuit breakers (1 and 3-pole)
- Thermal overload relays
- Fuses

### Control Elements
- Coils (relay/contactor)
- Emergency stop assemblies
- Push buttons

### Assemblies
- Contactors (configurable poles)
- Motor control circuits
- Current transducers with terminal boxes

## Wire Labels

Add wire specifications (color, size) to your diagrams:

```python
from pyschemaelectrical.layout import auto_connect_labeled

# Define wire specs
wire_config = {
    "X1": [("RD", "2.5mm²"), ("BK", "2.5mm²"), ("BN", "2.5mm²")]
}

# Connect with labels
elements.extend(auto_connect_labeled(x1_placed, q1_placed, wire_config["X1"]))
```

## CSV Export

Generate terminal connection lists:

```python
from pyschemaelectrical.system_analysis import export_terminals_to_csv

export_terminals_to_csv(elements, "connections.csv")
```

Output format:
```csv
Terminal,Pin From,Component From,Pin From Label,Component To,Pin To,Pin To Label
X1,1,,,Q1,1,
X1,2,,,Q1,2,
...
```

## Examples

Check out the `examples/` directory for more complex demonstrations:

- **`new_api_demo.py`** - Demonstration of the new helper API
- **`demo_system.py`** - Multi-circuit system with autonumbering
- **`multi_circuit_demo.py`** - Multiple motor circuits side-by-side

Run any example:

```bash
uv run examples/new_api_demo.py
```

Generated files are saved to `examples/output/`.

## Architecture

PySchemaElectrical follows **Clean Architecture** and **Functional Programming** principles:

- **Immutable data structures** - All entities are frozen dataclasses
- **Pure functions** - Core logic is side-effect free
- **Type safety** - Comprehensive type hints
- **Dependency injection** - Explicit dependencies
- **Separation of concerns** - Clear module boundaries

See [`AGENTS.md`](AGENTS.md) for detailed architectural guidelines.

## Testing

Run the test suite:

```bash
# Run all tests
uv run pytest

# With coverage report
uv run pytest --cov=src --cov-report=term-missing

# Run specific test file
uv run pytest tests/test_symbols.py
```

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/OleJBondahl/PySchemaElectrical.git
cd PySchemaElectrical

# Install with dev dependencies
uv sync

# Activate virtual environment
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows
```

### Project Structure

```
PySchemaElectrical/
├── src/pyschemaelectrical/    # Main library
│   ├── core.py               # Core data structures
│   ├── primitives.py         # Geometric primitives
│   ├── symbols/              # Symbol library
│   ├── layout.py             # Layout functions
│   ├── renderer.py           # SVG rendering

│   └── ...
├── examples/                  # Example scripts
│   └── output/               # Generated SVGs
├── tests/                     # Test suite
├── docs/                      # Documentation
└── pyproject.toml            # Project configuration
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Guidelines

1. Follow existing code style (functional, immutable, typed)
2. Add tests for new features
3. Update documentation
4. Use meaningful commit messages

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Author

**Ole Johan Bondahl**

## Acknowledgments

- IEC 60617 standard for electrical symbols
- Inspired by the need for programmatic electrical diagram generation
- Built with modern Python best practices

---

**Made with ❤️ for electrical engineers and automation professionals**
