Item

class beets.library.Item(db: D | None = None, **values)

Bases: LibModel

Represent a song or track.

__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)
clear()	Set all key/value pairs to None.
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.
current_mtime()	Return the current mtime of the file, rounded to the nearest integer.
destination([relative_to_libdir, basedir, ...])	Return the path in the library directory designated for the item (i.e., where the file ought to be).
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.
from_path(path)	Create a new item from the media file at the specified path.
get(key[, default, with_album])	Get the value for a given key or default if it does not exist.
get_album()	Get the Album object that this item belongs to, if any, or None if the item is a singleton or is not associated with a library.
items()	Iterate over (key, value) pairs that this object contains.
keys([computed, with_album])	Get a list of available field names.
load()	Refresh the object's metadata from the library database.
move([operation, basedir, with_album, store])	Move the item to its designated location within the library directory (provided by destination()).
move_file(dest[, operation])	Move, copy, link or hardlink the item depending on operation, updating the path value if the move succeeds.
read([read_path])	Read the metadata from the associated file.
remove([delete, with_album])	Remove the item.
set_parse(key, string)	Set the object's key to a value represented by a string.
store([fields])	Save the object's metadata into the library database.
try_filesize()	Get the size of the underlying file in bytes.
try_sync(write, move[, with_album])	Synchronize the item with the database and, possibly, update its tags on disk and its path (by moving the file).
try_write(*args, **kwargs)	Call write() but catch and log FileOperationError exceptions.
update(values)	Set all key/value pairs in the mapping.
write([path, tags, id3v23])	Write the item's metadata to a media file.

Methods definition

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()

Set all key/value pairs to None.

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

current_mtime()

Return the current mtime of the file, rounded to the nearest integer.

destination(relative_to_libdir=False, basedir=None, path_formats=None) → bytes

Return the path in the library directory designated for the item (i.e., where the file ought to be).

The path is returned as a bytestring. basedir can override the library's base directory for the destination. If relative_to_libdir is true, returns just the fragment of the path underneath the library base directory.

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)

Get a mapping containing all values on this object formatted as human-readable unicode strings.

classmethod from_path(path)

Create a new item from the media file at the specified path.

get(key, default=None, with_album=True)

Get the value for a given key or default if it does not exist.

Set with_album to false to skip album fallback.

get_album()

Get the Album object that this item belongs to, if any, or None if the item is a singleton or is not associated with a library.

items() → Iterator[tuple[str, Any]]

Iterate over (key, value) pairs that this object contains. Computed fields are not included.

keys(computed=False, with_album=True)

Get a list of available field names.

with_album controls whether the album's fields are included.

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.

move(operation=MoveOperation.MOVE, basedir=None, with_album=True, store=True)

Move the item to its designated location within the library directory (provided by destination()).

Subdirectories are created as needed. If the operation succeeds, the item's path field is updated to reflect the new location.

Instead of moving the item it can also be copied, linked or hardlinked depending on operation which should be an instance of util.MoveOperation.

basedir overrides the library base directory for the destination.

If the item is in an album and with_album is True, the album is given an opportunity to move its art.

By default, the item is stored to the database if it is in the database, so any dirty fields prior to the move() call will be written as a side effect. If store is False however, the item won't be stored and it will have to be manually stored after invoking this method.

move_file(dest, operation=MoveOperation.MOVE)

Move, copy, link or hardlink the item depending on operation, updating the path value if the move succeeds.

If a file exists at dest, then it is slightly modified to be unique.

operation should be an instance of util.MoveOperation.

read(read_path=None)

Read the metadata from the associated file.

If read_path is specified, read metadata from that file instead. Update all the properties in _media_fields from the media file.

Raise a ReadError if the file could not be read.

remove(delete=False, with_album=True)

Remove the item.

If delete, then the associated file is removed from disk.

If with_album, then the item's album (if any) is removed if the item was the last in the album.

set_parse(key, string: str)

Set the object's key to a value represented by a string.

store(fields=None)

Save the object's metadata into the library database. :param fields: the fields to be stored. If not specified, all fields will be.

try_filesize()

Get the size of the underlying file in bytes.

If the file is missing, return 0 (and log a warning).

try_sync(write, move, with_album=True)

Synchronize the item with the database and, possibly, update its tags on disk and its path (by moving the file).

write indicates whether to write new tags into the file. Similarly, move controls whether the path should be updated. In the latter case, files are only moved when they are inside their library's directory (if any).

Similar to calling write(), move(), and store() (conditionally).

try_write(*args, **kwargs)

Call write() but catch and log FileOperationError exceptions.

Return False an exception was caught and True otherwise.

update(values)

Set all key/value pairs in the mapping.

If mtime is specified, it is not reset (as it might otherwise be).

write(path=None, tags=None, id3v23=None)

Write the item's metadata to a media file.

All fields in _media_fields are written to disk according to the values on this object.

path is the path of the mediafile to write the data to. It defaults to the item's path.

tags is a dictionary of additional metadata the should be written to the file. (These tags need not be in _media_fields.)

id3v23 will override the global id3v23 config option if it is set to something other than None.

Can raise either a ReadError or a WriteError.