PyVK¶
PyVK is a Python client to VK API. It can be used in server or client applications, scripts, or interactively for data retrieval and analysis, social media integration, automation, and fun.
Features¶
Authorisation: PyVK assists both client- and server-side authorisation. It ensures that your password is not stored anywhere in plain-text. It also supports 2FA and captcha/mobile phone login confirmation.
Error handling: PyVK wraps API errors into exceptions and can recover from certain kinds of those, such as expired autorisation, temporal ban, or captcha request.
Pagination: PyVK can join paginated API responses into a single result.
Media upload: PyVK wraps it into a single method call and makes it easy to use those files as attachments in other API calls.
Python 2 and 3 : PyVK is tested for CPython 2.7 and 3.5-3.8
Example¶
>>> from pyvk import ClientAuth
>>> auth = ClientAuth(app_id=<...>, username=<...>)
>>> auth.auth()
Password: <...>
>>> api = auth.api(version='5.21', lang='en')
>>> # Call API methods
>>> api.users.get(user_ids=[210700286], fields=['bdate'])
[{'id': 210700286,
'first_name': 'Lindsey',
'last_name': 'Stirling',
'bdate': '21.9.1986'}]
Usage¶
VK API is accessible via API
object.
There are three ways to get one:
From an auth object. This is particulary handy for client applications:
>>> auth = ClientAuth(app_id=<...>, username=<...>) >>> auth.auth() Password: <...> >>> api = auth.api()
Keyword parameters given to
api()
will be passed to theAPI
constructor. Global parameters will be inherited from the auth object (if not shadowed).In server applications an auth object may not be around when it feels like an API call. In this case one can store an access token persistently and then use it create an
API
object manually:>>> auth = ServerAuth(<...>) >>> auth.auth(code=<...>, client_secret=<...>) >>> db['token'] = auth.token >>> # Elsewhere, elsewhen: >>> from pyvk import API >>> api = API(token=db['token'])
While it is not really common in practice, one can use a handful of API methods without an access token at all:
>>> api = API() >>> api.users.getFollowers(user_id=1, count=1) {'count': 5985409, 'items': [354451485]}
- class pyvk.API([token][, **parameters])
- Parameters:
token (str) – authorisation token. If None, only a small part of VK API methods is available.)
If you have obtained an API token elsewhere, you can use it directly:
>>> from pyvk import API
>>> api = API(token=<...>)
API Calls¶
Let’s call a couple of VK API methods:
>>> api.users.get(user_ids=[210700286], fields=['bdate'])
[{'bdate': '21.9.1986',
'first_name': 'Lindsey',
'id': 210700286,
'last_name': 'Stirling'}]
Or, without fancy attribute-chaining:
>>> vk.call('account.getInfo')
{'2fa_required': 0,
'country': 'RU',
'https_required': 0,
'intro': 0,
'lang': 0,
'no_wall_replies': 0,
'own_posts_default': 0}
Note that pythonic integers and lists can be used where the official API documentation specifies numbers (including negative) and comma-separated lists.
Error Handling¶
VK API errors can be catched as exceptions:
>>> from pyvk.exceptions import APIError
>>> try:
... api.docs.get()
... except APIError as exc:
... print('Error %d: %s' % (exc.error_code, exc.error_msg))
Error 15: Access denied: no access to call this method
However, PyVK can handle some recoverable errors (“too many requests per second”, “captcha needed”, and the like) by its own:
>>> for i in range(1, 100000):
... api.users.get(user_ids=[i])
... print(i, end=' ')
... sys.stdout.flush()
1 2 3 4 5 6 7 8 9 10 11 12 13 14 <...> pyvk.request INFO: Too many requests per second. Wait 0.3 sec and retry.
<...> pyvk.request INFO: Too many requests per second. Wait 0.6 sec and retry.
<...> pyvk.request INFO: Too many requests per second. Wait 1.2 sec and retry.
15 16 17 18 19 20 <...>
If that is not what you want, just make your request handler a bit dumber:
>>> api = auth.api(auto_delay=False, validation=False)
Or pass raw=True
to work with JSON responses directly:
>>> api = auth.api(raw=True)
>>> api.docs.get()
{'error': {'error_code': 15, 'error_msg': 'Access denied: no access to call this method', <...>}}
Configuration¶
Access Rights¶
VK API requires an access control bitmask passed during authorisation.
PyVK provides bitmasks for individual access rights as package-level constants.
They can be combined by bitwise-or operator and passed
into ClientAuth
or ServerAuth
with scope argument:
>>> from pyvk import p_audio, p_offline
>>> auth = ClientAuth(app_id=<...>, username=<...>,
scope=p_audio | p_offline)
There are also predefined p_all
and p_basic
.
The latter is used by default in ClientAuth
and combines
access rights commonly used used in scripts and interactive sessions.
ServerAuth
defaults to p_offline
.
- pyvk.p_basic
Combines
p_friends
,p_photos
,p_audio
,p_video
,p_status
,p_messages
,p_wall
,p_groups
,p_offline
.
- pyvk.p_all
Combines all the access rights.
- pyvk.p_notify
User allowed to send notifications to they (for Flash/iFrame apps)
- pyvk.p_friends
Access to friends.
- pyvk.p_photos
Access to photos.
- pyvk.p_audio
Access to audio.
- pyvk.p_video
Access to video.
- pyvk.p_pages
Access to wiki pages.
- pyvk.p_leftmenu
Addition of link to the application in the left menu.
- pyvk.p_status
Access to user status.
- pyvk.p_notes
Access to notes.
- pyvk.p_messages
Access to advanced methods for messaging. Unavailable for server-side authorisation.
- pyvk.p_wall
Access to standard and advanced methods for the wall. Ignored for server-side authorisation.
- pyvk.p_ads
Access to advanced methods for Ads API.
- pyvk.p_offline
Access to API at any time (non-expiring access token).
- pyvk.p_docs
Access to docs.
- pyvk.p_groups
Access to user communities.
- pyvk.p_notifications
Access to notifications about answers to the user.
- pyvk.p_stats
Access to statistics of user groups and applications where they is an administrator.
- pyvk.p_email
Access to user email.
- pyvk.p_market
Access to market.
User Input¶
- class pyvk.Input
Interface for requesting input from user via stdin. One can subclass and override
ask()
in order to implement other ways of providing the input.- static ask(field, **kwargs)
Read certain type of input from stdin with a relevant prompt.
- Parameters:
field (str) – type of input
- Returns:
input string
- Raises:
ValueError if incorrect arguments are passed
Additional keyword arguments are needed in some cases.
Possible inputs:
ask('app_id')
ask('username')
ask('password')
ask('secret_code')
ask('phone', msg='...')
ask('captcha', img='<image URL>')
Options¶
The following are configuration options and their default value used by
ClientAuth
, ServerAuth
, and API
.
Global options apply to all the classes, the others are specific to
certain class.
One can customise them by passing corresponding keyword arguments
when constructing the objects in question, for example:
>>> auth = ClientAuth(app_id=<...>, username=<...>, timeout=20.05,
version='5.0', disable_cache=True)
>>> auth = ServerAuth(app_id=<...>, username=<...>,
log_file='/logs/auth.log',
scope=p_groups | p_notes)
>>> api = API(token=<...>, scope=p_docs, lang='ru', max_attempts=10)
Global¶
- class pyvk.config.GlobalConfig(**params)¶
- log_format = '%(asctime)s %(name)s %(levelname)s: %(message)s'¶
log messages format compatible with
logging
module
- log_file = None¶
optional log file. If not set, standard output is used
- input¶
static class for requesting user information during an interactive client session.
Input
or its subclassed are expected.alias of
Input
- timeout = 6.05¶
time for waiting for a network response
- version = '5.60'¶
VK API version. See version history for more information.
ClientAuth¶
ServerAuth¶
- class pyvk.config.ServerAuthConfig(**params)¶
- scope = 65536¶
bitmaks for access rights requested from VK API
- display = 'page'¶
sets authorisation page appearance. See VK documentation for more details
- state = None¶
an arbitrary string that will be returned together with the authorisation result
API¶
- class pyvk.config.APIConfig(**params)¶
- lang = 'en'¶
language of VK API responses
- validation = True¶
if set, captcha requests will be handled via an interactive session.
- auto_delay = True¶
when encounter a request frequency limit add delays of increasing lenghts and repeat the request max_attempts times.
- max_attempts = 5¶
how many times to repeat a failed request if the failure is configured to be handled
- raw = False¶
return raw response objects (converted from JSON) instead of unpacking and error handling. If set, validation and auto_delay will be ignored