rekordbox-edit 0.6.0.dev44__tar.gz → 0.6.0.dev48__tar.gz

rekordbox_edit-0.6.0.dev48/.github/actions/commit-check/action.yml

@@ -0,0 +1,28 @@
+name: "Commit Check"
+description: "Validate commit messages and the PR title against the Conventional Commits schema"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Checkout
+      uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      with:
+        fetch-depth: 0
+
+    - name: Setup UV
+      uses: ./.github/actions/install
+
+    - name: Validate commit messages
+      shell: bash
+      run: |
+        uv run cz check --rev-range origin/main..HEAD
+
+    # The PR title becomes the commit message when a branch is squash-merged,
+    # so validate it too. Pass via env to avoid shell injection from the title.
+    - name: Validate PR title
+      if: ${{ github.event_name == 'pull_request' }}
+      shell: bash
+      env:
+        PR_TITLE: ${{ github.event.pull_request.title }}
+      run: |
+        uv run cz check --message "$PR_TITLE"

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/.github/actions/install/action.yml

@@ -8,10 +8,6 @@ runs:
       uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
       with:
         enable-cache: true
-
-    - name: Set up Python
-      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
-      with:
         python-version: ${{ env.PYTHON }}
 
     - name: Install dependencies

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/.github/actions/lint/action.yml

@@ -12,12 +12,6 @@ runs:
     - name: Setup UV
       uses: ./.github/actions/install
 
-    - name: Validate Conventional Commits
-      shell: bash
-      if: ${{ github.ref != 'refs/heads/main' }}
-      run: |
-        uv run cz check --rev-range origin/main..HEAD
-
     - name: Run lint
       shell: bash
       run: |

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/.github/workflows/ci.yml

@@ -31,6 +31,19 @@ jobs:
               paths_ignore:
                 - '**/*.md'
 
+  commit-check:
+    name: 📝 Commits
+    if: ${{ github.event_name == 'pull_request' }}
+    runs-on: ubuntu-slim
+    env:
+      PYTHON: "3.14"
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Validate commits and PR title
+        uses: ./.github/actions/commit-check
+
   lint:
     name: 🧺 Lint
     runs-on: ubuntu-latest
@@ -94,6 +107,7 @@ jobs:
     name: ✅ All Green
     if: always()
     needs:
+      - commit-check
       - lint
       - unit-tests
       - e2e-tests
@@ -102,5 +116,5 @@ jobs:
     steps:
       - uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # release/v1
         with:
-          allowed-skips: unit-tests, lint, e2e-tests
+          allowed-skips: commit-check, unit-tests, lint, e2e-tests
           jobs: ${{ toJSON(needs) }}

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/CHANGELOG.md

@@ -1,6 +1,10 @@
-## v0.6.0.dev44 (2026-06-12)
+## v0.6.0.dev48 (2026-06-12)
 
 
+- chore(deps): update dependency mkdocstrings to v1
+- ci: setup python via setup-uv to fix cache key collisions
+- ci: validate conventional commits always, check PR titles
+- docs: clean up documentation
 - chore(deps): update linters to v0.0.45 (#90)
 - Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
 - refactor: rename CommandArgs types to CommandRequest

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to Rekordbox Bulk Edit
 
-Thanks for your interest in contributing to this project! Python is not my expertise, so I'm eager for those more seasoned than I to weigh in. One way or another, I hope you're here as a fellow DJ looking to make managing a RekordBox library easier :)
+Thanks for your interest in contributing to this project! I think I've done a good job thus far, but Python is not my expertise so I'm eager for those more seasoned than I to weigh in. One way or another, I hope you're here as a fellow DJ looking to make managing a RekordBox library easier :)
 
 ## Development Setup
 
@@ -59,15 +59,24 @@ Thanks for your interest in contributing to this project! Python is not my exper
 # Run tests
 make test
 
+# Watch tests
+make watch 
+
 # Run tests with coverage
 make coverage
 
