easyeda-monkey 2026.5.26__py3-none-any.whl

easyeda_monkey/__init__.py

@@ -0,0 +1,3 @@
+"""EasyEDA / LCSC / JLCPCB schematic symbol, footprint, and 3D model parser."""
+
+__version__ = "2026.5.26"

easyeda_monkey/cli.py

@@ -0,0 +1,50 @@
+"""Top-level command-line orchestrator for EasyEDA Monkey."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable, Sequence
+from typing import cast
+
+from . import __version__
+from .cli_commands import COMMANDS as CLI_COMMANDS
+from .cli_commands import register_commands
+from .cli_commands.fetch_part import normalize_lcsc_id
+
+__all__ = ["CLI_COMMANDS", "build_parser", "main", "normalize_lcsc_id"]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the EasyEDA Monkey argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="easyeda-monkey",
+        description="EasyEDA / LCSC parsing utilities.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    register_commands(subparsers)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the EasyEDA Monkey CLI."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.print_help(sys.stderr)
+        return 2
+    return cast("CommandHandler", handler)(args)
+
+
+CommandHandler = Callable[[argparse.Namespace], int]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

easyeda_monkey/cli_command_types.py

@@ -0,0 +1,14 @@
+"""Shared CLI command metadata types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CliCommandSpec:
+    """Public CLI command metadata used by docs and signoff tests."""
+
+    name: str
+    design_doc: str
+    help: str

easyeda_monkey/cli_commands/__init__.py

