rekordbox-edit 0.6.0.dev29__tar.gz → 0.6.0.dev40__tar.gz

{rekordbox_edit-0.6.0.dev29 → rekordbox_edit-0.6.0.dev40}/.gitignore

@@ -49,3 +49,6 @@ Thumbs.db
 
 .claude
 docs/superpowers
+
+# MkDocs build output
+site/

rekordbox_edit-0.6.0.dev40/.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    install:
+      - uv sync --frozen --group docs
+    build:
+      html:
+        - uv run --group docs mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html
+
+mkdocs:
+  configuration: mkdocs.yml

{rekordbox_edit-0.6.0.dev29 → rekordbox_edit-0.6.0.dev40}/CHANGELOG.md

@@ -1,6 +1,17 @@
-## v0.6.0.dev29 (2026-06-10)
-
-
+## v0.6.0.dev40 (2026-06-11)
+
+
+- docs: add api reference page
+- docs: add convert command page
+- docs: add edit command page
+- docs: add search command page
+- docs: add filtering page
+- docs: configure read the docs build
+- docs: scaffold mkdocs material site
+- docs: trim README to overview and quick start
+- chore: add docs dependency group
+- feat: add --last filter to return only the last N results
+- feat: add --first filter to return only the first N results
 - test(e2e): update windows snapshot with unicode representation
 - test(e2e): force utf-8 encoding of stdout
 - test(e2e): align TZ to UTC

{rekordbox_edit-0.6.0.dev29 → rekordbox_edit-0.6.0.dev40}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: test test-e2e test-e2e-docker test-e2e-snapshot-update coverage lint format typecheck install-hooks run-hooks
+.PHONY: test test-e2e test-e2e-docker test-e2e-snapshot-update coverage lint format typecheck install-hooks run-hooks docs docs-build
 
 test:
 	uv run pytest tests
@@ -34,3 +34,9 @@ install-hooks:
 
 run-hooks:
 	uv run pre-commit run --all-files
+
+docs:
+	uv run --group docs mkdocs serve
+
+docs-build:
+	uv run --group docs mkdocs build --strict

