Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Sort and categorize config_default.yaml #4987

Merged
merged 7 commits into from
Dec 17, 2023
Merged

Sort and categorize config_default.yaml #4987

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
9f5e6ed
Sort and categorize config_default.yaml
RollingStar Nov 3, 2023
ec3d9b9
Merge pull request #1 from RollingStar/config_sort
RollingStar Nov 3, 2023
69493d0
Remove fixme
RollingStar Dec 4, 2023
ca1edab
Merge branch 'beetbox:master' into master
RollingStar Dec 4, 2023
ae8866f
Update changelog.rst for config_default
RollingStar Dec 4, 2023
9f958b8
Update docs/changelog.rst
RollingStar Dec 17, 2023
d927262
Merge branch 'master' into master
RollingStar Dec 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 51 additions & 30 deletions beets/config_default.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,34 @@
# --------------- Main ---------------

library: library.db
directory: ~/Music
statefile: state.pickle

# --------------- Plugins ---------------

plugins: []
pluginpath: []

# --------------- Import ---------------

clutter: ["Thumbs.DB", ".DS_Store"]
ignore: [".*", "*~", "System Volume Information", "lost+found"]
ignore_hidden: yes

import:
# common options
write: yes
copy: yes
move: no
timid: no
quiet: no
log:
# other options
default_action: apply
languages: []
quiet_fallback: skip
none_rec_action: ask
# rare options
link: no
hardlink: no
reflink: no
Expand All @@ -13,15 +37,8 @@ import:
incremental: no
incremental_skip_later: no
from_scratch: no
quiet_fallback: skip
none_rec_action: ask
timid: no
log:
autotag: yes
quiet: no
singletons: no
default_action: apply
languages: []
detail: no
flat: no
group_albums: no
Expand All @@ -37,10 +54,13 @@ import:
ignored_alias_types: []
singleton_album_disambig: yes

clutter: ["Thumbs.DB", ".DS_Store"]
ignore: [".*", "*~", "System Volume Information", "lost+found"]
ignore_hidden: yes
# --------------- Paths ---------------

path_sep_replace: _
drive_sep_replace: _
asciify_paths: false
art_filename: cover
max_filename_length: 0
replace:
# Replace bad characters with _
# prohibited in many filesystem paths
Expand All @@ -60,11 +80,6 @@ replace:
# starting and closing whitespace
'\s+$': ''
'^\s+': ''
path_sep_replace: _
drive_sep_replace: _
asciify_paths: false
art_filename: cover
max_filename_length: 0

aunique:
keys: albumartist album
Expand All @@ -76,21 +91,27 @@ sunique:
disambiguators: year trackdisambig
bracket: '[]'

overwrite_null:
album: []
track: []
# --------------- Tagging ---------------

plugins: []
pluginpath: []
threaded: yes
timeout: 5.0
per_disc_numbering: no
verbose: 0
terminal_encoding:
original_date: no
artist_credit: no
id3v23: no
va_name: "Various Artists"
paths:
default: $albumartist/$album%aunique{}/$track $title
singleton: Non-Album/$artist/$title
comp: Compilations/$album%aunique{}/$track $title

# --------------- Performance ---------------

threaded: yes
timeout: 5.0

# --------------- UI ---------------

verbose: 0
terminal_encoding:

ui:
terminal_width: 80
Expand Down Expand Up @@ -126,6 +147,8 @@ ui:
match_tracklist: 5
layout: column

# --------------- Search ---------------

format_item: $artist - $album - $title
format_album: $albumartist - $album
time_format: '%Y-%m-%d %H:%M:%S'
Expand All @@ -135,13 +158,11 @@ sort_album: albumartist+ album+
sort_item: artist+ album+ disc+ track+
sort_case_insensitive: yes

paths:
default: $albumartist/$album%aunique{}/$track $title
singleton: Non-Album/$artist/$title
comp: Compilations/$album%aunique{}/$track $title

statefile: state.pickle
# --------------- Autotagger ---------------

overwrite_null:
album: []
track: []
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a very interesting catch! Do you want to quickly open a "missing docs" issue for it. Someone "who knows" might want do document it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW it's not too uncommon for us to have undocumented config options. The way I think about this is that an undocumented option is better than not having the option at all (i.e., to have a magic number in the code). Sometimes these are undocumented intentionally, because we mostly hope people will not use them except in special circumstances, and sometimes we just haven't gotten around to it yet. In yet a third category, it might just be so specific that it seems like not worth the space in the docs page!

I'm not 100% certain which category to put overwrite_null in. Probably just missing docs that we should add? But maybe it's just hyper-specific with an audience that rounds down to zero. FWIW, it was added in #3133.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The use case of this is I'm in my config or config_default more often than you might think. But it feels like I'm changing "basic" parts more often. Plugins, timid/quiet, replace/inline/paths are probably my most common changes. The esoteric and undocumented parts most people will never touch. This PR is about taming the beast of config_default and make it a more useful starting point for a user config.

This PR is secretly part 1 of 3 or more:

  1. sort config
  2. sort config page of docs
  3. split config page of docs into basic/advanced
  4. split config yaml into basic/advanced yamls (not sure how hard it would be to have cascading configs; I think JOJ0 does this now).
  5. move inline function definitions to their own user_inline.py file to take advantage of code markup and symbol definitions in IDEs

