Metadata-Version: 2.4
Name: easyeda-monkey
Version: 2026.6.4
Summary: Core EasyEDA / LCSC symbol, footprint, and 3D reference parsing tooling
Project-URL: Homepage, https://github.com/wavenumber-eng/easyeda_monkey
Project-URL: Repository, https://github.com/wavenumber-eng/easyeda_monkey
Project-URL: Issues, https://github.com/wavenumber-eng/easyeda_monkey/issues
Author: Wavenumber LLC
License: MIT License
        
        Copyright (c) 2026 Wavenumber LLC
        
        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.
License-File: LICENSE
Requires-Python: <3.13,>=3.12
Requires-Dist: requests>=2.32.0
Provides-Extra: test
Requires-Dist: build>=1.2.0; extra == 'test'
Requires-Dist: pyright>=1.1.390; extra == 'test'
Requires-Dist: pytest-json-report>=1.5.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: ruff>=0.8.0; extra == 'test'
Requires-Dist: twine>=5.0.0; extra == 'test'
Requires-Dist: wn-rack>=2026.6.4; extra == 'test'
Description-Content-Type: text/markdown

# EasyEDA Monkey

`easyeda_monkey` is a small Python package for reading EasyEDA / LCSC component
data into typed Python objects. It also exposes a small diagnostic CLI for
package-local fetch and inspection workflows.

Current scope:

- EasyEDA / LCSC component API responses
- schematic symbols
- PCB footprints
- 3D model references and URL extraction
- SVG path parsing helpers

The package is intentionally focused on parsing and close-to-format data
models. Larger workflow commands and conversion applications should live in
downstream tools.

## Install

Install `uv` first if it is not already available:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

On macOS or Linux:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

For the command-line tool, use `uv tool install` so the executable is installed
in an isolated tool environment and exposed on PATH:

```powershell
uv tool install easyeda-monkey
uv tool update-shell
easyeda-monkey --version
```

For library use inside an existing Python environment:

```powershell
pip install easyeda-monkey
```

For development:

```powershell
git clone https://github.com/wavenumber-eng/easyeda_monkey.git
cd easyeda_monkey
uv sync --all-extras
```

## Testing

The active suite uses redistributable saved EasyEDA / LCSC API response
fixtures and does not require a private corpus.

```powershell
uv run rack run --all
```

Rack is the primary local gate. L99 signoff runs release metadata checks,
Python signoff, CLI design-doc checks, API design-doc checks, ruff, and pyright.

## CLI

The package installs the `easyeda-monkey` console script.

```powershell
easyeda-monkey --version
easyeda-monkey version
easyeda-monkey fetch-part C21190
easyeda-monkey fetch-part C21190 --cache-dir .cache/easyeda --output C21190.summary.json
easyeda-monkey download-part C21190 --output-dir output
python -m easyeda_monkey version
```

`download-part` writes to `output/<LCSC_ID>/` by default. The bundle includes
the raw API response, a compact summary, extracted 3D model metadata, and STEP
or OBJ model files when EasyEDA exposes a model reference for the part.

The top-level CLI module is only an orchestrator. Each public subcommand lives
in its own `easyeda_monkey.cli_commands` module, even when the command is
small.

## Design And Test Docs

`docs/` is the source of truth for architecture, tests, and contracts. The
master design entry point is [docs/design/index.html](docs/design/index.html).

Every public CLI command must have a matching HTML design document under
`docs/design/cli/`. The filename must match the command name, and signoff fails
when a registered command is missing its design document.

Commands that accept config files must also define a machine-readable contract
and validation tests before release. Command, interface, and standards-exception
manifests live under `docs/contracts/`.

New public features, commands, and external dependencies need explicit
justification in the commit, PR, or linked plan. Prefer the standard library
and existing dependencies unless a new dependency has a clear install,
licensing, and maintenance case.

Every public dataclass and major interface needs design documentation under
`docs/design/api/`. L99 signoff fails when interface docs or Rack test
ownership are missing.

## Fixture Model

Active fixtures live under:

- `tests/L0_foundation/cases/api_responses`

Broader fixture families should use this shape when needed:

- `input/`
- `reference_output/`
- `output/`

`output/` is transient and should stay local or temporary.

## Scope Boundaries

Core package responsibilities:

- parse EasyEDA-native JSON structures into typed Python objects
- preserve EasyEDA-native semantics
- expose a clean parser/API surface for downstream converters

Deferred or downstream responsibilities:

- command-line workflow applications
- Altium, KiCad, or other EDA conversion policy
- private project corpus handling

## Documentation

- [Architecture Decision Records](docs/adrs)
- [Design Notes](docs/design)
- [Plans](docs/plans)

## License

MIT.
