Library#

class beets.library.Library(path='library.blb', directory: str | None = None, path_formats=(('default', '$artist/$album/$track $title'),), replacements=None, set_music_dir: bool = True)[source]#

Bases: Database

A database of music containing songs and albums.

__init__(path='library.blb', directory: str | None = None, path_formats=(('default', '$artist/$album/$track $title'),), replacements=None, set_music_dir: bool = True)[source]#

Public methods summary

`add`(obj)	Add the `Item` or `Album` object to the library database.
`add_album`(items)	Create a new album consisting of a list of items.
`add_functions`(conn)
`albums`([query, sort])	Get `Album` objects matching the query.
`get_album`(item_or_id)	Given an album ID or an item associated with an album, return a `Album` object for the album.
`get_default_album_sort`()	Get a `Sort` object for albums from the config option.
`get_default_item_sort`()	Get a `Sort` object for items from the config option.
`get_item`(id_)	Fetch a `Item` by its ID.
`items`([query, sort])	Get `Item` objects matching the query.
`load_extension`(path)	Load an SQLite extension into all open connections.
`migration_exists`(name, table)	Return whether a named migration has been marked complete.
`music_dir_context`()	Temporarily bind this library's directory to path conversion.
`record_migration`(name, table)	Set completion state for a named migration.
`transaction`()	Get a `Transaction` object for interacting directly with the underlying SQLite database.

Methods definition

music_dir_context()[source]#: Temporarily bind this library's directory to path conversion.

add(obj)[source]#

Add the Item or Album object to the library database.

Return the object's new id.

add_album(items)[source]#

Create a new album consisting of a list of items.

The items are added to the database if they don't yet have an ID. Return a new Album object. The list items must not be empty.

static get_default_album_sort()[source]#: Get a Sort object for albums from the config option.

static get_default_item_sort()[source]#: Get a Sort object for items from the config option.

albums(query=None, sort=None) → Results[Album][source]#: Get Album objects matching the query.

items(query=None, sort=None) → Results[Item][source]#: Get Item objects matching the query.

get_item(id_: int) → Item | None[source]#

Fetch a Item by its ID.

Return None if no match is found.

get_album(item_or_id: Item | int) → Album | None[source]#

Given an album ID or an item associated with an album, return a Album object for the album.

If no such album exists, return None.

load_extension(path: str)#: Load an SQLite extension into all open connections.

migration_exists(name: str, table: str) → bool#: Return whether a named migration has been marked complete.

record_migration(name: str, table: str) → None#: Set completion state for a named migration.

revision = 0#: The current revision of the database. To be increased whenever data is written in a transaction.

supports_extensions = True#: Whether or not the current version of SQLite supports extensions

transaction() → Transaction#: Get a Transaction object for interacting directly with the underlying SQLite database.