mirror of
https://github.com/licsber/micropython.git
synced 2024-09-19 08:39:38 +08:00
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 <angus@redyak.com.au>
This commit is contained in:
parent
c8772b7baa
commit
307ecc5707
33
docs/differences/modules_preamble.txt
Normal file
33
docs/differences/modules_preamble.txt
Normal file
@ -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 <https://peps.python.org/pep-0570/>`_.
|
||||
|
||||
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<socket.socket>` 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)
|
@ -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/<filename>_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")
|
||||
|
Loading…
Reference in New Issue
Block a user