Library

The library package contains functions and dataclasses that expose a clean and functional interface for working with the data from the database.

This package is designed functionally–each module corresponds to one data model. A dataclass for each data model exists at module.T, and each module contains functions that fetch or operate on dataclasses.

These dataclasses are frozen (immutable). To update them, see the available utility functions at Utility Functions.

Note

The library delegates transaction handling to the consumers. The calling function is responsible for committing any mutations.

We do this to give more fine-grained control over transaction management to the handler for consistency and efficiency.

  • Consistency: If two mutations are coupled, they ought to be committed together.

  • Efficiency: Database commits are expensive, so allowing calling code to batch commit related groups of mutations is a big efficiency win. In the past, mutation functions did commit their changes, but indexing one test track then required 14 commits, taking almost a tenth of a second. After leaving it to the caller, which made one commit per track, the time per track dropped to a hundredth of a second.

Artist

Classes:

T(id, name, num_releases)

An artist dataclass.

Functions:

count(conn[, search])

Fetch the number of artists matching the passed-in criteria.

create(name, conn)

Create an artist and persist it to the database.

exists(id, conn)

Return whether an artist exists with the given ID.

from_id(id, conn)

Return the artist with the provided ID.

from_name(name, conn)

Return the artist with the given name, if they exist.

from_row(row)

Return an artist dataclass containing data from a row from the database.

image(art, conn)

Return an image for an artist.

releases(art, conn)

Get the releases of an artist.

search(conn[, search, page, per_page])

Search for artists.

star(art, user_id, conn)

Star the artist for the passed-in user.

starred(art, user_id, conn)

Return whether this artist is starred by the passed-in user.

top_genres(art, conn, *[, num_genres])

Get the top genre collections of the releases of an artist.

unstar(art, user_id, conn)

Unstar the artist for the passed-in user.

update(art, conn, **changes)

Update an artist and persist changes to the database.
class src.library.artist.T(id, name, num_releases)

An artist dataclass.

id: int
name: str
num_releases: int

The number of releases attributed to the artist.

src.library.artist.count(conn, search='')

Fetch the number of artists matching the passed-in criteria. Parameters are optional; omitted ones are excluded from the matching criteria.

Parameters

  • conn (sqlite3.Connection) – A connection to the database.

  • search (str) – A search string. We split this up into individual punctuation-less tokens and return artists whose names contain each token.

Return type

int

Returns

The number of matching artists.

src.library.artist.create(name, conn)

Create an artist and persist it to the database.

Parameters

  • name (str) – The name of the artist.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

src.library.artist.T

Returns

The newly created artist.

Raises

Duplicate – If an artist with the same name already exists. The duplicate artist is passed as the entity argument.

src.library.artist.exists(id, conn)

Return whether an artist exists with the given ID.

Parameters

id (int) – The ID to check.

Return type

bool

Returns

Whether an artist has the given ID.

src.library.artist.from_id(id, conn)

Return the artist with the provided ID.

Parameters

  • id (int) – The ID of the artist to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.artist.T]

Returns

The artist with the provided ID, if it exists.

src.library.artist.from_name(name, conn)

Return the artist with the given name, if they exist.

Parameters

  • name (str) – The name of the artist.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.artist.T]

Returns

The artist, if they exist.

src.library.artist.from_row(row)

Return an artist dataclass containing data from a row from the database.

Parameters

row (typing.Union[dict, sqlite3.Row]) – A row from the database.

Return type

src.library.artist.T

Returns

An artist dataclass.

src.library.artist.image(art, conn)

Return an image for an artist.

At the moment, artists do not have images, so we return a random cover image from one of the artists’ releases, if any exist.

Parameters

  • art (src.library.artist.T) – The artist whose image to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.image.T]

Returns

The image, if it exists.

src.library.artist.releases(art, conn)

Get the releases of an artist.

Parameters

  • art (src.library.artist.T) – The artist whose releases we want to get.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

list[src.library.release.T]

Returns

A list of releases of the artist.

src.library.artist.search(conn, search='', page=1, per_page=None)

Search for artists. Parameters are optional; omitted ones are excluded from the matching criteria.

Parameters

  • conn (sqlite3.Connection) – A connection to the database.

  • search (str) – A search string. We split this up into individual punctuation-less tokens and return artists whose names contain each token. If specified, the returned artists will be sorted by match proximity.

  • page (int) – Which page of artists to return.

  • per_page (typing.Optional[int]) – The number of artists per page. Pass None to return all artists (this will ignore page).

Return type

list[src.library.artist.T]

Returns

All matching artists.

src.library.artist.star(art, user_id, conn)

Star the artist for the passed-in user.

Parameters
Return type

None

src.library.artist.starred(art, user_id, conn)

Return whether this artist is starred by the passed-in user.

Parameters

  • art (src.library.artist.T) – The provided artist.

  • user_id (int) – The passed-in user’s ID.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

bool

Returns

Whether the artist is starred by the user.

src.library.artist.top_genres(art, conn, *, num_genres=5)

Get the top genre collections of the releases of an artist.

The returned genres are in the following format:

[
  {
    "genre": genre.T,
    "num_matches": int,
  },
  ...
]

The field num_releases in the genre collections is set to None.

Parameters

  • art (src.library.artist.T) – The artist whose top genres to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

  • num_genres (int) – The number of top genres to fetch.

Return type

list[dict]

Returns

The top genres.

src.library.artist.unstar(art, user_id, conn)

Unstar the artist for the passed-in user.

Parameters
Return type

None

src.library.artist.update(art, conn, **changes)

Update an artist and persist changes to the database. To update a value, pass it in as a keyword argument. To keep the original value, do not pass in a keyword argument.

Parameters

  • art (src.library.artist.T) – The artist to update.

  • conn (sqlite3.Connection) – A connection to the database.

  • name (str) – New artist name.

Return type

src.library.artist.T

Returns

The updated artist.

Raises

Duplicate – If an artist already exists with the new name.