-# Run linting and type-checking, will auto-fix issues
+# Run linting, will auto-fix issues
 make lint
 
+# Run type-checking
+make typcheck
+
 # Run formatting
 make format
 
+# Run the docsite locally
+make docs
+
 # Run all pre-commit hooks on all files
 make run-hooks
 ```
@@ -76,7 +85,7 @@ make run-hooks
 
 This project uses and enforces [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). The allowable types of commits are:
 
-- `BREAKING`: introduces breaking changes (major bump)
+- `BREAKING` or `feat!`: introduces breaking changes (major bump)
 - `feat`: introduces new features (minor bump)
 - `fix`: patches a bug, upgrades a dependency (minor bump)
 

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rekordbox-edit
-Version: 0.6.0.dev44
+Version: 0.6.0.dev48
 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
@@ -26,13 +26,17 @@ Description-Content-Type: text/markdown
 [![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.
+A command-line tool for bulk operations on your Rekordbox library. Search tracks, edit metadata, and convert between audio formats with the benefit of database updates that preserve all your cues, analyses, 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)
 
+> [!WARNING]
+> This project is in active development with no stable version released yet.
+> Breaking changes are likely to occur across version 0 releases until the API and behavior stabilizes.
+
 **Full documentation: [rekordbox-edit.readthedocs.io](https://rekordbox-edit.readthedocs.io/)**
 
 ## Installation
@@ -58,7 +62,7 @@ rbe search --playlist "House Favorites"
 Edit track metadata:
 
 ```bash
