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

kernpy/__init__.py

@@ -0,0 +1,215 @@
+"""
+# kernpy
+
+=====
+
+
+Python Humdrum kern and mens utilities package.
+
+
+
+Execute the following command to run **kernpy** as a module:
+```shell
+python -m kernpy --help
+python -m kernpy <command> <options>
+```
+
+Run `kernpy` from your script:
+```python
+import kernpy
+
+help(kernpy)
+```
+
+While the package is not published in `pip`, the `kernpy` module must be in the root directory.
+
+## 🎯 **kern2ekern**: Convertir un solo archivo .krn a .ekern:
+
+```bash
+python -m kernpy --kern2ekern --input_path <input_file>	 <v | --verbose [0-2]>
+```
+
+The command has the following arguments:
+* **input_path**: Ruta del archivo .krn a convertir.
+* **output_path**: Ruta del archivo .ekern a generar (opcional). Si no se especifica, se generará en la misma ubicación.
+* **-r**: Recursivo (opcional).
+* **--verbose[0-2]**: Nivel de verbosidad (opcional).
+
+
+📌 Basic usage running **kernpy** as a module:
+```shell
+python -m kernpy --input_path /my/path/to/file.krn # New ekern generated in /my/path/to/file.ekern
+```
+
+📌 Generate an _ekrn_ file in specific location running **kernpy** as a module:
+```shell
+python -m kernpy --input_path /my/path/to/file.krn --output_path /new/output.ekern
+```
+
+📌 Converting all the .krn files in a directory to .ekern files running **kernpy** as a module:
+* Every .krn file in the directory will be converted to .ekern in the same location.
+* Using, at least, one additional directory level is required.
+```
+root
+├─ kern-folder
+│   ├── 1.krn
+│   ├── 2.krn
+│   └── 3.krn
+├── more-kerns
+│   ├── 1.krn
+│   ├── ...
+```
+Run:
+```shell
+python -m kernpy --input_path /my/path/to/directory/ -r
+```
+
+✏️ This function is also available as a python function:
+```python
+# converter.py
+from kernpy import kern_to_ekern
+
+kern_to_ekern('/my/path/to/input.krn', '/to/my/output.ekrn')
+
+# Many files
+files = ['file1.krn', 'file2.krn', 'file3.krn']
+[kern_to_ekern(f) for f in files]
+
+# This function raises an exception if the conversion fails.
+# Handle the errors using try-except statement if many files are going to be converted in series.
+```
+
+****************************************************************************************
+## 🎯 **ekern2kern**: Convertir un solo archivo .ekern a .krn:
+
+```bash
+python -m kernpy --ekern2kern --input_path <input_file>	 <--verbose [0-2]>
+```
+
+The command has the following arguments:
+* **input_path**: Ruta del archivo .ekern a convertir.
+* **output_path**: Ruta del archivo .krn a generar (opcional). Si no se especifica, se generará en la misma ubicación.
+* **-r**: Recursivo (opcional).
+* **--verbose[0-2]**: Nivel de verbosidad (opcional).
+
+* Basic usage running **kernpy** as a module:
+```shell
+python -m kernpy --input_path /my/path/to/file.ekern # New krn generated in /my/path/to/file.krn
+```
+
+📌 Generate a _krn_ file in specific location running **kernpy** as a module:
+```shell
+python -m kernpy --input_path /my/path/to/file.ekern --output_path /new/output.krn
+```
+
+📌 Converting **all** the .ekern files in a directory to .krn files running **kernpy** as a module:
+
+* Every .ekrn file in the directory will be converted to .krn in the same location.
+* Using, at least, one additional directory level is required.
+```
+root
+├─ ekern-folder
+│   ├── 1.ekrn
+│   ├── 2.ekrn
+│   └── 3.ekrn
+├── more-ekerns
+│   ├── 1.ekrn
+│   ├── ...
+```
+Run:
+```shell
+python -m kernpy --input_path /my/path/to/directory/ -r
+```
+
+✏️ This function is also available as a python function:
+```python
+# converter.py
+from kernpy import ekern_to_krn
+
+# Only one file
+ekern_to_krn('/my/path/to/input.ekrn', '/to/my/output.krn')
+
+# Many files
+files = ['file1.ekrn', 'file2.ekrn', 'file3.ekrn']
+[ekern_to_krn(f) for f in files]
+
+# This function raises an exception if the conversion fails.
+# Handle the errors using try-except statement if many files are going to be converted in series.
+```
+
+
+****************************************************************************************
+## 🎯 **create fragments**
+Generate new valid _kern_ files from an original _kern_ file. Every new fragment will be a subset of the original file.
+
+Explore the documentation website for more information about the parameters.
+
+
+Use:
+- **create_fragments_from_kern** to generate using always the same measure length.
+- **create_fragments_from_directory** to generate using a Gaussian distribution for the measure length. Static measure is also available if the standard deviation is set to 0.
+
+
+📌 Create new scores from one original _kern_ directory running **kernpy** as a module:
+```shell
+python -m kernpy --generate_fragments --input_directory /from/my/kerns --output_directory /to/my/fragments --log_file log.csv  --verbose 2 --mean 4.2 --std_dev 1.5 --offset 1 --num_processes 12
+```
+
+
+✏️ Create new scores from one original _kern_ file:
+```python
+# generator.py
+from kernpy import create_fragments_from_kern
+
+# View docs:
+help(create_fragments_from_kern)
+
+create_fragments_from_kern('/my/path/to/input.krn', '/to/my/output_dir/',
+                           measure_length=4, offset=1,
+                           log_file='/dev/null')
+```
+
+✏️ Create new scores from one original _kern_ directory:
+- Using, at least, one additional directory level is required.
+```
+root
+├─ kern-folder
+│   ├── 1.krn
+│   ├── 2.krn
+│   └── 3.krn
+├── more-kerns
+│   ├── 1.krn
+│   ├── ...
+```
+
+Run:
+```python
+# generator.py
+from kernpy import create_fragments_from_directory
+
+# View docs:
+help(create_fragments_from_directory)
+
+create_fragments_from_directory('/my/path/to/input_dir/', '/to/my/output_dir/',
+                                mean=4.1, std_dev=0.2, offset=2,
+                                log_file='/logs/fragments.csv',
+                                num_processes=12)
+```
+
+
+
+"""
+
+
+from .core import *
+
+from .io import *
+
+from .util import *
+
+from .polish_scores import *
+
+
+
+
+

