vk_api

https://vk-api.readthedocs.io/en/latest/
Admin
vk_api is a Python module designed for creating scripts and interacting with the VKontakte (vk.com)...
Tokens:50,742
Snippets:234
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install vk_api using pip

Source: https://vk-api.readthedocs.io/en/latest/_sources/index.rst.txt

Use this command to install the vk_api library via pip. Ensure you are using pip3 for Python 3.

```shell
# pip3 install vk_api
```

--------------------------------

### Basic vk_api Authentication and Wall Post

Source: https://vk-api.readthedocs.io/en/latest/_sources/index.rst.txt

This example demonstrates how to authenticate with vk_api using a phone number and password, and then post a message to the wall. Ensure you have imported the vk_api library.

```python
import vk_api

vk_session = vk_api.VkApi('+71234567890', 'mypassword')
vk_session.auth()

vk = vk_session.get_api()

print(vk.wall.post(message='Hello world!'))
```

--------------------------------

### Get user albums

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/audio.html

Returns a list of albums for the specified owner.

```python
def get_albums(self, owner_id=None):
    """ Получить список альбомов пользователя

    :param owner_id: ID владельца (отрицательные значения для групп)
    """

    return list(self.get_albums_iter(owner_id))
```

--------------------------------

### Retrieve Audio Tracks as a List

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/audio.html

The get method returns a complete list of audio tracks by calling the iterative retrieval method.

```python
def get(self, owner_id=None, album_id=None, access_hash=None):
    """ Получить список аудиозаписей пользователя

    :param owner_id: ID владельца (отрицательные значения для групп)
    :param album_id: ID альбома
    :param access_hash: ACCESS_HASH альбома
    """

    return list(self.get_iter(owner_id, album_id, access_hash))
```

--------------------------------

### Retrieve User Albums Iteratively

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/audio.html

The get_albums_iter method provides a starting point for fetching user albums in chunks.

```python
def get_albums_iter(self, owner_id=None):
    """ Получить список альбомов пользователя (по частям)

    :param owner_id: ID владельца (отрицательные значения для групп)
    """

    if owner_id is None:
        owner_id = self.user_id

    offset = 0
```

--------------------------------

### VkBotLongPoll.listen()

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/bot_longpoll.html

Starts a continuous loop to listen for events from the server. This is a generator method that yields events as they arrive.

```APIDOC
## VkBotLongPoll.listen()

### Description
An infinite loop that continuously calls the check() method to retrieve and yield events from the server.

### Yields
- **Event** - Yields individual event objects as they are received from the server.
```

--------------------------------

### listen()

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/streaming.html

Establishes a WebSocket connection to listen for incoming streaming events.

```APIDOC
## WSS /stream

### Description
Establishes a WebSocket connection to receive real-time events from the streaming server.

### Response
- **event** (object) - The streaming event data received from the server.
```

--------------------------------

### VkApi.__init__

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/vk_api.html

Initializes the VkApi instance with credentials, configuration, and session settings.

```APIDOC
## VkApi.__init__

### Description
Initializes a new instance of the VkApi client. This sets up the session, authentication handlers, and configuration storage.

### Parameters
- **login** (str) - Optional - VK login (phone number recommended).
- **password** (str) - Optional - VK password.
- **token** (str) - Optional - Access token.
- **auth_handler** (callable) - Optional - Function for two-factor authentication.
- **captcha_handler** (callable) - Optional - Function for captcha handling.
- **api_version** (str) - Optional - API version (default: '5.92').
- **app_id** (int) - Optional - Standalone application ID.
- **scope** (int or str) - Optional - Requested permissions.
- **session** (requests.Session) - Optional - Custom requests session.
```

--------------------------------

### Initialize VkUpload

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/upload.html

The constructor requires a VkApi or VkApiMethod instance to handle authentication and API requests.

```python
def __init__(self, vk):

        if not isinstance(vk, (VkApi, VkApiMethod)):
            raise TypeError(
                'The arg should be VkApi or VkApiMethod instance'
            )

        self.vk = vk if isinstance(vk, VkApiMethod) else vk.get_api()
        self.http = requests.Session()
        self.http.headers.pop('user-agent')
```

--------------------------------

### Initialize VkApi Module

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/vk_api.html

Initializes the core module components, including regex patterns for login parsing and default configuration settings.

