pyrekordbox 0.4.2__py3-none-any.whl → 0.4.4__py3-none-any.whl

pyrekordbox/db6/tables.py

@@ -7,15 +7,15 @@
 import math
 import re
 import struct
-from datetime import datetime
+from datetime import datetime, timezone
 from enum import IntEnum
-from typing import List
+from typing import Any, Dict, Iterator, List, Optional, Tuple
 
 import numpy as np
 from sqlalchemy import (
     VARCHAR,
     BigInteger,
-    Column,
+    Dialect,
     Float,
     ForeignKey,
     Integer,
@@ -71,6 +71,7 @@ __all__ = [
     "ImageFile",
     "SettingFile",
     "UuidIDMap",
+    "FileType",
 ]
 
 
@@ -116,37 +117,38 @@ TABLES = [
 
 
 def datetime_to_str(value: datetime) -> str:
-    s = value.isoformat().replace("T", " ")
-    if value.tzinfo is not None:
-        # Get the timezone info (last 6 characters of the string)
-        tzinfo = s[-6:]
-        s = s[:-9] + " " + tzinfo
-    else:
-        s = s[:-3] + " +00:00"
+    # Convert to UTC timezone string
+    s = value.astimezone(timezone.utc).isoformat().replace("T", " ")
+    # Get the timezone info (last 6 characters of the string)
+    tzinfo = s[-6:]
+    s = s[:-9] + " " + tzinfo
     return s
 
 
 def string_to_datetime(value: str) -> datetime:
     try:
+        # Normalize 'Z' (Zulu/UTC) to '+00:00' for fromisoformat compatibility
+        if value.endswith("Z"):
+            value = value[:-1] + "+00:00"
         dt = datetime.fromisoformat(value)
     except ValueError:
         if len(value.strip()) > 23:
-            # Assume the format
-            # "2025-04-12 19:11:29.274 -05:00" or
+            # Handles formats like:
             # "2025-04-12 19:11:29.274 -05:00 (Central Daylight Time)"
             datestr, tzinfo = value[:23], value[23:30]
             datestr = datestr.strip()
             tzinfo = tzinfo.strip()
-            assert re.match(r"^[+-]?\d{1,2}:\d{2}", tzinfo)
-            datestr = datestr.strip() + tzinfo
+            if tzinfo == "Z":
+                tzinfo = "+00:00"
+            assert re.match(r"^[+-]?\d{1,2}:\d{2}", tzinfo), f"Invalid tzinfo: {tzinfo}"
+            datestr = datestr + tzinfo
         else:
-            datestr, tzinfo = value, ""
+            datestr = value.strip()
         dt = datetime.fromisoformat(datestr)
-    # Convert to local timezone and return without timezone
     return dt.astimezone().replace(tzinfo=None)
 
 
-class DateTime(TypeDecorator):
+class DateTime(TypeDecorator):  # type: ignore[type-arg]
     """Custom datetime column with timezone support.
 
     The datetime format in the database is `YYYY-MM-DD HH:MM:SS.SSS +00:00`.
@@ -156,10 +158,10 @@ class DateTime(TypeDecorator):
     impl = Text
     cache_ok = True
 
-    def process_bind_param(self, value: datetime, dialect) -> str:
+    def process_bind_param(self, value: datetime, dialect: Dialect) -> str:  # type: ignore[override]
         return datetime_to_str(value)
 
-    def process_result_value(self, value: str, dialect):
+    def process_result_value(self, value: str, dialect: Dialect) -> Optional[datetime]:  # type: ignore[override]
         if value:
             return string_to_datetime(value)
         return None
@@ -190,65 +192,65 @@ class Base(DeclarativeBase):
     __keys__: List[str] = []
 
     @classmethod
-    def create(cls, **kwargs):
+    def create(cls, **kwargs: Any):  # type: ignore # noqa: ANN206
         with RekordboxAgentRegistry.disabled():
             # noinspection PyArgumentList
             self = cls(**kwargs)
         return self
 
     @classmethod
-    def columns(cls):
+    def columns(cls) -> List[str]:
         """Returns a list of all column names without the relationships."""
         return [column.name for column in inspect(cls).c]
 
     @classmethod
-    def relationships(cls):
+    def relationships(cls) -> List[str]:
         """Returns a list of all relationship names."""
         return [column.key for column in inspect(cls).relationships]  # noqa
 
     @classmethod
-    def __get_keys__(cls):  # pragma: no cover
+    def __get_keys__(cls) -> List[str]:  # pragma: no cover
         """Get all attributes of the table."""
         items = cls.__dict__.items()
         keys = [k for k, v in items if not callable(v) and not k.startswith("_")]
         return keys
 
     @classmethod
-    def keys(cls):  # pragma: no cover
+    def keys(cls) -> List[str]:  # pragma: no cover
         """Returns a list of all column names including the relationships."""
         if not cls.__keys__:  # Cache the keys
             cls.__keys__ = cls.__get_keys__()
         return cls.__keys__
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[str]:
         """Iterates over all columns and relationship names."""
         return iter(self.keys())
 
-    def __len__(self):
+    def __len__(self) -> int:
         return sum(1 for _ in self.__iter__())
 
-    def __getitem__(self, item):
+    def __getitem__(self, item: str) -> Any:
         return self.__getattribute__(item)
 
     # noinspection PyUnresolvedReferences
-    def __setattr__(self, key, value):
+    def __setattr__(self, key: str, value: Any) -> None:
         if not key.startswith("_"):
             RekordboxAgentRegistry.on_update(self, key, value)
         super().__setattr__(key, value)
 
-    def values(self):
+    def values(self) -> List[Any]:
         """Returns a list of all column values including the relationships."""
         return [self.__getitem__(key) for key in self.keys()]
 
-    def items(self):
+    def items(self) -> Iterator[Tuple[str, Any]]:
         for key in self.__iter__():
             yield key, self.__getitem__(key)
 
-    def to_dict(self):
+    def to_dict(self) -> Dict[str, Any]:
         """Returns a dictionary of all column names and values."""
         return {key: self.__getitem__(key) for key in self.columns()}
 
-    def pformat(self, indent="   "):  # pragma: no cover
+    def pformat(self, indent: str = "   ") -> str:  # pragma: no cover
         lines = [f"{self.__tablename__}"]
         columns = self.columns()
         w = max(len(col) for col in columns)
@@ -271,7 +273,7 @@ class StatsTime:
 class StatsFull:
     """Mixin class for tables that use all statistics columns."""
 
-    ID: Column
+    ID: Mapped[str]
     """The ID (primary key) of the table entry."""
 
     UUID: Mapped[str] = mapped_column(VARCHAR(255), default=None)
@@ -296,7 +298,7 @@ class StatsFull:
     )
     """The last update date of the table entry (from :class:`StatsFull`)."""
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__}({self.ID})>"
 
 
@@ -525,7 +527,7 @@ class DjmdAlbum(Base, StatsFull):
     AlbumArtistName = association_proxy("AlbumArtist", "Name")
     """The name of the album artist (:class:`DjmdArtist`) of the track."""
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <10} Name={self.Name}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -542,7 +544,7 @@ class DjmdArtist(Base, StatsFull):
     SearchStr: Mapped[str] = mapped_column(VARCHAR(255), default=None)
     """The search string of the artist."""
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <10} Name={self.Name}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -588,7 +590,7 @@ class DjmdColor(Base, StatsFull):
     Commnt: Mapped[str] = mapped_column(VARCHAR(255), default=None)
     """The comment (name) of the color."""
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <2} Comment={self.Commnt}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -807,7 +809,7 @@ class DjmdContent(Base, StatsFull):
     MyTagIDs = association_proxy("MyTags", "MyTagID")
     """The IDs of the my tags (:class:`DjmdSongMyTag`) of the track."""
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <10} Title={self.Title}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -869,11 +871,11 @@ class DjmdCue(Base, StatsFull):
     """The content entry of the cue point (links to :class:`DjmdContent`)."""
 
     @property
-    def is_memory_cue(self):
+    def is_memory_cue(self) -> bool:
         return self.Kind == 0
 
     @property
-    def is_hot_cue(self):
+    def is_hot_cue(self) -> bool:
         return self.Kind > 0
 
 
@@ -889,7 +891,7 @@ class DjmdDevice(Base, StatsFull):
     Name: Mapped[str] = mapped_column(VARCHAR(255), default=None)
     """The name of the device."""
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <2} Name={self.Name}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -904,7 +906,7 @@ class DjmdGenre(Base, StatsFull):
     Name: Mapped[str] = mapped_column(VARCHAR(255), default=None)
     """The name of the genre."""
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <2} Name={self.Name}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -943,7 +945,7 @@ class DjmdHistory(Base, StatsFull):
     Backrefs to the parent history playlist via :attr:`Parent`.
     """
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <2} Name={self.Name}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -1007,7 +1009,7 @@ class DjmdHotCueBanklist(Base, StatsFull):
     Backrefs to the parent hot-cue banklist via :attr:`Parent`.
     """
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <2} Name={self.Name}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -1087,7 +1089,7 @@ class DjmdKey(Base, StatsFull):
     Seq: Mapped[int] = mapped_column(Integer, default=None)
     """The sequence of the key (for ordering)."""
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <2} Name={self.ScaleName}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -1102,7 +1104,7 @@ class DjmdLabel(Base, StatsFull):
     Name: Mapped[str] = mapped_column(VARCHAR(255), default=None)
     """The name of the label."""
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <2} Name={self.Name}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -1119,7 +1121,7 @@ class DjmdMenuItems(Base, StatsFull):
     Name: Mapped[str] = mapped_column(VARCHAR(255), default=None)
     """The name of the menu item."""
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <2} Name={self.Name}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -1151,7 +1153,7 @@ class DjmdMixerParam(Base, StatsFull):
     """The content this mixer parameters belong to (links to :class:`DjmdContent`)."""
 
     @staticmethod
-    def _get_db(low, high):
+    def _get_db(low: int, high: int) -> float:
         integer = (high << 16) | low
         byte_data = integer.to_bytes(4, byteorder="big")
         factor = struct.unpack("!f", byte_data)[0]
@@ -1160,7 +1162,7 @@ class DjmdMixerParam(Base, StatsFull):
         return 20 * math.log10(factor)
 
     @staticmethod
-    def _set_db(value):
+    def _set_db(value: float) -> Tuple[int, int]:
         if value == -np.inf:
             return 0, 0
         factor = 10 ** (value / 20)
@@ -1184,7 +1186,7 @@ class DjmdMixerParam(Base, StatsFull):
         self.GainLow, self.GainHigh = self._set_db(value)
 
     @property
-    def Peak(self):
+    def Peak(self) -> float:
         """The peak amplitude of a track in dB.
 
         This value is computed from the low and high peak values.
@@ -1193,7 +1195,7 @@ class DjmdMixerParam(Base, StatsFull):
         return self._get_db(self.PeakLow, self.PeakHigh)
 
     @Peak.setter
-    def Peak(self, value):
+    def Peak(self, value: float) -> None:
         self.PeakLow, self.PeakHigh = self._set_db(value)
 
 
@@ -1229,7 +1231,7 @@ class DjmdMyTag(Base, StatsFull):
     Backrefs to the parent list via :attr:`Parent`.
     """
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <2} Name={self.Name}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -1300,18 +1302,18 @@ class DjmdPlaylist(Base, StatsFull):
     """
 
     @property
-    def is_playlist(self):
+    def is_playlist(self) -> bool:
         return self.Attribute == PlaylistType.PLAYLIST
 
     @property
-    def is_folder(self):
+    def is_folder(self) -> bool:
         return self.Attribute == PlaylistType.FOLDER
 
     @property
-    def is_smart_playlist(self):
+    def is_smart_playlist(self) -> bool:
         return self.Attribute == PlaylistType.SMART_PLAYLIST
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <2} Name={self.Name}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -1381,7 +1383,7 @@ class DjmdRelatedTracks(Base, StatsFull):
     Backrefs to the parent related tracks list via :attr:`Parent`.
     """
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <2} Name={self.Name}"
         return f"<{self.__class__.__name__}({s})>"
 
@@ -1446,7 +1448,7 @@ class DjmdSampler(Base, StatsFull):
     Backrefs to the parent sampler list via :attr:`Parent`.
     """
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         s = f"{self.ID: <2} Name={self.Name}"
         return f"<{self.__class__.__name__}({s})>"
 

