bom-helper 0.1.1__tar.gz

bom_helper-0.1.1/.gitea/workflows/ci.yaml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: python-test-image
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: uv sync --frozen --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} pytest -m "not network"
+
+  code-quality:
+    name: Code Quality
+    runs-on: python-test-image
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: uv sync --frozen --python 3.12
+
+      - name: Run code quality checks
+        run: cq check . -o score
+
+  upgrade-test:
+    name: Dependency Upgrade Test
+    runs-on: python-test-image
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Upgrade all dependencies
+        run: uv lock --upgrade
+
+      - name: Run tests with upgraded dependencies
+        run: uv sync --frozen --python 3.14 && uv run --python 3.14 pytest -m "not network"

bom_helper-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run pytest -m "not network"

bom_helper-0.1.1/.github/workflows/python-publish.yml

@@ -0,0 +1,56 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Build release distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/bom-helper/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

bom_helper-0.1.1/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.coverage
+
+.*_cache/
+.claude/

bom_helper-0.1.1/.python-version

@@ -0,0 +1 @@
+3.14

bom_helper-0.1.1/CLAUDE.md

@@ -0,0 +1,175 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`bom-helper` is a Python CLI tool for fetching information about electronic components from LCSC (a Chinese electronics component distributor). It scrapes product pages to extract part specifications, pricing, images, and datasheets.
+
+## Package Management and Environment
+
+- **Package Manager**: Use `uv` for all dependency management
+- **Python Version**: 3.12.2 (specified in `.python-version`)
+- **Key Dependencies**:
+  - `typer` - CLI framework
+  - `rich` - Terminal formatting and progress bars
+  - `beautifulsoup4` - HTML parsing for web scraping
+  - `requests` - HTTP client
+  - `easyeda2kicad` - KiCad library generation (wrapped by kicad.py)
+
+## Commands
+
+### Running the CLI
+
+The CLI is installed as the `bom` command via entry point in `pyproject.toml`.
+
+**All commands support multiple space-separated part numbers for batch processing:**
+
+```bash
+# Install and run in development mode
+uv run bom --help
+
+# Get part information (returns JSON) - single or multiple
+uv run bom info C124378
+uv run bom info C2040 C124378 C100
+
+# Download datasheet PDFs - single or multiple
+uv run bom pdf C124378 --dir ./datasheets
+uv run bom pdf C2040 C2041 C2042 --dir ./datasheets
+
+# Export to KiCad (symbol + footprint + 3D model) - single or multiple
+uv run bom add C2040
+uv run bom add C2040 C2041 C2042
+uv run bom add C2040 --output ./kicad-libs/lcsc
+uv run bom add C2040 --overwrite
+
+# Export individual components - single or multiple
+uv run bom symbol C2040
+uv run bom symbol C2040 C2041
+uv run bom footprint C2040
+uv run bom 3d C2040
+```
+
+### Testing
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov
+
+# Run specific test file
+uv run pytest tests/test_lcsc.py
+
+# Run specific test
+uv run pytest tests/test_parsing.py::test_getPartDetails
+```
+
+### Linting and Formatting
+
+Uses `ruff` for both linting and formatting:
+
+```bash
+# Format code
+uv run ruff format
+
+# Lint code
+uv run ruff check
+
+# Auto-fix linting issues
+uv run ruff check --fix
+```
+
+## Architecture
+
+### Code Structure
+
+```
+src/bom_helper/
+├── cli.py        # CLI commands using Typer
+├── main.py       # Core logic for scraping and PDF handling
+├── kicad.py      # KiCad library export (wraps easyeda2kicad)
+└── __init__.py
+
+tests/
+├── test_lcsc.py     # Tests for URL generation and PDF downloading
+└── test_parsing.py  # Tests for HTML parsing logic (uses mocks)
+```
+
+### Key Functions and Data Flow
+
+**URL Generation** (`main.py`):
+- `partToUrl(part)` - Converts LCSC part number (e.g., "C124378") to product detail URL
+- `partToPdfUrl(part)` - Converts part number to datasheet PDF URL
+
+**PDF Handling** (`main.py`):
+- `savePdf(part, path)` - Downloads datasheet PDF with proper User-Agent headers (LCSC blocks default agents)
+
+**Web Scraping** (`main.py:getPartDetails`):
+Scrapes LCSC product pages and returns structured dictionary containing:
+1. **Basic Info**: Extracted from `table.tableInfoWrap` - includes Manufacturer (with "Asian Brands" suffix stripped), Mfr. Part #, Description
+2. **Datasheet URL**: Extracted from the Datasheet row, handles relative URLs
+3. **Specifications**: Parsed from table with "Type" and "Description" headers (Category, Package, etc.)
+4. **Pricing**: Extracted from `table.priceTable` - returns list of quantity/price tiers
+5. **Images**: Extracted via regex from embedded JavaScript (`productImages:["url1",...]`)
+
+**Special Parsing Notes**:
+- Manufacturer field removes the "Asian Brands" badge/suffix using `copy.copy()` and `.decompose()`
+- Images are extracted from inline JS using regex: `r'productImages\s*:\s*(\[[^\]]*\])'`
+- All HTTP requests include a Chrome User-Agent header to avoid being blocked
+
+**KiCad Library Export** (`kicad.py`):
+Wraps the easyeda2kicad Python API to provide a better UX:
+1. **Core Functions**:
+   - `export_symbol(part, output_path, overwrite)` - Export symbol only
+   - `export_footprint(part, output_path, overwrite)` - Export footprint only
+   - `export_3d_model(part, output_path, overwrite)` - Export 3D model only
+   - `export_full(part, output_path, overwrite)` - Export all three
+2. **Workflow**:
+   - Validate part number starts with 'C'
+   - Use `EasyedaApi().get_cad_data_of_component()` to fetch CAD data
+   - Create library directory structure if needed (`.kicad_sym`, `.pretty`, `.3dshapes`)
+   - Check if component already exists (using `id_already_in_symbol_lib`, `fp_already_in_footprint_lib`)
+   - If exists and not `--overwrite`: return with status "already_exists" (no error!)
+   - If exists and `--overwrite`: update component
+   - If new: add component to library
+   - Use easyeda2kicad importers (`EasyedaSymbolImporter`, `EasyedaFootprintImporter`, `Easyeda3dModelImporter`)
+   - Use easyeda2kicad exporters to generate KiCad format
+   - Return paths to created files with status (added/updated/already_exists)
+3. **Key Behavior**:
+   - Default output: `~/Documents/Kicad/easyeda2kicad/easyeda2kicad`
+   - Never errors when component exists - just confirms and shows paths
+   - Suppresses easyeda2kicad logging (sets to ERROR level only)
+   - Handles cases where 3D models might not be available
+
+**CLI Integration** (`cli.py`):
+- Uses Typer for command routing
+- Commands: `info` (JSON), `pdf` (datasheet), `add` (full export), `symbol`, `footprint`, `3d`
+- **All commands support multiple parts**: Uses `List[str] = typer.Argument(...)`
+- Multi-part behavior:
+  - Shows progress indicator `[1/3] C2040` when processing multiple parts
+  - Continues processing if one part fails (error handling with `continue`)
+  - Accumulates failed parts and exits with code 1 if any failed
+  - Displays results per part
+- All KiCad commands support `--output` and `--overwrite` flags
+- Uses `rich.progress` for progress feedback
+- Uses `rich.table` to display export results
+- Version command using `importlib.metadata.version()`
+
+### Testing Strategy
+
+- **Unit Tests**: Mock HTTP responses for parsing tests (`test_parsing.py`)
+- **Integration Tests**: Real network calls for basic URL and PDF tests (`test_lcsc.py`)
+- Mock HTML includes truncated but representative LCSC page structure with all key elements
+
+## Important Patterns
+
+1. **Part Number Validation**: All commands validate part numbers using `validate_lcsc_part_number()` from `main.py`
+   - Must start with 'C' followed by digits only (regex: `^C\d+$`)
+   - Rejects paths, special characters, spaces, lowercase
+   - Examples: Valid: `C2040`, `C124378`; Invalid: `C:\path`, `C123abc`, `c2040`
+2. **User-Agent Required**: All `requests.get()` calls must include Chrome User-Agent header or LCSC will return HTML instead of expected content
+3. **Path Handling**: Use `pathlib.Path` throughout; `savePdf` creates directories if they don't exist
+4. **Error Handling**: Functions raise exceptions that are caught at CLI level and converted to user-friendly messages with exit code 1
+5. **BeautifulSoup Usage**: Import inside function (`getPartDetails`) rather than module-level

bom_helper-0.1.1/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: bom-helper
+Version: 0.1.1
+Summary: CLI tool for fetching LCSC component info, datasheets, and KiCad library exports
+Project-URL: Repository, https://github.com/rhiza-fr/bom-helper
+Project-URL: Issues, https://github.com/rhiza-fr/bom-helper/issues
+Author-email: Chris Kilner <chris@rhiza.fr>
+License: MIT
+Keywords: bom,components,easyeda,electronics,kicad,lcsc
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.14.3
+Requires-Dist: easyeda2kicad>=0.8.0
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=14.2.0
+Requires-Dist: typer>=0.20.0
+Description-Content-Type: text/markdown
+
+# BOM Helper
+
+A Python CLI tool for fetching electronic component information from LCSC (a Chinese electronics component distributor). Quickly retrieve part specifications, pricing, datasheets, and images for your Bill of Materials (BOM) management.
+
+## Features
+
+- **Batch Processing**: All commands support multiple space-separated part numbers
+- **Part Information**: Retrieve detailed component specifications in JSON format
+- **Datasheet Download**: Automatically download component datasheets as PDFs
+- **KiCad Library Export**: Export symbols, footprints, and 3D models for KiCad
+- **Comprehensive Data Extraction**:
+  - Manufacturer and part numbers
+  - Technical specifications (package type, category, etc.)
+  - Pricing tiers for different quantities
+  - Product images
+  - Datasheet URLs
+
+## Installation
+
+This project uses [uv](https://github.com/astral-sh/uv) for package management. Make sure you have Python 3.12+ installed.
+
+```bash
+# Clone the repository
+git clone https://github.com/rhiza-fr/bom-helper.git
+cd bom-helper
+
+# Install the tool (makes `bom` available on your PATH)
+uv tool install .
+```
+
+After installation, use `bom` directly — no `uv run` prefix needed.
+
+## Usage
+
+### Get Component Information
+
+Retrieve detailed information about one or more components by LCSC part number:
+
+```bash
+# Single part
+bom info C124378
+
+# Multiple parts
+bom info C2040 C124378 C100
+```
+
+This returns a JSON object with all available information:
+```json
+{
+  "url": "https://www.lcsc.com/product-detail/C124378.html",
+  "Manufacturer": "hanxia",
+  "Mfr. Part #": "HX PM2.54-1x7P TP-YQ",
+  "Description": "2.54mm 1kV 7P 3A 1 Gold Brass",
+  "Datasheet": "https://www.lcsc.com/datasheet/C124378.pdf",
+  "Specifications": {
+    "Category": "Connectors",
+    "Package": "SMD,P=2.54mm"
+  },
+  "Pricing": [
+    {"Qty": "11+", "Unit Price": "€ 0.2071", "Ext. Price": "€ 2.28"},
+    {"Qty": "110+", "Unit Price": "€ 0.1639", "Ext. Price": "€ 18.03"}
+  ],
+  "Images": [
+    "https://assets.lcsc.com/images/lcsc/900x900/front.jpg",
+    "https://assets.lcsc.com/images/lcsc/900x900/back.jpg"
+  ]
+}
+```
+
+### Download Datasheet
+
+Download datasheets for one or more components:
+
+```bash
+# Save to current directory
+bom pdf C124378
+
+# Download multiple datasheets
+bom pdf C2040 C124378 C100
+
+# Save to a specific directory
+bom pdf C124378 --dir ./datasheets
+
+# Batch download to directory
+bom pdf C2040 C2041 C2042 --dir ./datasheets
+```
+
+### Export to KiCad
+
+Export component symbols, footprints, and 3D models for use in KiCad:
+
+```bash
+# Export everything (symbol + footprint + 3D model) for one part
+bom add C2040
+
+# Export multiple parts at once
+bom add C2040 C2041 C2042
+
+# Export to a custom location
+bom add C2040 --output ./kicad-libs/lcsc
+
+# Update existing components
+bom add C2040 --overwrite
+
+# Export only specific parts
+bom symbol C2040    # Symbol only
+bom footprint C2040 # Footprint only
+bom 3d C2040        # 3D model only
+
+# All commands support multiple parts
+bom symbol C2040 C2041
+bom footprint C2040 C2041 C2042
+```
+
+**Default location:** `~/Documents/Kicad/easyeda2kicad/`
+
+The tool will:
+- Create library files if they don't exist
+- Detect existing components and skip them (use `--overwrite` to update)
+- Show you the paths to all created files
+
+### Check Version
+
+```bash
+bom --version
+```
+
+## Development
+
+### Setup
+
+```bash
+# Install development dependencies
+uv sync --group dev
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage report
+uv run pytest --cov
+
+# Run specific test file
+uv run pytest tests/test_lcsc.py
+```
+
+### Code Quality
+
+This project uses [ruff](https://github.com/astral-sh/ruff) for linting and formatting:
+
+```bash
+# Format code
+uv run ruff format
+
+# Check for linting issues
+uv run ruff check
+
+# Auto-fix linting issues
+uv run ruff check --fix
+```
+
+## How It Works
+
+BOM Helper provides two main capabilities:
+
+### 1. Component Information & Datasheets
+Scrapes the LCSC website to extract component information:
+- Fetches product page HTML for a given part number
+- Parses structured data from tables and embedded JavaScript
+- Returns information in a clean, structured format
+
+Edge cases handled:
+- Extracting URLs from relative paths
+- Cleaning manufacturer names (removes "Asian Brands" badges)
+- Parsing pricing tables with quantity tiers
+- Extracting product images from embedded JavaScript
+
+### 2. KiCad Library Export
+Integrates with [easyeda2kicad](https://github.com/uPesy/easyeda2kicad.py) to generate KiCad library files:
+- Fetches CAD data from EasyEDA API
+- Converts symbols, footprints, and 3D models to KiCad format
+- Manages library files and prevents duplicates
+- Built on top of easyeda2kicad with a simpler batch-friendly CLI
+
+## Requirements
+
+- Python 3.12 or higher
+- Internet connection (to fetch data from LCSC)
+
+## Part Number Format
+
+All commands require valid LCSC part numbers. LCSC part numbers must:
+- Start with 'C' (uppercase)
+- Be followed by one or more digits
+- Contain no other characters (no spaces, hyphens, paths, etc.)
+
+**Valid examples:** `C2040`, `C124378`, `C999999999`
+**Invalid examples:** `C:\path`, `C123abc`, `C-123`, `c2040` (lowercase), `C 123` (space)
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Disclaimer
+
+This tool is not affiliated with or endorsed by LCSC. It is designed for personal use to help manage Bills of Materials. Please respect LCSC's terms of service and use this tool responsibly.