kernpy/__main__.py

@@ -0,0 +1,217 @@
+"""
+This module contains the main function for the kernpy package.
+
+Use the following command to run `kernpy` as a module:
+```bash
+python -m kernpy
+```
+
+"""
+
+import argparse
+import sys
+import os
+
+from kernpy import polish_scores, ekern_to_krn, kern_to_ekern, create_fragments_from_directory
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """
+    Create a parser for the command line arguments.
+
+    Examples:
+        >>> parser = create_parser()
+        >>> args = parser.parse_args()
+        >>> print(args.verbose)
+
+
+    Returns:
+        argparse.ArgumentParser: The parser object
+    """
+    parser = argparse.ArgumentParser(description="kernpy")
+
+    parser.add_argument('--verbose', default=1, help='Enable verbose mode')
+
+
+    # ekern to kern
+    kern_parser = parser.add_argument_group('Kern Parser options')
+    kern_parser.add_argument('--ekern2kern', action='store_true', help='Convert file from ekern to kern. [-r]')
+    kern_parser.add_argument('--kern2ekern', action='store_true', help='Convert file from kern to ekern. [-r]')
+
+    if '--ekern2kern' in sys.argv:
+        kern_parser.add_argument('--input_path', required=True, type=str,
+                                 help='Input file or directory path. Employ -r to use recursive mode')
+        kern_parser.add_argument('--output_path', required=False, type=str, help='Output file or directory path')
+        kern_parser.add_argument('-r', '--recursive', required=False, action='store_true', help='Recursive mode')
+
+    if '--kern2ekern' in sys.argv:
+        kern_parser.add_argument('--input_path', required=True, type=str,
+                                 help='Input file or directory path. Employ -r to use recursive mode')
+        kern_parser.add_argument('--output_path', required=False, type=str, help='Output file or directory path')
+        kern_parser.add_argument('-r', '--recursive', required=False, action='store_true', help='Recursive mode')
+
+    # Polish operations
+    # Create a group for optional arguments
+    polish_args = parser.add_argument_group('Polish Exporter options')
+    polish_args.add_argument('--polish', action='store_true', help='Enable Polish Exporter')
+    # Add the required flags, but only if --polish exists
+    if '--polish' in sys.argv:
+        polish_args.add_argument('--input_directory', required=True, type=str, help='Input directory path')
+        polish_args.add_argument('--output_directory', required=True, type=str, help='Output directory path')
+        polish_args.add_argument('--instrument', required=False, type=str, help='Instrument name')
+        polish_args.add_argument('--kern_type', required=False, type=str, help='Kern type: "krn" or "ekrn"')
+        polish_args.add_argument('--kern_spines_filter', required=False, type=str, help='How many kern spines scores will be exported. A number greater than 0', default=None)
+        polish_args.add_argument('--remove_empty_dirs', required=False, action='store_true', help='Remove empty directories after exporting the scores', default=True)
+
+    # Generate fragments
+    # Create a group for optional arguments
+    generate_fragments = parser.add_argument_group('Generate Fragments options')
+    generate_fragments.add_argument('--generate_fragments', action='store_true', help='Enable Generate Fragments')
+    if '--generate_fragments' in sys.argv:
+        generate_fragments.add_argument('--input_directory', required=True, type=str, help='Input directory path')
+        generate_fragments.add_argument('--output_directory', required=True, type=str, help='Output directory path')
+        generate_fragments.add_argument('--log_file', required=True, type=str, help='Log file path')
+        generate_fragments.add_argument('--check_file_extension', required=False, action='store_true', help='Check file extension', default=True)
+        generate_fragments.add_argument('--offset', required=True, type=int, help='Offset', default=1)
+        generate_fragments.add_argument('--num_processes', required=True, type=int, help='Number of processes')
+        generate_fragments.add_argument('--mean', required=True, type=float, help='Mean')
+        generate_fragments.add_argument('--std_dev', required=True, type=float, help='Standard deviation')
+
+    return parser
+
+
+def handle_polish_exporter(args) -> None:
+    """
+    Handle the Polish options.
+
+    Args:
+        args: The parsed arguments
+
+    Returns:
+        None
+    """
+    # TODO: Add instrument argument to download_polish_dataset.main
+    if args.instrument:
+        print("Instrument:", args.instrument)
+    else:
+        print("Instrument: Not specified")
+
+    polish_scores.download_polish_dataset.main(
+        input_directory=args.input_directory,
+        output_directory=args.output_directory,
+        kern_spines_filter=args.kern_spines_filter,
+        exporter_kern_type=args.kern_type,
+        remove_empty_directories=args.remove_empty_dirs
+    )
+
+
+def handle_ekern2kern(args) -> None:
+    """
+    Handle the ekern2kern options.
+
+    Args:
+        args: The parsed arguments
+
+    Returns:
+        None
+    """
+    if not args.output_path:
+        args.output_path = args.input_path.replace("ekrn", "krn")
+
+    if not args.recursive:
+        ekern_to_krn(args.input_path, args.output_path)
+        if int(args.verbose) > 0:
+            print(f"New kern generated in {args.output_path}")
+        return
+
+    # Recursive mode
+    for root, dirs, files in os.walk(args.input_path):
+        for directory in dirs:
+            files = os.listdir(os.path.join(root, directory))
+            for filename in files:
+                if filename.endswith(".ekrn"):
+                    if int(args.verbose) > 0:
+                        print("New kern: ", os.path.join(root, directory, filename))
+                    try:
+                        ekern_to_krn(os.path.join(root, directory, filename),
+                                     os.path.join(root, directory, filename.replace(".ekrn", ".krn")))
+                    except Exception as e:
+                        if int(args.verbose) > 0:
+                            print(f"An error occurred converting:{filename}:{e}", file=sys.stderr)
+
+
+def handle_kern2ekern(args) -> None:
+    """
+    Handle the kern2ekern options.
+
+    Args:
+        args: The parsed arguments
+
+    Returns:
+        None
+    """
+    if not args.output_path:
+        args.output_path = args.input_path.replace("krn", "ekrn")
+
+    if not args.recursive:
+        kern_to_ekern(args.input_path, args.output_path)
+        if int(args.verbose) > 0:
+            print(f"New ekern generated in {args.output_path}")
+        return
+
+    # Recursive mode
+    for root, dirs, files in os.walk(args.input_path):
+        for directory in dirs:
+            files = os.listdir(os.path.join(root, directory))
+            for filename in files:
+                if filename.endswith(".krn"):
+                    if int(args.verbose) > 0:
+                        print("New ekern: ", os.path.join(root, directory, filename))
+                    try:
+                        kern_to_ekern(os.path.join(root, directory, filename),
+                                      os.path.join(root, directory, filename.replace(".krn", ".ekrn")))
+                    except Exception as e:
+                        if int(args.verbose) > 0:
+                            print(f"An error occurred converting:{filename}:{e}", file=sys.stderr)
+
+
+def handle_generate_fragments(args) -> None:
+    """
+    Handle the generate_fragments options.
+
+    Args:
+        args: The parsed arguments
+
+    Returns:
+        None
+    """
+    create_fragments_from_directory(args.input_directory, args.output_directory, args.log_file,
+                                    check_file_extension=args.check_file_extension, offset=args.offset,
+                                    verbose=args.verbose, num_processes=args.num_processes, mean=args.mean,
+                                    std_dev=args.std_dev)
+
+
+def main():
+    parser = create_parser()
+    args = parser.parse_args()
+
+    # Accessing the values of the options
+    if int(args.verbose) > 2:
+        print(f"All arguments: \n{50 * '*'}")
+        for key, value in vars(args).items():
+            print(key, value)
+        print(f"{50 * '*'}\n")
+
+    if args.polish:
+        handle_polish_exporter(args)
+    if args.ekern2kern:
+        handle_ekern2kern(args)
+    if args.kern2ekern:
+        handle_kern2ekern(args)
+    if args.generate_fragments:
+        handle_generate_fragments(args)
+
+
+if __name__ == "__main__":
+    main()
+

