mirror of
https://github.com/beetbox/beets.git
synced 2026-05-16 16:00:56 -04:00
5bc11ea736
There have been multiple requests, in the past, for the ability to use
plugin fields in inline fields. This has not previously been available.
From what I can tell, it was intentionally left unavailable due to
performance concerns.
The way the item fields are made available to the inline python code
means that all fields are looked up, whether they're actually used by
the code or not. Doing that for all computed fields would be a
performance concern.
I don't believe there's a good way to postpone the field computation, as
python eval and compile requires that globals be a dictionary, not a
mapping. Instead, we can make available the album or item model object
to the code directly, and let the code access the fields it needs via
that object, resulting in postponing the computation of the fields until
they're actually accessed.
This is a simple approach that makes the computed and plugin fields
available to inline python, which allows for more code reuse, as well as
more options for shifting logic out of templates and into python code.
The object is available as `db_obj`.
Examples:
item_fields:
test_file_size: db_obj.filesize
album_fields:
test_album_path: db_obj.path
# If the missing plugin is enabled
test_album_missing: db_obj.missing
Signed-off-by: Christopher Larson <kergoth@gmail.com>
76 lines
2.6 KiB
ReStructuredText
76 lines
2.6 KiB
ReStructuredText
Inline Plugin
|
|
=============
|
|
|
|
The ``inline`` plugin lets you use Python to customize your path formats. Using
|
|
it, you can define template fields in your beets configuration file and refer to
|
|
them from your template strings in the ``paths:`` section (see
|
|
:doc:`/reference/config/`).
|
|
|
|
To use the ``inline`` plugin, enable it in your configuration (see
|
|
:ref:`using-plugins`). Then, make a ``item_fields:`` block in your config file.
|
|
Under this key, every line defines a new template field; the key is the name of
|
|
the field (you'll use the name to refer to the field in your templates) and the
|
|
value is a Python expression or function body. The Python code has all of a
|
|
track's normal fields in scope, so you can refer to these attributes (such as
|
|
``artist`` or ``title``) as Python variables. The Python code also has direct
|
|
access to the item or album object as ``db_obj``. This allows use of computed
|
|
fields and plugin fields, for example, ``db_obj.albumtotal``, or
|
|
``db_obj.missing`` if the :doc:`/plugins/missing` plugin is enabled.
|
|
|
|
Here are a couple of examples of expressions:
|
|
|
|
::
|
|
|
|
item_fields:
|
|
initial: albumartist[0].upper() + u'.'
|
|
disc_and_track: f"{disc:02d}.{track:02d}" if disctotal > 1 else f"{track:02d}"
|
|
|
|
Note that YAML syntax allows newlines in values if the subsequent lines are
|
|
indented.
|
|
|
|
These examples define ``$initial`` and ``$disc_and_track`` fields that can be
|
|
referenced in path templates like so:
|
|
|
|
::
|
|
|
|
paths:
|
|
default: $initial/$artist/$album%aunique{}/$disc_and_track $title
|
|
|
|
Block Definitions
|
|
-----------------
|
|
|
|
If you need to use statements like ``import``, you can write a Python function
|
|
body instead of a single expression. In this case, you'll need to ``return`` a
|
|
result for the value of the path field, like so:
|
|
|
|
::
|
|
|
|
item_fields:
|
|
filename: |
|
|
import os
|
|
from beets.util import bytestring_path
|
|
return bytestring_path(os.path.basename(path))
|
|
|
|
You might want to use the YAML syntax for "block literals," in which a leading
|
|
``|`` character indicates a multi-line block of text.
|
|
|
|
Album Fields
|
|
------------
|
|
|
|
The above examples define fields for *item* templates, but you can also define
|
|
fields for *album* templates. Use the ``album_fields`` configuration section. In
|
|
this context, all existing album fields are available as variables along with
|
|
``items``, which is a list of items in the album.
|
|
|
|
This example defines a ``$bitrate`` field for albums as the average of the
|
|
tracks' fields:
|
|
|
|
::
|
|
|
|
album_fields:
|
|
bitrate: |
|
|
total = 0
|
|
for item in items:
|
|
total += item.bitrate
|
|
return total / len(items)
|