Album#

class beets.library.Album(db: D | None = None, **values)[source]#

Bases: LibModel

Provide access to information about albums stored in a library.

Reflects the library’s “albums” table, including album art.

__init__(db: D | None = None, **values)#: Create a new object with an optional Database association and initial field values.

Public methods summary

`add`([lib])	Add the object to the library database.
`all_keys`()	Get a list of available keys for objects of this type.
`any_field_query`(args, *kwargs)
`any_writable_media_field_query`(args, *kwargs)
`art_destination`(image[, item_dir])	Return a path to the destination for the album art image for the album.
`clear_dirty`()	Mark all fields as clean (i.e., not needing to be stored to the database).
`copy`()	Create a copy of the model object.
`duplicates_query`(fields)	Return a query for entities with same values in the given fields.
`evaluate_template`(template[, for_path])	Evaluate a template (a string or a Template object) using the object's fields.
`field_query`(field, pattern, query_cls)	Get a FieldQuery for the given field on this model.
`formatted`([included_keys, for_path])	Get a mapping containing all values on this object formatted as human-readable unicode strings.
`get`(key[, default, raise_])	Get the value for a field, or default.
`get_fresh_from_db`()	Load this object from the database.
`item_dir`()	Return the directory containing the album's first item, provided that such an item exists.
`items`()	Return an iterable over the items associated with this album.
`keys`([computed])	Get a list of available field names for this object.
`load`()	Refresh the object's metadata from the library database.
`move`([operation, basedir, store])	Move, copy, link or hardlink (depending on operation) all items to their destination.
`move_art`([operation])	Move, copy, link or hardlink (depending on operation) any existing album art so that it remains in the same directory as the items.
`remove`([delete, with_items])	Remove this album and all its associated items from the library.
`set_art`(path[, copy])	Set the album's cover art to the image at the given path.
`set_parse`(key, string)	Set the object's key to a value represented by a string.
`store`([fields, inherit])	Update the database with the album information.
`try_sync`(write, move[, inherit])	Synchronize the album and its items with the database.
`update`(values)	Assign all values in the given dict.

Methods definition

property art_filepath: Path | None#: The path to album’s cover picture as pathlib.Path.

items()[source]#

Return an iterable over the items associated with this album.

This method conflicts with LibModel.items(), which is inherited from beets.dbcore.Model.items(). Since Album.items() predates these methods, and is likely to be used by plugins, we keep this interface as-is.

remove(delete=False, with_items=True)[source]#

Remove this album and all its associated items from the library.

If delete, then the items’ files are also deleted from disk, along with any album art. The directories containing the album are also removed (recursively) if empty.

Set with_items to False to avoid removing the album’s items.

move_art(operation=MoveOperation.MOVE)[source]#

Move, copy, link or hardlink (depending on operation) any existing album art so that it remains in the same directory as the items.

operation should be an instance of util.MoveOperation.

move(operation=MoveOperation.MOVE, basedir=None, store=True)[source]#

Move, copy, link or hardlink (depending on operation) all items to their destination. Any album art moves along with them.

basedir overrides the library base directory for the destination.

operation should be an instance of util.MoveOperation.

By default, the album is stored to the database, persisting any modifications to its metadata. If store is False however, the album is not stored automatically, and it will have to be manually stored after invoking this method.

item_dir()[source]#: Return the directory containing the album’s first item, provided that such an item exists.

art_destination(image, item_dir=None)[source]#

Return a path to the destination for the album art image for the album.

image is the path of the image that will be moved there (used for its extension).

The path construction uses the existing path of the album’s items, so the album must contain at least one item or item_dir must be provided.

set_art(path, copy=True)[source]#

Set the album’s cover art to the image at the given path.

The image is copied (or moved) into place, replacing any existing art.

Send an ‘art_set’ event with self as the sole argument.

store(fields=None, inherit=True)[source]#

Update the database with the album information.

fields represents the fields to be stored. If not specified, all fields will be.

The album’s tracks are also updated when the inherit flag is enabled. This applies to fixed attributes as well as flexible ones. The id attribute of the album will never be inherited.

try_sync(write, move, inherit=True)[source]#

Synchronize the album and its items with the database. Optionally, also write any new tags into the files and update their paths.

write indicates whether to write tags to the item files, and move controls whether files (both audio and album art) are moved.

property length: float[source]#: Return the total length of all items in this album in seconds.

add(lib=None)#

Add the object to the library database. This object must be associated with a database; you can provide one via the db parameter or use the currently associated database.

The object’s id and added fields are set along with any current field values.

classmethod all_keys()#: Get a list of available keys for objects of this type. Includes fixed and computed fields.

clear_dirty()#: Mark all fields as clean (i.e., not needing to be stored to the database). Also update the revision.

copy() → Model#

Create a copy of the model object.

The field values and other state is duplicated, but the new copy remains associated with the same database as the old object. (A simple copy.deepcopy will not work because it would try to duplicate the SQLite connection.)

property db: D#

Get the database associated with this object.

This validates that the database is attached and the object has an id.

duplicates_query(fields: list[str]) → AndQuery#: Return a query for entities with same values in the given fields.

evaluate_template(template: str | Template, for_path: bool = False) → str#: Evaluate a template (a string or a Template object) using the object’s fields. If for_path is true, then no new path separators will be added to the template.

classmethod field_query(field: str, pattern: str, query_cls: FieldQueryType) → FieldQuery#: Get a FieldQuery for the given field on this model.

property filepath: Path#: The path to the entity as pathlib.Path.

formatted(included_keys: str = '*', for_path: bool = False) → FormattedMapping#: Get a mapping containing all values on this object formatted as human-readable unicode strings.

get(key, default: Any = None, raise_: bool = False)#: Get the value for a field, or default. Alternatively, raise a KeyError if the field is not available.

get_fresh_from_db() → Self#: Load this object from the database.

keys(computed: bool = False)#: Get a list of available field names for this object. The computed parameter controls whether computed (plugin-provided) fields are included in the key list.

load()#

Refresh the object’s metadata from the library database.

If check_revision is true, the database is only queried loaded when a transaction has been committed since the item was last loaded.

set_parse(key, string: str)#: Set the object’s key to a value represented by a string.

update(values)#: Assign all values in the given dict.