re-organized structure for autocorrect (#193)

re-structuring for auto-completion

src/microbit/__init__.py

@@ -1 +1,24 @@
-from .shim import *
+from .__model.image import Image
+from .__model.microbit_model import __mb
+
+button_a = __mb.button_a
+button_b = __mb.button_b
+display = __mb.display
+
+
+def sleep(n):
+    """
+    Wait for ``n`` milliseconds. One second is 1000 milliseconds, so::
+    microbit.sleep(1000)
+    will pause the execution for one second.  ``n`` can be an integer or
+    a floating point number.
+    """
+    __mb.sleep(n)
+
+
+def running_time():
+    """
+    Return the number of milliseconds since the board was switched on or
+    restarted.
+    """
+    __mb.running_time()

src/microbit/__model/button.py

@@ -0,0 +1,42 @@
+class Button:
+    # The implementation is based off of https://microbit-micropython.readthedocs.io/en/v1.0.1/button.html.
+    def __init__(self):
+        self.__pressed = False
+        self.__presses = 0
+        self.__prev_pressed = False
+
+    def is_pressed(self):
+        """
+        Returns ``True`` if the specified button ``button`` is currently being
+        held down, and ``False`` otherwise.
+        """
+        return self.__pressed
+
+    def was_pressed(self):
+        """
+        Returns ``True`` or ``False`` to indicate if the button was pressed
+        (went from up to down) since the device started or the last time this
+        method was called.  Calling this method will clear the press state so
+        that the button must be pressed again before this method will return
+        ``True`` again.
+        """
+        res = self.__prev_pressed
+        self.__prev_pressed = False
+        return res
+
+    def get_presses(self):
+        """
+        Returns the running total of button presses, and resets this total
+        to zero before returning.
+        """
+        res = self.__presses
+        self.__presses = 0
+        return res
+
+    def __press_down(self):
+        self.__pressed = True
+        self.__prev_pressed = True
+        self.__presses += 1
+
+    def __release(self):
+        self.__pressed = False

src/microbit/model/display.py → src/microbit/__model/display.py

@@ -5,11 +5,10 @@
 
 from . import constants as CONSTANTS
 from .image import Image
-from .. import shim
 
 
 class Display:
-    # The implementation based off of https://github.com/bbcmicrobit/micropython/blob/master/docs/display.rst.
+    # The implementation based off of https://microbit-micropython.readthedocs.io/en/v1.0.1/display.html.
 
     def __init__(self):
         self.__image = Image()
@@ -20,6 +19,23 @@ def __init__(self):
         self.__lock = threading.Lock()
 
     def scroll(self, value, delay=150, wait=True, loop=False, monospace=False):
+        """
+        Scrolls ``value`` horizontally on the display. If ``value`` is an integer or float it is
+        first converted to a string using ``str()``. The ``delay`` parameter controls how fast
+        the text is scrolling.
+
+        If ``wait`` is ``True``, this function will block until the animation is
+        finished, otherwise the animation will happen in the background.
+
+        If ``loop`` is ``True``, the animation will repeat forever.
+
+        If ``monospace`` is ``True``, the characters will all take up 5 pixel-columns
+        in width, otherwise there will be exactly 1 blank pixel-column between each
+        character as they scroll.
+
+        Note that the ``wait``, ``loop`` and ``monospace`` arguments must be specified
+        using their keyword.
+        """
         if not wait:
             thread = threading.Thread(
                 target=self.scroll, args=(value, delay, True, loop, monospace)
@@ -82,6 +98,23 @@ def scroll(self, value, delay=150, wait=True, loop=False, monospace=False):
                 break
 
     def show(self, value, delay=400, wait=True, loop=False, clear=False):
+        """
+        Display the ``image``.
+
+        If ``value`` is a string, float or integer, display letters/digits in sequence.
+        Otherwise, if ``value`` is an iterable sequence of images, display these images in sequence.
+        Each letter, digit or image is shown with ``delay`` milliseconds between them.
+
+        If ``wait`` is ``True``, this function will block until the animation is
+        finished, otherwise the animation will happen in the background.
+
+        If ``loop`` is ``True``, the animation will repeat forever.
+
+        If ``clear`` is ``True``, the display will be cleared after the iterable has finished.
+
+        Note that the ``wait``, ``loop`` and ``clear`` arguments must be specified
+        using their keyword.
+        """
         if not wait:
             thread = threading.Thread(
                 target=self.show, args=(value, delay, True, loop, clear)
@@ -145,33 +178,60 @@ def show(self, value, delay=400, wait=True, loop=False, clear=False):
             self.clear()
 
     def get_pixel(self, x, y):
+        """
+        Return the brightness of the LED at column ``x`` and row ``y`` as an
+        integer between 0 (off) and 9 (bright).
+        """
         self.__lock.acquire()
         pixel = self.__image.get_pixel(x, y)
         self.__lock.release()
         return pixel
 
     def set_pixel(self, x, y, value):
+        """
+        Set the brightness of the LED at column ``x`` and row ``y`` to ``value``,
+        which has to be an integer between 0 and 9.
+        """
         self.__lock.acquire()
         self.__image.set_pixel(x, y, value)
         self.__lock.release()
         self.__update_client()
 
     def clear(self):
+        """
+        Set the brightness of all LEDs to 0 (off).
+        """
         self.__lock.acquire()
         self.__image = Image()
         self.__lock.release()
         self.__update_client()
 
     def on(self):
+        """
+        Use on() to turn on the display.
+        """
         self.__on = True
 
     def off(self):
+        """
+        Use off() to turn off the display.
+        """
         self.__on = False
 
     def is_on(self):
+        """
+        Returns ``True`` if the display is on, otherwise returns ``False``.
+        """
         return self.__on
 
     def read_light_level(self):
+        """
+        Not implemented yet.
+
+        Use the display's LEDs in reverse-bias mode to sense the amount of light
+        falling on the display.  Returns an integer between 0 and 255 representing
+        the light level, with larger meaning more light.
+        """
         raise NotImplementedError(CONSTANTS.NOT_IMPLEMENTED_ERROR)
 
     # Helpers