python/aiogram
1
0
Fork 0
mirror of https://github.com/aiogram/aiogram.git synced 2025-12-10 17:53:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Write docs and small fixes.

Browse source
This commit is contained in:
Alex Root Junior 2018-09-07 21:24:13 +03:00
parent 23fba99d93
commit 7a55c040ee
31 changed files with 306 additions and 458 deletions
Download patch file Download diff file Expand all files Collapse all files

9
docs/source/bot.rst
View file

@ -1,9 +0,0 @@
Bot object
==========
For detailed information about parameters read the official `Telegram Bot API reference <https://core.telegram.org/bots/api>`_
.. toctree::
bot/base
bot/extended

8
docs/source/bot/base.rst
View file

@ -1,8 +0,0 @@
BaseBot
=======
This class is the base class for bot. BaseBot implements only methods for interaction with Telegram Bot API.
.. autoclass:: aiogram.bot.base.BaseBot
:members:
:show-inheritance:

9
docs/source/bot/extended.rst
View file

@ -1,9 +0,0 @@
Bot object
==========
This is extended (and recommended for use) bot class based on BaseBot class.
You can use an instance of this bot in :obj:`aiogram.dispatcher.Dispatcher`
.. autoclass:: aiogram.bot.bot.Bot
:members:
:show-inheritance:

5
docs/source/contrib/contrib.rst
View file

@ -1,5 +0,0 @@
Contrib
=======
.. toctree::
storages

25
docs/source/contrib/storages.rst
View file

@ -1,25 +0,0 @@
Storages for FSM
================
You can create you own storage by extending :class:`aiogram.dispatcher.storage.BaseStorage` or use default storages:
Simple in-memory storage
------------------------
.. automodule:: aiogram.contrib.fsm_storage.memory
:members:
:show-inheritance:
Redis storage
-------------
.. automodule:: aiogram.contrib.fsm_storage.redis
:members:
:show-inheritance:
RethinkDB storage
-----------------
.. automodule:: aiogram.contrib.fsm_storage.rethinkdb
:members:
:show-inheritance:

4
docs/source/contribution.rst Normal file
View file

@ -0,0 +1,4 @@
Contribution
============
TODO

11
docs/source/dispatcher.rst
View file

@ -1,11 +0,0 @@
Dispatcher
==========
With parts of this package you can manage bot updates.
.. toctree::
dispatcher/main
dispatcher/storage
dispatcher/webhook
dispatcher/filters
dispatcher/handler

8
docs/source/dispatcher/filters.rst
View file

@ -1,8 +0,0 @@
Filters
-------
This module stores builtin filters for dispatcher.
.. automodule:: aiogram.dispatcher.filters
:members:
:show-inheritance:

6
docs/source/dispatcher/handler.rst
View file

@ -1,6 +0,0 @@
Handler class
-------------
.. automodule:: aiogram.dispatcher.handler
:members:
:show-inheritance:

4
docs/source/dispatcher/index.rst Normal file
View file

@ -0,0 +1,4 @@
Dispatcher
==========
TODO

6
docs/source/dispatcher/main.rst
View file

@ -1,6 +0,0 @@
Dispatcher class
----------------
.. automodule:: aiogram.dispatcher
:members:
:show-inheritance:

8
docs/source/dispatcher/storage.rst
View file

@ -1,8 +0,0 @@
Storages
--------
This module stores storage base for finite-state machine.
.. automodule:: aiogram.dispatcher.storage
:members:
:show-inheritance:

6
docs/source/dispatcher/webhook.rst
View file

@ -1,6 +0,0 @@
Webhook
-------
.. automodule:: aiogram.dispatcher.webhook
:members:
:show-inheritance:

4
docs/source/examples/echo_bot.rst Normal file
View file

@ -0,0 +1,4 @@
Echo bot
========
example

5
docs/source/examples/index.rst Normal file
View file

@ -0,0 +1,5 @@
Examples
========
.. toctree::
echo_bot

5
docs/source/features.rst
View file

@ -1,5 +0,0 @@
Features
========
.. toctree::
contrib/contrib

12
docs/source/index.rst
View file

@ -64,11 +64,13 @@ Contents
.. toctree::
install
quick_start
bot
dispatcher
types
features
migration
telegram/index
dispatcher/index
utils/index
examples/index
contribution
links
Indices and tables

10
docs/source/install.rst
View file