@@ -0,0 +1,19 @@
+"""CLI subcommand registry."""
+
+from __future__ import annotations
+
+import argparse
+
+from ..cli_command_types import CliCommandSpec
+from . import fetch_part
+
+COMMANDS: tuple[CliCommandSpec, ...] = (
+    fetch_part.COMMAND,
+)
+
+
+def register_commands(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Register all public CLI subcommands with an argparse parser."""
+    fetch_part.register(subparsers)

easyeda_monkey/cli_commands/fetch_part.py

@@ -0,0 +1,171 @@
+"""Implementation of the fetch-part CLI subcommand."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import cast
+
+from ..cli_command_types import CliCommandSpec
+from ..easyeda_api import EasyEdaApiClient
+
+JsonScalar = str | int | float | bool | None
+JsonValue = JsonScalar | list["JsonValue"] | dict[str, "JsonValue"]
+JsonObject = dict[str, JsonValue]
+
+COMMAND = CliCommandSpec(
+    name="fetch-part",
+    design_doc="cli/fetch-part.html",
+    help="Fetch an EasyEDA / LCSC component by C-number.",
+)
+
+
+def register(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Register the fetch-part parser."""
+    parser = subparsers.add_parser(
+        COMMAND.name,
+        help=COMMAND.help,
+        description="Fetch an EasyEDA / LCSC component by C-number.",
+    )
+    parser.add_argument("lcsc_id", help="LCSC part number, such as C21190 or 21190.")
+    parser.add_argument(
+        "--cache-dir",
+        type=Path,
+        default=None,
+        help="Optional directory for cached API JSON responses.",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        help="Optional output JSON file. Defaults to stdout.",
+    )
+    parser.add_argument(
+        "--raw",
+        action="store_true",
+        help="Emit the raw EasyEDA API response instead of the compact summary.",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=15,
+        help="HTTP timeout in seconds when a network fetch is needed.",
+    )
+    parser.add_argument(
+        "--rate-limit-seconds",
+        type=float,
+        default=0.5,
+        help="Minimum delay between live API requests for this process.",
+    )
+    parser.set_defaults(handler=run)
+
+
+def normalize_lcsc_id(value: str) -> str:
+    """Normalize a user supplied LCSC C-number."""
+    lcsc_id = value.strip().upper()
+    if not lcsc_id:
+        raise ValueError("LCSC id cannot be empty")
+    if not lcsc_id.startswith("C"):
+        lcsc_id = f"C{lcsc_id}"
+    return lcsc_id
+
+
+def summarize_component(component_data: Mapping[str, JsonValue], lcsc_id: str) -> JsonObject:
+    """Build a compact summary for an EasyEDA component API response."""
+    result = component_data.get("result")
+    if not isinstance(result, dict):
+        return {
+            "lcsc_id": lcsc_id,
+            "found": False,
+            "title": "",
+            "symbol": {"shape_count": 0},
+            "footprint": {"shape_count": 0},
+        }
+
+    data_str = _dict_or_empty(result.get("dataStr"))
+    symbol_shapes = _list_or_empty(data_str.get("shape"))
+
+    package_detail = _dict_or_empty(result.get("packageDetail"))
+    footprint_data = _dict_or_empty(package_detail.get("dataStr"))
+    footprint_shapes = _list_or_empty(footprint_data.get("shape"))
+
+    return {
+        "lcsc_id": _lcsc_id_from_result(result, default=lcsc_id),
+        "found": True,
+        "title": _str_or_empty(result.get("title")),
+        "uuid": _str_or_empty(result.get("uuid")),
+        "symbol": {
+            "shape_count": len(symbol_shapes),
+            "has_data": bool(symbol_shapes),
+        },
+        "footprint": {
+            "shape_count": len(footprint_shapes),
+            "has_data": bool(footprint_shapes),
+        },
+    }
+
+
+def run(args: argparse.Namespace) -> int:
+    """Run the fetch-part subcommand."""
+    try:
+        lcsc_id = normalize_lcsc_id(args.lcsc_id)
+    except ValueError as exc:
+        sys.stderr.write(f"error: {exc}\n")
+        return 2
+
+    client = EasyEdaApiClient(
+        cache_dir=args.cache_dir,
+        timeout=args.timeout,
+        rate_limit_seconds=args.rate_limit_seconds,
+    )
+    component_data = cast(JsonObject, client.fetch_component(lcsc_id))
+    if not component_data:
+        sys.stderr.write(f"error: no EasyEDA component data found for {lcsc_id}\n")
+        return 1
+
+    payload = component_data if args.raw else summarize_component(component_data, lcsc_id)
+    _emit_json(payload, args.output)
+    return 0
+
+
+def _dict_or_empty(value: JsonValue | object) -> Mapping[str, JsonValue]:
+    """Return a JSON object view when value is a dictionary."""
+    if isinstance(value, dict):
+        return cast(Mapping[str, JsonValue], value)
+    return {}
+
+
+def _list_or_empty(value: JsonValue | object) -> list[JsonValue]:
+    """Return a JSON list when value is a list."""
+    if isinstance(value, list):
+        return cast(list[JsonValue], value)
+    return []
+
+
+def _str_or_empty(value: JsonValue | object) -> str:
+    """Return a string value or an empty string."""
+    return value if isinstance(value, str) else ""
+
+
+def _lcsc_id_from_result(result: Mapping[str, JsonValue], *, default: str) -> str:
+    """Extract the LCSC C-number from a result object."""
+    lcsc = _dict_or_empty(result.get("lcsc"))
+    szlcsc = _dict_or_empty(result.get("szlcsc"))
+    return _str_or_empty(lcsc.get("number")) or _str_or_empty(szlcsc.get("number")) or default
+
+
+def _emit_json(payload: JsonObject, output: Path | None) -> None:
+    """Write JSON to stdout or an output file."""
+    text = json.dumps(payload, indent=2, sort_keys=True)
+    if output is None:
+        sys.stdout.write(text)
+        sys.stdout.write("\n")
+        return
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(text + "\n", encoding="utf-8")

easyeda_monkey/easyeda_3d_model.py

@@ -0,0 +1,213 @@
+"""
+EasyEDA 3D model reference and download support.
+
+3D models are referenced by UUID in the footprint data and downloaded
+from the EasyEDA modules API as STEP or OBJ files.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+log = logging.getLogger(__name__)
+
+_STEP_URL_BASE = "https://modules.easyeda.com/qAxj6KHrDKw4blvCG8QJPs7Y"
+_OBJ_URL_BASE = "https://modules.easyeda.com/3dmodel"
+
+if TYPE_CHECKING:
+    from .easyeda_footprint import EasyEdaFootprint
+
+
+@dataclass
+class EasyEda3DModel:
+    """3D model reference extracted from an EasyEDA footprint."""
+
+    uuid: str = ""
+    title: str = ""
+    translation_x: float = 0.0
+    translation_y: float = 0.0
+    translation_z: float = 0.0
+    rotation_x: float = 0.0
+    rotation_y: float = 0.0
+    rotation_z: float = 0.0
+    raw_attrs: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def step_url(self) -> str:
+        """URL to download STEP file."""
+        if not self.uuid:
+            return ""
+        return f"{_STEP_URL_BASE}/{self.uuid}"
+
+    @property
+    def obj_url(self) -> str:
+        """URL to download OBJ file."""
+        if not self.uuid:
+            return ""
+        return f"{_OBJ_URL_BASE}/{self.uuid}"
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "uuid": self.uuid,
+            "title": self.title,
+            "translation_x": self.translation_x,
+            "translation_y": self.translation_y,
+            "translation_z": self.translation_z,
+            "rotation_x": self.rotation_x,
+            "rotation_y": self.rotation_y,
+            "rotation_z": self.rotation_z,
+            "step_url": self.step_url,
+            "obj_url": self.obj_url,
+            "raw_attrs": self.raw_attrs,
+        }
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> EasyEda3DModel:
+        return cls(
+            uuid=data.get("uuid", ""),
+            title=data.get("title", ""),
+            translation_x=float(data.get("translation_x", 0)),
+            translation_y=float(data.get("translation_y", 0)),
+            translation_z=float(data.get("translation_z", 0)),
+            rotation_x=float(data.get("rotation_x", 0)),
+            rotation_y=float(data.get("rotation_y", 0)),
+            rotation_z=float(data.get("rotation_z", 0)),
+            raw_attrs=data.get("raw_attrs", {}),
+        )
+
+    def download_step(self, output_path: str | Path, timeout: int = 30) -> bool:
+        """Download STEP file to the given path. Returns True on success."""
+        if not self.uuid:
+            log.warning("No 3D model UUID — cannot download")
+            return False
+
+        import requests
+
+        url = self.step_url
+        log.info("Downloading STEP from %s", url)
+        try:
+            resp = requests.get(url, timeout=timeout)
+            resp.raise_for_status()
+            Path(output_path).write_bytes(resp.content)
+            log.info("Saved STEP (%d bytes) to %s", len(resp.content), output_path)
+            return True
+        except Exception as e:
+            log.error("Failed to download STEP: %s", e)
+            return False
+
+    def download_obj(self, output_path: str | Path, timeout: int = 30) -> bool:
+        """Download OBJ file to the given path. Returns True on success."""
+        if not self.uuid:
+            return False
+
+        import requests
+
+        url = self.obj_url
+        log.info("Downloading OBJ from %s", url)
+        try:
+            resp = requests.get(url, timeout=timeout)
+            resp.raise_for_status()
+            Path(output_path).write_text(resp.text, encoding="utf-8")
+            log.info("Saved OBJ (%d bytes) to %s", len(resp.content), output_path)
+            return True
+        except Exception as e:
+            log.error("Failed to download OBJ: %s", e)
+            return False
+
+
+def extract_3d_model_from_footprint(ee_fp: EasyEdaFootprint) -> EasyEda3DModel | None:
+    """
+    Extract 3D model reference from an EasyEdaFootprint's raw data.
+
+    EasyEDA stores 3D model info in SVGNODE elements within the footprint
+    shape list, containing JSON-encoded attributes with UUID, translation,
+    and rotation.
+    """
+    # Look for the 3D model UUID in the footprint info
+    model_uuid = ee_fp.info.model_3d_uuid
+    if model_uuid:
+        return EasyEda3DModel(uuid=model_uuid, title=ee_fp.info.name)
+
+    # Fallback: search passthrough for SVGNODE-derived data
+    return None
+
+
+def extract_3d_models_from_api_response(api_data: dict[str, Any]) -> list[EasyEda3DModel]:
+    """
+    Extract all 3D model references from a raw API response.
+
+    Searches packageDetail.dataStr.shape for SVGNODE entries containing
+    3D model metadata.
+    """
+    models: list[EasyEda3DModel] = []
+    result = api_data.get("result", {})
+    pkg_detail = result.get("packageDetail", {})
+    data_str = pkg_detail.get("dataStr", {})
+    shapes = data_str.get("shape", [])
+
+    for shape_str in shapes:
+        if not isinstance(shape_str, str):
+            continue
+        if "SVGNODE" not in shape_str and "3dmodel" not in shape_str.lower():
+            continue
+
+        # Try to extract JSON from the SVGNODE
+        model = _parse_svgnode_3d(shape_str)
+        if model:
+            models.append(model)
+
+    # Also check head attributes for 3D model references
+    head = data_str.get("head", "")
+    if isinstance(head, str) and "3d" in head.lower():
+        # Some footprints embed the UUID in head attributes
+        uuid_match = re.search(r"([0-9a-f]{32}|[0-9a-f-]{36})", head)
+        if uuid_match and not models:
+            models.append(EasyEda3DModel(
+                uuid=uuid_match.group(1),
+                title=result.get("title", ""),
+            ))
+
+    return models
+
+
+def _parse_svgnode_3d(shape_str: str) -> EasyEda3DModel | None:
+    """Try to extract a 3D model reference from an SVGNODE shape string."""
+    # SVGNODE shapes contain JSON-like attribute strings
+    # Look for c_origin (translation) and c_rotation patterns
+    try:
+        # Extract UUID — look for a 32-char hex string or standard UUID
+        uuid_match = re.search(r'"uuid"\s*:\s*"([^"]+)"', shape_str)
+        if not uuid_match:
+            uuid_match = re.search(r"([0-9a-f]{32})", shape_str)
+        if not uuid_match:
+            return None
+
+        uuid = uuid_match.group(1)
+
+        # Extract translation
+        tx = ty = tz = 0.0
+        origin_match = re.search(r'"c_origin"\s*:\s*"([^"]*)"', shape_str)
+        if origin_match:
+            parts = origin_match.group(1).split(",")
+            if len(parts) >= 3:
+                tx, ty, tz = float(parts[0]), float(parts[1]), float(parts[2])
+
+        # Extract rotation
+        rx = ry = rz = 0.0
+        rot_match = re.search(r'"c_rotation"\s*:\s*"([^"]*)"', shape_str)
+        if rot_match:
+            parts = rot_match.group(1).split(",")
+            if len(parts) >= 3:
+                rx, ry, rz = float(parts[0]), float(parts[1]), float(parts[2])
+
+        return EasyEda3DModel(
+            uuid=uuid,
+            translation_x=tx, translation_y=ty, translation_z=tz,
+            rotation_x=rx, rotation_y=ry, rotation_z=rz,
+        )
+    except (ValueError, IndexError, AttributeError):
+        return None

easyeda_monkey/easyeda_api.py

@@ -0,0 +1,118 @@
+"""
+LCSC / EasyEDA component API client.
+
+Fetches symbol, footprint, and 3D model data by LCSC part number.
+Uses ``requests`` for HTTP — this is the only module with an external dependency.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Any
+
+from .easyeda_footprint import EasyEdaFootprint
+from .easyeda_symbol import EasyEdaSymbol
+
+log = logging.getLogger(__name__)
+
+_API_BASE = "https://easyeda.com/api/products"
+_API_VERSION = "6.4.19.5"
+_USER_AGENT = "wn_pcb_tools/1.0"
+_DEFAULT_TIMEOUT = 15
+
+
+class EasyEdaApiClient:
+    """
+    Client for the LCSC / EasyEDA component API.
+
+    Fetches component data by LCSC part number (e.g. ``C21190``).
+    Supports optional disk caching for offline use and test fixture generation.
+    """
+
+    def __init__(
+        self,
+        cache_dir: str | Path | None = None,
+        timeout: int = _DEFAULT_TIMEOUT,
+        rate_limit_seconds: float = 0.5,
+    ) -> None:
+        self._cache_dir = Path(cache_dir) if cache_dir else None
+        self._timeout = timeout
+        self._rate_limit = rate_limit_seconds
+        self._last_request_time: float = 0.0
+
+        if self._cache_dir:
+            self._cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def fetch_component(self, lcsc_id: str) -> dict[str, Any]:
+        """
+        Fetch raw API response for an LCSC component.
+
+        Returns the full JSON response dict. Caches to disk if cache_dir set.
+        """
+        lcsc_id = lcsc_id.strip().upper()
+        if not lcsc_id.startswith("C"):
+            lcsc_id = f"C{lcsc_id}"
+
+        # Check cache first
+        if self._cache_dir:
+            cache_path = self._cache_dir / f"{lcsc_id}.json"
+            if cache_path.exists():
+                log.debug("Cache hit for %s", lcsc_id)
+                return json.loads(cache_path.read_text(encoding="utf-8"))
+
+        # Rate limiting
+        now = time.monotonic()
+        elapsed = now - self._last_request_time
+        if elapsed < self._rate_limit:
+            time.sleep(self._rate_limit - elapsed)
+
+        import requests
+
+        url = f"{_API_BASE}/{lcsc_id}/components?version={_API_VERSION}"
+        headers = {
+            "User-Agent": _USER_AGENT,
+            "Accept": "application/json",
+        }
+
+        log.info("Fetching %s from LCSC API", lcsc_id)
+        response = requests.get(url, headers=headers, timeout=self._timeout)
+        self._last_request_time = time.monotonic()
+        response.raise_for_status()
+
+        data = response.json()
+
+        if not data.get("success") or not data.get("result"):
+            log.warning("API returned empty/failed result for %s", lcsc_id)
+            return {}
+
+        # Cache to disk
+        if self._cache_dir:
+            cache_path = self._cache_dir / f"{lcsc_id}.json"
+            cache_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+            log.debug("Cached %s (%d bytes)", lcsc_id, cache_path.stat().st_size)
+
+        return data
+
+    def fetch_symbol(self, lcsc_id: str) -> EasyEdaSymbol:
+        """Fetch and parse a schematic symbol by LCSC part number."""
+        data = self.fetch_component(lcsc_id)
+        if not data:
+            raise ValueError(f"No component data for {lcsc_id}")
+        return EasyEdaSymbol.from_json(data)
+
+    def fetch_footprint(self, lcsc_id: str) -> EasyEdaFootprint:
+        """Fetch and parse a PCB footprint by LCSC part number."""
+        data = self.fetch_component(lcsc_id)
+        if not data:
+            raise ValueError(f"No component data for {lcsc_id}")
+        return EasyEdaFootprint.from_json(data)
+
+    def fetch_both(self, lcsc_id: str) -> tuple[EasyEdaSymbol, EasyEdaFootprint]:
+        """Fetch and parse both symbol and footprint in a single API call."""
+        data = self.fetch_component(lcsc_id)
+        if not data:
+            raise ValueError(f"No component data for {lcsc_id}")
+        return EasyEdaSymbol.from_json(data), EasyEdaFootprint.from_json(data)