```python
# -*- coding: utf-8 -*-
"""
:authors: python273
:license: Apache License, Version 2.0, see LICENSE file

:copyright: (c) 2019 python273
"""

import json
import logging
import random
import re
import threading
import time
import urllib.parse
from hashlib import md5

import requests

import jconfig
from .enums import VkUserPermissions
from .exceptions import *
from .utils import (
    code_from_number, search_re, clear_string,
    cookies_to_list, set_cookies_from_list
)

RE_LOGIN_TO = re.compile(r'"to":"(.*?)"')
RE_LOGIN_IP_H = re.compile(r'name="ip_h" value="([a-z0-9]+)"')
RE_LOGIN_LG_H = re.compile(r'name="lg_h" value="([a-z0-9]+)"')
RE_LOGIN_LG_DOMAIN_H = re.compile(r'name="lg_domain_h" value="([a-z0-9]+)"')

RE_CAPTCHAID = re.compile(r"onLoginCaptcha\('(\d+)'")
RE_NUMBER_HASH = re.compile(r"al_page: '3', hash: '([a-z0-9]+)'")
RE_AUTH_HASH = re.compile(r"Authcheck\.init\('([a-z_0-9]+)'")
RE_TOKEN_URL = re.compile(r'location\.href = "(.*?)"\+addr;')
RE_AUTH_TOKEN_URL = re.compile(r'window\.init = ({.*?});')

RE_PHONE_PREFIX = re.compile(r'label ta_r">\+(.*?)<')
RE_PHONE_POSTFIX = re.compile(r'phone_postfix">.*?(\d+).*?<')

DEFAULT_USERAGENT = 'Mozilla/5.0 (Windows NT 10.0; rv:109.0) Gecko/20100101 Firefox/115.0'

DEFAULT_USER_SCOPE = sum(VkUserPermissions)


def get_unknown_exc_str(s):
    return (
        f'Unknown error ({s}). Please send a bugreport to GitHub: '
        'https://github.com/python273/vk_api/issues'
    )
```

--------------------------------

### Initialize VkKeyboard Class

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/keyboard.html

Constructor for the VkKeyboard class, used to define whether the keyboard is one-time or inline.

```python
def __init__(self, one_time=False, inline=False):
    self.one_time = one_time
    self.inline = inline
    self.lines = [[]]

    self.keyboard = {
        'one_time': self.one_time,
        'inline': self.inline,
        'buttons': self.lines
    }
```

--------------------------------

### VkAudio Class Implementation

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/audio.html

The VkAudio class initializes with a VkApi object and sets up necessary cookies to mimic a browser session for audio retrieval.

```python
class VkAudio(object):
    """ Модуль для получения аудиозаписей без использования официального API.

    :param vk: Объект :class:`VkApi`
    """

    __slots__ = ('_vk', 'user_id', 'convert_m3u8_links')

    DEFAULT_COOKIES = [
        {  # если не установлено, то первый запрос ломается
            'version': 0,
            'name': 'remixaudio_show_alert_today',
            'value': '0',
            'port': None,
            'port_specified': False,
            'domain': '.vk.com',
            'domain_specified': True,
            'domain_initial_dot': True,
            'path': '/',
            'path_specified': True,
            'secure': True,
            'expires': None,
            'discard': False,
            'comment': None,
            'comment_url': None,
            'rfc2109': False,
            'rest': {}
        }, {  # для аудио из постов
            'version': 0,
            'name': 'remixmdevice',
            'value': '1920/1080/2/!!-!!!!',
            'port': None,
            'port_specified': False,
            'domain': '.vk.com',
            'domain_specified': True,
            'domain_initial_dot': True,
            'path': '/',
            'path_specified': True,
            'secure': True,
            'expires': None,
            'discard': False,
            'comment': None,
            'comment_url': None,
            'rfc2109': False,
            'rest': {}
        }
    ]

    def __init__(self, vk, convert_m3u8_links=True):
        self.user_id = vk.method('users.get')[0]['id']
        self._vk = vk
        self.convert_m3u8_links = convert_m3u8_links

        set_cookies_from_list(self._vk.http.cookies, self.DEFAULT_COOKIES)

        self._vk.http.get('https://m.vk.com/')  # load cookies
```

--------------------------------

### POST /method

Source: https://vk-api.readthedocs.io/en/latest/vk_api.html

Executes a specific VK API method.

```APIDOC
## POST /method

### Description
Calls a specific VK API method with provided parameters.

### Parameters
- **method** (str) - Required - Name of the API method.
- **values** (dict) - Optional - Parameters for the method.
- **captcha_sid** (str) - Optional - ID of the captcha.
- **captcha_key** (str) - Optional - Answer to the captcha.
- **raw** (bool) - Optional - If True, returns the full response object.
```

--------------------------------

### VkKeyboard Methods

Source: https://vk-api.readthedocs.io/en/latest/keyboard.html

Methods for manipulating and generating VkKeyboard objects.

