Clients

class amqcsl.DBClient(username=None, password=None, session_path=PosixPath('amq_session.txt'), max_batch_size=100, max_query_size=1500, lists=None, groups=None, queue=NOTHING)

Client for accessing the db. If session cookie is valid, username and password may be omitted.

username: str | None

DB username

password: str | None

DB password

session_path: Path

Filepath to look for/store session cookie in, defaults to amq_session.txt

max_batch_size: int

Maximum batch size when querying db

max_query_size: int

Maximum number of queries when iterating

is_sync()

Check for if client is synchronous

Return type:

bool

Returns:

True

property client: Client

Underlying httpx.Client

property queue: list[Bundle[Any]]
process(bundle)

Processes a bundle (Mainly for internal use)

Parameters:

bundle (Bundle[TypeVar(R)]) – Bundle

Return type:

TypeVar(R)

Returns:

Output of the bundle

enqueue(bundle)

Add an object to the queue

Parameters:

obj – An object wrapper around a request

commit(*, stop_if_err=True)

Commit changes in the queue

Parameters:

stop_if_err (bool) – Stop sending requests if one of them errors

logout()

Logout the client

Raises:

AMQCSLError – httpx client doesn’t exist yet

property lists: CSLLists

Dictionary of user’s lists, indexed by name

property groups: CSLGroups

Dictionary of DB groups, indexed by name

iter_tracks(search_term='', *, groups=(), active_list=None, missing_audio=False, missing_info=False, from_active_list=None, batch_size=50)

Iterate over tracks matching search parameters

Parameters:

  • search_term (str) – Search term

  • groups (Iterable[CSLGroup]) – List of groups to restrict to, leave empty if no restriction

  • active_list (CSLList | None) – List to restrict search by

  • missing_audio (bool) – Restrict to songs without audio

  • missing_info (bool) – Restrict to songs missing info

  • from_active_list (bool | None) – Restrict to songs from active list, defaults to True if active_list is given and False otherwise

  • batch_size (int) – How many tracks to query at once (page size)

Yields:

CSLTrack

iter_songs(search_term, *, batch_size=50)

Iterate over songs matching search_term

Parameters:

  • search_term (str) – Term to search for

  • batch_size (int) – Number of songs per page

Yields:

CSLSongSample

iter_artists(search_term, *, batch_size=50)

Iterator over artists matching search_term

Parameters:

  • search_term (str) – Term to search for

  • batch_size (int) – Number of artists per page

Yields:

CSLArtistSample

get_song(song)

Fetch detailed song info from db

Parameters:

song (CSLSongSample) – CSLSongSample, probably from iter_songs

Return type:

CSLSong

Returns:

CSLSong

get_artist(artist)

Fetch detailed artist info from db

Parameters:

artist (CSLArtistSample) – CSLArtistSample, probably from iter_artists

Return type:

CSLArtist

Returns:

CSLArtist

get_metadata(track)

Fetch metadata info from db

Parameters:

track (CSLTrack) – CSLTrack to get metadata from

Return type:

CSLMetadata | None

Returns:

CSLMetadata, or None if it doesn’t have any metadata

create_list(name, *csl_lists)

Make a list

Parameters:

  • name (str) – name of the list

  • *csl_lists (CSLList) – Lists to pull tracks from

Return type:

CSLList

Returns:

Newly created list

Raises:

ListCreateError – Error if the request gives an error, probably because the list already exists

list_edit(csl_list, *, name=None, add=(), remove=())

Edit a list

Parameters:

  • csl_list (CSLList) – List to edit

  • name (str | None) – New name

  • add_tracks – Tracks to add

  • remove_tracks – Tracks to remove

Return type:

None

create_group(name)

Create a group

Parameters:

name (str) – Name of the group

Return type:

CSLGroup

Returns:

Newly created group

group_edit(group, name, *, queue=False)

Edit a group

Parameters:

  • group (CSLGroup) – CSLGroup

  • name (str) – New name of the group

Return type:

None

group_delete(group, *, queue=False)

Delete a group

Parameters:

group (CSLGroup) – CSLGroup

Return type:

None

song_edit(song, name=None, disambiguation=None, *, queue=False)

Edit a song

Parameters:

  • song (CSLSong) – CSLSong

  • name (str | None) – New name

  • disambiguation (str | None) – New disambiguation

Return type:

None

song_delete(song, *, queue=False)

Delete a song

Parameters:

song (CSLSong) – CSLSong

Return type:

None

song_add_metadata(song, *metas, queue=False)

Add metadata to a song

Parameters:

  • song (CSLSong) – CSLSong

  • *metas (TypeAliasType) – Metadata to add

  • queue (bool) – Whether to queue the request, defaults to False

Return type:

None

song_delete_metadata(song, meta, queue=False)

Remove metadata from a song

Parameters:
Return type:

None

