Aiogram

=====================

Features
--------

- Added possibility to use custom events in routers (If router does not support custom event it does not break and passes it to included routers).
`1147 <https://github.com/aiogram/aiogram/issues/1147>`_
- Added support for FSM in Forum topics.

The strategy can be changed in dispatcher:

.. code-block:: python

from aiogram.fsm.strategy import FSMStrategy
...
dispatcher = Dispatcher(
fsm_strategy=FSMStrategy.USER_IN_TOPIC,
storage=..., Any persistent storage
)

.. note::

If you have implemented you own storages you should extend record key generation
with new one attribute - :code:`thread_id`
`1161 <https://github.com/aiogram/aiogram/issues/1161>`_
- Improved CallbackData serialization.

- Minimized UUID (hex without dashes)
- Replaced bool values with int (true=1, false=0)
`1163 <https://github.com/aiogram/aiogram/issues/1163>`_
- Added a tool to make text formatting flexible and easy.
More details on the :ref:`corresponding documentation page <formatting-tool>`
`1172 <https://github.com/aiogram/aiogram/issues/1172>`_
- Added :code:`X-Telegram-Bot-Api-Secret-Token` header check
`1173 <https://github.com/aiogram/aiogram/issues/1173>`_
- Made :code:`allowed_updates` list to revolve automatically in start_polling method if not set explicitly.
`1178 <https://github.com/aiogram/aiogram/issues/1178>`_
- Added possibility to pass custom headers to :class:`URLInputFile` object
`1191 <https://github.com/aiogram/aiogram/issues/1191>`_


Bugfixes
--------

- Change type of result in InlineQueryResult enum for :code:`InlineQueryResultCachedMpeg4Gif`
and :code:`InlineQueryResultMpeg4Gif` to more correct according to documentation.

Change regexp for entities parsing to more correct (:code:`InlineQueryResultType.yml`).
`1146 <https://github.com/aiogram/aiogram/issues/1146>`_
- Fixed signature of startup/shutdown events to include the :code:`**dispatcher.workflow_data` as the handler arguments.
`1155 <https://github.com/aiogram/aiogram/issues/1155>`_
- Added missing :code:`FORUM_TOPIC_EDITED` value to content_type property
`1160 <https://github.com/aiogram/aiogram/issues/1160>`_
- Fixed compatibility with Python 3.8-3.9 (from previous release)
`1162 <https://github.com/aiogram/aiogram/issues/1162>`_
- Fixed the markdown spoiler parser.
`1176 <https://github.com/aiogram/aiogram/issues/1176>`_
- Fixed workflow data propagation
`1196 <https://github.com/aiogram/aiogram/issues/1196>`_
- Fixed the serialization error associated with nested subtypes
like InputMedia, ChatMember, etc.

The previously generated code resulted in an invalid schema under pydantic v2,
which has stricter type parsing.
Hence, subtypes without the specification of all subtype unions were generating
an empty object. This has been rectified now.
`1213 <https://github.com/aiogram/aiogram/issues/1213>`_


Improved Documentation
----------------------

- Changed small grammar typos for :code:`upload_file`
`1133 <https://github.com/aiogram/aiogram/issues/1133>`_


Deprecations and Removals
-------------------------

- Removed text filter in due to is planned to remove this filter few versions ago.

Use :code:`F.text` instead
`1170 <https://github.com/aiogram/aiogram/issues/1170>`_


Misc
----

- Added full support of `Bot API 6.6 <https://core.telegram.org/bots/api-changelog#march-9-2023>`_

.. danger::

Note that this issue has breaking changes described in the Bot API changelog,
this changes is not breaking in the API but breaking inside aiogram because
Beta stage is not finished.
`1139 <https://github.com/aiogram/aiogram/issues/1139>`_
- Added full support of `Bot API 6.7 <https://core.telegram.org/bots/api-changelog#april-21-2023>`_

.. warning::

