migrate-to-esp-pylib

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

Step	Detail
1	Audit
2	Add dependency
3	Constants
4	Errors
5	Logging / output
6	IDE WebSocket + excepthook
7	Config loader
8	ROM ELF
9	Serial ports
10	Reset sequences
11	WebSocket client
12	CLI
13	sys.exit
14	Delete redundant files
15

Also in workflow.md: what stays local, common pitfalls, backward-compatibility patterns.

Critical rules

1. 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.
2. 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.
3. esp-pylib never imports consumer tools — the dependency graph flows one way.
4. Skip [Planned] steps — never invent imports for unshipped modules.
5. 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).