From 7ef2f65114f092be6303c145a2560fdf522dcde0 Mon Sep 17 00:00:00 2001 From: Jason Neal Date: Sat, 11 Jan 2020 19:44:17 +1300 Subject: [PATCH] docs/library: Add / to indicate positional-only args in library docs. Removes the confusion of positional-only arguments which have defaults that look like keyword arguments. --- docs/library/btree.rst | 2 +- docs/library/esp.rst | 2 +- docs/library/framebuf.rst | 2 +- docs/library/machine.rst | 2 +- docs/library/sys.rst | 4 ++-- docs/library/ubluetooth.rst | 6 +++--- docs/library/uctypes.rst | 4 ++-- docs/library/uos.rst | 2 +- docs/library/ure.rst | 6 +++--- docs/library/uselect.rst | 4 ++-- docs/library/usocket.rst | 6 +++--- docs/library/ustruct.rst | 2 +- docs/library/uzlib.rst | 4 ++-- 13 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/library/btree.rst b/docs/library/btree.rst index 3578acd8fd..a1f7a5420f 100644 --- a/docs/library/btree.rst +++ b/docs/library/btree.rst @@ -116,7 +116,7 @@ Methods Flush any data in cache to the underlying stream. .. method:: btree.__getitem__(key) - btree.get(key, default=None) + btree.get(key, default=None, /) btree.__setitem__(key, val) btree.__detitem__(key) btree.__contains__(key) diff --git a/docs/library/esp.rst b/docs/library/esp.rst index 867182be99..cb2bc7af8d 100644 --- a/docs/library/esp.rst +++ b/docs/library/esp.rst @@ -31,7 +31,7 @@ Functions The system enters the set sleep mode automatically when possible. -.. function:: deepsleep(time=0) +.. function:: deepsleep(time=0, /) **Note**: ESP8266 only - use `machine.deepsleep()` on ESP32 diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst index 1ff56e4dae..43ff0b6e1b 100644 --- a/docs/library/framebuf.rst +++ b/docs/library/framebuf.rst @@ -28,7 +28,7 @@ For example:: Constructors ------------ -.. class:: FrameBuffer(buffer, width, height, format, stride=width) +.. class:: FrameBuffer(buffer, width, height, format, stride=width, /) Construct a FrameBuffer object. The parameters are: diff --git a/docs/library/machine.rst b/docs/library/machine.rst index 747270d936..b580353d6b 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -111,7 +111,7 @@ Miscellaneous functions varies by hardware (so use substring of a full value if you expect a short ID). In some MicroPython ports, ID corresponds to the network MAC address. -.. function:: time_pulse_us(pin, pulse_level, timeout_us=1000000) +.. function:: time_pulse_us(pin, pulse_level, timeout_us=1000000, /) Time a pulse on the given *pin*, and return the duration of the pulse in microseconds. The *pulse_level* argument should be 0 to time a low pulse diff --git a/docs/library/sys.rst b/docs/library/sys.rst index d3cc308d89..24f9e353bb 100644 --- a/docs/library/sys.rst +++ b/docs/library/sys.rst @@ -9,7 +9,7 @@ Functions --------- -.. function:: exit(retval=0) +.. function:: exit(retval=0, /) Terminate current program with a given exit code. Underlyingly, this function raise as `SystemExit` exception. If an argument is given, its @@ -28,7 +28,7 @@ Functions This function is a MicroPython extension intended to provide similar functionality to the :mod:`atexit` module in CPython. -.. function:: print_exception(exc, file=sys.stdout) +.. function:: print_exception(exc, file=sys.stdout, /) Print exception with a traceback to a file-like object *file* (or `sys.stdout` by default). diff --git a/docs/library/ubluetooth.rst b/docs/library/ubluetooth.rst index 1a62d1e4ba..e3f4e13828 100644 --- a/docs/library/ubluetooth.rst +++ b/docs/library/ubluetooth.rst @@ -268,7 +268,7 @@ writes from a central to a given characteristic, use of the notification, avoiding the need for a separate read request. Note that this will not update the local value stored. -.. method:: BLE.gatts_set_buffer(value_handle, len, append=False) +.. method:: BLE.gatts_set_buffer(value_handle, len, append=False, /) Sets the internal buffer size for a value in bytes. This will limit the largest possible write that can be received. The default is 20. @@ -283,7 +283,7 @@ writes from a central to a given characteristic, use Central Role (GATT Client) -------------------------- -.. method:: BLE.gap_connect(addr_type, addr, scan_duration_ms=2000) +.. method:: BLE.gap_connect(addr_type, addr, scan_duration_ms=2000, /) Connect to a peripheral. @@ -326,7 +326,7 @@ Central Role (GATT Client) On success, the ``_IRQ_GATTC_READ_RESULT`` event will be raised. -.. method:: BLE.gattc_write(conn_handle, value_handle, data, mode=0) +.. method:: BLE.gattc_write(conn_handle, value_handle, data, mode=0, /) Issue a remote write to a connected peripheral for the specified characteristic or descriptor handle. diff --git a/docs/library/uctypes.rst b/docs/library/uctypes.rst index dce8caecb6..0fdc40e484 100644 --- a/docs/library/uctypes.rst +++ b/docs/library/uctypes.rst @@ -180,7 +180,7 @@ Following are encoding examples for various field types: Module contents --------------- -.. class:: struct(addr, descriptor, layout_type=NATIVE) +.. class:: struct(addr, descriptor, layout_type=NATIVE, /) Instantiate a "foreign data structure" object based on structure address in memory, descriptor (encoded as a dictionary), and layout type (see below). @@ -200,7 +200,7 @@ Module contents Layout type for a native structure - with data endianness and alignment conforming to the ABI of the system on which MicroPython runs. -.. function:: sizeof(struct, layout_type=NATIVE) +.. function:: sizeof(struct, layout_type=NATIVE, /) Return size of data structure in bytes. The *struct* argument can be either a structure class or a specific instantiated structure object diff --git a/docs/library/uos.rst b/docs/library/uos.rst index bb7e491cce..cbc1f3e915 100644 --- a/docs/library/uos.rst +++ b/docs/library/uos.rst @@ -112,7 +112,7 @@ Filesystem access Terminal redirection and duplication ------------------------------------ -.. function:: dupterm(stream_object, index=0) +.. function:: dupterm(stream_object, index=0, /) Duplicate or switch the MicroPython terminal (the REPL) on the given `stream`-like object. The *stream_object* argument must be a native stream object, or derive diff --git a/docs/library/ure.rst b/docs/library/ure.rst index ac5f02f9e8..ca5f35b703 100644 --- a/docs/library/ure.rst +++ b/docs/library/ure.rst @@ -124,7 +124,7 @@ Functions string for first position which matches regex (which still may be 0 if regex is anchored). -.. function:: sub(regex_str, replace, string, count=0, flags=0) +.. function:: sub(regex_str, replace, string, count=0, flags=0, /) Compile *regex_str* and search for it in *string*, replacing all matches with *replace*, and returning the new string. @@ -156,14 +156,14 @@ Compiled regular expression. Instances of this class are created using .. method:: regex.match(string) regex.search(string) - regex.sub(replace, string, count=0, flags=0) + regex.sub(replace, string, count=0, flags=0, /) Similar to the module-level functions :meth:`match`, :meth:`search` and :meth:`sub`. Using methods is (much) more efficient if the same regex is applied to multiple strings. -.. method:: regex.split(string, max_split=-1) +.. method:: regex.split(string, max_split=-1, /) Split a *string* using regex. If *max_split* is given, it specifies maximum number of splits to perform. Returns list of strings (there diff --git a/docs/library/uselect.rst b/docs/library/uselect.rst index e1becc60ea..0c3bdfdfd9 100644 --- a/docs/library/uselect.rst +++ b/docs/library/uselect.rst @@ -58,7 +58,7 @@ Methods Modify the *eventmask* for *obj*. If *obj* is not registered, `OSError` is raised with error of ENOENT. -.. method:: poll.poll(timeout=-1) +.. method:: poll.poll(timeout=-1, /) Wait for at least one of the registered objects to become ready or have an exceptional condition, with optional timeout in milliseconds (if *timeout* @@ -81,7 +81,7 @@ Methods Tuples returned may contain more than 2 elements as described above. -.. method:: poll.ipoll(timeout=-1, flags=0) +.. method:: poll.ipoll(timeout=-1, flags=0, /) Like :meth:`poll.poll`, but instead returns an iterator which yields a `callee-owned tuple`. This function provides an efficient, allocation-free diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index 461e37b353..e3b9d279a0 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -66,7 +66,7 @@ Tuple address format for ``socket`` module: Functions --------- -.. function:: socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP) +.. function:: socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP, /) Create a new socket using the given address family, socket type and protocol number. Note that specifying *proto* in most cases is not @@ -79,7 +79,7 @@ Functions # Create DGRAM UDP socket socket(AF_INET, SOCK_DGRAM) -.. function:: getaddrinfo(host, port, af=0, type=0, proto=0, flags=0) +.. function:: getaddrinfo(host, port, af=0, type=0, proto=0, flags=0, /) Translate the host/port argument into a sequence of 5-tuples that contain all the necessary arguments for creating a socket connected to that service. Arguments @@ -293,7 +293,7 @@ Methods * ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)`` * ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0)`` -.. method:: socket.makefile(mode='rb', buffering=0) +.. method:: socket.makefile(mode='rb', buffering=0, /) Return a file object associated with the socket. The exact returned type depends on the arguments given to makefile(). The support is limited to binary modes only ('rb', 'wb', and 'rwb'). diff --git a/docs/library/ustruct.rst b/docs/library/ustruct.rst index 81915d0a8d..357d622b2b 100644 --- a/docs/library/ustruct.rst +++ b/docs/library/ustruct.rst @@ -35,7 +35,7 @@ Functions Unpack from the *data* according to the format string *fmt*. The return value is a tuple of the unpacked values. -.. function:: unpack_from(fmt, data, offset=0) +.. function:: unpack_from(fmt, data, offset=0, /) Unpack from the *data* starting at *offset* according to the format string *fmt*. *offset* may be negative to count from the end of *buffer*. The return diff --git a/docs/library/uzlib.rst b/docs/library/uzlib.rst index 0b399f228a..d40c46145a 100644 --- a/docs/library/uzlib.rst +++ b/docs/library/uzlib.rst @@ -14,7 +14,7 @@ is not yet implemented. Functions --------- -.. function:: decompress(data, wbits=0, bufsize=0) +.. function:: decompress(data, wbits=0, bufsize=0, /) Return decompressed *data* as bytes. *wbits* is DEFLATE dictionary window size used during compression (8-15, the dictionary size is power of 2 of @@ -23,7 +23,7 @@ Functions to be raw DEFLATE stream. *bufsize* parameter is for compatibility with CPython and is ignored. -.. class:: DecompIO(stream, wbits=0) +.. class:: DecompIO(stream, wbits=0, /) Create a `stream` wrapper which allows transparent decompression of compressed data in another *stream*. This allows to process compressed