More review changes. Fix sphinx errors. Break api.rst into separate files.

Author: dhalbert

README.rst

@@ -10,9 +10,7 @@ Introduction
     :target: https://gitter.im/adafruit/circuitpython?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge
     :alt: Gitter
 
-This driver simulates USB HID devices, such as keyboard, mouse, and joystick.
-
-Currently keyboard and mouse are implemented.
+This driver simulates USB HID devices. Currently keyboard and mouse are implemented.
 
 Dependencies
 =============
@@ -33,8 +31,8 @@ The ``Keycode`` class defines USB HID keycodes to send using ``Keyboard``.
 
 .. code-block:: python
 
-    from adafruit_hid import Keyboard
-    from adafruit_hid import Keycode
+    from adafruit_hid.keyboard import Keyboard
+    from adafruit_hid.keycode import Keycode
 
     # Set up a keyboard device.
     kbd = Keyboard()
@@ -56,25 +54,25 @@ The ``Keycode`` class defines USB HID keycodes to send using ``Keyboard``.
     # Release all keys.
     kbd.release_all()
 
-The ``USKeyboardLayout`` sends ASCII characters using keypresses. It assumes
+The ``KeyboardLayoutUS`` sends ASCII characters using keypresses. It assumes
 the host is set to accept keypresses from a US keyboard.
 
 If the host is expecting a non-US keyboard, the character to key mapping provided by
-``USKeyboardLayout`` will not always be correct.
+``KeyboardLayoutUS`` will not always be correct.
 Different keypresses will be needed in some cases. For instance, to type an ``'A'`` on
 a French keyboard (AZERTY instead of QWERTY), ``Keycode.Q`` should be pressed.
 
-Currently this package provides only ``USKeyboardLayout``. More ``KeyboardLayout``
+Currently this package provides only ``KeyboardLayoutUS``. More ``KeyboardLayout``
 classes could be added to handle non-US keyboards and the different input methods provided
 by various operating systems.
 
 .. code-block:: python
 
-    from adafruit_hid import Keyboard
-    from adafruit_hid import USKeyboardLayout
+    from adafruit_hid.keyboard import Keyboard
+    from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS
 
     kbd = Keyboard()
-    layout = USKeyboardLayout(kbd)
+    layout = KeyboardLayoutUS(kbd)
 
     # Type 'abc' followed by Enter (a newline).
     layout.write('abc\n')
@@ -83,11 +81,11 @@ by various operating systems.
     # The method will return (Keycode.SHIFT, Keycode.FOUR).
     keycodes = layout.keycodes('$')
 
