vkpymusic.Service

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)

Functions

__init__(user_agent, token)

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.