```APIDOC
## VkKeyboard Methods

### get_keyboard()

#### Description
Get the JSON representation of the keyboard.

### get_empty_keyboard()

#### Description
Get the JSON for an empty keyboard. Sending an empty keyboard will remove the user's current keyboard.

### add_button(label, color, payload)

#### Description
Add a button with text. Maximum number of buttons per row: MAX_BUTTONS_ON_LINE.

#### Parameters
- **label** (str) - Required - The text on the button and the text sent when it is pressed.
- **color** (VkKeyboardColor or str) - Optional - The color of the button. Defaults to VkKeyboardColor.SECONDARY.
- **payload** (str or list or dict) - Optional - Parameter for callback API.

### add_callback_button(label, color, payload)

#### Description
Add a callback button with text. Maximum number of buttons per row: MAX_BUTTONS_ON_LINE.

#### Parameters
- **label** (str) - Required - The text on the button and the text sent when it is pressed.
- **color** (VkKeyboardColor or str) - Optional - The color of the button. Defaults to VkKeyboardColor.SECONDARY.
- **payload** (str or list or dict) - Optional - Parameter for callback API.

### add_location_button(payload)

#### Description
Add a button with location. Always occupies the full width of the row.

#### Parameters
- **payload** (str or list or dict) - Optional - Parameter for callback API.

### add_vkpay_button(hash, payload)

#### Description
Add a button for payment using VKPay. Always occupies the full width of the row.

#### Parameters
- **hash** (str) - Required - VKPay payment parameters and application ID (in the 'aid' field) separated by '&'.
- **payload** (str or list or dict) - Optional - Parameter for compatibility with older clients.

### add_vkapps_button(app_id, owner_id, label, hash, payload)

#### Description
Add a button for a VK Apps application. Always occupies the full width of the row.

#### Parameters
- **app_id** (int) - Required - The ID of the VK Apps application to launch.
- **owner_id** (int) - Required - The ID of the community where the application is installed, if it needs to be opened in the community context.
- **label** (str) - Required - The name of the application displayed on the button.
- **hash** (str) - Required - The hash for navigation within the application, will be passed in the launch parameters string after the '#' symbol.
- **payload** (str or list or dict) - Optional - Parameter for compatibility with older clients.

### add_openlink_button(label, link, payload)

#### Description
Add a button with a link. Maximum number of buttons per row: MAX_BUTTONS_ON_LINE.

#### Parameters
- **label** (str) - Required - The text on the button.
- **link** (str) - Required - The URL to open when the button is pressed.
- **payload** (str or list or dict) - Optional - Parameter for callback API.

### add_line()

#### Description
Creates a new row for placing buttons. Maximum number of rows: MAX_DEFAULT_LINES (standard display), MAX_INLINE_LINES (inline display).
```

--------------------------------

### VkAudio Methods

Source: https://vk-api.readthedocs.io/en/latest/audio.html

Methods for interacting with VK audio content including retrieval, searching, and management.

```APIDOC
## VkAudio.get

### Description
Retrieve a list of audio recordings for a user or group.

### Parameters
#### Query Parameters
- **owner_id** (int) - Optional - ID of the owner (negative values for groups)
- **album_id** (int) - Optional - ID of the album
- **access_hash** (str) - Optional - ACCESS_HASH of the album

## VkAudio.edit_audio

### Description
Edit an existing audio recording.

### Parameters
#### Request Body
- **audio_id** (int) - Required - ID of the audio recording
- **owner_id** (int) - Required - ID of the owner
- **hash** (str) - Required - Hash for editing the audio
- **performer** (str) - Required - Name of the performer
- **title** (str) - Required - Title of the audio
- **text** (str) - Optional - Text of the audio
- **genre** (int) - Optional - Genre ID (default 1001)

## VkAudio.upload_audio

### Description
Upload an audio recording.

### Parameters
#### Request Body
- **audio** (str) - Required - Path or identifier of the audio file
- **group_id** (int) - Optional - ID of the group (0 for user)

## VkAudio.search

### Description
Search for audio recordings.

### Parameters
#### Query Parameters
- **q** (str) - Required - Search query
- **count** (int) - Optional - Number of results (default 100)
- **offset** (int) - Optional - Offset for pagination
```

--------------------------------

### VkKeyboard API

Source: https://vk-api.readthedocs.io/en/latest/keyboard.html

Methods and classes for constructing custom keyboards for VK bot interactions.

```APIDOC
## VkKeyboard

### Description
Provides methods to construct and manage custom keyboards for VK bot messages.

### Methods
- **get_keyboard()**: Returns the constructed keyboard object.
- **get_empty_keyboard()**: Returns an empty keyboard object.
- **add_button()**: Adds a standard text button.
- **add_callback_button()**: Adds a callback button.
- **add_location_button()**: Adds a location request button.
- **add_vkpay_button()**: Adds a VK Pay button.
- **add_vkapps_button()**: Adds a VK Apps button.
- **add_openlink_button()**: Adds a button to open a link.
- **add_line()**: Adds a new line to the keyboard layout.
```

--------------------------------

### method(method, values=None, captcha_sid=None, captcha_key=None, raw=False)

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/vk_api.html

Executes a specific VK API method.

```APIDOC
## method(method, values=None, captcha_sid=None, captcha_key=None, raw=False)

### Description
Calls a VK API method with the provided parameters.

### Parameters
- **method** (str) - The name of the API method to call.
- **values** (dict) - Optional parameters for the API method.
- **captcha_sid** (int/str) - Optional captcha ID.
- **captcha_key** (str) - Optional captcha answer.
- **raw** (bool) - If False, returns the 'response' field; if True, returns the full response object.

### Response
- **response** (dict) - The result of the API call.
```

--------------------------------

### Fetch audio from post

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/audio.html

Retrieves a list of audio tracks attached to a specific user or group post.

