easyeda-monkey 2026.5.26__tar.gz

easyeda_monkey-2026.5.26/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.pyright/
+__pycache__/
+*.py[cod]
+tests/rack_results/

easyeda_monkey-2026.5.26/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 2026.5.26
+
+- Bootstrap `easyeda-monkey` as a standalone public package from the existing
+  EasyEDA parser package.
+- Include EasyEDA/LCSC symbol, footprint, SVG path, pad, and 3D model reference
+  parser coverage using package-local saved API fixtures.
+- Add public CI, release workflow, Rack tests, Python signoff, package build
+  checks, and clean install-test coverage.
+- Add the `easyeda-monkey fetch-part` CLI and design-document signoff policy
+  for registered commands.
+- Use an MIT license for the public package.
+- Document `uv tool install` as the preferred CLI install path and `uv` as the
+  development/test workflow.
+- Add ADR-003 for CLI command-module discipline and dependency minimization.
+- Add API/interface design documentation with Rack test ownership checks.
+- Move signoff and install-test helpers under `tests/support_scripts/`.
+- Exclude developer-only planning and research docs from release artifacts
+  while promoting stable EasyEDA format references into `docs/canonical_format/`.

easyeda_monkey-2026.5.26/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing
+
+`easyeda-monkey` accepts direct public pull requests once CI is enabled.
+
+Use `uv` for local development and test commands. Public CLI install
+documentation should prefer `uv tool install easyeda-monkey`; use
+`pip install easyeda-monkey` when documenting library use inside an existing
+Python environment.
+
+Before opening a PR:
+
+1. Keep changes focused on one parser, model, fixture, contract, or
+   infrastructure slice.
+2. Add or update tests for every public parser/API behavior change.
+3. Update docs for public interfaces, JSON behavior, or fixture contracts.
+4. Add or update `docs/design/` HTML for every public CLI command.
+5. Justify every new public feature, command, and dependency in the commit,
+   PR, or linked plan.
+6. Run package tests and signoff locally.
+
+Minimize external dependencies. A new dependency must explain why the standard
+library and existing project dependencies are not enough, whether it is
+runtime/optional/test-only, its license compatibility, and the expected
+packaging impact.
+
+Expected local checks:
+
+```powershell
+uv run --extra test rack run --all
+```
+
+Release decisions, compatibility policy, and public contract changes should be
+recorded in `docs/adrs/`.
+
+## Design Documentation Rules
+
+`docs/` owns architecture, test, and contract documentation. `docs/design/`
+contains human-readable and machine-inspectable HTML design docs.
+
+Every public CLI command requires:
+
+- a command registry entry in code;
+- a matching `docs/design/cli/<command>.html` file;
+- a link from `docs/design/cli/index.html`;
+- usage, invocation, argument, output, and test sections.
+
+Signoff fails when those links are missing. Commands with config files also
+need a machine-readable contract and validation tests.
+
+## API Design Documentation Rules
+
+Every public dataclass and major interface requires design documentation under
+`docs/design/api/`.
+
+Each interface design section must include:
+
+- rationale for why the interface exists;
+- purpose and ownership boundary;
+- test requirements;
+- a working definition;
+- the Rack stratum and test target that exercise it.
+
+L99 signoff fails when a dataclass or listed major interface lacks design
+documentation or when the referenced Rack test ownership is missing.
+
+## CLI Structure Rules
+
+The top-level CLI module is an orchestrator. It creates the root parser,
+registers commands, handles global options, and dispatches command handlers.
+
+Every public subcommand must live in its own module under
+`easyeda_monkey.cli_commands`, even if the first implementation is small. The
+command module owns command-specific arguments, behavior, output formatting,
+and command-specific imports.
+
+This convention is documented in
+`docs/adrs/ADR-003-cli-command-and-dependency-discipline.md`. L99 signoff
+checks the parts that are mechanically enforceable; reviewers can still reject
+a PR when command or dependency justification is missing.

easyeda_monkey-2026.5.26/LICENSE

@@ -0,0 +1,21 @@
+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.