@ -15,6 +15,15 @@ From sources
$ cd aiogram
$ python setup.py install
or if you want to install development version (maybe unstable):
.. code-block:: bash
$ git clone https://github.com/aiogram/aiogram.git
$ cd aiogram
$ git checkout dev-2.x
$ python setup.py install
Recommendations
---------------
@ -30,7 +39,6 @@ You can speedup your bots by following next instructions:
$ pip install uvloop
- Use `ujson <https://github.com/esnme/ultrajson>`_ instead of default json module.
*UltraJSON* is an ultra fast JSON encoder and decoder written in pure C with bindings for Python 2.5+ and 3.

4
docs/source/links.rst Normal file
View file

@ -0,0 +1,4 @@
Links
=====
TODO

185
docs/source/migration.rst Normal file
View file

@ -0,0 +1,185 @@
==========================
Migration FAQ (1.4 -> 2.0)
==========================
This update make breaking changes in aiogram API and drop backward capability with previous versions of framework.
From this point aiogram supports only Python 3.7 and newer.
Changelog
=========
- Used contextvars instead of `aiogram.utils.context`;
- Implemented filters factory;
- Implemented new filters mechanism;
- Allowed to customize command prefix in CommandsFilter;
- Implemented mechanism of passing results from filters (as dicts) as kwargs in handlers (like fixtures in pytest);
- Implemented states group feature;
- Changed files uploading mechanism;
- Implemented I18n Middleware;
- Errors handlers now should accept only two arguments (current update and exception);
- Used `aiohttp_socks` instead of `aiosocksy` for Socks4/5 proxy;
- (**in process**) Implemented utils for Telegram Passport;
- (**in process**) Webhook security improvements;
- (**in process**) Updated examples.
Instructions
============
Contextvars
-----------
Context utility (`aiogram.utils.context`) now is removed due to new features of Python 3.7 and all subclasses of :obj:`aiogram.types.base.TelegramObject`, :obj:`aiogram.Bot` and :obj:`aiogram.Dispatcher` has `.get_current()` and `.set_current()` methods for getting/setting contextual instances of objects.
Example:
.. code-block:: python
async def my_handler(message: types.Message):
bot = Bot.get_current()
user = types.User.get_current()
...
Filters
-------
Custom filters
~~~~~~~~~~~~~~
Now `func` keyword argument can't be used for passing filters to the list of filters instead of that you can pass the filters as arguments:
.. code-block:: python
@dp.message_handler(lambda message: message.text == 'foo')
@dp.message_handler(types.ChatType.is_private, is_superuser)
async def ...
Filters factory
~~~~~~~~~~~~~~~
Also you can bind your own filters for using as keyword arguments:
.. code-block:: python
from aiogram.dispatcher.filters import BoundFilter
class MyFilter(BoundFilter):
key = 'is_admin'
async def check(self, message: types.Message):
member = await bot.get_chat_member(message.chat.id, message.from_user.id)
return member.is_admin()
dp.filters_factory.bind(MyFilter)
@dp.message_handler(is_admin=True)
async def ...
Customize commands prefix
~~~~~~~~~~~~~~~~~~~~~~~~~
Commands prefix can be changed by following one of two available methods:
.. code-block:: python
@dp.message_handler(commands=['admin'], commands_prefix='!/')
@dp.message_handler(Command('admin', prefixes='!/'))
async def ...
Passing data from filters as keyword arguments to the handlers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can pass any data from any filter to the handler by returning :obj:`dict`
If any key from the received dictionary not in the handler specification the key will be skipped and and will be unavailable from the handler
.. code-block:: python
async def my_filter(message: types.Message):
# do something here
return {'foo': 'foo', 'bar': 42}
@dp.message_handler(my_filter)
async def my_message_handler(message: types.Message, bar: int):
await message.reply(f'bar = {bar}')
Other
~~~~~
Filters can also be used as logical expressions:
.. code-block:: python
Text(equals='foo') | Text(endswith='Bar') | ~Text(contains='spam')
States group
------------
You can use States objects and States groups instead of string names of the states.
String values is still also be available.
Writing states group:
.. code-block:: python
from aiogram.dispatcher.filters.state import State, StatesGroup
class UserForm(StatesGroup):
name = State() # Will be represented in storage as 'Form:name'
age = State() # Will be represented in storage as 'Form:age'
gender = State() # Will be represented in storage as 'Form:gender'
After that you can use states as `UserForm.name` and etc.
File uploading mechanism
------------------------
Fixed uploading files. Removed `BaseBot.send_file` method. This allowed to send the `thumb` field.
I18n Middleware
---------------
You can internalize your bot by following next steps:
First usage
~~~~~~~~~~~
1. Extract texts
.. code-block:: bash
pybabel extract i18n_example.py -o locales/mybot.pot
2. Create `*.po` files. For e.g. create `en`, `ru`, `uk` locales.
3. Translate texts
4. Compile translations
.. code-block:: bash
pybabel compile -d locales -D mybot
Updating translations
~~~~~~~~~~~~~~~~~~~~~
When you change the code of your bot you need to update `po` & `mo` files:
1. Regenerate pot file:
.. code-block:: bash
pybabel extract i18n_example.py -o locales/mybot.pot
2. Update po files
.. code-block:: bash
pybabel update -d locales -D mybot -i locales/mybot.pot
3. Update your translations
4. Compile `mo` files
.. code-block:: bash
pybabel compile -d locales -D mybot
Error handlers
--------------
Previously errors handlers had to have three arguments `dispatcher`, `update` and `exception` now `dispatcher` argument is removed and will no longer be passed to the error handlers.