pyrekordbox/mysettings/__init__.py

@@ -4,6 +4,7 @@
 
 import re
 from pathlib import Path
+from typing import List, Union
 
 from . import structs
 from .file import (
@@ -18,7 +19,7 @@ from .file import (
 RE_MYSETTING = re.compile(".*SETTING[0-9]?.DAT$")
 
 
-def get_mysetting_paths(root, deep=False):
+def get_mysetting_paths(root: Union[str, Path], deep: bool = False) -> List[Path]:
     files = list()
     root = Path(root)
     iteator = root.rglob("*") if deep else root.iterdir()
@@ -28,6 +29,6 @@ def get_mysetting_paths(root, deep=False):
     return files
 
 
-def read_mysetting_file(path) -> SettingsFile:
+def read_mysetting_file(path: Union[str, Path]) -> SettingsFile:
     obj = FILES[str(Path(path).name)]
     return obj.parse_file(path)

pyrekordbox/mysettings/file.py

@@ -6,6 +6,8 @@
 
 import re
 from collections.abc import MutableMapping
+from pathlib import Path
+from typing import Any, Dict, Iterator, Type, Union
 
 from construct import Struct
 
@@ -51,7 +53,7 @@ CRC16_XMODEM_TABLE = [
 RE_INVALID_KEY = re.compile("[_u][0-9]?", flags=re.IGNORECASE)
 
 
-def compute_checksum(data, struct):
+def compute_checksum(data: bytes, struct: Struct) -> int:
     """Computes the CRC16 XModem checksum for My-Setting files.
 
     The checksum is calculated over the contents of the `data` field,
@@ -83,11 +85,11 @@ def compute_checksum(data, struct):
     return crc
 
 
-def _is_valid_key(k: str):
+def _is_valid_key(k: str) -> bool:
     return not RE_INVALID_KEY.match(k)
 
 
-class SettingsFile(MutableMapping):
+class SettingsFile(MutableMapping):  # type: ignore[type-arg]
     """Base class for the Rekordbox My-Setting file handler.
 
     The base class implements the getters and setter defined by the keys and
@@ -98,16 +100,16 @@ class SettingsFile(MutableMapping):
     """
 
     struct: Struct
-    defaults: dict
+    defaults: Dict[str, str]
     version: str = ""  # only used by DEVSETTING
 
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__()
         self.parsed = None
-        self._items = dict()
+        self._items: Dict[str, str] = dict()
 
     @classmethod
-    def parse(cls, data: bytes):
+    def parse(cls, data: bytes) -> "SettingsFile":
         """Parses the in-memory data of a Rekordbox settings binary file.
 
         Parameters
@@ -125,18 +127,18 @@ class SettingsFile(MutableMapping):
         return self
 
     @classmethod
-    def parse_file(cls, path: str):
+    def parse_file(cls, path: Union[str, Path]) -> "SettingsFile":
         """Reads and parses a Rekordbox settings binary file.
 
         Parameters
         ----------
-        path : str
+        path : str or Path
             The path of a Rekordbox settings file which is used to read
             the file contents before parsing the binary data.
 
         Returns
         -------
-        self : AnlzFile
+        self : SettingsFile
             The new instance with the parsed file content.
 
         See Also
@@ -147,7 +149,7 @@ class SettingsFile(MutableMapping):
             data = fh.read()
         return cls.parse(data)
 
-    def _parse(self, data):
+    def _parse(self, data: bytes) -> None:
         parsed = self.struct.parse(data)
         keys = filter(_is_valid_key, parsed.data.keys())
         items = dict()
@@ -157,27 +159,27 @@ class SettingsFile(MutableMapping):
         self.parsed = parsed
         self._items.update(items)
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self.defaults.keys())
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[str]:
         return iter(self.defaults)
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: str) -> str:
         try:
             return self._items[key]
         except KeyError:
             return self.defaults[key]
 
-    def __setitem__(self, key, value):
+    def __setitem__(self, key: str, value: str) -> None:
         if key not in self.defaults.keys():
             raise KeyError(f"Key {key} not a valid field of {self.__class__.__name__}")
         self._items[key] = value
 
-    def __delitem__(self, key):
+    def __delitem__(self, key: str) -> None:
         del self._items[key]
 
-    def get(self, key, default=None):
+    def get(self, key: str, default: str = None) -> Union[str, None]:  # type: ignore[override]
         """Returns the value of a setting of the My-Setting file.
 
         If the key is not found in the My-Setting data, but it is present in the
@@ -202,7 +204,7 @@ class SettingsFile(MutableMapping):
         except KeyError:
             return default
 
-    def set(self, key, value):
+    def set(self, key: str, value: str) -> None:
         """Sets the value of a setting of the My-Setting file.
 
         Parameters
@@ -214,7 +216,7 @@ class SettingsFile(MutableMapping):
         """
         self.__setitem__(key, value)
 
-    def build(self):
+    def build(self) -> bytes:
         """Constructs the binary data for saving the My-Setting file.
 
         Returns
@@ -227,7 +229,7 @@ class SettingsFile(MutableMapping):
         items.update(self._items)
 
         # Create file data
-        file_items = {"data": items, "checksum": 0}
+        file_items: Dict[str, Any] = {"data": items, "checksum": 0}
         if self.version:
             file_items["version"] = self.version
 
@@ -239,9 +241,10 @@ class SettingsFile(MutableMapping):
         file_items["checksum"] = checksum
 
         # Write data with updated checksum
-        return self.struct.build(file_items)
+        bytedata: bytes = self.struct.build(file_items)
+        return bytedata
 
-    def save(self, path):
+    def save(self, path: Union[str, Path]) -> None:
         """Save the contents of the My-Setting file object.
 
         Parameters
@@ -257,7 +260,7 @@ class SettingsFile(MutableMapping):
         with open(path, "wb") as fh:
             fh.write(data)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"{self.__class__.__name__}()"
 
 
@@ -363,7 +366,7 @@ class DevSettingFile(SettingsFile):
     defaults = dict(entries="")
 
 
-FILES = {
+FILES: Dict[str, Type[SettingsFile]] = {
     "DEVSETTING.DAT": DevSettingFile,
     "DJMMYSETTING.DAT": DjmMySettingFile,
     "MYSETTING.DAT": MySettingFile,