1API Documentation 2================= 3 4.. currentmodule:: beets.library 5 6This page describes the internal API of beets' core. It's a work in 7progress---since beets is an application first and a library second, its API 8has been mainly undocumented until recently. Please file bugs if you run 9across incomplete or incorrect docs here. 10 11The :class:`Library` object is the central repository for data in beets. It 12represents a database containing songs, which are :class:`Item` instances, and 13groups of items, which are :class:`Album` instances. 14 15The Library Class 16----------------- 17 18.. autoclass:: Library(path, directory[, path_formats[, replacements]]) 19 20 .. automethod:: items 21 22 .. automethod:: albums 23 24 .. automethod:: get_item 25 26 .. automethod:: get_album 27 28 .. automethod:: add 29 30 .. automethod:: add_album 31 32 .. automethod:: transaction 33 34Transactions 35'''''''''''' 36 37The :class:`Library` class provides the basic methods necessary to access and 38manipulate its contents. To perform more complicated operations atomically, or 39to interact directly with the underlying SQLite database, you must use a 40*transaction*. For example:: 41 42 lib = Library() 43 with lib.transaction() as tx: 44 items = lib.items(query) 45 lib.add_album(list(items)) 46 47.. currentmodule:: beets.dbcore.db 48 49.. autoclass:: Transaction 50 :members: 51 52Model Classes 53------------- 54 55The two model entities in beets libraries, :class:`Item` and :class:`Album`, 56share a base class, :class:`Model`, that provides common functionality and 57ORM-like abstraction. 58 59The fields model classes can be accessed using attributes (dots, as in 60``item.artist``) or items (brackets, as in ``item['artist']``). The 61:class:`Model` base class provides some methods that resemble `dict` 62objects. 63 64Model base 65'''''''''' 66 67.. currentmodule:: beets.dbcore 68 69.. autoclass:: Model 70 :members: 71 72Item 73'''' 74 75.. currentmodule:: beets.library 76 77.. autoclass:: Item 78 :members: 79 80Album 81''''' 82 83.. autoclass:: Album 84 :members: 85