As this PR have changed very significantly I have completely rewritten the PR Description.
The old description can be found at the end.

This is a MicroPython alternative to:

• the C-based minimal typing module proposed in extmod: Implement a minimal typing module. micropython#15911
• the MicroPython Py-based typing module proposed in typing: Add typing module #584
• MicroPython-Stubs typing modules https://github.com/Josverl/micropython-stubs/tree/main/mip#micropythons-typingmpy-module

based on all the above and tuned for reduced firmware/frozen size, while keeping provable consistence with the relevant typing PEPs for features that are supported by MicroPython.

It consists of a number of modules that can be mip-installed or frozen as part of a firmware..
Note that the modules have been optimized for size - somewhat impacting readability - but where relevant the orignal code has been kept as comments.

For other related changes see later in this section.

Fixes: #190
Closes: micropython/micropython#15911
Closes: #584

I want to explicitly recognize that this work is in part based on and inspired the work by in PRs @stinos and @andrewleech and other individuals that have directly contributed to the typing stubs on the MicroPython-Stubs repo.

Summary of the modules:

• __future__ : contains the annotations feature, which allows for postponed evaluation
• typing : contains the core typing features, such as TypeVar, Generic, Protocol, Union, Optional, Callable and more.
• typing_extensions : features that are/were not yet part of the standard library for Python 3.4/3.5.
• collections.abc : contains the abstract base classes for collections, such as Iterable, Sequence, Mapping and more.
• abc : contains the ABC and abstractmethod features, while they are deprecated in Python 3.11, they are still relevant.

Implementation details:

The __future__ already existed as a basic list of assignments, and has been extended with only the annotations feature.

In order to save space in the firmware or on the file system the typing module uses a module level __getattr__ to lazily load the features of the module, rather than implement each typing class, method or decorator in detail. Care has been taken to match the runtime signatures of the CPython/Micropythn runtime , and reduce runtime overhead as much as possible.

The typing_extensions, abc and collections.abc modules re-use the same __getattr__ from the typing module and also include only limited implementations, again to save space.

each module can be frozen or installed individually, it will automatically pull in any required dependencies.

In order to further simplify installation or freezing a bundle-typing has been created that contains:

• __future__
• typing
• typing_extensions
  And optionally ( extensions=true ) also:
• abc
• collections.abc

The bundle also set the opt_level to 3, which will further reduce the size of the modules, but may impact readability of tracebacks.

# typing related modules
require(
    "bundle-typing",
    # extensions=False,  # Set to True to include collections.abc
    # opt_level=3,
)

Install from this PR:

The modules can be installed from this PR using the following command:

# install the bundle-typing 
mpremote mip install --index https://josverl.github.io/micropython-lib/mip/add_typing_py bundle-typing
# or each module individually
mpremote mip install --index https://josverl.github.io/micropython-lib/mip/add_typing_py __future__ typing typing_extensions collections-abc abc

# unittest 0.11.0
mpremote mip install --index https://josverl.github.io/micropython-lib/mip/add_typing_py unittest

( Do try this at home :-)

Testing:

I have spent perhaps more time on creating the tests than on the implementation, as I wanted to make sure that the implementation is consistent with the relevant PEPs and also to have a good coverage of the implemented features.
Currently there are 187 typing runtime tests, which are based on:

• The examples provided in the relevant PEPs, such as PEP 484, PEP 544, PEP 560 and more.
• A number of tests from the CPython test suite, such as test_typing and test_typing_extensions.
• Existing tests created for the MicroPython-stubs project
• AI generated, hand curated, tests for edge cases and features that are not covered by the above sources.
• A report generator that uses the existing test results to simplify comparison of the different implementations and variants.

Tests and test results

• Tests for all typing modules are located in micropython:tests/typing_runtime
• A tests for the new functionality of unittest has been added to micropython-lib:python-stdlib/unittest/tests

Test matrix

in order to compare the different optionas for implementation on both size and functionaly the followin variants have been tested:

Summary of test results

• Specified test(s): typing_runtime
  • micropython: yetanothertypingbranch (a0dcc1e43a8a)
  • micropython-lib: add_typing_py (0291143)
• Generated: 2026-06-04 22:08:51

Legend:

• ok=passed, xfail=expected failure, skip=test skipped
• FAIL=test failed, False Positive=unexpected success
• ERROR=test errored (also used when the test module crashed).
• Firmware sizes are reported in bytes from size <binary>.

typing_runtime/check_all_modules.py

probe module availability
test import only

See the full report.md

PR and merge dependencies

See the companion PR: micropython/micropython#19310

I'm open to recommendation on how the different parts needed to implement and test this functionality should be seperated into different PRs, across the different repos.

Apart from this PR there are at the following components needed:

1. unittest@0.11.0
   In order to be able to create tests, and clear reporting across the alternative implementations, I needed the test suite to be able to make use unittest.expectedFailure, and for unittest to report the Expected Failures and unexpected successes to the run-test.py test runner. This allows to distinguish on things that are not implemented in MicroPython, but are expected to fail ( User defined Generics[], MetaClass), from things that are implemented but not working as expected.

2. micropython:tests/run-test.py
   In turn, the run-test.py test runner needed to be updated to handle the additional information.

3. micropython:tools/make_report.py
   In order to keep an overview of all test results I have created a new tool make_report.py that builds a markdown report of the test results, which can be used to compare the results of different implementations and variants. This tool could also be used to compare other sets of PRs that implement the same features.

   Example report runner

   # example report run 
   report tests="typing_runtime": make_test_venv
       MICROPYPATH="{{MICROPYPATH_MIP}}" uv run tools/make_report.py \
           --variant standard=/home/jos/micropython.worktrees/runtime_typing/ports/unix/build-standard/micropython \
           --variant 1_mp-stubs=/home/jos/micropython.worktrees/runtime_typing/ports/unix/build-typing1/micropython \
           --variant 2a_typing=/home/jos/micropython.worktrees/runtime_typing/ports/unix/build-typing2a/micropython \
           --variant 2b_bundle_typing_S=/home/jos/micropython.worktrees/runtime_typing/ports/unix/build-typing2b/micropython \
           --variant 2c_bundle_typing_L=/home/jos/micropython.worktrees/runtime_typing/ports/unix/build-typing2c/micropython \
           --variant 3_builtintypingmodule=/home/jos/micropython.worktrees/runtime_typing/ports/unix/build-typing3/micropython \
           --variant 5_standard_mip_installed=/home/jos/micropython.worktrees/runtime_typing/ports/unix/build-standard/micropython \
           --variant 6_coverage=/home/jos/micropython.worktrees/runtime_typing/ports/unix/build-coverage/micropython \
           --keep-path 5_standard_mip_installed \
           --board RPI_PICO2=/dev/ttyACM0 \
           --board ESP32_C5=/dev/ttyACM1 \
           --out report.md \
           {{tests}}

Trade-offs and Alternatives

• Size versus accuracy:
  The implementation is optimized for size, which may impact readability and traceability of errors.
  Also due to the use of __getattr__ for lazy loading, some features may appear to be available, while they are actually not.
  For example:

  • from typing import NoSuchThing will not raise an ImportError at runtime.
  • import typing; dir(typing) will not work as expected but show a list of all QSTR's in the firmware.
    This is deemed acceptable as static type checkers and linter will catch this at development time.

• Size versus composability:
  While the freeezing of all .py files is larger than a fuctionally equivalant C implementation, it has the advanatge that is can be mip installed and also easily extended with new features, without the need to recompile the firmware.
  or any median can be accomplished by freezing only the core bundle-typing and mip installing other modules as appropriate.
  vfs size impact:

  $ mpremote df tree -s
  filesystem     size     used    avail use% mounted on
  <VfsLfs2>   3145728    45056  3100672    1 /
  tree :
  :/
  └── lib
      ├── [      194]  __future__.mpy
      ├── [      139]  abc.mpy
      ├── collections
      │   ├── [      274]  __init__.mpy
      │   └── [      112]  abc.mpy
      ├── [      642]  typing.mpy
      └── [      130]  typing_extensions.mpy
  

• Freezing methods:
  durign the quest to save firmware size, I have experimented with different freezing method. I noticed in particular that the __future__ made the fimware size increase by more that its .py file size. and could actually be stored smaller using freeze_as_str() at the cost of additional runtime overhead while loading. This was explained in Discussion
  This PR currently uses the require() method for all modules,to reduce or avoid memory fragmentation that is likely caused by compilation at runtime.

• unittest@0.11.0 and tools/run-tests.py:
  In order to be able to create tests for the typing modules, and to have clear reporting of expected failures and unexpected successes, I have added CPython compatible functionality to unittest

  That was defintly needed in order to develop this PR, but just guarding against regressiosn could be done using unittest@0.10.5, but that would require either removing.chaining the expected failure tests, or putting them behind a version check, which would make the tests less clear and more difficult to maintain.

  The update to tools/run-tests.py is minor, and adds just the abaility to parse the additional information, and is backward compatible with unittest@0.10.5.

  There is however no way for (a) unittest to check by which version of tools/run-tests.py it is being run.

Generative AI

I used generative AI tools when creating this PR, but a human has checked the
code and is responsible for the code and the description above.

# typing related modules
require(
    "bundle-typing",
    # extensions=False,  # Set to True to include collections.abc
    # opt_level=2,
)