vkpymusic

VKpyMusic

A library for interacting with music in VK.

Provides a convenient API for authorization, receiving audio recordings, searching for music, as well as downloading individual songs and playlists of the user in VK.

Classes:

Name	Description
Client	A class that stores the user agent string, client ID, and client secret.
TokenReceiver	A class for receiving an access token.
Service	A class for interacting with VK API.

Modules:

Name	Description
models	A module that contains all models for vkpymusic.
utils	A module that contains utilities for conversion and logging.
vk_api	A module that contains classes for requests to VK API.

vkpymusic.Client(user_agent, client_id, client_secret)

A class that stores the user agent string, client ID, and client secret.

Attributes:

Name	Type	Description
user_agent	str	The user agent string.
client_id	str	The client ID.
client_secret	str	The client secret.

Initializes a Client object.

Parameters:

Name	Type	Description	Default
user_agent	str	The user agent string.	required
client_id	str	The client ID.	required
client_secret	str	The client secret.	required

vkpymusic.TokenReceiver(login, password, client='Kate', logger=create_logger(__name__))

A class that is responsible for performing authorization using the available login and password. It interacts with the VK API to obtain an access token. The TokenReceiver class provides methods for handling captcha, 2-factor authentication, and various error scenarios.

Attributes:

Name	Type	Description
client	Client	The client object.
__login	str	The login.
__password	str	The password.
__token	str	The token.
_logger	Logger	The logger.

Example usage:

>>> receiver = TokenReceiver(login="my_username", password="my_password")
>>> if receiver.auth():
...    receiver.get_token()
...    receiver.save_to_config()
>>> # or
>>> if asyncio.run(receiver.auth()):
...     receiver.get_token()
...     receiver.save_to_config()

Initialize TokenReceiver.

Parameters:

Name	Type	Description	Default
login	str	Login to VK.	required
password	str	Password to VK.	required
client	str	Client to VK (default value = "Kate").	'Kate'
logger	Logger	Logger (default value = my logger).	create_logger(__name__)

auth(on_captcha=on_captcha_handler, on_2fa=on_2fa_handler, on_invalid_client=on_invalid_client_handler, on_critical_error=on_critical_error_handler)

Performs SYNC authorization using the available login and password. If necessary, interactively accepts a code from SMS or captcha.

Parameters:

Name	Type	Description	Default
on_captcha	Callable[[str], str]	Handler to captcha. Get url image. Return key.	on_captcha_handler
on_2fa	Callable[[], str]	Handler to 2-factor auth. Return captcha.	on_2fa_handler
on_invalid_client	Callable[[], None]	Handler to invalid client.	on_invalid_client_handler
on_critical_error	Callable[[Any], None]	Handler to critical error. Get response.	on_critical_error_handler

Returns:

Name	Type	Description
bool	bool	Boolean value indicating whether authorization was successful or not.

auth_async(on_captcha=on_captcha_handler_async, on_2fa=on_2fa_handler_async, on_invalid_client=on_invalid_client_handler_async, on_critical_error=on_critical_error_handler_async) async

Performs ASYNC authorization using the available login and password. If necessary, interactively accepts a code from SMS or captcha.

Parameters:

Name	Type	Description	Default
on_captcha	Callable[[str], str]	ASYNC handler to captcha. Get url image. Return key.	on_captcha_handler_async
on_2fa	Callable[[], str]	ASYNC handler to 2-factor auth. Return captcha.	on_2fa_handler_async
on_invalid_client	Callable[[], None]	ASYNC handler to invalid client.	on_invalid_client_handler_async
on_critical_error	Callable[[Any], None]	ASYNC handler to crit error. Get response.	on_critical_error_handler_async

Returns:

Name	Type	Description
bool	bool	Boolean value indicating whether authorization was successful or not.

get_token()

Returns the token if exists.

save_to_config(file_path='config_vk.ini')

Save token and user agent data in config (if authorisation was successful).