Note that arguments *switch_pm_parameter* and *switch_pm_text* was deprecated
and should be changed to *button* argument as described in API docs.
`1168 <https://github.com/aiogram/aiogram/issues/1168>`_
- Updated `Pydantic to V2 <https://docs.pydantic.dev/2.0/migration/>`_

.. warning::

Be careful, not all libraries is already updated to using V2
`1202 <https://github.com/aiogram/aiogram/issues/1202>`_
- Added global defaults :code:`disable_web_page_preview` and :code:`protect_content` in addition to :code:`parse_mode` to the Bot instance,
reworked internal request builder mechanism.
`1142 <https://github.com/aiogram/aiogram/issues/1142>`_
- Removed bot parameters from storages
`1144 <https://github.com/aiogram/aiogram/issues/1144>`_

- Replaced ContextVar's with a new feature called `Validation Context <https://docs.pydantic.dev/latest/usage/validators/#validation-context>`_
in Pydantic to improve the clarity, usability, and versatility of handling the Bot instance within method shortcuts.

.. danger::

**Breaking**: The 'bot' argument now is required in `URLInputFile`
`1210 <https://github.com/aiogram/aiogram/issues/1210>`_
- Updated magic-filter with new features

- Added hint for :code:`len(F)` error
- Added not in operation
`1221 <https://github.com/aiogram/aiogram/issues/1221>`_

=====================

.. warning::

Note that this version has incompatibility with Python 3.8-3.9 in case when you create an instance of Dispatcher outside of the any coroutine.

Sorry for the inconvenience, it will be fixed in the next version.

This code will not work:

.. code-block:: python

dp = Dispatcher()

def main():
...
dp.run_polling(...)

main()

But if you change it like this it should works as well:

.. code-block:: python

router = Router()

async def main():
dp = Dispatcher()
dp.include_router(router)
...
dp.start_polling(...)

asyncio.run(main())


Features
--------

- Added missing shortcuts, new enums, reworked old stuff

**Breaking**
All previously added enums is re-generated in new place - `aiogram.enums` instead of `aiogram.types`

**Added enums:** :class:`aiogram.enums.bot_command_scope_type.BotCommandScopeType`,
:class:`aiogram.enums.chat_action.ChatAction`,
:class:`aiogram.enums.chat_member_status.ChatMemberStatus`,
:class:`aiogram.enums.chat_type.ChatType`,
:class:`aiogram.enums.content_type.ContentType`,
:class:`aiogram.enums.dice_emoji.DiceEmoji`,
:class:`aiogram.enums.inline_query_result_type.InlineQueryResultType`,
:class:`aiogram.enums.input_media_type.InputMediaType`,
:class:`aiogram.enums.mask_position_point.MaskPositionPoint`,
:class:`aiogram.enums.menu_button_type.MenuButtonType`,
:class:`aiogram.enums.message_entity_type.MessageEntityType`,
:class:`aiogram.enums.parse_mode.ParseMode`,
:class:`aiogram.enums.poll_type.PollType`,
:class:`aiogram.enums.sticker_type.StickerType`,
:class:`aiogram.enums.topic_icon_color.TopicIconColor`,
:class:`aiogram.enums.update_type.UpdateType`,

**Added shortcuts**:

- *Chat* :meth:`aiogram.types.chat.Chat.get_administrators`,
:meth:`aiogram.types.chat.Chat.delete_message`,
:meth:`aiogram.types.chat.Chat.revoke_invite_link`,
:meth:`aiogram.types.chat.Chat.edit_invite_link`,
:meth:`aiogram.types.chat.Chat.create_invite_link`,
:meth:`aiogram.types.chat.Chat.export_invite_link`,
:meth:`aiogram.types.chat.Chat.do`,
:meth:`aiogram.types.chat.Chat.delete_sticker_set`,
:meth:`aiogram.types.chat.Chat.set_sticker_set`,
:meth:`aiogram.types.chat.Chat.get_member`,
:meth:`aiogram.types.chat.Chat.get_member_count`,
:meth:`aiogram.types.chat.Chat.leave`,
:meth:`aiogram.types.chat.Chat.unpin_all_messages`,
:meth:`aiogram.types.chat.Chat.unpin_message`,
:meth:`aiogram.types.chat.Chat.pin_message`,
:meth:`aiogram.types.chat.Chat.set_administrator_custom_title`,
:meth:`aiogram.types.chat.Chat.set_permissions`,
:meth:`aiogram.types.chat.Chat.promote`,
:meth:`aiogram.types.chat.Chat.restrict`,
:meth:`aiogram.types.chat.Chat.unban`,
:meth:`aiogram.types.chat.Chat.ban`,
:meth:`aiogram.types.chat.Chat.set_description`,
:meth:`aiogram.types.chat.Chat.set_title`,
:meth:`aiogram.types.chat.Chat.delete_photo`,
:meth:`aiogram.types.chat.Chat.set_photo`,
- *Sticker*: :meth:`aiogram.types.sticker.Sticker.set_position_in_set`,
:meth:`aiogram.types.sticker.Sticker.delete_from_set`,
- *User*: :meth:`aiogram.types.user.User.get_profile_photos`
`952 <https://github.com/aiogram/aiogram/issues/952>`_
- Added :ref:`callback answer <callback-answer-util>` feature
`1091 <https://github.com/aiogram/aiogram/issues/1091>`_
- Added a method that allows you to compactly register routers
`1117 <https://github.com/aiogram/aiogram/issues/1117>`_


Bugfixes
--------

- Check status code when downloading file
`816 <https://github.com/aiogram/aiogram/issues/816>`_
- Fixed `ignore_case` parameter in :obj:`aiogram.filters.command.Command` filter
`1106 <https://github.com/aiogram/aiogram/issues/1106>`_


Misc
----

- Added integration with new code-generator named `Butcher <https://github.com/aiogram/butcher>`_
`1069 <https://github.com/aiogram/aiogram/issues/1069>`_
- Added full support of `Bot API 6.4 <https://core.telegram.org/bots/api-changelog#december-30-2022>`_
`1088 <https://github.com/aiogram/aiogram/issues/1088>`_
- Updated package metadata, moved build internals from Poetry to Hatch, added contributing guides.
`1095 <https://github.com/aiogram/aiogram/issues/1095>`_
- Added full support of `Bot API 6.5 <https://core.telegram.org/bots/api-changelog#february-3-2023>`_

.. danger::

Note that :obj:`aiogram.types.chat_permissions.ChatPermissions` is updated without
backward compatibility, so now this object has no :code:`can_send_media_messages` attribute
`1112 <https://github.com/aiogram/aiogram/issues/1112>`_
- Replaced error :code:`TypeError: TelegramEventObserver.__call__() got an unexpected keyword argument '<name>'`
with a more understandable one for developers and with a link to the documentation.
`1114 <https://github.com/aiogram/aiogram/issues/1114>`_
- Added possibility to reply into webhook with files
`1120 <https://github.com/aiogram/aiogram/issues/1120>`_
- Reworked graceful shutdown. Added method to stop polling.
Now polling started from dispatcher can be stopped by signals gracefully without errors (on Linux and Mac).
`1124 <https://github.com/aiogram/aiogram/issues/1124>`_

=====================

Features
--------