easyeda_monkey-2026.5.26/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: easyeda-monkey
+Version: 2026.5.26
+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-File: LICENSE
+Requires-Python: <3.13,>=3.11
+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; 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>=1.1.0; 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 --extra test
+```
+
+## Testing
+
+The active suite uses redistributable saved EasyEDA / LCSC API response
+fixtures and does not require a private corpus.
+
+```powershell
+uv run --extra test 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 fetch-part C21190
+easyeda-monkey fetch-part C21190 --cache-dir .cache/easyeda --output C21190.summary.json
+```
+
+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.
+
+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.

easyeda_monkey-2026.5.26/README.md

@@ -0,0 +1,139 @@
+# 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 --extra test
+```
+
+## Testing
+
+The active suite uses redistributable saved EasyEDA / LCSC API response
+fixtures and does not require a private corpus.
+
+```powershell
+uv run --extra test 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 fetch-part C21190
+easyeda-monkey fetch-part C21190 --cache-dir .cache/easyeda --output C21190.summary.json
+```
+
+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.
+
+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.

easyeda_monkey-2026.5.26/docs/adrs/ADR-001-easyeda-native-data-model-and-api-conventions.md

@@ -0,0 +1,99 @@
+# ADR-001: EasyEDA Native Data Model and API Conventions
+
+## Status
+
+Accepted.
+
+## Date
+
+2026-03-18.
+
+## Context
+
+`easyeda-monkey` parses EasyEDA schematic symbols and PCB footprints from the
+LCSC / JLCPCB component API. Downstream tools can then convert that typed native
+model into other EDA formats.
+
+The EasyEDA format is JSON-based with tilde-delimited shape strings. It is
+smaller than Altium binary formats, but still needs a dedicated native model to
+preserve source-format details before conversion.
+
+## Decision
+
+### 1. EasyEDA-Native Data Model First
+
+The package exposes typed Python classes that represent EasyEDA JSON semantics:
+
+- tilde-delimited string parsing
+- EasyEDA coordinate systems
+- EasyEDA-specific shape prefixes
+- symbol pin `^^` segment parsing
+- footprint pad, track, hole, via, and 3D model references
+
+Downstream conversion policy is intentionally outside this package.
+
+### 2. Public Construction And Serialization
+
+Primary public entry points:
+
+- `EasyEdaSymbol.from_json(data_or_path)`
+- `EasyEdaFootprint.from_json(data_or_path)`
+- `EasyEdaApiClient.fetch_symbol(lcsc_id)`
+- `EasyEdaApiClient.fetch_footprint(lcsc_id)`
+- `EasyEdaApiClient.fetch_both(lcsc_id)`
+
+Serialization methods:
+
+- `.to_json()` returns a round-trippable dict.
+- `.save(path)` writes JSON to disk.
+
+The direct dataclass constructor remains available for advanced/internal use,
+but parsing should go through `from_json` or the API client.
+
+### 3. API Client Is Separate From The Data Model
+
+`easyeda_api.py` handles HTTP fetches from the LCSC API. Data model classes
+accept parsed dictionaries or saved JSON fixture paths and do not perform HTTP
+requests themselves.
+
+### 4. Minimal Core Dependencies
+
+Core parsing uses the Python standard library. The API client uses `requests`.
+The package avoids heavy model frameworks so downstream tools can embed it
+without pulling in large application stacks.
+
+### 5. Scope
+
+In scope:
+
+- schematic symbols
+- PCB footprints
+- SVG path parsing helpers
+- 3D model references and download URLs
+
+Out of scope for the initial public package:
+
+- full EasyEDA schematic document support
+- EasyEDA Pro
+- direct Altium/KiCad conversion commands
+- authoring/building EasyEDA components
+
+## Consequences
+
+Positive:
+
+- Native model preserves source-format details for round-trip tests.
+- Saved API fixture tests do not require network access.
+- Downstream converters get a small parser dependency.
+
+Tradeoffs:
+
+- Format conversion remains the responsibility of downstream tools.
+- Some inherited parser functions are complex and tracked in the signoff
+  baseline until they can be split safely.
+
+## Source Anchors
+
+- EasyEDA format docs: https://docs.easyeda.com/en/DocumentFormat/EasyEDA-Document-Format/index.html
+- Reference implementation studied for format behavior: https://github.com/uPesy/easyeda2kicad.py
+- LCSC API shape: `https://easyeda.com/api/products/{LCSC_ID}/components?version=6.4.19.5`

easyeda_monkey-2026.5.26/docs/adrs/ADR-002-versioning-tagging-and-release-policy.md

