Fix handling multi valued fields by snejus · Pull Request #6387 · beetbox/beets

snejus · 2026-02-22T01:23:50Z

While working on #6367 I noticed that users are currently required to use our internal separator \␀ in order to edit multi-valued fields, for example beet modify artists='a\␀b'.

Similarly, this separator is used in output, for example, reporting of field changes:

$ beet modify path::aaa artists='a\␀b'
Modifying 8 items.
54898 | 2022 / RAVE SLUTZ: Fallen Shrine & dj Christian NXC - DEEEJAAAY
  artists: Fallen Shrine\␀dj Christian NXC -> a\␀b

This PR replaces \␀ separator with ; for input and formats changes in multi-valued fields clearly:

$ beet modify path::aaa artists='a; b'
54898 | 2022 / RAVE SLUTZ: Fallen Shrine & dj Christian NXC - DEEEJAAAY
  artists:
    - Fallen Shrine
    - dj Christian NXC
    + a
    + b

Architecture-level changes

DelimitedString now separates concerns between:
- database serialization via db_delimiter (to_sql)
- user-facing/template formatting via a fixed '; ' delimiter (format)
- parsing that accepts both DB and user-facing separators (parse)
Field diff rendering now has a dedicated path for list fields:
- _field_diff detects list values
- _multi_value_diff computes set-based added/removed entries and renders per-item diff lines
Coloring responsibilities were streamlined:
- raw ANSI application moved to _colorize
- colorize is now only the feature-flag/environment gate
- colordiff is reduced to string diff highlighting logic, with redundant wrapper logic removed

High-level impact

Multi-valued fields behave consistently between DB storage and CLI/template usage ('; ' for user input/output, DB delimiter internally).
Diff output for list fields is much more readable, showing explicit +/- item-level changes instead of generic string diffs.
Docs and tests were updated to reflect the new multi-value behavior, including %first usage and beet modify examples.

github-actions · 2026-02-22T01:24:02Z

Thank you for the PR! The changelog has not been updated, so here is a friendly reminder to check if you need to add an entry.

Copilot

Pull request overview

This PR improves multi-valued field handling by separating user-facing and database delimiters, enhancing diff output readability, and refactoring color formatting logic. The change makes beet modify and field display more user-friendly by replacing the internal \␀ separator with ; for user input and output.

Changes:

DelimitedString type now uses ; for formatting/user input and \␀ for database serialization
Field diffs for list values display per-item changes with +/- prefixes instead of string comparison
Color formatting refactored into _colorize (raw ANSI) and colorize (feature-gated wrapper)

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
beets/dbcore/types.py	Separated database delimiter (`\␀`) from user-facing delimiter (`;` ) in DelimitedString type
beets/ui/init.py	Added list-aware diff rendering, refactored colorize/colordiff functions
beets/library/models.py	Updated tmpl_first documentation to remove redundant info
docs/reference/pathformat.rst	Expanded %first function documentation with examples and clearer parameter descriptions
docs/reference/cli.rst	Added guidance for modifying multi-valued fields
docs/conf.py	Added semicolon_space RST substitution for consistent documentation
test/ui/test_field_diff.py	Added tests for multi-value field diff rendering
test/test_plugins.py	Updated test assertion for new delimiter format
test/test_library.py	Updated %first function tests to use appropriate field types

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

codecov · 2026-02-22T01:31:14Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 69.17%. Comparing base (940e94c) to head (edfe005).
⚠️ Report is 6 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6387      +/-   ##
==========================================
+ Coverage   69.13%   69.17%   +0.03%     
==========================================
  Files         140      140              
  Lines       18684    18686       +2     
  Branches     3055     3053       -2     
==========================================
+ Hits        12918    12926       +8     
+ Misses       5119     5115       -4     
+ Partials      647      645       -2

Files with missing lines	Coverage Δ
beets/dbcore/types.py	`96.01% <100.00%> (+0.03%)`	⬆️
beets/library/models.py	`87.10% <ø> (ø)`
beets/ui/__init__.py	`83.60% <100.00%> (+0.90%)`	⬆️
beets/ui/commands/import_/display.py	`82.59% <100.00%> (ø)`
beetsplug/edit.py	`85.62% <100.00%> (ø)`

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

snejus · 2026-02-22T12:06:51Z

@amogus07 I see you've given the PR a thumbs-up. Would you mind reviewing it as well? 😆

amogus07 · 2026-02-22T12:47:41Z

@amogus07 I see you've given the PR a thumbs-up. Would you mind reviewing it as well? 😆

I'm not that familiar with these parts of the codebase, unfortunately... I'm just glad this is finally being addressed

JOJ0 · 2026-02-22T14:31:50Z

I will review and test this later today!

- Use '\␀' as the DB delimiter while formatting lists with '; ' for templates. - Update DelimitedString parsing to accept both separators: * '\␀' for the values from the DB * '; ' for the rest of parsed values (for example `beet modify genres="eletronic; jazz"`) - Refresh %first docs and tests to reflect multi-value field behavior.

JOJ0

Damnit forgot to add my final message in my previous review: Overall many many thanks! Great stuff here!. When testing add-multiple-genres I had similar thoughts: We need to find a way to make delimiters passing more user friendly. This null character is only suitable for actual storing. Well done, great solution you provided here!

Also adding a tiny test idea here in this subseuqent review. Not sure. What do you say?

JOJ0 · 2026-02-22T19:50:03Z

