Initial commit

.github/workflows/build.yml

@@ -0,0 +1,42 @@
+name: Build
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Build (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.9', '3.10', '3.11']
+
+    env:
+      TERM: xterm-256color
+      RELEASE_FILE: ${{ github.event.repository.name }}-${{ github.event.release.tag_name || github.sha }}-py${{ matrix.python }}
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install Dependencies
+        run: |
+          make dev-deps
+
+      - name: Build Packages
+        run: |
+          make build
+
+      - name: Upload Packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ env.RELEASE_FILE }}
+          path: dist/

.github/workflows/qa.yml

@@ -0,0 +1,43 @@
+name: QA
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Linting & Spelling
+    runs-on: ubuntu-latest
+    env:
+      TERM: xterm-256color
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python '3,11'
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Dependencies
+        run: |
+          make dev-deps
+
+      - name: Run Quality Assurance
+        run: |
+          make qa
+
+      - name: Run Code Checks
+        run: |
+          make check
+
+      - name: Run Bash Code Checks
+        run: |
+          make shellcheck
+
+      - name: Run Tool Code Checks
+        run: |
+          ruff check tools

.github/workflows/test.yml

@@ -0,0 +1,42 @@
+name: Tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    env:
+      TERM: xterm-256color
+    strategy:
+      matrix:
+        python: ['3.9', '3.10', '3.11']
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install Dependencies
+        run: |
+          make dev-deps
+
+      - name: Run Tests
+        run: |
+          make pytest
+
+      - name: Coverage
+        if: ${{ matrix.python == '3.9' }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          python -m pip install coveralls
+          coveralls --service=github

.gitignore

@@ -0,0 +1,20 @@
+build/
+_build/
+*.o
+*.so
+*.a
+*.py[cod]
+*.egg-info
+dist/
+__pycache__
+.DS_Store
+*.deb
+*.dsc
+*.build
+*.changes
+*.orig.*
+packaging/*tar.xz
+library/debian/
+.coverage
+.pytest_cache
+.tox

CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+0.0.1
+-----
+
+* Initial Release

LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Pimoroni Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

Makefile

@@ -0,0 +1,62 @@
+LIBRARY_NAME := $(shell hatch project metadata name 2> /dev/null)
+LIBRARY_VERSION := $(shell hatch version 2> /dev/null)
+REPO := $(shell git remote get-url origin)
+
+.PHONY: usage pytest qa dev-deps check tag clean testdeploy deploy package.json
+usage:
+ifdef LIBRARY_NAME
+	@echo "Library: ${LIBRARY_NAME}"
+	@echo "Version: ${LIBRARY_VERSION}\n"
+else
+	@echo "WARNING: You should 'make dev-deps'\n"
+endif
+	@echo "Usage: make <target>, where target is one of:\n"
+	@echo "dev-deps:     install Python dev dependencies"
+	@echo "check:        perform basic integrity checks on the codebase"
+	@echo "qa:           run linting and package QA"
+	@echo "pytest:       run Python test fixtures"
+	@echo "clean:        clean Python build and dist directories"
+	@echo "build:        build Python distribution files"
+	@echo "testdeploy:   build and upload to test PyPi"
+	@echo "deploy:       build and upload to PyPi"
+	@echo "tag:          tag the repository with the current version\n"
+
+version:
+	@hatch version
+
+dev-deps:
+	python3 -m pip install -r requirements-dev.txt
+	sudo apt install dos2unix shellcheck
+
+check:
+	@bash check.sh
+
+shellcheck:
+	shellcheck *.sh
+
+qa:
+	tox -e qa
+
+package.json:
+	./tools/mkpackagejson.py --ver ${LIBRARY_VERSION} --repo ${REPO} src/
+
+pytest:
+	tox -e py
+
+nopost:
+	@bash check.sh --nopost
+
+tag: version
+	git tag -a "v${LIBRARY_VERSION}" -m "Version ${LIBRARY_VERSION}"
+
+build: check
+	@hatch build
+
+clean:
+	-rm -r dist
+
+testdeploy: build
+	twine upload --repository testpypi dist/*
+
+deploy: nopost build
+	twine upload dist/*

README.md

@@ -0,0 +1,19 @@
+# Boilerplate MicroPython
+
+This boilerplate repository is intended to be a starting point for library
+authors creating a `mip`-compatible library that is also available via
+PyPI (and thus installable by Thonny's Tools -> Manage Packages.)
+
+## package.json
+
+Specify a package installable via `mip`.
+
+The format for this file is documented at https://docs.micropython.org/en/latest/reference/packages.html#writing-publishing-packages
+
+You can generate it automatically by running `make package.json`, though
+this will not handle dependencies.
+
+## pyproject.toml
+
+Specify a Python package which can be built with `hatch` and deployed to
+the Python Package Index.

check.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+
+# This script handles some basic QA checks on the source
+
+NOPOST=$1
+LIBRARY_NAME=$(hatch project metadata name)
+LIBRARY_VERSION=$(hatch version | awk -F "." '{print $1"."$2"."$3}')
+POST_VERSION=$(hatch version | awk -F "." '{print substr($4,0,length($4))}')
+TERM=${TERM:="xterm-256color"}
+
+success() {
+	echo -e "$(tput setaf 2)$1$(tput sgr0)"
+}
+
+inform() {
+	echo -e "$(tput setaf 6)$1$(tput sgr0)"
+}
+
+warning() {
+	echo -e "$(tput setaf 1)$1$(tput sgr0)"
+}
+
+while [[ $# -gt 0 ]]; do
+	K="$1"
+	case $K in
+	-p|--nopost)
+		NOPOST=true
+		shift
+		;;
+	*)
+		if [[ $1 == -* ]]; then
+			printf "Unrecognised option: %s\n" "$1";
+			exit 1
+		fi
+		POSITIONAL_ARGS+=("$1")
+		shift
+	esac
+done
+
+inform "Checking $LIBRARY_NAME $LIBRARY_VERSION\n"
+
+inform "Checking package.json version..."
+JSON_VERSION=$(
+	python - <<EOF
+import json
+print(json.load(open("package.json"))["version"])
+EOF
+)
+if [[ "$LIBRARY_VERSION" != "$JSON_VERSION" ]]; then
+    warning "package.json version ($JSON_VERSION) does not match library version ($LIBRARY_VERSION)."
+    exit 1
+fi
+
+inform "Checking for trailing whitespace..."
+if grep -IUrn --color "[[:blank:]]$" --exclude-dir=dist --exclude-dir=.tox --exclude-dir=.git --exclude=PKG-INFO; then
+    warning "Trailing whitespace found!"
+    exit 1
+else
+    success "No trailing whitespace found."
+fi
+printf "\n"
+
+inform "Checking for DOS line-endings..."
+if grep -lIUrn --color $'\r' --exclude-dir=dist --exclude-dir=.tox --exclude-dir=.git --exclude=Makefile; then
+    warning "DOS line-endings found!"
+    exit 1
+else
+    success "No DOS line-endings found."
+fi
+printf "\n"
+
+inform "Checking CHANGELOG.md..."
+if ! grep "^${LIBRARY_VERSION}" CHANGELOG.md > /dev/null 2>&1; then
+    warning "Changes missing for version ${LIBRARY_VERSION}! Please update CHANGELOG.md."
+    exit 1
+else
+    success "Changes found for version ${LIBRARY_VERSION}."
+fi
+printf "\n"
+
+inform "Checking for git tag ${LIBRARY_VERSION}..."
+if ! git tag -l | grep -E "${LIBRARY_VERSION}$"; then
+    warning "Missing git tag for version ${LIBRARY_VERSION}"
+fi
+printf "\n"
+
+if [[ $NOPOST ]]; then
+    inform "Checking for .postN on library version..."
+    if [[ "$POST_VERSION" != "" ]]; then
+        warning "Found .$POST_VERSION on library version."
+        inform "Please only use these for testpypi releases."
+        exit 1
+    else
+        success "OK"
+    fi
+fi

package.json

@@ -0,0 +1,9 @@
+{
+ "version": "0.0.1",
+ "urls": [
+  [
+   "boilerplate/__init__.py",
+   "github:pimoroni/boilerplate-micropython/src/boilerplate/__init__.py"
+  ]
+ ]
+}