In an ideal world I think every config option would at least point to the PR it was added, or the part of the code it exists in. That's often what I'm looking at when trying to figure out if a config feature is something I need to change. But even linking that stuff may be too much work for very esoteric options.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Working on the docs page to prioritize the most important stuff seems great!

While it also seems like a good idea to organize config_default.yaml, I am, in general, not sure we should be relying on it to be a "starting point" for user configs… I really hope that most people don't need to copy & paste the entirety of config_default.yaml and can just adjust exactly what they need to change.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really hope that most people don't need to copy & paste the entirety of config_default.yaml

Okay, I'm not married to that idea. The reason I started with copying config_default for my personal config is I wanted to read through the config page and make sure I wasn't "missing" any options that would be helpful. Keeping the default value doesn't hurt anything (unless the value changes). [Also, I think part of it was I'm using the LSIO container and they change the config to their own default, and I wanted to change it back and take back control of the config.]

I wonder if there's a way to give people a blank config with the categories in this PR already filled in (possibly in the docs page). The user is free to use that or not, but it might help them keep some semblance of organization. Configs can get out of hand.

A sorted config_default also helps with maintenance on our end.

Copy link
Member

@JOJ0 JOJ0 Nov 29, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest as a first step we could finalize this PR by doing these things:

  • Remove the comment about the undocumented feature but add a proper entry to the documentation. Or if that's not possible at this time or seems tedious, just leave an issue about a missing config entry.
  • Merge the sorted config_default.yaml / Merge this PR

PS: I want to find time to comment on other points and ideas you mentioned @RollingStar soon! :-)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good to me!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll add the undocumented feature to the docs when i sort the page to match the new default yaml.

Copy link
Member

@JOJ0 JOJ0 Dec 7, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The use case of this is I'm in my config or config_default more often than you might think. But it feels like I'm changing "basic" parts more often. Plugins, timid/quiet, replace/inline/paths are probably my most common changes. The esoteric and undocumented parts most people will never touch. This PR is about taming the beast of config_default and make it a more useful starting point for a user config.

I feel you. Often I find myself changing things back and forth between beets runs. What I find most helpful is controlling things via cli options. If we don't have them we should add them. Recently @mgoltzsche opened a bunch of PR's doing just that, which I very much appreciate.

This PR is secretly part 1 of 3 or more:

  1. sort config

very good idea

  1. sort config page of docs

very good idea

  1. split config page of docs into basic/advanced

sometimes hard to decide what's basic and what not. that's what I actually tried to say with my (probably bad) hardlinking example. I think it's rather advanced. Others might think differently.

All that aside please go ahead with that idea , we can nitpick about it over there :-) Great idea!

  1. split config yaml into basic/advanced yamls (not sure how hard it would be to have cascading configs; I think JOJ0 does this now).

Not really like that but I use config overlays as a last resort solution. I also use shell aliases heavily. Best in my opinion is having complex beet commands consisting of --long-options (for readability) but saving them in .zshrc. If you forgot what it was alias somebeetalias prints it.

also -c overlay.yaml could be contained in such a shell alias. For example sometimes I want Spotify as the preferred source. Stuff like that (source score) is not layed out as --options

About all that I wanted to make a discussions/showandtell post for a long time now already and never find the time.

For some things simply including via include: is enough...I do that with longish things like smartplaylist defs.

one more thing helpful, especially when coding and reviewing beets stuff: custom shell prompts depending on python venv, $BEETSDIR, ... all controllable/switchable via zsh aliases

  1. move inline function definitions to their own user_inline.py file to take advantage of code markup and symbol definitions in IDEs

That is an awesome idea and might not even be extremly hard to implement. It should be configurable though so existing inline configs dont break. Maybe a new config option that enables that inline: is ignored but a separate inline.py is looked for in $BEETSDIR. Or even better, look for an inline_album.py and inline_item.py

In an ideal world I think every config option would at least point to the PR it was added, or the part of the code it exists in. That's often what I'm looking at when trying to figure out if a config feature is something I need to change. But even linking that stuff may be too much work for very esoteric options.

Indeed often I look up where and why something was implemented. But keeping track of that is impossible. The best thing for that would be our changelog. Usually it links to an issue though, so after looking that up the PR that closed it needs to be looked up after that in the often messy github message history.

Should we keep track not only about the issue but also the PR implementing it, right within the changelog? Would that improve something?

musicbrainz:
enabled: yes
host: musicbrainz.org
Expand Down
1 change: 1 addition & 0 deletions docs/changelog.rst
View file
Open in desktop
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can't get docs to render on my PC so I can't test this.

Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,7 @@ New features:
plugin which allows to replace fields based on a given library query.
* :doc:`/plugins/lyrics`: Add LRCLIB as a new lyrics provider and a new
`synced` option to prefer synced lyrics over plain lyrics.
* Sorted the default configuration file :ref: into categories.
RollingStar marked this conversation as resolved.
Show resolved Hide resolved

Bug fixes:

Expand Down
Loading