Collection

Classes:

T(id, name, type, user_id[, num_releases, …])

A collection dataclass.

Functions:

add_release(col, release_id, conn)

Add the provided release to the provided collection.

count(conn, *[, search, types, user_ids])

Fetch the number of collections matching the passed-in criteria.

create(name, type, conn[, user_id, …])

Create a collection and persist it to the database.

del_release(col, release_id, conn)

Remove the provided release from the provided collection.

exists(id, conn)

Return whether a collection exists with the given ID.

favorites_of(user_id, conn)

Return the favorites collection of the passed-in user.

from_id(id, conn)

Return the collection with the provided ID.

from_name_and_type(name, type, conn)

Return all collections with the given name and type.

from_name_type_user(name, type, conn[, user_id])

Return the collection with the given name, type, and user, if it exists.

from_row(row)

Return a collection dataclass containing data from a row from the database.

has_release(col, release_id, conn)

Return whether the collection has a given release.

image(col, conn)

Return an image for a collection.

inbox_of(user_id, conn)

Return the inbox collection of the passed-in user.

releases(col, conn)

Get the releases in a collection.

search(conn, *[, search, types, user_ids, …])

Search for collections.

star(col, user_id, conn)

Star the collection for the passed-in user.

starred(col, user_id, conn)

Return whether this collection is starred by the passed-in user.

top_genres(col, conn, *[, num_genres])

Get the top genre collections of the releases in a collection.

unstar(col, user_id, conn)

Unstar the collection for the passed-in user.

update(col, conn, **changes)

Update a collection and persist changes to the database.

user(col, conn)

Returns the user the collection belongs to, if it belongs to a user.
class src.library.collection.T(id, name, type, user_id, num_releases=None, last_updated_on=None)

A collection dataclass.

id: int
last_updated_on: Optional[datetime.datetime] = None
name: str
num_releases: Optional[int] = None
type: src.enums.CollectionType
src.library.collection.add_release(col, release_id, conn)

Add the provided release to the provided collection.

Parameters

  • col (src.library.collection.T) – The collection to add the release to.

  • release_id (int) – The ID of the release to add.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

src.library.collection.T

Returns

The collection with the number of tracks (if present) updated.

Raises

  • NotFound – If no release has the given release ID.

  • AlreadyExists – If the release is already in the collection.

src.library.collection.count(conn, *, search='', types=[], user_ids=[])

Fetch the number of collections matching the passed-in criteria. Parameters are optional; omitted ones are excluded from the matching criteria.

Parameters

  • conn (sqlite3.Connection) – A connection to the database.

  • search (str) – A search string. We split this up into individual punctuation-less tokens and return collections whose titles contain each token.

  • types (list[src.enums.CollectionType]) – Filter by collection types.

  • user_ids (list[int]) – Filter by collection owners.

Return type

int

Returns

The number of matching collections.

src.library.collection.create(name, type, conn, user_id=None, override_immutable=False)

Create a collection and persist it to the database.

Parameters

  • name (str) – The name of the collection.

  • type (src.enums.CollectionType) – The type of the collection.

  • conn (sqlite3.Connection) – A connection to the database.

  • user_id (typing.Optional[int]) – The ID of the user that this collection belongs to. Should be set for Personal and System collections; unset otherwise.

  • override_immutable (bool) – Whether to allow creation of immutable collections. For internal use.

Return type

src.library.collection.T

Returns

The newly created collection.

Raises

  • Duplicate – If an collection with the same name and type already exists. The duplicate collection is passed as the entity argument.

  • InvalidArgument – If the user_id argument is passed with an non-personal collection type.

src.library.collection.del_release(col, release_id, conn)

Remove the provided release from the provided collection.

Parameters

  • col (src.library.collection.T) – The collection to remove the release from.

  • release_id (int) – The release to remove.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

src.library.collection.T

Returns

The collection with the number of tracks (if present) updated.

Raises

  • NotFound – If no release has the given release ID.

  • DoesNotExist – If the release is not in the collection.

src.library.collection.exists(id, conn)

Return whether a collection exists with the given ID.

Parameters

id (int) – The ID to check.

Return type

bool

Returns

Whether a collection has the given ID.

src.library.collection.favorites_of(user_id, conn)

Return the favorites collection of the passed-in user.

Parameters

  • user_id (int) – The ID of the user whose favorites to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

src.library.collection.T

Returns

The user’s favorites collection.

Raises

DoesNotExist – If the inbox does not exist.

src.library.collection.from_id(id, conn)

Return the collection with the provided ID.

Parameters

  • id (int) – The ID of the collection to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.collection.T]

Returns

The collection with the provided ID, if it exists.

src.library.collection.from_name_and_type(name, type, conn)

Return all collections with the given name and type.

Parameters

  • name (str) – The name of the collection.

  • type (src.enums.CollectionType) – The type of the collection.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

list[src.library.collection.T]

Returns

The collection, if it exists.

src.library.collection.from_name_type_user(name, type, conn, user_id=None)

Return the collection with the given name, type, and user, if it exists.

Parameters

  • name (str) – The name of the collection.

  • type (src.enums.CollectionType) – The type of the collection.

  • user_id (typing.Optional[int]) – Who the collection belongs to.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.collection.T]

Returns

The collection, if it exists.

src.library.collection.from_row(row)

Return a collection dataclass containing data from a row from the database.

Parameters

row (typing.Union[dict, sqlite3.Row]) – A row from the database.

Return type

src.library.collection.T

Returns

A collection dataclass.

src.library.collection.has_release(col, release_id, conn)

Return whether the collection has a given release.

Parameters

  • col (src.library.collection.T) – The collection to check membership in.

  • release_id (int) – The release to check membership for.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

bool

Returns

Whether the release exists in the collection.

src.library.collection.image(col, conn)

Return an image for a collection.

Since collections do not have images, we return a random cover image from one of the releases in the collection, if any exist.

Parameters

  • col (src.library.collection.T) – The collection whose image to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.image.T]