track_add_metadata(track, *metas, override=None, existing_meta=None, queue=False)

Add metadata to a track

Parameters:

  • track (CSLTrack) – CSLTrack

  • *metas (TypeAliasType) – Metadata to add

  • override (bool | None) – Change metadata to override or append

  • existing_meta (CSLMetadata | None) – Existing metadata on the track, pass in to avoid duplicating metadata

  • queue (bool) – Whether to queue the request, defaults to False

Raises:

ValueError – If non-metadata is passed into metas

Return type:

None

track_remove_metadata(track, meta, *, queue=False)

Remove metadata from a track

Parameters:
Return type:

None

track_edit(track, *, artist_credits=None, groups=None, name=None, original_artist=None, original_name=None, song=None, type=None, queue=False)

Edit a track

Parameters:

  • track (CSLTrack) – CSLTrack

  • artist_credits (Sequence[TrackPutArtistCredit] | None) – List of new artist credits

  • groups (Sequence[CSLGroup] | None) – List of new groups

  • name (str | None) – New track name

  • original_artist (str | None) – New track original artist

  • original_name (str | None) – New track original name

  • song (NewSong | CSLSongSample | None) – New song

  • type (TypeAliasType | None) – New track type

  • queue (bool) – Whether to queue the request, defaults to False

Raises:

ValueError – New track type is not a valid track type

Return type:

None

Returns:

Newly edited track

create_album(name, original_name, year, groups, tracks, *, queue=False)

Create an album

Parameters:

  • name (str) – Album name

  • original_name (str) – Original album name

  • year (int) – Year album was created

  • groups (Iterable[CSLGroup]) – Groups associated with album

  • tracks (Sequence[Sequence[AlbumTrack]]) – CSLTrack[][], where each CSLTrack[] is a disc

  • queue (bool) – Whether to queue the request, defaults to False

Return type:

None

add_audio(track, audio_path, *, queue=False)

Add audio to a track

Parameters:

  • track (CSLTrack) – CSLTrack

  • audio_path (str | PathLike[str]) – Path to the audio file

  • queue (bool) – Whether to queue the request, defaults to False

Raises:

QueryError – Audio path is invalid

Return type:

None

class amqcsl.AsyncDBClient(username=None, password=None, session_path=PosixPath('amq_session.txt'), max_batch_size=100, max_query_size=1500, max_request_count=15, lists=NOTHING, groups=NOTHING, queue=NOTHING)

Async client for accessing the db. If session cookie is valid, username and password may be omitted.

username: str | None

DB username

password: str | None

DB password

session_path: Path

Filepath to look for/store session cookie in, defaults to amq_session.txt

max_batch_size: int

Maximum batch size when querying db

max_query_size: int

Maximum number of queries when iterating

max_request_count: int

Maximum number of concurrent requests

is_sync()

Check for if client is synchronous

Return type:

bool

Returns:

False

property client: AsyncClient

Underlying httpx.Client

property queue: list[Bundle[Any]]
async process(bundle)

Processes a bundle (Mainly for internal use)

Parameters:

bundle (Bundle[TypeVar(R)]) – Bundle

Return type:

TypeVar(R)

Returns:

Output of the bundle

enqueue(bundle)

Add an object to the queue

Parameters:

obj – An object wrapper around a request

async commit(*, stop_if_err=True)

Commit changes in the queue

Parameters:

stop_if_err (bool) – Stop sending requests if one of them errors

async logout()

Logout the client

Raises:

AMQCSLError – httpx client doesn’t exist yet

property lists: CSLLists

Dictionary of user’s lists, indexed by name

async refresh_lists()

Refresh client.lists (usually done automatically)

Return type:

None

property groups: CSLGroups

Dictionary of DB groups, indexed by name

async refresh_groups()

Refresh client.groups (usually done automatically)

Return type:

None

async iter_tracks(search_term='', *, groups=(), active_list=None, missing_audio=False, missing_info=False, from_active_list=None, batch_size=50)

Gather tracks matching search term, optionally applying a continuation to each track

Parameters:

  • search_term (str) – Search term

  • groups (Iterable[CSLGroup]) – List of groups to restrict to, leave empty if no restriction

  • active_list (CSLList | None) – List to restrict search by

  • missing_audio (bool) – Restrict to songs without audio

  • missing_info (bool) – Restrict to songs missing info

  • from_active_list (bool | None) – Restrict to songs from active list, defaults to True if active_list is given and False otherwise

  • batch_size (int) – How many tracks to query at once (page size)

Return type:

AsyncIterator[CSLTrack]

Returns:

Iterable of results from calling func on each track

async iter_songs(search_term, *, batch_size=50)

Gather songs matching search term, optionally applying a continuation to each song

Parameters:

  • search_term (str) – Term to search for

  • batch_size (int) – Number of songs per page

Return type:

AsyncIterator[CSLSongSample]

