From adf0630040af411a0883aacaab0ead92dc1d359a Mon Sep 17 00:00:00 2001 From: hdk5 Date: Sun, 1 Apr 2018 02:50:02 +0300 Subject: [PATCH 01/10] jconfig docs --- docs/conf.py | 4 ++++ docs/jconfig.rst | 36 ++++++++++-------------------------- jconfig/__init__.py | 8 ++++---- jconfig/base.py | 22 ++++++++++++++++++---- jconfig/jconfig.py | 14 ++++++++++---- jconfig/memory.py | 5 +++++ 6 files changed, 51 insertions(+), 38 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 8ba5e9ee..0c531195 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -178,6 +178,10 @@ # -- Extension configuration ------------------------------------------------- +# -- Options for autodoc extension ------------------------------------------- + +autodoc_inherit_docstrings = False + # -- Options for todo extension ---------------------------------------------- # If true, `todo` and `todoList` produce output, else they produce nothing. diff --git a/docs/jconfig.rst b/docs/jconfig.rst index 6e823ee9..03c15161 100644 --- a/docs/jconfig.rst +++ b/docs/jconfig.rst @@ -1,38 +1,22 @@ -jconfig package +Пакен jconfig =============== -Submodules ----------- +Базовый объект конфигурации +--------------------------- -jconfig.base module -------------------- - -.. automodule:: jconfig.base +.. autoclass:: jconfig.base.BaseConfig :members: - :undoc-members: - :show-inheritance: -jconfig.jconfig module ----------------------- +Объект конфигурации в файле +--------------------------- -.. automodule:: jconfig.jconfig +.. autoclass:: jconfig.jconfig.Config :members: - :undoc-members: :show-inheritance: -jconfig.memory module ---------------------- - -.. automodule:: jconfig.memory - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- +Объект конфигурации в памяти +---------------------------- -.. automodule:: jconfig +.. autoclass:: jconfig.memory.MemoryConfig :members: - :undoc-members: :show-inheritance: diff --git a/jconfig/__init__.py b/jconfig/__init__.py index 8758490f..39fe95d3 100644 --- a/jconfig/__init__.py +++ b/jconfig/__init__.py @@ -1,10 +1,10 @@ # -*- coding: utf-8 -*- """ -@author: python273 -@contact: https://vk.com/python273 -@license Apache License, Version 2.0, see LICENSE file +:authors: python273 +:contact: https://vk.com/python273 +:license: Apache License, Version 2.0, see LICENSE file -Copyright (C) 2018 +:copyright: (c) 2018 python273 """ __author__ = 'python273' diff --git a/jconfig/base.py b/jconfig/base.py index 29fa598a..98d923dd 100644 --- a/jconfig/base.py +++ b/jconfig/base.py @@ -1,14 +1,22 @@ # -*- coding: utf-8 -*- """ -@author: python273 -@contact: https://vk.com/python273 -@license Apache License, Version 2.0, see LICENSE file +:authors: python273 +:contact: https://vk.com/python273 +:license: Apache License, Version 2.0, see LICENSE file -Copyright (C) 2018 +:copyright: (c) 2018 python273 """ class BaseConfig(object): + r""" + Абстрактный базовый класс конфигурации + + У наследуемых классов должен быть определен `__slots__` + + :param section: имя подкатегории в конфиге + :param \**kwargs: будут переданы в :func:`load` + """ __slots__ = ('section_name', '_settings', '_section') @@ -38,7 +46,13 @@ def clear_section(self): self._section.clear() def load(self, **kwargs): + """ + Абстрактный метод, должен возвращать dict с конфигом + """ raise NotImplementedError def save(self): + """ + Абстрактный метод, должен сохранять конфиг + """ raise NotImplementedError diff --git a/jconfig/jconfig.py b/jconfig/jconfig.py index 8272ceda..c99d58a2 100644 --- a/jconfig/jconfig.py +++ b/jconfig/jconfig.py @@ -1,18 +1,24 @@ # -*- coding: utf-8 -*- """ -@author: python273 -@contact: https://vk.com/python273 -@license Apache License, Version 2.0, see LICENSE file +:authors: python273 +:contact: https://vk.com/python273 +:license: Apache License, Version 2.0, see LICENSE file -Copyright (C) 2018 +:copyright: (c) 2018 python273 """ + import json from .base import BaseConfig class Config(BaseConfig): + """ + Класс конфигурации в файле + + :param filename: имя файла + """ __slots__ = ('_filename',) diff --git a/jconfig/memory.py b/jconfig/memory.py index cbf82c80..1fbce7a3 100644 --- a/jconfig/memory.py +++ b/jconfig/memory.py @@ -11,6 +11,11 @@ class MemoryConfig(BaseConfig): + """ + Класс конфигурации в памяти + + :param settings: существующий dict с конфигом + """ __slots__ = tuple() From 906ad970207428c8158e0c0772811e22218d0281 Mon Sep 17 00:00:00 2001 From: hdk5 Date: Sun, 1 Apr 2018 03:12:56 +0300 Subject: [PATCH 02/10] push before going to bed --- docs/vk_api.rst | 32 ++++++++--------------- vk_api/audio.py | 8 ++++++ vk_api/vk_api.py | 66 ++++++++++++++++++++++++------------------------ 3 files changed, 52 insertions(+), 54 deletions(-) diff --git a/docs/vk_api.rst b/docs/vk_api.rst index e9b9cdef..11bafe2c 100644 --- a/docs/vk_api.rst +++ b/docs/vk_api.rst @@ -4,13 +4,20 @@ vk\_api package Submodules ---------- +Основной класс библиотеки +------------------------- + +.. module:: vk_api.vk_api + +.. autoclass:: VkApi + :members: + + vk\_api.audio module -------------------- -.. automodule:: vk_api.audio - :members: - :undoc-members: - :show-inheritance: +.. module:: vk_api.audio + vk\_api.audio\_url\_decoder module ---------------------------------- @@ -83,20 +90,3 @@ vk\_api.utils module :members: :undoc-members: :show-inheritance: - -vk\_api.vk\_api module ----------------------- - -.. automodule:: vk_api.vk_api - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: vk_api - :members: - :undoc-members: - :show-inheritance: diff --git a/vk_api/audio.py b/vk_api/audio.py index 9df46f22..871a6f04 100644 --- a/vk_api/audio.py +++ b/vk_api/audio.py @@ -1,4 +1,12 @@ # -*- coding: utf-8 -*- +""" +:authors: python273 +:contact: https://vk.com/python273 +:license: Apache License, Version 2.0, see LICENSE file + +:copyright: (c) 2018 python273 +""" + import re from bs4 import BeautifulSoup diff --git a/vk_api/vk_api.py b/vk_api/vk_api.py index 56f6e281..cebae387 100644 --- a/vk_api/vk_api.py +++ b/vk_api/vk_api.py @@ -1,10 +1,10 @@ # -*- coding: utf-8 -*- """ -@author: python273 -@contact: https://vk.com/python273 -@license Apache License, Version 2.0, see LICENSE file +:authors: python273 +:contact: https://vk.com/python273 +:license: Apache License, Version 2.0, see LICENSE file -Copyright (C) 2018 +:copyright: (c) 2018 python273 """ import logging @@ -44,43 +44,43 @@ class VkApi(object): + """ + :param login: Логин ВКонтакте (лучше использовать номер телефона для + автоматического обхода проверки безопасности) + :param password: Пароль ВКонтакте (если пароль не передан, то будет + попытка использовать сохраненные данные) - RPS_DELAY = 0.34 # ~3 requests per second + :param token: access_token + :type token: str - def __init__(self, login=None, password=None, token=None, - auth_handler=None, captcha_handler=None, - config=jconfig.Config, config_filename='vk_config.v2.json', - api_version='5.73', app_id=6222115, scope=DEFAULT_USER_SCOPE, - client_secret=None): - """ - :param login: Логин ВКонтакте (лучше использовать номер телефона для - автоматического обхода проверки безопасности) - :param password: Пароль ВКонтакте (если пароль не передан, то будет - попытка использовать сохраненные данные) + :param auth_handler: Функция для обработки двухфакторной аутентификации, + должна возвращать строку с кодом и + булево значение, означающее, стоит ли запомнить + это устройство, для прохождения аутентификации. + :param captcha_handler: Функция для обработки капчи, см. :func:`captcha_handler` + :param config: Класс для сохранения настроек + :param config_filename: Расположение config файла - :param token: access_token - :type token: str + :param api_version: Версия API + :type api_version: str - :param auth_handler: Функция для обработки двухфакторной аутентификации, - должна возвращать строку с кодом и - булевое значение, означающее, стоит ли запомнить - это устройство, для прохождения аутентификации. - :param captcha_handler: Функция для обработки капчи - :param config: Класс для сохранения настроек - :param config_filename: Расположение config файла + :param app_id: Standalone-приложение + :type app_id: int - :param api_version: Версия API - :type api_version: str + :param scope: Запрашиваемые права (можно передать строкой или числом) + :type scope: int, str - :param app_id: Standalone-приложение - :type app_id: int + :param client_secret: Защищенный ключ приложения для серверной + авторизации (https://vk.com/dev/auth_server) + """ - :param scope: Запрашиваемые права (можно передать строкой или числом) - :type scope: int, str + RPS_DELAY = 0.34 # ~3 requests per second - :param client_secret: Защищенный ключ приложения для серверной - авторизации (https://vk.com/dev/auth_server) - """ + def __init__(self, login=None, password=None, token=None, + auth_handler=None, captcha_handler=None, + config=jconfig.Config, config_filename='vk_config.v2.json', + api_version='5.73', app_id=6222115, scope=DEFAULT_USER_SCOPE, + client_secret=None): self.login = login self.password = password From 4a54cb2a84aa54ba4baa271ac248868a66a59e22 Mon Sep 17 00:00:00 2001 From: hdk5 Date: Mon, 2 Apr 2018 16:25:01 +0300 Subject: [PATCH 03/10] some docs --- docs/conf.py | 3 +- docs/vk_api.rst | 70 ++++++++++----------- jconfig/base.py | 8 +-- vk_api/audio.py | 8 ++- vk_api/enums.py | 38 +++++++++++- vk_api/exceptions.py | 8 +-- vk_api/longpoll.py | 143 +++++++++++++++++++++++++++++++++++++------ vk_api/vk_api.py | 82 +++++++++++++++---------- 8 files changed, 257 insertions(+), 103 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 0c531195..2e62a02c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -68,7 +68,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = 'en' +language = 'ru' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -181,6 +181,7 @@ # -- Options for autodoc extension ------------------------------------------- autodoc_inherit_docstrings = False +autodoc_member_order = 'bysource' # -- Options for todo extension ---------------------------------------------- diff --git a/docs/vk_api.rst b/docs/vk_api.rst index 11bafe2c..0bb0a40b 100644 --- a/docs/vk_api.rst +++ b/docs/vk_api.rst @@ -1,8 +1,5 @@ -vk\_api package -=============== - -Submodules ----------- +Пакет vk\_api +============= Основной класс библиотеки ------------------------- @@ -12,36 +9,36 @@ Submodules .. autoclass:: VkApi :members: +.. autoclass:: VkUserPermissions + :show-inheritance: + :members: -vk\_api.audio module --------------------- - +Модуль для работы с аудио +------------------------- .. module:: vk_api.audio - - -vk\_api.audio\_url\_decoder module ----------------------------------- - -.. automodule:: vk_api.audio_url_decoder +.. autoclass:: VkAudio :members: - :undoc-members: - :show-inheritance: -vk\_api.enums module --------------------- +Модуль для работы с longpoll +---------------------------- -.. automodule:: vk_api.enums +.. module:: vk_api.longpoll +.. autoclass:: VkLongPoll :members: - :undoc-members: - :show-inheritance: - -vk\_api.exceptions module -------------------------- - -.. automodule:: vk_api.exceptions +.. autoclass:: Event + :members: +.. autoclass:: VkLongpollMode + :members: +.. autoclass:: VkEventType + :members: +.. autoclass:: VkPlatform + :members: +.. autoclass:: VkOfflineType + :members: +.. autoclass:: VkMessageFlag + :members: +.. autoclass:: VkPeerFlag :members: - :undoc-members: - :show-inheritance: vk\_api.execute module ---------------------- @@ -51,14 +48,6 @@ vk\_api.execute module :undoc-members: :show-inheritance: -vk\_api.longpoll module ------------------------ - -.. automodule:: vk_api.longpoll - :members: - :undoc-members: - :show-inheritance: - vk\_api.requests\_pool module ----------------------------- @@ -90,3 +79,12 @@ vk\_api.utils module :members: :undoc-members: :show-inheritance: + + +Исключения, бросаемые библиотекой +--------------------------------- + +.. automodule:: vk_api.exceptions + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/jconfig/base.py b/jconfig/base.py index 98d923dd..5e98c1af 100644 --- a/jconfig/base.py +++ b/jconfig/base.py @@ -46,13 +46,9 @@ def clear_section(self): self._section.clear() def load(self, **kwargs): - """ - Абстрактный метод, должен возвращать dict с конфигом - """ + """Абстрактный метод, должен возвращать dict с конфигом""" raise NotImplementedError def save(self): - """ - Абстрактный метод, должен сохранять конфиг - """ + """Абстрактный метод, должен сохранять конфиг""" raise NotImplementedError diff --git a/vk_api/audio.py b/vk_api/audio.py index 871a6f04..c8e8765d 100644 --- a/vk_api/audio.py +++ b/vk_api/audio.py @@ -23,14 +23,16 @@ class VkAudio(object): + """ + Модуль для получения аудиозаписей без использования официального API. + + :type vk: vk_api.VkApi + """ __slots__ = ('_vk', 'user_id') def __init__(self, vk): - """ - :type vk: vk_api.VkApi - """ self.user_id = vk.method('users.get')[0]['id'] self._vk = vk diff --git a/vk_api/enums.py b/vk_api/enums.py index 24b0a810..f8bd4023 100644 --- a/vk_api/enums.py +++ b/vk_api/enums.py @@ -7,27 +7,61 @@ Copyright (C) 2018 """ -from enum import Enum +from enum import Enum, IntEnum -class VkUserPermissions(Enum): +class VkUserPermissions(IntEnum): + """ + Перечисление прав пользователя. + Список прав получается побитовым сложением (x & y) каждого права. + Подробнее в документации VK API: https://vk.com/dev/permissions + """ NOTIFY = 1 + """ + Пользователь разрешил отправлять ему уведомления (для flash/iframe-приложений). + Это право бесполезно для этой библиотеки. + """ FRIEND = 2 + """Доступ к друзьям.""" PHOTOS = 2**2 + """Доступ к фотографиям.""" AUDIO = 2**3 + """ + Доступ к аудиозаписям. + При отсутствии доступа к закрытому API аудиозаписей это право позволяет только загрузку аудио. + """ VIDEO = 2**4 + """Доступ к видеозаписям.""" STORIES = 2**6 + """Доступ к историям.""" PAGES = 2**7 + """Доступ к wiki-страницам.""" ADD_LINK = 2**8 + """Добавление ссылки на приложение в меню слева.""" STATUS = 2**10 + """Доступ к статусу пользователя.""" NOTES = 2**11 + """Доступ к заметкам пользователя.""" MESSAGES = 2**12 + """Доступ к расширенным методам работы с сообщениями.""" WALL = 2**13 + """Доступ к обычным и расширенным методам работы со стеной.""" ADS = 2**15 + """Доступ к расширенным методам работы с рекламным API.""" OFFLINE = 2**16 + """ + Доступ к API в любое время. + Рекомендуется при работе с этой библиотекой. + """ DOCS = 2**17 + """Доступ к документам.""" GROUPS = 2**18 + """Доступ к группам пользователя.""" NOTIFICATIONS = 2**19 + """Доступ к оповещениям об ответах пользователю.""" STATS = 2**20 + """Доступ к статистике групп и приложений пользователя, администратором которых он является.""" EMAIL = 2**22 + """Доступ к email пользователя.""" MARKET = 2**27 + """Доступ к товарам.""" diff --git a/vk_api/exceptions.py b/vk_api/exceptions.py index ce0406c4..b65c0bb4 100644 --- a/vk_api/exceptions.py +++ b/vk_api/exceptions.py @@ -1,10 +1,10 @@ # -*- coding: utf-8 -*- """ -@author: python273 -@contact: https://vk.com/python273 -@license Apache License, Version 2.0, see LICENSE file +:authors: python273 +:contact: https://vk.com/python273 +:license: Apache License, Version 2.0, see LICENSE file -Copyright (C) 2018 +:copyright: (c) 2018 python273 """ diff --git a/vk_api/longpoll.py b/vk_api/longpoll.py index c6dbad94..75ba59a5 100644 --- a/vk_api/longpoll.py +++ b/vk_api/longpoll.py @@ -9,88 +9,178 @@ from collections import defaultdict from datetime import datetime -from enum import Enum +from enum import Enum, IntEnum import requests CHAT_START_ID = int(2E9) # id с которого начинаются беседы -class VkLongpollMode(Enum): +class VkLongpollMode(IntEnum): + """Перечисление дополнительных опций ответа""" GET_ATTACHMENTS = 2 + """Получать вложения""" GET_EXTENDED = 2**3 + """Возвращать расширенный набор событий""" GET_PTS = 2**5 + """возвращать pts для метода `messages.getLongPollHistory`""" GET_EXTRA_ONLINE = 2**6 + """В событии с кодом 8 (друг стал онлайн) возвращать дополнительные данные в поле `extra`""" GET_RANDOM_ID = 2**7 + """Возвращать поле `random_id`""" -DEFAULT_MODE = sum([x.value for x in VkLongpollMode]) +DEFAULT_MODE = sum(VkLongpollMode) -class VkEventType(Enum): +class VkEventType(IntEnum): + """ + Перечисление событий, получаемых от longpoll-сервера. + Подробнее в документации VK API: https://vk.com/dev/using_longpoll?f=3.+Структура+событий + """ MESSAGE_FLAGS_REPLACE = 1 + """Замена флагов сообщения (FLAGS:=$flags)""" MESSAGE_FLAGS_SET = 2 + """Установка флагов сообщения (FLAGS|=$mask)""" MESSAGE_FLAGS_RESET = 3 + """Сброс флагов сообщения (FLAGS&=~$mask)""" MESSAGE_NEW = 4 + """Добавление нового сообщения.""" MESSAGE_EDIT = 5 + """Редактирование сообщения.""" READ_ALL_INCOMING_MESSAGES = 6 + """Прочтение всех входящих сообщений в $peer_id, пришедших до сообщения с $local_id.""" READ_ALL_OUTGOING_MESSAGES = 7 + """Прочтение всех исходящих сообщений в $peer_id, пришедших до сообщения с $local_id.""" USER_ONLINE = 8 + """ + Друг $user_id стал онлайн. $extra не равен 0, если в mode был передан флаг 64. + В младшем байте (остаток от деления на 256) числа extra лежит идентификатор + платформы (см. :class:`VkPlatform`). $timestamp — время последнего действия + пользователя $user_id на сайте. """ USER_OFFLINE = 9 + """ + Друг $user_id стал оффлайн ($flags равен 0, если пользователь покинул сайт и 1, + если оффлайн по таймауту) . $timestamp — время последнего действия пользователя + $user_id на сайте. + """ PEER_FLAGS_RESET = 10 + """ + Сброс флагов диалога $peer_id. + Соответствует операции (PEER_FLAGS &= ~$flags). + Только для диалогов сообществ. + """ PEER_FLAGS_REPLACE = 11 + """ + Замена флагов диалога $peer_id. + Соответствует операции (PEER_FLAGS:= $flags). + Только для диалогов сообществ. + """ PEER_FLAGS_SET = 12 + """ + Установка флагов диалога $peer_id. + Соответствует операции (PEER_FLAGS|= $flags). + Только для диалогов сообществ. + """ PEER_DELETE_ALL = 13 + """Удаление всех сообщений в диалоге $peer_id с идентификаторами вплоть до $local_id.""" PEER_RESTORE_ALL = 14 + """Восстановление недавно удаленных сообщений в диалоге $peer_id с идентификаторами вплоть до $local_id.""" CHAT_EDIT = 51 + """ + Один из параметров (состав, тема) беседы $chat_id были изменены. + $self — 1 или 0 (вызваны ли изменения самим пользователем). + """ USER_TYPING = 61 + """ + Пользователь $user_id набирает текст в диалоге. + Событие приходит раз в ~5 секунд при наборе текста. $flags = 1. + """ USER_TYPING_IN_CHAT = 62 + """Пользователь $user_id набирает текст в беседе $chat_id.""" USER_CALL = 70 + """Пользователь $user_id совершил звонок с идентификатором $call_id.""" MESSAGES_COUNTER_UPDATE = 80 + """Счетчик в левом меню стал равен $count.""" NOTIFICATION_SETTINGS_UPDATE = 114 + """Изменились настройки оповещений. + $peer_id — идентификатор чата/собеседника, + $sound — 1/0, включены/выключены звуковые оповещения, + $disabled_until — выключение оповещений на необходимый срок. + """ -class VkPlatform(Enum): +class VkPlatform(IntEnum): + """Идентификаторы платформ""" MOBILE = 1 + """Мобильная версия сайта или неопознанное мобильное приложение""" IPHONE = 2 + """Официальное приложение для iPhone""" IPAD = 3 + """Официальное приложение для iPad""" ANDROID = 4 + """Официальное приложение для Android""" WPHONE = 5 + """Официальное приложение для Windows Phone""" WINDOWS = 6 + """Официальное приложение для Windows 8""" WEB = 7 + """Полная версия сайта или неопознанное приложение""" -class VkOfflineType(Enum): +class VkOfflineType(IntEnum): + """Выход из сети в событии :attr:`VkEventType.USER_OFFLINE`""" EXIT = 0 + """Пользователь покинул сайт""" AWAY = 1 + """Оффлайн по таймауту""" -class VkMessageFlag(Enum): +class VkMessageFlag(IntEnum): + """Флаги сообщений""" UNREAD = 1 + """Cообщение не прочитано.""" OUTBOX = 2 + """Исходящее сообщение.""" REPLIED = 2**2 + """На сообщение был создан ответ.""" IMPORTANT = 2**3 + """Помеченное сообщение.""" CHAT = 2**4 + """Сообщение отправлено через чат.""" FRIENDS = 2**5 + """ + Cообщение отправлено другом. + Не применяется для сообщений из групповых бесед. + """ SPAM = 2**6 + """Cообщение помечено как "Спам".""" DELETED = 2**7 + """Cообщение удалено (в корзине).""" FIXED = 2**8 + """Cообщение проверено пользователем на спам.""" MEDIA = 2**9 + """Cообщение содержит медиаконтент""" HIDDEN = 2**16 + """Приветственное сообщение от сообщества.""" DELETED_ALL = 2**17 + """Cообщение удалено для всех получателей.""" -class VkPeerFlag(Enum): +class VkPeerFlag(IntEnum): + """Флаги диалогов""" IMPORTANT = 1 + """Важный диалог""" UNANSWERED = 2 + """Неотвеченный диалог""" MESSAGE_EXTRA_FIELDS = [ @@ -151,6 +241,21 @@ def get_all_event_attrs(): class VkLongPoll(object): + """ + Класс для работы с longpoll-сервером + + Подробнее в документации VK API: + + https://vk.com/dev/using_longpoll + + https://vk.com/dev/using_longpoll_2 + + :param vk: объект :class:`VkApi` + :param wait: время ожидания + :param mode: дополнительные опции ответа + :param preload_messages: предзагрузка данных сообщений для + получения ссылок на прикрепленные файлы + """ __slots__ = ( 'vk', 'wait', 'mode', 'preload_messages', @@ -164,16 +269,6 @@ class VkLongPoll(object): ] def __init__(self, vk, wait=25, mode=DEFAULT_MODE, preload_messages=True): - """ - https://vk.com/dev/using_longpoll - https://vk.com/dev/using_longpoll_2 - - :param vk: объект VkApi - :param wait: время ожидания - :param mode: дополнительные опции ответа - :param preload_messages: предзагрузка данных сообщений для - получения ссылок на прикрепленные файлы - """ self.vk = vk self.wait = wait @@ -208,6 +303,11 @@ def update_longpoll_server(self, update_ts=True): self.pts = response['pts'] def check(self): + """ + Получить события от сервера один раз + + :returns: `list` of :class:`Event` + """ values = { 'act': 'a_check', 'key': self.key, @@ -263,10 +363,16 @@ def preload_message_events_data(self, events): event.message_data = message def listen(self): + """ + Слушать сервер + + :yields: :class:`Event` + """ while True: events = self.check() + # Мне кажется, это должно быть в check if self.preload_messages: self.preload_message_events_data(events) @@ -275,6 +381,7 @@ def listen(self): class Event(object): + """TODO Описать отдельно распаршенные поля (datetime и прочие enum-ы)""" __slots__ = frozenset(( 'raw', 'type', 'platform', 'offline_type', diff --git a/vk_api/vk_api.py b/vk_api/vk_api.py index cebae387..abad9b23 100644 --- a/vk_api/vk_api.py +++ b/vk_api/vk_api.py @@ -40,38 +40,50 @@ RE_PHONE_POSTFIX = re.compile(r'phone_postfix">.*?(\d+).*?<') -DEFAULT_USER_SCOPE = sum([x.value for x in VkUserPermissions]) +DEFAULT_USER_SCOPE = sum(VkUserPermissions) class VkApi(object): """ :param login: Логин ВКонтакте (лучше использовать номер телефона для - автоматического обхода проверки безопасности) + автоматического обхода проверки безопасности) + :type login: str + :param password: Пароль ВКонтакте (если пароль не передан, то будет - попытка использовать сохраненные данные) + попытка использовать сохраненные данные) + :param login: str :param token: access_token :type token: str :param auth_handler: Функция для обработки двухфакторной аутентификации, - должна возвращать строку с кодом и - булево значение, означающее, стоит ли запомнить - это устройство, для прохождения аутентификации. + должна возвращать строку с кодом и + булево значение, означающее, стоит ли запомнить + это устройство, для прохождения аутентификации. :param captcha_handler: Функция для обработки капчи, см. :func:`captcha_handler` :param config: Класс для сохранения настроек - :param config_filename: Расположение config файла + :type config: :class:`jconfig.base.BaseConfig` + :param config_filename: Расположение config файла для :class:`jconfig.config.Config` :param api_version: Версия API :type api_version: str - :param app_id: Standalone-приложение + :param app_id: app_id Standalone-приложения :type app_id: int - :param scope: Запрашиваемые права (можно передать строкой или числом) + :param scope: Запрашиваемые права, можно передать строкой или числом. + См. :class:`VkUserPermissions` :type scope: int, str - :param client_secret: Защищенный ключ приложения для серверной - авторизации (https://vk.com/dev/auth_server) + :param client_secret: Защищенный ключ приложения для Client Credentials Flow + авторизации приложения (https://vk.com/dev/client_cred_flow). + Внимание: Этот способ авторизации устарел, рекомендуется использовать + сервисный ключ из настроек приложения. + + + `login` и `password` необходимы для автоматического получения токена при помощи + Implicit Flow авторизации пользователя и возможности работы с веб-версией сайта + (включая :class:`vk_api.audio.VkAudio`) """ RPS_DELAY = 0.34 # ~3 requests per second @@ -81,6 +93,8 @@ def __init__(self, login=None, password=None, token=None, config=jconfig.Config, config_filename='vk_config.v2.json', api_version='5.73', app_id=6222115, scope=DEFAULT_USER_SCOPE, client_secret=None): + # TODO: убрать config_filename, в качестве config брать объект, а не класс + # TODO: убрать auth_handler и captcha_handler - это должно происходить через наследование self.login = login self.password = password @@ -114,7 +128,7 @@ def __init__(self, login=None, password=None, token=None, self.logger = logging.getLogger('vk_api') @property - def sid(self): + def _sid(self): return ( self.http.cookies.get('remixsid') or self.http.cookies.get('remixsid6') @@ -124,23 +138,23 @@ def auth(self, reauth=False, token_only=False): """ Аутентификация :param reauth: Позволяет переавторизиваться, игнорируя сохраненные - куки и токен + куки и токен :param token_only: Включает оптимальную стратегию аутентификации, если - необходим только access_token + необходим только access_token - Например если сохраненные куки не валидны, - но токен валиден, то аутентификация пройдет успешно + Например если сохраненные куки не валидны, + но токен валиден, то аутентификация пройдет успешно - При token_only=False, сначала проверяется - валидность куки. Если кука не будет валидна, то - будет произведена попытка аутетификации с паролем. - Тогда если пароль не верен или пароль не передан, - то аутентификация закончится с ошибкой. + При token_only=False, сначала проверяется + валидность куки. Если кука не будет валидна, то + будет произведена попытка аутетификации с паролем. + Тогда если пароль не верен или пароль не передан, + то аутентификация закончится с ошибкой. - Если вы не делаете запросы к веб версии сайта - используя куки, то лучше использовать - token_only=True + Если вы не делаете запросы к веб версии сайта + используя куки, то лучше использовать + token_only=True """ if not self.login: @@ -178,7 +192,7 @@ def _auth_cookies(self, reauth=False): if not self.check_sid(): self.logger.info( 'remixsid from config is not valid: {}'.format( - self.sid + self._sid ) ) @@ -285,7 +299,7 @@ def vk_login(self, captcha_sid=None, captcha_key=None): self.twofactor(response) - if self.sid: + if self._sid: self.logger.info('Got remixsid') self.storage.cookies = cookies_to_list(self.http.cookies) @@ -302,7 +316,8 @@ def vk_login(self, captcha_sid=None, captcha_key=None): def twofactor(self, auth_response): """ Двухфакторная аутентификация - :param auth_response: страница с приглашением к аутентификации + + :param auth_response: страница с приглашением к аутентификации """ code, remember_device = self.error_handlers[TWOFACTOR_CODE]() @@ -343,7 +358,8 @@ def security_check(self, response=None): return response phone_prefix = clear_string(search_re(RE_PHONE_PREFIX, response.text)) - phone_postfix = clear_string(search_re(RE_PHONE_POSTFIX, response.text)) + phone_postfix = clear_string( + search_re(RE_PHONE_POSTFIX, response.text)) code = None if self.login and phone_prefix and phone_postfix: @@ -376,7 +392,7 @@ def check_sid(self): self.logger.info('Checking remixsid...') - if not self.sid: + if not self._sid: self.logger.info('No remixsid') return @@ -391,7 +407,7 @@ def check_sid(self): def api_login(self): """ Получение токена через Desktop приложение """ - if not self.sid: + if not self._sid: raise AuthError('API auth error (no remixsid)') for cookie_name in ['p', 'l']: @@ -406,7 +422,7 @@ def api_login(self): 'response_type': 'token' } ) - + if 'act=blocked' in response.url: raise AccountBlocked('Account is blocked') @@ -494,7 +510,7 @@ def need_validation_handler(self, error): def http_handler(self, error): """ Обработчик ошибок соединения - + :param error: исключение """ @@ -519,7 +535,7 @@ def auth_handler(self): def get_api(self): """ Возвращает VkApiMethod(self) - + Позволяет обращаться к методам API как к обычным классам. Например vk.wall.get(...) """ From 71a36ccea486336fd1d0fde8da1fe76fedc9cf39 Mon Sep 17 00:00:00 2001 From: hdk5 Date: Thu, 5 Apr 2018 13:55:53 +0300 Subject: [PATCH 04/10] almost all docs --- docs/vk_api.rst | 47 +++++++++++++++++------------------------ vk_api/audio.py | 2 +- vk_api/execute.py | 29 ++++++++++++++----------- vk_api/longpoll.py | 33 +++++++++++++++++------------ vk_api/requests_pool.py | 33 +++++++++++++++++++++-------- vk_api/tools.py | 46 ++++++++++++++++++++++------------------ vk_api/upload.py | 12 +++++------ 7 files changed, 112 insertions(+), 90 deletions(-) diff --git a/docs/vk_api.rst b/docs/vk_api.rst index 0bb0a40b..6f698609 100644 --- a/docs/vk_api.rst +++ b/docs/vk_api.rst @@ -40,45 +40,36 @@ .. autoclass:: VkPeerFlag :members: -vk\_api.execute module ----------------------- +Модуль для работы с методом execute +----------------------------------- -.. automodule:: vk_api.execute +.. module:: vk_api.execute +.. autoclass:: VkFunction :members: - :undoc-members: - :show-inheritance: + :special-members: __call__ -vk\_api.requests\_pool module ------------------------------ +Модуль для объединения запросов в один запрос execute +----------------------------------------------------- -.. automodule:: vk_api.requests_pool +.. module:: vk_api.requests_pool +.. autoclass:: VkRequestsPool :members: - :undoc-members: - :show-inheritance: - -vk\_api.tools module --------------------- - -.. automodule:: vk_api.tools +.. autoclass:: RequestResult :members: - :undoc-members: - :show-inheritance: -vk\_api.upload module ---------------------- +Модуль для выкачивания множества результатов +-------------------------------------------- -.. automodule:: vk_api.upload +.. module:: vk_api.tools +.. autoclass:: VkTools :members: - :undoc-members: - :show-inheritance: -vk\_api.utils module --------------------- +Модуль для загрузки медиаконтента в VK +-------------------------------------- -.. automodule:: vk_api.utils +.. module:: vk_api.upload +.. autoclass:: VkUpload :members: - :undoc-members: - :show-inheritance: Исключения, бросаемые библиотекой @@ -87,4 +78,4 @@ vk\_api.utils module .. automodule:: vk_api.exceptions :members: :undoc-members: - :show-inheritance: \ No newline at end of file + :show-inheritance: diff --git a/vk_api/audio.py b/vk_api/audio.py index c8e8765d..cfa13bb5 100644 --- a/vk_api/audio.py +++ b/vk_api/audio.py @@ -26,7 +26,7 @@ class VkAudio(object): """ Модуль для получения аудиозаписей без использования официального API. - :type vk: vk_api.VkApi + :param vk: Объект :class:`VkApi` """ __slots__ = ('_vk', 'user_id') diff --git a/vk_api/execute.py b/vk_api/execute.py index ea25977c..9121326d 100644 --- a/vk_api/execute.py +++ b/vk_api/execute.py @@ -1,10 +1,10 @@ # -*- coding: utf-8 -*- """ -@author: python273 -@contact: https://vk.com/python273 -@license Apache License, Version 2.0, see LICENSE file +:authors: python273 +:contact: https://vk.com/python273 +:license: Apache License, Version 2.0, see LICENSE file -Copyright (C) 2018 +:copyright: (c) 2018 python273 """ from .utils import sjson_dumps @@ -12,18 +12,18 @@ class VkFunction(object): + """ + Обертка над методом execute. + + :param code: код функции (VKScript) + :param args: список аргументов (будут конвертированы в JSON) + :param clean_args: список raw аргументов (будут вставлены как строки) + :param return_raw: аргумент raw функции VkApi.method + """ __slots__ = ('code', '_minified_code', 'args', 'clean_args', 'return_raw') def __init__(self, code, args=None, clean_args=None, return_raw=False): - """ Обертка над методом execute - - :param code: код функции (VKScript) - :param args: список аргументов (будут конвертированы в JSON) - :param clean_args: список raw аргументов (будут вставлены как строки) - :param return_raw: аргумент raw функции VkApi.method - """ - self.code = code self._minified_code = minify(code) @@ -44,6 +44,11 @@ def compile(self, args): return self._minified_code % compiled_args def __call__(self, vk, *args, **kwargs): + r""" + :param vk: VkApi или VkApiMethod + :param \*args: + :param \**kwargs: + """ if not isinstance(vk, (VkApi, VkApiMethod)): raise TypeError( diff --git a/vk_api/longpoll.py b/vk_api/longpoll.py index 75ba59a5..b29113e7 100644 --- a/vk_api/longpoll.py +++ b/vk_api/longpoll.py @@ -17,7 +17,11 @@ class VkLongpollMode(IntEnum): - """Перечисление дополнительных опций ответа""" + """ + Дополнительные опции ответа + + `Подробнее в документации VK API `_ + """ GET_ATTACHMENTS = 2 """Получать вложения""" GET_EXTENDED = 2**3 @@ -36,7 +40,8 @@ class VkLongpollMode(IntEnum): class VkEventType(IntEnum): """ Перечисление событий, получаемых от longpoll-сервера. - Подробнее в документации VK API: https://vk.com/dev/using_longpoll?f=3.+Структура+событий + + `Подробнее в документации VK API `__ """ MESSAGE_FLAGS_REPLACE = 1 """Замена флагов сообщения (FLAGS:=$flags)""" @@ -244,11 +249,7 @@ class VkLongPoll(object): """ Класс для работы с longpoll-сервером - Подробнее в документации VK API: - - https://vk.com/dev/using_longpoll - - https://vk.com/dev/using_longpoll_2 + `Подробнее в документации VK API `__. :param vk: объект :class:`VkApi` :param wait: время ожидания @@ -279,7 +280,7 @@ def __init__(self, vk, wait=25, mode=DEFAULT_MODE, preload_messages=True): self.key = None self.server = None self.ts = None - self.pts = mode & VkLongpollMode.GET_PTS.value + self.pts = mode & VkLongpollMode.GET_PTS self.session = requests.Session() @@ -365,7 +366,7 @@ def preload_message_events_data(self, events): def listen(self): """ Слушать сервер - + :yields: :class:`Event` """ @@ -381,7 +382,13 @@ def listen(self): class Event(object): - """TODO Описать отдельно распаршенные поля (datetime и прочие enum-ы)""" + """ + Событие, полученное от longpoll-сервера. + + Имеет поля в соответствии с `документацией `_. + + События с полем `timestamp` также дополнительно имеют поле `datetime` + """ __slots__ = frozenset(( 'raw', 'type', 'platform', 'offline_type', @@ -461,17 +468,17 @@ def _parse_peer_id(self): def _parse_message_flags(self): self.message_flags = set( - x for x in VkMessageFlag if self.flags & x.value + x for x in VkMessageFlag if self.flags & x ) def _parse_peer_flags(self): self.peer_flags = set( - x for x in VkPeerFlag if self.flags & x.value + x for x in VkPeerFlag if self.flags & x ) def _parse_message(self): - if self.flags & VkMessageFlag.OUTBOX.value: + if self.flags & VkMessageFlag.OUTBOX: self.from_me = True else: self.to_me = True diff --git a/vk_api/requests_pool.py b/vk_api/requests_pool.py index 01acc420..cdf9c0f5 100644 --- a/vk_api/requests_pool.py +++ b/vk_api/requests_pool.py @@ -1,10 +1,10 @@ # -*- coding: utf-8 -*- """ -@author: python273 -@contact: https://vk.com/python273 -@license Apache License, Version 2.0, see LICENSE file +:authors: python273 +:contact: https://vk.com/python273 +:license: Apache License, Version 2.0, see LICENSE file -Copyright (C) 2018 +:copyright: (c) 2018 python273 """ import sys @@ -25,6 +25,7 @@ class VkRequestsPoolException(Exception): class RequestResult(object): + """ Результат запроса из пула""" __slots__ = ('_result', 'ready', '_error') @@ -35,6 +36,7 @@ def __init__(self): @property def error(self): + """Ошибка, либо `False`, если запрос прошёл успешно.""" return self._error @error.setter @@ -44,6 +46,7 @@ def error(self, value): @property def result(self): + """Результат запроса, если он прошёл успешно.""" if not self.ready: raise RuntimeError('Result is not available in `with` context') @@ -59,12 +62,19 @@ def result(self, result): @property def ok(self): + """`True`, если результат запроса не содержит ошибок, иначе `False`""" return self.ready and not self._error class VkRequestsPool(object): - """ Позволяет сделать несколько обращений к API за один запрос - за счет метода execute + """ + Позволяет сделать несколько обращений к API за один запрос + за счет метода execute. + + Служит как менеджер контекста: запросы к API добавляются в + открытый пул, и выполняются при его закрытии. + + :param vk: Объект :class:`VkApi` """ __slots__ = ('vk', 'pool', 'one_param', 'execute_errors') @@ -88,7 +98,9 @@ def get_execute_errors(self): return self.execute_errors def method(self, method, values=None): - """ Добавляет запрос в пулл + """ + Добавляет запрос в пул. Невозможно использовать вместе с :func:`method_one_param`. + Возвращаемое значение будет содержать результат после закрытия пула. :param method: метод :type method: str @@ -111,7 +123,10 @@ def method(self, method, values=None): return result def method_one_param(self, method, key, values, default_values=None): - """ Использовать, если изменяется значение только одного параметра + """ + Использовать, если изменяется значение только одного параметра. + Невозможно использовать вместе с :func:`method`. + Возвращаемое значение будет содержать результат после закрытия пула. :param method: метод :type method: str @@ -196,7 +211,7 @@ def execute_one_param(self): def check_one_method(pool): - """ Возвращает True, если все запросы в пулле к одному методу """ + """ Возвращает True, если все запросы в пуле к одному методу """ if not pool: return False diff --git a/vk_api/tools.py b/vk_api/tools.py index 25d2a349..db02007d 100644 --- a/vk_api/tools.py +++ b/vk_api/tools.py @@ -1,10 +1,10 @@ # -*- coding: utf-8 -*- """ -@author: python273 -@contact: https://vk.com/python273 -@license Apache License, Version 2.0, see LICENSE file +:authors: python273 +:contact: https://vk.com/python273 +:license: Apache License, Version 2.0, see LICENSE file -Copyright (C) 2018 +:copyright: (c) 2018 python273 """ import sys @@ -17,21 +17,22 @@ class VkTools(object): - """ Содержит некоторые воспомогательные функции, которые могут понадобиться - при использовании API + """ + Содержит некоторые воспомогательные функции, которые могут понадобиться + при использовании API + + :param vk: Объект :class:`VkApi` """ __slots__ = ('vk',) def __init__(self, vk): - """ - :param vk: объект VkApi - """ self.vk = vk def get_all_iter(self, method, max_count, values=None, key='items', limit=None, stop_fn=None, negative_offset=False): - """ Получить все элементы. + """ + Получить все элементы. Работает в методах, где в ответе есть count и items или users. За один запрос получает max_count * 25 элементов @@ -97,13 +98,14 @@ def get_all_iter(self, method, max_count, values=None, key='items', def get_all(self, method, max_count, values=None, key='items', limit=None, stop_fn=None, negative_offset=False): - """ Использовать только если нужно загрузить все объекты в память. + """ + Использовать только если нужно загрузить все объекты в память. - Eсли вы можете обрабатывать объекты по частям, то лучше - использовать get_all_iter + Eсли вы можете обрабатывать объекты по частям, то лучше + использовать get_all_iter - Например если вы записываете объекты в БД, то нет смысла загружать - все данные в память + Например если вы записываете объекты в БД, то нет смысла загружать + все данные в память """ items = list( @@ -116,7 +118,8 @@ def get_all(self, method, max_count, values=None, key='items', limit=None, def get_all_slow_iter(self, method, max_count, values=None, key='items', limit=None, stop_fn=None, negative_offset=False): - """ Получить все элементы (без использования execute) + """ + Получить все элементы (без использования execute) Работает в методах, где в ответе есть count и items или users :param method: имя метода @@ -187,13 +190,14 @@ def get_all_slow_iter(self, method, max_count, values=None, key='items', def get_all_slow(self, method, max_count, values=None, key='items', limit=None, stop_fn=None, negative_offset=False): - """ Использовать только если нужно загрузить все объекты в память. + """ + Использовать только если нужно загрузить все объекты в память. - Eсли вы можете обрабатывать объекты по частям, то лучше - использовать get_all_slow_iter + Eсли вы можете обрабатывать объекты по частям, то лучше + использовать get_all_slow_iter - Например если вы записываете объекты в БД, то нет смысла загружать - все данные в память + Например если вы записываете объекты в БД, то нет смысла загружать + все данные в память """ items = list( diff --git a/vk_api/upload.py b/vk_api/upload.py index a91f6789..f6ac0060 100644 --- a/vk_api/upload.py +++ b/vk_api/upload.py @@ -1,10 +1,10 @@ # -*- coding: utf-8 -*- """ -@author: python273 -@contact: https://vk.com/python273 -@license Apache License, Version 2.0, see LICENSE file +:authors: python273 +:contact: https://vk.com/python273 +:license: Apache License, Version 2.0, see LICENSE file -Copyright (C) 2018 +:copyright: (c) 2018 python273 """ @@ -320,8 +320,8 @@ def document(self, doc, title=None, tags=None, group_id=None, def document_wall(self, doc, title=None, tags=None, group_id=None): """ Загрузка документа в папку Отправленные, - для последующей отправки документа на стену - или личным сообщением. + для последующей отправки документа на стену + или личным сообщением. :param doc: путь к документу или file-like объект :param title: название документа From c9b8bf9a99ad77e4411e644bb5dd284d31c65bd9 Mon Sep 17 00:00:00 2001 From: hdk5 Date: Fri, 6 Apr 2018 00:38:59 +0300 Subject: [PATCH 05/10] Separated doc pages for each module --- docs/audio.rst | 8 +++++ docs/conf.py | 1 + docs/exceptions.rst | 7 ++++ docs/execute.rst | 9 ++++++ docs/index.rst | 13 ++++++-- docs/jconfig.rst | 2 +- docs/longpoll.rst | 22 +++++++++++++ docs/requests_pool.rst | 10 ++++++ docs/tools.rst | 8 +++++ docs/upload.rst | 8 +++++ docs/vk_api.rst | 72 +----------------------------------------- vk_api/vk_api.py | 1 - 12 files changed, 85 insertions(+), 76 deletions(-) create mode 100644 docs/audio.rst create mode 100644 docs/exceptions.rst create mode 100644 docs/execute.rst create mode 100644 docs/longpoll.rst create mode 100644 docs/requests_pool.rst create mode 100644 docs/tools.rst create mode 100644 docs/upload.rst diff --git a/docs/audio.rst b/docs/audio.rst new file mode 100644 index 00000000..d2b8c317 --- /dev/null +++ b/docs/audio.rst @@ -0,0 +1,8 @@ +Модуль `audio` +============== + +Модуль для работы с аудио + +.. module:: vk_api.audio +.. autoclass:: VkAudio + :members: diff --git a/docs/conf.py b/docs/conf.py index 2e62a02c..e9e0f634 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -85,6 +85,7 @@ # a list of builtin themes. # html_theme = 'alabaster' +# html_theme = "sphinx_rtd_theme" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/exceptions.rst b/docs/exceptions.rst new file mode 100644 index 00000000..f7535a55 --- /dev/null +++ b/docs/exceptions.rst @@ -0,0 +1,7 @@ +Исключения, бросаемые библиотекой +================================= + +.. automodule:: vk_api.exceptions + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/execute.rst b/docs/execute.rst new file mode 100644 index 00000000..d1ee0a41 --- /dev/null +++ b/docs/execute.rst @@ -0,0 +1,9 @@ +Модуль `execute` +================ + +Модуль для работы с методом execute + +.. module:: vk_api.execute +.. autoclass:: VkFunction + :members: + :special-members: __call__ diff --git a/docs/index.rst b/docs/index.rst index 171d3194..92617163 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,14 +1,21 @@ -Welcome to vk_api's documentation! -================================== +Документация к библиотеке vk_api +================================ vk_api – Python модуль для написания скриптов для социальной сети Вконтакте (vk.com) (API wrapper) .. toctree:: :maxdepth: 4 - :caption: Contents: + :caption: Содержание: vk_api + audio + longpoll + execute + requests_pool + tools + upload + exceptions jconfig diff --git a/docs/jconfig.rst b/docs/jconfig.rst index 03c15161..cba8aa4b 100644 --- a/docs/jconfig.rst +++ b/docs/jconfig.rst @@ -1,4 +1,4 @@ -Пакен jconfig +Пакет jconfig =============== Базовый объект конфигурации diff --git a/docs/longpoll.rst b/docs/longpoll.rst new file mode 100644 index 00000000..88b6f9f1 --- /dev/null +++ b/docs/longpoll.rst @@ -0,0 +1,22 @@ +Модуль `longpoll` +================= + +Модуль для работы с longpoll + +.. module:: vk_api.longpoll +.. autoclass:: VkLongPoll + :members: +.. autoclass:: Event + :members: +.. autoclass:: VkLongpollMode + :members: +.. autoclass:: VkEventType + :members: +.. autoclass:: VkPlatform + :members: +.. autoclass:: VkOfflineType + :members: +.. autoclass:: VkMessageFlag + :members: +.. autoclass:: VkPeerFlag + :members: \ No newline at end of file diff --git a/docs/requests_pool.rst b/docs/requests_pool.rst new file mode 100644 index 00000000..032f5ce8 --- /dev/null +++ b/docs/requests_pool.rst @@ -0,0 +1,10 @@ +Модуль `requests_pool` +====================== + +Модуль для объединения запросов в один запрос execute + +.. module:: vk_api.requests_pool +.. autoclass:: VkRequestsPool + :members: +.. autoclass:: RequestResult + :members: diff --git a/docs/tools.rst b/docs/tools.rst new file mode 100644 index 00000000..6b2c158f --- /dev/null +++ b/docs/tools.rst @@ -0,0 +1,8 @@ +Модуль `tools` +============== + +Модуль для выкачивания множества результатов + +.. module:: vk_api.tools +.. autoclass:: VkTools + :members: \ No newline at end of file diff --git a/docs/upload.rst b/docs/upload.rst new file mode 100644 index 00000000..8365c350 --- /dev/null +++ b/docs/upload.rst @@ -0,0 +1,8 @@ +Модуль `upload` +=============== + +Модуль для загрузки медиаконтента в VK + +.. module:: vk_api.upload +.. autoclass:: VkUpload + :members: \ No newline at end of file diff --git a/docs/vk_api.rst b/docs/vk_api.rst index 6f698609..0a5738b0 100644 --- a/docs/vk_api.rst +++ b/docs/vk_api.rst @@ -1,8 +1,5 @@ -Пакет vk\_api -============= - Основной класс библиотеки -------------------------- +========================= .. module:: vk_api.vk_api @@ -12,70 +9,3 @@ .. autoclass:: VkUserPermissions :show-inheritance: :members: - -Модуль для работы с аудио -------------------------- -.. module:: vk_api.audio -.. autoclass:: VkAudio - :members: - -Модуль для работы с longpoll ----------------------------- - -.. module:: vk_api.longpoll -.. autoclass:: VkLongPoll - :members: -.. autoclass:: Event - :members: -.. autoclass:: VkLongpollMode - :members: -.. autoclass:: VkEventType - :members: -.. autoclass:: VkPlatform - :members: -.. autoclass:: VkOfflineType - :members: -.. autoclass:: VkMessageFlag - :members: -.. autoclass:: VkPeerFlag - :members: - -Модуль для работы с методом execute ------------------------------------ - -.. module:: vk_api.execute -.. autoclass:: VkFunction - :members: - :special-members: __call__ - -Модуль для объединения запросов в один запрос execute ------------------------------------------------------ - -.. module:: vk_api.requests_pool -.. autoclass:: VkRequestsPool - :members: -.. autoclass:: RequestResult - :members: - -Модуль для выкачивания множества результатов --------------------------------------------- - -.. module:: vk_api.tools -.. autoclass:: VkTools - :members: - -Модуль для загрузки медиаконтента в VK --------------------------------------- - -.. module:: vk_api.upload -.. autoclass:: VkUpload - :members: - - -Исключения, бросаемые библиотекой ---------------------------------- - -.. automodule:: vk_api.exceptions - :members: - :undoc-members: - :show-inheritance: diff --git a/vk_api/vk_api.py b/vk_api/vk_api.py index abad9b23..92161a29 100644 --- a/vk_api/vk_api.py +++ b/vk_api/vk_api.py @@ -94,7 +94,6 @@ def __init__(self, login=None, password=None, token=None, api_version='5.73', app_id=6222115, scope=DEFAULT_USER_SCOPE, client_secret=None): # TODO: убрать config_filename, в качестве config брать объект, а не класс - # TODO: убрать auth_handler и captcha_handler - это должно происходить через наследование self.login = login self.password = password From f925c1fb18a6dad7c20363d2e194ebe0a43bf616 Mon Sep 17 00:00:00 2001 From: hdk5 Date: Fri, 6 Apr 2018 01:42:04 +0300 Subject: [PATCH 06/10] theme tweaks --- docs/_static/css/custom.css | 3 +++ docs/_static/custom.css | 5 ----- docs/_templates/sidebarlogo.html | 8 -------- docs/conf.py | 13 +++++++++++-- 4 files changed, 14 insertions(+), 15 deletions(-) create mode 100644 docs/_static/css/custom.css delete mode 100644 docs/_static/custom.css delete mode 100644 docs/_templates/sidebarlogo.html diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 00000000..1d0cd268 --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,3 @@ +.logo { + font-family: monospace; +} diff --git a/docs/_static/custom.css b/docs/_static/custom.css deleted file mode 100644 index 872a9562..00000000 --- a/docs/_static/custom.css +++ /dev/null @@ -1,5 +0,0 @@ -.logo-text { - font-family: "Courier New", Courier, monospace; - font-size: 16px; - font-size: 4vw; -} diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html deleted file mode 100644 index 4241fed2..00000000 --- a/docs/_templates/sidebarlogo.html +++ /dev/null @@ -1,8 +0,0 @@ -
- vk_api -
- -