Parameters:

Name	Type	Description	Default
file_path	str	Filename of config (default value = "config_vk.ini").	'config_vk.ini'

create_path(file_path) staticmethod

Create path before and after this for different funcs.

Parameters:

Name	Type	Description	Default
file_path	str	Relative path to file.	required

Returns:

Name	Type	Description
str	str	Absolute path to file.

vkpymusic.Service(user_agent, token)

A class for working with VK API.

Attributes:

Name	Type	Description
user_agent	str	User agent string.
__token	str	Token for VK API.
logger	Logger	The logger for class.

Example usage:

>>> service = Service.parse_config()
>>> songs = service.search_songs_by_text("Imagine Dragons")
>>> for song in songs:
...     Service.save_music(song)
>>> // or
>>> songs = await service.search_songs_by_text_async("Imagine Dragons")
>>> for song in songs:
...     await Service.save_music_async(song)

Initializes a Service object.

Parameters:

Name	Type	Description	Default
user_agent	str	User agent string.	required
token	str	Token for VK API.	required

set_logger(logger) classmethod

Set logger for class.

Parameters:

Name	Type	Description	Default
logger	Logger	Logger.	required

parse_config(filename='config_vk.ini') classmethod

Create an instance of Service from config created by 'TokenReceiver'.

Parameters:

Name	Type	Description	Default
filename	str	Filename of config (default = "config_vk.ini").	'config_vk.ini'

del_config(filename='config_vk.ini') classmethod

Delete config created by 'TokenReceiver'.

Parameters:

Name	Type	Description	Default
filename	str	Filename of config (default value = "config_vk.ini").	'config_vk.ini'

fill_user_agent_and_token(request)

Fill user-agent and token in request.

Parameters:

Name	Type	Description	Default
request	VkApiRequest	Request to fill.	required

get_user_info()

Get user info by token (sync).

Returns:

Name	Type	Description
UserInfo	UserInfo	Instance of 'UserInfo'.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_user_info_async() async

Get user info by token (async).

Returns:

Name	Type	Description
UserInfo	UserInfo	Instance of 'UserInfo'.

Raises:

Type	Description
VkApiException	If the response contains an error.

check_token(token) classmethod

Check token for VK API (sync).

Parameters:

Name	Type	Description	Default
token	str	Token for VK API.	required

Returns:

Name	Type	Description
bool	bool	True if token is valid, False otherwise.

check_token_async(token) async classmethod

Check token for VK API (async).

Parameters:

Name	Type	Description	Default
token	str	Token for VK API.	required

Returns:

Name	Type	Description
bool	bool	True if token is valid, False otherwise.

is_token_valid()

Check token for VK API (sync).

Returns:

Name	Type	Description
bool	bool	True if token is valid, False otherwise.

is_token_valid_async() async

Check token for VK API (async).

Returns:

Name	Type	Description
bool	bool	True if token is valid, False otherwise.

get_count_by_user_id(user_id)

Get count of all user's songs (sync).

Parameters:

Name	Type	Description	Default
user_id	str | int	VK user id. (NOT USERNAME! vk.com/id*).	required

Returns:

Name	Type	Description
int	int	count of all user's songs or -1 if access denied.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_count_by_user_id_async(user_id) async

Get count of all user's songs (async).

Parameters:

Name	Type	Description	Default
user_id	str | int	VK user id. (NOT USERNAME! vk.com/id*).	required

Returns:

Name	Type	Description
int	int	count of all user's songs or -1 if access denied.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_songs_by_id(audios_ids)

Get songs by ids (sync).

Parameters:

Name	Type	Description	Default
audios_ids	List[str]	The list of audio IDs in the format "[owner_id]_[audio_id]".	required

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_songs_by_id_async(audios_ids) async

Get songs by ids (async).

Parameters:

