thonny-upypi-manager 0.1.1

Thonny plugin for searching and installing uPyPi packages

thonny-upypi-manager

---

Table of Contents / 目录

• English
  • Current scope
  • Project layout
  • Installation
  • Development
  • Packaging
  • Publishing to PyPI
  • Notes
• 中文
  • 功能范围
  • 项目结构
  • 安装
  • 开发
  • 打包
  • 发布到 PyPI
  • 备注

---

English

thonny-upypi-manager is a Thonny IDE plugin for searching packages on uPyPi, inspecting package metadata, downloading package files, and installing them onto a connected MicroPython board with mpremote.

The plugin adds a visible uPyPi entry point in Thonny and is intended for Thonny 4.1.7.

Current scope

• Search uPyPi packages from inside Thonny
• Show metadata from each package's package.json
• Download realistic multi-file packages to a local cache
• Install package files to /lib on a connected device through mpremote
• Automatic dependency installation: reads the deps field in package.json and installs all declared dependencies before the main package
• Surface recoverable errors such as missing network access, missing mpremote, or no connected board

Project layout

The plugin is implemented under the thonnycontrib.upypi_manager package so that Thonny can discover it as a third-party plugin.

Key files:

• thonnycontrib/upypi_manager/plugin.py: Thonny UI, panel registration, and user actions
• thonnycontrib/upypi_manager/client.py: uPyPi API and package metadata client
• thonnycontrib/upypi_manager/installer.py: download, cache, and mpremote install flow
• pyproject.toml: packaging metadata

Installation

There are two practical ways to install the plugin:

• Install a built wheel
• Copy the plugin package into Thonny's user plugin directory

For sharing with a client, the wheel is the cleaner option.

Option 1: Install from a wheel

Build the wheel on a development machine:

python -m build

This creates a file under dist/, for example:

dist/thonny_upypi_manager-0.1.1-py3-none-any.whl

In Thonny, open Tools -> Manage plug-ins..., choose Install from local file, and select the wheel file.

Note: Install from local file requires Thonny 4.x or above. For older versions, use pip install <path-to-wheel> in Thonny's built-in terminal.

Option 2: Install by copying the package

Copy thonnycontrib/upypi_manager into Thonny's site-packages:

.../site-packages/thonnycontrib/upypi_manager/__init__.py
.../site-packages/thonnycontrib/upypi_manager/plugin.py
.../site-packages/thonnycontrib/upypi_manager/client.py
.../site-packages/thonnycontrib/upypi_manager/installer.py
.../site-packages/thonnycontrib/upypi_manager/icon.png

Typical Thonny user plugin locations:

• Linux: ~/.config/Thonny/plugins/lib/pythonX.Y/site-packages/
• macOS: ~/Library/Thonny/plugins/lib/pythonX.Y/site-packages/
• Windows: %APPDATA%\Thonny\plugins\lib\pythonX.Y\site-packages\

After copying the files, restart Thonny.

Platform notes

• Windows: make sure mpremote is on PATH. Device discovery supports COM ports (e.g. COM3).
• macOS: if mpremote is installed via Homebrew, launch Thonny from an environment where it is on PATH.
• Linux: install mpremote in a virtual environment if system-wide pip is blocked, and launch Thonny with that PATH.

Development

During local development, add this repository to PYTHONPATH and launch Thonny from the same environment:

PYTHONPATH=/path/to/thonny-upypi-manager python -m thonny

If testing install-to-device flows, make sure mpremote is available on PATH.

Packaging

Build distribution artifacts with:

uv build --no-sources

This produces a wheel and source distribution under dist/.

Publishing to PyPI

1. Fork the repository

Fork this repository into your own GitHub account or organization. The repository used to publish to PyPI should be under your ownership.

After forking:

1. Clone your fork locally.
2. Confirm you can push to it.
3. Do the release from your fork, not from the original repository.

2. Review pyproject.toml