kernpy/core/__init__.py

@@ -0,0 +1,119 @@
+"""
+kernpy.core
+
+=====
+
+This module contains the core functionality of the `kernpy` package.
+"""
+
+from .tokens import *
+from .document import *
+from .importer import *
+from .exporter import *
+from .graphviz_exporter import  *
+from .importer_factory import *
+from .dyn_importer import *
+from .dynam_spine_importer import *
+from .fing_spine_importer import *
+from .harm_spine_importer import *
+from .kern_spine_importer import *
+from .mens_spine_importer import *
+from .root_spine_importer import *
+from .text_spine_importer import *
+from .mhxm_spine_importer import *
+from .basic_spine_importer import *
+from .generic import *
+from .tokenizers import *
+from .transposer import *
+from .pitch_models import *
+from .gkern import *
+
+
+__all__ = [
+    'Document',
+    'TokenCategory',
+    'Importer',
+    'ExportOptions',
+    'Exporter',
+    'Encoding',
+    'GraphvizExporter',
+    'ekern_to_krn',
+    'kern_to_ekern',
+    'get_kern_from_ekern',
+    'Encoding',
+    'Tokenizer',
+    'KernTokenizer',
+    'EkernTokenizer',
+    'BekernTokenizer',
+    'BkernTokenizer',
+    'TokenizerFactory',
+    'Token',
+    'KernTokenizer',
+    'BEKERN_CATEGORIES',
+    'DynSpineImporter',
+    'DynamSpineImporter',
+    'FingSpineImporter',
+    'HarmSpineImporter',
+    'KernSpineImporter',
+    'MensSpineImporter',
+    'RootSpineImporter',
+    'TextSpineImporter',
+    'MxhmSpineImporter',
+    'BasicSpineImporter',
+    'SpineOperationToken',
+    'PitchRest',
+    'Duration',
+    'DurationClassical',
+    'DurationMensural',
+    'read',
+    'create',
+    'export',
+    'store',
+    'store_graph',
+    'transposer',
+    'get_spine_types',
+    'createImporter',
+    'TokenCategoryHierarchyMapper',
+    'TOKEN_SEPARATOR',
+    'DECORATION_SEPARATOR',
+    'Subtoken',
+    'AbstractToken',
+    'SimpleToken',
+    'ComplexToken',
+    'CompoundToken',
+    'NoteRestToken',
+    'HeaderToken',
+    'HeaderTokenGenerator',
+    'NotationEncoding',
+    'AgnosticPitch',
+    'PitchExporter',
+    'PitchExporterFactory',
+    'HumdrumPitchExporter',
+    'AmericanPitchExporter',
+    'PitchImporter',
+    'PitchImporterFactory',
+    'HumdrumPitchImporter',
+    'AmericanPitchImporter',
+    'Direction',
+    'Intervals',
+    'IntervalsByName',
+    'transpose',
+    'transpose_agnostics',
+    'transpose_encoding_to_agnostic',
+    'transpose_agnostic_to_encoding',
+    'PositionInStaff',
+    'distance',
+    'agnostic_distance',
+    'PitchPositionReferenceSystem',
+    'Clef',
+    'GClef',
+    'F3Clef',
+    'F4Clef',
+    'C1Clef',
+    'C2Clef',
+    'C3Clef',
+    'C4Clef',
+    'ClefFactory',
+    'AVAILABLE_INTERVALS'
+]
+