Returns

The image, if it exists.

src.library.collection.inbox_of(user_id, conn)

Return the inbox collection of the passed-in user.

Parameters

  • user_id (int) – The ID of the user whose inbox to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

src.library.collection.T

Returns

The user’s inbox collection.

Raises

DoesNotExist – If the inbox does not exist.

src.library.collection.releases(col, conn)

Get the releases in a collection.

Parameters

  • col (src.library.collection.T) – The collection whose releases we want to get.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

list[src.library.release.T]

Returns

A list of releases in the collection.

src.library.collection.search(conn, *, search='', types=[], user_ids=[], page=1, per_page=None)

Search for collections. Parameters are optional; omitted ones are excluded from the matching criteria.

Parameters

  • conn (sqlite3.Connection) – A connection to the database.

  • search (str) – A search string. We split this up into individual punctuation-less tokens and return collections whose titles contain each token. If specified, the returned collections will be sorted by match proximity.

  • types (list[src.enums.CollectionType]) – Filter by collection types.

  • user_ids (list[int]) – Filter by collection owners.

  • page (int) – Which page of collections to return.

  • per_page (typing.Optional[int]) – The number of collections per page. Pass None to return all collections (this will ignore page).

Return type

list[src.library.collection.T]

Returns

All matching collections.

src.library.collection.star(col, user_id, conn)

Star the collection for the passed-in user. :type col: src.library.collection.T :param col: :type user_id: int :param user_id: :type conn: sqlite3.Connection :param conn:

Return type

None

src.library.collection.starred(col, user_id, conn)

Return whether this collection is starred by the passed-in user. :type col: src.library.collection.T :param col: The provided collection. :type user_id: int :param user_id: The passed-in user’s ID. :type conn: sqlite3.Connection :param conn: A connection to the database. :rtype: bool :return: Whether the collection is starred by the user.

src.library.collection.top_genres(col, conn, *, num_genres=5)

Get the top genre collections of the releases in a collection.

The returned genres are in the following format:

[
  {
    "genre": collection.T,
    "num_matches": int,
  },
  ...
]

The field num_releases in the genre collections is set to None.

Parameters

  • col (src.library.collection.T) – The collection whose top genres to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

  • num_genres (int) – The number of top genres to fetch.

Return type

list[dict]

Returns

The top genres.

src.library.collection.unstar(col, user_id, conn)

Unstar the collection for the passed-in user. :type col: src.library.collection.T :param col: :type user_id: int :param user_id: :type conn: sqlite3.Connection :param conn:

Return type

None

src.library.collection.update(col, conn, **changes)

Update a collection and persist changes to the database. To update a value, pass it in as a keyword argument. To keep the original value, do not pass in a keyword argument.

Note: The type of a collection cannot be changed.

Parameters

  • col (src.library.collection.T) – The collection to update.

  • conn (sqlite3.Connection) – A connection to the database.

  • name (str) – New collection name.

Return type

src.library.collection.T

Returns

The updated collection.

Raises

  • Immutable – If the collection cannot be updated.

  • Duplicate – If the new name conflicts with another collection.

src.library.collection.user(col, conn)

Returns the user the collection belongs to, if it belongs to a user.

Parameters

  • col (src.library.collection.T) – The collection whose user to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.user.T]

Returns

The user, if one exists.

Playlist

This module contains the playlist dataclass and its associated functions.

A playlist is an ordered list of tracks and associated metainfo. We denote a track in a playlist an “entry.” Each entry represents a track and its index in the playlist. The playlist_entry module contains an entry dataclass and associated functions for working with playlist entries.

Classes:

T(id, name, type, user_id[, num_tracks, …])

A playlist dataclass.

Functions:

count(conn, *[, search, types, user_ids])

Fetch the number of playlists matching the passed-in criteria.

create(name, type, conn[, user_id, …])

Create a playlist and persist it to the database.

entries(ply, conn)

Get the tracks in a playlist.

exists(id, conn)

Return whether a playlist exists with the given ID.

favorites_of(user_id, conn)

Return the favorites playlist of the passed-in user.

from_id(id, conn)

Return the playlist with the provided ID.

from_name_and_type(name, type, conn)

Return all playlist with the given name and type.

from_name_type_user(name, type, conn[, user_id])

Return the playlist with the given name, type, and user, if it exists.

from_row(row)

Return a playlist dataclass containing data from a row from the database.

image(ply, conn)

Return an image for a playlist.

search(conn, *[, search, types, user_ids, …])

Search for playlists.

star(ply, user_id, conn)

Star the playlist for the passed-in user.

starred(ply, user_id, conn)

Return whether this playlist is starred by the passed-in user.

top_genres(ply, conn, *[, num_genres])

Get the top genre collections of the tracks in a playlist.

unstar(ply, user_id, conn)

Unstar the playlist for the passed-in user.

update(ply, conn, **changes)

Update a playlist and persist changes to the database.

user(ply, conn)

Returns the user the playlist belongs to, if it belongs to a user.
class src.library.playlist.T(id, name, type, user_id, num_tracks=None, last_updated_on=None)

A playlist dataclass.

id: int
last_updated_on: Optional[datetime.datetime] = None
name: str
num_tracks: Optional[int] = None
type: src.enums.PlaylistType
src.library.playlist.count(conn, *, search='', types=[], user_ids=[])

Fetch the number of playlists matching the passed-in criteria. Parameters are optional; omitted ones are excluded from the matching criteria.

Parameters

  • conn (sqlite3.Connection) – A connection to the database.

  • search (str) – A search string. We split this up into individual punctuation-less tokens and return playlists whose titles contain each token.

  • types (list[src.enums.PlaylistType]) – Filter by playlist types.

  • user_ids (list[int]) – Filter by collection owners.

Return type

int

Returns

The number of matching playlists.

src.library.playlist.create(name, type, conn, user_id=None, override_immutable=False)

Create a playlist and persist it to the database.

