From 307ecc5707e78c62b0b9fb1c0ba8dcb9c4cc5559 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 17 Jan 2024 11:55:20 +1100 Subject: [PATCH] docs: Add note about position-only arguments in CPython vs MicroPython. Required modifying the gen-cpydiff.py code to allow a "preamble" section to be inserted at the top of any of the generated files. This work was funded through GitHub Sponsors. Signed-off-by: Angus Gratton --- docs/differences/modules_preamble.txt | 33 +++++++++++++++++++++++++++ tools/gen-cpydiff.py | 11 ++++++++- 2 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 docs/differences/modules_preamble.txt diff --git a/docs/differences/modules_preamble.txt b/docs/differences/modules_preamble.txt new file mode 100644 index 0000000000..1958f0084d --- /dev/null +++ b/docs/differences/modules_preamble.txt @@ -0,0 +1,33 @@ +.. Preamble section inserted into generated output + +Positional-only Parameters +-------------------------- + +To save code size, many functions that accept keyword arguments in CPython only accept positional arguments in MicroPython. + +MicroPython marks positional-only parameters in the same way as CPython, by inserting a ``/`` to mark the end of the positional parameters. Any function whose signature ends in ``/`` takes *only* positional arguments. For more details, see `PEP 570 `_. + +Example +~~~~~~~ + +For example, in CPython 3.4 this is the signature of the constructor ``socket.socket``:: + + socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None) + +However, the signature documented in :func:`MicroPython` is:: + + socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP, /) + +The ``/`` at the end of the parameters indicates that they are all positional-only in MicroPython. The following code works in CPython but not in most MicroPython ports:: + + import socket + s = socket.socket(type=socket.SOCK_DGRAM) + +MicroPython will raise an exception:: + + TypeError: function doesn't take keyword arguments + +The following code will work in both CPython and MicroPython:: + + import socket + s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) diff --git a/tools/gen-cpydiff.py b/tools/gen-cpydiff.py index 29545bad0b..578b6c136f 100644 --- a/tools/gen-cpydiff.py +++ b/tools/gen-cpydiff.py @@ -47,7 +47,8 @@ else: TESTPATH = "../tests/cpydiff" DOCPATH = "../docs/genrst" -INDEXTEMPLATE = "../docs/differences/index_template.txt" +SRCDIR = "../docs/differences" +INDEXTEMPLATE = os.path.join(SRCDIR, "index_template.txt") INDEX = "index.rst" HEADER = ".. This document was generated by tools/gen-cpydiff.py\n\n" @@ -219,6 +220,14 @@ def gen_rst(results): rst.write(section[i] + "\n") rst.write(RSTCHARS[0] * len(section[i])) rst.write(time.strftime("\nGenerated %a %d %b %Y %X UTC\n\n", time.gmtime())) + # If a file docs/differences/_preamble.txt exists + # then its output is inserted after the top-level heading, + # but before any of the generated sections. + preamble_path = os.path.join(SRCDIR, filename + "_preamble.txt") + if os.path.exists(preamble_path): + with open(preamble_path, "r") as f: + rst.write(f.read()) + rst.write("\n") toctree.append(filename) else: rst.write(section[i] + "\n")