kernpy/core/_io.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional, Union
+
+
+def _write(path: Union[str, Path], content: str) -> None:
+    """
+    Store content in a file.
+
+    Args:
+        path (str): Path to the file.
+        content (str): Content to be stored in the file.
+
+    Returns: None
+
+    """
+    if not os.path.exists(os.path.dirname(Path(path).absolute())):
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+
+    with open(path, 'w+') as f:
+        f.write(content)
+
+
+def find_all_files(
+        path: Path,
+        extension: Optional[str] = None) -> list:
+    """
+    Find all files with the given extension in the given directory.
+    Args:
+        path (str): Path to the directory where the files are located.
+        extension (Optional[str]): Extension of the files to be found. If None, all files are returned.
+
+    Returns (List[str]): List of paths to the found files.
+
+    Examples:
+        >>> find_all_files('/kern_files', 'krn')
+        ...
+
+        >>> find_all_files('/files' )
+        ...
+    """
+    p = Path(path)
+    if extension is None:
+        return list(p.glob('**/*'))
+    else:
+        return list(p.glob(f'**/*.{extension}'))

kernpy/core/base_antlr_importer.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from antlr4 import CommonTokenStream, ParseTreeWalker
+from antlr4.InputStream import InputStream
+
+
+class BaseANTLRImporter(ABC):
+    def __init__(self, input_string):
+        char_stream = InputStream(input_string)
+        self.lexer = self.createLexer(char_stream)
+        token_stream = CommonTokenStream(self.lexer)
+        self.parser = self.createParser(token_stream)
+
+    @abstractmethod
+    def createLexer(self, charStream):
+        pass
+
+    @abstractmethod
+    def createParser(self, tokenStream):
+        pass
+
+    @abstractmethod
+    def startRule(self):
+        pass
+
+
+class BaseANTLRListenerImporter(BaseANTLRImporter):
+    def __init__(self, input_string):
+        super().__init__(input_string)
+        self.listener = self.createListener()
+
+    def start(self):
+        tree = self.startRule()
+        walker = ParseTreeWalker()
+        walker.walk(self.listener, tree)
+        #ParseTreeWalker.DEFAULT.walk(walker, tree)
+
+    @abstractmethod
+    def createListener(self):
+        pass
+
+
+class BaseANTLRVisitorImporter(BaseANTLRImporter):
+    def __init__(self, input):
+        super().__init__(input)
+        self.visitor = self.createVisitor()
+
+    def start(self):
+        tree_context = self.startRule()
+        self.visitStart(tree_context)
+
+    @abstractmethod
+    def createVisitor(self):
+        pass
+
+    @abstractmethod
+    def visitStart(self, start_context):
+        pass
+