concertina_helper

 1"""
 2**concertina_helper** is a python script and supporting API
 3to find good fingerings on bisonoric concertinas for
 4tunes in [ABC notation](https://abcnotation.com/).
 5
 6This is the API documentation; For help with the CLI,
 7see the [README](https://github.com/mccalluc/concertina-helper#readme).
 8
 9The CLI is a thin wrapper around
10`concertina_helper.notes_on_layout.TuneOnLayout.get_best_fingerings`:
11
12>>> from pathlib import Path
13>>> from pyabc2 import Tune
14>>> from concertina_helper.notes_on_layout import NotesOnLayout
15>>> from concertina_helper.note_generators import notes_from_tune
16>>> from concertina_helper.layouts.layout_loader import load_bisonoric_layout_by_name
17>>> from concertina_helper.penalties import (
18...     penalize_finger_in_same_column, penalize_bellows_change, penalize_outer_fingers)
19>>> tune = Tune(Path('tests/g-major.abc').read_text())
20>>> notes = notes_from_tune(tune)
21>>> layout = load_bisonoric_layout_by_name('30_wheatstone_cg')
22>>> n_l = NotesOnLayout(notes, layout)
23>>> best = n_l.get_best_fingerings([
24...     penalize_finger_in_same_column(3),
25...     penalize_bellows_change(2),
26...     penalize_outer_fingers(1)
27... ])
28>>> len(best)
298
30>>> print(best[0].fingering)
31PULL:
32--- --- --- G4  ---    --- --- --- --- ---
33--- --- --- --- ---    --- --- --- --- ---
34--- --- --- --- ---    --- --- --- --- ---
35>>> print(best[-1].fingering)
36PULL:
37--- --- --- --- ---    --- G5  --- --- ---
38--- --- --- --- ---    --- --- --- --- ---
39--- --- --- --- ---    --- --- --- --- ---
40>>> from concertina_helper.output_utils import condense
41>>> print(condense(best))
42. . . ➊ .   . ➑ . . .
43. . . . .   ➌ ➎ . . .
44. . ➋ ➍ ➏   ➐ . . . .
45
46**concertina_helper** models a tune as a graph,
47with each possible fingering for a given note a node in that graph. It then uses an
48[implementation of the A* algorithm](https://github.com/jrialland/python-astar/)
49(wrapped in `concertina_helper.finger_finder`)
50to find the best path through this graph.
51
52Utilities to load ABC tunes and plain lists of pitches
53are in `concertina_helper.note_generators`.
54
55Classes representing uni- and bisonoric layouts, fingerings on those layouts,
56and utilities to create layouts, are in `concertina_helper.layouts`.
57
58Functions that encapsulate heuristics about what makes a "good" fingering are in
59`concertina_helper.penalties`, or you can provide your own penalty functions.
60"""
61
62__version__ = "0.0.3"