```python
    def get_post_audio(self, owner_id, post_id):
        """ Получить список аудиозаписей из поста пользователя или группы

        :param owner_id: ID владельца (отрицательные значения для групп)
        :param post_id: ID поста
        """
        response = self._vk.http.get(f'https://m.vk.com/wall{owner_id}_{post_id}')

        ids = scrap_ids_from_html(
            response.text,
            filter_root_el={'class': 'audios_list'}
        )

        return scrap_tracks(
            ids,
            self.user_id,
            http=self._vk.http,
            convert_m3u8_links=self.convert_m3u8_links,
        )
```

--------------------------------

### Upload Audio

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/upload.html

Uploads an audio file to VK.

```python
    def audio(self, audio, artist, title):
        """ Загрузка аудио

        :param audio: путь к аудиофайлу или file-like объект
        :param artist: исполнитель
        :param title: название
        """

        url = self.vk.audio.getUploadServer()['upload_url']

        with FilesOpener(audio, key_format='file') as f:
            response = self.http.post(url, files=f).json()

        response.update({
            'artist': artist,
            'title': title
        })

        return self.vk.audio.save(**response)
```

--------------------------------

### search(q, count=100, offset=0)

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/audio.html

Searches for audio tracks globally.

```APIDOC
## search(q, count=100, offset=0)

### Description
Searches for audio tracks globally.

### Parameters
- **q** (str) - Required - The search query string.
- **count** (int) - Optional - Number of results to return.
- **offset** (int) - Optional - Offset for pagination.
```

--------------------------------

### VkApi Initialization

Source: https://vk-api.readthedocs.io/en/latest/vk_api.html

Initializes the main VkApi class for interacting with the VK API.

```APIDOC
## VkApi Initialization

### Description
Initializes the VkApi client with credentials, configuration, and session settings.

### Parameters
- **login** (str) - Optional - VK login (phone number recommended).
- **password** (str) - Optional - VK password.
- **token** (str) - Optional - Access token.
- **api_version** (str) - Optional - API version (default: '5.92').
- **app_id** (int) - Optional - Standalone app ID (default: 6222115).
- **scope** (int/str) - Optional - Requested permissions.
- **session** (requests.Session) - Optional - Custom requests session.
```

--------------------------------

### Full Data Retrieval with get_all

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/tools.html

Loads all items into memory. Use only when necessary; prefer get_all_iter for processing items in chunks.

```python
def get_all(self, method, max_count, values=None, key='items', limit=None,
            stop_fn=None, negative_offset=False):
    """ Использовать только если нужно загрузить все объекты в память.

    Eсли вы можете обрабатывать объекты по частям, то лучше
    использовать get_all_iter

    Например если вы записываете объекты в БД, то нет смысла загружать
    все данные в память
    """

    items = list(
        self.get_all_iter(
            method, max_count, values, key, limit, stop_fn, negative_offset
        )
    )

    return {'count': len(items), key: items}
```

--------------------------------

### VkFunction Class

Source: https://vk-api.readthedocs.io/en/latest/execute.html

Documentation for initializing and calling the VkFunction wrapper for VKScript execution.

```APIDOC
## VkFunction

### Description
A wrapper class for the VK execute method, enabling the execution of VKScript code.

### Parameters
- **code** (string) - Required - The VKScript code to be executed.
- **args** (list) - Optional - A list of arguments to be converted into JSON.
- **clean_args** (list) - Optional - A list of raw arguments to be inserted as strings.
- **return_raw** (boolean) - Optional - Argument for the raw function of VkApi.method.

## VkFunction.__call__

### Description
Executes the defined VKScript using the provided VkApi instance.

### Parameters
- **vk** (VkApi/VkApiMethod) - Required - The VkApi or VkApiMethod instance.
- ***args** - Optional - Positional arguments.
- ***kwargs** - Optional - Keyword arguments.
```

--------------------------------

### Iterate over user albums

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/audio.html

Fetches audio albums for a specific user or group by iterating through pages.

```python
while True:
    response = self._vk.http.get(
        f'https://m.vk.com/audio?act=audio_playlists{owner_id}',
        params={'offset': offset},
        allow_redirects=False,
    )

    if not response.text:
        raise AccessDenied(
            f"You don\'t have permissions to browse {owner_id}\'s albums"
        )

    albums = scrap_albums(response.text)

    if not albums:
        break

    yield from albums
    offset += ALBUMS_PER_USER_PAGE
```

--------------------------------

### listen()

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/longpoll.html

Continuously listens for events from the Long Poll server.

```APIDOC
## listen()

### Description
Starts an infinite loop that continuously polls the server for new events using the check() method.

### Yields
- **Event** - Yields individual Event objects as they are received from the server.
```

--------------------------------

### VkAudio API Methods

Source: https://vk-api.readthedocs.io/en/latest/index.html

Methods for interacting with VK Audio, including searching, retrieving, and editing audio tracks.

