ubuiltins: Examples for common exceptions.

doc/main/micropython/exceptions.rst

@@ -38,11 +38,8 @@ This section lists all available exceptions in alphabetical order.
     :no-members:
 
 .. autoclass:: ubuiltins.KeyboardInterrupt
-    :noindex:
     :no-members:
 
-    See also `stopping a program`_.
-
 .. autoclass:: ubuiltins.KeyError
     :no-members:
 
@@ -76,11 +73,8 @@ This section lists all available exceptions in alphabetical order.
     :no-members:
 
 .. autoclass:: ubuiltins.SystemExit
-    :noindex:
     :no-members:
 
-    See also `stopping a program`_.
-
 .. autoclass:: ubuiltins.TypeError
     :no-members:
 
@@ -90,17 +84,6 @@ This section lists all available exceptions in alphabetical order.
 .. autoclass:: ubuiltins.ZeroDivisionError
     :no-members:
 
-.. _stopping a program:
-
-Stopping programs
------------------
-
-.. autoclass:: ubuiltins.KeyboardInterrupt
-    :no-members:
-
-.. autoclass:: ubuiltins.SystemExit
-    :no-members:
-
 .. _OSError:
 
 Using ``OSError`` with :mod:`uerrno`
@@ -135,9 +118,21 @@ from the ``uerrno`` module. See also :ref:`this example <device_detection>`.
 Examples
 ---------------------
 
+Debugging in the REPL terminal
+*****************************************
+
+.. literalinclude::
+    ../../../examples/micropython/keyboard_interrupt.py
+
+Running code when the stop button is pressed
+********************************************
+
+.. literalinclude::
+    ../../../examples/micropython/system_exit.py
+
 .. _device_detection:
 
-Detect devices using ``OSError``
+Detecting devices using ``OSError``
 *****************************************
 
 .. literalinclude::

examples/micropython/keyboard_interrupt.py

@@ -0,0 +1,21 @@
+from pybricks.pupdevices import Motor
+from pybricks.parameters import Port
+from pybricks.tools import wait
+
+# Initialize the motor.
+test_motor = Motor(Port.A)
+
+# Start moving at 500 deg/s.
+test_motor.run(500)
+
+# If you click on the terminal window and press CTRL+C,
+# you can continue debugging in this terminal.
+wait(5000)
+
+# You can also do this to exit the script and enter the
+# terminal. Variables in the global scope are still available.
+raise KeyboardInterrupt
+
+# For example, you can copy the following line to the terminal
+# to get the angle, because test_motor is still available.
+test_motor.angle()

examples/micropython/oserror.py

@@ -4,8 +4,16 @@ from pybricks.parameters import Port
 from uerrno import ENODEV
 
 try:
+    # Try to initialize a motor.
     my_motor = Motor(Port.A)
+
+    # If all goes well, you'll see this message.
     print("Detected a motor.")
 except OSError as ex:
+    # If an OSError was raised, we can check what
+    # kind of error this was, like ENODEV.
     if ex.errno == ENODEV:
+        # ENODEV is short for "Error, no device."
         print("There is no motor this port.")
+    else:
+        print("Another error occurred.")

examples/micropython/system_exit.py

@@ -0,0 +1,16 @@
+from pybricks.tools import wait
+
+print("Started!")
+
+try:
+
+    # Run your script here as you normally would. In this
+    # example we just wait forever and do nothing.
+    while True:
+        wait(1000)
+
+except SystemExit:
+    # This code will run when you press the stop button.
+    # This can be useful to "clean up", such as to move
+    # the motors back to their starting positions.
+    print("You pressed the stop button!")