CI: Add support for MicroPython (#27)

.github/workflows/tests.yml

@@ -51,11 +51,11 @@ jobs:
             pyproject.toml
             requirements*.txt
 
-      - name: Set up project tools
+      - name: Set up project requirements and tools
         run: uv pip install --system --requirement=requirements.txt --requirement=requirements-dev.txt
 
       - name: Run linters and software tests
-        run: poe check
+        run: poe check-cpython
 
       # https://github.com/codecov/codecov-action
       - name: Upload coverage results to Codecov
@@ -68,3 +68,55 @@ jobs:
           env_vars: OS,PYTHON
           name: codecov-umbrella
           fail_ci_if_error: false
+
+
+  test-micropython:
+    name: "
+    MicroPython ${{ matrix.micropython-version }}
+    "
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ['ubuntu-latest']
+        micropython-version: [
+          'v1.20.0',
+          'v1.24.0',
+          'v1.25.0-preview',
+        ]
+
+    env:
+      OS: ${{ matrix.os }}
+      MICROPYTHON: ${{ matrix.micropython-version }}
+
+    services:
+      cratedb:
+        image: crate/crate:nightly
+        ports:
+          - 4200:4200
+
+    steps:
+
+      - name: Acquire sources
+        uses: actions/checkout@v4
+
+      - name: Set up CPython
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Set up project tools
+        run: uv pip install --system poethepoet
+
+      # https://github.com/marketplace/actions/install-micropython
+      - name: Set up MicroPython ${{ matrix.micropython-version }}
+        uses: BrianPugh/install-micropython@v2
+        with:
+          reference: ${{ matrix.micropython-version }}
+
+      - name: Set up project requirements
+        run: micropython -m mip install base64 requests
+
+      - name: Run linters and software tests
+        run: poe check-micropython

README.md

@@ -444,7 +444,9 @@ Constants for each value of `code` are provided.  For example `4043` is `CRATEDB
 ## Examples
 
 The [`examples`](examples/) folder contains example MicroPython scripts, some of which are for specific microcontroller boards, including the popular Raspberry Pi Pico W.
-Hardware-independent example programs also work well on CPython, see [Running on CPython](./docs/cpython.md).
+Hardware-independent example programs also work well on CPython, and the
+MicroPython UNIX and Windows port, see [Running on CPython](./docs/cpython.md)
+and [Running on MicroPython](./docs/micropython.md).
 
 ## Testing
 

cratedb.py

@@ -129,7 +129,7 @@ def __make_request(self, sql, args=None, with_types=False, return_response=True)
                 payload["bulk_args"] = args
 
         try:
-            response = requests.post(request_url, headers=headers, json=payload)
+            response = requests.post(request_url, headers=headers, json=payload)  # noqa: S113
         except OSError as o:
             raise NetworkError(o)  # noqa: B904
 

docs/cpython.md

@@ -2,6 +2,11 @@
 
 The module is designed for [MicroPython], but also works on [CPython].
 
+While CPython does not provide hardware support usually available when
+running MicroPython on embedded devices, this is mostly not a concern
+when running a database driver.
+
+
 ## Setup
 
 Install Python package and project manager [uv].

docs/micropython.md

@@ -0,0 +1,49 @@
+# Running on MicroPython
+
+The module is designed for [MicroPython]. You can run it on embedded systems,
+and, thanks to the [MicroPython UNIX and Windows port], also on Linux, macOS,
+and Windows.
+
+While MicroPython on a workstation does not provide hardware support usually
+available when running MicroPython on embedded devices, this is mostly not
+a concern when running a database driver.
+
+
+## Embedded
+
+Todo.
+
+
+## Workstation
+
+### Setup
+
+Install MicroPython.
+```shell
+{apt,brew,pip,zypper} install micropython
+```
+
+Install requirements.
+```shell
+micropython -m mip install base64 requests
+```
+
+## Usage
+
+Start CrateDB.
+```shell
+docker run --rm -it --name=cratedb \
+  --publish=4200:4200 --publish=5432:5432 \
+  --env=CRATE_HEAP_SIZE=2g crate:latest -Cdiscovery.type=single-node
+```
+
+Invoke example programs.
+```shell
+export MICROPYPATH=".frozen:${HOME}/.micropython/lib:/usr/lib/micropython:$(pwd)"
+micropython examples/example_usage.py
+micropython examples/object_examples.py
+```
+
+
+[MicroPython]: https://en.wikipedia.org/wiki/Micropython
+[MicroPython UNIX and Windows port]: https://docs.micropython.org/en/latest/unix/quickref.html

pyproject.toml

@@ -90,8 +90,17 @@ exclude_lines = [
 [tool.poe.tasks]
 
 check = [
-  "lint",
-  "test",
+  "check-cpython",
+  "check-micropython",
+]
+
+check-cpython = [
+  "lint-cpython",
+  "test-cpython",
+]
+
+check-micropython = [
+  "test-micropython",
 ]
 
 format = [
@@ -102,18 +111,23 @@ format = [
   { cmd = "pyproject-fmt --keep-full-version pyproject.toml" },
 ]
 
-lint = [
+lint-cpython = [
   { cmd = "ruff format --check ." },
   { cmd = "ruff check ." },
   { cmd = "validate-pyproject pyproject.toml" },
 ]
 
-[tool.poe.tasks.test]
+[tool.poe.tasks."test-cpython"]
 cmd = "pytest"
-help = "Invoke software tests"
+help = "Invoke software tests on CPython"
 
-[tool.poe.tasks.test.args.expression]
+[tool.poe.tasks."test-cpython".args.expression]
 options = [ "-k" ]
 
-[tool.poe.tasks.test.args.marker]
+[tool.poe.tasks."test-cpython".args.marker]
 options = [ "-m" ]
+
+[tool.poe.tasks."test-micropython"]
+sequence = [
+  { shell = 'MICROPYPATH="${HOME}/.micropython/lib:$(pwd)" micropython tests/test_micropython.py' },
+]

tests/test_micropython.py

@@ -0,0 +1,21 @@
+# ruff: noqa: S605, S607
+import os
+
+
+def example_usage():
+    """
+    Validate `examples/example_usage.py` runs to completion.
+    """
+    assert os.system("micropython examples/example_usage.py") == 0
+
+
+def object_examples():
+    """
+    Validate `examples/object_examples.py` runs to completion.
+    """
+    assert os.system("micropython examples/object_examples.py") == 0
+
+
+if __name__ == "__main__":
+    example_usage()
+    object_examples()