Name	Type	Description	Default
audios_ids	List[str]	The list of audio IDs in the format "[owner_id]_[audio_id]".	required

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_songs_by_userid(user_id, count=100, offset=0)

Search songs by owner/user id (sync).

Parameters:

Name	Type	Description	Default
user_id	str | int	VK user id. (NOT USERNAME! vk.com/id*).	required
count	int	Count of resulting songs (for VK API: default/max = 100).	100
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_songs_by_userid_async(user_id, count=100, offset=0) async

Search songs by owner/user id (async).

Parameters:

Name	Type	Description	Default
user_id	str | int	VK user id. (NOT USERNAME! vk.com/id*).	required
count	int	Count of resulting songs (for VK API: default/max = 100).	100
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_songs_by_playlist_id(user_id, playlist_id, access_key, count=100, offset=0)

Get songs by playlist id (sync).

Parameters:

Name	Type	Description	Default
user_id	str | int	VK user id. (NOT USERNAME! vk.com/id*).	required
playlist_id	int	VK playlist id. (Take it from methods for playlist).	required
access_key	str	VK access key. (Take it from methods for playlist).	required
count	int	Count of resulting songs (for VK API: default/max = 100).	100
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_songs_by_playlist_id_async(user_id, playlist_id, access_key, count=100, offset=0) async

Get songs by playlist id (async).

Parameters:

Name	Type	Description	Default
user_id	str | int	VK user id. (NOT USERNAME! vk.com/id*).	required
playlist_id	int	VK playlist id. (Take it from methods for playlist).	required
access_key	str	VK access key. (Take it from methods for playlist).	required
count	int	Count of resulting songs (for VK API: default/max = 100).	100
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_songs_by_playlist(playlist, count=10, offset=0)

Get songs by instance of 'Playlist' (sync).

Parameters:

Name	Type	Description	Default
playlist	Playlist	Instance of 'Playlist' (take from methods for receiving Playlist).	required
count	int	Count of resulting songs (for VK API: default/max = 100).	10
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_songs_by_playlist_async(playlist, count=10, offset=0) async

Get songs by instance of 'Playlist' (async).

Parameters:

Name	Type	Description	Default
playlist	Playlist	Instance of 'Playlist' (take from methods for receiving Playlist).	required
count	int	Count of resulting songs (for VK API: default/max = 100).	10
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

search_songs_by_text(text, count=3, offset=0)

Search songs by text/query (sync).

Parameters:

Name	Type	Description	Default
text	str	Text of query. Can be title of song, author, etc.	required
count	int	Count of resulting songs (for VK API: default/max = 100).	3
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

search_songs_by_text_async(text, count=3, offset=0) async

Search songs by text/query (async).

Parameters:

Name	Type	Description	Default
text	str	Text of query. Can be title of song, author, etc.	required
count	int	Count of resulting songs (for VK API: default/max = 100).	3
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_playlists_by_userid(user_id, count=5, offset=0)

Get playlist by owner/user id (sync).

Parameters:

Name	Type	Description	Default
user_id	str or int	VK user id. (NOT USERNAME! vk.com/id*).	required
count	int	Count of resulting playlists (for VK API: default = 50, max = 100).	5
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Playlist]	list[Playlist]: List of playlists.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_playlists_by_userid_async(user_id, count=5, offset=0) async

Get playlist by owner/user id (async).

Parameters:

Name	Type	Description	Default
user_id	str or int	VK user id. (NOT USERNAME! vk.com/id*).	required
count	int	Count of resulting playlists (for VK API: default = 50, max = 100).	5
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Playlist]	list[Playlist]: List of playlists.

Raises:

Type	Description
VkApiException	If the response contains an error.

search_playlists_by_text(text, count=5, offset=0)

Search playlists by text/query (sync). Playlist - it user's collection of songs.

Parameters:

Name	Type	Description	Default
text	str	Text of query. Can be title of playlist, genre, etc.	required
count	int	Count of resulting playlists (for VK API: default = 50, max = 100).	5
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Playlist]	list[Playlist]: List of playlists.

