added docstrings to notes and temperament

trallala/core/notes.py

@@ -1,16 +1,49 @@
 #!/usr/bin/env python3
 
+"""Note and PitchClass Class definitions
+
+PitchClasses and Notes are fundamentel datatypes for this
+music theory package and are used and supported by all other
+classes like scales, chords or instruments.
+"""
+
 from functools import singledispatchmethod
 import re
 
 from .temperament import _CoreChromaticScale
 
 class Note:
-
+    """Object representing a Note
+
+    The Note object supports the initilization from different datatypes and
+    supports several mathematical operations on top of if.
+
+    Furthermore the Note Class is used as a fundamental class  and is supported
+    by all other classes in trallala.
+
+    Porperties:
+        name:
+            SPN name of the Note
+        distance:
+            Semitone distance to C0
+        frequency:
+            Frequency in Hz of the note
+    """
     @singledispatchmethod
     def __init__(self, note, chromaticscale=_CoreChromaticScale()):
-        """ Creates a Note Object from another Note object, SPN, distance to C0 (int) or a frequency
+        """ Initializes a Note Object
+
+        Creates a Note Object from another Note object, SPN, distance to C0 (int) or a frequency
         (float).
+
+        Args:
+            note:
+                Note, SPN (str), distance to C0 (int) or frequency (float)
+            chromaticscale:
+                ChromaticScale Object. Default: TET12
+        Raises:
+            ValueError:
+                Frequency, SPN, distance does not usable to create note from
         """
         if type(note) == type(self):
             self._shared_init(note.distance, chromaticscale)
@@ -226,10 +259,29 @@ def frequency(self):
 
 
 class PitchClass:
+    """Object representing a ptichclass (e.g. all C notes in all octaves)
+
+    Properties:
+        numeric:
+            Numeric representation (i.e., 0 to 11)
+        name:
+            Str name of the PichClass (e.g. C,D... without added octave)
+    """
 
     def __init__(self, note, chromaticscale=_CoreChromaticScale()):
-        """ Creates the PitchClass containing 'note'; 'note' can be any of SPN,
-        distance to C0, PitchClass numeric (c=0,...) or frequency
+        """ initializes the PitchClass 
+
+        Pitchclass can be initialized from a note, SPN,  distance to C0,
+        PitchClass numeric (c=0,...) or frequency
+
+        Args:
+            note:
+                Refernce value for the intialization. Can be any of Note, SPN,
+                str name (e.g. 'a' without added octave), distance to C0 or frequency.
+            chromaticscale:
+                ChromaticScale used to for the definition. Default: TET12
+
+        Raises:
         """
         try:
             n = Note(note)

trallala/core/temperament.py

@@ -1,11 +1,32 @@
 #!/usr/bin/env python3
 
+""" Core definitions of temperaments, steps per octace
+
+    This packages supports TET12 by default. Additional temperaments can be
+    added to the temperament dict and afterwards used to initialize a 
+    chromaticscale:
+
+    temperament = {
+        '12TET' : TwelveTET()
+    }
+"""
+
 from fractions import Fraction
 import re
 
 
 # definition of temperaments
 class TwelveTET():
+    """ Definition of 12-TET
+
+    Definition of the names and distances and frequency calculation used in
+    a chromaticscale and therefore in all classes of this package.
+
+    Properties:
+        length:
+            Length (amount of steps) in an octave
+
+    """
     _len = 12
     _precision = 2
     _semitone_distance = {
@@ -43,17 +64,49 @@ def __len__(self):
 
     def get_note_frequency(self, root, distance, precision=None):
         """ Returns the frequency of note with 'distance' to 'root' frequency
+
+        Args:
+            root:
+                root frequency used to calculate the target frequency
+            distance:
+                Semitone-step distance of target from root
+            precision:
+                Floating point precision of the return
+        Returns:
+            Frequency as float
         """
         if not precision:
             precision = self._precision
         return round(root * ((2**Fraction(1, self._len)) ** distance), precision)
 
     def distance_to_name(self, distance):
-        """ Translates any note distance to the number of the pitch class (int)
+        """ Translates any note distance to the name of the pitch class (int)
+
+        Args:
+            distance:
+                semitone distance to C. Must be int with a value in
+                range(self.length)
+        Returns:
+            Name of pitchclass as str
+        Raises:
+            KeyError:
+                Distance > self.length
         """
         return self._reverse_semitone_distance[distance]
 
     def name_to_distance(self, name):
+        """Translates a name of a pitchclass into the semitone distance.
+
+        Args:
+            name:
+                Name of pitchclass without added octave
+        Returns:
+            Numeric name of the pitchclass (name without added octave)
+        Raises:
+            ValueError:
+                Unknown name
+
+        """
         name = name.lower()
         if name in self._semitone_distance:
             return self._semitone_distance[name]
@@ -78,13 +131,25 @@ def init_temperament():
 
 
 class _CoreChromaticScale:
+    """ 'Raw' ChromaticScales used by Notes and PitchClasses
+
+    This 'raw' Class is used to prevent circular dependencies of the classes
+    in this package and does not support higher level data types.
+
+    Please use trallala.core.scales.ChromaticSclae instead.
+
+    !DO NOT USE THIS CLASS OUTSIDE OF TRALLALA!
+
+    """
     _number_octaves = 9
 
     def __init__(self, note=('a4', 440), temperament=temperament['12TET']):
         """ Warning: Internal Class only. Please use ChromaticScale instead.
+
         Creates Chromatic Scale from given note (Scientific Pitch Notation)
         and a temperament distance list. For non-12 steps scales, a list of
-        tone with the correpsonding half-tone distance must be be provided in addition. Default: A4=440Hz and 12TET"""
+        tone with the correpsonding half-tone distance must be be provided 
+        in addition. Default: A4=440Hz and 12TET"""
 
         if type(note) is not list and type(note) is not tuple:
             raise ValueError(f"Wrong anchor note type: {type(note)}")