From c3e74273d28a8bc9077b508e458cce628ebbbd9d Mon Sep 17 00:00:00 2001 From: David Lechner Date: Sun, 12 Jan 2020 14:10:06 -0600 Subject: [PATCH] pybricks/builtins: update Speaker docs --- doc/api/hubs_ev3brick.inc | 16 +++++++------ doc/common/conf.py | 5 +++++ pybricks/_instances.py | 4 +--- pybricks/builtins.py | 47 ++++++++++++++++++++++++++++++++++----- 4 files changed, 56 insertions(+), 16 deletions(-) diff --git a/doc/api/hubs_ev3brick.inc b/doc/api/hubs_ev3brick.inc index 0efff07..07421a4 100644 --- a/doc/api/hubs_ev3brick.inc +++ b/doc/api/hubs_ev3brick.inc @@ -20,19 +20,21 @@ .. rubric:: Using the speaker - .. automethod:: pybricks._instances.speaker.volume + .. todo:: The following method is not yet implemented - .. automethod:: pybricks._instances.speaker.beep + .. automethod:: pybricks.hubs::EV3Brick.speaker.volume - .. automethod:: pybricks._instances.speaker.play + .. automethod:: pybricks.hubs::EV3Brick.speaker.beep - .. todo:: The following functionality is not yet implemented + .. automethod:: pybricks.hubs::EV3Brick.speaker.play_notes - .. automethod:: pybricks._instances.speaker.say + .. automethod:: pybricks.hubs::EV3Brick.speaker.play_file - .. todo:: The following functionality is not yet implemented + .. automethod:: pybricks.hubs::EV3Brick.speaker.say - .. automethod:: pybricks._instances.speaker.set_voice_settings + .. todo:: The following method is not yet implemented + + .. automethod:: pybricks.hubs::EV3Brick.speaker.set_voice_settings .. rubric:: Using the screen diff --git a/doc/common/conf.py b/doc/common/conf.py index d847131..6569c8e 100644 --- a/doc/common/conf.py +++ b/doc/common/conf.py @@ -25,6 +25,7 @@ sys.path.insert(0, os.path.abspath('../..')) from pybricks import _version # noqa E402 from pybricks.hubs import EV3Brick # noqa E402 from pybricks.resources import Image # noqa E402 +from pybricks.builtins import Speaker # noqa E402 # ON_RTD is whether we are on readthedocs.org # this line of code grabbed from docs.readthedocs.org @@ -110,6 +111,7 @@ nitpick_ignore = [ ('py:class', 'dict'), ('py:class', 'float'), ('py:class', 'int'), + ('py:class', 'iter'), ('py:class', 'list'), ('py:class', 'object'), ('py:class', 'str'), @@ -288,9 +290,12 @@ def find_obj(self, env, modname, classname, name, type, searchmode=0): modname = 'pybricks.resources' else: classname = 'EV3Brick.screen' + elif classname == 'speaker': + classname = 'EV3Brick.speaker' return base_find_obj(self, env, modname, classname, name, type, searchmode) PythonDomain.find_obj = find_obj EV3Brick.screen = Image +EV3Brick.speaker = Speaker diff --git a/pybricks/_instances.py b/pybricks/_instances.py index 81d0d4c..e472b8d 100644 --- a/pybricks/_instances.py +++ b/pybricks/_instances.py @@ -1,6 +1,6 @@ """Sphinx workaround to document instance attributes such as self.light""" -from .builtins import Motor, Speaker, Battery, ColorLight, KeyPad, LightArray +from .builtins import Motor, Battery, ColorLight, KeyPad, LightArray from .parameters import Direction, Stop from types import ModuleType @@ -23,8 +23,6 @@ buttons = make_instance(KeyPad) battery = make_instance(Battery) -speaker = make_instance(Speaker) - class Motor(Motor): """Generic class to control motors with built-in rotation sensors.""" diff --git a/pybricks/builtins.py b/pybricks/builtins.py index f337076..566f3db 100644 --- a/pybricks/builtins.py +++ b/pybricks/builtins.py @@ -338,17 +338,50 @@ class Speaker(): """Play a beep/tone. Arguments: - frequency (:ref:`frequency`): Frequency of the beep - (*Default*: 500). - duration (:ref:`time`): Duration of the beep (*Default*: 100). + frequency (:ref:`frequency`): + Frequency of the beep (*Default*: 500). Frequencies below 100 + are treated as 100. + duration (:ref:`time`): + Duration of the beep (*Default*: 100). If the duration is less + than 0, then the method returns immediately and the frequency + play continues to play indefinitely. """ pass - def play(self, file_name): + def play_notes(self, notes, tempo=120): + """Play a sequence of notes. + + Notes are strings with the following format: + + - The first character is the name of the note, ``A`` to ``G`` or ``R`` + for a rest. + - Note names can also include an accidental ``#`` (sharp) or ``b`` + (flat). ``B#``/``Cb`` and ``E#``/``Fb`` are not allowed. + - The note name is followed by the octave number ``2`` to ``8``. For + example ``C4`` is middle C. The octave changes to the next number at + the note C, for example, ``B3`` is the note below middle C (``C4``). + - The octave is followed by ``/`` and a number that indicates the size + of the note. For example ``/4`` is a quarter note, ``/8`` is an + eight note and so on. + - This can optionally followed by a ``.`` to make a dotted note. + Dotted notes are 1-1/2 times as long as notes without a dot. + - The note can optionally end with a ``_`` which is a tie or a slur. + This causes there to be no pause between this note and the next note. + + Arguments: + notes (iter): + A sequence of notes to be played (see format above). + tempo (int): + Beats per minute where a quarter note is one beat. + """ + pass + + def play_file(self, file_name): """Play a sound file. Arguments: - file_name (str): Path to the sound file, including extension. + file_name (str): + Path to the sound file, including the file extension. """ pass @@ -356,6 +389,8 @@ class Speaker(): def say(self, text): """Say a given text string. + The settings from :meth:`set_voice_settings` will affect the playback. + Arguments: text (str): What to say. """ @@ -366,7 +401,7 @@ class Speaker(): """Configure voice settings used by the ``say`` method. Arguments: - language (str):: + language (str): - ``'en'`` (English) - ``'nl'`` (Dutch) - ``'de'`` (German)