- (again) Added possibility to combine filters with an *and*/*or* operations.

Read more in ":ref:`Combining filters <combining-filters>`" documentation section
`1018 <https://github.com/aiogram/aiogram/issues/1018>`_
- Added following methods to ``Message`` class:

- :code:`Message.forward(...)`
- :code:`Message.edit_media(...)`
- :code:`Message.edit_live_location(...)`
- :code:`Message.stop_live_location(...)`
- :code:`Message.pin(...)`
- :code:`Message.unpin()`
`1030 <https://github.com/aiogram/aiogram/issues/1030>`_
- Added following methods to :code:`User` class:

- :code:`User.mention_markdown(...)`
- :code:`User.mention_html(...)`
`1049 <https://github.com/aiogram/aiogram/issues/1049>`_
- Added full support of `Bot API 6.3 <https://core.telegram.org/bots/api-changelog#november-5-2022>`_
`1057 <https://github.com/aiogram/aiogram/issues/1057>`_


Bugfixes
--------

- Fixed :code:`Message.send_invoice` and :code:`Message.reply_invoice`, added missing arguments
`1047 <https://github.com/aiogram/aiogram/issues/1047>`_
- Fixed copy and forward in:

- :code:`Message.answer(...)`
- :code:`Message.copy_to(...)`
`1064 <https://github.com/aiogram/aiogram/issues/1064>`_


Improved Documentation
----------------------

- Fixed UA translations in index.po
`1017 <https://github.com/aiogram/aiogram/issues/1017>`_
- Fix typehints for :code:`Message`, :code:`reply_media_group` and :code:`answer_media_group` methods
`1029 <https://github.com/aiogram/aiogram/issues/1029>`_
- Removed an old now non-working feature
`1060 <https://github.com/aiogram/aiogram/issues/1060>`_


Misc
----

- Enabled testing on Python 3.11
`1044 <https://github.com/aiogram/aiogram/issues/1044>`_
- Added a mandatory dependency :code:`certifi` in due to in some cases on systems that doesn't have updated ca-certificates the requests to Bot API fails with reason :code:`[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain`
`1066 <https://github.com/aiogram/aiogram/issues/1066>`_

=====================

Features
--------

- Add PyPy support and run tests under PyPy
`985 <https://github.com/aiogram/aiogram/issues/985>`_
- Added message text to aiogram exceptions representation
`988 <https://github.com/aiogram/aiogram/issues/988>`_
- Added warning about using magic filter from `magic_filter` instead of `aiogram`'s ones.
Is recommended to use `from aiogram import F` instead of `from magic_filter import F`
`990 <https://github.com/aiogram/aiogram/issues/990>`_
- Added more detailed error when server response can't be deserialized. This feature will help to debug unexpected responses from the Server
`1014 <https://github.com/aiogram/aiogram/issues/1014>`_


Bugfixes
--------

- Reworked error event, introduced :class:`aiogram.types.error_event.ErrorEvent` object.
`898 <https://github.com/aiogram/aiogram/issues/898>`_
- Fixed escaping markdown in `aiogram.utils.markdown` module
`903 <https://github.com/aiogram/aiogram/issues/903>`_
- Fixed polling crash when Telegram Bot API raises HTTP 429 status-code.
`995 <https://github.com/aiogram/aiogram/issues/995>`_
- Fixed empty mention in command parsing, now it will be None instead of an empty string
`1013 <https://github.com/aiogram/aiogram/issues/1013>`_


Improved Documentation
----------------------

- Initialized Docs translation (added Ukrainian language)
`925 <https://github.com/aiogram/aiogram/issues/925>`_


Deprecations and Removals
-------------------------

- Removed filters factory as described in corresponding issue.
`942 <https://github.com/aiogram/aiogram/issues/942>`_


Misc
----

- Now Router/Dispatcher accepts only keyword arguments.
`982 <https://github.com/aiogram/aiogram/issues/982>`_

=====================

Features
--------

- Add class helper ChatAction for constants that Telegram BotAPI uses in sendChatAction request.
In my opinion, this will help users and will also improve compatibility with 2.x version
where similar class was called "ChatActions".
`803 <https://github.com/aiogram/aiogram/issues/803>`_
- Added possibility to combine filters or invert result

Example:

.. code-block:: python

Text(text="demo") | Command(commands=["demo"])
MyFilter() & AnotherFilter()
~StateFilter(state='my-state')

`894 <https://github.com/aiogram/aiogram/issues/894>`_
- Fixed type hints for redis TTL params.
`922 <https://github.com/aiogram/aiogram/issues/922>`_
- Added `full_name` shortcut for `Chat` object
`929 <https://github.com/aiogram/aiogram/issues/929>`_


Bugfixes
--------

- Fixed false-positive coercing of Union types in API methods
`901 <https://github.com/aiogram/aiogram/issues/901>`_
- Added 3 missing content types:

* proximity_alert_triggered
* supergroup_chat_created
* channel_chat_created
`906 <https://github.com/aiogram/aiogram/issues/906>`_
- Fixed the ability to compare the state, now comparison to copy of the state will return `True`.
`927 <https://github.com/aiogram/aiogram/issues/927>`_
- Fixed default lock kwargs in RedisEventIsolation.
`972 <https://github.com/aiogram/aiogram/issues/972>`_


Misc
----

- Restrict including routers with strings
`896 <https://github.com/aiogram/aiogram/issues/896>`_
- Changed CommandPatterType to CommandPatternType in `aiogram/dispatcher/filters/command.py`
`907 <https://github.com/aiogram/aiogram/issues/907>`_
- Added full support of `Bot API 6.1 <https://core.telegram.org/bots/api-changelog#june-20-2022>`_
`936 <https://github.com/aiogram/aiogram/issues/936>`_
- **Breaking!** More flat project structure

These packages was moved, imports in your code should be fixed:

- :code:`aiogram.dispatcher.filters` -> :code:`aiogram.filters`
- :code:`aiogram.dispatcher.fsm` -> :code:`aiogram.fsm`
- :code:`aiogram.dispatcher.handler` -> :code:`aiogram.handler`
- :code:`aiogram.dispatcher.webhook` -> :code:`aiogram.webhook`
- :code:`aiogram.dispatcher.flags/*` -> :code:`aiogram.dispatcher.flags` (single module instead of package)
`938 <https://github.com/aiogram/aiogram/issues/938>`_
- Removed deprecated :code:`router.<event>_handler` and :code:`router.register_<event>_handler` methods.
`941 <https://github.com/aiogram/aiogram/issues/941>`_
- Deprecated filters factory. It will be removed in next Beta (3.0b5)
`942 <https://github.com/aiogram/aiogram/issues/942>`_
- `MessageEntity` method `get_text` was removed and `extract` was renamed to `extract_from`
`944 <https://github.com/aiogram/aiogram/issues/944>`_
- Added full support of `Bot API 6.2 <https://core.telegram.org/bots/api-changelog#august-12-2022>`_
`975 <https://github.com/aiogram/aiogram/issues/975>`_

=====================

Features
--------

- Added possibility to get command magic result as handler argument
`889 <https://github.com/aiogram/aiogram/issues/889>`_
- Added full support of `Telegram Bot API 6.0 <https://core.telegram.org/bots/api-changelog#april-16-2022>`_
`890 <https://github.com/aiogram/aiogram/issues/890>`_


Bugfixes
--------

- Fixed I18n lazy-proxy. Disabled caching.
`839 <https://github.com/aiogram/aiogram/issues/839>`_
- Added parsing of spoiler message entity
`865 <https://github.com/aiogram/aiogram/issues/865>`_
- Fixed default `parse_mode` for `Message.copy_to()` method.
`876 <https://github.com/aiogram/aiogram/issues/876>`_
- Fixed CallbackData factory parsing IntEnum's
`885 <https://github.com/aiogram/aiogram/issues/885>`_


Misc
----

- Added automated check that pull-request adds a changes description to **CHANGES** directory
`873 <https://github.com/aiogram/aiogram/issues/873>`_
- Changed :code:`Message.html_text` and :code:`Message.md_text` attributes behaviour when message has no text.
The empty string will be used instead of raising error.
`874 <https://github.com/aiogram/aiogram/issues/874>`_
- Used `redis-py` instead of `aioredis` package in due to this packages was merged into single one
`882 <https://github.com/aiogram/aiogram/issues/882>`_
- Solved common naming problem with middlewares that confusing too much developers
- now you can't see the `middleware` and `middlewares` attributes at the same point
because this functionality encapsulated to special interface.
`883 <https://github.com/aiogram/aiogram/issues/883>`_