Parameters

  • name (str) – The name of the playlist.

  • type (src.enums.PlaylistType) – The type of the playlist.

  • conn (sqlite3.Connection) – A connection to the database.

  • user_id (typing.Optional[int]) – The ID of the user that this playlist belongs to. Should be set for Personal and System playlists; unset otherwise.

  • override_immutable (bool) – Whether to allow creation of immutable playlists. For internal use.

Return type

src.library.playlist.T

Returns

The newly created playlist.

Raises

  • Duplicate – If an playlist with the same name and type already exists. The duplicate playlist is passed as the entity argument.

  • InvalidArgument – If the user_id argument is passed with a non-personal playlist type.

src.library.playlist.entries(ply, conn)

Get the tracks in a playlist.

Parameters

  • ply (src.library.playlist.T) – The playlist whose tracks we want to get.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

list[src.library.playlist_entry.T]

Returns

A list of tracks in the playlist.

src.library.playlist.exists(id, conn)

Return whether a playlist exists with the given ID.

Parameters

  • id (int) – The ID to check.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

bool

Returns

Whether a playlist has the given ID.

src.library.playlist.favorites_of(user_id, conn)

Return the favorites playlist of the passed-in user.

Parameters

  • user_id (int) – The ID of the user whose favorites to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

src.library.playlist.T

Returns

The user’s favorites playlist.

Raises

DoesNotExist – If the inbox does not exist.

src.library.playlist.from_id(id, conn)

Return the playlist with the provided ID.

Parameters

  • id (int) – The ID of the playlist to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.playlist.T]

Returns

The playlist with the provided ID, if it exists.

src.library.playlist.from_name_and_type(name, type, conn)

Return all playlist with the given name and type.

Parameters

  • name (str) – The name of the playlist.

  • type (src.enums.PlaylistType) – The type of the playlist.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

list[src.library.playlist.T]

Returns

The playlist, if it exists.

src.library.playlist.from_name_type_user(name, type, conn, user_id=None)

Return the playlist with the given name, type, and user, if it exists.

Parameters

  • name (str) – The name of the playlist.

  • type (src.enums.PlaylistType) – The type of the playlist.

  • user_id (typing.Optional[int]) – Who the playlist belongs to.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.playlist.T]

Returns

The playlist, if it exists.

src.library.playlist.from_row(row)

Return a playlist dataclass containing data from a row from the database.

Parameters

row (typing.Union[dict, sqlite3.Row]) – A row from the database.

Return type

src.library.playlist.T

Returns

A playlist dataclass.

src.library.playlist.image(ply, conn)

Return an image for a playlist.

Since playlists do not have images, we return a random cover image from one of the tracks in the playlist, if any exist.

Parameters

  • ply (src.library.playlist.T) – The playlist whose image to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.image.T]

Returns

The image, if it exists.

src.library.playlist.search(conn, *, search='', types=[], user_ids=[], page=1, per_page=None)

Search for playlists. Parameters are optional; omitted ones are excluded from the matching criteria.

Parameters

  • conn (sqlite3.Connection) – A connection to the database.

  • search (str) – A search string. We split this up into individual punctuation-less tokens and return playlists whose titles contain each token. If specified, the returned playlists will be sorted by match proximity.

  • types (list[src.enums.PlaylistType]) – Filter by playlist types.

  • user_ids (list[int]) – Filter by collection owners.

  • page (int) – Which page of playlists to return.

  • per_page (typing.Optional[int]) – The number of playlists per page. Pass None to return all playlists (this will ignore page).

Return type

list[src.library.playlist.T]

Returns

All matching playlists.

src.library.playlist.star(ply, user_id, conn)

Star the playlist for the passed-in user. :type ply: src.library.playlist.T :param ply: :type user_id: int :param user_id: :type conn: sqlite3.Connection :param conn:

Return type

None

src.library.playlist.starred(ply, user_id, conn)

Return whether this playlist is starred by the passed-in user. :type ply: src.library.playlist.T :param ply: The provided playlist. :type user_id: int :param user_id: The passed-in user’s ID. :type conn: sqlite3.Connection :param conn: A connection to the database. :rtype: bool :return: Whether the playlist is starred by the user.

src.library.playlist.top_genres(ply, conn, *, num_genres=5)

Get the top genre collections of the tracks in a playlist.

The returned genres are in the following format:

[
  {
    "genre": collection.T,
    "num_matches": int,
  },
  ...
]

The field num_releases in the genre collections is set to None.

Parameters

  • ply (src.library.playlist.T) – The playlist whose top genres to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

  • num_genres (int) – The number of top genres to fetch.

Return type

list[dict]

Returns

The top genres.

src.library.playlist.unstar(ply, user_id, conn)

Unstar the playlist for the passed-in user. :type ply: src.library.playlist.T :param ply: :type user_id: int :param user_id: :type conn: sqlite3.Connection :param conn:

Return type

None

src.library.playlist.update(ply, conn, **changes)

Update a playlist and persist changes to the database. To update a value, pass it in as a keyword argument. To keep the original value, do not pass in a keyword argument.

Note: The type and user_id of a playlist cannot be changed.

Parameters

  • ply (src.library.playlist.T) – The playlist to update.

  • conn (sqlite3.Connection) – A connection to the database.

  • name (str) – New playlist name.

Return type

src.library.playlist.T

Returns

The updated playlist.

Raises

  • Immutable – If the playlist cannot be updated.

  • Duplicate – If the new name conflicts with another playlist.

src.library.playlist.user(ply, conn)

Returns the user the playlist belongs to, if it belongs to a user.

Parameters

  • ply (src.library.playlist.T) – The playlist whose user to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.user.T]

Returns

The user, if one exists.

Release

Classes:

T(id, title, release_type, added_on, …[, …])

A release dataclass.

Functions:

add_artist(rls, artist_id, role, conn)

Add the provided artist to the provided release.

all_years(conn)

Get all release years stored in the database, sorted in descending order.

artists(rls, conn)

