Metadata-Version: 2.4
Name: python-kicad
Version: 0.5.0
Summary: Pydantic models and parsers for KiCad 6 and newer design files
Author: esophagoose
License-Expression: MIT
Project-URL: Homepage, https://github.com/esophagoose/python-kicad
Project-URL: Repository, https://github.com/esophagoose/python-kicad
Project-URL: Issues, https://github.com/esophagoose/python-kicad/issues
Keywords: kicad,eda,pcb,schematic,parser,pydantic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3,>=2.10.6
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
Requires-Dist: twine>=6.1.0; extra == "dev"
Dynamic: license-file

# python-kicad

`python-kicad` provides Pydantic models and parsers for KiCad schematic,
PCB, and exported netlist files.

- KiCad 6 and newer
- Python 3.10 and newer
- No KiCad installation required
- MIT licensed

## Installation

```console
python -m pip install python-kicad
```

The distribution is named `python-kicad`, while the import package remains
`pykicad`:

```python
from pykicad import Pcb, Schematic, read_from_file

document = read_from_file("project.kicad_pcb")
if isinstance(document, Pcb):
    print(document.version)
    print(len(document.footprint))
elif isinstance(document, Schematic):
    print(document.version)
    print(len(document.symbols))
```

An older, unrelated distribution already uses the `pykicad` name on PyPI and
installs into the same Python import namespace. Do not install `pykicad` and
`python-kicad` into the same environment.

## Supported documents

`read_from_file()` and `read_from_string()` recognize:

- `.kicad_pcb` board files as `Pcb`
- `.kicad_sch` schematic files as `Schematic`
- KiCad-exported S-expression netlists as `Netlist`

The parser uses one Pydantic model family for released KiCad 6 and newer file
variants. Unknown enum values and malformed S-expressions remain validation
errors.

```python
from pydantic import ValidationError
from pykicad import read_from_string

try:
    board = read_from_string(
        "(kicad_pcb (version 20240101) (generator pcbnew))"
    )
except (ValueError, ValidationError) as error:
    print(f"Invalid KiCad document: {error}")
```

## Writing limitations

Exact PCB round-tripping is available for an unchanged `Pcb` loaded through
`read_from_file()` or `read_from_string()`:

```python
from pykicad import read_from_file, write_to_file

board = read_from_file("project.kicad_pcb")
write_to_file(board, "copy.kicad_pcb")
```

Structured serialization of modified PCB models and schematic writing are not
implemented. Attempting either raises `ValueError`.

## Development

Create an environment and install the development dependencies:

```console
python -m pip install -e ".[dev]"
python -m pytest
```

Build and validate release artifacts with:

```console
python -m build
python -m twine check dist/*
python scripts/check_distribution.py dist/*
```

See [RELEASING.md](RELEASING.md) for the trusted-publishing release process.
