this is version 1.2.0

CHANGELOG.rst

@@ -2,6 +2,47 @@
 Changelog
 =========
 
+Version 1.2.0
+=============
+
+**ms3 requires Python 3.10**
+
+Extraction of all lyrics
+------------------------
+
+This version enables the extraction of lyrics with all verses. Previously, only the last verse's syllable for any
+given position was extracted. The lyrics now can be found in `lyrics_[verse]` columns in the chords facet,
+where `lyrics_1` corresponds to the first or only verse.
+
+Extraction of figured bass
+--------------------------
+
+Figured bass labels can now be found in the chords facet tables. Score that include at least one figure will have a
+``thoroughbass_duration`` column and each layer of figures comes in a separate ``thoroughbass_layer_#`` column.
+For example, if all stacks of figures have only layer, there will be only the column ``thoroughbass_layer_1``.
+
+Extraction of custom-named spanners
+-----------------------------------
+
+Spanners with adjusted "Begin text" property get their own columns in the chords tables, containing the relevant subselection of IDs.
+For example, if a score contains normal ``8va`` spanners and others where the "Begin text" has been set to ``custom``,
+all IDs will be combined in the column ``Ottava:8va`` as before, but the subset pertaining to the custom spanners is
+additionally shown in the column ``Ottava:8va_custom``.
+
+Including and excluding paths
+-----------------------------
+
+It is now possible to specify specific directories to be included or excluded from a view, not only folder names.
+
+New methods and properties
+--------------------------
+
+* ``Parse.get_facet()`` (singular)
+* ``Corpus.fnames``
+* ``Corpus.add_dir()``
+* first version of ``utils.merge_chords_and_notes()``
+
+
 Version 1.1.2
 =============
 

src/ms3/operations.py

@@ -10,8 +10,8 @@ def insert_labels_into_score(ms3_object: Union[Parse, Corpus],
                              ask_for_input: bool = True,
                              replace: bool = True,
                              staff: int = None,
-                             voice: Literal[1, 2, 3, 4] = None,
-                             harmony_layer: Literal[0, 1, 2] = None,
+                             voice: Optional[Literal[1, 2, 3, 4]] = None,
+                             harmony_layer: Optional[Literal[0, 1, 2]] = None,
                              check_for_clashes: bool = True
                              ) -> None:
     """ Write labels into the <Harmony> tags of the corresponding MuseScore files.
@@ -23,23 +23,24 @@ def insert_labels_into_score(ms3_object: Union[Parse, Corpus],
             What to do if more than one TSV or MuseScore file is detected for a particular fname. By default, the user is asked for input.
             Pass False to prevent that and pick the files with the shortest relative paths instead.
         replace: By default, any existing labels are removed from the scores. Pass False to leave them in, which may lead to clashes.
-        staff : :obj:`int`, optional
+        staff
             If you pass a staff ID, the labels will be attached to that staff where 1 is the upper stuff.
             By default, the staves indicated in the 'staff' column of :obj:`ms3.annotations.Annotations.df`
-            will be used.
-        voice : {1, 2, 3, 4}, optional
+            will be used, or, if such a column is not present, labels will be inserted under the lowest staff -1.
+        voice
             If you pass the ID of a notational layer (where 1 is the upper voice, blue in MuseScore),
             the labels will be attached to that one.
             By default, the notational layers indicated in the 'voice' column of
-            :obj:`ms3.annotations.Annotations.df` will be used.
-        harmony_layer : :obj:`int`, optional
+            :obj:`ms3.annotations.Annotations.df` will be used, 
+            or, if such a column is not present, labels will be inserted for voice 1.
+        harmony_layer
             | By default, the labels are written to the layer specified as an integer in the column ``harmony_layer``.
             | Pass an integer to select a particular layer:
             | * 0 to attach them as absolute ('guitar') chords, meaning that when opened next time,
             |   MuseScore will split and encode those beginning with a note name ( resulting in ms3-internal harmony_layer 3).
             | * 1 the labels are written into the staff's layer for Roman Numeral Analysis.
             | * 2 to have MuseScore interpret them as Nashville Numbers
-        check_for_clashes : :obj:`bool`, optional
+        check_for_clashes
             By default, warnings are thrown when there already exists a label at a position (and in a notational
             layer) where a new one is attached. Pass False to deactivate these warnings.
     """

src/ms3/utils.py

@@ -32,7 +32,7 @@
 from .logger import function_logger, update_cfg, LogCapturer
 from ._typing import FileDict, Facet, ViewDict, FileDataframeTupleMaybe
 
-MS3_VERSION = '1.1.2'
+MS3_VERSION = '1.2.0'
 LATEST_MUSESCORE_VERSION = '3.6.2'
 COMPUTED_METADATA_COLUMNS = ['TimeSig', 'KeySig', 'last_mc', 'last_mn', 'length_qb', 'last_mc_unfolded', 'last_mn_unfolded', 'length_qb_unfolded',
                          'volta_mcs', 'all_notes_qb', 'n_onsets', 'n_onset_positions',