docs,extmod: Deprecate machine.soft_reset().

projectgus · projectgus · commit 5f0a2a7a856a · 2024-10-22T11:56:37.000+11:00
Encourage calling sys.exit() instead, mark machine.soft_reset() for removal
in MicroPython 2.0.

Adds some additional explanation of SystemExit in the MicroPython context.

Signed-off-by: Angus Gratton &lt;angus@redyak.com.au&gt;
diff --git a/docs/library/builtins.rst b/docs/library/builtins.rst
@@ -194,6 +194,12 @@ Exceptions
 
     |see_cpython| `python:SystemExit`.
 
+    On non-embedded ports (i.e. Windows and Unix), an unhandled ``SystemExit``
+    exits the MicroPython process in a similar way to CPython.
+
+    On embedded ports, an unhandled ``SystemExit`` causes a :ref:`soft_reset` of
+    MicroPython.
+
 .. exception:: TypeError
 
     |see_cpython| `python:TypeError`.
diff --git a/docs/library/machine.rst b/docs/library/machine.rst
@@ -70,6 +70,9 @@ Reset related functions
    Performs a :ref:`soft reset <soft_reset>` of the interpreter, deleting all
    Python objects and resetting the Python heap.
 
+   .. note:: This function is deprecated. Call the Python standard
+             :func:`sys.exit()` function instead.
+
 .. function:: reset_cause()
 
    Get the reset cause. See :ref:`constants <machine_constants>` for the possible return values.
diff --git a/docs/library/sys.rst b/docs/library/sys.rst
@@ -12,9 +12,12 @@ Functions
 .. 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
+   function raises a `SystemExit` exception. If an argument is given, its
    value given as an argument to `SystemExit`.
 
+   On embedded ports (i.e. all ports but Windows and Unix), an unhandled
+   `SystemExit` triggers a :ref:`soft_reset` of MicroPython.
+
 .. function:: atexit(func)
 
    Register *func* to be called upon termination.  *func* must be a callable
diff --git a/docs/reference/repl.rst b/docs/reference/repl.rst
@@ -154,7 +154,7 @@ method by which you're connected to the MicroPython board (USB-serial, or Wifi).
 You can perform a soft reset from the REPL by pressing Ctrl-D, or from your python
 code by executing: ::
 
-    machine.soft_reset()
+    sys.exit()
 
 For example, if you reset your MicroPython board, and you execute a dir()
 command, you'd see something like this:
diff --git a/docs/reference/reset_boot.rst b/docs/reference/reset_boot.rst
@@ -38,7 +38,7 @@ Soft Reset
 
 When MicroPython is already running, it's possible to trigger a soft reset by
 :ref:`typing Ctrl-D in the REPL <repl_soft_reset>` or executing
-:func:`machine.soft_reset()`.
+:func:`sys.exit()`.
 
 A soft reset clears the Python interpreter, frees all Python memory, and starts
 the MicroPython environment again.
diff --git a/extmod/modmachine.c b/extmod/modmachine.c
@@ -156,7 +156,9 @@ static const mp_rom_map_elem_t machine_module_globals_table[] = {
     #endif
 
     // Reset related functions.
+    #if !MICROPY_PREVIEW_VERSION_2
     { MP_ROM_QSTR(MP_QSTR_soft_reset), MP_ROM_PTR(&mp_sys_exit_obj) },
+    #endif
     #if MICROPY_PY_MACHINE_BOOTLOADER
     { MP_ROM_QSTR(MP_QSTR_bootloader), MP_ROM_PTR(&machine_bootloader_obj) },
     #endif
