docs/builtins: Add basic builtins documentation. - #19595
Conversation
Josverl
changed the title
pavelrevak
left a comment
pavelrevak
left a comment
There was a problem hiding this comment.
Nice work on this — the builtins page has been a bare list for far too long, and the cpydiff cross-referencing is well done: all 35 labels resolve and the paraphrases match the source descriptions.
I look through it and focused on correctness — signatures or claims that don't match the implementation. I verified each against py/modbuiltins.c and by running it on a freshly built ports/unix at master; evidence is inline.
Most cluster into two patterns, so the fix is smaller than the comment count suggests:
- Optional args written as
=None(getattr,next,min/max) — they have no default; omitting them raisesAttributeError/StopIteration/ValueError. /markers on args that do accept keywords (enumerate,open) — plusslice, which can't be called at all.
There's also some unevenness in completeness and style — execfile is still missing (the PR description names it as the motivation) and the "optional feature" availability notes cover only about a third of the builtins that need them — but nothing there is blocking.
Thank you, I created a draft because that work still needed to be done, but I was in the middle of 4 different things with interdependencies. |
|
@pavelrevak, Ill leave it in draft as I want to verify a few more things. |
dff0b27 to
f3c0e2a
Compare
|
Rebased on current master which included merging other updates Regarding the availability / Only available on builds with MPY_GUARD , |
4020edb to
ba4b5d1
Compare
Add basic parameters to methods. For Micropython specific differences. - Add a concise description of the differences For CPython equivalent: - Add one line description & reference to CPython. Signed-off-by: Jos Verlinde <Jos_Verlinde@hotmail.com>
2 participants
Summary
The documentation for builtins was rather terse , and missing even the MicroPython specific
execfile()method, making things hard to discover and learn.This PR aims to add minimal documentation on the built-in methods and classes, and refer to CPython for more details.
Where there are known differences, there are referrals to more detailed documentation.
Testing
Trade-offs and Alternatives
There is some overlap with the documentation based on
cpydifftests, but I think that is unavoidable and acceptable.Generative AI
I used generative AI tools when creating this PR, but a human has checked the
documentation and is responsible for the docs and the description above.