Metadata-Version: 2.4
Name: setup2upypackage
Version: 0.8.0
Summary: Validate and create MicroPython package JSON file
Home-page: https://github.com/brainelectronics/micropython-package-validation
Author: brainelectronics
Author-email: info@brainelectronics.de
License: MIT
Project-URL: Bug Reports, https://github.com/brainelectronics/micropython-package-validation/issues
Project-URL: Source, https://github.com/brainelectronics/micropython-package-validation/
Keywords: micropython,package,mip-helper,validation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.7, <4
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: changelog2version<1,>=0.12.1
Requires-Dist: deepdiff<9,>=8.6.2
Requires-Dist: mock<6,>=5.2.0
Provides-Extra: dev
Requires-Dist: tox<5,>=4.30; extra == "dev"
Provides-Extra: test
Requires-Dist: flake8<8,>=7.3.0; extra == "test"
Requires-Dist: coverage<8,>=7.10; extra == "test"
Requires-Dist: nose2<1,>=0.16.0; extra == "test"
Requires-Dist: yamllint<2,>=1.37; extra == "test"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# MicroPython Package Validation

[![Downloads](https://pepy.tech/badge/micropython-package-validation)](https://pepy.tech/project/micropython-package-validation)
![Release](https://img.shields.io/github/v/release/brainelectronics/micropython-package-validation?include_prereleases&color=success)
![Python](https://img.shields.io/badge/python3-Ok-green.svg)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![codecov](https://codecov.io/github/brainelectronics/micropython-package-validation/branch/main/graph/badge.svg)](https://app.codecov.io/github/brainelectronics/micropython-package-validation)
[![CI](https://github.com/brainelectronics/micropython-package-validation/actions/workflows/release.yml/badge.svg)](https://github.com/brainelectronics/micropython-package-validation/actions/workflows/release.yml)

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][ref-rtd-micropython-package-validation] 📚

<!-- MarkdownTOC -->

- [Installation](#installation)
    - [Install required tools](#install-required-tools)
- [Installation](#installation-1)
- [Usage](#usage)
    - [Validate](#validate)
        - [Validate package JSON file](#validate-package-json-file)
        - [Validate package JSON file from changelog](#validate-package-json-file-from-changelog)
        - [Options](#options)
    - [Create](#create)
        - [Create package JSON file](#create-package-json-file)
            - [Create specific package JSON file](#create-specific-package-json-file)
        - [Create package JSON file from changelog](#create-package-json-file-from-changelog)
        - [Create package JSON file with files other than Python](#create-package-json-file-with-files-other-than-python)
- [Contributing](#contributing)
    - [Unittests](#unittests)
    - [Precommit hooks](#precommit-hooks)
- [Credits](#credits)

<!-- /MarkdownTOC -->

## Installation

### Install required tools

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

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

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

pip install -r requirements.txt
```

## Installation

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

```json
{"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.

```bash
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][ref-changelog2version], the semantic version changelog can
be specified explicitly to use its latest entry for the version value.

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

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

```bash
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][ref-changelog2version], the semantic version changelog can
be specified explicitly to use its latest entry for the version value.

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

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

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

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

```bash
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][ref-pypa-sample].

<!-- Links -->
[ref-rtd-micropython-package-validation]: https://micropython-package-validation.readthedocs.io/en/latest/
[ref-pypa-sample]: https://github.com/pypa/sampleproject
[ref-changelog2version]: https://github.com/brainelectronics/changelog2version
