Library#

class beets.library.Library(path: PathLike = PosixPath('library.blb'), directory: str | None = None, set_music_dir: bool = True)[source]#

Bases: Database

A database of music containing songs and albums.

__init__(path: PathLike = PosixPath('library.blb'), directory: str | None = None, set_music_dir: bool = True) → None[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.
`create_backup`(dest)	Create a backup of the database at dest.
`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.
`get_replacements`()	Build regex/string replacement pairs from config.
`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

static get_replacements() → Replacements[source]#: Build regex/string replacement pairs from config.

music_dir_context() → Iterator[Library][source]#: Temporarily bind this library’s directory to path conversion.

add(obj: LibModel) → int | None[source]#

Add the Item or Album object to the library database.

Return the object’s new id.

add_album(items: list[Item]) → Album[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() → Sort[source]#: Get a Sort object for albums from the config option.

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

albums(query: str | Sequence[str] | Query | None = None, sort: Sort | None = None) → dbcore.Results[Album][source]#: Get Album objects matching the query.

items(query: str | Sequence[str] | Query | None = None, sort: Sort | None = None) → dbcore.Results[Item][source]#: Get Item objects matching the query.

create_backup(dest: str) → None#: Create a backup of the database at dest.

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

Fetch a Item by its ID.

Return None if no match is found.

load_extension(path: str) → None#: 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 = False#: Whether or not the current version of SQLite supports extensions

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

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.