Metadata-Version: 2.4
Name: yaml-to-schemdraw
Version: 0.1.0
Summary: Generate schemdraw diagrams from YAML files or Python dictionaries.
Project-URL: Homepage, https://github.com/Julynx/yaml-to-schemdraw
Project-URL: Repository, https://github.com/Julynx/yaml-to-schemdraw
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: ruamel-yaml
Requires-Dist: schemdraw

# yaml-to-schemdraw

Generate schemdraw diagrams from YAML files or Python dictionaries.

`pip install yaml-to-schemdraw`

- [yaml-to-schemdraw](#yaml-to-schemdraw)
  - [Usage](#usage)
  - [Why?](#why)
  - [How it works](#how-it-works)

The following YAML spec:

```yaml
V1:
  - elements
  - SourceV
  - label: ["5V"]

line1:
  - elements
  - Line
  - right: [0.75]

S1:
  - elements
  - SwitchSpdt2: [{ action: close }]
  - up
  - anchor: ["b"]
  - label: ["$t=0$", { loc: rgt }]

line2:
  - elements
  - Line
  - right: [0.75]
  - at: ["S1.c"]

R1:
  - elements
  - Resistor
  - down
  - label: ["$100\\Omega$"]
  - label: [["+", "$v_o$", "-"], { loc: bot }]

line3:
  - elements
  - Line
  - to: ["V1.start"]

C1:
  - elements
  - Capacitor
  - at: ["S1.a"]
  - toy: ["V1.start"]
  - label: ["1$\\mu$F"]
  - dot
```

Represents the equivalent Python code:

```python
with schemdraw.Drawing() as d:
    V1 = elm.SourceV().label('5V')
    elm.Line().right(d.unit*.75)
    S1 = elm.SwitchSpdt2(action='close').up().anchor('b').label('$t=0$', loc='rgt')
    elm.Line().right(d.unit*.75).at(S1.c)
    elm.Resistor().down().label(r'$100\Omega$').label(['+','$v_o$','-'], loc='bot')
    elm.Line().to(V1.start)
    elm.Capacitor().at(S1.a).toy(V1.start).label(r'1$\mu$F').dot()
```

And can be loaded with this library as follows:

## Usage

```python
from pathlib import Path
from ruamel.yaml import YAML
from yaml_to_schemdraw import from_dict

yaml = YAML()
spec = yaml.load(Path("diagram.yaml").read_text())
diagram = from_dict(spec)  # <- Schemdraw diagram object
```

You can now call `diagram.draw()` or `diagram.save("diagram.svg")` as usual.

## Why?

Schemdraw was always intended to be used as a Python library, with developers manually writing diagrams in code.

However, when it comes to accepting diagram definitions provided by clients through the network or originating from an untrusted environment, the naive approach of running arbitrary Python code with a function like `exec()` poses a significant security risk.

This module proposes an alternative, declarative way to represent Schemdraw diagrams as a YAML file or a Python dictionary.

## How it works

The module parses the dictionary and resolves the function calls against the schemdraw library.

Internally, it uses `getattr()` to resolve function calls, with an attribute whitelist to prevent module escalation.

It can easily and safely parse most of the schemdraw examples library, which was used to generate the included whitelist.

If you encounter any valid diagrams that cannot be parsed (or easily adapted into something that this module can parse), please open an issue.