Please verify at least: name, version, authors, maintainers, project.urls.

3. Build and test

Install uv if not already available (docs.astral.sh/uv), then run:

uv build --no-sources

Test the wheel in Thonny:

1. Open Thonny.
2. Go to Tools -> Manage plug-ins...
3. Choose Install from local file.
4. Select the wheel from dist/.
5. Restart Thonny and confirm the plugin appears.

4. Publish

Create a PyPI account at pypi.org, then generate an API token from account settings.

Set your token:

macOS / Linux:

export UV_PUBLISH_TOKEN="pypi-REPLACE_WITH_YOUR_TOKEN"

Windows PowerShell:

$env:UV_PUBLISH_TOKEN="pypi-REPLACE_WITH_YOUR_TOKEN"

Windows Command Prompt:

set UV_PUBLISH_TOKEN=pypi-REPLACE_WITH_YOUR_TOKEN

Before publishing, remove any old build artifacts from dist/ to avoid accidentally uploading a previous version:

macOS / Linux:

rm -rf dist/

Windows PowerShell:

Remove-Item dist\* -Recurse -Force

Then rebuild and publish:

uv build --no-sources
uv publish

Confirm the release at pypi.org/project/thonny-upypi-manager/, then verify it appears in Thonny under Tools -> Manage plug-ins....

Example: full build and publish session (Windows PowerShell)

# Add uv to PATH for the current session
$env:Path = "C:\Users\Administrator\.local\bin;" + $env:Path

# Verify uv is available
uv --version
# uv 0.11.7 (9d177269e 2026-04-15 x86_64-pc-windows-msvc)

# Build wheel and source distribution
uv build --no-sources
# Building source distribution...
# ...
# Successfully built dist\thonny_upypi_manager-0.1.0.tar.gz
# Successfully built dist\thonny_upypi_manager-0.1.0-py3-none-any.whl

# Set PyPI token and publish
$env:UV_PUBLISH_TOKEN="pypi-REPLACE_WITH_YOUR_TOKEN"
uv publish
# Publishing 2 files to https://upload.pypi.org/legacy/
# Uploading thonny_upypi_manager-0.1.0-py3-none-any.whl (14.4KiB)
# Uploading thonny_upypi_manager-0.1.0.tar.gz (13.5KiB)

Notes

• Windows, macOS, and Linux are intended targets.
• Uninstall, upgrade, and overwrite behavior are out of scope for v1.
• Build outputs should not be committed to the repository.

---

中文

thonny-upypi-manager 是一个 Thonny IDE 插件，用于在 uPyPi 上搜索包、查看包元数据、下载包文件，并通过 mpremote 将其安装到已连接的 MicroPython 开发板上。

插件会在 Thonny 中添加一个可见的 uPyPi 入口，适用于 Thonny 4.1.7。

功能范围

• 在 Thonny 内搜索 uPyPi 包
• 显示每个包的 package.json 元数据
• 下载多文件包到本地缓存
• 通过 mpremote 将包文件安装到设备的 /lib 目录
• 自动安装依赖：读取 package.json 中的 deps 字段，在安装主包前先安装所有声明的依赖
• 提示可恢复的错误，如网络不可用、mpremote 缺失或未连接开发板

项目结构

插件实现在 thonnycontrib.upypi_manager 包下，以便 Thonny 能将其识别为第三方插件。

关键文件：

• thonnycontrib/upypi_manager/plugin.py：Thonny UI、面板注册与用户操作
• thonnycontrib/upypi_manager/client.py：uPyPi API 与包元数据客户端
• thonnycontrib/upypi_manager/installer.py：下载、缓存与 mpremote 安装流程
• pyproject.toml：打包元数据

安装

安装插件有两种方式：

• 安装构建好的 wheel 文件
• 将插件包复制到 Thonny 的用户插件目录

对于分发给他人，wheel 方式更为规范。

