
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.


Model base
----------


Item
----


Album
-----
