Metadata-Version: 2.4
Name: lexicon-python
Version: 0.5.1
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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: InquirerPy>=0.3
Requires-Dist: requests>=2.31
Requires-Dist: typing_extensions>=4.0
Dynamic: license-file

# Lexicon Python

Python client for the Lexicon DJ Local API.

This SDK wraps the Lexicon Local API with resource groups, sensible defaults, and optional validation. It is designed
for scripting library automation, playlist management, and metadata edits while keeping a clean escape hatch to the raw
API.

## Features

- Resource grouped client (`lex.tracks`, `lex.playlists`, `lex.tags`, `lex.player`)
- Player and hotkey commands via `lex.player` and `lex.control()`
- Pagination handled for `tracks.list()` and `tracks.search()` (API returns 1000 per page)
- Lexicon v1.12 app approval and tokens, with v1.11 still supported
- Validation modes for inputs: warn (default), strict, or off
- Typed responses and payload hints (TypedDicts and Literals)
- Optional interactive playlist chooser via `InquirerPy`
- Raw request escape hatch via `lex.request(...)`

## Requirements

- Python 3.10+
- Lexicon DJ running with the Local API enabled (Lexicon settings, Local API). Lexicon v1.12 is the target; v1.11 works
  for everything that existed in it (see [Lexicon versions](#lexicon-versions)).

## Install

```bash
pip install lexicon-python
```

## Quickstart

```python
from lexicon import Lexicon

# Verifies the API is reachable; raises LexiconConnectionError otherwise. On Lexicon v1.12
# the first run shows the user a popup asking to allow the app; see Authentication.
lex = Lexicon(app_name="My Lexicon Tool")
playlist = lex.playlists.choose()

# list tracks (default fields: id, artist, title, bpm, key, ...)
tracks = lex.tracks.list(limit=10) or []
for t in tracks:
    print(t.get("artist"), "-", t.get("title"))

# search — pass fields=[...] for a narrow projection, or fields="all" for the
# full payload (tempomarkers, cuepoints, tags, etc.)
results = lex.tracks.search({"artist": "Daft Punk"}) or []
print("matches:", len(results))

# get a single track by id — always returns the full record
full = lex.tracks.get(123)

# get a playlist by path
playlist = lex.playlists.get_by_path(["Genres", "Drum & Bass"], playlist_type="folder")
print(playlist)
```

## Configuration

By default the client targets:

- Host: `localhost`
- Port: `48624`

You can override these via constructor args or environment variables.

```python
lex = Lexicon(host="127.0.0.1", port=48624, raise_on_error=False)
```

Other options:

- `default_timeout`: request timeout in seconds
- `session`: optional `requests.Session`
- `raise_on_error`: raise HTTP errors instead of returning None
- `verify_connection` (default `True`): probe the API on construction and raise `LexiconConnectionError` if Lexicon
  isn't reachable, or `LexiconAuthError` if it refuses the app. Set to `False` to build a client without a running
  Lexicon (e.g. for tests).
- `app_name` (default `"lexicon-python"`): the name the user sees in Lexicon's approval popup and settings.
- `token`: the app's API token for Lexicon v1.12 (see below).

Environment variables:

```bash
export LEXICON_HOST=localhost
export LEXICON_PORT=48624         # Lexicon v1.12 lets the user change it in the Local API settings
export LEXICON_APP_NAME="My Lexicon Tool"
export LEXICON_TOKEN=...          # optional, see Authentication
```

## Authentication

Starting in Lexicon v1.12, the user has to allow each app before it can use the API. Every request names the app in the
`X-Lexicon-App` header (`app_name`, default `"lexicon-python"`). Lexicon asks once per name, so give each tool its own.

- **First run:** the first request from a new app name shows the user a popup, and Lexicon holds the request until they
  answer. `Lexicon()` waits up to 70 seconds for that. When the user allows the app, Lexicon sends a token, which the
  client keeps in `lex.token`.
- **On the computer running Lexicon:** an allowed app is let in by name alone, so a local script needs no token.
- **From another device:** every request needs the token. Store `lex.token` and pass it back as `token=` or
  `LEXICON_TOKEN`. Lexicon only keeps a hash, so it cannot show the token again.
- **Pairing explicitly:** `lex.pair()` asks the user right away (waiting up to two minutes) and returns the token.
- **Personal scripts:** the user can instead copy the API token from the Lexicon settings under Local API. Lexicon
  always lets that token in.

```python
from lexicon import Lexicon, LexiconAuthError

try:
    lex = Lexicon(app_name="My Lexicon Tool", token=load_saved_token())
except LexiconAuthError as exc:
    print(exc.error_code, exc)  # 10: not answered yet, 6: blocked, 11: allowed but token missing
```

`LexiconAuthError` (a `LexiconConnectionError`) carries Lexicon's error code:

| Code | Meaning                                                                                        |
| ---- | ---------------------------------------------------------------------------------------------- |
| `10` | The popup was not answered in time, or was closed. Lexicon waits a minute before asking again. |
| `6`  | The user blocked the app. Unblock it in the Lexicon settings.                                  |
| `11` | The name is already allowed, but the request did not send its token.                           |
| `9`  | The token is wrong, or the request looked like it came from a web page.                        |

The user can block or remove an app at any time in the Lexicon settings, which stops its token from working. Lexicon
v1.11 and older have no authentication and ignore these headers.

## Validation Modes

Many methods accept a `validation` parameter with three modes:

- `"warn"` (default): invalid inputs are skipped with a warning. This avoids API failures, but intended changes may be
  ignored.
- `"strict"`: invalid inputs raise `ValueError`.
- `"off"`: skips normalization and sends inputs as-is (inputs must match API-native shapes)

Example:

```python
lex.tracks.search({"rating": "bad"}, validation="warn")   # logs warning
lex.tracks.search({"rating": "bad"}, validation="strict") # raises
lex.tracks.search({"rating": "bad"}, validation="off")    # sends as-is
```

## Convenience vs Raw API

This SDK adds several quality-of-life behaviors on top of the raw Lexicon API. In general, response shapes are unwrapped
(e.g., `"data": {...}` is removed and single-item lists are collapsed to a single dict).

### Additional Methods (Not in the Raw API)

- `tracks.get_many()` repeats `get()` and preserves input order.
- `playlists.get_many()` repeats `get()` and preserves input order.
- `playlists.tracks.get()` fetches track dicts in playlist order.
- `playlists.tracks.update()` replaces the full track list (remove + add).
- `playlists.choose()` provides an interactive chooser (wraps list + get).
- `playlists.get_path()` resolves a path from a playlist tree.

### Input Normalization (Broader Accepted Inputs)

- **ID normalization**: Many methods accept lists of IDs instead of a single ID for easier batch operations.
- **Field selection**: By default, `tracks.list()` and `tracks.search()` return a minimal set of fields rather than the
  full payload:
  - `id`, `artist`, `title`, `albumTitle`, `bpm`, `key`, `duration`, `year`
  - Fields used as a search filter or sort item are also returned.
- **Search filter normalization**:
  - Text fields accept `None` (becomes `"NONE"` in filter context).
  - Numeric filters accept `None` (becomes `"0"`).
  - Date filters accept `YYYY-MM-DD`, full datetime strings, or `datetime.date` / `datetime.datetime` inputs (time is
    stripped).
    - Comparisons (`>YYYY-MM-DD`) are warned/blocked because the API currently ignores them.
- **Sort normalization**:
  - Accepts tuple shorthand: `[("title", "asc")]`.
- **Track update helpers**:
  - Cuepoint and tempomarker entries are normalized (e.g., cuepoint type accepts name/number variants).
  - Invalid entries can be skipped in `"warn"` mode without failing the update.

If no SDK normalization is desired, use `validation="off"` and pass API-native payloads. API-native shapes are also
accepted in `"warn"`/`"strict"`; those modes simply add normalization/validation on top. For fully raw access,
`lex.request(...)` can always be called directly.

## Tracks

Common operations:

```python
track = lex.tracks.get(123)
tracks = lex.tracks.get_many([1, 2, 3])
tracks = lex.tracks.list(limit=100)
tracks = lex.tracks.search({"artist": "Daft Punk"})

added = lex.tracks.add(["/path/to/file1.mp3", "/path/to/file2.mp3"])
updated = lex.tracks.update(123, {"title": "New Title"})
lex.tracks.delete([123, 456])

# Lexicon v1.12: the selection in Lexicon, and relocating a track to another file
ids = lex.tracks.selected()                      # [12, 7, 33]
track = lex.tracks.get("selected")               # the topmost selected track
lex.tracks.update("selected", {"rating": 5})     # every selected track
moved = lex.tracks.update_location(123, "/Music/new/file.mp3")

# Replace tempomarkers while keeping cuepoints anchored to the same beats
lex.tracks.update_tempogrid(123, [{"startTime": 0.0, "bpm": 124.0}])

# Start Lexicon's analyzer on specific tracks
lex.tracks.analyze([123, 456], analyze_beatgrid=True, do_not_overwrite=False)
```

Notes:

- `tracks.search()` returns every match on Lexicon v1.12, which pages results 1000 at a time; pass `limit=` to cap it.
  Lexicon v1.11 returns at most 1000 matches and logs a warning when there are more.
- `tracks.update()` returns the track as Lexicon stored it. On v1.12 that comes from the PATCH response; on older
  versions the client fetches it again.
- A `cuepoints` or `tempomarkers` edit replaces the whole list, and Lexicon clears the `data` of any cue or marker sent
  without it. That `data` holds what a DJ app import stored (Traktor, Rekordbox, ...), so to keep it, edit the list from
  `tracks.get()` and send it back. `update_tempogrid()` does this for cuepoints.
- `tracks.update_location()` only changes the library; the file is never moved. Lexicon normalizes the path, so read
  `location` back from the returned track.
- `tracks.get_many()` preserves input order and returns `None` for missing IDs.
- `tracks.get()` always returns the full record (no `fields` parameter).
- For `tracks.list()` / `tracks.search()`:
  - `fields=None` returns a minimal default set.
    - In `validation="off"` mode, `fields=None` returns the full API payload.
  - Pass a list of field names for a narrow projection (`fields=["id", "location"]`).
  - `fields="all"` or `fields="*"` requests the full payload.
  - Comma-separated strings (e.g. `"id,location"`) are _not_ accepted; pass a list. With `validation="warn"` the call
    falls back to the default field set and logs.
- `tracks.add()` returns track dicts, but analysis fields (tempo markers, key, etc.) may be populated later by Lexicon.
- `tracks.update_tempogrid()` replaces tempomarkers while preserving each cuepoint's beat position by rewriting
  `startTime`/`endTime` against the new grid. Use `tracks.update(track_id, {"tempomarkers": [...]})` directly if you
  want the raw field replacement (cuepoints' seconds stay put, beats shift).
- `tracks.analyze()` returns as soon as Lexicon accepts the request. Analysis runs in the background and the API has no
  completion signal, so poll `tracks.get()` and watch `tempomarkers`, `bpm`, `key`, or `dateModified`.
- `tracks.analyze(tempo_range=...)` takes one of the eight ids Lexicon's analyze dropdown stores: `"0_300"` (Any),
  `"58_115"`, `"68_135"`, `"78_155"`, `"88_175"`, `"98_195"`, `"128_255"`, `"180_300"` (180+). An equivalent
  `(min, max)` tuple works too. The value is written to Lexicon's stored analysis setting and persists after the call;
  the boolean options apply to that run only.

### Track Payload Shapes

Rich-payload fields like `cuepoints` and `tempomarkers` aren't in the default field set; request them explicitly
(`fields=["cuepoints", "tempomarkers"]`) or ask for everything (`fields="all"`). Their shapes are typed via
`CuePointResponse` and `TempoMarkerResponse`, both re-exported from `lexicon`:

```python
from lexicon import TrackResponse, TempoMarkerResponse, CuePointResponse
```

Color values (cuepoint/tag/etc. `color` fields) are Lexicon-specific name strings declared by the `Color` literal type.
To convert a name to RGB:

```python
from lexicon import color_rgb

color_rgb("red_dark")  # → (158, 15, 7)
```

### Track Search, Filters, and Sort

`tracks.search(filter=...)` accepts a dict of field names and values. The SDK validates fields/values in
`"warn"`/`"strict"` modes and can send API-native values in `"off"` mode.

Examples:

```python
# text filters
lex.tracks.search({"artist": "Daft Punk"})

# numeric filters (strings)
lex.tracks.search({"bpm": "120"})
lex.tracks.search({"bpm": "120-128"})
lex.tracks.search({"bpm": ">=120"})
lex.tracks.search({"bpm": "120~128"})  # stops before 128

# date filters (YYYY-MM-DD)
# - ">" is that day and later, "<" is before that day
lex.tracks.search({"dateAdded": "2024-01-01"})
lex.tracks.search({"dateAdded": ">2024-01-01"})

# tag filters (comma-separated names)
# - default: OR across tags
# - prefix with "~" to require ALL tags (AND)
# - prefix with "!" to exclude a tag
lex.tracks.search({"tags": "Rock, Chill"})     # Rock OR Chill
lex.tracks.search({"tags": "~Rock, Chill"})    # Rock AND Chill
lex.tracks.search({"tags": "~Rock, !Chill"})   # Rock AND NOT Chill
lex.tracks.search({"tags": None})              # no tags at all (v1.12)

# Lexicon v1.12: look tracks up by id, or by file extension
lex.tracks.search({"id": [12, 48, 153]}, fields=["id", "title"])
lex.tracks.search({"fileType": "flac"})
```

Tag filter details:

- Input is a single string with comma-separated tag names.
- Whitespace is ignored around commas.
- `~` at the start switches from OR to AND for the list.
- `!` before a tag name negates that tag.
- `None` finds tracks without any tag on Lexicon v1.12 (unless a tag is labeled "None").

Lexicon v1.12 rejects a filter on a field it cannot filter with an error, where v1.11 silently ignored it. The `id`
filter is the dangerous case on v1.11, which ignores it and matches the whole library, so `search()` returns `None` when
more tracks come back than ids were asked for.

Sort can be expressed in two shapes:

- API-native: list of dicts: `[{"field": "title", "dir": "asc"}]`
- Alternative: list of tuples: `[("title", "asc")]`

API-native dicts work in all modes; `validation="off"` requires the dict shape.

## Playlists

```python
playlist = lex.playlists.get(42)
playlist = lex.playlists.get_by_path(["Genres", "Drum & Bass"], playlist_type="playlist")
tree = lex.playlists.list()

new_id = lex.playlists.add("Demo Playlist", playlist_type="playlist", parent_id=1)
lex.playlists.update(new_id, name="Renamed Playlist")
lex.playlists.update(new_id, position=0)  # v1.12: the others shift down, like dragging
lex.playlists.delete([new_id])

selected = lex.playlists.selected()  # v1.12: IDs selected in the playlist tree
```

Playlist type accepts:

- `"folder"`, `"playlist"`, `"smartlist"`
- `1`, `2`, `3` (or string numerals `"1"`, `"2"`, `"3"`)

### Playlist tracks helpers

For getting the tracks of a playlist or editing the tracklist.

```python
track_ids = lex.playlists.tracks.list(42)
tracks = lex.playlists.tracks.get(42)
lex.playlists.tracks.add(42, [1, 2, 3])
lex.playlists.tracks.remove(42, [1, 2])
lex.playlists.tracks.update(42, [3, 2, 1])
```

## Tags

```python
tags = lex.tags.list()
new_tag = lex.tags.add(category_id=1, label="Demo Tag")
lex.tags.update(new_tag["id"], label="Renamed Tag")
lex.tags.delete(new_tag["id"])

categories = lex.tags.categories.list()
new_cat = lex.tags.categories.add(label="Demo Category", color="red")
lex.tags.categories.update(new_cat["id"], label="Renamed Category")
lex.tags.categories.delete(new_cat["id"])

# Lexicon v1.12: reorder a category's tags (every tag it has, in the new order; tags from
# other categories move in), and move the category itself
lex.tags.categories.update(new_cat["id"], tags=[12, 10, 11])
lex.tags.categories.update(new_cat["id"], position=0)
```

## Player

```python
playing = lex.player.playing()  # None when no track is loaded
if playing:
    print(playing["track"]["title"], playing["currentTime"], playing["progress"])

queue = lex.player.queue()  # the tracks after the loaded one
```

`playing()` returns the loaded track whether it is playing or paused. For Beatport, Apple Music, and Spotify tracks,
`track` is not a library row: `id` is the service's own track ID, and `duration` is the length of the preview clip.

## Control

`lex.control()` runs the commands that can be bound to a hotkey. Parameters use their API names.

```python
lex.control("MusicPlayer_TogglePlay")
lex.control("MusicPlayer_Load", id=123)
lex.control("MusicPlayer_Seek", seconds=30)
```

It returns `True` when Lexicon accepts the request. Lexicon does not wait for the action to finish and has no completion
signal, and it accepts an action whose target is missing, such as one for the selected tracks with nothing selected.
Names are checked against the `ControlAction` list; pass `validation="off"` for one that is not listed. The list covers
Lexicon v1.11 and v1.12, so it holds both names of the actions v1.12 renamed: v1.12 calls the `Direct2Cdj_*` player
actions `DeckConnect_*` (`DeckConnect_LoadDeck`, `DeckConnect_LoadDeck1` to `8`, `DeckConnect_LoadEmptyDeck`) and
rejects the old names.

## Tools

Interactive playlist chooser (requires InquirerPy):

```python
choice = lex.playlists.choose()
print(choice)

# Or avoid an API call if you already have the tree
playlist_tree = lex.playlists.list()
choice = lex.tools.playlists.choose_playlist(playlist_tree) if playlist_tree else None
print(choice)
```

Helper to resolve a playlist path from a tree:

```python
path = lex.playlists.get_path(42)
print(path)

# Or avoid an API call if you already have the tree
playlist_tree = lex.playlists.list()
path = lex.tools.playlists.get_path_from_tree(playlist_tree, playlist_id=42)
print(path)

# -> ["Genres", "Drum & Bass"]
```

## Raw Requests (Escape Hatch)

The API can always be accessed directly with `lex.request`:

```python
payload = lex.request("GET", "/tracks", params={"fields": "all"})
```

## Resource Overview

High level namespaces (full mapping in `docs/resource-map.md`):

- `lex.tracks`: get, get_many, list, search, selected, add, update, update_location, update_tempogrid, add_tags,
  remove_tags, delete, analyze
- `lex.playlists`: get, get_many, list (tree root), selected, get_path, get_by_path, add, update, delete, choose
- `lex.playlists.tracks`: list (IDs), get (track dicts), add, remove, update
- `lex.tags`: list, add, update, delete
- `lex.tags.categories`: list, add, update, delete
- `lex.player`: playing, queue
- `lex.control()`: run a control action
- `lex.pair()`: ask the user to allow the app and get its token (v1.12)

## Lexicon versions

The client targets Lexicon v1.12 and keeps working with v1.11. Requests are the same, and the client falls back where
v1.11 answers differently:

| Feature                                              | v1.12                   | v1.11                                                    |
| ---------------------------------------------------- | ----------------------- | -------------------------------------------------------- |
| App approval, `token`, `pair()`                      | required                | no authentication; headers ignored                       |
| `selected()`, `get("selected")`, `update_location()` | yes                     | `None` (endpoint does not exist)                         |
| `search()` past 1000 matches                         | pages through all       | first 1000, with a warning                               |
| `search()` filters `id`, `fileType`, `tags=None`     | yes                     | `id`: `None`; `fileType`: error; `tags=None`: no matches |
| `update()` result                                    | from the PATCH response | fetched again                                            |
| `playlists.update(position=)`                        | inserts, others shift   | stores the number, positions can overlap                 |
| `tags.categories.update(tags=, position=)`           | yes                     | accepted but ignored                                     |
| Cue `activeLoop`                                     | sent as `true`/`false`  | not tested with booleans                                 |
| DeckConnect actions                                  | `DeckConnect_*`         | `Direct2Cdj_*`                                           |

## Type Hints

The SDK includes TypedDict and Literal types for payloads and enums. These are intended to improve editor autocomplete
and static checks.

For full payload schemas and endpoint details, refer to the Lexicon API docs:

- https://www.lexicondj.com/docs/developers/api
- https://www.lexicondj.com/developer/api-docs.yaml

## 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
# 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
```

The integration fixture quits Lexicon and renames `main.db` while it runs. If the Lexicon data folder is synced to
another machine (Syncthing, Dropbox, iCloud), pause the sync first. On Lexicon v1.12 the first run shows an approval
popup for "lexicon-python integration tests"; Lexicon remembers the answer outside the library, so later runs do not ask
again.

### 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
```

### Pre-commit hook (recommended)

The repo ships a [pre-commit](https://pre-commit.com/) config (`.pre-commit-config.yaml`) that mirrors the CI lint job.
After cloning, install the hook once:

```bash
uv tool install pre-commit  # or: pipx install pre-commit
pre-commit install
```

`git commit` now runs `ruff format` + `ruff check --fix` on staged files and blocks the commit on any failure. Run
against the whole repo any time with:

```bash
pre-commit run --all-files
```

The ruff version is pinned in `.pre-commit-config.yaml`; bump it when CI bumps to keep them aligned.

### 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`).