-The ``Mouse` class simulates a three-button mouse with a scroll wheel.
+The ``Mouse`` class simulates a three-button mouse with a scroll wheel.
 
 .. code-block:: python
 
-    from adafruit_hid import Mouse
+    from adafruit_hid.mouse import Mouse
 
     m = Mouse()
 
@@ -117,4 +115,7 @@ API Reference
 .. toctree::
    :maxdepth: 2
 
-   api
+   keyboard
+   keycode
+   keyboard_layout_us
+   mouse

adafruit_hid/__init__.py

@@ -24,16 +24,7 @@
 `adafruit_hid`
 ====================================================
 
-TODO(description)
+This driver simulates USB HID devices. Currently keyboard and mouse are implemented.
 
 * Author(s): Scott Shawcroft, Dan Halbert
 """
-# Import these for convenience so that the user may import the packages classes
-# directly without needing to know the file names.
-# E.g.:
-# from adafruit_hid import Keyboard
-
-from .keyboard import Keyboard
-from .keycode import Keycode
-from .mouse import Mouse
-from .us_keyboard_layout import USKeyboardLayout

adafruit_hid/keyboard.py

@@ -1,6 +1,6 @@
 # The MIT License (MIT)
 #
-# Copyright (c) 2017 Scott Shawcroft for Adafruit Industries
+# Copyright (c) 2017 Dan Halbert
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -22,7 +22,7 @@
 #
 
 """
-:mod:`adafruit_hid.Keyboard`
+:mod:`adafruit_hid.keyboard.Keyboard`
 ====================================================
 
 * Author(s): Scott Shawcroft, Dan Halbert
@@ -31,7 +31,7 @@
 from micropython import const
 import usb_hid
 
-from . import Keycode
+from .keycode import Keycode
 
 class Keyboard:
     """Send HID keyboard reports."""
@@ -66,10 +66,14 @@ def __init__(self):
     def press(self, *keycodes):
         """Send a report indicating that the given keys have been pressed.
 
+        :param keycodes: Press these keycodes all at once.
+        :raises ValueError: if more than six regular keys are pressed.
+
         Keycodes may be modifiers or regular keys.
         No more than six regular keys may be pressed simultaneously.
 
-        Examples:
+        Examples::
+
             from adafruit_hid.keycode import Keycode
 
             # Press ctrl-x.
@@ -88,7 +92,12 @@ def press(self, *keycodes):
     def release(self, *keycodes):
         """Send a USB HID report indicating that the given keys have been released.
 
-        Examples:
+        :param keycodes: Release these keycodes all at once.
+
+        If a keycode to be released was not pressed, it is ignored.
+
+        Example::
+
             # release SHIFT key
             kbd.release(Keycode.SHIFT)
         """

adafruit_hid/us_keyboard_layout.py renamed to adafruit_hid/keyboard_layout_us.py

@@ -1,6 +1,6 @@
 # The MIT License (MIT)
 #
-# Copyright (c) 2017 Scott Shawcroft for Adafruit Industries
+# Copyright (c) 2017 Dan Halbert
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -22,15 +22,15 @@
 #
 
 """
-:mod:`adafruit_hid.USKeyboardLayout`
-====================================================
+:mod:`adafruit_hid.keyboard_layout_us.KeyboardLayoutUS`
+=======================================================
 
 * Author(s): Dan Halbert
 """
 
-from . import Keycode
+from .keycode import Keycode
 
-class USKeyboardLayout:
+class KeyboardLayoutUS:
     """Map ASCII characters to appropriate keypresses on a standard US PC keyboard.
 
     Non-ASCII characters and most control characters will raise an exception.
@@ -182,11 +182,29 @@ class USKeyboardLayout:
     )
 
     def __init__(self, keyboard):
-        """Specify the layout for the given keyboard."""
+        """Specify the layout for the given keyboard.
+
+        :param keyboard: a Keyboard object. Write characters to this keyboard when requested.
+
+        Example::
+
+            kbd = Keyboard()
+            layout = KeyboardLayoutUS(kbd)
+        """
+
         self.keyboard = keyboard
 
     def write(self, string):
-        """Type the string by pressing and releasing keys on my keyboard."""
+        """Type the string by pressing and releasing keys on my keyboard.
+
+        :param string: A string of ASCII characters.
+        :raises ValueError: if any of the characters are not ASCII or have no keycode (such as some control characters).
+
+        Example::
+
+            # Write abc followed by Enter to the keyboard
+            layout.write('abc\\n')
+        """
         for char in string:
             keycode = self._char_to_keycode(char)
             # If this is a shifted char, clear the SHIFT flag and press the SHIFT key.
@@ -197,7 +215,24 @@ def write(self, string):
             self.keyboard.release_all()
 
     def keycodes(self, char):
-        """Return a tuple of keycodes needed to type the given character."""
+        """Return a tuple of keycodes needed to type the given character.
+
+        :param char: A single ASCII character in a string.
+        :type char: str of length one.
+        :returns: tuple of Keycode keycodes.
+        :raises ValueError: if ``char`` is not ASCII or there is no keycode for it.
+
+        Examples::
+
+            # Returns (Keycode.TAB,)
+            keycodes('\t')
+            # Returns (Keycode.A,)
+            keycode('a')
+            # Returns (Keycode.SHIFT, Keycode.A)
+            keycode('A')
+            # Raises ValueError because it's a accented e and is not ASCII
+            keycode('é')
+        """
         keycode = self._char_to_keycode(char)
         if keycode & self.SHIFT_FLAG:
             return (Keycode.SHIFT, keycode & ~self.SHIFT_FLAG)
@@ -208,7 +243,8 @@ def _char_to_keycode(self, char):
         """Return the HID keycode for the given ASCII character, with the SHIFT_FLAG possibly set.
 
         If the character requires pressing the Shift key, the SHIFT_FLAG bit is set.
-        You must clear this bit before passing the keycode in a USB report."""
+        You must clear this bit before passing the keycode in a USB report.
+        """
         char_val = ord(char)
         if char_val > 128:
             raise ValueError("Not an ASCII character.")

adafruit_hid/keycode.py

@@ -22,7 +22,7 @@
 #
 
 """
-:mod:`adafruit_hid.Keycode`
+:mod:`adafruit_hid.keycode.Keycode`
 ====================================================
 
 * Author(s): Scott Shawcroft, Dan Halbert

adafruit_hid/mouse.py

@@ -22,7 +22,7 @@
 #
 
 """
-:mod:`adafruit_hid.Mouse`
+:mod:`adafruit_hid.mouse.Mouse`
 ====================================================
 
 * Author(s): Dan Halbert
@@ -33,9 +33,11 @@ class Mouse:
     """Send USB HID mouse reports."""
 
     LEFT_BUTTON = 1
+    """Left mouse button."""
     RIGHT_BUTTON = 2
+    """Right mouse button."""
     MIDDLE_BUTTON = 4
-    ALL_BUTTONS = LEFT_BUTTON | RIGHT_BUTTON | MIDDLE_BUTTON
+    """Middle mouse button."""
 
     def __init__(self):
         """Create a Mouse object that will send USB mouse HID reports."""
@@ -56,12 +58,26 @@ def __init__(self):
 
 
     def press(self, buttons):
-        """Press the given mouse buttons."""
+        """Press the given mouse buttons.
+
+        :param buttons: a bitwise-or'd combination of ``LEFT_BUTTON``, ``MIDDLE_BUTTON``, and ``RIGHT_BUTTON``.
+
+        Examples::
+
+            # Press the left button.
+            m.press(Mouse.LEFT_BUTTON)
+
+            # Press the left and right buttons simultaneously.
+            m.press(Mouse.LEFT_BUTTON | Mouse.RIGHT_BUTTON)
+        """
         self.report[0] |= buttons
         self.move(0, 0, 0)
 
     def release(self, buttons):
-        """Release the given mouse buttons."""
+        """Release the given mouse buttons.
+
+        :param buttons: a bitwise-or'd combination of ``LEFT_BUTTON``, ``MIDDLE_BUTTON``, and ``RIGHT_BUTTON``.
+       """
         self.report[0] &= ~buttons
         self.move(0, 0, 0)
 
@@ -71,19 +87,53 @@ def release_all(self):
         self.move(0, 0, 0)
 
     def click(self, buttons):
-        """Press and release the given mouse buttons."""
+        """Press and release the given mouse buttons.
+
+        :param buttons: a bitwise-or'd combination of ``LEFT_BUTTON``, ``MIDDLE_BUTTON``, and ``RIGHT_BUTTON``.
+
+        Examples::
+
+            # Click the left button.
+            m.click(Mouse.LEFT_BUTTON)
+
+            # Double-click the left button.
+            m.click(Mouse.LEFT_BUTTON)
+            m.click(Mouse.LEFT_BUTTON)
+        """
+
         self.press(buttons)
         self.release(buttons)
 
     def move(self, x_distance, y_distance, wheel_turn):
         """Move the mouse and turn the wheel as directed.
 
-        All arguments should be in the range -127 to 127 inclusive.
-        """
-        self.report[1] = x_distance
-        self.report[2] = y_distance
-        self.report[3] = wheel_turn
-        self.hid_mouse.send_report(self.report)
+        :param x_distance: Move the mouse along the x axis. Negative is to the left, positive is to the right.
+        :param y_distance: Move the mouse along the y axis. Negative is toward the user, positive is away from the user.
+        :param wheel turn: Rotate the wheel this amount. Negative is toward the user, positive is away from the user.
+        :raises ValueError: if any argument is not in the range -127 to 127 inclusive.
+
+        Examples::
 
+            # Move 100 to the left.
+            m.move(-100, 0, 0)
 
+            # Move diagonally to the upper right.
+            m.move(50, 20, 0)
 
+            # Roll the mouse wheel away from the user.
+            m.move(0, 0, 5)
+        """
+        if (self._distance_ok(x_distance)
+                and self._distance_ok(y_distance)
+                and self._distance_ok(wheel_turn)):
+            self.report[1] = x_distance
+            self.report[2] = y_distance
+            self.report[3] = wheel_turn
+            self.hid_mouse.send_report(self.report)
+        else:
+            raise ValueError('All arguments must be >= -127 and <= 127')
+
+    @staticmethod
+    def _distance_ok(dist):
+        """Return True if dist is in the range [-127,127]"""
+        return -127 <= dist <= 127