@@ -0,0 +1,47 @@
+# ADR-002: Versioning, Tagging, and Release Policy
+
+## Status
+
+Accepted.
+
+## Context
+
+`easyeda-monkey` is a public package and will be consumed by downstream tools.
+Releases need to be reproducible from Git tags and automatable through GitHub
+Actions.
+
+## Decision
+
+The package uses date-based versions in `YYYY.M.DD` form. For example, the
+May 26, 2026 release is `2026.5.26`.
+
+Release tags use the package name and version:
+
+```text
+easyeda-monkey/v2026.5.26
+```
+
+Every release must include:
+
+- a matching `pyproject.toml` version
+- a matching `easyeda_monkey.__version__`
+- a matching `CHANGELOG.md` entry
+- a passing pytest suite
+- a passing Rack suite
+- a passing Python signoff baseline check
+- successful source distribution and wheel builds
+- successful `twine check`
+- an installed-wheel install test
+
+Release artifacts may include public reference docs such as ADRs, design docs,
+canonical format docs, contracts, and tests. Developer planning and research
+notes under `docs/plans/` and `docs/research/` are not part of the public
+release artifacts and must be excluded from source distributions.
+
+GitHub Actions is the preferred release path once PyPI Trusted Publishing is
+configured for this repository.
+
+## Consequences
+
+Downstream repos can pin exact package dates and exact Git tags. Old names or
+pre-public internal package flows are not part of the public contract.

easyeda_monkey-2026.5.26/docs/adrs/ADR-003-cli-command-and-dependency-discipline.md

@@ -0,0 +1,56 @@
+# ADR-003: CLI Command And Dependency Discipline
+
+## Status
+
+Accepted.
+
+## Context
+
+Python tools in this package family should stay small, easy to install, and
+easy to review. `easyeda-monkey` is the first small public repo where this
+convention is being codified, but the rule is intended for future tool repos as
+well.
+
+CLI commands can grow quickly if each command places parser setup, command
+behavior, output formatting, and dependency imports into the top-level entry
+point.
+
+External dependencies also create long-term install, packaging, CI, and user
+support costs. Even small dependencies need a reason to exist.
+
+## Decision
+
+The top-level CLI module is an orchestrator only. It may create the root
+argument parser, register subcommands, handle global options, dispatch handlers,
+and expose command metadata for docs/signoff.
+
+Each public subcommand must live in its own module under
+`easyeda_monkey.cli_commands`. The command module owns command-specific parser
+arguments, handler implementation, output behavior, and command-specific
+imports.
+
+Every new public CLI command requires:
+
+- a command module;
+- a command registry entry;
+- a matching `docs/design/cli/<command>.html` design document;
+- tests for behavior and help/registration;
+- a short justification in the commit, PR, or plan.
+
+Every tool in this package family should minimize external dependencies. New
+dependencies are accepted only when the commit or PR explains:
+
+- why the dependency is needed;
+- why the standard library or existing project dependencies are not sufficient;
+- expected install/package impact;
+- license compatibility;
+- whether the dependency is required, optional, or test-only.
+
+## Consequences
+
+Reviewers can reject a command or dependency addition that lacks justification,
+even when tests pass.
+
+L99 signoff should enforce the parts that are mechanically checkable, including
+the per-command module convention and matching design docs. Human review still
+owns dependency justification quality.

easyeda_monkey-2026.5.26/docs/adrs/ADR-004-interface-design-doc-and-rack-ownership.md

@@ -0,0 +1,44 @@
+# ADR-004: Interface Design Documentation And Rack Ownership
+
+## Status
+
+Accepted.
+
+## Context
+
+Dataclasses and major interfaces become long-lived contracts quickly. A class
+can pass unit tests while still leaving future maintainers unclear about why it
+exists, where its boundary is, or what behavior counts as working.
+
+The test system already uses Rack strata as the release gate, so interface
+documentation should point back to Rack-owned tests instead of separate ad hoc
+checklists.
+
+## Decision
+
+Every public dataclass and major interface requires design documentation under
+`docs/design/api/`.
+
+Each interface design section must include:
+
+- rationale for why the interface exists;
+- purpose and ownership boundary;
+- test requirements;
+- a working definition;
+- Rack stratum and test target metadata.
+
+L99 signoff scans source dataclasses and the major-interface list, then fails
+if any required interface lacks design documentation.
+
+L99 signoff also fails if an interface design section does not point to an
+existing Rack stratum, existing test file, and test target. For nested data
+classes, the exercising test may be an aggregate parser test when that is the
+natural coverage boundary.
+
+## Consequences
+
+New dataclasses and major interfaces require docs and tests in the same change.
+
+The first enforcement pass checks source, design docs, Rack strata, test files,
+and declared test targets. A later refinement can inspect Rack result reports
+directly if the report format provides a stable machine-readable target map.