Sample PoC of PyPi packaging PEP-561 stubs for Micropython Esp32.

As it is only "proof-of-concept" it NOT assumed to for production use and package can be deleted in the future. Another purspose of this project is collect info about stubbing

For the production implementation please see:

• https://pypi.org/project/micropython-esp32-stubs
• https://pypi.org/project/micropython-esp8266-stubs
• https://pypi.org/project/micropython-stm32-stubs
• https://pypi.org/project/micropython-rp2-stubs
• https://github.com/Josverl/micropython-stubs

pip3 install esp32-test-stubs

Next script correct working in PyCharm for autocompete and analyzing with only installed stub package via standart pip command. All types does not show any warnings and recognized properly:

import machine
machine.freq()

import esp32
esp32.NVS()
esp32.wake_on_ext0("Test")

from esp.sub_pkg import sub_pkg_fun
sub_pkg_fun()

from esp32.sub_pkg import sub_pkg_function
sub_pkg_function()

import uuid

# Points to stdlib
uuid.uuid4()

# Points to stub (mean partial stub, so extent stdlib)
# (see uuid-stubs and py.typed)
uuid.uuid6()

import upip
upip.cleanup()

• Project root *.pyi files
• <package>-stubs with __init__.pyi (see stub-only packages)
• <package>-stubs/<sub_package>.pyi (see stub-only-packages)
• "custom folders" (Not recommended) - like src, marked as package = [{ include = "*.pyi" , from = "src"}], under hood all *.pyi will be moved into package root during package build.
  CONS:
  • "custom folders" does not recognize as stub source before stub package will pack properly.
  • stubs not moved properly in in target *.tar.gz build, so it led to potential errors during stub recognition from pure sources.

Note: all of these variants should be explicitly marked in pyproject.toml in Poetry (see package section pyproject.toml)

• Prepare

  poetry config repositories.testpypi https://test.pypi.org/legacy/
  poetry config pypi-token.testpypi <TOKEN>
  
  poetry config repositories.pypi https://upload.pypi.org/legacy/
  poetry config pypi-token.pypi <TOKEN>

• Publish

  poetry publish --build -r testpypi
  poetry publish --build -r pypi

• PyCharm Micropython plugin stubs
• Brython stubs

• PEP-484 - Type Hints, Stub Files
• PEP-561 - Distributing and Packaging Type
• Real world stubs example (Numpy)
• Poetry stub-only project examples
• stubgen - generate stubs from code
• stubtest - tool for validate stubs files against implementaion (info)
• merge-pyi - merge pyi types to py files
• tools for stubbing - list of tools for working with stubs