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

kernpy/__init__.py

@@ -4,7 +4,7 @@
 =====
 
 
-Python Humdrum kern and mens utilities package.
+Python Humdrum **kern and **mens utilities package.
 
 
 
@@ -13,191 +13,6 @@ Execute the following command to run **kernpy** as a module:
 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)
-```
-
-
-
 """
 
 

kernpy/__main__.py

@@ -1,217 +1,127 @@
 """
 This module contains the main function for the kernpy package.
 
-Use the following command to run `kernpy` as a module:
-```bash
-python -m kernpy
-```
-
+Usage:
+    python -m kernpy
 """
 
 import argparse
 import sys
-import os
+from pathlib import Path
 
-from kernpy import polish_scores, ekern_to_krn, kern_to_ekern, create_fragments_from_directory
+from kernpy import polish_scores, ekern_to_krn, kern_to_ekern
 
 
 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')
+    parser = argparse.ArgumentParser(description="kernpy CLI tool")
 
-    return parser
+    parser.add_argument('--verbose', type=int, default=1, help='Verbosity level')
 
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument('--ekern2kern', action='store_true', help='Convert files from ekern to kern')
+    group.add_argument('--kern2ekern', action='store_true', help='Convert files from kern to ekern')
+    group.add_argument('--polish', action='store_true', help='Run Polish Exporter')
+    group.add_argument('--generate_fragments', action='store_true', help='Generate Fragments')
 
-def handle_polish_exporter(args) -> None:
-    """
-    Handle the Polish options.
+    parser.add_argument('--input_path', type=str, help='Input file or directory')
+    parser.add_argument('--output_path', type=str, help='Output file or directory')
+    parser.add_argument('-r', '--recursive', action='store_true', help='Enable recursive directory processing')
 
-    Args:
-        args: The parsed arguments
+    # Polish Exporter
+    parser.add_argument('--input_directory', type=str, help='Polish: Input directory')
+    parser.add_argument('--output_directory', type=str, help='Polish: Output directory')
+    parser.add_argument('--instrument', type=str, help='Polish: Instrument name')
+    parser.add_argument('--kern_type', type=str, help='Polish: "krn" or "ekrn"')
+    parser.add_argument('--kern_spines_filter', type=str, help='Polish: Filter for number of kern spines')
+    parser.add_argument('--remove_empty_dirs', action='store_true', help='Polish: Remove empty directories')
 
-    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
-    )
+    return parser
 
 
-def handle_ekern2kern(args) -> None:
-    """
-    Handle the ekern2kern options.
+def find_files(directory: Path, patterns: list[str], recursive: bool = False) -> list[Path]:
+    files = []
+    for pattern in patterns:
+        if recursive:
+            files.extend(directory.rglob(pattern))
+        else:
+            files.extend(directory.glob(pattern))
+    return files
 
-    Args:
-        args: The parsed arguments
 
-    Returns:
-        None
-    """
-    if not args.output_path:
-        args.output_path = args.input_path.replace("ekrn", "krn")
+def handle_ekern2kern(args):
+    input_path = Path(args.input_path)
+    output_path = Path(args.output_path) if args.output_path else None
 
-    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}")
+    if input_path.is_file():
+        out = output_path or input_path.with_suffix(".krn")
+        ekern_to_krn(str(input_path), str(out))
+        if args.verbose:
+            print(f"Converted: {input_path} → {out}")
         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}")
+    files = find_files(input_path, ["*.ekrn", "*.ekern"], recursive=args.recursive)
+    for file in files:
+        out = file.with_suffix(".krn")
+        try:
+            ekern_to_krn(str(file), str(out))
+            if args.verbose:
+                print(f"Converted: {file} → {out}")
+        except Exception as e:
+            print(f"Error converting {file}: {e}", file=sys.stderr)
+
+
+def handle_kern2ekern(args):
+    input_path = Path(args.input_path)
+    output_path = Path(args.output_path) if args.output_path else None
+
+    if input_path.is_file():
+        out = output_path or input_path.with_suffix(".ekrn")
+        kern_to_ekern(str(input_path), str(out))
+        if args.verbose:
+            print(f"Converted: {input_path} → {out}")
         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)
+    files = find_files(input_path, ["*.krn", "*.kern"], recursive=args.recursive)
+    for file in files:
+        out = file.with_suffix(".ekrn")
+        try:
+            kern_to_ekern(str(file), str(out))
+            if args.verbose:
+                print(f"Converted: {file} → {out}")
+        except Exception as e:
+            print(f"Error converting {file}: {e}", file=sys.stderr)
+
+
+def handle_polish_exporter(args):
+    if args.verbose:
+        print(f"Running Polish Exporter on {args.input_directory} → {args.output_directory}")
+
+    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 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.verbose > 2:
+        print("Arguments:")
+        for key, val in vars(args).items():
+            print(f"  {key}: {val}")
 
-    if args.polish:
-        handle_polish_exporter(args)
     if args.ekern2kern:
         handle_ekern2kern(args)
-    if args.kern2ekern:
+    elif args.kern2ekern:
         handle_kern2ekern(args)
-    if args.generate_fragments:
-        handle_generate_fragments(args)
+    elif args.polish:
+        handle_polish_exporter(args)
 
 
 if __name__ == "__main__":
     main()
-

kernpy/core/exporter.py

@@ -153,7 +153,7 @@ class HeaderTokenGenerator:
     """
     HeaderTokenGenerator class.
 
-    This class is used to translate the HeaderTokens to the specific tokenizer format.
+    This class is used to translate the HeaderTokens to the specific encoding format.
     """
     @classmethod
     def new(cls, *, token: HeaderToken, type: Encoding):
@@ -162,7 +162,7 @@ class HeaderTokenGenerator:
 
         Args:
             token (HeaderToken): The HeaderToken to be translated.
-            type (Encoding): The tokenizer to be used.
+            type (Encoding): The encoding to be used.
 
         Examples:
             >>> header = HeaderToken('**kern', 0)

kernpy/core/tokenizers.py

@@ -18,7 +18,7 @@ class Encoding(Enum):  # TODO: Eventually, polymorphism will be used to export d
         >>> doc, _ = kp.load('path/to/file.krn')
         >>>
         >>> # Save the file using the specified encoding
-        >>> exported_content = kp.dumps(tokenizer=kp.Encoding.normalizedKern)
+        >>> exported_content = kp.dumps(encoding=kp.Encoding.normalizedKern)
     """
     eKern = 'ekern'
     normalizedKern = 'kern'

kernpy/io/public.py

@@ -12,7 +12,9 @@ from kernpy import Encoding
 from kernpy.core import (
     Document, Importer, Exporter, ExportOptions, GraphvizExporter,
     generic,
-    TokenCategoryHierarchyMapper)
+    TokenCategoryHierarchyMapper,
+    TokenCategory,
+)
 
 
 def load(fp: Union[str, Path], *, raise_on_errors: Optional[bool] = False, **kwargs) -> (Document, List[str]):
@@ -84,13 +86,13 @@ def loads(s, *, raise_on_errors: Optional[bool] = False, **kwargs) -> (Document,
 
 
 def dump(document: Document, fp: Union[str, Path], *,
-         spine_types: [] = None,
-         include: [] = None,
-         exclude: [] = None,
+         spine_types: [str] = None,
+         include: [TokenCategory] = None,
+         exclude: [TokenCategory] = None,
          from_measure: int = None,
          to_measure: int = None,
-         tokenizer: Encoding = None,
-         instruments: [] = None,
+         encoding: Encoding = None,
+         instruments: [str] = None,
          show_measure_numbers: bool = None,
          spine_ids: [int] = None
          ) -> None:
@@ -104,7 +106,7 @@ def dump(document: Document, fp: Union[str, Path], *,
         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.
+        encoding (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. \
@@ -130,7 +132,7 @@ def dump(document: Document, fp: Union[str, Path], *,
         exclude=exclude,
         from_measure=from_measure,
         to_measure=to_measure,
-        kern_type=tokenizer,
+        kern_type=encoding,
         instruments=instruments,
         show_measure_numbers=show_measure_numbers,
         spine_ids=spine_ids
@@ -144,13 +146,13 @@ def dump(document: Document, fp: Union[str, Path], *,
 
 
 def dumps(document: Document, *,
-          spine_types: [] = None,
-          include: [] = None,
-          exclude: [] = None,
+          spine_types: [str] = None,
+          include: [TokenCategory] = None,
+          exclude: [TokenCategory] = None,
           from_measure: int = None,
           to_measure: int = None,
-          tokenizer: Encoding = None,
-          instruments: [] = None,
+          encoding: Encoding = None,
+          instruments: [str] = None,
           show_measure_numbers: bool = None,
           spine_ids: [int] = None
           ) -> str:
@@ -164,7 +166,7 @@ def dumps(document: Document, *,
         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.
+        encoding (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. \
@@ -189,7 +191,7 @@ def dumps(document: Document, *,
         exclude=exclude,
         from_measure=from_measure,
         to_measure=to_measure,
-        kern_type=tokenizer,
+        kern_type=encoding,
         instruments=instruments,
         show_measure_numbers=show_measure_numbers,
         spine_ids=spine_ids

{kernpy-1.0.0.dist-info → kernpy-1.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kernpy
-Version: 1.0.0
+Version: 1.0.2
 Summary: Python Humdrum **kern and **mens utilities
 Project-URL: Homepage, https://github.com/OMR-PRAIG-UA-ES/kernpy
 Project-URL: Documentation, https://github.com/OMR-PRAIG-UA-ES/kernpy#readme
@@ -19,9 +19,18 @@ Description-Content-Type: text/markdown
 
 # Python Humdrum **kern and **mens utilities
 
-## Documentation: <a target="_blank" href="https://kernpy.pages.dev/">https://kernpy.pages.dev/</a>
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg?style=for-the-badge)](https://www.gnu.org/licenses/agpl-3.0)
+![Python Version](https://img.shields.io/badge/Python-3.9+-3776AB?logo=python&logoColor=white&style=for-the-badge)
+[![PyPI](https://img.shields.io/pypi/v/kernpy?color=brightgreen&label=PyPI&style=for-the-badge&logo=pypi)](https://pypi.org/project/kernpy/)
+[![Docs](https://img.shields.io/badge/docs-available-blue?style=for-the-badge&logo=readthedocs)](https://kernpy.pages.dev)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen?style=for-the-badge&logo=pytest)](https://github.com/kernpy/kernpy/actions)
+[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-orange?style=for-the-badge&logo=github)](CONTRIBUTING.md)
 
-![kernpy logo](https://static.wixstatic.com/media/7a8a67_90be144dbf384480908c3327b93ba97a~mv2.jpg/v1/fill/w_461,h_354,fp_0.46_0.20,q_80,usm_0.66_1.00_0.01,enc_avif,quality_auto/mending-the-sail-1896_jpg!Large.jpg)
+
+Python package that provides comprehensive tools for working with symbolic modern and mensural notations in Humdrum format. kernpy is a fully open-source project open to contributions.
+
+## Documentation 
+Visit the online website: <a target="_blank" href="https://kernpy.pages.dev/">https://kernpy.pages.dev/</a>
 
 ## Index:
 - [Code examples](#code-examples)
@@ -71,18 +80,74 @@ Only use the specified spines in `spine_types`.
 ```python
 import kernpy as kp
 