方式一：通过 wheel 安装

构建 wheel：

python -m build

生成文件示例：

dist/thonny_upypi_manager-0.1.1-py3-none-any.whl

在 Thonny 中，打开 Tools -> Manage plug-ins...，选择 Install from local file，然后选择 wheel 文件。

注意：Install from local file 需要 Thonny 4.x 及以上版本。旧版本可在 Thonny 内置终端执行 pip install <path-to-wheel>。

方式二：复制包目录

将 thonnycontrib/upypi_manager 复制到 Thonny 的 site-packages：

.../site-packages/thonnycontrib/upypi_manager/__init__.py
.../site-packages/thonnycontrib/upypi_manager/plugin.py
.../site-packages/thonnycontrib/upypi_manager/client.py
.../site-packages/thonnycontrib/upypi_manager/installer.py
.../site-packages/thonnycontrib/upypi_manager/icon.png

典型路径：

• Linux: ~/.config/Thonny/plugins/lib/pythonX.Y/site-packages/
• macOS: ~/Library/Thonny/plugins/lib/pythonX.Y/site-packages/
• Windows: %APPDATA%\Thonny\plugins\lib\pythonX.Y\site-packages\

复制完成后重启 Thonny。

平台说明

• Windows：确保 mpremote 在 PATH 中，设备发现支持 COM 端口（如 COM3）。
• macOS：若通过 Homebrew 安装 mpremote，需在包含该路径的环境中启动 Thonny。
• Linux：若系统 pip 受限，在虚拟环境中安装 mpremote 并以该 PATH 启动 Thonny。

开发

本地开发时，将此仓库加入 PYTHONPATH 并从同一环境启动 Thonny：

PYTHONPATH=/path/to/thonny-upypi-manager python -m thonny

如需测试安装到设备的流程，请确保 mpremote 在 PATH 中可用。

打包

构建发布产物：

uv build --no-sources

会在 dist/ 下生成 wheel 和源码包。

发布到 PyPI

1. Fork 仓库

请先把这个仓库 fork 到你们自己的 GitHub 账号或组织下。用于发布到 PyPI 的仓库应当由你们自己持有。

fork 之后：

1. 在本地 clone 你们自己的 fork。
2. 确认你们可以正常 push。
3. 后续发布基于你们自己的 fork，不要基于原始仓库。

2. 检查 pyproject.toml

至少请核对：name、version、authors、maintainers、project.urls。

3. 构建并测试

如未安装 uv，请先参考 docs.astral.sh/uv 安装。

Windows PowerShell 安装 uv：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

加入当前会话 PATH：

$env:Path = "C:\Users\<YourUsername>\.local\bin;" + $env:Path

然后构建：

uv build --no-sources

在 Thonny 中测试：

1. 打开 Thonny。
2. 进入 Tools -> Manage plug-ins...
3. 选择 Install from local file。
4. 选择 dist/ 中生成的 wheel。
5. 重启 Thonny，确认插件能够显示。

4. 发布

在 pypi.org 注册账号，在账号设置的 API tokens 页面创建发布用 token。

设置 token：

macOS / Linux：

export UV_PUBLISH_TOKEN="pypi-REPLACE_WITH_YOUR_TOKEN"

Windows PowerShell：

$env:UV_PUBLISH_TOKEN="pypi-REPLACE_WITH_YOUR_TOKEN"

Windows 命令提示符：

set UV_PUBLISH_TOKEN=pypi-REPLACE_WITH_YOUR_TOKEN

然后发布：

uv publish

发布完成后，在 pypi.org/project/thonny-upypi-manager/ 确认新版本已显示，再在 Thonny 的 Tools -> Manage plug-ins... 中搜索 thonny-upypi-manager 确认可以找到。

备注

• 支持 Windows、macOS 和 Linux。
• v1 不涉及卸载、升级和覆盖安装行为。
• 构建产物不应提交到仓库。