Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/BradenM/micropy-cli

Micropython Project Management Tool with VSCode support, Linting, Intellisense, Dependency Management, and more!
https://github.com/BradenM/micropy-cli

autocompletion automate cli ide intellisense linting microcontroller micropython pylint stubs visual-studio-code vscode

Last synced: 2 months ago
JSON representation

Micropython Project Management Tool with VSCode support, Linting, Intellisense, Dependency Management, and more!

Lists

README 

        
# Micropy Cli [![PyPI][pypi-img]][pypi-url] [![PyPI - Python Version][pypiv-img]][pypi-url] [![Github - Test Micropy Cli][build-img]][build-url] [![Coverage Status][cover-img]][cover-url]



Micropy Cli is a project management/generation tool for writing [Micropython](https://micropython.org/) code in modern IDEs such as VSCode.

Its primary goal is to automate the process of creating a workspace complete with:



* **Linting** compatible with Micropython

* VSCode **Intellisense**

* **Autocompletion**

* Dependency Management

* VCS Compatibility





    Micropy Demo SVG




[pypi-img]: https://img.shields.io/pypi/v/micropy-cli?logo=pypi&logoColor=white&style=flat-square

[pypi-url]: https://pypi.org/project/micropy-cli/

[pypiv-img]: https://img.shields.io/pypi/pyversions/micropy-cli.svg?style=flat-square&logo=python&logoColor=green

[build-img]: https://img.shields.io/github/workflow/status/BradenM/micropy-cli/Test%20MicropyCli/master?logo=github&style=flat-square

[build-url]: https://github.com/BradenM/micropy-cli/actions

[cover-img]: https://img.shields.io/coveralls/github/BradenM/micropy-cli/master?style=flat-square&logo=coveralls

[cover-url]: https://coveralls.io/github/BradenM/micropy-cli



# Getting Started



## Installation



You can download and install the latest version of this software from the Python package index (PyPI) as follows:



`pip install --upgrade micropy-cli`



If applicable, you can test out a pre-release by executing:



`pip install --upgrade --pre micropy-cli`



## Creating a Project



Creating a new project folder is as simple as:



1. Executing `micropy init `

2. Selecting which features to enable

3. Selecting your target device/firmware

4. Boom. Your workspace is ready.





    Micropy Demo




## Micropy Project Environment



When creating a project with `micropy-cli`, two special items are added:



* A `.micropy/` folder

* A `micropy.json` file



The `.micropy/` contains symlinks from your project to your `$HOME/.micropy/stubs` folder. By doing this, micropy can reference the required stub files for your project as relative to it, rather than using absolute paths to `$HOME/.micropy`. How does this benefit you? Thanks to this feature, you can feel free to push common setting files such as `settings.json` and `.pylint.rc` to your remote git repository. This way, others who clone your repo can achieve a matching workspace in their local environment.



> Note: The generated `.micropy/` folder should be *IGNORED* by your VCS. It is created locally for each environment via the `micropy.json` file.



The `micropy.json` file contains information micropy needs in order to resolve your projects required files when other clone your repo. Think of it as a `package.json` for micropython.



## Cloning a Micropy Environment



To setup a Micropy environment locally, simply:



* Install `micropy-cli`

* Navigate to the project directory

* Execute `micropy`



Micropy will automatically configure and install any stubs required by a project thanks to its `micropy.json` file.



## Project Dependencies



While all modules that are included in your targeted micropython firmware are available with autocompletion, intellisense, and linting, most projects require external dependencies.



Currently, handling dependencies with micropython is a bit tricky. Maybe you can install a cpython version of your requirement? Maybe you could just copy and paste it? What if it needs to be frozen?



Micropy handles all these issues for you automatically. Not only does it track your project's dependencies, it keeps both `requirements.txt` and `dev-requirements.txt` updated, enables autocompletion/intellisense for each dep, and allows you to import them just as you would on your device.



This allows you to include your requirement however you want, whether that be as a frozen module in your custom built firmware, or simply in the `/lib` folder on your device.



#### Installing Packages



To add a package as a requirement for your project, run:



`micropy install `



while in your project's root directory.



This will automatically execute the following:



* Source `PACKAGE_NAMES` from pypi, as a url, or a local path

* Retrieve the module/package and stub it, adding it to your local `.micropy` folder.

* Add requirement to your `micropy.json`

* Update `requirements.txt`



To install dev packages that are not needed on your device, but are needed for local development, add the `--dev` flag. This will do everything above **except** stub the requirement.



You can also install all requirements found in `micropy.json`/`requirements.txt`/`dev-requirements.txt` by executing `micropy install` without passing any packages. Micropy will automatically do this when setting up a local environment of an existing micropy project.



#### Example



Lets say your new project will depend on [picoweb](https://pypi.org/project/picoweb/) and [blynklib](https://pypi.org/project/blynklib/). Plus, you'd like to use [rshell](https://pypi.org/project/rshell/) to communicate directly with your device. After creating your project via `micropy init`, you can install your requirements as so:





    Micropy Pkg Install Demo




Now you or anybody cloning your project can import those requirements normally, and have the benefits of all the features micropy brings:





    Micropy Deps Demo




## Stub Management



Stub files are the magic behind how micropy allows features such as linting, Intellisense, and autocompletion to work. To achieve the best results with MicropyCli, its important that you first add the appropriate stubs for the device/firmware your project uses.



> Note: When working in a micropy project, all stub related commands will also be executed on the active project. (i.e if in a project and you run `micropy stubs add `, then that stub retrieved AND added to the active project.)



### Adding Stubs



Adding stubs to Micropy is a breeze. Simply run: `micropy stubs add `

By sourcing [micropy-stubs](https://github.com/BradenM/micropy-stubs), MicroPy has several premade stub packages to choose from.



These packages generally use the following naming schema:



`--`



For example, running `micropy stubs add esp32-micropython-1.11.0` will install the following:

* Micropython Specific Stubs

* ESP32 Micropython v1.11 Device Specific Stubs

* Frozen Modules for both device and firmware



You can search stubs that are made available to Micropy via `micropy stubs search `



Alternatively, using `micropy stubs add `, you can manually add stubs to Micropy.

For manual stub generation, please see [Josvel/micropython-stubber](https://github.com/Josverl/micropython-stubber).



### Creating Stubs



Using `micropy stubs create `, MicropyCli can automatically generate and add stubs from any Micropython device you have on hand. This can be done over both USB and WiFi.



> Note: For stub creation, micropy-cli has additional dependencies.

>

> These can be installed by executing: `pip install micropy-cli[create_stubs]`



### Viewing Stubs



To list stubs you have installed, simply run `micropy stubs list`.



To search for stubs for your device, use `micropy stubs search `.



# See Also



* [VSCode IntelliSense, Autocompletion & Linting capabilities][lemariva-blog]

    - An awesome article written by [lemariva](https://github.com/lemariva). It covers creating a micropython project environment from scratch using `micropy-cli` and [pymakr-vsc](pymakr-vsc). Great place to start if you're new to this!



* [Developing for the Raspberry Pi Pico in VS Code][cpwood-medium]

    - A getting started guide for developing in micropython on the Raspberry Pi Pico by [cpwood][cpwood-git].

    - Also see: [Pico-Go: Micropy-Cli][cpwood-picogo]



* [Awesome MicroPython][awesome-micropy]

    - Collection of awesome micropython libraries / resources.

    - Features `micropy-cli` along with several other great development tools under the [Development][awesome-micropy-develop] category.



[lemariva-blog]: https://lemariva.com/blog/2019/08/micropython-vsc-ide-intellisense

[lemariva-git]:  https://github.com/lemariva



[cpwood-medium]: https://medium.com/all-geek-to-me/developing-for-the-raspberry-pi-pico-in-vs-code-getting-started-6dbb3da5ba97

[cpwood-picogo]: http://pico-go.net/docs/help/micropy/

[cpwood-git]: https://github.com/cpwood/



[awesome-micropy]: https://awesome-micropython.com/

[awesome-micropy-develop]: https://awesome-micropython.com/#development



# Acknowledgements



## Micropython-Stubber

[Josvel/micropython-stubber](https://github.com/Josverl/micropython-stubber)



Josverl's Repo is full of information regarding Micropython compatibility with VSCode and more. To find out more about how this process works, take a look at it.



micropy-cli and [micropy-stubs](https://github.com/BradenM/micropy-stubs) depend on micropython-stubber for its ability to generate frozen modules, create stubs on a pyboard, and more.