Metadata-Version: 2.4
Name: thonny-upypi-manager
Version: 0.1.1
Summary: Thonny plugin for searching and installing uPyPi packages
Author: Ali, leezisheng
Project-URL: Homepage, https://upypi.net
Project-URL: Source, https://github.com/leezisheng/thonny-upypi-manager
Keywords: thonny,micropython,upypi,mpremote
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.0

# thonny-upypi-manager

---

## Table of Contents / 目录

- [English](#english)
  - [Current scope](#current-scope)
  - [Project layout](#project-layout)
  - [Installation](#installation)
  - [Development](#development)
  - [Packaging](#packaging)
  - [Publishing to PyPI](#publishing-to-pypi)
  - [Notes](#notes)
- [中文](#中文)
  - [功能范围](#功能范围)
  - [项目结构](#项目结构)
  - [安装](#安装)
  - [开发](#开发)
  - [打包](#打包)
  - [发布到 PyPI](#发布到-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:

```bash
python -m build
```

This creates a file under `dist/`, for example:

```text
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`:

```text
.../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:

```bash
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:

```bash
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](https://docs.astral.sh/uv)), then run:

```bash
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](https://pypi.org), then generate an API token from account settings.

Set your token:

macOS / Linux:
```bash
export UV_PUBLISH_TOKEN="pypi-REPLACE_WITH_YOUR_TOKEN"
```

Windows PowerShell:
```powershell
$env:UV_PUBLISH_TOKEN="pypi-REPLACE_WITH_YOUR_TOKEN"
```

Windows Command Prompt:
```cmd
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:
```bash
rm -rf dist/
```

Windows PowerShell:
```powershell
Remove-Item dist\* -Recurse -Force
```

Then rebuild and publish:
```bash
uv build --no-sources
uv publish
```

Confirm the release at [pypi.org/project/thonny-upypi-manager/](https://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)

```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：

```bash
python -m build
```

生成文件示例：

```text
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`：

```text
.../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：

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

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

### 打包

构建发布产物：

```bash
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](https://docs.astral.sh/uv) 安装。

Windows PowerShell 安装 `uv`：

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

加入当前会话 PATH：

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

然后构建：

```bash
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](https://pypi.org) 注册账号，在账号设置的 **API tokens** 页面创建发布用 token。

设置 token：

macOS / Linux：
```bash
export UV_PUBLISH_TOKEN="pypi-REPLACE_WITH_YOUR_TOKEN"
```

Windows PowerShell：
```powershell
$env:UV_PUBLISH_TOKEN="pypi-REPLACE_WITH_YOUR_TOKEN"
```

Windows 命令提示符：
```cmd
set UV_PUBLISH_TOKEN=pypi-REPLACE_WITH_YOUR_TOKEN
```

然后发布：
```bash
uv publish
```

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

### 备注

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