pyrekordbox 0.4.1__tar.gz → 0.4.3__tar.gz

{pyrekordbox-0.4.1 → pyrekordbox-0.4.3}/.github/workflows/tests.yml

@@ -74,7 +74,9 @@ jobs:
         pytest tests/ --cov=pyrekordbox --cov-report=xml -v
 
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
       with:
         env_vars: OS,PYTHON
         verbose: True

{pyrekordbox-0.4.1 → pyrekordbox-0.4.3}/.pre-commit-config.yaml

@@ -13,7 +13,7 @@ repos:
           - id: check-yaml
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.11.4
+      rev: v0.11.9
       hooks:
         # Run the linter.
         - id: ruff

{pyrekordbox-0.4.1 → pyrekordbox-0.4.3}/CHANGELOG.md

@@ -1,5 +1,37 @@
 # What's New
 
+<a name="v0.4.3"></a>
+## [v0.4.3] - 2025-05-14
+
+This release adds type annotations across the codebase and fixes various bugs.
+
+### Improvements/Bug Fixes
+
+- **db:** **add type checks for deleting playlists and playlist songs ([#169](https://github.com/dylanljones/pyrekordbox/issues/169))**  
+  This prevents deleting a content instead of a playlist song by accident.
+- **db:** **fix timezone issue when setting datetimes ([#168](https://github.com/dylanljones/pyrekordbox/issues/168))**  
+  Datetime fields are now set with UTC which is the same format that Rekordbox uses. 
+  Timezone agnostic dates or dates with another timezone are converted accordingly.
+- **xml:** **fix issue with pretty-formatting xml string ([#164](https://github.com/dylanljones/pyrekordbox/issues/164))**  
+  For Python>3.8 the built-in indentation is used, for Python3.8 the XML string is returned unformatted if minidom fails
+- **add type hints across the codebase and use mypy for static type checking**
+
+
+<a name="v0.4.2"></a>
+## [v0.4.2] - 2025-04-21
+
+This release contains bug fixes for the command-line interface and XML handling.
+
+### Improvements/Bug Fixes
+
+- **cli:** **fix import error when downloading db key via CLI ([#162](https://github.com/dylanljones/pyrekordbox/pull/162))**  
+- **xml:** **fix get_track method to accept Location parameter**  
+
+### Documentation
+
+- **anlz:** **add simple tutorial for ANLZ files**  
+- **db:** **add ActiveLoop description**  
+
 
 <a name="v0.4.1"></a>
 ## [v0.4.1] - 2025-04-20
@@ -634,7 +666,9 @@ This release contains documentation fixes.
 - **add missing djmd tables to `master.db` database documentation**
 
 
-[Unreleased]: https://github.com/dylanljones/pyrekordbox/compare/v0.4.1...HEAD
+[Unreleased]: https://github.com/dylanljones/pyrekordbox/compare/v0.4.3...HEAD
+[v0.4.3]: https://github.com/dylanljones/pyrekordbox/compare/v0.4.2...v0.4.3
+[v0.4.2]: https://github.com/dylanljones/pyrekordbox/compare/v0.4.1...v0.4.2
 [v0.4.1]: https://github.com/dylanljones/pyrekordbox/compare/v0.4.0...v0.4.1
 [v0.4.0]: https://github.com/dylanljones/pyrekordbox/compare/v0.3.2...v0.4.0
 [v0.3.2]: https://github.com/dylanljones/pyrekordbox/compare/v0.3.1...v0.3.2

{pyrekordbox-0.4.1/pyrekordbox.egg-info → pyrekordbox-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrekordbox
-Version: 0.4.1
+Version: 0.4.3
 Summary: Inofficial Python package for interacting with the library of Pioneers Rekordbox DJ software.
 Author-email: Dylan Jones <dylanljones94@gmail.com>
 License: MIT License

{pyrekordbox-0.4.1 → pyrekordbox-0.4.3}/docs/source/formats/db6.md

@@ -497,7 +497,7 @@ around 1/75th of a second (13.333ms) per frame, i.e. about half the granularity
      - ?
      -
    * - `ActiveLoop`
-     - ?
+     - Should the loop start active when reaching the point in playback
      -
    * - `Comment`
      - Name of comment of cue point

pyrekordbox-0.4.3/docs/source/tutorial/anlz.md

@@ -0,0 +1,88 @@
+# Analysis Files
+
+Rekordbox stores analysis information of the tracks in the collection in specific files,
+which also get exported to decives used by Pioneer professional DJ equipment. The files
+have names like `ANLZ0000` and come with the extensions `.DAT`, `.EXT` or `.2EX`.
+They include waveforms, beat grids (information about the precise time at which
+each beat occurs), time indices to allow efficient seeking to specific positions
+inside variable bit-rate audio streams, and lists of memory cues and loop points.
+
+```{seealso}
+See the {ref}`Analysis Files Format<Analysis Files Format>` documentation for more information.
+```
+
+## Reading and writing ANLZ Files
+
+To read an ANLZ file, you can use the `AnlzFile.parse_file` method:
+
+```python
+from pyrekordbox import AnlzFile
+
+# Read a single ANLZ file
+anlz = AnlzFile.parse_file("path/to/ANLZXXXX.DAT")
+```
+
+You can also read multiple ANLZ files for a single track using the `read_anlz_files` function.
+It takes the root directory of the files as argument:
+
+```python
+from pyrekordbox import read_anlz_files
+
+# Read all ANLZ files for a track
+files = read_anlz_files("path/to/anlz_directory")
+```
+
+After modifiying the contents of a ANLZ file, it can be saved via
+```python
+# Save the ANLZ file contents
+anlz.save("path/to/ANLZXXXX.DAT")
+```
+
+
+To find the ANLZ files corresponding to a specific track in the Rekordbox collection,
+the database handler includes a method that returnes the directory containing the ANLZ files:
+```python
+>>> from pyrekordbox import Rekordbox6Database
+>>> db = Rekordbox6Database()
+>>> content = db.get_content().first()
+>>> db.get_anlz_dir(content)
+C:\Users\user\AppData\Roaming\Pioneer\rekordbox\share\PIONEER\USBANLZ\0e8\0d4cc-06a6-4574-ba18-1c2301ea9924
+```
+
+Alternatively, a dictionary containing the paths of the ANLZ files can be found via
+```python
+>>> db.get_anlz_paths(content)
+{
+    'DAT': 'C:/Users/user/AppData/Roaming/Pioneer/rekordbox/share/PIONEER/USBANLZ/0e8/0d4cc-06a6-4574-ba18-1c2301ea9924/ANLZ0000.DAT',
+    'EXT': 'C:/Users/user/AppData/Roaming/Pioneer/rekordbox/share/PIONEER/USBANLZ/0e8/0d4cc-06a6-4574-ba18-1c2301ea9924/ANLZ0000.EXT',
+    '2EX': None
+}
+```
+In this example, the analysis data of the track is stored in only two ANLZ files, `ANLZ0000.DAT` and `ANLZ0000.EXT`.
+Instead of returning the paths of the analysis files, they can also be read directly via
+```python
+db.read_anlz_files(content)
+```
+
+
+## Accessing ANLZ Data
+
+The `AnlzFile` object implements a dictionary-like interface. You can access tags by their type code or name:
+
+```python
+# Check if a tag exists
+if "beat_grid" in anlz:
+    print("Beat grid found")
+
+# Get the first tag of a specific type
+beat_grid = anlz.get_tag("PQTZ")
+# or by name
+beat_grid = anlz.get_tag("beat_grid")
+
+# Get all tags of a specific type
+all_cues = anlz.getall_tags("PCOB")
+```
+
+```{note}
+More coming soon!
+```

{pyrekordbox-0.4.1 → pyrekordbox-0.4.3}/docs/source/tutorial/mysetting.md

@@ -13,7 +13,8 @@ DJ equipment.
 See the {ref}`My-Setting Files Format<My-Setting Files Format>` documentation for more information.
 ```
 
-Pyrekordbox includes a file handler for each of the four My-Settings files. To read any of the four files, use
+Pyrekordbox includes a file handler for each of the four My-Settings files.
+To read any of the four files, use
 ````python
 from pyrekordbox import read_mysetting_file
 
@@ -30,6 +31,21 @@ file3 = DjmMySettingFile.parse_file("DJMMYSETTING.DAT")
 file4 = DevSettingFile.parse_file("DEVSETTING.DAT")
 ````
 
+To find the My-Settings files, the database handler includes a method that returnes the
+paths of all four files:
+````python
+>>> from pyrekordbox import Rekordbox6Database
+>>> db = Rekordbox6Database()
+>>> db.get_mysetting_paths()
+[
+    'C:/Users/user/AppData/Roaming/Pioneer/rekordbox/DEVSETTING.DAT',
+    'C:/Users/user/AppData/Roaming/Pioneer/rekordbox/DJMMYSETTING.DAT',
+    'C:/Users/user/AppData/Roaming/Pioneer/rekordbox/MYSETTING.DAT',
+    'C:/Users/user/AppData/Roaming/Pioneer/rekordbox/MYSETTING2.DAT'
+]
+````
+
+
 After parsing a My-Setting file, the settings can be accessed as dictionary:
 ````python
 >>> file = read_mysetting_file("MYSETTING.DAT")

{pyrekordbox-0.4.1 → pyrekordbox-0.4.3}/pyproject.toml

@@ -78,6 +78,9 @@ include = ["pyrekordbox", "pyrekordbox.*"]
 write_to = "pyrekordbox/_version.py"
 git_describe_command = "git describe --dirty --tags --long --match * --first-parent"
 
+[tool.setuptools.package-data]
+pyrekordbox = ["py.typed"]
+
 
 # -- Ruff ------------------------------------------------------------------------------
 
@@ -105,6 +108,7 @@ select = [
     "NPY", # Numpy
     "N", # pep8-naming
     "D", # pydocstyle
+    "ANN", # types-annotations
 ]
 ignore = [
     "E203",  # Whitespace before ':'
@@ -124,12 +128,21 @@ ignore = [
     "N813", # Camelcase imported as lowercase
     #"N815", # Variable in class scope should not be mixedCase
     "N818", # Exception name should be named with an Error suffix
+    "ANN001", # Missing type annotation for obj in method
+    "ANN002", # Missing type annotation for args in method
+    "ANN003", # Missing type annotation for kwargs in method
+    "ANN101", # Missing type annotation for self in method
+    "ANN102", # Missing type annotation for cls in classmethod
+    "ANN204", # Missing return type for __init__
+    "ANN401", # Dynamically typed expressions (typing.Any) are disallowed
 ]
 fixable = ["ALL"]  # Allow fix for all enabled rules (when `--fix`) is provided.
 unfixable = []
 
 [tool.ruff.lint.per-file-ignores]
 "*__init__.py" = ["F401"]
+"*__main__.py" = ["ANN"]
+"tests/*" = ["ANN"]
 "rbxml.py" = ["N803"]
 "tables.py" = ["N802", "N815"]
 
@@ -148,6 +161,36 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 
+# -- Mypy ------------------------------------------------------------------------------
+
+[tool.mypy]
+
+strict = true
+ignore_missing_imports = true  # Ignore missing type hints for third-party librarie
+show_error_codes = true  # Show error codes in the output
+
+exclude = [
+    "__main__.py",
+    'tools',
+    'agent'
+]
+
+# Useful fine-tuning overrides to 'strict'
+warn_unused_configs = true
+warn_return_any = true
+no_implicit_optional = false
+warn_unused_ignores = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+disallow_untyped_calls = false  # often useful to allow
+disallow_untyped_decorators = false  # decorators are often tricky
+check_untyped_defs = true
+
+plugins = [
+    "numpy.typing.mypy_plugin",
+    "sqlalchemy.ext.mypy.plugin",
+]
+
 # -- Coverage --------------------------------------------------------------------------
 
 [tool.coverage.run]

{pyrekordbox-0.4.1 → pyrekordbox-0.4.3}/pyrekordbox/__init__.py

@@ -2,6 +2,7 @@
 # Author: Dylan Jones
 # Date:   2022-04-10
 
+# mypy: disable-error-code="attr-defined"
 from .anlz import AnlzFile, get_anlz_paths, read_anlz_files, walk_anlz_paths
 from .config import get_config, show_config, update_config
 from .db6 import Rekordbox6Database

{pyrekordbox-0.4.1 → pyrekordbox-0.4.3}/pyrekordbox/__main__.py

@@ -9,7 +9,7 @@ import sys
 import urllib.request
 from pathlib import Path
 
-from pyrekordbox.config import _cache_file, write_db6_key_cache
+from pyrekordbox.config import get_cache_file, write_db6_key_cache
 
 KEY_SOURCES = [
     {
@@ -144,7 +144,8 @@ def download_db6_key():
             dp = match.group("dp")
             break
     if dp:
-        print(f"Found key, updating cache file {_cache_file}")
+        cache_file = get_cache_file()
+        print(f"Found key, updating cache file {cache_file}")
         write_db6_key_cache(dp)
     else:
         print("No key found in the online sources.")

{pyrekordbox-0.4.1 → pyrekordbox-0.4.3}/pyrekordbox/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.4.1'
-__version_tuple__ = version_tuple = (0, 4, 1)
+__version__ = version = '0.4.3'
+__version_tuple__ = version_tuple = (0, 4, 3)

{pyrekordbox-0.4.1 → pyrekordbox-0.4.3}/pyrekordbox/anlz/__init__.py

@@ -4,7 +4,7 @@
 
 import re
 from pathlib import Path
-from typing import Union
+from typing import Dict, Iterator, Tuple, Union
 
 from . import structs
 from .file import AnlzFile
@@ -42,7 +42,7 @@ def is_anlz_file(path: Union[str, Path]) -> bool:
     return bool(RE_ANLZ.match(path.name))
 
 
-def get_anlz_paths(root: Union[str, Path]) -> dict:
+def get_anlz_paths(root: Union[str, Path]) -> Dict[str, Union[Path, None]]:
     """Returns the paths of all existing ANLZ files in a directory.
 
     Parameters
@@ -62,14 +62,14 @@ def get_anlz_paths(root: Union[str, Path]) -> dict:
     >>> p["DAT"]
     directory/ANLZ0000.DAT
     """
-    paths = {"DAT": None, "EXT": None, "2EX": None}
+    paths: Dict[str, Union[Path, None]] = {"DAT": None, "EXT": None, "2EX": None}
     for path in Path(root).iterdir():
         if RE_ANLZ.match(path.name):
             paths[path.suffix[1:].upper()] = path
     return paths
 
 
-def walk_anlz_dirs(root_dir: Union[str, Path]):
+def walk_anlz_dirs(root_dir: Union[str, Path]) -> Iterator[Path]:
     """Finds all ANLZ directory paths recursively.
 
     Parameters
@@ -88,7 +88,7 @@ def walk_anlz_dirs(root_dir: Union[str, Path]):
                 yield path
 
 
-def walk_anlz_paths(root_dir: Union[str, Path]):
+def walk_anlz_paths(root_dir: Union[str, Path]) -> Iterator[Tuple[Path, Dict[str, Path]]]:
     """Finds all ANLZ directory paths and the containing file paths recursively.
 
     Parameters
@@ -110,7 +110,7 @@ def walk_anlz_paths(root_dir: Union[str, Path]):
         yield anlz_dir, files
 
 
-def read_anlz_files(root: Union[str, Path] = "") -> dict:
+def read_anlz_files(root: Union[str, Path] = "") -> Dict[Path, AnlzFile]:
     """Open all ANLZ files in the given root directory.
 
     Parameters

{pyrekordbox-0.4.1 → pyrekordbox-0.4.3}/pyrekordbox/anlz/file.py

@@ -5,12 +5,12 @@
 import logging
 from collections import abc
 from pathlib import Path
-from typing import Union
+from typing import Any, Iterator, List, Union
 
-from construct import Int16ub
+from construct import Int16ub, Struct
 
 from . import structs
-from .tags import TAGS
+from .tags import TAGS, AbstractAnlzTag, StructNotInitializedError
 
 logger = logging.getLogger(__name__)
 
@@ -18,35 +18,35 @@ XOR_MASK = bytearray.fromhex("CB E1 EE FA E5 EE AD EE E9 D2 E9 EB E1 E9 F3 E8 E9
 
 
 class BuildFileLengthError(Exception):
-    def __init__(self, struct, len_data):
+    def __init__(self, struct: Struct, len_data: int) -> None:
         super().__init__(
             f"`len_file` ({struct.len_file}) of '{struct.type}' does not "
             f"match the data-length ({len_data})!"
         )
 
 
-class AnlzFile(abc.Mapping):
+class AnlzFile(abc.Mapping):  # type: ignore[type-arg]
     """Rekordbox `ANLZnnnn.xxx` binary file handler."""
 
-    def __init__(self):
-        self._path = ""
-        self.file_header = None
-        self.tags = list()
+    def __init__(self) -> None:
+        self._path: str = ""
+        self.file_header: Union[Struct, None] = None
+        self.tags: List[AbstractAnlzTag] = list()
 
     @property
-    def num_tags(self):
+    def num_tags(self) -> int:
         return len(self.tags)
 
     @property
-    def tag_types(self):
+    def tag_types(self) -> List[str]:
         return [tag.type for tag in self.tags]
 
     @property
-    def path(self):
+    def path(self) -> str:
         return self._path
 
     @classmethod
-    def parse(cls, data: bytes):
+    def parse(cls, data: bytes) -> "AnlzFile":
         """Parses the in-memory data of a Rekordbox analysis binary file.
 
         Parameters
@@ -64,7 +64,7 @@ class AnlzFile(abc.Mapping):
         return self
 
     @classmethod
-    def parse_file(cls, path: Union[str, Path]):
+    def parse_file(cls, path: Union[str, Path]) -> "AnlzFile":
         """Reads and parses a Rekordbox analysis binary file.
 
         Parameters
@@ -92,10 +92,10 @@ class AnlzFile(abc.Mapping):
             data = fh.read()
 
         self = cls.parse(data)
-        self._path = path
+        self._path = str(path)
         return self
 
-    def _parse(self, data: bytes):
+    def _parse(self, data: bytes) -> None:
         file_header = structs.AnlzFileHeader.parse(data)
         tag_type = file_header.type
         assert tag_type == "PMAI"
@@ -136,6 +136,8 @@ class AnlzFile(abc.Mapping):
             try:
                 # Parse the struct
                 tag = TAGS[tag_type](tag_data)
+                if tag.struct is None:
+                    raise StructNotInitializedError()
                 tags.append(tag)
                 len_header = tag.struct.len_header
                 len_tag = tag.struct.len_tag
@@ -147,28 +149,34 @@ class AnlzFile(abc.Mapping):
                 )
             except KeyError:
                 logger.warning("Tag '%s' not supported!", tag_type)
-                tag = structs.AnlzTag.parse(tag_data)
-                len_tag = tag.len_tag
+                tag_struct = structs.AnlzTag.parse(tag_data)
+                len_tag = tag_struct.len_tag
             i += len_tag
 
         self.file_header = file_header
         self.tags = tags
 
-    def update_len(self):
+    def update_len(self) -> None:
         # Update struct lengths
+        if self.file_header is None:
+            raise StructNotInitializedError()
         tags_len = 0
         for tag in self.tags:
+            if tag.struct is None:
+                raise StructNotInitializedError()
             tag.update_len()
             tags_len += tag.struct.len_tag
         # Update file length
         len_file = self.file_header.len_header + tags_len
         self.file_header.len_file = len_file
 
-    def build(self):
+    def build(self) -> bytes:
+        if self.file_header is None:
+            raise StructNotInitializedError()
         self.update_len()
         header_data = structs.AnlzFileHeader.build(self.file_header)
         section_data = b"".join(tag.build() for tag in self.tags)
-        data = header_data + section_data
+        data: bytes = header_data + section_data
         # Check `len_file`
         len_file = self.file_header.len_file
         len_data = len(data)
@@ -177,38 +185,38 @@ class AnlzFile(abc.Mapping):
 
         return data
 
-    def save(self, path=""):
+    def save(self, path: Union[str, Path] = "") -> None:
         path = path or self._path
 
         data = self.build()
         with open(path, "wb") as fh:
             fh.write(data)
 
-    def get_tag(self, key):
+    def get_tag(self, key: str) -> AbstractAnlzTag:
         return self.__getitem__(key)[0]
 
-    def getall_tags(self, key):
+    def getall_tags(self, key: str) -> List[AbstractAnlzTag]:
         return self.__getitem__(key)
 
-    def get(self, key):
+    def get(self, key: str) -> Any:  # type: ignore[override]
         return self.__getitem__(key)[0].get()
 
-    def getall(self, key):
+    def getall(self, key: str) -> List[Any]:
         return [tag.get() for tag in self.__getitem__(key)]
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self.keys())
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[str]:
         return iter(set(tag.type for tag in self.tags))
 
-    def __getitem__(self, item):
+    def __getitem__(self, item: str) -> List[AbstractAnlzTag]:
         if item.isupper() and len(item) == 4:
             return [tag for tag in self.tags if tag.type == item]
         else:
             return [tag for tag in self.tags if tag.name == item]
 
-    def __contains__(self, item):
+    def __contains__(self, item: str) -> bool:  # type: ignore[override]
         if item.isupper() and len(item) == 4:
             for tag in self.tags:
                 if item == tag.type:
@@ -219,9 +227,9 @@ class AnlzFile(abc.Mapping):
                     return True
         return False
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"{self.__class__.__name__}({self.tag_types})"
 
-    def set_path(self, path):
+    def set_path(self, path: Union[Path, str]) -> None:
         tag = self.get_tag("PPTH")
         tag.set(path)