Use enumerations for motor constants

This avoids using int everywhere. Using enumerations allows type
checking.

Also add Brick.get_motor() to create a Motor instance.

Author: schodet

docs/api/brick.rst

@@ -38,6 +38,7 @@ Brick
 
    This part is still a work in progress.
 
+   .. automethod:: Brick.get_motor
    .. automethod:: Brick.get_sensor
 
    Programs

docs/migration.rst

@@ -45,6 +45,33 @@ use this code before calling any NXT-Python function::
 The :mod:`!nxt` module no longer exports name from sub-modules. In general,
 NXT-Python now avoids to have two names for the same object.
 
+Output port constants are replaced by enumerations, using the :mod:`enum`
+module:
+
+.. py:currentmodule:: nxt.motor
+
+===============================  ============================
+NXT-Python 2                     NXT-Python 3
+===============================  ============================
+:data:`!PORT_A`                  :attr:`Port.A`
+:data:`!PORT_B`                  :attr:`Port.B`
+:data:`!PORT_C`                  :attr:`Port.C`
+:data:`!MODE_IDLE`               :attr:`Mode.IDLE`
+:data:`!MODE_MOTOR_ON`           :attr:`Mode.ON`
+:data:`!MODE_BRAKE`              :attr:`Mode.BRAKE`
+:data:`!MODE_REGULATED`          :attr:`Mode.REGULATED`
+:data:`!REGULATION_IDLE`         :attr:`RegulationMode.IDLE`
+:data:`!REGULATION_MOTOR_SPEED`  :attr:`RegulationMode.SPEED`
+:data:`!REGULATION_MOTOR_SYNC`   :attr:`RegulationMode.SYNC`
+:data:`!RUN_STATE_IDLE`          :attr:`RunState.IDLE`
+:data:`!RUN_STATE_RAMP_UP`       :attr:`RunState.RAMP_UP`
+:data:`!RUN_STATE_RUNNING`       :attr:`RunState.RUNNING`
+:data:`!RUN_STATE_RAMP_DOWN`     :attr:`RunState.RAMP_DOWN`
+===============================  ============================
+
+You can now create :class:`nxt.motor.Motor` objects using
+:meth:`nxt.brick.Brick.get_motor`, however direct creation still works.
+
 
 Text String or Binary String
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

nxt/brick.py

@@ -19,6 +19,7 @@
 import time
 
 import nxt.error
+import nxt.motor
 import nxt.sensor
 from nxt.telegram import Opcode, Telegram
 
@@ -272,6 +273,15 @@ def find_modules(self, pattern="*.*"):
 
     get_sensor = nxt.sensor.get_sensor
 
+    def get_motor(self, port):
+        """Return a motor object connected to one of the brick output port.
+
+        :param nxt.motor.Port port: Output port identifier.
+        :return: The motor object.
+        :rtype: nxt.motor.Motor
+        """
+        return nxt.motor.Motor(self, port)
+
     def _cmd(self, tgram):
         """Send a message to the NXT brick and read reply.
 
@@ -332,27 +342,30 @@ def play_tone(self, frequency_hz, duration_ms):
         self._cmd(tgram)
 
     def set_output_state(
-        self, port, power, mode, regulation, turn_ratio, run_state, tacho_limit
+        self, port, power, mode, regulation_mode, turn_ratio, run_state, tacho_limit
     ):
         """Set output port state on the brick.
 
-        :param int port: Output port constant.
+        :param nxt.motor.Port port: Output port identifier.
         :param int power: Motor speed or power level (-100 to 100).
-        :param int mode: Motor power mode.
-        :param int regulation: Motor regulation mode.
+        :param nxt.motor.Mode mode: Motor power mode.
+        :param nxt.motor.RegulationMode regulation_mode: Motor regulation mode.
         :param int turn_ratio: Turn ratio (-100 to 100). Negative value shift power to
            the left motor.
-        :param int run_state: Motor run state.
+        :param nxt.motor.RunState run_state: Motor run state.
         :param int tacho_limit: Number of degrees the motor should rotate relative to
            the current position.