rekordbox_edit-0.6.0.dev40/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: rekordbox-edit
+Version: 0.6.0.dev40
+Summary: Tools for managing and modifying a RekordBox library en-masse
+Project-URL: Homepage, https://github.com/jviall/rekordbox-edit
+Project-URL: Repository, https://github.com/jviall/rekordbox-edit
+Project-URL: Issues, https://github.com/jviall/rekordbox-edit/issues
+Author-email: James Viall <jamesviall@pm.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bulk,convert,database,dj,edit,music,rekordbox
+Requires-Python: >=3.11
+Requires-Dist: click<=9.0.0,>=8.0.0
+Requires-Dist: ffmpeg-python>=0.2.0
+Requires-Dist: platformdirs<5.0.0,>=4.3.8
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: pyrekordbox==0.4.4
+Requires-Dist: rich<15.1.0,>=15.0.0
+Description-Content-Type: text/markdown
+
+# rekordbox-edit
+
+[![Build](https://img.shields.io/github/actions/workflow/status/jviall/rekordbox-edit/cd.yml?branch=main&logo=github&style=flat)](https://github.com/jviall/rekordbox-edit/blob/main/.github/workflows/cd.yml)
+[![Coverage](https://codecov.io/gh/jviall/rekordbox-edit/graph/badge.svg?token=ILZ1XHE61V)](https://codecov.io/gh/jviall/rekordbox-edit)
+[![Version](https://img.shields.io/pypi/v/rekordbox-edit?style=flat)](https://pypi.org/project/rekordbox-edit/)
+[![Platforms](https://img.shields.io/badge/platform-win%20%7C%20osx-blue?style=flat)](https://pypi.org/project/rekordbox-edit/)
+[![License](https://img.shields.io/pypi/l/rekordbox-edit?color=lightgrey)](https://github.com/jviall/rekordbox-edit/blob/main/LICENSE)
+
+A command-line tool for bulk operations on your Rekordbox library. Search tracks, edit metadata, and convert audio formats — updating your database while preserving all your cues, analysis, and metadata.
+
+> [!CAUTION]
+> This tool can modify your Rekordbox database and audio files. Always back up your data first.
+> No warranty is provided--you assume all risk and liability of data loss in using this.
+> See [Safety and Best Practices](#safety-and-best-practices)
+
+**Full documentation: [rekordbox-edit.readthedocs.io](https://rekordbox-edit.readthedocs.io/)**
+
+## Installation
+
+```bash
+pip install rekordbox-edit
+```
+
+**Requirements:**
+
+- Python 3.11+
+- FFmpeg (for audio conversion)
+
+## Quick Start
+
+Search your library:
+
+```bash
+rbe search --artist "Daft Punk" --format flac
+rbe search --playlist "House Favorites"
+```
+
+Edit track metadata:
+
+```bash
+# Fix a typo across every matching title (previews and confirms first)
+rbe edit --title "Teh" Title --match "Teh" --replace "The" --multi
+```
+
+Convert audio files:
+
+```bash
+# Preview what would be converted
+rbe convert --artist "Daft Punk" --dry-run
+
+# Convert all FLAC or WAV files to AIFF (default output format)
+rbe convert --format flac --format wav --yes
+```
+
+See the [documentation](https://rekordbox-edit.readthedocs.io/) for every command, the full filtering language, and scripting recipes.
+
+## Safety and Best Practices
+
+**Before using this tool:**
+
+1. **Back up your Rekordbox database**
+
+   Rekordbox already keeps multiple backups. But every time you close it, it creates a fresh one and deletes the oldest, so repetitive exits will quickly make those backups fairly useless.
+
+   You should make manual copies of RB's database backups before using this. You can usually find them in `~/Library/Pioneer/rekordbox/` on macOS or `%APPDATA%\Pioneer\rekordbox\` on Windows.
+
+2. **Back up your music library**
+
+   If you don't have a back up already it's a very worthwhile investment, even if you don't plan to use this tool! Find yourself a cheap external drive, you won't regret it.
+
+And generally limit the potential impact of a mistake by using filters to target a few tracks at a time e.g. `--artist "Crazy Frog" --first 5` before targeting a larger set, and always run with `--dry-run` first.
+
+## AI Usage
+
+I believe it's important to be aware of and to disclose AI usage. In many ways it's being forced upon us without us having much choice in the matter, and it's a gross and oppressive experience. While it has lots of potential to benefit the common good, mostly it's only furthered capitalist greed.
+
+I'm mostly attempting to thoughtfully disclose that generative AI _has_ been a significant tool in building out this project. I don't personally enjoy too much coding in my personal time, but I feel passionate about making `rekordbox-edit`--AI has admittedly helped me bridge that gap between my capacity and my vision. I'm a career professional software engineer who takes pride in their work, and I don't want to produce a vibe coded mess any more than you want to experience it. Please validate the quality of this project yourself--at the end of the day it's just code written by some stranger.
+
+If it's any consolation, my main test subject has been my own 10,000+ track RekordBox library--a risk I do not take lightly!
+
+## Credits
+
+This project exists thanks to [@dylanjones](https://github.com/dylanjones), the creator of [pyrekordbox](https://github.com/dylanljones/pyrekordbox), which provides the Python API for Rekordbox databases.
+
+I built this tool to help correct my own bad habits and missteps in managing and organizing my rekordbox library. If it helps you too, great! If you find issues or have ideas, contributions are welcome.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/jviall/rekordbox-edit/blob/main/CONTRIBUTING.md) for development setup, testing, and contribution guidelines.

rekordbox_edit-0.6.0.dev40/README.md

@@ -0,0 +1,89 @@
+# rekordbox-edit
+
+[![Build](https://img.shields.io/github/actions/workflow/status/jviall/rekordbox-edit/cd.yml?branch=main&logo=github&style=flat)](https://github.com/jviall/rekordbox-edit/blob/main/.github/workflows/cd.yml)
+[![Coverage](https://codecov.io/gh/jviall/rekordbox-edit/graph/badge.svg?token=ILZ1XHE61V)](https://codecov.io/gh/jviall/rekordbox-edit)
+[![Version](https://img.shields.io/pypi/v/rekordbox-edit?style=flat)](https://pypi.org/project/rekordbox-edit/)
+[![Platforms](https://img.shields.io/badge/platform-win%20%7C%20osx-blue?style=flat)](https://pypi.org/project/rekordbox-edit/)
+[![License](https://img.shields.io/pypi/l/rekordbox-edit?color=lightgrey)](https://github.com/jviall/rekordbox-edit/blob/main/LICENSE)
+
+A command-line tool for bulk operations on your Rekordbox library. Search tracks, edit metadata, and convert audio formats — updating your database while preserving all your cues, analysis, and metadata.
+
+> [!CAUTION]
+> This tool can modify your Rekordbox database and audio files. Always back up your data first.
+> No warranty is provided--you assume all risk and liability of data loss in using this.
+> See [Safety and Best Practices](#safety-and-best-practices)
+
+**Full documentation: [rekordbox-edit.readthedocs.io](https://rekordbox-edit.readthedocs.io/)**
+
+## Installation
+
+```bash
+pip install rekordbox-edit
+```
+
+**Requirements:**
+
+- Python 3.11+
+- FFmpeg (for audio conversion)
+
+## Quick Start
+
+Search your library:
+
+```bash
+rbe search --artist "Daft Punk" --format flac
+rbe search --playlist "House Favorites"
+```
+
+Edit track metadata:
+
+```bash
+# Fix a typo across every matching title (previews and confirms first)
+rbe edit --title "Teh" Title --match "Teh" --replace "The" --multi
+```
+
+Convert audio files:
+
+```bash
+# Preview what would be converted
+rbe convert --artist "Daft Punk" --dry-run
+
+# Convert all FLAC or WAV files to AIFF (default output format)
+rbe convert --format flac --format wav --yes
+```
+
+See the [documentation](https://rekordbox-edit.readthedocs.io/) for every command, the full filtering language, and scripting recipes.
+
+## Safety and Best Practices
+
+**Before using this tool:**
+
+1. **Back up your Rekordbox database**
+
+   Rekordbox already keeps multiple backups. But every time you close it, it creates a fresh one and deletes the oldest, so repetitive exits will quickly make those backups fairly useless.
+
+   You should make manual copies of RB's database backups before using this. You can usually find them in `~/Library/Pioneer/rekordbox/` on macOS or `%APPDATA%\Pioneer\rekordbox\` on Windows.
+
+2. **Back up your music library**
+
+   If you don't have a back up already it's a very worthwhile investment, even if you don't plan to use this tool! Find yourself a cheap external drive, you won't regret it.
+
+And generally limit the potential impact of a mistake by using filters to target a few tracks at a time e.g. `--artist "Crazy Frog" --first 5` before targeting a larger set, and always run with `--dry-run` first.
+
+## AI Usage
+
+I believe it's important to be aware of and to disclose AI usage. In many ways it's being forced upon us without us having much choice in the matter, and it's a gross and oppressive experience. While it has lots of potential to benefit the common good, mostly it's only furthered capitalist greed.
+
+I'm mostly attempting to thoughtfully disclose that generative AI _has_ been a significant tool in building out this project. I don't personally enjoy too much coding in my personal time, but I feel passionate about making `rekordbox-edit`--AI has admittedly helped me bridge that gap between my capacity and my vision. I'm a career professional software engineer who takes pride in their work, and I don't want to produce a vibe coded mess any more than you want to experience it. Please validate the quality of this project yourself--at the end of the day it's just code written by some stranger.
+
+If it's any consolation, my main test subject has been my own 10,000+ track RekordBox library--a risk I do not take lightly!
+
+## Credits
+
+This project exists thanks to [@dylanjones](https://github.com/dylanjones), the creator of [pyrekordbox](https://github.com/dylanljones/pyrekordbox), which provides the Python API for Rekordbox databases.
+
+I built this tool to help correct my own bad habits and missteps in managing and organizing my rekordbox library. If it helps you too, great! If you find issues or have ideas, contributions are welcome.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/jviall/rekordbox-edit/blob/main/CONTRIBUTING.md) for development setup, testing, and contribution guidelines.

rekordbox_edit-0.6.0.dev40/docs/api.md

@@ -0,0 +1,28 @@
+# API Reference
+
+Everything the CLI does is available from Python. The public surface is the three functions in `rekordbox_edit.api` and the Pydantic models in `rekordbox_edit.models` that describe their inputs and outputs.
+
+```python
+from pyrekordbox import Rekordbox6Database
+from rekordbox_edit.api import search
+from rekordbox_edit.models import SearchArgs
+
+db = Rekordbox6Database()
+response = search(db, SearchArgs(artist=["Daft Punk"], format=["flac"], match_all=True))
+for track in response.tracks:
+    print(track.ID, track.Title)
+```
+
+`--print json` on any CLI command emits exactly these response envelopes, so the models below also document the JSON you get when scripting.
+
+## Functions
+
+::: rekordbox_edit.api.search
+
+::: rekordbox_edit.api.edit
+
+::: rekordbox_edit.api.convert
+
+## Models
+
+::: rekordbox_edit.models

rekordbox_edit-0.6.0.dev40/docs/commands/convert.md

@@ -0,0 +1,46 @@
+# convert
+
+Convert audio files between formats and update the Rekordbox database to point at the new files. Your cues, analysis, beatgrids, and all metadata are preserved.
+
+## Supported Formats
+
+- **Input:** FLAC, AIFF, WAV (lossless only — lossy sources are skipped)
+- **Output:** AIFF (default), FLAC, WAV, ALAC, or MP3 (320kbps CBR)
+
+Tracks already in the target format are skipped, as are tracks whose output file already exists (override with `--overwrite`).
+
+## Originals: Delete or Keep
+
+After a successful conversion the original file is **deleted** for lossless output (you can always convert back) and **kept** for MP3 output (the quality loss is one-way). Override either default with `--delete` or `--keep`.
+
+## Examples
+
+```bash
+# Preview conversion
+rbe convert --format-out aiff --format flac --dry-run
+
+# Convert and skip confirmation
+rbe convert --format-out wav --artist "Burial" --yes
+
+# Convert to MP3 but delete originals
+rbe convert --format-out mp3 --playlist "Export" --yes --delete
+
+# Keep originals when converting to AIFF
+rbe convert --format-out aiff --format flac --yes --keep
+
+# Get just the IDs of files that would be converted
+rbe convert --format-out aiff --format flac --print ids --dry-run
+
+# Convert everything a search finds
+rbe search --artist "Lauryn Hill" --print ids | rbe convert --yes
+```
+
+`--interactive` confirms each file individually; like `edit`, converting while Rekordbox is open triggers a warning (or a refusal in scripting modes). See [Filtering](../filtering.md) for the full filter language.
+
+## Reference
+
+::: mkdocs-click
+    :module: rekordbox_edit.cli.convert
+    :command: convert_command
+    :prog_name: rbe convert
+    :depth: 1

rekordbox_edit-0.6.0.dev40/docs/commands/edit.md

@@ -0,0 +1,48 @@
+# edit
+
+Bulk-edit a metadata field on tracks in your Rekordbox database.
+
+```bash
+rbe edit [OPTIONS] [TRACK-IDS]... FIELD
+```
+
+`FIELD` names the metadata field to change. Currently `Title` is the only editable field; more are planned.
+
+`--replace` supplies the new value. On its own it overwrites the whole field; add `--match PATTERN` to find that literal text within the field and replace only that portion:
+
+```bash
+# Rename one track outright
+rbe edit --exact-title "Untitled 3" Title --replace "Acid Rain"
+
+# Fix a typo across many titles (substring replacement)
+rbe edit --title "Teh" Title --match "Teh" --replace "The" --multi
+```
+
+## Safety Rails
+
+- **Preview and confirm by default.** Without flags, `edit` shows every planned change and asks once before applying. `--interactive` confirms each track individually; `--dry-run` previews without writing; `--yes` skips the prompt.
+- **Single-track by default.** When filters match more than one track, `edit` refuses unless you pass `--multi`. This keeps a too-broad filter from rewriting your whole library.
+- **Rekordbox running:** editing while Rekordbox is open risks conflicts, so `edit` warns (or refuses, in scripting modes).
+
+## Examples
+
+```bash
+# Preview a cleanup without touching the database
+rbe edit --title "(Original Mix)" Title --match " (Original Mix)" --replace "" --multi --dry-run
+
+# Apply it, confirming each track
+rbe edit --title "(Original Mix)" Title --match " (Original Mix)" --replace "" --multi --interactive
+
+# Pipe a search result in and edit those exact tracks
+rbe search --playlist "Mislabeled" --print ids | rbe edit Title --match "  " --replace " " --multi --yes
+```
+
+See [Filtering](../filtering.md) for the full filter language.
+
+## Reference
+
+::: mkdocs-click
+    :module: rekordbox_edit.cli.edit
+    :command: edit_command
+    :prog_name: rbe edit
+    :depth: 1

rekordbox_edit-0.6.0.dev40/docs/commands/search.md

@@ -0,0 +1,29 @@
+# search
+
+Find and display tracks in your Rekordbox database. `search` is read-only: it never modifies the database or your files, which makes it the safe way to rehearse a [filter](../filtering.md) before handing it to `edit` or `convert`.
+
+## Examples
+
+```bash
+# Show all FLAC tracks by an artist
+rbe search --artist "Aphex Twin" --format flac
+
+# Get all the track IDs in a playlist
+rbe search --playlist "Techno" --print ids
+
+# Find tracks matching ALL filters (AND logic)
+rbe search --artist "Burial" --album "Untrue" --match-all
+
+# Feed results to another command
+rbe search --artist "Lauryn Hill" --print ids | rbe convert --yes
+```
+
+See [Filtering](../filtering.md) for the full filter language and piping recipes.
+
+## Reference
+
+::: mkdocs-click
+    :module: rekordbox_edit.cli.search
+    :command: search_command
+    :prog_name: rbe search
+    :depth: 1

rekordbox_edit-0.6.0.dev40/docs/filtering.md

@@ -0,0 +1,108 @@
+# Filtering
+
+Every command (`search`, `edit`, `convert`) selects tracks with the same filter options. The filters decide *which* tracks a command sees; the command's own options decide what happens to them.
+
+## Filter Options
+
+Repeating a filter, or combining different filters, matches tracks that satisfy *any* of them (OR logic). Pass `--match-all` to require *every* filter to match (AND logic).
+
+| Option | Matches tracks whose... |
+| --- | --- |
+| `--track-id ID` | database track ID equals `ID` |
+| `--title TEXT` | title contains `TEXT` |
+| `--exact-title TEXT` | title is exactly `TEXT` |
+| `--artist TEXT` | artist name contains `TEXT` |
+| `--exact-artist TEXT` | artist name is exactly `TEXT` |
+| `--album TEXT` | album name contains `TEXT` |
+| `--exact-album TEXT` | album name is exactly `TEXT` |
+| `--playlist TEXT` | playlist name contains `TEXT` |
+| `--exact-playlist TEXT` | playlist name is exactly `TEXT` |
+| `--format FMT` | file format is `FMT` (`mp3`, `flac`, `aiff`, `wav`, `m4a`) |
+| `--path TEXT` | file path contains `TEXT` (matched against the folder path, filename, or both) |
+| `--exact-path TEXT` | file path is exactly `TEXT` (resolved to an absolute path before matching) |
+
+**Examples:**
+
+```bash
+# Tracks by either artist (OR)
+rbe search --artist "Daft Punk" --artist "Justice"
+
+# Tracks matching artist AND format
+rbe search --artist "Aphex Twin" --format flac --match-all
+
+# All the songs in this playlist
+rbe search --exact-playlist "Main Room 2024"
+
+# All the songs in all my "house" or "disco" playlists
+rbe search --playlist "house" --playlist "disco"
+
+# All the songs in my library that aren't in any playlist
+rbe search --playlist ""
+
+# Tracks whose path contains a folder or filename substring
+rbe search --path "Favorites/" --path "track.wav"
+
+# The track at an exact location
+rbe search --exact-path "/Users/djmustard/Music/banger.mp3"
+```
+
+## Limiting Results
+
+- `--first N`: return only the first N results
+- `--last N`: return only the last N results
+
+The two are mutually exclusive. They make a great blast radius limiter while you refine a filter: `rbe convert --artist "Crazy Frog" --first 5 --dry-run`.
+
+## Track ID Arguments
+
+Any positional argument that is not a defined option is interpreted as one or more track IDs:
+
+```bash
+rbe search 12345 67890
+```
+
+Track IDs can also arrive on stdin (see [Scripting and Piping](#scripting-and-piping)). Piped IDs require `--yes` or `--dry-run`, since prompting would interrupt a pipeline.
+
+## Output Levels
+
+All commands take `--print [silent|ids|info|debug|json]`:
+
+- `info` (default): human-readable output
+- `debug`: adds application state detail; debug logs for every run are also written to a log file (the path is shown in `--help`)
+- `silent`: no output
+- `ids`: print only the matching track IDs, space-separated — designed for piping
+- `json`: dump the full response envelope as JSON — a list of [`Track`][rekordbox_edit.models.Track] records plus a result summary (see the response models in the [API Reference](api.md))
+
+!!! note
+
+    `silent`, `ids`, and `json` exist for scripting, so they require `--yes` or `--dry-run`: an interactive confirmation prompt would contradict them.
+
+## Scripting and Piping
+
+`--print ids` output feeds straight into another command's track-ID arguments:
+
+```bash
+# Convert all of the items found by the initial search command
+rbe search --artist "Lauryn Hill" --print ids | rbe convert --yes
+```
+
+Piping composes OR and AND logic that a single command cannot express:
+
+**AND-narrowing** — pipe a broad OR result into a second command with `--match-all` to intersect:
+
+```bash
+# (Daft Punk OR Justice) AND flac
+rbe search --artist "Daft Punk" --artist "Justice" --print ids \
+  | rbe search --format flac --match-all
+```
+
+**OR between AND-groups** — merge results from two commands using a subshell:
+
+```bash
+# (Daft Punk AND flac) OR (Justice AND aiff)
+{ rbe search --artist "Daft Punk" --format flac --match-all --print ids; \
+  rbe search --artist "Justice" --format aiff --match-all --print ids; } \
+  | rbe convert --format-out mp3 --dry-run
+```
+
+For richer pipelines, `--print json` emits the same selection as structured data for `jq` or a Python script.

rekordbox_edit-0.6.0.dev40/docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

rekordbox_edit-0.6.0.dev40/mkdocs.yml

@@ -0,0 +1,54 @@
+site_name: rekordbox-edit
+site_description: Tools for managing and modifying a RekordBox library en-masse
+site_url: https://rekordbox-edit.readthedocs.io/
+repo_url: https://github.com/jviall/rekordbox-edit
+repo_name: jviall/rekordbox-edit
+
+exclude_docs: |
+  superpowers/
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - content.code.copy
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            filters: ["!^_"]
+            show_root_heading: true
+            show_source: false
+            members_order: source
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - github-callouts
+  - mkdocs-click
+  - pymdownx.snippets:
+      base_path: ["."]
+      check_paths: true
+  - pymdownx.superfences
+
+nav:
+  - Getting Started: index.md
+  - Filtering: filtering.md
+  - Commands:
+      - search: commands/search.md
+      - edit: commands/edit.md
+      - convert: commands/convert.md
+  - API Reference: api.md

{rekordbox_edit-0.6.0.dev29 → rekordbox_edit-0.6.0.dev40}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rekordbox-edit"
-version = "0.6.0.dev29"
+version = "0.6.0.dev40"
 description = "Tools for managing and modifying a RekordBox library en-masse"
 authors = [{ name = "James Viall", email= "jamesviall@pm.me"}]
 license = "MIT"
@@ -33,6 +33,12 @@ dev = [
     "ty>=0.0.1,<1",
     "syrupy>=5,<6",
 ]
+docs = [
+    "mkdocs-material>=9.5,<10",
+    "mkdocstrings[python]>=0.27,<1",
+    "mkdocs-click>=0.8,<1",
+    "markdown-callouts>=0.4,<1",
+]
 
 [tool.pytest.ini_options]
 markers = [

{rekordbox_edit-0.6.0.dev29 → rekordbox_edit-0.6.0.dev40}/rekordbox_edit/_click.py

@@ -95,6 +95,18 @@ global_click_filters = [
         multiple=True,
         help="Find tracks of this format",
     ),
+    click.option(
+        "--first",
+        type=click.IntRange(min=1),
+        default=None,
+        help="Return only the first N results",
+    ),
+    click.option(
+        "--last",
+        type=click.IntRange(min=1),
+        default=None,
+        help="Return only the last N results",
+    ),
     click.option(
         "--match-all",
         type=bool,

{rekordbox_edit-0.6.0.dev29 → rekordbox_edit-0.6.0.dev40}/rekordbox_edit/cli/_utils.py

@@ -4,9 +4,10 @@ import functools
 import logging
 import sys
 from copy import copy
+from typing import TypeVar
 
 import click
-from pydantic import BaseModel
+from pydantic import BaseModel, ValidationError
 from pyrekordbox import Rekordbox6Database
 from pyrekordbox.utils import get_rekordbox_pid
 
@@ -17,6 +18,16 @@ logger = logging.getLogger(__name__)
 
 SCRIPTING_MODES = (PrintChoice.IDS, PrintChoice.SILENT, PrintChoice.JSON)
 
+_ArgsT = TypeVar("_ArgsT", bound=BaseModel)
+
+
+def _build_args(model_cls: type[_ArgsT], kwargs: dict) -> _ArgsT:
+    """Construct the command's args model, surfacing validation failures as usage errors."""
+    try:
+        return model_cls(**kwargs)
+    except ValidationError as e:
+        raise click.UsageError("; ".join(err["msg"] for err in e.errors())) from e
+
 
 def _handle_stdin(args) -> bool:
     """Append track IDs from piped stdin to args.track_ids. Returns True if IDs were piped."""
@@ -70,6 +81,8 @@ def _narrow_to_track_ids(args, ids: list[str]):
             setattr(narrowed, field_name, [])
     narrowed.track_ids = list(ids)
     narrowed.match_all = False
+    narrowed.first = None
+    narrowed.last = None
     return narrowed