Don't allow `micropython.const`
This came up in https://github.com/micropython/micropython-lib/pull/693
It does seem reasonable to expect that A = micropython.const(1) should do the right thing, but it only works if you write A = const(1). I would argue that the former should raise an error or otherwise indicate that it's not doing anything useful.
We need to support from micropython import const because this facilitates:
- Running MicroPython code on CPython (where you have a
micropython.pythat provides a dummyconstfunction). - On builds with
MICROPY_COMP_CONSTdisabled (e.g. when settrace is enabled) there will be no "magic" const, so it needs to be imported.
I think 791b65f4b261a23e427664f0b86ce32b60e33cb5 confirms the above.
Some ideas:
- We could change
parse.cto turnconst(...)into a no-op, rather than not handling it at all whenMICROPY_COMP_CONSTis disabled. (I never realised until today that we had this implicit requirement to usefrom micropython import constto be able to useconst()in all builds, I have written a lot of .py files that don't do this!). Thenmicropython.constshould no longer be the identity function (it should raise an error).
or
- Only if
MICROPY_COMP_CONSTis enabled, thenmicropython.constshould no longer be the identity function (it should raise an error to indicate incorrect usage).
or
- Make the parser also handle
micropython.const.
My preference would be #1. Instead of making micropython.const raise an error, it could also just be None (enough to make the import work), but then it might be a bit confusing to figure out why it's failing.
docs: Improve micropython.const() documentation and consistency
Summary
Expanded micropython.const() documentation to address gaps identified through
investigation of GitHub issues and user confusion.
The current documentation lacks details about what const() actually does, has no
warnings about scope or import syntax requirements, and doesn't explain the
confusing behavior when used incorrectly. This has led to multiple GitHub
issues from confused users.
Changes include scope requirements, import syntax warnings, storage/visibility
explanation, and limitations section. Also fixed inconsistency in
speed_python.rst and added cross-references from other docs back to the main
micropython.const() documentation.
All issues reviewed against updated documentation to ensure complete coverage.
GitHub issues referenced:
- https://github.com/micropython/micropython/issues/573
- https://github.com/micropython/micropython/issues/11929
- https://github.com/micropython/micropython/issues/15246
- https://github.com/micropython/micropython/issues/15608
- https://github.com/micropython/micropython/issues/17453
Testing
Built docs with Sphinx, no warnings or errors. Verified HTML rendering and
cross-reference links.
Trade-offs and Alternatives
The expanded documentation increases the micropython.const() function
documentation from ~18 to ~89 lines, making it much longer than other function
entries in the same file. An alternative would be to create a separate
documentation page (e.g. docs/reference/const.rst) with the detailed
explanation and keep only a brief summary with cross-reference in the library
reference. Feedback welcome on whether this restructuring would be preferred.