23
docs/source/quick_start.rst
View file

@ -8,9 +8,7 @@ At first you have to import all necessary modules
.. code-block:: python3
from aiogram import Bot, types
from aiogram.dispatcher import Dispatcher
from aiogram.utils import executor
from aiogram import Bot, Dispatcher, executor, types
Then you have to initialize bot and dispatcher instances.
Bot token you can get from `@BotFather <https://t.me/BotFather>`_
@ -29,6 +27,14 @@ Next step: interaction with bots starts with one command. Register your first co
async def send_welcome(message: types.Message):
await message.reply("Hi!\nI'm EchoBot!\nPowered by aiogram.")
If you want to handle all messages in the chat simply add handler without filters:
.. code-block:: python
@dp.message_handler()
async def echo(message: types.Message):
await bot.send_message(message.chat.id, message.text)
Last step: run long polling.
.. code-block:: python3
@ -41,16 +47,21 @@ Summary
.. code-block:: python3
from aiogram import Bot, types
from aiogram.dispatcher import Dispatcher
from aiogram.utils import executor
from aiogram import Bot, Dispatcher, executor, types
bot = Bot(token='BOT TOKEN HERE')
dp = Dispatcher(bot)
@dp.message_handler(commands=['start', 'help'])
async def send_welcome(message: types.Message):
await message.reply("Hi!\nI'm EchoBot!\nPowered by aiogram.")
@dp.message_handler()
async def echo(message: types.Message):
await bot.send_message(message.chat.id, message.text)
if __name__ == '__main__':
executor.start_polling(dp)

25
docs/source/telegram/bot.rst Normal file
View file

@ -0,0 +1,25 @@
Bot object
==========
Low level API
-------------
Subclass of this class used only for splitting network interface from all of API methods.
.. autoclass:: aiogram.bot.base.BaseBot
:members:
:show-inheritance:
Telegram Bot
------------
This class based on :obj:`aiogram.bot.base.BaseBot`
.. autoclass:: aiogram.bot.bot.Bot
:members:
:show-inheritance:
API Helpers
-----------
.. automodule:: aiogram.bot.api
:members:
:show-inheritance:

7
docs/source/telegram/index.rst Normal file
View file

@ -0,0 +1,7 @@
Telegram
========
.. toctree::
bot
types/index

318
docs/source/types.rst
View file

