1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
Plugin Development
==================
Beets plugins are Python modules or packages that extend the core functionality
of beets. The plugin system is designed to be flexible, allowing developers to
add virtually any type of features to beets.
For instance you can create plugins that add new commands to the command-line
interface, listen for events in the beets lifecycle or extend the autotagger
with new metadata sources.
.. _basic-plugin-setup:
Basic Plugin Setup
------------------
A beets plugin is just a Python module or package inside the ``beetsplug``
namespace [1]_ package. To create the basic plugin layout, create a directory
called ``beetsplug`` and add either your plugin module:
.. code-block:: shell
beetsplug/
└── myawesomeplugin.py
or your plugin subpackage
.. code-block:: shell
beetsplug/
└── myawesomeplugin/
├── __init__.py
└── myawesomeplugin.py
.. attention::
You do not need to add an ``__init__.py`` file to the ``beetsplug``
directory. Python treats your plugin as a namespace package automatically,
thus we do not depend on ``pkgutil``-based setup in the ``__init__.py`` file
anymore.
The meat of your plugin goes in ``myawesomeplugin.py``. Every plugin has to
extend the |BeetsPlugin| abstract base class [2]_ . For instance, a minimal
plugin without any functionality would look like this:
.. code-block:: python
# beetsplug/myawesomeplugin.py
from beets.plugins import BeetsPlugin
class MyAwesomePlugin(BeetsPlugin):
pass
.. attention::
If your plugin is composed of intermediate |BeetsPlugin| subclasses, make
sure that your plugin is defined *last* in the namespace. We only load the
last subclass of |BeetsPlugin| we find in your plugin namespace.
To use your new plugin, you need to package [3]_ your plugin and install it into
your ``beets`` (virtual) environment. To enable your plugin, add it it to the
beets configuration
.. code-block:: yaml
# config.yaml
plugins:
- myawesomeplugin
and you're good to go!
.. [1] Check out `this article`_ and `this Stack Overflow question`_ if you
haven't heard about namespace packages.
.. [2] Abstract base classes allow us to define a contract which any plugin must
follow. This is a common paradigm in object-oriented programming, and it
helps to ensure that plugins are implemented in a consistent way. For more
information, see for example pep-3119_.
.. [3] There are a variety of packaging tools available for python, for example
you can use poetry_, setuptools_ or hatchling_.
.. _hatchling: https://hatch.pypa.io/latest/config/build/#build-system
.. _pep-3119: https://peps.python.org/pep-3119/#rationale
.. _poetry: https://python-poetry.org/docs/pyproject/#packages
.. _setuptools: https://setuptools.pypa.io/en/latest/userguide/package_discovery.html#finding-simple-packages
.. _this article: https://realpython.com/python-namespace-package/#setting-up-some-namespace-packages
.. _this stack overflow question: https://stackoverflow.com/a/27586272/9582674
More information
----------------
For more information on writing plugins, feel free to check out the following
resources:
.. toctree::
:maxdepth: 3
:includehidden:
commands
events
autotagger
other/index
|
