kernpy 0.0.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

kernpy/core/transposer.py

@@ -0,0 +1,300 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Optional
+
+from .pitch_models import (
+    NotationEncoding,
+    AgnosticPitch,
+    PitchExporterFactory,
+    PitchImporterFactory,
+    Direction,
+)
+
+
+Intervals = {
+    -2: 'dd1',
+    -1: 'd1',
+    0: 'P1',
+    1: 'A1',
+    2: 'AA1',
+    3: 'dd2',
+    4: 'd2',
+    5: 'm2',
+    6: 'M2',
+    7: 'A2',
+    8: 'AA2',
+    9: 'dd3',
+    10: 'd3',
+    11: 'm3',
+    12: 'M3',
+    13: 'A3',
+    14: 'AA3',
+    15: 'dd4',
+    16: 'd4',
+    17: 'P4',
+    18: 'A4',
+    19: 'AA4',
+    21: 'dd5',
+    # 20 is unused
+    22: 'd5',
+    23: 'P5',
+    24: 'A5',
+    25: 'AA5',
+    26: 'dd6',
+    27: 'd6',
+    28: 'm6',
+    29: 'M6',
+    30: 'A6',
+    31: 'AA6',
+    32: 'dd7',
+    33: 'd7',
+    34: 'm7',
+    35: 'M7',
+    36: 'A7',
+    37: 'AA7',
+    40: 'octave'
+}
+"""
+Base-40 interval classes (d=diminished, m=minor, M=major, P=perfect, A=augmented)
+"""
+
+IntervalsByName = {v: k for k, v in Intervals.items()}  # reverse the key-value pairs
+AVAILABLE_INTERVALS = sorted(IntervalsByName.keys())
+
+LETTER_TO_SEMITONES = {
+    'C': 0,
+    'D': 2,
+    'E': 4,
+    'F': 5,
+    'G': 7,
+    'A': 9,
+    'B': 11,
+}
+
+
+def transpose_agnostics(
+        input_pitch: AgnosticPitch,
+        interval: int,
+        direction: str = Direction.UP.value
+) -> AgnosticPitch:
+    """
+    Transpose an AgnosticPitch by a given interval.
+
+    Args:
+        input_pitch (AgnosticPitch): The pitch to transpose.
+        interval (int): The interval to transpose the pitch.
+        direction (str): The direction of the transposition. 'UP' or 'DOWN'. Default is 'UP'.
+
+    Returns :
+        AgnosticPitch: The transposed pitch.
+
+    Examples:
+        >>> transpose_agnostics(AgnosticPitch('C', 4), IntervalsByName['P4'])
+        AgnosticPitch('F', 4)
+        >>> transpose_agnostics(AgnosticPitch('C', 4), IntervalsByName['P4'], direction='down')
+        AgnosticPitch('G', 3)
+        >>> transpose_agnostics(AgnosticPitch('C#', 4), IntervalsByName['P4'])
+        AgnosticPitch('F#', 4)
+        >>> transpose_agnostics(AgnosticPitch('G', 4), IntervalsByName['m3'], direction='down')
+        AgnosticPitch('Bb', 4)
+
+    """
+    return AgnosticPitch.to_transposed(input_pitch, interval, direction)
+
+
+def transpose_encoding_to_agnostic(
+        input_encoding: str,
+        interval: int,
+        input_format: str = NotationEncoding.HUMDRUM.value,
+        direction: str = Direction.UP.value
+) -> AgnosticPitch:
+    """
+    Transpose a pitch by a given interval.
+
+    The pitch must be in the American notation.
+
+    Args:
+        input_encoding (str): The pitch to transpose.
+        interval (int): The interval to transpose the pitch.
+        input_format (str): The encoding format of the pitch. Default is HUMDRUM.
+        direction (str): The direction of the transposition.'UP' or 'DOWN' Default is 'UP'.
+
+    Returns:
+        AgnosticPitch: The transposed pitch.
+
+    Examples:
+        >>> transpose_encoding_to_agnostic('ccc', IntervalsByName['P4'], input_format='kern')
+        AgnosticPitch('fff', 4)
+        >>> transpose_encoding_to_agnostic('ccc', IntervalsByName['P4'], input_format=NotationEncoding.HUMDRUM.value)
+        AgnosticPitch('fff', 4)
+        >>> transpose_encoding_to_agnostic('ccc', IntervalsByName['P4'], input_format='kern', direction='down')
+        AgnosticPitch('gg', 3)
+        >>> transpose_encoding_to_agnostic('ccc#', IntervalsByName['P4'])
+        AgnosticPitch('fff#', 4)
+        >>> transpose_encoding_to_agnostic('G4', IntervalsByName['m3'], input_format='american')
+        AgnosticPitch('Bb4', 4)
+        >>> transpose_encoding_to_agnostic('C3', IntervalsByName['P4'], input_format='american', direction='down')
+        AgnosticPitch('G2', 2)
+
+    """
+    importer = PitchImporterFactory.create(input_format)
+    pitch: AgnosticPitch = importer.import_pitch(input_encoding)
+
+    return transpose_agnostics(pitch, interval, direction=direction)
+
+
+def transpose_agnostic_to_encoding(
+        agnostic_pitch: AgnosticPitch,
+        interval: int,
+        output_format: str = NotationEncoding.HUMDRUM.value,
+        direction: str = Direction.UP.value
+) -> str:
+    """
+    Transpose an AgnosticPitch by a given interval.
+
+    Args:
+        agnostic_pitch (AgnosticPitch): The pitch to transpose.
+        interval (int): The interval to transpose the pitch.
+        output_format (Optional[str]): The encoding format of the transposed pitch. Default is HUMDRUM.
+        direction (Optional[str]): The direction of the transposition.'UP' or 'DOWN' Default is 'UP'.
+
+    Returns (str):
+        str: The transposed pitch.
+
+    Examples:
+        >>> transpose_agnostic_to_encoding(AgnosticPitch('C', 4), IntervalsByName['P4'])
+        'F4'
+        >>> transpose_agnostic_to_encoding(AgnosticPitch('C', 4), IntervalsByName['P4'], direction='down')
+        'G3'
+        >>> transpose_agnostic_to_encoding(AgnosticPitch('C#', 4), IntervalsByName['P4'])
+        'F#4'
+        >>> transpose_agnostic_to_encoding(AgnosticPitch('G', 4), IntervalsByName['m3'], direction='down')
+        'Bb4'
+    """
+    exporter = PitchExporterFactory.create(output_format)
+    transposed_pitch = transpose_agnostics(agnostic_pitch, interval, direction=direction)
+    content = exporter.export_pitch(transposed_pitch)
+
+    return content
+
+
+
+
+
+def transpose(
+        input_encoding: str,
+        interval: int,
+        input_format: str = NotationEncoding.HUMDRUM.value,
+        output_format: str = NotationEncoding.HUMDRUM.value,
+        direction: str = Direction.UP.value
+) -> str:
+    """
+    Transpose a pitch by a given interval.
+
+    The pitch must be in the American notation.
+
+    Args:
+        input_encoding (str): The pitch to transpose.
+        interval (int): The interval to transpose the pitch.
+        input_format (str): The encoding format of the pitch. Default is HUMDRUM.
+        output_format (str): The encoding format of the transposed pitch. Default is HUMDRUM.
+        direction (str): The direction of the transposition.'UP' or 'DOWN' Default is 'UP'.
+
+    Returns:
+        str: The transposed pitch.
+
+    Examples:
+        >>> transpose('ccc', IntervalsByName['P4'], input_format='kern', output_format='kern')
+        'fff'
+        >>> transpose('ccc', IntervalsByName['P4'], input_format=NotationEncoding.HUMDRUM.value)
+        'fff'
+        >>> transpose('ccc', IntervalsByName['P4'], input_format='kern', direction='down')
+        'gg'
+        >>> transpose('ccc', IntervalsByName['P4'], input_format='kern', direction=Direction.DOWN.value)
+        'gg'
+        >>> transpose('ccc#', IntervalsByName['P4'])
+        'fff#'
+        >>> transpose('G4', IntervalsByName['m3'], input_format='american')
+        'Bb4'
+        >>> transpose('G4', IntervalsByName['m3'], input_format=NotationEncoding.AMERICAN.value)
+        'Bb4'
+        >>> transpose('C3', IntervalsByName['P4'], input_format='american', direction='down')
+        'G2'
+
+
+    """
+    importer = PitchImporterFactory.create(input_format)
+    pitch: AgnosticPitch = importer.import_pitch(input_encoding)
+
+    transposed_pitch = transpose_agnostics(pitch, interval, direction=direction)
+
+    exporter = PitchExporterFactory.create(output_format)
+    content = exporter.export_pitch(transposed_pitch)
+
+    return content
+
+
+def agnostic_distance(
+    first_pitch: AgnosticPitch,
+    second_pitch: AgnosticPitch,
+) -> int:
+    """
+    Calculate the distance in semitones between two pitches.
+
+    Args:
+        first_pitch (AgnosticPitch): The first pitch to compare.
+        second_pitch (AgnosticPitch): The second pitch to compare.
+
+    Returns:
+        int: The distance in semitones between the two pitches.
+
+    Examples:
+        >>> agnostic_distance(AgnosticPitch('C4'), AgnosticPitch('E4'))
+        4
+        >>> agnostic_distance(AgnosticPitch('C4'), AgnosticPitch('B3'))
+        -1
+    """
+    def semitone_index(p: AgnosticPitch) -> int:
+        # base letter:
+        letter = p.name.replace('+', '').replace('-', '')
+        base = LETTER_TO_SEMITONES[letter]
+        # accidentals: '+' is one sharp, '-' one flat
+        alteration = p.name.count('+') - p.name.count('-')
+        return p.octave * 12 + base + alteration
+
+    return semitone_index(second_pitch) - semitone_index(first_pitch)
+
+
+def distance(
+    first_encoding: str,
+    second_encoding: str,
+    *,
+    first_format: str = NotationEncoding.HUMDRUM.value,
+    second_format: str = NotationEncoding.HUMDRUM.value,
+) -> int:
+    """
+    Calculate the distance in semitones between two pitches.
+
+    Args:
+        first_encoding (str): The first pitch to compare.
+        second_encoding (str): The second pitch to compare.
+        first_format (str): The encoding format of the first pitch. Default is HUMDRUM.
+        second_format (str): The encoding format of the second pitch. Default is HUMDRUM.
+
+    Returns:
+        int: The distance in semitones between the two pitches.
+
+    Examples:
+        >>> distance('C4', 'E4')
+        4
+        >>> distance('C4', 'B3')
+        -1
+    """
+    first_importer = PitchImporterFactory.create(first_format)
+    first_pitch: AgnosticPitch = first_importer.import_pitch(first_encoding)
+
+    second_importer = PitchImporterFactory.create(second_format)
+    second_pitch: AgnosticPitch = second_importer.import_pitch(second_encoding)
+
+    return agnostic_distance(first_pitch, second_pitch)

