Metadata-Version: 2.4
Name: thonny-upypi-manager
Version: 0.1.0
Summary: Thonny plugin for searching and installing uPyPi packages
Author: Ali
Project-URL: Homepage, https://thonny.org/
Project-URL: Source, https://github.com/FreakStudioCN/upypi
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

`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. It is easier to hand over, easier to install consistently, and closer to how a packaged release should behave. Manual copy is still useful for quick testing.

### 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.0-py3-none-any.whl
```

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

This is the recommended installation method for client handoff.

### Option 2: Install by copying the package

Copy the `thonnycontrib/upypi_manager` directory into Thonny's user plugin `site-packages` directory so the final structure contains:

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

The exact `pythonX.Y` version depends on the Python runtime bundled with or used by the local Thonny installation.

After copying the files, restart Thonny.

### Platform notes

- Windows: make sure `mpremote` is installed and available on `PATH` if install-to-device support is required. Device discovery supports Windows `COM` ports (e.g. `COM3`) as well as `/dev/` paths on Linux and macOS.
- macOS: if `mpremote` is installed with Homebrew or user-local Python tools, launch Thonny from an environment where that executable is on `PATH`.
- Linux: distro-managed Python environments may block system-wide `pip install` usage. If `mpremote` is needed, install it in a virtual environment or other user-managed environment and launch Thonny with that `PATH`.

## Development

Thonny discovers third-party plugins under the `thonnycontrib` namespace package. During local development, add this repository to `PYTHONPATH` and launch Thonny from the same environment:

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

If you are testing install-to-device flows, make sure `mpremote` is available on `PATH` for the process that launches Thonny.

## Packaging

Build distribution artifacts with:

```bash
python -m build
```

This produces a wheel and source distribution under `dist/`.

You do not need a wheel for local development, but you should build one before sharing the plugin with a client or validating the packaged install flow.

## Notes

- Windows, macOS, and Linux are intended targets.
- Uninstall, upgrade, and overwrite behavior are out of scope for v1.
- This repository currently contains the plugin source. Build outputs should not be committed.