- -

diff --git a/docs/conf.py b/docs/conf.py index e9e0f634..0c175180 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -112,10 +112,19 @@ # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', # 'searchbox.html']``. # +# html_sidebars = { +# '**': [ +# 'sidebarlogo.html', 'localtoc.html', 'relations.html', +# 'sourcelink.html', 'searchbox.html' +# ] +# } html_sidebars = { '**': [ - 'sidebarlogo.html', 'localtoc.html', 'relations.html', - 'sourcelink.html', 'searchbox.html' + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + 'donate.html', ] } From 5d315172f449ae71e73dcfdde6c4a1a59676b499 Mon Sep 17 00:00:00 2001 From: python273 Date: Sat, 7 Apr 2018 15:28:37 +0300 Subject: [PATCH 07/10] Update docs titles --- docs/audio.rst | 4 ++-- docs/exceptions.rst | 4 ++-- docs/execute.rst | 4 ++-- docs/index.rst | 11 +++++++++-- docs/jconfig.rst | 8 ++++---- docs/longpoll.rst | 4 ++-- docs/requests_pool.rst | 4 ++-- docs/tools.rst | 4 ++-- docs/upload.rst | 6 +++--- docs/vk_api.rst | 4 ++-- 10 files changed, 30 insertions(+), 23 deletions(-) diff --git a/docs/audio.rst b/docs/audio.rst index d2b8c317..995b4714 100644 --- a/docs/audio.rst +++ b/docs/audio.rst @@ -1,5 +1,5 @@ -Модуль `audio` -============== +VkAudio +======= Модуль для работы с аудио diff --git a/docs/exceptions.rst b/docs/exceptions.rst index f7535a55..405a78df 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -1,5 +1,5 @@ -Исключения, бросаемые библиотекой -================================= +Исключения библиотеки +===================== .. automodule:: vk_api.exceptions :members: diff --git a/docs/execute.rst b/docs/execute.rst index d1ee0a41..37cc5d2a 100644 --- a/docs/execute.rst +++ b/docs/execute.rst @@ -1,5 +1,5 @@ -Модуль `execute` -================ +VkFunction +========== Модуль для работы с методом execute diff --git a/docs/index.rst b/docs/index.rst index 92617163..de4e863d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,9 +1,16 @@ -Документация к библиотеке vk_api -================================ +Документация vk_api +=================== vk_api – Python модуль для написания скриптов для социальной сети Вконтакте (vk.com) (API wrapper) +`Установка через PIP +`_: + +.. code-block:: bash + + $ pip install vk_api + .. toctree:: :maxdepth: 4 :caption: Содержание: diff --git a/docs/jconfig.rst b/docs/jconfig.rst index cba8aa4b..38d899ad 100644 --- a/docs/jconfig.rst +++ b/docs/jconfig.rst @@ -1,20 +1,20 @@ Пакет jconfig -=============== +============= -Базовый объект конфигурации +BaseConfig --------------------------- .. autoclass:: jconfig.base.BaseConfig :members: -Объект конфигурации в файле +Config (хранение в json файле) --------------------------- .. autoclass:: jconfig.jconfig.Config :members: :show-inheritance: -Объект конфигурации в памяти +MemoryConfig (хранение в памяти) ---------------------------- .. autoclass:: jconfig.memory.MemoryConfig diff --git a/docs/longpoll.rst b/docs/longpoll.rst index 88b6f9f1..65bff4a9 100644 --- a/docs/longpoll.rst +++ b/docs/longpoll.rst @@ -1,5 +1,5 @@ -Модуль `longpoll` -================= +Модуль `longpoll` (VkLongPoll) +============================== Модуль для работы с longpoll diff --git a/docs/requests_pool.rst b/docs/requests_pool.rst index 032f5ce8..31969121 100644 --- a/docs/requests_pool.rst +++ b/docs/requests_pool.rst @@ -1,5 +1,5 @@ -Модуль `requests_pool` -====================== +VkRequestsPool +============== Модуль для объединения запросов в один запрос execute diff --git a/docs/tools.rst b/docs/tools.rst index 6b2c158f..42040d5b 100644 --- a/docs/tools.rst +++ b/docs/tools.rst @@ -1,5 +1,5 @@ -Модуль `tools` -============== +VkTools +======= Модуль для выкачивания множества результатов diff --git a/docs/upload.rst b/docs/upload.rst index 8365c350..a6ce002f 100644 --- a/docs/upload.rst +++ b/docs/upload.rst @@ -1,7 +1,7 @@ -Модуль `upload` -=============== +VkUpload +======== -Модуль для загрузки медиаконтента в VK +Модуль для загрузки медиафайлов в VK .. module:: vk_api.upload .. autoclass:: VkUpload diff --git a/docs/vk_api.rst b/docs/vk_api.rst index 0a5738b0..f6f7e47e 100644 --- a/docs/vk_api.rst +++ b/docs/vk_api.rst @@ -1,5 +1,5 @@ -Основной класс библиотеки -========================= +VkApi (основной класс) +====================== .. module:: vk_api.vk_api From 7ce3e93ef5362e472d629199c7d368118b54f695 Mon Sep 17 00:00:00 2001 From: python273 Date: Sat, 7 Apr 2018 15:36:35 +0300 Subject: [PATCH 08/10] Fix some VkApi docstings --- vk_api/vk_api.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vk_api/vk_api.py b/vk_api/vk_api.py index 92161a29..c971e37f 100644 --- a/vk_api/vk_api.py +++ b/vk_api/vk_api.py @@ -51,7 +51,7 @@ class VkApi(object): :param password: Пароль ВКонтакте (если пароль не передан, то будет попытка использовать сохраненные данные) - :param login: str + :param password: str :param token: access_token :type token: str @@ -545,7 +545,7 @@ def method(self, method, values=None, captcha_sid=None, captcha_key=None, raw=False): """ Вызов метода API - :param method: имя метода + :param method: название метода :type method: str :param values: параметры From fc54f7c9e5d352d36c5e61704c070a32e9279ca4 Mon Sep 17 00:00:00 2001 From: hdk5 Date: Sat, 7 Apr 2018 21:33:59 +0300 Subject: [PATCH 09/10] --- docs/_static/css/custom.css | 2 +- docs/conf.py | 1 + docs/index.rst | 12 ++++++++++-- docs/jconfig.rst | 4 ++-- 4 files changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index 1d0cd268..155f6f73 100644 --- a/docs/_static/css/custom.css +++ b/docs/_static/css/custom.css @@ -1,3 +1,3 @@ .logo { - font-family: monospace; + font-family: "Courier New", Courier, "Liberation Mono", "Anonymous Pro", monospace; } diff --git a/docs/conf.py b/docs/conf.py index 0c175180..668543ce 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -96,6 +96,7 @@ 'github_user': 'python273', 'github_repo': 'vk_api', 'github_banner': True, + 'github_type': 'star', 'show_related': False } diff --git a/docs/index.rst b/docs/index.rst index de4e863d..4a0eaae3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,9 +7,17 @@ vk_api – Python модуль для написания скриптов для `Установка через PIP `_: -.. code-block:: bash +.. code-block:: shell-session - $ pip install vk_api + $ pip install --user vk_api + +или + +.. code-block:: shell-session + + # pip install vk_api + +Примеры по использованию библиотеки доступны на `GitHub `_. .. toctree:: :maxdepth: 4 diff --git a/docs/jconfig.rst b/docs/jconfig.rst index 38d899ad..b93426ca 100644 --- a/docs/jconfig.rst +++ b/docs/jconfig.rst @@ -8,14 +8,14 @@ BaseConfig :members: Config (хранение в json файле) ---------------------------- +------------------------------ .. autoclass:: jconfig.jconfig.Config :members: :show-inheritance: MemoryConfig (хранение в памяти) ----------------------------- +-------------------------------- .. autoclass:: jconfig.memory.MemoryConfig :members: From bdf283a2d3f342b5029803d4460762186da98fd1 Mon Sep 17 00:00:00 2001 From: python273 Date: Sat, 14 Apr 2018 18:59:19 +0300 Subject: [PATCH 10/10] Update VkApi method names --- vk_api/vk_api.py | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/vk_api/vk_api.py b/vk_api/vk_api.py index c971e37f..f177056c 100644 --- a/vk_api/vk_api.py +++ b/vk_api/vk_api.py @@ -184,8 +184,8 @@ def _auth_cookies(self, reauth=False): self.storage.clear_section() - self.vk_login() - self.api_login() + self._vk_login() + self._api_login() return if not self.check_sid(): @@ -195,9 +195,9 @@ def _auth_cookies(self, reauth=False): ) ) - self.vk_login() + self._vk_login() else: - self.security_check() + self._pass_security_check() if not self._check_token(): self.logger.info( @@ -206,7 +206,7 @@ def _auth_cookies(self, reauth=False): ) ) - self.api_login() + self._api_login() else: self.logger.info('access_token from config is valid') @@ -220,14 +220,14 @@ def _auth_token(self, reauth=False): self.logger.info('Auth (API) forced') if self.check_sid(): - self.security_check() - self.api_login() + self._pass_security_check() + self._api_login() elif self.password: - self.vk_login() - self.api_login() + self._vk_login() + self._api_login() - def vk_login(self, captcha_sid=None, captcha_key=None): + def _vk_login(self, captcha_sid=None, captcha_key=None): """ Авторизация ВКонтакте с получением cookies remixsid :param captcha_sid: id капчи @@ -276,7 +276,7 @@ def vk_login(self, captcha_sid=None, captcha_key=None): self.logger.info('Captcha code is required') captcha_sid = search_re(RE_CAPTCHAID, response.text) - captcha = Captcha(self, captcha_sid, self.vk_login) + captcha = Captcha(self, captcha_sid, self._vk_login) return self.error_handlers[CAPTCHA_ERROR_CODE](captcha) @@ -284,7 +284,7 @@ def vk_login(self, captcha_sid=None, captcha_key=None): self.logger.info('Captcha code is required (recaptcha)') captcha_sid = str(random.random())[2:16] - captcha = Captcha(self, captcha_sid, self.vk_login) + captcha = Captcha(self, captcha_sid, self._vk_login) return self.error_handlers[CAPTCHA_ERROR_CODE](captcha) @@ -296,7 +296,7 @@ def vk_login(self, captcha_sid=None, captcha_key=None): response = self.http.get('https://vk.com/login?act=authcheck') - self.twofactor(response) + self._pass_twofactor(response) if self._sid: self.logger.info('Got remixsid') @@ -308,12 +308,12 @@ def vk_login(self, captcha_sid=None, captcha_key=None): 'Unknown error. Please send bugreport: https://vk.com/python273' ) - response = self.security_check(response) + response = self._pass_security_check(response) if 'act=blocked' in response.url: raise AccountBlocked('Account is blocked') - def twofactor(self, auth_response): + def _pass_twofactor(self, auth_response): """ Двухфакторная аутентификация :param auth_response: страница с приглашением к аутентификации @@ -337,11 +337,11 @@ def twofactor(self, auth_response): return self.http.get('https://vk.com/' + response_parsed[5]) elif response_parsed[4] == '8': # Incorrect code - return self.twofactor(auth_response) + return self._pass_twofactor(auth_response) raise TwoFactorError('Two factor authentication failed') - def security_check(self, response=None): + def _pass_security_check(self, response=None): """ Функция для обхода проверки безопасности (запрос номера телефона) :param response: ответ предыдущего запроса, если есть @@ -403,7 +403,7 @@ def check_sid(self): self.logger.info('remixsid is not valid') - def api_login(self): + def _api_login(self): """ Получение токена через Desktop приложение """ if not self._sid: