Aiogram

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

Bugfixes
--------

- Replaced :code:`datetime.datetime` with `DateTime` type wrapper across types to make dumped JSONs object
more compatible with data that is sent by Telegram.
`1277 <https://github.com/aiogram/aiogram/issues/1277>`_
- Fixed magic :code:`.as_(...)` operation for values that can be interpreted as `False` (e.g. `0`).
`1281 <https://github.com/aiogram/aiogram/issues/1281>`_
- Italic markdown from utils now uses correct decorators
`1282 <https://github.com/aiogram/aiogram/issues/1282>`_
- Fixed method :code:`Message.send_copy` for stickers.
`1284 <https://github.com/aiogram/aiogram/issues/1284>`_
- Fixed :code:`Message.send_copy` method, which was not working properly with stories, so not you can copy stories too (forwards messages).
`1286 <https://github.com/aiogram/aiogram/issues/1286>`_
- Fixed error overlapping when validation error is caused by remove_unset root validator in base types and methods.
`1290 <https://github.com/aiogram/aiogram/issues/1290>`_

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

Bugfixes
--------

- Fixed missing message content types (:code:`ContentType.USER_SHARED`, :code:`ContentType.CHAT_SHARED`)
`1252 <https://github.com/aiogram/aiogram/issues/1252>`_
- Fixed nested hashtag, cashtag and email message entities not being parsed correctly when these entities are inside another entity.
`1259 <https://github.com/aiogram/aiogram/issues/1259>`_
- Moved global filters check placement into router to add chance to pass context from global filters
into handlers in the same way as it possible in other places
`1266 <https://github.com/aiogram/aiogram/issues/1266>`_


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

- Added error handling example `examples/error_handling.py`
`1099 <https://github.com/aiogram/aiogram/issues/1099>`_
- Added a few words about skipping pending updates
`1251 <https://github.com/aiogram/aiogram/issues/1251>`_
- Added a section on Dependency Injection technology
`1253 <https://github.com/aiogram/aiogram/issues/1253>`_
- This update includes the addition of a multi-file bot example to the repository.
`1254 <https://github.com/aiogram/aiogram/issues/1254>`_
- Refactored examples code to use aiogram enumerations and enhanced chat messages with markdown
beautification's for a more user-friendly display.
`1256 <https://github.com/aiogram/aiogram/issues/1256>`_
- Supplemented "Finite State Machine" section in Migration FAQ
`1264 <https://github.com/aiogram/aiogram/issues/1264>`_
- Removed extra param in docstring of TelegramEventObserver's filter method
and fixed typo in I18n documentation.
`1268 <https://github.com/aiogram/aiogram/issues/1268>`_


Misc
----

- Enhanced the warning message in dispatcher to include a JSON dump of the update when update type is not known.
`1269 <https://github.com/aiogram/aiogram/issues/1269>`_
- Added support for `Bot API 6.8 <https://core.telegram.org/bots/api-changelog#august-18-2023>`_
`1275 <https://github.com/aiogram/aiogram/issues/1275>`_

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

Features
--------

- Added Currency enum.
You can use it like this:

.. code-block:: python

from aiogram.enums import Currency

await bot.send_invoice(
...,
currency=Currency.USD,
...
)
`1194 <https://github.com/aiogram/aiogram/issues/1194>`_
- Updated keyboard builders with new methods for integrating buttons and keyboard creation more seamlessly.
Added functionality to create buttons from existing markup and attach another builder.
This improvement aims to make the keyboard building process more user-friendly and flexible.
`1236 <https://github.com/aiogram/aiogram/issues/1236>`_
- Added support for message_thread_id in ChatActionSender
`1249 <https://github.com/aiogram/aiogram/issues/1249>`_


Bugfixes
--------

- Fixed polling startup when "bot" key is passed manually into dispatcher workflow data
`1242 <https://github.com/aiogram/aiogram/issues/1242>`_
- Added codegen configuration for lost shortcuts:

- ShippingQuery.answer
- PreCheckoutQuery.answer
- Message.delete_reply_markup
`1244 <https://github.com/aiogram/aiogram/issues/1244>`_


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

- Added documentation for webhook and polling modes.
`1241 <https://github.com/aiogram/aiogram/issues/1241>`_


Misc
----

- Reworked InputFile reading, removed :code:`__aiter__` method, added `bot: Bot` argument to
the :code:`.read(...)` method, so, from now URLInputFile can be used without specifying
bot instance.
`1238 <https://github.com/aiogram/aiogram/issues/1238>`_
- Code-generated :code:`__init__` typehints in types and methods to make IDE happy without additional pydantic plugin
`1245 <https://github.com/aiogram/aiogram/issues/1245>`_

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

Features
--------

- Added new shortcuts for :class:`aiogram.types.chat_member_updated.ChatMemberUpdated`
to send message to chat that member joined/left.
`1234 <https://github.com/aiogram/aiogram/issues/1234>`_
- Added new shortcuts for :class:`aiogram.types.chat_join_request.ChatJoinRequest`
to make easier access to sending messages to users who wants to join to chat.
`1235 <https://github.com/aiogram/aiogram/issues/1235>`_


Bugfixes
--------

- Fixed bot assignment in the :code:`Message.send_copy` shortcut
`1232 <https://github.com/aiogram/aiogram/issues/1232>`_
- Added model validation to remove UNSET before field validation.
This change was necessary to correctly handle parse_mode where 'UNSET' is used as a sentinel value.
Without the removal of 'UNSET', it would create issues when passed to model initialization from Bot.method_name.
'UNSET' was also added to typing.
`1233 <https://github.com/aiogram/aiogram/issues/1233>`_
- Updated pydantic to 2.1 with few bugfixes


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

- Improved docs, added basic migration guide (will be expanded later)
`1143 <https://github.com/aiogram/aiogram/issues/1143>`_


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

- Removed the use of the context instance (Bot.get_current) from all placements that were used previously.
This is to avoid the use of the context instance in the wrong place.
`1230 <https://github.com/aiogram/aiogram/issues/1230>`_

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

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>`_