+
+        .. warning:: This is a low level function, prefer to use
+           :meth:`nxt.motor.Motor`, you can get one from :meth:`get_motor`.
         """
         tgram = Telegram(Opcode.DIRECT_SET_OUT_STATE, reply_req=False)
-        tgram.add_u8(port)
+        tgram.add_u8(port.value)
         tgram.add_s8(power)
-        tgram.add_u8(mode)
-        tgram.add_u8(regulation)
+        tgram.add_u8(mode.value)
+        tgram.add_u8(regulation_mode.value)
         tgram.add_s8(turn_ratio)
-        tgram.add_u8(run_state)
+        tgram.add_u8(run_state.value)
         tgram.add_u32(tacho_limit)
         self._cmd(tgram)
 
@@ -372,18 +385,19 @@ def set_input_mode(self, port, sensor_type, sensor_mode):
     def get_output_state(self, port):
         """Get output port state from the brick.
 
-        :param int port: Output port constant.
-        :return: A tuple with `port`, `power`, `mode`, `regulation`, `turn_ratio`,
+        :param nxt.motor.Port port: Output port identifier.
+        :return: A tuple with `port`, `power`, `mode`, `regulation_mode`, `turn_ratio`,
            `run_state`, `tacho_limit`, `tacho_count`, `block_tacho_count`, and
            `rotation_count`.
-        :rtype: (int, int, int, int, int, int, int, int, int, int)
+        :rtype: (nxt.motor.Port, int, nxt.motor.Mode, nxt.motor.RegulationMode, int,
+           nxt.motor.RunState, int, int, int, int)
 
         Return value details:
 
-        - **port** Output port constant.
+        - **port** Output port identifier.
         - **power** Motor speed or power level (-100 to 100).
         - **mode** Motor power mode.
-        - **regulation** Motor regulation mode.
+        - **regulation_mode** Motor regulation mode.
         - **turn_ratio** Turn ratio (-100 to 100). Negative value shift power to the
           left motor.
         - **run_state** Motor run state.
@@ -392,16 +406,19 @@ def get_output_state(self, port):
           "block" start.
         - **rotation_count** Number of degrees the motor rotated relative to the program
           start.
+
+        .. warning:: This is a low level function, prefer to use
+           :meth:`nxt.motor.Motor`, you can get one from :meth:`get_motor`.
         """
         tgram = Telegram(Opcode.DIRECT_GET_OUT_STATE)
-        tgram.add_u8(port)
+        tgram.add_u8(port.value)
         tgram = self._cmd(tgram)
-        port = tgram.parse_u8()
+        port = nxt.motor.Port(tgram.parse_u8())
         power = tgram.parse_s8()
-        mode = tgram.parse_u8()
-        regulation = tgram.parse_u8()
+        mode = nxt.motor.Mode(tgram.parse_u8())
+        regulation_mode = nxt.motor.RegulationMode(tgram.parse_u8())
         turn_ratio = tgram.parse_s8()
-        run_state = tgram.parse_u8()
+        run_state = nxt.motor.RunState(tgram.parse_u8())
         tacho_limit = tgram.parse_u32()
         tacho_count = tgram.parse_s32()
         block_tacho_count = tgram.parse_s32()
@@ -410,7 +427,7 @@ def get_output_state(self, port):
             port,
             power,
             mode,
-            regulation,
+            regulation_mode,
             turn_ratio,
             run_state,
             tacho_limit,
@@ -494,12 +511,15 @@ def message_write(self, inbox, message):
     def reset_motor_position(self, port, relative):
         """Reset block or program motor position for a brick output port.
 
-        :param int port: Output port constant.
+        :param nxt.motor.Port port: Output port identifier.
         :param bool relative: If ``True``, reset block position, if ``False``, reset
            program position.
