Skip to main content
`Ctrl`+`K`

# Library

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

  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

  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

    Build regex/string replacement pairs from config.

  music_dir_context() → Iterator[Library]

    Temporarily bind this library’s directory to path conversion.

  add(obj: LibModel) → int | None

    Add the `Item` or `Album` object to the library database.

    Return the object’s new id.

  add_album(items: list[Item]) → Album

    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

    Get a `Sort` object for albums from the config option.

  static get_default_item_sort() → Sort

    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]

    Get `Album` objects matching the query.

  items(query: str | Sequence[str] | Query | None = None, sort: Sort | None = None) → dbcore.Results[Item]

    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

    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 = 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.

  get_album(item_or_id: Item | int) → Album | None

    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.