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

lexicon/__init__.py

@@ -1,5 +1,23 @@
 """Public package surface for the lexicon Python client."""
 
-from .lexicon import LexiconClient
+from .client import DEFAULT_HOST, LEXICON_PORT, Lexicon
+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__ = ["LexiconClient"]
+__all__ = [
+    "DEFAULT_HOST",
+    "LEXICON_PORT",
+    "Lexicon",
+    "TrackResponse",
+    "PlaylistResponse",
+    "TagResponse",
+    "TagCategoryResponse",
+    "CuePointResponse",
+    "TempoMarkerResponse",
+]

lexicon/client.py

@@ -0,0 +1,162 @@
+"""Core Lexicon client with a raw-request escape hatch."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Optional
+
+import requests
+
+from .resources.playlist_tracks import PlaylistTracks
+from .resources.playlists import Playlists
+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: Tools
+
+    def __init__(
+        self,
+        *,
+        host: Optional[str] = None,
+        port: Optional[int | str] = None,
+        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.
+
+        Parameters
+        ----------
+        host
+            Hostname or IP for the Lexicon API.
+        port
+            API port number.
+        default_timeout
+            Default request timeout in seconds.
+        session
+            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.tags: Tags = Tags(self)
+        self.tags.categories = TagCategories(self)
+        self.tools = Tools()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict[str, Any] | list[tuple[str, Any]]] = None,
+        json: Optional[dict[str, Any]] = None,
+        timeout: Optional[int] = None,
+    ) -> Optional[dict[str, Any] | list[Any]]:
+        """Send a raw request to the Lexicon API.
+
+        Parameters
+        ----------
+        method
+            HTTP method (GET, POST, PATCH, DELETE).
+        path
+            Endpoint path, with or without a leading `/v1`.
+        params
+            Query parameters for the request.
+        json
+            JSON payload for the request.
+        timeout
+            Timeout in seconds for this request.
+
+        Returns
+        -------
+        dict | list | None
+            Parsed JSON payload, or None if the response is empty or non-JSON.
+        """
+        if not path.startswith("/"):
+            path = "/" + path
+        if not path.startswith("/v1/"):
+            path = "/v1" + path
+        url = f"http://{self.host}:{self.port}{path}"
+
+        requester = self._session or requests
+        try:
+            response = requester.request(
+                method,
+                url,
+                params=params,
+                json=json,
+                timeout=timeout or self.default_timeout,
+            )
+            response.raise_for_status()
+        except requests.HTTPError as exc:
+            if self.raise_on_error:
+                raise
+            # Extract error message from response body if available
+            error_msg = str(exc)
+            try:
+                error_body = response.json()
+                if isinstance(error_body, dict):
+                    # Try common error message fields
+                    if "message" in error_body:
+                        error_msg = f"{exc}\nServer message: {error_body['message']}"
+                    elif "error" in error_body:
+                        error_msg = f"{exc}\nServer error: {error_body['error']}"
+                    elif "detail" in error_body:
+                        error_msg = f"{exc}\nDetails: {error_body['detail']}"
+            except (ValueError, AttributeError, KeyError):
+                pass  # Response wasn't JSON or didn't have expected fields
+            self._logger.warning("Request failed for %s %s: %s", method, url, error_msg)
+            return None
+        except Exception as exc:  # noqa: BLE001 - surface request failures
+            if self.raise_on_error:
+                raise
+            self._logger.warning("Request failed for %s %s: %s", method, url, exc)
+            return None
+
+        if not response.content:
+            return None
+        try:
+            payload = response.json()
+        except ValueError:  # noqa: PERF203 - only attempt JSON when present
+            self._logger.warning("Response from %s %s was not JSON", method, url)
+            return None
+        if isinstance(payload, (dict, list)):
+            return payload
+        return None

lexicon/resources/__init__.py

@@ -0,0 +1,15 @@
+"""Resource module exports."""
+
+from .playlist_tracks import PlaylistTracks
+from .playlists import Playlists
+from .tag_categories import TagCategories
+from .tags import Tags
+from .tracks import Tracks
+
+__all__ = [
+    "PlaylistTracks",
+    "Playlists",
+    "TagCategories",
+    "Tags",
+    "Tracks",
+]

lexicon/resources/_common_types.py

@@ -0,0 +1,228 @@
+"""Shared types and validation helpers for resources.
+
+This module contains:
+- Validation mode type (shared across all resources)
+- Color type definitions and normalization (used by tag_categories)
+- Common validation normalizers (ID sequences, etc.)
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Literal, Sequence, get_args
+
+from ..utils import unique_in_order
+
+_logger = logging.getLogger(__name__)
+
+# --- Shared Validation Mode --- #
+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",
+]
+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
+)
+
+
+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) -> 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
+    -------
+    tuple[int, int, int] or None
+        RGB tuple (0-255), or ``None`` when the input is ``None``.
+
+    Raises
+    ------
+    ValueError
+        If the input cannot be parsed as a color value.
+    """
+    if value is None:
+        return None
+    if isinstance(value, str):
+        if value.strip().lower() == "none":
+            return None
+        if value in COLORS:
+            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]
+            return (
+                int(hex_value[0:2], 16),
+                int(hex_value[2:4], 16),
+                int(hex_value[4:6], 16),
+            )
+        raise ValueError(f"Unsupported string input {value!r}")
+
+    if isinstance(value, int):
+        if value < 0:
+            raise ValueError(f"Negative packed int {value!r}")
+        if value > 0xFFFFFF:
+            value = value & 0xFFFFFF
+        return ((value >> 16) & 0xFF, (value >> 8) & 0xFF, value & 0xFF)
+
+    if isinstance(value, (tuple, list)) and len(value) in (3, 4):
+        rgb_values = value[:3]
+        if all(isinstance(channel, (int, float)) for channel in rgb_values):
+            rgb = []
+            for channel in rgb_values:
+                channel_value = float(channel)
+                if channel_value <= 1:
+                    channel_value *= 255
+                rgb.append(int(max(0, min(255, round(channel_value)))))
+            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
+    best_distance = float("inf")
+    for index, candidate in enumerate(COLOR_RGBS):
+        dr = rgb[0] - candidate[0]
+        dg = rgb[1] - candidate[1]
+        db = rgb[2] - candidate[2]
+        distance = dr * dr + dg * dg + db * db
+        if distance < best_distance:
+            best_distance = distance
+            best_index = index
+    return COLORS[best_index]
+
+
+# --- 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.
+    Filters out any non-integer elements and values < 1, then deduplicates.
+    """
+    if isinstance(ids, int):
+        id_list = [ids]
+    elif isinstance(ids, Sequence) and not isinstance(ids, (str, bytes)):
+        id_list = list(ids)
+    else:
+        return None
+
+    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
+
+    return unique_in_order(valid_ids)

