inline: make the album/item available directly

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.

In items, the object is available as 'item', and in albums, it's
available as 'album'.

Examples:

    item_fields:
      test_file_size: item.filesize

    album_fields:
      test_album_path: album.path
      # If the missing plugin is enabled
      test_album_missing: album.missing

Signed-off-by: Christopher Larson <[email protected]>

beetsplug/inline.py

@@ -33,11 +33,13 @@ def __init__(self, code, exc):
         )
 
 
-def _compile_func(body):
+def _compile_func(body, args=""):
     """Given Python code for a function body, return a compiled
     callable that invokes that code.
     """
-    body = "def {}():\n    {}".format(FUNC_NAME, body.replace("\n", "\n    "))
+    body = "def {}({}):\n    {}".format(
+        FUNC_NAME, args, body.replace("\n", "\n    ")
+    )
     code = compile(body, "inline", "exec")
     env = {}
     eval(code, env)
@@ -84,7 +86,9 @@ def compile_inline(self, python_code, album):
         except SyntaxError:
             # Fall back to a function body.
             try:
-                func = _compile_func(python_code)
+                func = _compile_func(
+                    python_code, args="album" if album else "item"
+                )
             except SyntaxError:
                 self._log.error(
                     "syntax error in inline field definition:\n" "{0}",
@@ -106,6 +110,7 @@ def _dict_for(obj):
             # For expressions, just evaluate and return the result.
             def _expr_func(obj):
                 values = _dict_for(obj)
+                values["album" if album else "item"] = obj
                 try:
                     return eval(code, values)
                 except Exception as exc:
@@ -119,7 +124,7 @@ def _func_func(obj):
                 old_globals = dict(func.__globals__)
                 func.__globals__.update(_dict_for(obj))
                 try:
-                    return func()
+                    return func(obj)
                 except Exception as exc:
                     raise InlineError(python_code, exc)
                 finally:

docs/changelog.rst

@@ -23,6 +23,8 @@ New features:
 * Beets now uses ``platformdirs`` to determine the default music directory.
   This location varies between systems -- for example, users can configure it
   on Unix systems via ``user-dirs.dirs(5)``.
+* :doc:`plugins/inline`: Add access to the ``album`` or ``item`` object in
+  inline fields.
 
 Bug fixes:
 

docs/plugins/inline.rst

@@ -13,7 +13,10 @@ 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 fields in scope, so you can
 refer to any normal attributes (such as ``artist`` or ``title``) as Python
-variables.
+variables. The Python code also has direct access to the item object as ``item``
+for item fields, and as ``album`` for album fields. This allows use of computed
+fields and plugin fields, for example, ``album.albumtotal``, or ``album.missing``
+if the :doc:`plugins/missing` plugin is enabled.
 
 Here are a couple of examples of expressions::