Alters existing docstrings to follow google's docstring format and adds docstring to Items class. Also updates some typos and updates some block comments to follow PEP 8 style guide.
See https://github.com/beetbox/beets/discussions/4172.
I think the confusion arises because the documentation refers to the
query. That is, when `-a` is given, albums are queried, not tracks. This
is especially clear when using `beet list`, because then it truly lists
"albums instead of items". However, for other commands, the distinction
between what is queried and what is acted on should be made more clear.
This PR fixes the section for `modify`, but there are more questions:
- `remove` command: The documentation states that it acts on albums
instead of individual tracks. I guess we should also amend that? I think
the complete album including the tracks is deleted, or is that not true?
- `move` command: I think the same is true for this command. If `-a` is
given, the queried albums including all tracks are moved.
- `update` command: The `-a` flag is not explained here.
When constructing paths to image files to serve, we previously spliced
strings from URL requests directly into the path to be opened. This is
theoretically worrisome because it could allow clients to read other
files that they are not supposed to read.
I'm not actually sure this is a real security problem because Flask's
URL parsing should probably rule out IDs that have `/` in them anyway.
But out of an abundance of caution, this now prevents paths from showing
up in IDs at all---and also prevents `.` and `..` from being valid
names.
Unit test may fails when path to temprorary library contains `.`; to
garantue that bug wasn't here, it forces to use one more `.` inside path.
Fixes: https://github.com/beetbox/beets/issues/4151
Making these types and queries available is part of fully loading the plugins,
so the event should not be sent until this work is done. This allows plugins
to make use of those types and queries in a pluginload listener.
