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

lexicon/__init__.py

@@ -1,5 +1,8 @@
 """Public package surface for the lexicon Python client."""
 
-from .lexicon import LexiconClient
+from .client import DEFAULT_HOST, LEXICON_PORT, Lexicon
+from .resources.tracks_types import *
 
-__all__ = ["LexiconClient"]
+
+
+__all__ = ["DEFAULT_HOST", "LEXICON_PORT", "Lexicon"]

lexicon/client.py

@@ -0,0 +1,147 @@
+"""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
+DEFAULT_HOST = os.environ.get("LEXICON_HOST", "localhost")
+LEXICON_PORT = int(os.environ.get("LEXICON_PORT", "48624"))
+
+
+class Lexicon:
+    """Resource-grouped client for the Lexicon Local API."""
+
+    tracks: Tracks
+    playlists: Playlists
+    tags: Tags
+    tools: Any
+
+    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,
+    ) -> 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.
+        """
+        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._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 = type("Tools", (), {})()
+        self.tools.playlists = playlist_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,179 @@
+"""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 _normalize_color(value: object) -> Color | None:
+    """Normalize color inputs to the nearest Lexicon color name.
+
+    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``)
+
+    Returns
+    -------
+    Color or None
+        The nearest Lexicon color name, 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 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 = (
+                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):
+        if value < 0:
+            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)
+
+    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 _nearest_color((rgb[0], rgb[1], rgb[2]))
+        raise ValueError(f"Invalid RGB tuple values {value!r}")
+
+    raise ValueError(f"Unsupported input type {type(value)}")
+
+
+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,67 @@
+"""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)