lexicon/resources/base.py

@@ -0,0 +1,69 @@
+"""Base resource helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ..client import Lexicon
+
+
+class Resource:
+    """Shared helpers for resource classes."""
+
+    def __init__(self, client: "Lexicon") -> None:
+        self._client = client
+
+    @property
+    def _logger(self):
+        return self._client._logger
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict[str, Any] | list[tuple[str, Any]]] = None,
+        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
+        )
+
+    def _get(
+        self,
+        path: str,
+        *,
+        params: Optional[dict[str, Any] | list[tuple[str, Any]]] = None,
+        timeout: Optional[int] = None,
+    ) -> Optional[dict[str, Any] | list[Any]]:
+        return self._request("GET", path, params=params, timeout=timeout)
+
+    def _post(
+        self,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]] = None,
+        timeout: Optional[int] = None,
+    ) -> Optional[dict[str, Any] | list[Any]]:
+        return self._request("POST", path, json=json, timeout=timeout)
+
+    def _patch(
+        self,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]] = None,
+        timeout: Optional[int] = None,
+    ) -> Optional[dict[str, Any] | list[Any]]:
+        return self._request("PATCH", path, json=json, timeout=timeout)
+
+    def _delete(
+        self,
+        path: str,
+        *,
+        params: Optional[dict[str, Any] | list[tuple[str, Any]]] = None,
+        json: Optional[dict[str, Any]] = None,
+        timeout: Optional[int] = None,
+    ) -> Optional[dict[str, Any] | list[Any]]:
+        return self._request("DELETE", path, params=params, json=json, timeout=timeout)