```APIDOC
## VkAudio Methods

### Description
Provides access to audio-related functionality within the VK API.

### Methods
- **get_iter()**: Returns an iterator for audio tracks.
- **get()**: Retrieves audio tracks.
- **get_albums_iter()**: Returns an iterator for audio albums.
- **get_albums()**: Retrieves audio albums.
- **search_user()**: Searches for audio by user.
- **edit_audio()**: Edits an existing audio track.
- **upload_audio()**: Uploads a new audio track.
- **search()**: Searches for audio tracks.
- **search_iter()**: Returns an iterator for audio search results.
- **get_updates_iter()**: Returns an iterator for audio updates.
- **get_popular_iter()**: Returns an iterator for popular audio tracks.
- **get_news_iter()**: Returns an iterator for audio news.
- **get_audio_by_id()**: Retrieves audio by specific ID.
- **get_post_audio()**: Retrieves audio attached to a post.
```

--------------------------------

### Upload Video Method

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/upload.html

Uploads a video file or embeds a link to a video. Requires either a video_file path/object or a link.

```python
def video(self, video_file=None, link=None, name=None, description=None,
          is_private=None, wallpost=None, group_id=None,
          album_id=None, privacy_view=None, privacy_comment=None,
          no_comments=None, repeat=None):
    """ Загрузка видео

    :param video_file: путь к видеофайлу или file-like объект.
    :type video_file: object or str

    :param link: url для встраивания видео с внешнего сайта,
        например, с Youtube.
    :type link: str

    :param name: название видеофайла
    :type name: str

    :param description: описание видеофайла
    :type description: str

    :param is_private: указывается 1, если видео загружается для отправки
        личным сообщением. После загрузки с этим параметром видеозапись
        не будет отображаться в списке видеозаписей пользователя и не будет
        доступна другим пользователям по ее идентификатору.
    :type is_private: bool

    :param wallpost: требуется ли после сохранения опубликовать
        запись с видео на стене.
    :type wallpost: bool

    :param group_id: идентификатор сообщества, в которое будет сохранен
        видеофайл. По умолчанию файл сохраняется на страницу текущего
        пользователя.
    :type group_id: int

    :param album_id: идентификатор альбома, в который будет загружен
        видеофайл.
    :type album_id: int

    :param privacy_view: настройки приватности просмотра видеозаписи в
        специальном формате. (https://vk.com/dev/objects/privacy)
        Приватность доступна для видеозаписей, которые пользователь
        загрузил в профиль. (список слов, разделенных через запятую)
    :param privacy_comment: настройки приватности комментирования
        видеозаписи в специальном формате.
        (https://vk.com/dev/objects/privacy)

    :param no_comments: 1 — закрыть комментарии (для видео из сообществ).
    :type no_comments: bool

    :param repeat: зацикливание воспроизведения видеозаписи. Флаг.
    :type repeat: bool
    """

    if not link and not video_file:
        raise ValueError('Either link or video_file param is required')

    if link and video_file:
        raise ValueError('Both params link and video_file aren\'t allowed')

    values = {
        'name': name,
        'description': description,
        'is_private': is_private,
        'wallpost': wallpost,
        'link': link,
        'group_id': group_id,
        'album_id': album_id,
        'privacy_view': privacy_view,
        'privacy_comment': privacy_comment,
        'no_comments': no_comments,
        'repeat': repeat
    }

    response = self.vk.video.save(**values)
    url = response.pop('upload_url')

    with FilesOpener(video_file or [], 'video_file') as f:
        response.update(self.http.post(
            url,
            files=f or None
        ).json())
        return response
```

--------------------------------

### Authentication Methods

Source: https://vk-api.readthedocs.io/en/latest/vk_api.html

Methods for handling user and server authentication.

```APIDOC
## Authentication Methods

### auth(reauth=False, token_only=False)
Performs authentication. `reauth` ignores saved cookies/tokens. `token_only` optimizes for access_token retrieval.

### check_sid()
Checks the validity of the remixsid cookie.

### server_auth()
Performs server-side authorization.

### code_auth(code, redirect_url)
Retrieves an access_token using an authorization code.
```

--------------------------------

### VkTools.get_all

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/tools.html

Retrieves all elements from a VK API method and returns them as a single list. Use this only if you need to load all objects into memory.

```APIDOC
## VkTools.get_all

### Description
Retrieves all elements from a VK API method and returns them as a single list. Use this only if you need to load all objects into memory.

### Parameters
- **method** (str) - Required - The name of the VK API method to call.
- **max_count** (int) - Required - Maximum number of elements to retrieve per request.
- **values** (dict) - Optional - Parameters for the API method.
- **key** (str) - Optional - The key in the response containing the items (default: 'items').
- **limit** (int) - Optional - Limit on the number of elements to retrieve.
- **stop_fn** (func) - Optional - A function that determines when to stop the iteration.
- **negative_offset** (bool) - Optional - Set to True if the offset should be negative.
```

--------------------------------

### Upload Market Album Photo

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/upload.html

Uploads a photo for a market product collection.

