Improve documentation about Note.dynamics deprecation and constructor

Author: edudobay

doc/wiki/refMingusContainersNote.rst

@@ -19,7 +19,13 @@ mingus.containers.note
    .. method:: __gt__(self, other)
 
 
-   .. method:: __init__(self, name=C, octave=4, dynamics={})
+   .. method:: __init__(self, name=C, octave=4, dynamics=None, velocity=None, channel=None)
+
+      :param name:
+      :param octave:
+      :param dynamics: Deprecated. Use `velocity` and `channel` directly.
+      :param velocity:
+      :param channel:
 
 
    .. method:: __int__(self)
@@ -152,13 +158,26 @@ mingus.containers.note
       Call notes.remove_redundant_accidentals on this note's name.
 
 
-   .. method:: set_note(self, name=C, octave=4, dynamics={})
+   .. method:: set_channel(self, channel)
+
+
+   .. method:: set_note(self, name=C, octave=4, dynamics=None, velocity=None, channel=None)
 
       Set the note to name in octave with dynamics.
 
       Return the objects if it succeeded, raise an NoteFormatError
       otherwise.
 
+      :param name:
+      :param octave:
+      :param dynamics: Deprecated. Use `velocity` and `channel` directly.
+      :param velocity:
+      :param channel:
+      :return:
+
+
+   .. method:: set_velocity(self, velocity)
+
 
    .. method:: to_hertz(self, standard_pitch=440)
 

mingus/containers/note.py

@@ -52,6 +52,13 @@ class Note(object):
     velocity = _DEFAULT_VELOCITY
 
     def __init__(self, name="C", octave=4, dynamics=None, velocity=None, channel=None):
+        """
+        :param name:
+        :param octave:
+        :param dynamics: Deprecated. Use `velocity` and `channel` directly.
+        :param int velocity: Integer (0-127)
+        :param int channel: Integer (0-15)
+        """
         if dynamics is None:
             dynamics = {}
 
@@ -68,12 +75,13 @@ def __init__(self, name="C", octave=4, dynamics=None, velocity=None, channel=Non
         elif isinstance(name, int):
             self.from_int(name)
         else:
-            raise NoteFormatError(
-                "Don't know what to do with name object: " "'%s'" % name
-            )
+            raise NoteFormatError("Don't know what to do with name object: %r" % name)
 
     @property
     def dynamics(self):
+        """
+        .. deprecated:: Provided only for compatibility with existing code.
+        """
         return {
             "channel": self.channel,
             "velocity": self.velocity,
@@ -94,6 +102,13 @@ def set_note(self, name="C", octave=4, dynamics=None, velocity=None, channel=Non
 
         Return the objects if it succeeded, raise an NoteFormatError
         otherwise.
+
+        :param name:
+        :param octave:
+        :param dynamics: Deprecated. Use `velocity` and `channel` directly.
+        :param int velocity: Integer (0-127)
+        :param int channel: Integer (0-15)
+        :return:
         """
         if dynamics is None:
             dynamics = {}
@@ -115,22 +130,17 @@ def set_note(self, name="C", octave=4, dynamics=None, velocity=None, channel=Non
                 self.octave = octave
                 return self
             else:
-                raise NoteFormatError(
-                    "The string '%s' is not a valid "
-                    "representation of a note in mingus" % name
-                )
+                raise NoteFormatError("Invalid note representation: %r" % name)
         elif len(dash_index) == 2:
             note, octave = dash_index
             if notes.is_valid_note(note):
                 self.name = note
                 self.octave = int(octave)
                 return self
             else:
-                raise NoteFormatError(
-                    "The string '%s' is not a valid "
-                    "representation of a note in mingus" % name
-                )
-        return False
+                raise NoteFormatError("Invalid note representation: %r" % name)
+        else:
+            raise NoteFormatError("Invalid note representation: %r" % name)
 
     def empty(self):
         """Remove the data in the instance."""

mingus/containers/note_container.py

@@ -83,7 +83,7 @@ def add_notes(self, notes):
         >>> notes = [['C', 5], ['E', 5], ['G', 6]]
 
         or even:
-        >>> notes = [['C', 5, {'volume': 20}], ['E', 6, {'volume': 20}]]
+        >>> notes = [['C', 5, {'velocity': 20}], ['E', 6, {'velocity': 20}]]
         """
         if hasattr(notes, "notes"):
             for x in notes.notes:

tests/unit/containers/test_note_containers.py

@@ -1,8 +1,10 @@
 # -*- coding: utf-8 -*-
 from __future__ import absolute_import
 
+import doctest
 import unittest
 
+import mingus.containers.note_container
 from mingus.containers.note import Note
 from mingus.containers.note_container import NoteContainer
 
@@ -135,3 +137,8 @@ def test_is_dissonant(self):
         self.assertTrue(not NoteContainer().from_chord("C").is_dissonant())
         self.assertTrue(not NoteContainer().from_chord("G").is_dissonant())
         self.assertTrue(not NoteContainer().from_chord("Dm").is_dissonant())
+
+
+def load_tests(loader, tests, ignore):
+    tests.addTests(doctest.DocTestSuite(mingus.containers.note_container))
+    return tests