API Documentation¶
This page describes the internal API of beets’ core. It’s a work in progress—since beets is an application first and a library second, its API has been mainly undocumented until recently. Please file bugs if you run across incomplete or incorrect docs here.
The Library
object is the central repository for data in beets. It
represents a database containing songs, which are Item
instances, and
groups of items, which are Album
instances.
The Library Class¶
Transactions¶
The Library
class provides the basic methods necessary to access and
manipulate its contents. To perform more complicated operations atomically, or
to interact directly with the underlying SQLite database, you must use a
transaction. For example:
lib = Library()
with lib.transaction() as tx:
items = lib.items(query)
lib.add_album(list(items))
Model Classes¶
The two model entities in beets libraries, Item
and Album
,
share a base class, Model
, that provides common functionality and
ORM-like abstraction.
The fields model classes can be accessed using attributes (dots, as in
item.artist
) or items (brackets, as in item['artist']
). The
Model
base class provides some methods that resemble dict
objects.