```python
    def photo_market_album(self, photo, group_id):
        """ Загрузка фотографии для подборки товаров

        :param photo: путь к изображению(ям) или file-like объект(ы)
        :type photo: str or list

        :param group_id: идентификатор сообщества, для которого необходимо загрузить фотографию для подборки товаров
        :type group_id: int
        """

        if group_id < 0:
            group_id = abs(group_id)

        values = {
            'group_id': group_id,
        }

        response = self.vk.photos.getMarketAlbumUploadServer(**values)
        url = response['upload_url']

        with FilesOpener(photo) as photos_files:
            response = self.http.post(url, files=photos_files)

        values.update(response.json())

        return self.vk.photos.saveMarketAlbumPhoto(**values)
```

--------------------------------

### Upload Audio

Source: https://vk-api.readthedocs.io/en/latest/upload.html

Uploads an audio file to VK.

```APIDOC
## POST /upload/audio

### Description
Uploads an audio file to VK.

### Method
POST

### Endpoint
/upload/audio

### Parameters
#### Path Parameters
- None

#### Query Parameters
- **artist** (str) - Required - The artist of the audio file.
- **title** (str) - Required - The title of the audio file.

#### Request Body
- **audio** (str) - Required - Path to the audio file or a file-like object.

### Request Example
```json
{
  "audio": "/path/to/song.mp3",
  "artist": "Example Artist",
  "title": "Example Song"
}
```

### Response
#### Success Response (200)
- **response** (object) - Contains information about the uploaded audio file.

#### Response Example
```json
{
  "response": {
    "audio_hash": "abcdef1234567890",
    "audio_id": 444444444
  }
}
```
```

--------------------------------

### Perform Server-Side Authentication

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/vk_api.html

Executes client credentials flow to obtain an access token.

```python
def server_auth(self):
    """ Серверная авторизация """
    values = {
        'client_id': self.app_id,
        'client_secret': self.client_secret,
        'v': self.api_version,
        'grant_type': 'client_credentials'
    }

    response = self.http.post(
        'https://oauth.vk.com/access_token', values
    ).json()

    if 'error' in response:
        raise AuthError(response['error_description'])
    else:
        self.token = response
```

--------------------------------

### FilesOpener Class Implementation

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/upload.html

The FilesOpener class manages file opening and closing via the context manager protocol, supporting both file paths and file-like objects.

```python
class FilesOpener(object):
    def __init__(self, paths, key_format='file{}'):
        if not isinstance(paths, list):
            paths = [paths]

        self.paths = paths
        self.key_format = key_format
        self.opened_files = []

    def __enter__(self):
        return self.open_files()

    def __exit__(self, type, value, traceback):
        self.close_files()

    def open_files(self):
        self.close_files()

        files = []

        for x, file in enumerate(self.paths):
            if hasattr(file, 'read'):
                f = file

                filename = file.name if hasattr(file, 'name') else '.jpg'
            else:
                filename = file
                f = open(filename, 'rb')
                self.opened_files.append(f)

            ext = filename.split('.')[-1]
            files.append((self.key_format.format(x), (f'file{x}.{ext}', f)))

        return files

    def close_files(self):
        for f in self.opened_files:
            f.close()

        self.opened_files = []
```

--------------------------------

### Core API Modules

Source: https://vk-api.readthedocs.io/en/latest/keyboard.html

Overview of the primary classes used for interacting with the VK API.

```APIDOC
## Core Modules

### Description
Essential classes for interacting with the VK platform.

### Classes
- **VkApi**: The main class for API interaction.
- **VkUpload**: Handles file uploads to VK servers.
- **VkTools**: Utility functions for API operations.
- **VkLongPoll**: Module for standard long polling.
- **VkBotLongPoll**: Module for bot-specific long polling.
```

--------------------------------

### get_all Method

Source: https://vk-api.readthedocs.io/en/latest/tools.html

Retrieves all elements and loads them into memory. Use this only if you need all objects in memory. For processing objects in parts, prefer `get_all_iter`.

```APIDOC
## Method get_all

### Description
Use only if you need to load all objects into memory. If you can process objects in parts, it is better to use `get_all_iter`. For example, if you are writing objects to a database, there is no point in loading all the data into memory.

### Parameters
- **method** (str) - The name of the method.
- **max_count** (int) - The maximum number of elements that can be obtained per request.
- **values** (dict) - Parameters for the API call.
- **key** (str) - The key for the elements to retrieve (default: 'items').
- **limit** (int) - A limit on the number of elements to retrieve, though more may be returned.
- **stop_fn** (func) - A function that determines when to stop the iteration.
- **negative_offset** (bool) - If True, the offset should be negative (default: False).
```

--------------------------------

### Using FilesOpener for HTTP Uploads

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/upload.html

Utilize the FilesOpener context manager to handle file streams during a POST request.

```python
with FilesOpener(file, key_format='file') as files:
    return self.http.post(url, files=files)
```

--------------------------------

### document(doc, title=None, tags=None, group_id=None, to_wall=False, message_peer_id=None, doc_type=None)

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/upload.html

Uploads a document to VK.

