| name | migrate-to-esp-pylib |
| repository | https://github.com/espressif/esp-pylib |
| description | Migrates Espressif Python tools to the shared esp-pylib library. Use when the user explicitly asks to migrate to esp-pylib, replace duplicated code (FatalError, logging, console output options via set_console_options, set_info_stream, progress bars, collapsible log stages, byte progress or unbounded counters, IDE WebSocket, INI config, ROM ELF resolution, serial port discovery, DTR/RTS reset primitives, named reset sequences, Click ParamTypes and Click option classes), convert argparse CLIs to rich-click, remove dependencies superseded by an esp_pylib.* module, or troubleshoot common migration pitfalls (terminal width in tests, logger prefix assertions in tests, leftover argparse imports after rich-click, breaking vs cosmetic API changes). |
Migrate a Tool to esp-pylib
Using this skill
- Bundle: use the whole
migrate-to-esp-pylib/ directory (SKILL.md plus references/workflow.md), not SKILL.md alone — symlink, copy, submodule, or fetch that folder from GitHub.
- Target repo: run the migration in the consumer Python tool you are updating, not in the esp-pylib repository.
- Dependency: add
esp-pylib on PyPI to the consumer's pyproject.toml or setup.py (see Step 2); look up the current release on PyPI and pin >= that version — do not leave the X.Y.Z placeholder from the workflow examples.
esp-pylib ships incrementally. The module status table below shows what is implemented today; skip steps marked [Planned] until they flip to [Available]. For per-parameter semantics, platform quirks, and edge cases, read the relevant module's docstrings (installed package or Source links below) rather than relying on this skill — it intentionally stays at the workflow level.
Module status
| Module | Status | Replaces |
|---|
esp_pylib.constants | Available | Duplicated VID/PID, baud, port name patterns, macOS exclude list, hardware-flow-control adapter list |
esp_pylib.errors | Available | Duplicated FatalError classes, plus the recoverable PortVidPidNotFoundError |
esp_pylib.logger | Available | Raw ANSI helpers, local log.py modules, Python logging usage, ad-hoc progress-bar printers |
esp_pylib.ws | Available | Tool-local WebSocket clients + structured diagnostics |
esp_pylib.excepthook | Available | Uncaught-exception reporting (no prior equivalent) |
esp_pylib.config | Available | Duplicated INI config file loaders |
esp_pylib.serial_ports | Available | Duplicated port discovery / filtering / sorting + USB VID/PID lookup for a device path |
esp_pylib.serial_reset | Available | Duplicated DTR/RTS primitives, named reset sequences, hardware-flow-control reset paths, custom-sequence parser |
esp_pylib.cli_types | Available | SerialPortType, AnyIntType, AutoSizeType, BaudRateType, arg_auto_int() |
esp_pylib.cli_options | Available | EspRichGroup, MutuallyExclusiveOption, OptionEatAll |
esp_pylib.rom | Available | Duplicated ROM ELF resolution |
esp_pylib.serial_reset ships the low-level pin primitives, the four named reset sequences shared between esptool and esp-idf-monitor (each with an opt-in flow_control=True mode for hardware-flow-control adapters), and the custom-sequence parser/executor. The strategy-selection layer above the sequences (which sequence to run for a given chip + connection mode, retry orchestration, --before / --after plumbing) stays in each tool — see Step 10.
Migration workflow
One PR per consumer repo. Skip [Planned] steps.
Copy this checklist and track progress. After Step 1, open references/workflow.md (or the GitHub copy if the skill folder is not on disk) and follow only the sections for steps marked [Available] above.
Task Progress:
- [ ] Step 1: Audit — identify what to migrate
- [ ] Step 2: Add esp-pylib dependency
- [ ] Step 3: Replace constants [Available]
- [ ] Step 4: Replace error classes [Available]
- [ ] Step 5: Replace logging / output (incl. progress) [Available]
- [ ] Step 6: Wire up IDE WebSocket + exception hooks [Available]
- [ ] Step 7: Replace config loader [Available]
- [ ] Step 8: Replace ROM ELF resolution [Available]
- [ ] Step 9: Replace serial port logic [Available]
- [ ] Step 10: Replace reset primitives + sequences [Available]
- [ ] Step 11: Replace local WebSocket client [Available]
- [ ] Step 12: Convert CLI to rich-click [Available]
- [ ] Step 13: Migrate sys.exit calls
- [ ] Step 14: Delete redundant files
- [ ] Step 15: Run tests and verify
- [ ] Step 16: Write a migration report for the reviewer
Also in workflow.md: what stays local, common pitfalls, backward-compatibility patterns.
Critical rules
- No breaking changes to public APIs — preserve Python callables consumers import, CLI flag names/defaults/semantics, return types, exception types external code catches, and exit codes. Unified log wording and styling for cross-tool consistency (e.g.
Notice → NOTE:, bold WARNING:) are not breaking — see Common pitfalls and Backward-compatibility patterns.
- Tool-specific code stays local — chip/protocol definitions, reset strategy selection and
--before/--after plumbing, byte-level serial ANSI coloring, and tool-specific env vars/timings stay in the consumer; see what stays local.
esp-pylib never imports consumer tools — the dependency graph flows one way.- Skip [Planned] steps — never invent imports for unshipped modules.
- Read module docstrings during migration — use installed-package docstrings or the Source column above; this skill intentionally omits per-parameter semantics, platform quirks, and edge cases that live in the source.
See also
README.md (repo root) — public-facing usage doc; keep aligned with this skill.references/workflow.md — detailed step instructions, code examples, and compatibility wrappers (GitHub when the skill folder is not on disk).