Get the “album artists” of the provided release.

collections(rls, conn[, type])

Get the collections that contain the provided release.

count(conn, *[, search, collection_ids, …])

Fetch the number of releases matching the passed-in criteria.

create(title, artists, release_type, …[, …])

Create a release with the provided parameters.

del_artist(rls, artist_id, role, conn)

Delete the provided artist to the provided release.

exists(id, conn)

Return whether a release exists with the given ID.

from_id(id, conn)

Return the release with the provided ID.

from_row(row)

Return a release dataclass containing data from a row from the database.

in_favorites(rls, user_id, conn)

Return whether this release is in the favorites of the passed-in user.

in_inbox(rls, user_id, conn)

Return whether this release is in the inbox of the passed-in user.

search(conn, *[, search, collection_ids, …])

Search for releases matching the passed-in criteria.

tracks(rls, conn)

Get the tracks of the provided release.

update(rls, conn, **changes)

Update a release and persist changes to the database.
class src.library.release.T(id, title, release_type, added_on, release_year, num_tracks, rating, runtime, release_date=None, image_id=None)

A release dataclass.

added_on: datetime.datetime

When this release was added to the server.

id: int
image_id: Optional[int] = None

The filepath of the album cover.

num_tracks: int

The number of tracks that this release has.

rating: Optional[int]

The track rating (if exists, in the interval [1, 10]).

release_date: Optional[datetime.date] = None

The date this release was released.

release_type: src.enums.ReleaseType

The type of this release.

release_year: Optional[int]

The year this release was released.

title: str
src.library.release.add_artist(rls, artist_id, role, conn)

Add the provided artist to the provided release.

Parameters

  • rls (src.library.release.T) – The release to add the artist to.

  • artist_id (int) – The ID of the artist to add.

  • role (tagfiles._common.ArtistRoles) – The role to add the artist with.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

src.library.release.T

Returns

The release that was passed in.

Raises

  • NotFound – If no artist has the given artist ID.

  • AlreadyExists – If the artist is already on the release.

src.library.release.all_years(conn)

Get all release years stored in the database, sorted in descending order.

Parameters

conn (sqlite3.Connection) – A connection to the database.

Return type

list[int]

src.library.release.artists(rls, conn)

Get the “album artists” of the provided release.

Parameters

  • rls (src.library.release.T) – The provided release.

  • conn (sqlite3.Connection) – A connection to the datbase.

Return type

list[dict]

Returns

A list of {"artist": artist.T, "role": ArtistRole} dicts representing the album artists.

src.library.release.collections(rls, conn, type=None)

Get the collections that contain the provided release.

Parameters

  • rls (src.library.release.T) – The provided release.

  • conn (sqlite3.Connection) – A connection to the datbase.

  • type (typing.Optional[src.enums.CollectionType]) – The type of collections to fetch. Leave None to fetch all.

Return type

list[src.library.collection.T]

Returns

The collections that contain the provided release.

src.library.release.count(conn, *, search='', collection_ids=[], artist_ids=[], release_types=[], years=[], ratings=[])

Fetch the number of releases matching the passed-in criteria. Parameters are optional; omitted ones are excluded from the matching criteria.

Parameters

  • search (str) – A search string. We split this up into individual punctuation-less words and return releases that contain each word.

  • collection_ids (list[int]) – A list of collection IDs. We match releases by the collections in this list. For a release to match, it must be in all collections in this list.

  • artist_ids (list[int]) – A list of artist IDs. We match releases by the artists in this list. For a release to match, all artists in this list must be included.

  • release_types (list[src.enums.ReleaseType]) – A list of release types. Filter out releases that do not match one of the release types in this list.

  • years (list[int]) – A list of years. Filter out releases that were not released in one of the years in this list.

  • ratings (list[int]) – A list of ratings. Filter out releases that do not match one of the ratings in this list.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

int

Returns

The number of matching releases.

src.library.release.create(title, artists, release_type, release_year, conn, release_date=None, rating=None, image_id=None, allow_duplicate=True)

Create a release with the provided parameters.

Parameters

  • title (str) – The title of the release.

  • artists (list[dict]) – The artists that contributed to this release. A list of {"artist_id": int, "role": ArtistRole} mappings.

  • release_type (src.enums.ReleaseType) – The type of the release.

  • release_year (typing.Optional[int]) – The year the release came out.

  • conn (sqlite3.Connection) – A connection to the database.

  • release_date (typing.Optional[datetime.date]) – The date the release came out.

  • rating (typing.Optional[int]) – A rating for the release.

  • image_id (typing.Optional[int]) – An ID of an image to serve as cover art.

  • allow_duplicate (bool) – Whether to allow creation of a duplicate release or not. If this is False, then Duplicate will never be raised. All releases will be created.

Return type

src.library.release.T

Returns

The newly created release.

Raises

  • NotFound – If the list of artists contains an invalid ID.

  • Duplicate – If a release with the same name and artists already exists. The duplicate release is passed as the entity argument.

src.library.release.del_artist(rls, artist_id, role, conn)

Delete the provided artist to the provided release.

Parameters

  • rls (src.library.release.T) – The release to delete the artist from.

  • artist_id (int) – The ID of the artist to delete.

  • role (tagfiles._common.ArtistRoles) – The role of the artist on the release.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

src.library.release.T

Returns

The release that was passed in.

Raises

  • NotFound – If no artist has the given artist ID.

  • DoesNotExist – If the artist is not on the release.

src.library.release.exists(id, conn)

Return whether a release exists with the given ID.

Parameters

id (int) – The ID to check.

Return type

bool

Returns

Whether a release has the given ID.

src.library.release.from_id(id, conn)

Return the release with the provided ID.

Parameters

  • id (int) – The ID of the release to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.release.T]

Returns

The release with the provided ID, if it exists.

src.library.release.from_row(row)

Return a release dataclass containing data from a row from the database.

Parameters

row (typing.Union[dict, sqlite3.Row]) – A row from the database.

