Feat/type checking - #19742

Summary

Special cases the parser's handling of TYPE_CHECKING.
It treats an assignment of exactly TYPE_CHECKING = False as an private constant that can
be further optimised (out) by the compiler. It is treated similar to _TYPE_CHECKING = const(False).

This allows code that is only needed by static type checkers, such as imports
from typing or method stubs, to be added without any runtime or code size
overhead, because code guarded by if TYPE_CHECKING: is removed from the
bytecode::

TYPE_CHECKING = False
if TYPE_CHECKING:
    from typing import Callable

class Display:
     def write_cmd(self, cmd: int, cb: Callable[[int], None] | None = None) -> None: 
         print("cmd", hex(cmd))
         if cb:
             cb(cmd)

d = Display()
d.write_cmd(0x01) 
d.write_cmd(0x02, lambda x: print("callback", hex(x)))
d.write_cmd(0x03, lambda : print("bad callback")) # <-- Type Check Error:
# Function accepts too few positional parameters; expected 1 but received 0

Static type checkers always treat TYPE_CHECKING as True, so they still
see the guarded code. As with other module-private constants, no
TYPE_CHECKING global variable is created. Only the bare name is recognised:
from typing import TYPE_CHECKING and typing.TYPE_CHECKING are not
optimised.

A .mpy built with the feature contains no qstrs for the guarded names at all.
Importing a .py file saves less heap than importing a pre-compiled .mpy. The lexer still interns
every name in the file, guarded or not, so those qstrs are still allocated; only bytecode and global-dict space is
saved.

closes: #19734

Testing

• unix port and several other ports were build
• Added test to verify that the bytecode has been reduced.
• Tested on Unix port

I created a few sample modules to test the optimisation and to measure the impact.
(Currently these are not part of the PR, but can be shared)

Four sample modules use the pattern. Each was compiled as written ("after") and with
TYPE_CHECKING renamed to TYPE_CHECKINX ("before"). The rename keeps the name length identical
and turns the optimisation off, so "before" matches the old behaviour exactly.

Results

.mpy sizes are the flash or filesystem space taken by the deployed module. Heap saved is measured
after import on the 64-bit unix port, in 32-byte GC blocks, so those numbers are coarse.

For comparison, s1_min with the three guard lines deleted compiles to 120 bytes, so the guard so the guard
costs only 1 byte of line-number info.
That growth is possibly caused by included debug line numbers that were pushed into the double-digit range (not verified)

Trade-offs and Alternatives

The trade off is adding code to the firmware , with the intent to reduce the overall firmware size
Additions:

This is to be offset by the zero-overhead addition of one or more frozen MicroPython modules that can use type annotations.

An initial rough test estimates the saving per mpy-cross compiled module at 64 - 400 bytes for pre-compiled .mpy modules, depending on the use of type annotations.

This would indicate that the feature saves firmware (and memory) if one or more frozen python modules use TYPE_CHECKING guards.

Should this be mpy-cross only ?
It is possible to only include this optimisation in mpy-cross, to avoid any impact on firmware size.

• In mpconfig.h, default the option to off: #define MICROPY_COMP_TYPE_CHECKING (0).
• In mpy-cross/mpconfigport.h, turn it on with #define MICROPY_COMP_TYPE_CHECKING (1), next to the other MICROPY_COMP_* settings that mpy-cross already sets.
• In CI, turn it on in the unix coverage variant (mpconfigvariant.h), so the tests keep exercising the parser code.

Benefits of mpy-cross only:

• Firmware size impact would then be zero on every port. Device firmware never contains the extra parser code.
• Frozen modules: these are compiled by mpy-cross, so the savings apply to firmware images. This is probably the biggest win (micropython-lib, drivers).
• .mpy files deployed to a device, for example via mip or mpremote : same Bytes saved per .mpy module as in the report above.

Against mpy-cross only:

• .py files compiled on the device keep the guarded code. They still run correctly, because TYPE_CHECKING is a normal global set to False, but they don't get the size or RAM savings.
• The same source behaves slightly differently depending on how it's compiled, rather rare, but would need some documentation.

Generative AI

I did not use generative AI tools when creating this PR.

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.