This failing test seems unrelated: https://github.com/beetbox/beets/actions/runs/22280727644/job/64450831853?pr=6387

snejus · 2026-02-22T20:44:06Z

Actually, I thinkw we'd also like to adjust edit plugin:

Currently we have:

album: RAVE SLUTZ
album_id: 11492
albumartist: Fallen Shrine & dj Christian NXC
albumstatus: Official
albumtype: album
albumtypes: album
artist: Fallen Shrine & dj Christian NXC
artist_sort: ''
artists: Fallen Shrine; dj Christian NXC

While I imagine we'd instead like to have:

album: RAVE SLUTZ
album_id: 11492
albumartist: Fallen Shrine & dj Christian NXC
albumstatus: Official
albumtype: album
albumtypes:
- album
artist: Fallen Shrine & dj Christian NXC
artist_sort: ''
artists:
- Fallen Shrine
- dj Christian NXC

JOJ0

Let's go ahead then 😍

JOJ0 · 2026-02-22T22:19:45Z

Actually, I thinkw we'd also like to adjust edit plugin:

Currently we have:

album: RAVE SLUTZ

album_id: 11492

albumartist: Fallen Shrine & dj Christian NXC

albumstatus: Official

albumtype: album

albumtypes: album

artist: Fallen Shrine & dj Christian NXC

artist_sort: ''

artists: Fallen Shrine; dj Christian NXC

While I imagine we'd instead like to have:

album: RAVE SLUTZ

album_id: 11492

albumartist: Fallen Shrine & dj Christian NXC

albumstatus: Official

albumtype: album

albumtypes:

- album

artist: Fallen Shrine & dj Christian NXC

artist_sort: ''

artists:

- Fallen Shrine

- dj Christian NXC

Hmm interesting idea, since it's yaml...

Do this in a subsequent PR? For now it's good enough in my opinion. Played with edit before and didn't miss anything, but yeah would be a great and self-explanatory feature!

snejus · 2026-02-23T00:30:30Z

It kinds of belongs here, what do you think? The change was just two lines, so I added it here:

Note: I use edit quite a lot 😅

Treat DelimitedString as a safe YAML-editable type in the edit plugin, allowing multi-valued fields to be edited as native lists.

JOJ0 · 2026-02-24T07:01:59Z

sure! edit! sorry was busy this weekend orherwise. good you included it! thanks!

See: beetbox/beets#6387

Copilot AI review requested due to automatic review settings February 22, 2026 01:23

snejus requested a review from a team as a code owner February 22, 2026 01:23

snejus requested review from JOJ0 and henry-oberholtzer February 22, 2026 01:23

Copilot started reviewing on behalf of snejus February 22, 2026 01:24 View session

Copilot AI reviewed Feb 22, 2026

View reviewed changes

Comment thread docs/reference/pathformat.rst Outdated

Comment thread beets/dbcore/types.py

Comment thread beets/dbcore/types.py

Comment thread test/ui/test_field_diff.py

snejus force-pushed the fix-handling-multi-valued-fields branch 6 times, most recently from 748934b to 03114e1 Compare February 22, 2026 12:06

snejus mentioned this pull request Feb 22, 2026

Add multiple genres #6367

Merged

snejus force-pushed the fix-handling-multi-valued-fields branch from 03114e1 to 54a46bd Compare February 22, 2026 15:57

snejus added 3 commits February 22, 2026 16:12

Colorize multi-valued field changes distinctly

31f79f1

Remove redundant coloring logic

4699958

snejus force-pushed the fix-handling-multi-valued-fields branch from 54a46bd to 4699958 Compare February 22, 2026 16:17

JOJ0 reviewed Feb 22, 2026

View reviewed changes

JOJ0 requested changes Feb 22, 2026

View reviewed changes

Comment thread test/test_plugins.py

JOJ0 approved these changes Feb 22, 2026

View reviewed changes

Handle DelimitedString fields as native lists in edit plugin

edfe005

Treat DelimitedString as a safe YAML-editable type in the edit plugin, allowing multi-valued fields to be edited as native lists.

snejus force-pushed the fix-handling-multi-valued-fields branch from d5abe35 to edfe005 Compare February 23, 2026 00:33

snejus merged commit 2ea7886 into master Feb 23, 2026
22 checks passed

snejus deleted the fix-handling-multi-valued-fields branch February 23, 2026 01:14

Morikko added a commit to Morikko/beets-multivalue that referenced this pull request Mar 11, 2026

Add some tests about native list compatibility

a1fcee5

See: beetbox/beets#6387

Conversation

snejus commented Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Architecture-level changes

High-level impact

Uh oh!

github-actions Bot commented Feb 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

snejus commented Feb 22, 2026

Uh oh!

amogus07 commented Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JOJ0 commented Feb 22, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JOJ0 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JOJ0 commented Feb 22, 2026

Uh oh!

snejus commented Feb 22, 2026

Uh oh!

JOJ0 left a comment

Choose a reason for hiding this comment

Uh oh!

JOJ0 commented Feb 22, 2026

Uh oh!

snejus commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

JOJ0 commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

snejus commented Feb 22, 2026 •

edited

Loading

codecov Bot commented Feb 22, 2026 •

edited

Loading

amogus07 commented Feb 22, 2026 •

edited

Loading

snejus commented Feb 23, 2026 •

edited

Loading

JOJ0 commented Feb 24, 2026 •

edited

Loading