diff --git a/docs/guide/fretboard.rst b/docs/guide/fretboard.rst index a99b977..33084ae 100644 --- a/docs/guide/fretboard.rst +++ b/docs/guide/fretboard.rst @@ -185,46 +185,46 @@ on any instrument. It scores each possibility by: 2. Preferring **ascending** fret patterns — easier hand position 3. Minimizing the number of **fingers needed** -.. code-block:: python +.. code-block:: pycon - from pytheory import Fretboard, CHARTS + >>> from pytheory import Fretboard, CHARTS - fb = Fretboard.guitar() - c = CHARTS["western"]["C"] + >>> fb = Fretboard.guitar() + >>> f = fb.chord("C") + >>> f + Fingering(e=0, B=1, G=0, D=2, A=3, E=0) - # Fingerings return a Fingering object with labeled strings - f = c.fingering(fretboard=fb) - print(f) - # Fingering(e=0, B=1, G=0, D=2, A=3, E=0) + >>> f['A'] + 3 + >>> f[1] + 1 - # Access by string name or index - f['A'] # 3 - f[1] # 1 (B string) + >>> f.identify() + 'C major' - # Identify the chord directly from a fingering - f.identify() # 'C major' + >>> chord = f.to_chord() + >>> chord.identify() + 'C major' - # Convert to a Chord for further analysis - chord = f.to_chord() - chord.harmony # consonance score - chord.intervals # [4, 3] — major triad + >>> # All equally-scored fingerings via CHARTS + >>> CHARTS["western"]["C"].fingering(fretboard=fb, multiple=True) + [...] - # All equally-scored fingerings - all_c = c.fingering(fretboard=fb, multiple=True) - - # Muted strings appear as None - f = CHARTS["western"]["F"] - print(f.fingering(fretboard=fb)) + >>> # Muted strings appear as None + >>> CHARTS["western"]["F"].fingering(fretboard=fb) + ... You can also go from fret positions to chord identification: -.. code-block:: python +.. code-block:: pycon - # "What chord am I playing?" - fb = Fretboard.guitar() - f = fb.fingering(0, 0, 0, 2, 2, 0) - print(f) # Fingering(e=0, B=0, G=0, D=2, A=2, E=0) - print(f.identify()) # E minor + >>> # "What chord am I playing?" + >>> fb = Fretboard.guitar() + >>> f = fb.fingering(0, 0, 0, 2, 2, 0) + >>> f + Fingering(e=0, B=0, G=0, D=2, A=2, E=0) + >>> f.identify() + 'E minor' Reading Fingerings ~~~~~~~~~~~~~~~~~~ diff --git a/docs/guide/quickstart.rst b/docs/guide/quickstart.rst index 357c0e0..401af5b 100644 --- a/docs/guide/quickstart.rst +++ b/docs/guide/quickstart.rst @@ -117,29 +117,30 @@ Build chords directly: Guitar Fingerings ----------------- -.. code-block:: python +.. code-block:: pycon - from pytheory import Fretboard, CHARTS + >>> from pytheory import Fretboard - fb = Fretboard.guitar() + >>> fb = Fretboard.guitar() - # Get a labeled fingering from the chord chart - f = CHARTS["western"]["C"].fingering(fretboard=fb) - f # Fingering(e=0, B=1, G=0, D=2, A=3, E=0) - f['A'] # 3 + >>> fb.chord("C") + Fingering(e=0, B=1, G=0, D=2, A=3, E=0) - # Identify a chord from fret positions - fb.fingering(0, 0, 0, 2, 2, 0).identify() # 'E minor' + >>> fb.chord("C")['A'] + 3 - # ASCII tablature - print(CHARTS["western"]["Am"].tab(fretboard=fb)) - # Am - # E|--0-- - # B|--1-- - # G|--2-- - # D|--2-- - # A|--0-- - # E|--0-- + >>> fb.fingering(0, 0, 0, 2, 2, 0).identify() + 'E minor' + + >>> from pytheory import CHARTS + >>> print(CHARTS["western"]["Am"].tab(fretboard=fb)) + Am + E|--0-- + B|--1-- + G|--2-- + D|--2-- + A|--0-- + E|--0-- Audio Playback -------------- diff --git a/docs/index.rst b/docs/index.rst index 336291a..ba5b717 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,8 +29,8 @@ instruments using a clean, Pythonic API. 'perfect 5th' >>> fb = Fretboard.guitar() - >>> fb.fingering(0, 1, 0, 2, 3, 0) - Fingering(e=0, B=1, G=0, D=2, A=3, E=0) + >>> fb.chord("G") + Fingering(e=3, B=0, G=0, D=0, A=2, E=3) It also works from the command line:: diff --git a/pyproject.toml b/pyproject.toml index f5ce155..c9c7b69 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "pytheory" -version = "0.6.1" +version = "0.7.0" description = "Music Theory for Humans" readme = "README.md" license = "MIT" diff --git a/pytheory/__init__.py b/pytheory/__init__.py index 3a0ac18..fac1fba 100644 --- a/pytheory/__init__.py +++ b/pytheory/__init__.py @@ -1,6 +1,6 @@ """PyTheory: Music Theory for Humans.""" -__version__ = "0.6.1" +__version__ = "0.7.0" from .tones import Tone, Interval from .systems import System, SYSTEMS diff --git a/pytheory/chords.py b/pytheory/chords.py index 117bbc4..98a8688 100644 --- a/pytheory/chords.py +++ b/pytheory/chords.py @@ -1251,6 +1251,25 @@ class Fretboard: return "\n".join(lines) + def chord(self, name: str, *, system: str = "western") -> "Fingering": + """Look up a chord by name and return its best fingering. + + Args: + name: Chord name like ``"G"``, ``"Am7"``, ``"Bb"``, ``"Dm"``. + system: Tonal system to use (default ``"western"``). + + Returns: + A :class:`Fingering` for that chord on this fretboard. + + Example:: + + >>> fb = Fretboard.guitar() + >>> fb.chord("G") + Fingering(e=3, B=0, G=0, D=0, A=2, E=3) + """ + from .charts import CHARTS + return CHARTS[system][name].fingering(fretboard=self) + def fingering(self, *positions: int) -> "Fingering": """Apply fret positions to each string, returning a Fingering.