MicroPython Package Validation

Validate and create MicroPython package JSON file

General

MicroPython Package Validation for mip package.json files

📚 The latest documentation is available at MicroPython Package Validation ReadTheDocs 📚

• Installation
  • Install required tools
• Installation
• Usage
  • Validate
    • Validate package JSON file
    • Validate package JSON file from changelog
    • Options
  • Create
    • Create package JSON file
      • Create specific package JSON file
    • Create package JSON file from changelog
    • Create package JSON file with files other than Python
• Contributing
  • Unittests
  • Precommit hooks
• Credits

Installation

Install required tools

Python3 must be installed on your system. Check the current Python version with the following command

python --version
python3 --version

Depending on which command Python 3.x.y (with x.y as some numbers) is returned, use that command to proceed.

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt

Installation

pip install setup2upypackage

Usage

Validate

The optional arg --pretty can be used to output human readable content instead of JSON data in case of a failure.

The machine readable JSON output might look like and can directly be processed with e.g. jq using upy-package ... --validate 2> >(jq -r '.'):

{
    "values_changed":
    {
        "root['urls'][1][0]":
        {
            "new_value": "be_upy_blink/blink2.py",
            "old_value": "be_upy_blink/blink.py"
        }
    }
}

The human readable output using --pretty might look like:

Mismatch between "setup.py" and "package.json"
Diff: Value of root['urls'][1][0] changed from "be_upy_blink/blink.py" to "be_upy_blink/blink2.py".

Validate package JSON file

The following command will exit with a non-zero code in case of a difference between the generated (based on setup.py) and existing package (package.json) content.

upy-package \
    --setup_file tests/data/setup.py \
    --package_changelog_file tests/data/sample_changelog.md \
    --package_file tests/data/package.json \
    --validate

Validate package JSON file from changelog

In case the package version is defined by a changelog and the version entry of the setup.py file is filled on demand by e.g. changelog2version, the semantic version changelog can be specified explicitly to use its latest entry for the version value.

upy-package \
    --setup_file tests/data/setup.py \
    --package_changelog_file tests/data/sample_changelog.md \
    --package_file tests/data/package.json \
    --validate

Options

To not take the version or the dependencies specified in the package.json file during a validation run, use the --ignore-version or --ignore-deps argument. Additionally added boot.py and main.py files in package.json can be ignored using --ignore-boot-main during a validation run.

Create

Using the optional --pretty argument will pretty format all JSON output in the generated output file and on the optional console output.

Create package JSON file

The following command creates a package.json file in the same directory as the specified setup.py file. The content of the package.json file is additionally printed to stdout (--print) with an indentation of 4 (due to the --pretty option)

upy-package \
    --setup_file tests/data/setup.py \
    --create \
    --print \
    --pretty

Create specific package JSON file

A specific package JSON file can be specified with the --package_file parameter. The file has to exist before running the command.

upy-package \
    --setup_file tests/data/setup.py \
    --package_file tests/data/custom-package.json \
    --create \
    --print \
    --pretty

Create package JSON file from changelog

In case the package version is defined by a changelog and the version entry of the setup.py file is filled on demand by e.g. changelog2version, the semantic version changelog can be specified explicitly to use its latest entry for the version value.

upy-package \
    --setup_file tests/data/setup.py \
    --package_changelog_file tests/data/sample_changelog.md \
    --create \
    --print \
    --pretty

Create package JSON file with files other than Python

By default all *.py files of the packages defined by the setup.py file are used to create the list of URLs in the package.json file. For a cross compiled MicroPython package the generated *.mpy files would not be picked up and added to the package.json file. The CLI arg --package_file_glob allows setting a different pattern than *.py to include different types of files. The specified pattern is not extending the default pattern, but replacing it. In order to include *.py and *.mpy files may use the pattern *.*py

upy-package \
    --setup_file tests/data/setup.py \
    --package_file_glob "*.mpy" \
    --create \
    --print \
    --pretty

Contributing

Unittests

Run the unittests locally with the following command after installing this package in a virtual environment

# run all tests
nose2 --config tests/unittest.cfg

# run only one specific tests
nose2 tests.test_setup2upypackage.TestSetup2uPyPackage.test_package_version

Generate the coverage files with

python create_report_dirs.py
coverage html

The coverage report is placed at reports/coverage/html/index.html

Precommit hooks

This repo is equipped with a .pre-commit-hooks.yaml file to be usable in other repos.

In order to run this repo's pre commit hooks, perform the following steps

pip install pre-commit
# for older systems without colored output support, last supported version is
# 1.18.3 (7c3404ef1f7593094c854f99bcd3b3eec75fbb2f, 1.19.0 broke it)
# test it with:
# from os import openpty
# r,w = openpty()

pre-commit run --all-files

Credits

Based on the PyPa sample project.