kernpy/io/__init__.py

@@ -0,0 +1,14 @@
+from .public import *
+
+__all__ = [
+    'load',
+    'loads',
+    'dump',
+    'dumps',
+    'merge',
+    'concat',
+    'spine_types',
+    'graph'
+]
+
+

kernpy/io/public.py

@@ -0,0 +1,355 @@
+"""
+Public API for KernPy.
+
+The main functions for handling the input and output of **kern files are provided here.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional, Any, Union, Tuple, Sequence
+
+from kernpy import Encoding
+from kernpy.core import (
+    Document, Importer, Exporter, ExportOptions, GraphvizExporter,
+    generic,
+    TokenCategoryHierarchyMapper)
+
+
+def load(fp: Union[str, Path], *, raise_on_errors: Optional[bool] = False, **kwargs) -> (Document, List[str]):
+    """
+    Load a Document object from a Humdrum **kern file-like object.
+
+    Args:
+        fp (Union[str, Path]): A path-like object representing a **kern file.
+        raise_on_errors (Optional[bool], optional): If True, raise an exception if any grammar error is detected\
+            during parsing.
+
+    Returns ((Document, List[str])): A tuple containing the Document object and a list of messages representing \
+        grammar errors detected during parsing. If the list is empty,\
+        the parsing did not detect any errors.
+
+    Raises:
+        ValueError: If the Humdrum **kern representation could not be parsed.
+
+    Examples:
+        >>> import kernpy as kp
+        >>> document, errors = kp.load('BWV565.krn')
+        >>> if len(errors) > 0:
+        >>>     print(f"Grammar didn't recognize the following errors: {errors}")
+        ['Error: Invalid **kern spine: 1', 'Error: Invalid **kern spine: 2']
+        >>>     # Anyway, we can use the Document
+        >>>     print(document)
+        >>> else:
+        >>>     print(document)
+        <kernpy.core.document.Document object at 0x7f8b3b7b3d90>
+    """
+    return generic.Generic.read(
+        path=fp,
+        strict=raise_on_errors,
+    )
+
+
+def loads(s, *, raise_on_errors: Optional[bool] = False, **kwargs) -> (Document, List[str]):
+    """
+    Load a Document object from a string encoded in Humdrum **kern.
+
+    Args:
+        s (str): A string containing a **kern file.
+        raise_on_errors (Optional[bool], optional): If True, raise an exception if any grammar error is detected\
+            during parsing.
+
+    Returns ((Document, List[str])): A tuple containing the Document object and a list of messages representing \
+        grammar errors detected during parsing. If the list is empty,\
+        the parsing did not detect any errors.
+
+    Raises:
+        ValueError: If the Humdrum **kern representation could not be parsed.
+
+    Examples:
+        >>> import kernpy as kp
+        >>> document, errors = kp.loads('**kern\n*clefG2\n=1\n4c\n4d\n4e\n4f\n')
+        >>> if len(errors) > 0:
+        >>>     print(f"Grammar didn't recognize the following errors: {errors}")
+        ['Error: Invalid **kern spine: 1']
+        >>>     # Anyway, we can use the Document
+        >>>     print(document)
+        >>> else:
+        >>>     print(document)
+        <kernpy.core.document.Document object at 0x7f8b3b7b3d90>
+    """
+    return generic.Generic.create(
+        content=s,
+        strict=raise_on_errors,
+    )
+
+
+def dump(document: Document, fp: Union[str, Path], *,
+         spine_types: [] = None,
+         include: [] = None,
+         exclude: [] = None,
+         from_measure: int = None,
+         to_measure: int = None,
+         tokenizer: Encoding = None,
+         instruments: [] = None,
+         show_measure_numbers: bool = None,
+         spine_ids: [int] = None
+         ) -> None:
+    """
+
+    Args:
+        document (Document): The Document object to write to the file.
+        fp (Union[str, Path]): The file path to write the Document object.
+        spine_types (Iterable): **kern, **mens, etc...
+        include (Iterable): The token categories to include in the exported file. When None, all the token categories will be exported.
+        exclude (Iterable): The token categories to exclude from the exported file. When None, no token categories will be excluded.
+        from_measure (int): The measure to start exporting. When None, the exporter will start from the beginning of the file. The first measure is 1
+        to_measure (int): The measure to end exporting. When None, the exporter will end at the end of the file.
+        tokenizer (Encoding): The type of the **kern file to export.
+        instruments (Iterable): The instruments to export. If None, all the instruments will be exported.
+        show_measure_numbers (Bool): Show the measure numbers in the exported file.
+        spine_ids (Iterable): The ids of the spines to export. When None, all the spines will be exported. \
+            Spines ids start from 0, and they are increased by 1 for each spine to the right.
+
+
+    Returns (None): None
+
+    Raises:
+        ValueError: If the document could not be exported.
+
+    Examples:
+        >>> import kernpy as kp
+        >>> document, errors = kp.load('BWV565.krn')
+        >>> kp.dump(document, 'BWV565_normalized.krn')
+        None
+        >>> # File 'BWV565_normalized.krn' will be created with the normalized **kern representation.
+    """
+    # Create an ExportOptions instance with only user-modified arguments
+    options = generic.Generic.parse_options_to_ExportOptions(
+        spine_types=spine_types,
+        include=include,
+        exclude=exclude,
+        from_measure=from_measure,
+        to_measure=to_measure,
+        kern_type=tokenizer,
+        instruments=instruments,
+        show_measure_numbers=show_measure_numbers,
+        spine_ids=spine_ids
+    )
+
+    return generic.Generic.store(
+        document=document,
+        path=fp,
+        options=options
+    )
+
+
+def dumps(document: Document, *,
+          spine_types: [] = None,
+          include: [] = None,
+          exclude: [] = None,
+          from_measure: int = None,
+          to_measure: int = None,
+          tokenizer: Encoding = None,
+          instruments: [] = None,
+          show_measure_numbers: bool = None,
+          spine_ids: [int] = None
+          ) -> str:
+    """
+
+    Args:
+        document (Document): The Document object to write to the file.
+        fp (Union[str, Path]): The file path to write the Document object.
+        spine_types (Iterable): **kern, **mens, etc...
+        include (Iterable): The token categories to include in the exported file. When None, all the token categories will be exported.
+        exclude (Iterable): The token categories to exclude from the exported file. When None, no token categories will be excluded.
+        from_measure (int): The measure to start exporting. When None, the exporter will start from the beginning of the file. The first measure is 1
+        to_measure (int): The measure to end exporting. When None, the exporter will end at the end of the file.
+        tokenizer (Encoding): The type of the **kern file to export.
+        instruments (Iterable): The instruments to export. If None, all the instruments will be exported.
+        show_measure_numbers (Bool): Show the measure numbers in the exported file.
+        spine_ids (Iterable): The ids of the spines to export. When None, all the spines will be exported. \
+            Spines ids start from 0, and they are increased by 1 for each spine to the right.
+
+
+    Returns (None): None
+
+    Raises:
+        ValueError: If the document could not be exported.
+
+    Examples:
+        >>> import kernpy as kp
+        >>> document, errors = kp.load('score.krn')
+        >>> kp.dumps(document)
+        '**kern\n*clefG2\n=1\n4c\n4d\n4e\n4f\n*-'
+    """
+    # Create an ExportOptions instance with only user-modified arguments
+    options = generic.Generic.parse_options_to_ExportOptions(
+        spine_types=spine_types,
+        include=include,
+        exclude=exclude,
+        from_measure=from_measure,
+        to_measure=to_measure,
+        kern_type=tokenizer,
+        instruments=instruments,
+        show_measure_numbers=show_measure_numbers,
+        spine_ids=spine_ids
+    )
+
+    return generic.Generic.export(
+        document=document,
+        options=options
+    )
+
+
+def graph(document: Document, fp: Optional[Union[str, Path]]) -> None:
+    """
+    Create a graph representation of a Document object using Graphviz. Save the graph as a .dot file or indicate the\
+     output file path or stream. If the output file path is None, the function will return the graphviz content as a\
+        string to the standard output.
+
+    Use the Graphviz software to convert the .dot file to an image.
+
+
+    Args:
+        document (Document): The Document object to export as a graphviz file.
+        fp (Optional[Union[str, Path]]): The file path to write the graphviz file. If None, the function will return the\
+            graphviz content as a string to the standard output.
+
+    Returns (None): None
+
+    Examples:
+        >>> import kernpy as kp
+        >>> document, errors = kp.load('score.krn')
+        >>> kp.graph(document, 'score.dot')
+        None
+        >>> # File 'score.dot' will be created with the graphviz representation of the Document object.
+        >>> kp.graph(document, None)
+        'digraph G { ... }'
+    """
+    return generic.Generic.store_graph(
+        document=document,
+        path=fp
+    )
+
+
+def concat(
+        contents: List[str],
+        *,
+        separator: Optional[str] = '\n',
+) -> Tuple[Document, List[Tuple[int, int]]]:
+    """
+    Concatenate multiple **kern fragments into a single Document object. \
+     All the fragments should be presented in order. Each fragment does not need to be a complete **kern file. \
+
+    Warnings:
+        Processing a large number of files in a row may take some time.
+         This method performs as many `kp.read` operations as there are fragments to concatenate.
+    Args:
+        contents (Sequence[str]): List of **kern strings
+        separator (Optional[str]): Separator string to separate the **kern fragments. Default is '\n' (newline).
+
+    Returns (Tuple[Document, List[Tuple[int, int]]]): Document object and \
+      and a List of Pairs (Tuple[int, int]) representing the measure fragment indexes of the concatenated document.
+
+    Examples:
+        >>> import kernpy as kp
+        >>> contents = ['**kern\n4e\n4f\n4g\n*-\n', '4a\n4b\n4c\n*-\n=\n', '4d\n4e\n4f\n*-\n']
+        >>> document, indexes = kp.concat(contents)
+        >>> indexes
+        [(0, 3), (3, 6), (6, 9)]
+        >>> document, indexes = kp.concat(contents, separator='\n')
+        >>> indexes
+        [(0, 3), (3, 6), (6, 9)]
+        >>> document, indexes = kp.concat(contents, separator='')
+        >>> indexes
+        [(0, 3), (3, 6), (6, 9)]
+        >>> for start, end in indexes:
+        >>>     print(kp.dumps(document, from_measure=start, to_measure=end)))
+    """
+    return generic.Generic.concat(
+        contents=contents,
+        separator=separator,
+    )
+
+
+def merge(
+        contents: List[str],
+        *,
+        raise_on_errors: Optional[bool] = False,
+) -> Tuple[Document, List[Tuple[int, int]]]:
+    """
+    Merge multiple **kern fragments into a single **kern string. \
+     All the fragments should be presented in order. Each fragment does not need to be a complete **kern file. \
+
+    Warnings:
+        Processing a large number of files in a row may take some time.
+         This method performs as many `kp.read` operations as there are fragments to concatenate.
+    Args:
+        contents (Sequence[str]): List of **kern strings
+        raise_on_errors (Optional[bool], optional): If True, raise an exception if any grammar error is detected\
+            during parsing.
+
+    Returns (Tuple[Document, List[Tuple[int, int]]]): Document object and \
+      and a List of Pairs (Tuple[int, int]) representing the measure fragment indexes of the concatenated document.
+
+    Examples:
+        >>> import kernpy as kp
+        >>> contents = ['**kern\n4e\n4f\n4g\n*-\n*-', '**kern\n4a\n4b\n4c\n*-\n=\n*-', '**kern\n4d\n4e\n4f\n*-\n*-']
+        >>> document, indexes = kp.concat(contents)
+        >>> indexes
+        [(0, 3), (3, 6), (6, 9)]
+        >>> document, indexes = kp.concat(contents, separator='\n')
+        >>> indexes
+        [(0, 3), (3, 6), (6, 9)]
+        >>> document, indexes = kp.concat(contents, separator='')
+        >>> indexes
+        [(0, 3), (3, 6), (6, 9)]
+        >>> for start, end in indexes:
+        >>>     print(kp.dumps(document, from_measure=start, to_measure=end)))
+    """
+    return generic.Generic.merge(
+        contents=contents,
+        strict=raise_on_errors
+    )
+
+
+def spine_types(
+        document: Document,
+        headers: Optional[Sequence[str]] = None
+) -> List[str]:
+    """
+    Get the spines of a Document object.
+
+    Args:
+        document (Document): Document object to get spines from
+        headers (Optional[Sequence[str]]): List of spine types to get. If None, all spines are returned. Using a \
+         header will return all the spines of that type.
+
+    Returns (List[str]): List of spines
+
+    Examples:
+        >>> import kernpy as kp
+        >>> document, _ = kp.read('path/to/file.krn')
+        >>> kp.spine_types(document)
+        ['**kern', '**kern', '**kern', '**kern', '**root', '**harm']
+        >>> kp.spine_types(document, None)
+        ['**kern', '**kern', '**kern', '**kern', '**root', '**harm']
+        >>> kp.spine_types(document, headers=None)
+        ['**kern', '**kern', '**kern', '**kern', '**root', '**harm']
+        >>> kp.spine_types(document, headers=['**kern'])
+        ['**kern', '**kern', '**kern', '**kern']
+        >>> kp.spine_types(document, headers=['**kern', '**root'])
+        ['**kern', '**kern', '**kern', '**kern', '**root']
+        >>> kp.spine_types(document, headers=['**kern', '**root', '**harm'])
+        ['**kern', '**kern', '**kern', '**kern', '**root', '**harm']
+        >>> kp.spine_types(document, headers=[])
+        []
+    """
+    return generic.Generic.get_spine_types(
+        document=document,
+        spine_types=headers
+    )
+
+
+
+

kernpy/polish_scores/__init__.py

@@ -0,0 +1,13 @@
+"""
+polish_scores
+
+====
+
+This module provides a way to download and process the Polish Scores dataset.
+"""
+
+from .download_polish_dataset import (
+    convert_and_download_file,
+    main as download_polish_scores,
+)
+