Returns:

Iterable of results from calling func on each song

async iter_artists(search_term, *, batch_size=50)

Gather artists matching search term, optionally applying a continuation to each artist

Parameters:

  • search_term (str) – Term to search for

  • batch_size (int) – Number of artists per page

Return type:

AsyncIterator[CSLArtistSample]

Returns:

Iterable of results from calling func on each artist

async get_song(song)

Fetch detailed song info from db

Parameters:

song (CSLSongSample) – CSLSongSample, probably from iter_songs

Return type:

CSLSong

Returns:

CSLSong

async get_artist(artist)

Fetch detailed artist info from db

Parameters:

artist (CSLArtistSample) – CSLArtistSample, probably from iter_artists

Return type:

CSLArtist

Returns:

CSLArtist

async get_metadata(track)

Fetch metadata info from db

Parameters:

track (CSLTrack) – CSLTrack to get metadata from

Return type:

CSLMetadata | None

Returns:

CSLMetadata, or None if it doesn’t have any metadata

async create_list(name, *csl_lists)

Make a list

Parameters:

  • name (str) – name of the list

  • *csl_lists (CSLList) – Lists to pull tracks from

Return type:

CSLList

Returns:

Newly created list

Raises:

ListCreateError – Error if the request gives an error, probably because the list already exists

async list_edit(csl_list, *, name=None, add=(), remove=())

Edit a list

Parameters:

  • csl_list (CSLList) – List to edit

  • name (str | None) – New name

  • add_tracks – Tracks to add

  • remove_tracks – Tracks to remove

Return type:

None

async create_group(name)

Create a group

Parameters:

name (str) – Name of the group

Return type:

CSLGroup

Returns:

Newly created group

async group_edit(group, name)

Edit a group

Parameters:

  • group (CSLGroup) – CSLGroup

  • name (str) – New name of the group

Return type:

None

async group_delete(group)

Delete a group

Parameters:

group (CSLGroup) – CSLGroup

Return type:

None

async song_edit(song, name=None, disambiguation=None)

Edit a song

Parameters:

  • song (CSLSong) – CSLSong

  • name (str | None) – New name

  • disambiguation (str | None) – New disambiguation

Return type:

None

async song_delete(song)

Delete a song

Parameters:

song (CSLSong) – CSLSong

Return type:

None

async song_add_metadata(song, *metas, queue=False)

Add metadata to a song

Parameters:

  • song (CSLSong) – CSLSong

  • *metas (TypeAliasType) – Metadata to add

  • queue (bool) – Whether to queue the request, defaults to False

Return type:

None

async song_delete_metadata(song, meta, queue=False)

Remove metadata from a song

Parameters:
Return type:

None

async track_add_metadata(track, *metas, override=None, existing_meta=None, queue=False)

Add metadata to a track

Parameters:

  • track (CSLTrack) – CSLTrack

  • *metas (TypeAliasType) – Metadata to add

  • override (bool | None) – Change metadata to override or append

  • existing_meta (CSLMetadata | None) – Existing metadata on the track, pass in to avoid duplicating metadata

  • queue (bool) – Whether to queue the request, defaults to False

Raises:

ValueError – If non-metadata is passed into metas

Return type:

None

async track_remove_metadata(track, meta, queue=False)

Remove metadata from a track

Parameters:
Return type:

None

async track_edit(track, *, artist_credits=None, groups=None, name=None, original_artist=None, original_name=None, song=None, type=None, queue=False)

Edit a track

Parameters:

  • track (CSLTrack) – CSLTrack

  • artist_credits (Sequence[TrackPutArtistCredit] | None) – List of new artist credits

  • groups (Sequence[CSLGroup] | None) – List of new groups

  • name (str | None) – New track name

  • original_artist (str | None) – New track original artist

  • original_name (str | None) – New track original name

  • song (NewSong | CSLSongSample | None) – New song

  • type (TypeAliasType | None) – New track type

  • queue (bool) – Whether to queue the request, defaults to False

Raises:

ValueError – New track type is not a valid track type

Return type:

None

async create_album(name, original_name, year, groups, tracks, *, queue=False)

Create an album

Parameters:

  • name (str) – Album name

  • original_name (str) – Original album name

  • year (int) – Year album was created

  • groups (Iterable[CSLGroup]) – Groups associated with album

  • tracks (Sequence[Sequence[AlbumTrack]]) – CSLTrack[][], where each CSLTrack[] is a disc

  • queue (bool) – Whether to queue the request, defaults to False

Return type:

None

async add_audio(track, audio_path, *, queue=False)

Add audio to a track

Parameters:

  • track (CSLTrack) – CSLTrack

  • audio_path (str | PathLike[str]) – Path to the audio file

  • queue (bool) – Whether to queue the request, defaults to False

Raises:

QueryError – Audio path is invalid

Return type:

None