lexicon-python 0.2.0__tar.gz → 0.3.0__tar.gz

{lexicon_python-0.2.0/src/lexicon_python.egg-info → lexicon_python-0.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: lexicon-python
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python client for the Lexicon DJ API
 Author-email: Garrison Burger <burgerga123@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/photonicvelocity/lexicon-python
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: InquirerPy>=0.3
@@ -41,12 +41,6 @@ management, and metadata edits while keeping a clean escape hatch to the raw API
 pip install lexicon-python
 ```
 
-Optional (for interactive playlist chooser):
-
-```bash
-pip install InquirerPy
-```
-
 ## Quickstart
 
 ```python
@@ -320,10 +314,80 @@ For full payload schemas and endpoint details, refer to the Lexicon API docs:
 
 ## Development
 
+### Setup
+
+#### Pip 
+
+Ensure that you have Python 3.9+ installed locally.
+To install all runtime and dev dependencies into a local virtual environment using pip:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+#### uv
+
+To use [uv](https://docs.astral.sh/uv/) to install all runtime and dev dependencies into a local virtual environment, simply install `uv` and run:
+
+```bash
+uv sync --dev
+```
+
+The lockfile (`uv.lock`) is checked in to ensure reproducible installs.
+
+### Running Tests
+
 ```bash
-./.venv/bin/python -m pytest --cov --cov-branch --cov-report=term-missing
+# Unit tests
+make run-tests
+
+# Integration tests (requires Lexicon running)
+# Note: Integration tests enforce an empty library state to avoid destructive edits on existing libraries.
+# The fixture setup will back up the existing library, clear it for testing, and restore it afterward.
+make run-integration-tests
 ```
 
+### Linting and Formatting
+
+The project uses [ruff](https://docs.astral.sh/ruff/) for both linting and
+formatting.
+
+`make test` runs the full suite: format, lint (with auto-fix), then tests.
+`make fix` runs all auto-fixers (lint + format) without running tests.
+
+```bash
+make test               # format-fix → lint-fix → format-check → lint-check → tests
+make fix                # lint-fix → format-fix
+make clean              # remove __pycache__, .pytest_cache, .ruff_cache, etc.
+```
+
+If you want to run the linters or formatters manually, you can use the following commands:
+
+```bash
+make lint-check         # check for lint issues
+make lint-fix           # auto-fix lint issues
+make format-check       # check formatting
+make format-fix         # auto-fix formatting
+```
+
+### CI
+
+GitHub Actions runs on every push to `main` and on pull requests
+targeting those branches. The pipeline includes:
+
+- **Tests** across Python 3.9, 3.10, 3.11, and 3.12
+- **Lint and format checks** via ruff on Python 3.12
+
+Before opening a PR, make sure `make test` passes locally.
+
+### Pull Requests
+
+A PR template is provided at `.github/pull_request_template.md`. When opening a
+PR, fill in the description, check the relevant change-type boxes, and confirm
+testing/checklist items.
+
 ## License
 
 MIT (see `LICENSE`).

{lexicon_python-0.2.0 → lexicon_python-0.3.0}/README.md

@@ -26,12 +26,6 @@ management, and metadata edits while keeping a clean escape hatch to the raw API
 pip install lexicon-python
 ```
 
-Optional (for interactive playlist chooser):
-
-```bash
-pip install InquirerPy
-```
-
 ## Quickstart
 
 ```python
@@ -305,10 +299,80 @@ For full payload schemas and endpoint details, refer to the Lexicon API docs:
 
 ## Development
 
+### Setup
+
+#### Pip 
+
+Ensure that you have Python 3.9+ installed locally.
+To install all runtime and dev dependencies into a local virtual environment using pip:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+#### uv
+
+To use [uv](https://docs.astral.sh/uv/) to install all runtime and dev dependencies into a local virtual environment, simply install `uv` and run:
+
+```bash
+uv sync --dev
+```
+
+The lockfile (`uv.lock`) is checked in to ensure reproducible installs.
+
+### Running Tests
+
 ```bash
-./.venv/bin/python -m pytest --cov --cov-branch --cov-report=term-missing
+# Unit tests
+make run-tests
+
+# Integration tests (requires Lexicon running)
+# Note: Integration tests enforce an empty library state to avoid destructive edits on existing libraries.
+# The fixture setup will back up the existing library, clear it for testing, and restore it afterward.
+make run-integration-tests
 ```
 
+### Linting and Formatting
+
+The project uses [ruff](https://docs.astral.sh/ruff/) for both linting and
+formatting.
+
+`make test` runs the full suite: format, lint (with auto-fix), then tests.
+`make fix` runs all auto-fixers (lint + format) without running tests.
+
+```bash
+make test               # format-fix → lint-fix → format-check → lint-check → tests
+make fix                # lint-fix → format-fix
+make clean              # remove __pycache__, .pytest_cache, .ruff_cache, etc.
+```
+
+If you want to run the linters or formatters manually, you can use the following commands:
+
+```bash
+make lint-check         # check for lint issues
+make lint-fix           # auto-fix lint issues
+make format-check       # check formatting
+make format-fix         # auto-fix formatting
+```
+
+### CI
+
+GitHub Actions runs on every push to `main` and on pull requests
+targeting those branches. The pipeline includes:
+
+- **Tests** across Python 3.9, 3.10, 3.11, and 3.12
+- **Lint and format checks** via ruff on Python 3.12
+
+Before opening a PR, make sure `make test` passes locally.
+
+### Pull Requests
+
+A PR template is provided at `.github/pull_request_template.md`. When opening a
+PR, fill in the description, check the relevant change-type boxes, and confirm
+testing/checklist items.
+
 ## License
 
 MIT (see `LICENSE`).

{lexicon_python-0.2.0 → lexicon_python-0.3.0}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lexicon-python"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python client for the Lexicon DJ API"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [
   {name = "Garrison Burger", email = "burgerga123@gmail.com"}
 ]
@@ -19,6 +19,15 @@ dependencies = [
   "typing_extensions>=4.0"
 ]
 
+[dependency-groups]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0",
+    "ipython>=8.12.3",
+]
+
 [project.urls]
 Homepage = "https://github.com/photonicvelocity/lexicon-python"
 
@@ -28,6 +37,17 @@ where = ["src"]
 [tool.setuptools]
 package-dir = {"" = "src"}
 
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+  "integration: integration tests requiring a running Lexicon instance",
+]
+addopts = "-m 'not integration'"
+
+[tool.uv]
+# Dev dependencies are specified in [dependency-groups]
+default-groups = ["dev"]
+
 [tool.pydocstyle]
 convention = "numpy"
 

lexicon_python-0.3.0/src/lexicon/__init__.py

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

{lexicon_python-0.2.0 → lexicon_python-0.3.0}/src/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_python-0.2.0 → lexicon_python-0.3.0}/src/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_python-0.2.0 → lexicon_python-0.3.0}/src/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,