From e59bf587017ab5b35765770c82de501fbd3e3432 Mon Sep 17 00:00:00 2001 From: Bernd Date: Wed, 17 Jan 2024 22:29:02 +0100 Subject: [PATCH] added docstrings to notes and temperament --- trallala/core/notes.py | 60 ++++++++++++++++++++++++++++--- trallala/core/temperament.py | 69 ++++++++++++++++++++++++++++++++++-- 2 files changed, 123 insertions(+), 6 deletions(-) diff --git a/trallala/core/notes.py b/trallala/core/notes.py index ad9a86f..7f2ed5c 100644 --- a/trallala/core/notes.py +++ b/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) diff --git a/trallala/core/temperament.py b/trallala/core/temperament.py index 86c2568..1d271d1 100644 --- a/trallala/core/temperament.py +++ b/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)}")