+# only export the **kern spines
 kp.dump(document, "newfile_core.krn",
         spine_types=['**kern'])
+
+# only export the **text spines
 kp.dump(document, "newfile_lyrics.krn",
         spine_types=['**text])
+                     
+# only export **kern and **text spines     
 kp.dump(document, "newfile_core_and_lyrics.krn",
         spine_types=['*+text'])
 ```
 
+- The categories are hierarchically defined in the `TokenCategory` class.
+See the hierarchy as a tree
+```python
+import kernpy as kp
+
+
+print(kp.TokenCategory.tree())
+```
+Tree:
+```txt
+.
+├── STRUCTURAL
+│   ├── HEADER
+│   └── SPINE_OPERATION
+├── CORE
+│   ├── NOTE_REST
+│   │   ├── DURATION
+│   │   ├── NOTE
+│   │   │   ├── PITCH
+│   │   │   ├── DECORATION
+│   │   │   └── ALTERATION
+│   │   └── REST
+│   ├── CHORD
+│   ├── EMPTY
+│   └── ERROR
+├── SIGNATURES
+│   ├── CLEF
+│   ├── TIME_SIGNATURE
+│   ├── METER_SYMBOL
+│   ├── KEY_SIGNATURE
+│   └── KEY_TOKEN
+├── ENGRAVED_SYMBOLS
+├── OTHER_CONTEXTUAL
+├── BARLINES
+├── COMMENTS
+│   ├── FIELD_COMMENTS
+│   └── LINE_COMMENTS
+├── DYNAMICS
+├── HARMONY
+├── FINGERING
+├── LYRICS
+├── INSTRUMENTS
+├── IMAGE_ANNOTATIONS
+│   ├── BOUNDING_BOXES
+│   └── LINE_BREAK
+├── OTHER
+├── MHXM
+└── ROOT
+```
+
 - Use `include` for selecting the **kern semantic categories **to use**. The output only contains what is passed. By default, all the categories are included.
 ```python
 import kernpy as kp
 
+
 kp.dump(document, "newfile_only_clefs.krn",
         include={kp.TokenCategory.CLEF})
 kp.dump(document, "newfile_only_durations_and_bounding_boxes.krn",
@@ -104,34 +169,37 @@ import kernpy as kp
 kp.dump(document, "newfile_custom.krn",
         include=kp.BEKERN_CATEGORIES,  # Preloaded set of simple categories
         exclude={kp.TokenCategory.PITCH})
+
+# Inspect the BEKERN preloaded categories
+print(kp.BEKERN_CATEGORIES)
 ```
 
-- Use `tokenizer` to select how the categories are split. By default, the `normalizedKern` tokenizer is used.
+- Use `encoding` to select how the categories are split. By default, the `normalizedKern` encoding is used.
 
 ```python
 import kernpy as kp
 
 kp.dump(document, "newfile_normalized.krn",
-        tokenizer=kp.Encoding.normalizedKern)  # Default tokenizer
+        encoding=kp.Encoding.normalizedKern)  # Default encoding
 ```
-Select the proper Humdrum **kern tokenizer:
+Select the proper Humdrum **kern encoding:
 
-`kernpy` provides different tokenizers to export the content each symbol in different formats.
+`kernpy` provides different encodings to export the content each symbol in different formats.
 
-| Encoding | Tokenized    | Description                            |
+| Encoding | Output       | Description                            |
 |----------|--------------|----------------------------------------|
 | kern     | 2.bb-_L      | Traditional Humdrum **kern encoding    |
 | ekern    | 2@.@bb@-·_·L | Extended Humdrum **kern encoding       |
 
-Use the `Encoding` enum class to select the tokenizer:
+Use the `Encoding` enum class to select the encoding:
 
 ```python
 import kernpy as kp
 
 doc, _ = kp.load('resource_dir/legacy/chor048.krn')
 
-kern_content = kp.dumps(doc, tokenizer=kp.Encoding.normalizedKern)
-ekern_content = kp.dumps(doc, tokenizer=kp.Encoding.eKern)
+kern_content = kp.dumps(doc, encoding=kp.Encoding.normalizedKern)
+ekern_content = kp.dumps(doc, encoding=kp.Encoding.eKern)
 ```
 
 - Use `from_measure` and `to_measure` to select the measures to export. By default, all the measures are exported.
@@ -168,7 +236,7 @@ kp.dump(document, "newfile.krn",
         spine_types=['**kern'],  # Export only the **kern spines
         include=kp.BEKERN_CATEGORIES,  # Token categories to include
         exclude={kp.TokenCategory.PITCH},  # Token categories to exclude
-        tokenizer=kp.Encoding.eKern,  # Kern encoding
+        encoding=kp.Encoding.eKern,  # Kern encoding
         from_measure=1,  # First from measure 1
         to_measure=10,  # Last measure exported
         spine_ids=[0, 1],  # Export only the first and the second spine
@@ -271,7 +339,7 @@ for page_label, bounding_box_measure in doc.page_bounding_boxes.items():
    kp.dump(doc, f"foo_{page_label}.ekrn",
            spine_types=['**kern'],
            token_categories=kp.BEKERN_CATEGORIES,
-           tokenizer=kp.Encoding.eKern,
+           encoding=kp.Encoding.eKern,
            from_measure=bounding_box_measure.from_measure,
            to_measure=bounding_box_measure.to_measure - 1  # TODO: Check bounds            
            )
@@ -382,8 +450,10 @@ kp.graph(document, '/tmp/graph.dot')
 ### Production version:
 Just install the last version of **kernpy** using pip:
 ```shell
-pip3 uninstall kernpy     # Uninstall the previous version before installing the new one
-pip3 install git+https://github.com/OMR-PRAIG-UA-ES/kernpy.git
+pip3 install kernpy
+
+# ensure you have the latest version
+pip3 install kernpy --upgrade 
 ```
 
 > [!NOTE]
@@ -391,55 +461,6 @@ pip3 install git+https://github.com/OMR-PRAIG-UA-ES/kernpy.git
 
 <hr>
 
-### Development version:
-
-> [!IMPORTANT]  
-> - Add the development dependencies to the `requirements.txt` file.
-> - Add the production dependencies to the `pyproject.toml` file.
-> - After every change in the grammar, the next steps are mandatory:
-> - - Run the `antlr4.sh` script (JAVA required).
-> - - Commit & push the changes to the repository.
-
-
-- Generate antrl4 grammar:
-- For generating the Python code required for parsing the **kern files, the shell script `antlr4.sh` inside the `kernpy` package must be run.
-
-```shell
-./antlr4.sh
-```
-
-Install all the dependencies using the `requirements.txt` file:
-```shell
-pip install -r requirements.txt
-```
-
-Otherwise, install the required packages manually:
-
-
-- It requires the `antlr4` package to be installed using:
-```shell
-pip install antlr4-python3-runtime
-```
-
-
-- For visualizing the bounding boxes, the library, the `Pillow` library is required:
-```shell
-pip install Pillow
-```
-
-- To parse a IIIF (International Image Interoperability Framework) manifest in Python, we use the `requests` library to fetch the manifest file:
-```shell
-pip install requests
-```
-
-- If fetching data from `https` fails, install the following version of `urllib`:
-```shell
-pip install urllib3==1.26.6
-```
-
-It has been tested with version 4.13.1 of the package.
-
-
 ## Documentation
 Documentation available at [https://kernpy.pages.dev/](https://kernpy.pages.dev/)
 
@@ -461,32 +482,7 @@ cd tests && python -m pytest
 
 We welcome contributions from the community! If you'd like to contribute to the project, please follow these steps:
 
-1. Fork the Repository from GitHub.
-2. Clone your own fork repository.
-   ```bash
-   git clone ...
-   cd ...
-   ```
-3. Create a Branch:
-4. Create a new branch for your feature or bug fix:
-   ```bash
-   git checkout -b feature/your-feature-name
-    ```
-5. Commit Your Changes:
-Commit your changes with a descriptive message:
-    ```bash
-    git commit -m "feat: add your feature or fix"
-     ```
-
-6. Push to Your Branch:
-Push your changes to your forked repository:
-    ```bash
-    git push origin feature/your-feature-name
-     ```
-
-7. Create a Pull Request:
-Open a pull request to the main repository, describing your changes.
-
+Go to the file [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to contribute.
 
 ## Citation:
 ```bibtex

{kernpy-1.0.0.dist-info → kernpy-1.0.2.dist-info}/RECORD

@@ -1,5 +1,5 @@
-kernpy/__init__.py,sha256=h1o3Z_Xk7nZdE4fBu7uLx6V6nR4M3LySi36ONj73sOo,5998
-kernpy/__main__.py,sha256=ayuovsnyTaTrhcyOM1kFBoSXGjT1QALwIMcJ_NOqVkM,8495
+kernpy/__init__.py,sha256=HdHS0T3se8qIU0d2mULhwhgJRfgGmNA4Zhxl4YvjeVA,313
+kernpy/__main__.py,sha256=ZxsPlyfgzpZjU8TdNBc1SrMyTTr-Osu4j08DXHAgpVQ,4437
 kernpy/test_grammar.sh,sha256=MP9Hav9nPxTbHeofFEuunwDsLcBoeFRtzPp4bbPnqBU,520
 kernpy/visualize_analysis.sh,sha256=z68jyZ8zj4w7v5CoC8-J7PGh7dYA_iQbuFL5T63X6qY,526
 kernpy/core/__init__.py,sha256=gIbOKMWcPcQc4c6QpslWnAw9XkcMJ6OvedHANyDABbs,2581
@@ -11,7 +11,7 @@ kernpy/core/document.py,sha256=Y_Wpwc-t1GkaGr2QVU0hqLRFJv9wJ_Nm6UitgwAlT8w,34892
 kernpy/core/dyn_importer.py,sha256=dKgZqVIdEELUu8HY63ClLJAMQXXItjHmaYxxOwFZRiY,1025
 kernpy/core/dynam_spine_importer.py,sha256=crg4LwsWr56VZ6GLYAO1CDnLuum9f1tlX_pXCqKemEc,1450
 kernpy/core/error_listener.py,sha256=bTlAZvVIQx_6BLZ3oRut_pn24JnV8_7GnNONiwoMMPU,1516
-kernpy/core/exporter.py,sha256=5MWOk1JmPtpXfjN_VBv5jxUhYu8hhAZwt9eB5u9f1eM,21371
+kernpy/core/exporter.py,sha256=t2Ep-qe_r1CvEmPb3KoMpzHd2W3SfEcjY8XhFOUqGxs,21369
 kernpy/core/fing_spine_importer.py,sha256=5GLPPakmZVRcNbbaoCn1p1cQdat5QttflbpKu3AytQU,1382
 kernpy/core/generic.py,sha256=9OTDE2t49laVk6fgtydK5yZh7SCfZwViP_dZUJlskA8,10967
 kernpy/core/gkern.py,sha256=nRYFLFJ0uOLJwio0DKxQ0YIqLixy6-qCM-eY8DNdxfM,16332
@@ -27,7 +27,7 @@ kernpy/core/pitch_models.py,sha256=TpSt1uxGYhbhXs0viB1dNo4jiGxyCOHWseyRHTpfH-0,9
 kernpy/core/root_spine_importer.py,sha256=w7oFbMeXakHF9OAlgKWm_HaGJoNq6u7BE_JUnvLiLnU,1893
 kernpy/core/spine_importer.py,sha256=_VoWcVGfDMhxDn-hCu18g_29Aw2c2bjLnaXuvW2Fbsc,1430
 kernpy/core/text_spine_importer.py,sha256=mz1qX2nviJs0VsGsN87jk6BVWCIE7mmB9IxEx4RdhT8,1522
-kernpy/core/tokenizers.py,sha256=dJsaCdPStruzToaYA-RyM9beJ9tQyZRjM4qKLK0d0k4,7899
+kernpy/core/tokenizers.py,sha256=-m-isPSvWbikTLj5pfzG-4UCLrjxPfqHJD7s4znLHCo,7898
 kernpy/core/tokens.py,sha256=0XhbYm6F9NDfYpP5gbrgzZL3qB_xWs74faTwAZghpyM,66515
 kernpy/core/transposer.py,sha256=EqsEy7Z3bWIXdxUTruBrg8z9sWdJ3Cd_KIzo_6ZuNNA,9352
 kernpy/core/generated/kernSpineLexer.interp,sha256=Y3_seqmHQu3czO9fHE8XtRwTrk8g4Txf0IKiMaHBqeg,28801
@@ -39,13 +39,13 @@ kernpy/core/generated/kernSpineParser.tokens,sha256=ciGB91o4t7VM-tgSLtGB-BUFzHNo
 kernpy/core/generated/kernSpineParserListener.py,sha256=fcOPxYkGbNbIw8Qk9aqYXnuTB48WWJCn_ZYxTdoFtpY,40015
 kernpy/core/generated/kernSpineParserVisitor.py,sha256=YSEdcb4kuIi-E4rAFhDKsCVu0lyPdlqrCMtQAeVDhZY,23821
 kernpy/io/__init__.py,sha256=9103cE_Ao1tu2mi4EaFni-YmnCnwtJqQqFqgeFuT7rA,147
-kernpy/io/public.py,sha256=p5f22Vse54vU3QYDBn5Z5iJXhRLrF9OTG1MYD8QhdGc,13782
+kernpy/io/public.py,sha256=ge7A2N77efVG5dMpLDH2jxtkVi_2EOq-TnhDggyg9vQ,13861
 kernpy/polish_scores/__init__.py,sha256=EjILt5N5T9cKKdhWwflS_MU4TXuLhdHOYhW8txaicrI,217
 kernpy/polish_scores/download_polish_dataset.py,sha256=VqACpxDiM1yQYDs4QHHlZ87ZW2gkjl6R_bxYh5E67K4,14633
 kernpy/polish_scores/iiif.py,sha256=yITdrQbMsGmm8qag8TSousjCjS2io148Jk9xwEKa3B4,1526
 kernpy/util/__init__.py,sha256=dfW3nRSMkGQS7p7YebM271_0H8_pVw4IiDKeINs_LI8,152
 kernpy/util/helpers.py,sha256=Xbj3nWNyErdOpLHYd4uVyfwleXvmC5_FlYEhxaeTtS8,1549
 kernpy/util/store_cache.py,sha256=AA7SFCGQ6ryy-c02wbLy8gIQ2C-VdM1JSWFoWIK_KLA,1186
-kernpy-1.0.0.dist-info/METADATA,sha256=D2maG9kcRvqxzIO02G6gjx4IecAZtUlfZDoT58rQJOo,14888
-kernpy-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kernpy-1.0.0.dist-info/RECORD,,
+kernpy-1.0.2.dist-info/METADATA,sha256=Uj7S-i6JIAMSEA4eyc-PTACGQX-hch51Ze2fnOJH1C4,15085
+kernpy-1.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kernpy-1.0.2.dist-info/RECORD,,