Return type

src.library.release.T

Returns

A release dataclass.

src.library.release.in_favorites(rls, user_id, conn)

Return whether this release is in the favorites of the passed-in user.

Parameters

  • rls (src.library.release.T) – The provided release.

  • user_id (int) – The ID of the user whose favorites to check.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

bool

Returns

Whether the release is in the user’s favorites.

Raises

DoesNotExist – If the user’s favorites does not exist.

src.library.release.in_inbox(rls, user_id, conn)

Return whether this release is in the inbox of the passed-in user.

Parameters

  • rls (src.library.release.T) – The provided release.

  • user_id (int) – The ID of the user whose inbox to check.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

bool

Returns

Whether the release is in the user’s inbox.

Raises

DoesNotExist – If the user’s inbox does not exist.

src.library.release.search(conn, *, search='', collection_ids=[], artist_ids=[], release_types=[], years=[], ratings=[], page=1, per_page=None, sort=None, asc=True)

Search for releases matching the passed-in criteria. Parameters are optional; omitted ones are excluded from the matching criteria.

Parameters

  • search (str) – A search string. We split this up into individual punctuation-less tokens and return releases whose titles and artists contain each token.

  • collection_ids (list[int]) – A list of collection IDs. We match releases by the collections in this list. For a release to match, it must be in all collections in this list.

  • artist_ids (list[int]) – A list of artist IDs. We match releases by the artists in this list. For a release to match, all artists in this list must be included.

  • release_types (list[src.enums.ReleaseType]) – A list of release types. Filter out releases that do not match one of the release types in this list.

  • years (list[int]) – A list of years. Filter out releases that were not released in one of the years in this list.

  • ratings (list[int]) – A list of ratings. Filter out releases that do not match one of the ratings in this list.

  • page (int) – Which page of releases to return.

  • per_page (typing.Optional[int]) – The number of releases per page. Pass None to return all releases (this will ignore page).

  • sort (typing.Optional[src.enums.ReleaseSort]) – How to sort the matching releases. If not explicitly passed, this defaults to SEARCH_RANK if search is not None and RECENTLY_ADDED otherwise.

  • asc (bool) – If true, sort in ascending order. If false, descending.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

list[src.library.release.T]

Returns

The matching releases on the current page.

src.library.release.tracks(rls, conn)

Get the tracks of the provided release.

Parameters

  • rls (src.library.release.T) – The provided release.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

list[src.library.track.T]

Returns

The tracks of the provided release.

src.library.release.update(rls, conn, **changes)

Update a release and persist changes to the database. To update a value, pass it in as a keyword argument. To keep the original value, do not pass in a keyword argument.

Parameters

  • rls (src.library.release.T) – The release to update.

  • conn (sqlite3.Connection) – A connection to the database.

  • title (str) – New release title.

  • release_type (src.enums.ReleaseType) – New release type.

  • release_year (int) – New release year.

  • release_date (datetime.date) – New release date.

  • rating (int) – New release rating. Pass in 0 to delete existing rating. Passing in None does not change the existing rating.

Return type

src.library.release.T

Returns

The updated release.

Track

Classes:

T(id, filepath, sha256, sha256_initial, …)

A track dataclass.

Functions:

add_artist(trk, artist_id, role, conn)

Add the provided artist/role combo to the provided track.

artists(trk, conn)

Get the artists that contributed to a track and their roles.

calculate_track_full_sha256(trk, conn)

Given a track, calculate its full SHA256.

count(conn, *[, search, playlist_ids, …])

Fetch the number of tracks matching the passed-in criteria.

create(title, filepath, sha256_initial, …)

Create a track with the provided parameters.

del_artist(trk, artist_id, role, conn)

Delete the provided artist/role combo to the provided track.

delete(trk, conn)

Delete a track.

exists(id, conn)

Return whether a track exists with the given ID.

from_filepath(filepath, conn)

Return the track with the provided filepath.

from_id(id_, conn)

Return the track with the provided ID.

from_row(row)

Return a track dataclass containing data from a row in the database.

from_sha256(sha256, conn)

Return the track with the provided sha256 hash.

from_sha256_initial(sha256_initial, conn)

Return the track with the provided sha256_initial (hash of the first 1KB) hash.

in_favorites(trk, user_id, conn)

Return whether this track is in the favorites of the passed-in user.

release(trk, conn)

Get the release that this track belongs to.

search(conn, *[, search, playlist_ids, …])

Search for tracks matching the passed-in criteria.

update(trk, conn, **changes)

Update a track and persist changes to the database.
class src.library.track.T(id, filepath, sha256, sha256_initial, title, release_id, duration, track_number, disc_number=None)

A track dataclass.

disc_number: Optional[str] = None
duration: int
filepath: pathlib.Path
id: int
release_id: int
sha256: Optional[bytes]

A hash of the audio file.

sha256_initial: bytes

A hash of the first 1KB of the file.

title: str
track_number: str
src.library.track.add_artist(trk, artist_id, role, conn)

Add the provided artist/role combo to the provided track.

Parameters

  • trk (src.library.track.T) – The track to add the artist to.

  • artist_id (int) – The ID of the artist to add.

  • role (tagfiles._common.ArtistRoles) – The role to add the artist with.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

src.library.track.T

Returns

The track that was passed in.

Raises

  • NotFound – If no artist has the given artist ID.

  • AlreadyExists – If the artist/role combo is already on the track.

src.library.track.artists(trk, conn)

Get the artists that contributed to a track and their roles.

Parameters

  • trk (src.library.track.T) – The track whose artists to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

list[dict]

Returns

A list of {"artist": artist.T, "role": ArtistRole} dicts.

src.library.track.calculate_track_full_sha256(trk, conn)

Given a track, calculate its full SHA256. If the newly calculated SHA256 is equivalent to an existing track’s SHA256, delete the passed-in track and raise a Duplicate error with the existing track.

Parameters

  • trk (src.library.track.T) – The track.

  • conn (sqlite3.Connection) – A connection to the DB.