Raises:

Type	Description
VkApiException	If the response contains an error.

search_playlists_by_text_async(text, count=5, offset=0) async

Search playlists by text/query (async). Playlist - it user's collection of songs.

Parameters:

Name	Type	Description	Default
text	str	Text of query. Can be title of playlist, genre, etc.	required
count	int	Count of resulting playlists (for VK API: default = 50, max = 100).	5
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Playlist]	list[Playlist]: List of playlists.

Raises:

Type	Description
VkApiException	If the response contains an error.

search_albums_by_text(text, count=5, offset=0)

Search albums by text/query (sync). Album - artists' album/collection of songs. In obj context - same as 'Playlist'.

Parameters:

Name	Type	Description	Default
text	str	Text of query. Can be title of album, name of artist, etc.	required
count	int	Count of resulting playlists (for VK API: default = 50, max = 100).	5
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Playlist]	list[Playlist]: List of albums.

Raises:

Type	Description
VkApiException	If the response contains an error.

search_albums_by_text_async(text, count=5, offset=0) async

Search albums by text/query (async). Album - artists' album/collection of songs. In obj context - same as 'Playlist'.

Parameters:

Name	Type	Description	Default
text	str	Text of query. Can be title of album, name of artist, etc.	required
count	int	Count of resulting playlists (for VK API: default = 50, max = 100).	5
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Playlist]	list[Playlist]: List of albums.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_popular(count=50, offset=0)

Get popular songs (sync). (Be careful, it always returns less than count)

Parameters:

Name	Type	Description	Default
count	int	Count of resulting songs (for VK API: default = 50, max = 500).	50
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_popular_async(count=50, offset=0) async

Get popular songs (async). (Be careful, it always returns less than count)

Parameters:

Name	Type	Description	Default
count	int	Count of resulting songs (for VK API: default = 50, max = 500).	50
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_recommendations(user_id=None, song_id=None, count=50, offset=0)

Get recommendations by user id or song id (sync). (Be careful, it always returns less than count)

Parameters:

Name	Type	Description	Default
user_id	int	VK user id. (NOT USERNAME! vk.com/id*).	None
song_id	int	VK song id.	None
count	int	Count of resulting songs (for VK API: default = 50, max = 300).	50
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

get_recommendations_async(user_id=None, song_id=None, count=50, offset=0) async

Get recommendations by user id or song id (async). (Be careful, it always returns less than count)

Parameters:

Name	Type	Description	Default
user_id	int	VK user id. (NOT USERNAME! vk.com/id*).	None
song_id	int	VK song id.	None
count	int	Count of resulting songs (for VK API: default = 50, max = 300).	50
offset	int	Set offset for result. For example, count = 100, offset = 100 -> 101-200.	0

Returns:

Type	Description
List[Song]	list[Song]: List of songs.

Raises:

Type	Description
VkApiException	If the response contains an error.

save_music(song, overwrite=False) classmethod

Save song (sync) to '{workDirectory}/Music/{song name}.mp3'. If you wanna another behavior, you can override this method or use your own method for saving music.

Parameters:

Name	Type	Description	Default
song	Song	'Song' instance obtained from 'Service' methods.	required
overwrite	bool	If True, overwrite file if it exists. By default doesn't overwrite.	False

Returns:

Name	Type	Description
str	Optional[str]	relative path of downloaded music or None if error.

save_music_async(song, overwrite=False) async classmethod

Save song (async) to '{workDirectory}/Music/{song name}.mp3'. If you wanna another behavior, you can override this method or use your own method for saving music.

Parameters:

Name	Type	Description	Default
song	Song	'Song' instance obtained from 'Service' methods.	required
overwrite	bool	If True, overwrite file if it exists. By default doesn't overwrite.	False

Returns:

Name	Type	Description
str	Optional[str]	relative path of downloaded music or None if error.