@ -1,318 +0,0 @@
Data types
==========
Bases
-----
.. automodule:: aiogram.types.base
:members:
:show-inheritance:
Update
------
:class:`aiogram.types.Update`
.. automodule:: aiogram.types.update
:members:
:show-inheritance:
WebhookInfo
-----------
:class:`aiogram.types.WebhookInfo`
.. automodule:: aiogram.types.webhook_info
:members:
:show-inheritance:
User
----
:class:`aiogram.types.User`
.. automodule:: aiogram.types.user
:members:
:show-inheritance:
Chat
----
:class:`aiogram.types.Chat`
.. automodule:: aiogram.types.chat
:members:
:show-inheritance:
Message
-------
:class:`aiogram.types.Message`
.. automodule:: aiogram.types.message
:members:
:show-inheritance:
MessageEntity
-------------
:class:`aiogram.types.MessageEntity`
.. automodule:: aiogram.types.message_entity
:members:
:show-inheritance:
PhotoSize
---------
:class:`aiogram.types.PhotoSize`
.. automodule:: aiogram.types.photo_size
:members:
:show-inheritance:
Audio
-----
:class:`aiogram.types.Audio`
.. automodule:: aiogram.types.audio
:members:
:show-inheritance:
Document
--------
:class:`aiogram.types.Document`
.. automodule:: aiogram.types.document
:members:
:show-inheritance:
Video
-----
:class:`aiogram.types.Video`
.. automodule:: aiogram.types.video
:members:
:show-inheritance:
Voice
-----
:class:`aiogram.types.Voice`
.. automodule:: aiogram.types.voice
:members:
:show-inheritance:
VideoNote
---------
:class:`aiogram.types.VideoNote`
.. automodule:: aiogram.types.video_note
:members:
:show-inheritance:
Contact
-------
:class:`aiogram.types.Contact`
.. automodule:: aiogram.types.contact
:members:
:show-inheritance:
Location
--------
:class:`aiogram.types.Location`
.. automodule:: aiogram.types.location
:members:
:show-inheritance:
Venue
-----
:class:`aiogram.types.Venue`
.. automodule:: aiogram.types.venue
:members:
:show-inheritance:
UserProfilePhotos
-----------------
:class:`aiogram.types.UserProfilePhotos`
.. automodule:: aiogram.types.user_profile_photos
:members:
:show-inheritance:
File
----
:class:`aiogram.types.File`
.. automodule:: aiogram.types.file
:members:
:show-inheritance:
ReplyKeyboardMarkup & KeyboardButton & ReplyKeyboardRemove
----------------------------------------------------------
:class:`aiogram.types.ReplyKeyboardMarkup`
:class:`aiogram.types.KeyboardButton`
:class:`aiogram.types.ReplyKeyboardRemove`
.. automodule:: aiogram.types.reply_keyboard
:members:
:show-inheritance:
InlineKeyboardMarkup & InlineKeyboardButton
-------------------------------------------
:class:`aiogram.types.InlineKeyboardMarkup`
:class:`aiogram.types.InlineKeyboardButton`
.. automodule:: aiogram.types.inline_keyboard
:members:
:show-inheritance:
CallbackQuery
-------------
:class:`aiogram.types.CallbackQuery`
.. automodule:: aiogram.types.callback_query
:members:
:show-inheritance:
ForceReply
----------
:class:`aiogram.types.ForceReply`
.. automodule:: aiogram.types.force_reply
:members:
:show-inheritance:
ChatPhoto
---------
:class:`aiogram.types.ChatPhoto`
.. automodule:: aiogram.types.chat_photo
:members:
:show-inheritance:
ChatMember
----------
:class:`aiogram.types.ChatMember`
.. automodule:: aiogram.types.chat_member
:members:
:show-inheritance:
ResponseParameters
------------------
:class:`aiogram.types.ResponseParameters`
.. automodule:: aiogram.types.response_parameters
:members:
:show-inheritance:
InputMedia
----------
:class:`aiogram.types.InputMediaPhoto`
:class:`aiogram.types.InputMediaVideo`
:class:`aiogram.types.MediaGroup`
.. automodule:: aiogram.types.input_media
:members:
:show-inheritance:
Sticker
-------
:class:`aiogram.types.Sticker`
.. automodule:: aiogram.types.sticker
:members:
:show-inheritance:
StickerSet
-----------
:class:`aiogram.types.StickerSet`
.. automodule:: aiogram.types.sticker_set
:members:
:show-inheritance:
MaskPosition
------------
:class:`aiogram.types.MaskPosition`
.. automodule:: aiogram.types.mask_position
:members:
:show-inheritance:
Inline mode objects
-------------------
.. automodule:: aiogram.types.inline_query
:members:
:show-inheritance:
.. automodule:: aiogram.types.chosen_inline_result
:members:
:show-inheritance:
.. automodule:: aiogram.types.inline_query_result
:members:
:show-inheritance:
Payments
--------
.. automodule:: aiogram.types.labeled_price
:members:
:show-inheritance:
.. automodule:: aiogram.types.invoice
:members:
:show-inheritance:
.. automodule:: aiogram.types.shipping_address
:members:
:show-inheritance:
.. automodule:: aiogram.types.order_info
:members:
:show-inheritance:
.. automodule:: aiogram.types.shipping_option
:members:
:show-inheritance:
.. automodule:: aiogram.types.successful_payment
:members:
:show-inheritance:
.. automodule:: aiogram.types.shipping_query
:members:
:show-inheritance:
.. automodule:: aiogram.types.pre_checkout_query
:members:
:show-inheritance:
Games
-----
.. automodule:: aiogram.types.game
:members:
:show-inheritance:
.. automodule:: aiogram.types.animation
:members:
:show-inheritance:
.. automodule:: aiogram.types.game_high_score
:members:
:show-inheritance:
InputFile interface
-------------------
:class:`aiogram.types.InputFile`
.. automodule:: aiogram.types.input_file
:members:
:show-inheritance:

4
docs/source/utils/index.rst Normal file
View file

@ -0,0 +1,4 @@
Utils
=====
TODO