Return type

bytes

Returns

The calculated SHA256.

Raises

  • FileNotFoundError – If the track no longer exists.

  • Duplicate – If the calculated sha256 is the same as an existing track. The existing track is attached to the error.

src.library.track.count(conn, *, search='', playlist_ids=[], artist_ids=[], years=[])

Fetch the number of tracks matching the passed-in criteria. Parameters are optional; omitted ones are excluded from the matching criteria.

Parameters

  • search (str) – A search string. We split this up into individual punctuation-less tokens and return tracks whose titles and artists contain each token.

  • playlist_ids (list[int]) – A list of playlist IDs. We match tracks by the playlists in this list. For a track to match, it must be in all playlists in this list.

  • artist_ids (list[int]) – A list of artist IDs. We match tracks by the artists in this list. For a track to match, all artists in this list must be included.

  • years (list[int]) – A list of years. Filter out tracks that were not released in one of the years in this list.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

int

Returns

The number of matching releases.

src.library.track.create(title, filepath, sha256_initial, release_id, artists, duration, track_number, disc_number, conn, sha256=None)

Create a track with the provided parameters.

If a track already exists with the same SHA256, the filepath of that track will be set to the passed-in filepath and nothing else will be done.

Parameters

  • title (str) – The title of the track.

  • filepath (pathlib.Path) – The filepath of the track.

  • sha256_initial (bytes) – The SHA256 of the first 1KB of the track file.

  • release_id (int) – The ID of the release that this track belongs to.

  • artists (list[dict]) – The artists that contributed to this track. A list of {"artist_id": int, "role": ArtistRole} mappings.

  • duration (int) – The duration of this track, in seconds.

  • track_number (str) – The track number.

  • disc_number (str) – The disc number.

  • sha256 (typing.Optional[bytes]) – The full SHA256 of the track file. This should generally not be passed in–calculating a SHA256 requires a filesystem read of several MB, and we want to do that lazily. But we allow it to be passed in for testing and cases where efficiency doesn’t matter.

Return type

src.library.track.T

Returns

The newly created track.

Raises

  • NotFound – If no release has the given release ID or no artist corresponds with any of the given artist IDs.

  • Duplicate – If a track with the same filepath already exists. The duplicate track is passed as the entity argument.

src.library.track.del_artist(trk, artist_id, role, conn)

Delete the provided artist/role combo to the provided track.

Parameters

  • trk (src.library.track.T) – The track to delete the artist from.

  • artist_id (int) – The ID of the artist to delete.

  • role (tagfiles._common.ArtistRoles) – The role of the artist on the track.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

src.library.track.T

Returns

The track that was passed in.

Raises

  • NotFound – If no artist has the given artist ID.

  • DoesNotExist – If the artist is not on the track.

src.library.track.delete(trk, conn)

Delete a track.

Parameters

  • trk (src.library.track.T) – The track to delete.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

None

src.library.track.exists(id, conn)

Return whether a track exists with the given ID.

Parameters

id (int) – The ID to check.

Return type

bool

Returns

Whether a track has the given ID.

src.library.track.from_filepath(filepath, conn)

Return the track with the provided filepath.

Parameters

  • filepath (typing.Union[pathlib.Path, str]) – The filepath of the track to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.track.T]

Returns

The track with the provided filepath, if it exists.

src.library.track.from_id(id_, conn)

Return the track with the provided ID.

Parameters

  • id – The ID of the track to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.track.T]

Returns

The track with the provided ID, if it exists.

src.library.track.from_row(row)

Return a track dataclass containing data from a row in the database.

Parameters

row (typing.Union[dict, sqlite3.Row]) – A row from the database.

Return type

src.library.track.T

Returns

A track dataclass.

src.library.track.from_sha256(sha256, conn)

Return the track with the provided sha256 hash.

WARNING: The sha256 attribute is populated lazily. It may not exist. Only use this function in a scenario where the sha256 value is guaranteed to exist.

Parameters

  • sha256 (bytes) – The sha256 hash of the track to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.track.T]

Returns

The track with the provided sha256 hash, if it exists.

src.library.track.from_sha256_initial(sha256_initial, conn)

Return the track with the provided sha256_initial (hash of the first 1KB) hash.

Parameters

  • sha256_initial (bytes) – The sha256_initial of the track to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.track.T]

Returns

The track with the provided ID, if it exists.

src.library.track.in_favorites(trk, user_id, conn)

Return whether this track is in the favorites of the passed-in user.

Parameters

  • trk (src.library.track.T) – The provided track.

  • user_id (int) – The ID of the user whose favorites to check.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

bool

Returns

Whether the track is in the user’s favorites.

Raises

DoesNotExist – If the user’s favorites does not exist.

src.library.track.release(trk, conn)

Get the release that this track belongs to.

Parameters

  • trk (src.library.track.T) – The track whose artists to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

src.library.release.T

Returns

A list of {"artist": artist.T, "role": ArtistRole} dicts.

src.library.track.search(conn, *, search='', playlist_ids=[], artist_ids=[], years=[], page=1, per_page=None, sort=None, asc=True)

Search for tracks matching the passed-in criteria. Parameters are optional; omitted ones are excluded from the matching criteria.

Parameters

  • search (str) – A search string. We split this up into individual punctuation-less tokens and return tracks whose titles and artists contain each token.

  • playlist_ids (list[int]) – A list of playlist IDs. We match tracks by the playlists in this list. For a track to match, it must be in all playlists in this list.

  • artist_ids (list[int]) – A list of artist IDs. We match tracks by the artists in this list. For a track to match, all artists in this list must be included.

  • years (list[int]) – A list of years. Filter out tracks that were not released in one of the years in this list.

  • page (int) – Which page of tracks to return.

  • per_page (typing.Optional[int]) – The number of tracks per page. Pass None to return all releases (this will ignore page).

  • sort (typing.Optional[src.enums.TrackSort]) – How to sort the matching releases. If not explicitly passed, this defaults to SEARCH_RANK if search is not None and RECENTLY_ADDED otherwise.

  • asc (bool) – If true, sort in ascending order. If false, descending.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