+
+        .. warning:: This is a low level function, prefer to use
+           :meth:`nxt.motor.Motor`, you can get one from :meth:`get_motor`.
         """
         tgram = Telegram(Opcode.DIRECT_RESET_POSITION)
-        tgram.add_u8(port)
+        tgram.add_u8(port.value)
         tgram.add_bool(relative)
         self._cmd(tgram)
 

nxt/motcont.py

@@ -89,13 +89,13 @@ def _decode_ports(self, ports, max_ports):
         except TypeError:
             ports = frozenset((ports,))
         mapping = {
-            frozenset((nxt.motor.PORT_A,)): "0",
-            frozenset((nxt.motor.PORT_B,)): "1",
-            frozenset((nxt.motor.PORT_C,)): "2",
-            frozenset((nxt.motor.PORT_A, nxt.motor.PORT_B)): "3",
-            frozenset((nxt.motor.PORT_A, nxt.motor.PORT_C)): "4",
-            frozenset((nxt.motor.PORT_B, nxt.motor.PORT_C)): "5",
-            frozenset((nxt.motor.PORT_A, nxt.motor.PORT_B, nxt.motor.PORT_C)): "6",
+            frozenset((nxt.motor.Port.A,)): "0",
+            frozenset((nxt.motor.Port.B,)): "1",
+            frozenset((nxt.motor.Port.C,)): "2",
+            frozenset((nxt.motor.Port.A, nxt.motor.Port.B)): "3",
+            frozenset((nxt.motor.Port.A, nxt.motor.Port.C)): "4",
+            frozenset((nxt.motor.Port.B, nxt.motor.Port.C)): "5",
+            frozenset((nxt.motor.Port.A, nxt.motor.Port.B, nxt.motor.Port.C)): "6",
         }
         if ports not in mapping or len(ports) > max_ports:
             raise ValueError("invalid combination of ports")
@@ -106,9 +106,9 @@ def cmd(
     ):
         """Send a CONTROLLED_MOTORCMD to MotorControl.
 
-        :param ports: Port or ports to control, use one of the port constant of
-            :mod:`nxt.motor`, or a tuple with one or two of them.
-        :type ports: int or Iterable[int]
+        :param ports: Port or ports to control, use one of the port identifiers, or
+           an iterable returning one or two of them.
+        :type ports: nxt.motor.Port or Iterable[nxt.motor.Port]
         :param int power: Speed or power, -100 to 100.
         :param int tacholimit: Position to drive to, 1 to 999999, or 0 for unlimited.
         :param bool speedreg: ``True`` to enable regulation.
@@ -126,9 +126,9 @@ def cmd(
     def reset_tacho(self, ports):
         """Reset NXT tacho count.
 
-        :param ports: Port or ports to control, use one of the port constant of
-            :mod:`nxt.motor`, or a tuple with one to three of them.
-        :type ports: int or Iterable[int]
+        :param ports: Port or ports to control, use one of the port identifiers, or
+           an iterable returning one to three of them.
+        :type ports: nxt.motor.Port or Iterable[nxt.motor.Port]
         """
         self._interval_is_ready()
         ports, strports = self._decode_ports(ports, 3)
@@ -139,9 +139,9 @@ def reset_tacho(self, ports):
     def is_ready(self, port):
         """Determine the state of a single motor.
 
-        :param port: Port to control, use one of the port constant of :mod:`nxt.motor`.
-           or a tuple with one of them.
-        :type port: int or Iterable[int]
+        :param port: Port to control, use one of the port identifiers, or an iterable
+           returning one of them.
+        :type port: nxt.motor.Port or Iterable[nxt.motor.Port]
         :return: ``True`` if the motor is ready to accept new commands.
         :rtype: bool
         """
@@ -160,9 +160,9 @@ def is_ready(self, port):
     def set_output_state(self, ports, power, tacholimit, speedreg=True):
         """Send a CLASSIC_MOTORCMD to MotorControl.
 
-        :param ports: Port or ports to control, use one of the port constant of
-            :mod:`nxt.motor`, or a tuple with one or two of them.
-        :type ports: int or Iterable[int]
+        :param ports: Port or ports to control, use one of the port identifiers, or
+           an iterable returning one or two of them.
+        :type ports: nxt.motor.Port or Iterable[nxt.motor.Port]
         :param int power: Speed or power, -100 to 100.
         :param int tacholimit: Position to drive to, 1 to 999999, or 0 for unlimited.
         :param bool speedreg: ``True`` to enable regulation.