lexicon-python 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

lexicon/__init__.py

@@ -1,8 +1,23 @@
 """Public package surface for the lexicon Python client."""
 
 from .client import DEFAULT_HOST, LEXICON_PORT, Lexicon
-from .resources.tracks_types import *
+from .resources.playlists_types import PlaylistResponse
+from .resources.tag_categories_types import TagCategoryResponse
+from .resources.tags_types import TagResponse
+from .resources.tracks_types import (
+    CuePointResponse,
+    TempoMarkerResponse,
+    TrackResponse,
+)
 
-
-
-__all__ = ["DEFAULT_HOST", "LEXICON_PORT", "Lexicon"]
+__all__ = [
+    "DEFAULT_HOST",
+    "LEXICON_PORT",
+    "Lexicon",
+    "TrackResponse",
+    "PlaylistResponse",
+    "TagResponse",
+    "TagCategoryResponse",
+    "CuePointResponse",
+    "TempoMarkerResponse",
+]

lexicon/client.py

@@ -14,17 +14,26 @@ from .resources.tag_categories import TagCategories
 from .resources.tags import Tags
 from .resources.tracks import Tracks
 from .tools import playlists as playlist_tools
+from .tools import tracks as track_tools
+
 DEFAULT_HOST = os.environ.get("LEXICON_HOST", "localhost")
 LEXICON_PORT = int(os.environ.get("LEXICON_PORT", "48624"))
 
 
+class Tools:
+    """Namespace for helper tools."""
+
+    playlists = playlist_tools
+    tracks = track_tools
+
+
 class Lexicon:
     """Resource-grouped client for the Lexicon Local API."""
 
     tracks: Tracks
     playlists: Playlists
     tags: Tags
-    tools: Any
+    tools: Tools
 
     def __init__(
         self,
@@ -34,6 +43,7 @@ class Lexicon:
         default_timeout: int = 20,
         session: Optional[requests.Session] = None,
         raise_on_error: bool = False,
+        raw_enums: bool = True,
     ) -> None:
         """Create a Lexicon client bound to an API instance.
 
@@ -49,21 +59,26 @@ class Lexicon:
             Optional requests session to reuse connections.
         raise_on_error
             If True, raise HTTP errors instead of returning None.
+        raw_enums
+            If True (default), return API enum values as raw codes (e.g. ``"1"``).
+            If False, convert to human-readable names (e.g. ``"normal"``).
         """
         self.host = host or DEFAULT_HOST
         self.port = int(port or LEXICON_PORT)
         self.default_timeout = default_timeout
         self.raise_on_error = raise_on_error
+        self.raw_enums = raw_enums
         self._logger = logging.getLogger(__name__)
         self._session = session
 
         self.tracks: Tracks = Tracks(self)
         self.playlists: Playlists = Playlists(self)
-        self.playlists.tracks = PlaylistTracks(self, tracks=self.tracks, playlists=self.playlists)
+        self.playlists.tracks = PlaylistTracks(
+            self, tracks=self.tracks, playlists=self.playlists
+        )
         self.tags: Tags = Tags(self)
         self.tags.categories = TagCategories(self)
