is it possible to create stubs for a small library (not mine) that I use with micropython

[jonhp]

I use an independent library of about 10 .py files. is it possible to create stubs just for the library and then manually add them to my typings folder so they get handled just like they were "machine" or "network"? if this is already documented somewhere, I apologize for not finding it.

[Josverl]

Yes, that should be possible with some manual work, and it's documented in patches across the internet...

But let's try to improve that😁

If you can share a link to your module,
Then together we can work out how to do that, document it as we go.
I know several approaches and tools that may work

I can add the docs somewhere once we have the process.

[jonhp]

Hi Jos,
What a kind and generous offer. The python libarary that I am using is not mine,
but it is in the public domain. I don't think the author would have any objections,
however, I could ask if you felt it necessary (MIT License).

The library is found here: HT16K33
I have a clone of this repro without any local changes that I use.
The folder structure is:

ht16k33.py
ht16k33bar.py
ht16k33matrix.py
ht16k33matrixcolour.py
ht16k33matrixfeatherwing.py
ht16k33matrixmulti.py
ht16k33segment.py
ht16k33segment14.py
ht16k33segmentbig.py
ht16k33segmentgen.py
init.py

Thoughts on how we proceed?
Jon

[Josverl]

A quick step by step that you can follow :
Create a workfolder, ( optionally run git init in the workfolder)

md workfolder
cd workfolder
uv venv
.venv\Scripts\activate

uv pip install micropython-stubber 
uv pip install auto-type-annotate
uv pip install micropython-esp32-stubs --target typings --no-deps 
git clone https://github.com/smittytone/HT16K33-Python

the resulting strcture should be something like this

workfolder
+---.venv
+---HT16K33-Python
|   +---ht16k33
|   +---examples
|   |   +---circuitpython
|   |   \---micropython
|   \---tools
\---typings

This also installs tools that are helpfull

1. pyright --createstub - generates stubs for a given module, part of pyright.
2. stubgen - generates stubs for a given module, part of mypy.

I my experience pyright is better at generating stubs for micropython modules, especially if the sources are not well annotated, or contain docstrings.

before running pyright --createstubs, first check if the provided code can pass a basic type check by runnin pyright on the code ``

If it fails, you can still create stubs, but you may need to change both the stubs and the code later.

cd src
pyright --createstub ht16k33

This will create a folder typings\ht16k33, containing the stubs for the module.

You can commit the typings\ht16k33 folder to git to keep track of the changes. ( git add typings\ht16k33 , git commit -m "added stubs for ht16k33")

If the source did not contain type information or docstrings, you will need to add them manually to the .pyi files that were created.

you can refer to both the standard python types and classes ( int , str, float ) and the MicroPython types ( machine.I2C, machine.Pin, etc ) to add type information to the stubs.

If you don't know the type of a variable, you can use Incomple as a type hint. This is a special type hint that indicates that the type is not known, but it is expected to be a valid type. Or you can just omit the type hint.

Initial basic stub : typings\ht16k33\ht16k33.pyi

class HT16K33:
    # ...
    HT16K33_GENERIC_DISPLAY_ON = ...
    # ...
    def __init__(self, i2c, i2c_address) -> None:
        ...

    def set_brightness(self, brightness = ...) -> None:
        ...

with some manual improvements

from typing import Literal, TypeAlias
from typeshed impint 
from machine import I2C
from _typeshed import Incomplete

_Brightness : TypeAlias = Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]

class HT16K33:
    # ...
    HT16K33_GENERIC_DISPLAY_ON : int = ...
    # ...
    def __init__(self, i2c:I2C, i2c_address:int) -> None:
        ...

    def set_blink_rate(self, rate:Incomplete = 0) -> None:
        ...

    def set_brightness(self, brightness:_Brightness = 15) -> None:
        ...