```APIDOC
## document

### Description
Uploads a document to VK. Supports uploading to walls, messages, or general storage.

### Parameters
- **doc** (object or str) - Required - Path to the document or a file-like object.
- **title** (str) - Optional - Title of the document.
- **tags** (str) - Optional - Tags for searching.
- **group_id** (int) - Optional - ID of the community.
- **to_wall** (bool) - Optional - Whether to upload to the wall.
- **message_peer_id** (int) - Optional - Peer ID for message uploads.
- **doc_type** (str) - Optional - Type of the document.
```

--------------------------------

### POST /document

Source: https://vk-api.readthedocs.io/en/latest/upload.html

Uploads a document to VK.

```APIDOC
## POST /document

### Description
Uploads a document to the VK platform.

### Parameters
#### Request Body
- **doc** (file/path) - Required - Path to the document or file-like object
- **title** (string) - Optional - Title of the document
- **tags** (string) - Optional - Tags for search
- **group_id** (int) - Optional - Community ID if uploading to a group
```

--------------------------------

### Execute API Method

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/vk_api.html

Sends a request to the VK API with automatic rate limiting and token injection.

```python
def method(self, method, values=None, captcha_sid=None, captcha_key=None,
           raw=False):
    """ Вызов метода API

    :param method: название метода
    :type method: str

    :param values: параметры
    :type values: dict

    :param captcha_sid: id капчи
    :type captcha_key: int or str

    :param captcha_key: ответ капчи
    :type captcha_key: str

    :param raw: при False возвращает `response['response']`
                при True возвращает `response`
                (может понадобиться для метода execute для получения
                execute_errors)
    :type raw: bool
    """

    values = values.copy() if values else {}

    if 'v' not in values:
        values['v'] = self.api_version

    if self.token:
        values['access_token'] = self.token['access_token']

    if captcha_sid and captcha_key:
        values['captcha_sid'] = captcha_sid
        values['captcha_key'] = captcha_key

    with self.lock:
        # Ограничение 3 запроса в секунду
        delay = self.RPS_DELAY - (time.time() - self.last_request)

        if delay > 0:
            time.sleep(delay)

        response = self.http.post(
            f'https://api.vk.com/method/{method}',
            values,
            headers={'Cookie': ''},
        )
        self.last_request = time.time()

    if response.ok:
        response = response.json()
    else:
        error = ApiHttpError(self, method, values, raw, response)
        response = self.http_handler(error)

        if response is not None:
            return response

        raise error

    if 'error' in response:
        error = ApiError(self, method, values, raw, response['error'])
```

--------------------------------

### Retrieve news audio iterator

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/audio.html

Fetches new audio tracks and iterates through them with pagination support.

```python
    def get_news_iter(self, offset=0):
        """ Искать популярные аудиозаписи  (генератор)

        :param offset: смещение
        """

        offset_left = 0

        response = self._vk.http.post(
            'https://vk.com/audio',
            data={
                'block': 'new_songs',
                'section': 'recoms'
            }
        )
        json_response = json.loads(scrap_json(response.text))

        ids = scrap_ids(
            json_response['sectionData']['recoms']['playlist']['list']
        )

        if offset_left + len(ids) >= offset:
            yield from scrap_tracks(
                ids if offset_left >= offset else ids[offset - offset_left :],
                self.user_id,
                convert_m3u8_links=self.convert_m3u8_links,
                http=self._vk.http,
            )
        offset_left += len(ids)

        while True:
            response = self._vk.http.post(
                'https://vk.com/al_audio.php',
                data={
                    'al': 1,
                    'act': 'load_catalog_section',
                    'section_id': json_response['sectionData']['recoms']['sectionId'],
                    'start_from': json_response['sectionData']['recoms']['nextFrom']
                }
            )
```

--------------------------------

### POST /story

Source: https://vk-api.readthedocs.io/en/latest/upload.html

Uploads a story to VK.

```APIDOC
## POST /story

### Description
Uploads a story to VK.

### Parameters
#### Request Body
- **file** (file/path) - Required - Path to the image, gif, or video file
- **file_type** (string) - Required - Type of story (photo or video)
- **add_to_news** (bool) - Optional - Whether to post to news
- **user_ids** (list) - Optional - User IDs who can see the story
- **reply_to_story** (int) - Optional - ID of the story being replied to
- **link_text** (string) - Optional - Text for the link
- **link_url** (string) - Optional - URL for the link
- **group_id** (int) - Optional - Community ID
```

--------------------------------

### BaseConfig Class

Source: https://vk-api.readthedocs.io/en/latest/jconfig.html

Abstract base class for configuration management. Inheriting classes must define __slots__ and implement load and save methods.

```APIDOC
## BaseConfig

### Description
Abstract base class for configuration. Inheriting classes must define __slots__.

### Parameters
- **section** (string) - Required - Name of the configuration subcategory.
- **kwargs** (dict) - Optional - Arguments passed to the load() method.

### Methods
- **load(**kwargs)**: Abstract method, must return a dict with the configuration.
- **save()**: Abstract method, must save the configuration.
```

--------------------------------

### POST /photo_cover

