Avoid wildcard imports and mention enums

.spelling

@@ -9,6 +9,7 @@ DTSE9H
 Ebuyer
 esque
 finessing
+GPIO
 iMAX
 IntelliJ
 Nikitin

programming/arduino/custom_firmware.md

@@ -23,7 +23,7 @@ The Arduino serial number is a string of numbers and letters, and is output in t
 You'll need the serial number later, so it's best to save it into a variable:
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 
 # Replace this with the actual serial number of your board
 ARDUINO_SN = "752303138333517171B1"
@@ -40,7 +40,7 @@ If you need to communicate with a device, you will need to open its serial port.
 If you want the `robot` object to do this and provide a serial port for your use, you will need to do the following.
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 
 # Replace this with the actual serial number of your board
 ARDUINO_SN = "752303138333517171B1"

programming/arduino/sr_firmware.md

@@ -15,7 +15,7 @@ The kit can control multiple Arduinos at once, however we only provide one in th
 If there is exactly one Arduino connected to your robot, it can be accessed using the `arduino` property of the `Robot` object.
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 robot = Robot()
 
 my_arduino = robot.arduino
@@ -57,10 +57,13 @@ The possible modes for a pin are:
 `INPUT_PULLUP`
 :   set the pin to input mode with a [pull-up resistor](#pull-up-resistors)
 
+These are available from `sr.robot3`, or the `GPIOPinMode` enum.
 
 An example of how to use this is below:
 
 ~~~~~ python
+from sr.robot3 import INPUT, INPUT_PULLUP, OUTPUT
+
 # set Arduino pin 2 to output
 robot.arduino.pins[2].mode = OUTPUT
 
@@ -96,8 +99,11 @@ value = robot.arduino.pins[A0].analog_read()
 value = robot.arduino.pins[A4].analog_read()
 ~~~~~
 
-The analog pin numbers are available as `A0`, `A1`, `A2`, `A3`, `A4`, and `A5` respectively.
+The analog pin numbers are available as `A0`, `A1`, `A2`, `A3`, `A4`, and `A5` respectively, either imported directly or using the `AnalogPins` enum.
 
+~~~~ python
+from sr.robot3 import A0, A1, A2, A3, A4, A5, AnalogPins
+~~~~
 
 ## Output
 
@@ -145,6 +151,6 @@ distance_mm = robot.arduino.ultrasound_measure(4, 5)
 
 <div class="warning">
 The ultrasound sensor can measure distances up to around 4 metres.
-If the ultrasound signal has to travel further, the echo may not be detected. 
+If the ultrasound signal has to travel further, the echo may not be detected.
 This will cause the sensor to timeout and return 0.
 </div>

programming/cheat_sheet.md

@@ -16,7 +16,7 @@ For more information, make sure you check the rest of the documentation.
 In order to use the `sr.robot3` API you first need to import it into your code:
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 ~~~~~
 
 ## Initialising your robot

programming/leds.md

@@ -38,7 +38,7 @@ robot.kch.leds[LED_B].colour = Colour.CYAN
 robot.kch.leds[LED_C].colour = Colour.OFF
 ~~~~~
 
-The available colours are:
+The available colours are defined on the `Colour` enum:
 
 ~~~~~ python
 Colour.OFF
@@ -63,3 +63,9 @@ robot.kch.leds[LED_B].r = False
 # Turn on the green segment of LED B
 robot.kch.leds[LED_B].g = True
 ~~~~~
+
+These values are all available from the `sr.robot3` module:
+
+~~~~ python
+from sr.robot3 import Colour, LED_A, LED_B, LED_C
+~~~~

programming/motors.md

@@ -19,7 +19,7 @@ Accessing the Motor Board
 If there is exactly one Motor Board connected to your robot, it can be accessed using the `motor_board` property of the `Robot` object.
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 robot = Robot()
 
 my_motor_board = robot.motor_board
@@ -39,7 +39,7 @@ sr.robot3.robot - INFO - Found MotorBoard, serial: srXYZ1
 You can then access the boards like this:
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 robot = Robot()
 
 my_motor_board = robot.motor_boards["srABC1"]
@@ -125,6 +125,7 @@ Special Values
 --------------
 
 In addition to the numeric values, there are two special constants that can be used:
+
 - `BRAKE`
 - `COAST`
 
@@ -135,6 +136,8 @@ In addition to the numeric values, there are two special constants that can be u
 </div>
 
 ~~~~~ python
+from sr.robot3 import BRAKE, COAST
+
 # Stop the motor as quick as possible
 robot.motor_boards["srABC1"].motors[0].power = BRAKE
 ~~~~~

programming/power.md

@@ -18,7 +18,7 @@ Accessing the Power Board
 The power board can be accessed using the `power_board` property of the `Robot` object.
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 robot = Robot()
 
 my_power_board = robot.power_board
@@ -28,7 +28,7 @@ my_power_board = robot.power_board
 Power Outputs
 -------------
 
-Each of the power board's controllable outputs has a constant whose name closely matches the name of the output:
+Each of the power board's controllable outputs has a constant whose name closely matches the name of the output, which can be imported from `sr.robot3`:
 
 * H0 : `OUT_H0`
 * H1 : `OUT_H1`
@@ -38,6 +38,8 @@ Each of the power board's controllable outputs has a constant whose name closely
 * L3 : `OUT_L3`
 * 5V : `OUT_FIVE_VOLT`
 
+These are also available on the `PowerOutputPosition` enum.
+
 Both of the 5V outputs are controlled together.
 
 All the ports are turned on when your code starts running, you can then control whether each output is turned on or off like so:
@@ -108,6 +110,8 @@ The frequency on the buzzer is limited from 8Hz to 10,000Hz
 </div>
 
 ~~~~~ python
+from sr.robot3 import Note
+
 # Beep for 0.5s in D.
 robot.power_board.piezo.buzz(Note.D6, 0.5)
 

programming/robot_api/comp_mode.md

@@ -28,14 +28,7 @@ This will instruct your robot that it is in competition mode and will have a num
     Certain robot attributes will change when in comp mode, these can be used to change your robot's behaviour.
     The affected attributes are:
 
-    mode
-    :   Whether the robot is running in competition mode.
-        When in a competition match, this will be `COMP`, and at all other times this will be `DEV`.
+    - `robot.mode`
+    - `robot.zone`
 
-    zone
-    :   The number of the scoring zone that the robot is associated with.
-        Between `0` and `3`.
-
-        The zone you are in defines which arena markers are near your scoring zone.
-        You can use the knowledge of your zone to compensate for this, so your robot behaves correctly in all starting positions.
-        See the [rules]({{ site.baseurl }}/rules) for where the scoring zones and arena markers are positioned.
+    See [other robot attributes]({{ site.baseurl }}/programming/robot_api/#other-robot-attributes) for further details of these attributes.

programming/robot_api/index.md

@@ -23,13 +23,21 @@ See the [Motor Board]({{ site.baseurl }}/programming/motors) page for more detai
 To gain access to all of this functionality, all you need to do at the top of your code is the following:
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 robot = Robot()
 ~~~~~
 
 This imports the Student Robotics module that we've written to interface with our hardware.
 We then use the `Robot` class from within the `sr.robot3` module, to create a `robot` object that sets up and gives you access to your robot's hardware.
 
+Alongside `Robot`, other values are importable from `sr.robot3` which may be useful, such as `OUT_H0` or `A3`. It's best practice to only import the values you need, rather than `import *`. Most of these are available directly, or can be retrieved from the enums they're defined on (`PowerOutputPosition` and `AnalogPins` in these cases). If you need multiple values, you can import them all on one line:
+
+~~~~ python
+from sr.robot3 import Robot, OUT_H0, AnalogPins
+~~~~
+
+If you don't need a value, it's best not to import it, to avoid accidentally overriding it.
+
 <div class="info" markdown="1">
 Most examples in the documentation will assume you have created a `robot` object from the `Robot` class.
 If you see `robot` in a code example, it is assumed you have run the two lines above.
@@ -46,7 +54,6 @@ Then, within your `robot` you can use the following attributes to access to the
 
 The functions of each board are described on their respective pages.
 
-
 ## Other Robot Attributes
 
 As well as the attributes listed above, the `Robot` class also has the following attributes, which you may find useful:
@@ -56,6 +63,8 @@ zone
     Between `0` and `3`.
 
     This attribute is only available after the start button is pressed and will throw an error if accessed before.
+    The zone you are in defines which arena markers are near your scoring zone.
+    You can use the knowledge of your zone to compensate for this, so your robot behaves correctly in all starting positions.
     See the [competition mode](./comp_mode) page for more information about this attribute.
 
 mode
@@ -66,7 +75,7 @@ mode
     See the [competition mode](./comp_mode) page for more information about this attribute.
 
     ~~~~~ python
-    from sr.robot3 import *
+    from sr.robot3 import Robot, COMP, DEV
 
     robot = Robot()
 
@@ -76,14 +85,16 @@ mode
         print("This is development")
     ~~~~~
 
+    `COMP` and `DEV` are aliases for `RobotMode.COMP` and `RobotMode.DEV`, which can also be imported from `sr.robot3`.
+
 usbkey
 :   A [`Path`](https://docs.python.org/3/library/pathlib.html#basic-use) object containing the path to the USB stick.
     You can use this to easily read and write files on the USB stick itself.
 
     An example of how the `usbkey` attribute might be used to read a file called `my-file.txt` which is stored on the USB stick:
 
     ~~~~~ python
-    from sr.robot3 import *
+    from sr.robot3 import Robot
     import os
 
     robot = Robot()
@@ -103,15 +114,15 @@ is_simulated
 Normally the Robot object is initialised with the following:
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 robot = Robot()
 ~~~~~
 
 By default your robot will pause on this line waiting for the start button to be pressed.
 However if you want to initialise some hardware or software before the start button is pressed then Robot initialisation can be broken up as follows.
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 robot = Robot(wait_for_start=False)
 
 # Initialisation phase.
@@ -121,3 +132,30 @@ robot.wait_start()
 ~~~~~
 
 This will not pause on the line which creates the `robot` but will instead pause on the `robot.wait_start()` line, until the start button is pressed.
+
+## Enums
+
+Many values from the robot API are "enums". Enums are sets of values with names.
+
+Enums compare equal to each other:
+
+~~~~~ python
+from sr.robot3 import Colour
+
+pump_output = PowerOutputPosition.H0
+
+pump_output == PowerOutputPosition.H0  # True
+pump_output == PowerOutputPosition.H1  # False
+~~~~~
+
+Enums are special values. They may look like strings or numbers, but they're not. An enum is a name for a special value. For example, the value for `PowerOutputPosition.H0` is `0`, whilst `RobotMode.COMP` is `"COMP"`. The inner value can be retrieved using `.value`.
+
+
+~~~~~ python
+from sr.robot3 import RobotMode
+
+RobotMode.COMP == "COMP"  # False
+RobotMode.COMP.value == "COMP"  # True
+~~~~~
+
+In general, the enum should be used and compared directly, rather than using its inner value.

programming/servos.md

@@ -18,7 +18,7 @@ Accessing the Servo Board
 The servo board can be accessed using the `servo_board` property of the `Robot` object.
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 robot = Robot()
 
 my_servo_board = robot.servo_board

programming/vision/index.md

@@ -28,7 +28,7 @@ see
 Here's an example that will repeatedly print out the distance, in meters, to each marker that the robot can see:
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 robot = Robot()
 
 while True:
@@ -52,7 +52,7 @@ capture
 
 ~~~~~ python
 import cv2
-from sr.robot3 import *
+from sr.robot3 import Robot
 robot = Robot()
 
 frame = robot.camera.capture()
@@ -68,7 +68,7 @@ You can use the output of the `capture` method with the other vision commands to
 This may be useful if you wish to use both your own vision algorithms and our marker detection on the same frames.
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 robot = Robot()
 
 # Capture an OpenCV frame
@@ -101,7 +101,7 @@ Snapshots are saved to your USB drive, and can be viewed on another computer.
 </div>
 
 ```python
-from sr.robot3 import *
+from sr.robot3 import Robot
 
 robot = Robot()
 

tutorials/basic_motor_control.md

@@ -80,7 +80,7 @@ If the motor appears to be going in the wrong direction, just swap the motor's p
 As a first example:
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 
 robot = Robot()
 
@@ -131,7 +131,7 @@ Our aim is to do the forwards and backwards bit (as above), but, instead of sett
 Here's the code:
 
 ~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
 
 robot = Robot()