-        self.tools = type("Tools", (), {})()
-        self.tools.playlists = playlist_tools
+        self.tools = Tools()
 
     def request(
         self,

lexicon/resources/_common_types.py

@@ -22,62 +22,85 @@ ValidationMode = Literal["off", "warn", "strict"]
 
 # --- Color Types and Normalization --- #
 Color = Literal[
-    "red_dark", "red", "red_light", "red_orange", "orange", "beige", "yellow_dark", "yellow",
-    "lime", "green_light", "green", "green_dark", "teal", "aqua", "aqua_dark", "blue_light",
-    "blue", "blue_dark", "blue_violet", "violet", "violet_light", "magenta", "magenta_dark",
-    "magenta_red", "grey_light", "grey_dark", "black", "white",
+    "red_dark",
+    "red",
+    "red_light",
+    "red_orange",
+    "orange",
+    "beige",
+    "yellow_dark",
+    "yellow",
+    "lime",
+    "green_light",
+    "green",
+    "green_dark",
+    "teal",
+    "aqua",
+    "aqua_dark",
+    "blue_light",
+    "blue",
+    "blue_dark",
+    "blue_violet",
+    "violet",
+    "violet_light",
+    "magenta",
+    "magenta_dark",
+    "magenta_red",
+    "grey_light",
+    "grey_dark",
+    "black",
+    "white",
 ]
 COLORS: tuple[Color, ...] = get_args(Color)
 COLOR_RGBS: tuple[tuple[int, int, int], ...] = (
-    (158,  15,   7), # red_dark
-    (230,  15,  13), # red
-    (242, 102,  92), # red_light
-    (239,  89,  15), # red_orange
-    (232, 137,  20), # orange
-    (255, 225, 148), # beige
-    (245, 208,   1), # yellow_dark
-    (245, 245,  10), # yellow
-    (186, 232,  22), # lime
-    (174, 245,  95), # green_light
-    (127, 231,  16), # green
-    ( 75, 140,   8), # green_dark
-    ( 20, 222, 120), # teal
-    ( 20, 222, 202), # aqua
-    (  7, 148, 134), # aqua_dark
-    ( 47, 168, 237), # blue_light
-    ( 14,  88, 222), # blue
-    (  0,  40, 171), # blue_dark
-    (132,   0, 255), # blue_violet
-    (170,  59, 255), # violet
-    (198, 140, 243), # violet_light
-    (230,  15, 222), # magenta
-    (170,   0, 188), # magenta_dark
-    (222,  17,  92), # magenta_red
-    (173, 173, 173), # grey_light
-    ( 92,  92,  92), # grey_dark
-    ( 48,  48,  48), # black
-    (255, 255, 255), # white
+    (158, 15, 7),  # red_dark
+    (230, 15, 13),  # red
+    (242, 102, 92),  # red_light
+    (239, 89, 15),  # red_orange
+    (232, 137, 20),  # orange
+    (255, 225, 148),  # beige
+    (245, 208, 1),  # yellow_dark
+    (245, 245, 10),  # yellow
+    (186, 232, 22),  # lime
+    (174, 245, 95),  # green_light
+    (127, 231, 16),  # green
+    (75, 140, 8),  # green_dark
+    (20, 222, 120),  # teal
+    (20, 222, 202),  # aqua
+    (7, 148, 134),  # aqua_dark
+    (47, 168, 237),  # blue_light
+    (14, 88, 222),  # blue
+    (0, 40, 171),  # blue_dark
+    (132, 0, 255),  # blue_violet
+    (170, 59, 255),  # violet
+    (198, 140, 243),  # violet_light
+    (230, 15, 222),  # magenta
+    (170, 0, 188),  # magenta_dark
+    (222, 17, 92),  # magenta_red
+    (173, 173, 173),  # grey_light
+    (92, 92, 92),  # grey_dark
+    (48, 48, 48),  # black
+    (255, 255, 255),  # white
 )
 
 
-def _normalize_color(value: object) -> Color | None:
-    """Normalize color inputs to the nearest Lexicon color name.
+def _parse_color_rgb(value: object) -> tuple[int, int, int] | None:
+    """Parse a color input into an RGB tuple.
 
     Parameters
     ----------
     value
         Color input. Supported forms:
-        - ``None`` or the string ``"None"`` (case-insensitive)
-        - Lexicon color names (see ``COLORS``)
-        - Various RGB/RGBA forms (alpha is dropped)
-          - Hex strings (``#RGB``, ``#RGBA``, ``#RRGGBB``, ``#RRGGBBAA``)
-          - RGB/RGBA tuples or lists (ints 0-255 or floats 0-1)
-          - Packed RGB integer (``0xRRGGBB``, ``0xAARRGGBB``)
+        - ``None`` or the string ``"None"`` (case-insensitive) -> returns None
+        - Lexicon color names (see ``COLORS``) -> looked up from COLOR_RGBS
+        - Hex strings (``#RGB``, ``#RGBA``, ``#RRGGBB``, ``#RRGGBBAA``)
+        - RGB/RGBA tuples or lists (ints 0-255 or floats 0-1)
+        - Packed RGB integer (``0xRRGGBB``, ``0xAARRGGBB``)
 
     Returns
     -------
-    Color or None
-        The nearest Lexicon color name, or ``None`` when the input is ``None``.
+    tuple[int, int, int] or None
+        RGB tuple (0-255), or ``None`` when the input is ``None``.
 
     Raises
     ------
@@ -90,20 +113,23 @@ def _normalize_color(value: object) -> Color | None:
         if value.strip().lower() == "none":
             return None
         if value in COLORS:
-            return value
-        hex_match = re.match(r"^\s*#?([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})\s*$", value, flags=re.IGNORECASE)
+            return COLOR_RGBS[COLORS.index(value)]
+        hex_match = re.match(
+            r"^\s*#?([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})\s*$",
+            value,
+            flags=re.IGNORECASE,
+        )
         if hex_match:
             hex_value = hex_match.group(1)
             if len(hex_value) in (3, 4):
                 hex_value = "".join(ch * 2 for ch in hex_value)
             if len(hex_value) == 8:
                 hex_value = hex_value[:6]
-            rgb = (
+            return (
                 int(hex_value[0:2], 16),
                 int(hex_value[2:4], 16),
                 int(hex_value[4:6], 16),
             )
-            return _nearest_color(rgb)
         raise ValueError(f"Unsupported string input {value!r}")
 
     if isinstance(value, int):
@@ -111,8 +137,7 @@ def _normalize_color(value: object) -> Color | None:
             raise ValueError(f"Negative packed int {value!r}")
         if value > 0xFFFFFF:
             value = value & 0xFFFFFF
-        rgb = ((value >> 16) & 0xFF, (value >> 8) & 0xFF, value & 0xFF)
-        return _nearest_color(rgb)
+        return ((value >> 16) & 0xFF, (value >> 8) & 0xFF, value & 0xFF)
 
     if isinstance(value, (tuple, list)) and len(value) in (3, 4):
         rgb_values = value[:3]
@@ -123,12 +148,34 @@ def _normalize_color(value: object) -> Color | None:
                 if channel_value <= 1:
                     channel_value *= 255
                 rgb.append(int(max(0, min(255, round(channel_value)))))
-            return _nearest_color((rgb[0], rgb[1], rgb[2]))
+            return (rgb[0], rgb[1], rgb[2])
         raise ValueError(f"Invalid RGB tuple values {value!r}")
 
     raise ValueError(f"Unsupported input type {type(value)}")
 
 
+def _normalize_color(value: object) -> Color | None:
+    """Normalize color inputs to the nearest Lexicon color name.
+
+    Used for tracks and cuepoints which use a fixed color swatch.
+    """
+    rgb = _parse_color_rgb(value)
+    if rgb is None:
+        return None
+    return _nearest_color(rgb)
+
+
+def _normalize_color_hex(value: object) -> str | None:
+    """Normalize color inputs to a hex string (#RRGGBB).
+
+    Used for tag categories which support a full color picker.
+    """
+    rgb = _parse_color_rgb(value)
+    if rgb is None:
+        return None
+    return f"#{rgb[0]:02x}{rgb[1]:02x}{rgb[2]:02x}"
+
+
 def _nearest_color(rgb: tuple[int, int, int]) -> Color:
     """Find the nearest Lexicon color to the given RGB values."""
     best_index = 0
@@ -147,19 +194,19 @@ def _nearest_color(rgb: tuple[int, int, int]) -> Color:
 # --- ID Sequence Normalization --- #
 def _normalize_id_sequence(ids: int | Sequence[int] | object) -> list[int] | None:
     """Normalize single ID or sequence of IDs to a deduplicated list.
-    
+
     Parameters
     ----------
     ids
         Single integer ID or sequence of integer IDs.
-    
+
     Returns
     -------
     list[int] | None
         Deduplicated list of valid IDs (>= 1), or None if:
         - Input is not int or sequence (or is str/bytes)
         - No valid IDs found (all < 1)
-    
+
     Notes
     -----
     Used for normalizing track IDs, tag IDs, and similar integer sequences.
@@ -172,7 +219,9 @@ def _normalize_id_sequence(ids: int | Sequence[int] | object) -> list[int] | Non
     else:
         return None
 
-    valid_ids = [id_val for id_val in id_list if isinstance(id_val, int) and id_val >= 1]
+    valid_ids = [
+        id_val for id_val in id_list if isinstance(id_val, int) and id_val >= 1
+    ]
     if not valid_ids:
         return None
 

lexicon/resources/base.py

@@ -27,7 +27,9 @@ class Resource:
         json: Optional[dict[str, Any]] = None,
         timeout: Optional[int] = None,
     ) -> Optional[dict[str, Any] | list[Any]]:
-        return self._client.request(method, path, params=params, json=json, timeout=timeout)
+        return self._client.request(
+            method, path, params=params, json=json, timeout=timeout
+        )
 
     def _get(
         self,

lexicon/resources/playlist_tracks.py

@@ -10,7 +10,6 @@ from .playlists_types import PlaylistResponse
 from .tracks import Tracks
 from .tracks_types import TrackResponse
 from ._common_types import ValidationMode, _normalize_id_sequence
-from ..utils import unique_in_order
 
 
 class PlaylistTracks(Resource):
@@ -32,7 +31,6 @@ class PlaylistTracks(Resource):
         self._tracks = tracks
         self._playlists = playlists
 
-
     def get(
         self,
         playlist_id: int,
@@ -63,14 +61,13 @@ class PlaylistTracks(Resource):
             if validation == "warn":
                 self._logger.warning("Invalid playlist_id for remove: %s", playlist_id)
             return None
-        
+
         track_ids = self.list(playlist_id, validation=validation, timeout=timeout)
         if track_ids is None:
             return None
         if not track_ids:
             return []
         return self._tracks.get_many(track_ids, validation="off", timeout=timeout)
-    
 
     def list(
         self,
@@ -112,7 +109,6 @@ class PlaylistTracks(Resource):
             return [track_id for track_id in track_ids if isinstance(track_id, int)]
         self._logger.warning("Playlist %s missing expected trackIds list", playlist_id)
         return None
-    
 
     def add(
         self,
@@ -150,7 +146,7 @@ class PlaylistTracks(Resource):
             if validation == "warn":
                 self._logger.warning("Invalid playlist_id for add: %s", playlist_id)
             return False
-        
+
         # When validation is off, pass input directly without transformation
         if validation == "off":
             normalized_ids = [track_ids] if isinstance(track_ids, int) else track_ids
@@ -163,7 +159,7 @@ class PlaylistTracks(Resource):
                 if validation == "warn":  # pragma: no branch - strict raises above
                     self._logger.warning("Invalid track_ids for add: %s", track_ids)
                     return False
-        
+
         if index is not None and (not isinstance(index, int) or index < 0):
             if validation == "strict":
                 raise ValueError(f"Invalid index: {index}")
@@ -211,7 +207,7 @@ class PlaylistTracks(Resource):
             if validation == "warn":
                 self._logger.warning("Invalid playlist_id for remove: %s", playlist_id)
             return False
-        
+
         # When validation is off, pass input directly without transformation
         if validation == "off":
             normalized_ids = [track_ids] if isinstance(track_ids, int) else track_ids
@@ -224,7 +220,7 @@ class PlaylistTracks(Resource):
                 if validation == "warn":  # pragma: no branch - strict raises above
                     self._logger.warning("Invalid track_ids for remove: %s", track_ids)
                     return False
-        
+
         payload = {"id": playlist_id, "trackIds": normalized_ids}
         response = self._delete("/playlist-tracks", json=payload, timeout=timeout)
         return response is not None
@@ -270,14 +266,20 @@ class PlaylistTracks(Resource):
         playlist_type = cast(PlaylistResponse, playlist).get("type")
         if playlist_type is not None and str(playlist_type) != "2":
             if validation == "strict":
-                raise ValueError(f"Playlist {playlist_id} is not a normal playlist (type=2)")
+                raise ValueError(
+                    f"Playlist {playlist_id} is not a normal playlist (type=2)"
+                )
             if validation == "warn":
-                self._logger.warning("Playlist %s is not a normal playlist (type=2)", playlist_id)
+                self._logger.warning(
+                    "Playlist %s is not a normal playlist (type=2)", playlist_id
+                )
             return False
 
         existing_ids = cast(PlaylistResponse, playlist).get("trackIds")
         if isinstance(existing_ids, list) and existing_ids:
-            if not self.remove(playlist_id, existing_ids, validation="off", timeout=timeout):
+            if not self.remove(
+                playlist_id, existing_ids, validation="off", timeout=timeout
+            ):
                 return False
 
         # When validation is off, pass input directly without transformation
@@ -295,4 +297,6 @@ class PlaylistTracks(Resource):
         if not normalized_ids:
             return True
 
-        return self.add(playlist_id, normalized_ids, index=0, validation="off", timeout=timeout)
+        return self.add(
+            playlist_id, normalized_ids, index=0, validation="off", timeout=timeout
+        )