Source: https://vk-api.readthedocs.io/en/latest/upload.html

Uploads a profile cover image.

```APIDOC
## POST /photo_cover

### Description
Uploads a profile cover image.

### Parameters
#### Request Body
- **photo** (file/path) - Required - Path to the image or file-like object
- **group_id** (int) - Required - Community ID
- **crop_x** (int) - Optional - X coordinate for top-left corner
- **crop_y** (int) - Optional - Y coordinate for top-left corner
- **crop_x2** (int) - Optional - X coordinate for bottom-right corner
- **crop_y2** (int) - Optional - Y coordinate for bottom-right corner
```

--------------------------------

### Upload audio file

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/audio.html

Uploads an audio file to a user or group profile.

```python
def upload_audio(self, audio: str, group_id: int = 0):
    """ Загрузка аудиозаписи

    :param group_id: ID группы, для юзера - 0
    """
    response = self._vk.http.post(
        'https://vk.com/al_audio.php',
        data={
            'al': 1,
            'act': 'new_audio',
            'boxhash': base36encode(),
            'gid': group_id
        }
    )
    url = re.search("(https?:[^']*)", json.loads(response.text.replace('<!--', ''))["payload"][1][2]).group(0)
    with FilesOpener(audio, key_format='file') as f:
        uploader_response = self._vk.http.post(url, files=f).json()
    response = self._vk.http.post(
        'https://vk.com/al_audio.php',
        data={
            'al': 1,
            'act': 'done_add',
            'go_uploader_response': json.dumps(uploader_response),
            'upldr': 1
        }
    )
    return json.loads(response.text.replace('<!--', ''))["payload"][1][0]
```

--------------------------------

### Upload Document Method

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/upload.html

Uploads a document file to VK. Supports wall, message, or standard document upload servers.

```python
def document(self, doc, title=None, tags=None, group_id=None,
             to_wall=False, message_peer_id=None, doc_type=None):
    """ Загрузка документа

    :param doc: путь к документу или file-like объект
    :param title: название документа
    :param tags: метки для поиска
    :param group_id: идентификатор сообщества (если загрузка идет в группу)
    """

    values = {
        'group_id': group_id,
        'peer_id': message_peer_id,
        'type': doc_type
    }

    if to_wall:
        method = self.vk.docs.getWallUploadServer
    elif message_peer_id:
        method = self.vk.docs.getMessagesUploadServer
    else:
        method = self.vk.docs.getUploadServer

    url = method(**values)['upload_url']

    with FilesOpener(doc, 'file') as files:
        response = self.http.post(url, files=files).json()

    response.update({
        'title': title,
        'tags': tags
    })

    return self.vk.docs.save(**response)
```

--------------------------------

### Upload Market Photo

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/upload.html

Uploads images for products in the VK market.

```python
    def photo_market(self, photo, group_id, main_photo=False,
                     crop_x=None, crop_y=None, crop_width=None):
        """ Загрузка изображений для товаров в магазине

        :param photo: путь к изображению(ям) или file-like объект(ы)
        :type photo: str or list

        :param group_id: идентификатор сообщества, для которого необходимо загрузить фотографию товара
        :type group_id: int
        :param main_photo: является ли фотография обложкой товара
        :type main_photo: bool
        :param crop_x: координата x для обрезки фотографии (верхний правый угол)
        :type crop_x: int
        :param crop_y: координата y для обрезки фотографии (верхний правый угол)
        :type crop_y: int
        :param crop_width: ширина фотографии после обрезки в px
        :type crop_width: int
        """

        if group_id < 0:
            group_id = abs(group_id)

        values = {
            'main_photo': main_photo,
            'group_id': group_id,
        }

        if crop_x is not None:
            values['crop_x'] = crop_x
        if crop_y is not None:
            values['crop_y'] = crop_y
        if crop_width is not None:
            values['crop_width'] = crop_width

        response = self.vk.photos.getMarketUploadServer(**values)
        url = response['upload_url']

        with FilesOpener(photo) as photos_files:
            response = self.http.post(url, files=photos_files)

        values.update(response.json())

        return self.vk.photos.saveMarketPhoto(**values)
```

--------------------------------

### VkKeyboard Class

Source: https://vk-api.readthedocs.io/en/latest/keyboard.html

The VkKeyboard class is used to create keyboards for VK bots. It supports one-time keyboards and inline keyboards.

```APIDOC
## Class VkKeyboard

### Description
Class for creating a keyboard for a bot.

### Parameters
- **one_time** (bool) - Optional - If True, the keyboard will disappear after a button is pressed.
- **inline** (bool) - Optional - If True, the keyboard will be an inline keyboard.
```

--------------------------------

### add_line()

Source: https://vk-api.readthedocs.io/en/latest/_modules/vk_api/keyboard.html

Creates a new line for placing buttons.

```APIDOC
## add_line()

### Description
Creates a new line where buttons can be placed. The maximum number of lines is determined by MAX_DEFAULT_LINES for standard keyboards or MAX_INLINE_LINES for inline keyboards.
```
Tokens:
Raw