list[src.library.track.T]

Returns

The matching tracks on the current page.

src.library.track.update(trk, conn, **changes)

Update a track and persist changes to the database. To update a value, pass it in as a keyword argument. To keep the original value, do not pass in a keyword argument.

Parameters

  • trk (src.library.track.T) – The track to update.

  • conn (sqlite3.Connection) – A connection to the database.

  • title (str) – New track title.

  • release_id (int) – ID of the new release.

  • track_number (str) – New track number.

  • disc_number (str) – New disc number.

Return type

src.library.track.T

Returns

The updated track.

Raises

NotFound – If the new release ID does not exist.

User

Classes:

T(id, nickname, csrf_token)

A user dataclass.

Functions:

check_token(usr, token, conn)

Check if a given token is valid for a user.

create(nickname, conn)

Create a user.

exists(id, conn)

Return whether a user exists with the given ID.

from_id(id, conn)

Get a user dataclass from the user’s ID.

from_nickname(nickname, conn)

Get a user dataclass from the user’s nickname.

from_row(row)

Return a user dataclass containing data from a row from the database.

from_token(token, conn)

Get a user dataclass from the user’s token.

new_token(usr, conn)

Generate a new token for a given user.

post_create(user_id, conn)

This is a helper function used in the create function.

update(usr, conn, **changes)

Update a user and persist changes to the database.
class src.library.user.T(id, nickname, csrf_token)

A user dataclass.

csrf_token: bytes
id: int
nickname: str
src.library.user.check_token(usr, token, conn)

Check if a given token is valid for a user.

Parameters

  • usr (src.library.user.T) – The user to check.

  • token (bytes) – The token to check.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

bool

Returns

Whether the token is valid.

src.library.user.create(nickname, conn)

Create a user.

Note: This function commits before returning. This is because it spawns a task that depends on the written data.

Parameters

  • nickname (str) – The nickname of the user to create.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

tuple[src.library.user.T, bytes]

Returns

The newly created user and their token.

Raises
src.library.user.exists(id, conn)

Return whether a user exists with the given ID.

Parameters

id (int) – The ID to check.

Return type

bool

Returns

Whether a user has the given ID.

src.library.user.from_id(id, conn)

Get a user dataclass from the user’s ID.

Parameters

  • id (int) – The ID of the user to get.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.user.T]

Returns

The user, if they exist.

src.library.user.from_nickname(nickname, conn)

Get a user dataclass from the user’s nickname.

Parameters

  • nickname (str) – The nickname of the user to get.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.user.T]

Returns

The user, if they exist.

src.library.user.from_row(row)

Return a user dataclass containing data from a row from the database.

Parameters

row (typing.Union[dict, sqlite3.Row]) – A row from the database.

Return type

src.library.user.T

Returns

A user dataclass.

src.library.user.from_token(token, conn)

Get a user dataclass from the user’s token. The returned user is necessarily authenticated.

How it works: We store a unique prefix of each user’s token and match on that.

Parameters

  • token (bytes) – The token of the user to get.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.user.T]

Returns

The user, if they exist.

src.library.user.new_token(usr, conn)

Generate a new token for a given user.

Parameters

  • usr (src.library.user.T) – The user to generate a new token for.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

bytes

Returns

The new token.

Raises

TokenGenerationFailure – If we could not generate a suitable token.

src.library.user.post_create(user_id, conn)

This is a helper function used in the create function. If you create a user manually, without using the create function, call this afterwards. This is used in the e2e testing developer endpoint.

Return type

None

src.library.user.update(usr, conn, **changes)

Update a user and persist changes to the database. To update a value, pass it in as a keyword argument. To keep the original value, do not pass in a keyword argument.

Parameters

  • usr (src.library.user.T) – The user to update.

  • conn (sqlite3.Connection) – A connection to the database.

  • nickname (str) – New user nickname.

Return type

src.library.user.T

Returns

The updated user.

Image

Classes:

T(id, path)

An image dataclass.

Functions:

create(path, conn)

Create an image with the given path.

delete(img, conn)

Delete an image (and its associated image on disk).

from_id(id, conn)

Return the image with the provided ID.

from_path(path, conn)

Return the image with the provided path.

from_row(row)

Return an image dataclass containing data from a row from the database.

thumbnail_path(img)

Given an image, return the path to the thumbnail of an image.
class src.library.image.T(id, path)

An image dataclass.

id: int
path: pathlib.Path
src.library.image.create(path, conn)

Create an image with the given path.

Parameters

  • path (typing.Union[pathlib.Path, str]) – The path of the image file.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

src.library.image.T

Returns

The newly created image.

Raises

Duplicate – If an image with the given path already exists. The duplicate image is passed as the entity argument.

src.library.image.delete(img, conn)

Delete an image (and its associated image on disk).

Parameters

  • img (src.library.image.T) – The image to delete.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

None

src.library.image.from_id(id, conn)

Return the image with the provided ID.

Parameters

  • id (int) – The ID of the image to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.image.T]

Returns

An image with the provided ID, if it exists.

src.library.image.from_path(path, conn)

Return the image with the provided path.

Parameters

  • path (typing.Union[pathlib.Path, str]) – The path of the image to fetch.

  • conn (sqlite3.Connection) – A connection to the database.

Return type

typing.Optional[src.library.image.T]

Returns

An image with the provided ID, if it exists.

src.library.image.from_row(row)

Return an image dataclass containing data from a row from the database.

Parameters

row (typing.Union[dict, sqlite3.Row]) – A row from the database.

Return type

src.library.image.T

Returns

An image dataclass.

src.library.image.thumbnail_path(img)

Given an image, return the path to the thumbnail of an image.

Parameters

img (src.library.image.T) – An image.

Return type

pathlib.Path

Returns

The path to the thumbnail.