-# Fix a typo across every matching title (previews and confirms first)
+# Fix a typo across every matching track title
 rbe edit --title "Teh" Title --match "Teh" --replace "The" --multi
 ```
 
@@ -68,8 +72,8 @@ Convert audio files:
 # 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
+# Convert all FLAC or WAV files to AIFF without confirming
+rbe convert --format flac --format wav --format-out aiff --yes
 ```
 
 See the [documentation](https://rekordbox-edit.readthedocs.io/) for every command, the full filtering language, and scripting recipes.
@@ -88,21 +92,21 @@ See the [documentation](https://rekordbox-edit.readthedocs.io/) for every comman
 
    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.
+And more generally you should 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
+## Credits
 
-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.
+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 interacting with the Rekordbox database.
 
-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.
+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.
 
-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!
+## AI Usage
 
-## Credits
+I believe it's important to be aware of and to disclose AI usage. The way its presence and usage is forced on us from every direction is too often gross and oppressive, and it's used almost exclusively for capitalist profit.
 
-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'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 goals of completing it. This being said, 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 a stranger on the internet!
 
-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.
+p.s. 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. :3
 
 ## Contributing
 

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/README.md

@@ -6,13 +6,17 @@
 [![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.
+A command-line tool for bulk operations on your Rekordbox library. Search tracks, edit metadata, and convert between audio formats with the benefit of database updates that preserve all your cues, analyses, 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)
 
+> [!WARNING]
+> This project is in active development with no stable version released yet.
+> Breaking changes are likely to occur across version 0 releases until the API and behavior stabilizes.
+
 **Full documentation: [rekordbox-edit.readthedocs.io](https://rekordbox-edit.readthedocs.io/)**
 
 ## Installation
@@ -38,7 +42,7 @@ rbe search --playlist "House Favorites"
 Edit track metadata:
 
 ```bash
-# Fix a typo across every matching title (previews and confirms first)
+# Fix a typo across every matching track title
 rbe edit --title "Teh" Title --match "Teh" --replace "The" --multi
 ```
 
@@ -48,8 +52,8 @@ Convert audio files:
 # 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
+# Convert all FLAC or WAV files to AIFF without confirming
+rbe convert --format flac --format wav --format-out aiff --yes
 ```
 
 See the [documentation](https://rekordbox-edit.readthedocs.io/) for every command, the full filtering language, and scripting recipes.
@@ -68,21 +72,21 @@ See the [documentation](https://rekordbox-edit.readthedocs.io/) for every comman
 
    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.
+And more generally you should 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
+## Credits
 
-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.
+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 interacting with the Rekordbox database.
 
-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.
+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.
 
-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!
+## AI Usage
 
-## Credits
+I believe it's important to be aware of and to disclose AI usage. The way its presence and usage is forced on us from every direction is too often gross and oppressive, and it's used almost exclusively for capitalist profit.
 
-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'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 goals of completing it. This being said, 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 a stranger on the internet!
 
-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.
+p.s. 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. :3
 
 ## Contributing
 

rekordbox_edit-0.6.0.dev48/docs/api.md

@@ -0,0 +1,92 @@
+# 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 SearchRequest
+
+db = Rekordbox6Database()
+response = search(db, SearchRequest(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
+
+The models form three layers: the [`FilterArgs`][rekordbox_edit.models.FilterArgs] base that every command shares, the per-command requests and responses, and the lower-level domain types those req/resp models are built from.
+
+::: rekordbox_edit.models.FilterArgs
+    options:
+      heading_level: 3
+
+### Search
+
+::: rekordbox_edit.models.SearchRequest
+    options:
+      heading_level: 4
+
+::: rekordbox_edit.models.SearchResponse
+    options:
+      heading_level: 4
+
+### Edit
+
+::: rekordbox_edit.models.EditRequest
+    options:
+      heading_level: 4
+
+::: rekordbox_edit.models.EditResponse
+    options:
+      heading_level: 4
+
+::: rekordbox_edit.models.EditResult
+    options:
+      heading_level: 4
+
+### Convert
+
+::: rekordbox_edit.models.ConvertRequest
+    options:
+      heading_level: 4
+
+::: rekordbox_edit.models.ConvertResponse
+    options:
+      heading_level: 4
+
+::: rekordbox_edit.models.ConvertResult
+    options:
+      heading_level: 4
+
+### Miscellaneous
+
+::: rekordbox_edit.models.Track
+    options:
+      heading_level: 4
+
+::: rekordbox_edit.models.EditOp
+    options:
+      heading_level: 4
+
+::: rekordbox_edit.models.ConvertOp
+    options:
+      heading_level: 4
+
+::: rekordbox_edit.models.SkippedTrack
+    options:
+      heading_level: 4
+
+::: rekordbox_edit.models.SkipReason
+    options:
+      heading_level: 4

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/docs/commands/convert.md

@@ -35,7 +35,9 @@ rbe convert --format-out aiff --format flac --print ids --dry-run
 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.
+### Guardrails
+- Without flags, `convert` shows every planned change and asks once before applying. `--interactive` confirms each track individually; `--dry-run` previews without writing; `--yes` confirms the default choice for all prompts without asking.
+- Editing while Rekordbox is open risks corrupting your database. By default `convert` warns; in a non-interactive mode (e.g. `--print ids`) it throws an error.
 
 ## Reference
 

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/docs/commands/edit.md

@@ -6,7 +6,7 @@ Bulk-edit a metadata field on tracks in your Rekordbox database.
 rbe edit [OPTIONS] [TRACK-IDS]... FIELD
 ```
 
-`FIELD` names the metadata field to change. Currently `Title` is the only editable field; more are planned.
+`FIELD` specifies the [DjmdContent](https://pyrekordbox.readthedocs.io/en/latest/formats/db6.html#djmdcontent) column 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:
 
@@ -18,11 +18,11 @@ rbe edit --exact-title "Untitled 3" Title --replace "Acid Rain"
 rbe edit --title "Teh" Title --match "Teh" --replace "The" --multi
 ```
 
-## Safety Rails
+## Guardrails
 
-- **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).
+- **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` confirms the default choice for all prompts without asking.
+- **Single-track by default.** When filters match more than one track, `edit` refuses unless you pass `--multi`. This prevents an unintentionally broad filter from making unintended edits across your library.
+- **Rekordbox running:** editing while Rekordbox is open risks corrupting your database. By default `edit` warns; in a non-interactive mode (e.g. `--print ids`) it throws an error.
 
 ## Examples
 

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/docs/filtering.md

@@ -1,10 +1,10 @@
 # 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.
+Every command supports filtering by all of the [`FilterArgs`][rekordbox_edit.models.FilterArgs]. The filters determine which tracks a command operates on.
 
 ## 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).
+Repeating a filter, or combining different filters, matches tracks that satisfy *any* of the provided filters. Pass `--match-all` to require *every* filter to match.
 
 | Option | Matches tracks whose... |
 | --- | --- |
@@ -20,11 +20,17 @@ Repeating a filter, or combining different filters, matches tracks that satisfy
 | `--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) |
+| `--first N` | return only the first N results |
+| `--last N` | return only the last N results |
 
-**Examples:**
+> [!TIP]
+> Filters that are "exact" are case-sensitive (e.g. `--exact-artist 'HOOBASTANK'` won't match "Hoobastank") whereas their counterparts (`--artist`) are case-insensitive and match substrings. Only one of either the `--first` and `--last` filters can be provided at a time as they're mutually exclusive.
+
+
+### Examples
 
 ```bash
-# Tracks by either artist (OR)
+# Tracks by either artist
 rbe search --artist "Daft Punk" --artist "Justice"
 
 # Tracks matching artist AND format
@@ -39,20 +45,13 @@ 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 first 10 tracks whose path contains a folder or filename substring
+rbe search --path "Favorites/" --path "track.wav" --first 10
 
 # 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:
@@ -68,14 +67,14 @@ Track IDs can also arrive on stdin (see [Scripting and Piping](#scripting-and-pi
 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
+- `debug`: adds application state detail; debug logs for every run are also written to a log file (the path to which is shown in `--help`)
+- `silent`: no output at all
+- `ids`: print only the matching track IDs, space-separated — designed for piping between consecutive `rbe` commands.
 - `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.
+    `silent`, `ids`, and `json` are non-interactive print modes, so they require `--yes` or `--dry-run`.
 
 ## Scripting and Piping
 
@@ -86,12 +85,12 @@ All commands take `--print [silent|ids|info|debug|json]`:
 rbe search --artist "Lauryn Hill" --print ids | rbe convert --yes
 ```
 
-Piping composes OR and AND logic that a single command cannot express:
+Piping allows you to compose OR and AND logic that a single command could not express by itself:
 
 **AND-narrowing** — pipe a broad OR result into a second command with `--match-all` to intersect:
 
 ```bash
-# (Daft Punk OR Justice) AND flac
+# Search all (Daft Punk OR Justice) AND flac
 rbe search --artist "Daft Punk" --artist "Justice" --print ids \
   | rbe search --format flac --match-all
 ```
@@ -99,10 +98,10 @@ rbe search --artist "Daft Punk" --artist "Justice" --print ids \
 **OR between AND-groups** — merge results from two commands using a subshell:
 
 ```bash
-# (Daft Punk AND flac) OR (Justice AND aiff)
+# Convert all (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.
+For richer pipelines, `--print json` emits the same selection as structured data for `jq` and other shell tools. Use the [API functions](/api/#functions) if you want to build a more complex python script.

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/mkdocs.yml

@@ -37,6 +37,7 @@ plugins:
             show_if_no_docstring: true
             show_signature_annotations: true
             separate_signature: true
+            signature_crossrefs: true
             docstring_section_style: table
 
 markdown_extensions:

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rekordbox-edit"
-version = "0.6.0.dev44"
+version = "0.6.0.dev48"
 description = "Tools for managing and modifying a RekordBox library en-masse"
 authors = [{ name = "James Viall", email= "jamesviall@pm.me"}]
 license = "MIT"
@@ -35,7 +35,7 @@ dev = [
 ]
 docs = [
     "mkdocs-material>=9.5,<10",
-    "mkdocstrings[python]>=0.27,<1",
+    "mkdocstrings[python]>=1,<2",
     "mkdocs-click>=0.8,<1",
     "markdown-callouts>=0.4,<1",
     "mkdocs-open-in-new-tab>=1.0,<2",

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/rekordbox_edit/api/convert.py

@@ -14,8 +14,8 @@ from sqlalchemy import select
 
 from rekordbox_edit.api._utils import _order_tracks_by_op
 from rekordbox_edit.models import (
-    ConvertRequest,
     ConvertOp,
+    ConvertRequest,
     ConvertResponse,
     ConvertResult,
     SkippedTrack,
@@ -248,8 +248,8 @@ def convert(
     With `dry_run=True`, returns the planned conversions without any ffmpeg or
     DB writes. With `dry_run=False` (default), commits the changes.
 
-    The rollback block protects only pre-commit work; once commit lands, the
-    transaction is honoured even if the delete-originals loop or response
+    The rollback block protects only pre-commit work; once a database commit lands,
+    the transaction is honoured even if the delete-originals loop or response
     re-query later fails.
     """
     from rekordbox_edit.utils import ffmpeg_in_path, get_ffmpeg_directions

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/rekordbox_edit/models.py

@@ -4,21 +4,22 @@ Three layers:
 
 - **Filter base** (`FilterArgs`) declares track-selection criteria shared by all
   commands.
-- **Command args** (`SearchRequest`, `EditRequest`, `ConvertRequest`) extend `FilterArgs`
+- **API/Command request models** (`SearchRequest`, `EditRequest`, `ConvertRequest`) extend `FilterArgs`
   with command-specific fields.
-- **Domain types** (`Track`, `EditOp`, `ConvertOp`, `SkippedTrack`) and
-  **response envelopes** (`SearchResponse`, `EditResponse`, `ConvertResponse`)
+- **API/Command response models** (`SearchResponse`, `EditResponse`, `ConvertResponse`)
   describe what each command returns.
+- **Domain types** (`Track`, `EditOp`, `ConvertOp`, `SkippedTrack`)
+  which help describe the internals of requests/responses
 
-Envelope semantics:
+Response semantics:
 
 - `tracks` always reflects the **current DB state** at the moment the response
   was built. Pre-execute for dry-runs, post-execute for write runs.
-- `result` summarizes what happened (or would happen in a dry-run). Result
-  envelopes carry operation identity (the field name for edit, the target
-  format for convert) so a response is fully self-describing.
-- `tracks` and `result.edits` / `result.converted` align 1:1 by index;
-  validators enforce equal lengths.
+- `result` summarizes what happened (or would happen in a dry-run). Response
+  models should self describe the operation that happened (e.g. the field name
+  for edit, the target format for convert) so a response is fully self-describing.
+- `tracks` and `result.edits` / `result.converted` align 1:1 in their contents and
+  order by index;
 """
 
 from typing import Literal, TypeAlias
@@ -89,9 +90,10 @@ class ConvertRequest(FilterArgs):
 
 class Track(BaseModel):
     """A Rekordbox track.
-    Field names mirror the [DjmdContent](https://pyrekordbox.readthedocs.io/en/latest/formats/db6.html#djmdcontent) table's column names,
-    except where additional derived fields have been added for convenience. All database columns are silently included in each object
-    for convenience, but what's defined here is just what RBE cares about.
+    Field names mirror the [DjmdContent](https://pyrekordbox.readthedocs.io/en/latest/formats/db6.html#djmdcontent)
+    table's column names, except where additional derived fields have been added for convenience.
+    What's defined here are just the fields RBE cares about, but all database columns and their raw
+    are silently included in each Track instance, and are included in `--print json`.
     """
 
     model_config = ConfigDict(extra="allow")
@@ -125,7 +127,9 @@ SkipReason: TypeAlias = Literal[
 
 
 class SkippedTrack(BaseModel):
-    """A track the command declined to operate on."""
+    """A track the command declined to operate on.
+    e.g. A result in a [convert][rekordbox_edit.api.convert] command that is already the target format.
+    """
 
     id: str
     reason: SkipReason

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/uv.lock

@@ -727,7 +727,7 @@ wheels = [
 
 [[package]]
 name = "mkdocstrings"
-version = "0.30.1"
+version = "1.0.4"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "jinja2" },
@@ -737,9 +737,9 @@ dependencies = [
     { name = "mkdocs-autorefs" },
     { name = "pymdown-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/c5/33/2fa3243439f794e685d3e694590d28469a9b8ea733af4b48c250a3ffc9a0/mkdocstrings-0.30.1.tar.gz", hash = "sha256:84a007aae9b707fb0aebfc9da23db4b26fc9ab562eb56e335e9ec480cb19744f", size = 106350, upload-time = "2025-09-19T10:49:26.446Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/1d/5d/f888d4d3eb31359b327bc9b17a212d6ef03fe0b0682fbb3fc2cb849fb12b/mkdocstrings-1.0.4.tar.gz", hash = "sha256:3969a6515b77db65fd097b53c1b7aa4ae840bd71a2ee62a6a3e89503446d7172", size = 100088, upload-time = "2026-04-15T09:16:53.376Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/7b/2c/f0dc4e1ee7f618f5bff7e05898d20bf8b6e7fa612038f768bfa295f136a4/mkdocstrings-0.30.1-py3-none-any.whl", hash = "sha256:41bd71f284ca4d44a668816193e4025c950b002252081e387433656ae9a70a82", size = 36704, upload-time = "2025-09-19T10:49:24.805Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/94/be70f8ee9c45f2f62b39a1f0e9303bc20e138a8f3b8e50ffd89498e177e1/mkdocstrings-1.0.4-py3-none-any.whl", hash = "sha256:63464b4b29053514f32a1dbbf604e52876d5e638111b0c295ab7ed3cac73ca9b", size = 35560, upload-time = "2026-04-15T09:16:51.436Z" },
 ]
 
 [package.optional-dependencies]
@@ -1268,7 +1268,7 @@ wheels = [
 
 [[package]]
 name = "rekordbox-edit"
-version = "0.6.0.dev44"
+version = "0.6.0.dev48"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -1328,7 +1328,7 @@ docs = [
     { name = "mkdocs-click", specifier = ">=0.8,<1" },
     { name = "mkdocs-material", specifier = ">=9.5,<10" },
     { name = "mkdocs-open-in-new-tab", specifier = ">=1.0,<2" },
-    { name = "mkdocstrings", extras = ["python"], specifier = ">=0.27,<1" },
+    { name = "mkdocstrings", extras = ["python"], specifier = ">=1,<2" },
 ]
 
 [[package]]

rekordbox_edit-0.6.0.dev44/docs/api.md

@@ -1,28 +0,0 @@
-# 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 SearchRequest
-
-db = Rekordbox6Database()
-response = search(db, SearchRequest(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.dev44 → rekordbox_edit-0.6.0.dev48}/rekordbox_edit/cli/convert.py

@@ -37,9 +37,9 @@ logger = logging.getLogger(__name__)
 )
 @add_click_options(
     [
-        *global_click_filters,
-        *global_click_confirmations,
         *convert_click_options,
+        *global_click_confirmations,
+        *global_click_filters,
         print_option,
         track_ids_argument,
     ]

{rekordbox_edit-0.6.0.dev44 → rekordbox_edit-0.6.0.dev48}/rekordbox_edit/cli/edit.py

@@ -37,9 +37,9 @@ logger = logging.getLogger(__name__)
 )
 @add_click_options(
     [
-        *global_click_filters,
-        *global_click_confirmations,
         *edit_click_options,
+        *global_click_confirmations,
+        *global_click_filters,
         print_option,
     ]
 )