Merge branch 'dev-3.x'

docs/api/methods/edit_message_checklist.rst

@@ -0,0 +1,45 @@
+####################
+editMessageChecklist
+####################
+
+Returns: :obj:`Message`
+
+.. automodule:: aiogram.methods.edit_message_checklist
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+    :exclude-members: model_config,model_fields
+
+
+Usage
+=====
+
+As bot method
+-------------
+
+.. code-block::
+
+    result: Message = await bot.edit_message_checklist(...)
+
+
+Method as object
+----------------
+
+Imports:
+
+- :code:`from aiogram.methods.edit_message_checklist import EditMessageChecklist`
+- alias: :code:`from aiogram.methods import EditMessageChecklist`
+
+With specific bot
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    result: Message = await bot(EditMessageChecklist(...))
+
+As reply into Webhook in handler
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    return EditMessageChecklist(...)

docs/api/methods/get_my_star_balance.rst

@@ -0,0 +1,38 @@
+################
+getMyStarBalance
+################
+
+Returns: :obj:`StarAmount`
+
+.. automodule:: aiogram.methods.get_my_star_balance
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+    :exclude-members: model_config,model_fields
+
+
+Usage
+=====
+
+As bot method
+-------------
+
+.. code-block::
+
+    result: StarAmount = await bot.get_my_star_balance(...)
+
+
+Method as object
+----------------
+
+Imports:
+
+- :code:`from aiogram.methods.get_my_star_balance import GetMyStarBalance`
+- alias: :code:`from aiogram.methods import GetMyStarBalance`
+
+With specific bot
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    result: StarAmount = await bot(GetMyStarBalance(...))

docs/api/methods/index.rst

@@ -86,6 +86,7 @@ Available methods
     send_animation
     send_audio
     send_chat_action
+    send_checklist
     send_contact
     send_dice
     send_document
@@ -133,6 +134,7 @@ Updating messages
     delete_messages
     delete_story
     edit_message_caption
+    edit_message_checklist
     edit_message_live_location
     edit_message_media
     edit_message_reply_markup
@@ -191,6 +193,7 @@ Payments
     answer_shipping_query
     create_invoice_link
     edit_user_star_subscription
+    get_my_star_balance
     get_star_transactions
     refund_star_payment
     send_invoice

docs/api/methods/send_checklist.rst

@@ -0,0 +1,45 @@
+#############
+sendChecklist
+#############
+
+Returns: :obj:`Message`
+
+.. automodule:: aiogram.methods.send_checklist
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+    :exclude-members: model_config,model_fields
+
+
+Usage
+=====
+
+As bot method
+-------------
+
+.. code-block::
+
+    result: Message = await bot.send_checklist(...)
+
+
+Method as object
+----------------
+
+Imports:
+
+- :code:`from aiogram.methods.send_checklist import SendChecklist`
+- alias: :code:`from aiogram.methods import SendChecklist`
+
+With specific bot
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    result: Message = await bot(SendChecklist(...))
+
+As reply into Webhook in handler
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    return SendChecklist(...)

docs/api/types/checklist.rst

@@ -0,0 +1,10 @@
+#########
+Checklist
+#########
+
+
+.. automodule:: aiogram.types.checklist
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+    :exclude-members: model_config,model_fields

docs/api/types/checklist_task.rst

@@ -0,0 +1,10 @@
+#############
+ChecklistTask
+#############
+
+
+.. automodule:: aiogram.types.checklist_task
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+    :exclude-members: model_config,model_fields

docs/api/types/checklist_tasks_added.rst

@@ -0,0 +1,10 @@
+###################
+ChecklistTasksAdded
+###################
+
+
+.. automodule:: aiogram.types.checklist_tasks_added
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+    :exclude-members: model_config,model_fields

docs/api/types/checklist_tasks_done.rst

@@ -0,0 +1,10 @@
+##################
+ChecklistTasksDone
+##################
+
+
+.. automodule:: aiogram.types.checklist_tasks_done
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+    :exclude-members: model_config,model_fields

docs/api/types/direct_message_price_changed.rst

@@ -0,0 +1,10 @@
+#########################
+DirectMessagePriceChanged
+#########################
+
+
+.. automodule:: aiogram.types.direct_message_price_changed
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+    :exclude-members: model_config,model_fields

docs/api/types/index.rst

@@ -70,9 +70,14 @@ Available types
     chat_permissions
     chat_photo
     chat_shared
+    checklist
+    checklist_task
+    checklist_tasks_added
+    checklist_tasks_done
     contact
     copy_text_button
     dice
+    direct_message_price_changed
     document
     external_reply_info
     file
@@ -94,6 +99,8 @@ Available types
     inaccessible_message
     inline_keyboard_button
     inline_keyboard_markup
+    input_checklist
+    input_checklist_task
     input_file
     input_media
     input_media_animation

docs/api/types/input_checklist.rst

@@ -0,0 +1,10 @@
+##############
+InputChecklist
+##############
+
+
+.. automodule:: aiogram.types.input_checklist
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+    :exclude-members: model_config,model_fields

docs/api/types/input_checklist_task.rst

@@ -0,0 +1,10 @@
+##################
+InputChecklistTask
+##################
+
+
+.. automodule:: aiogram.types.input_checklist_task
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+    :exclude-members: model_config,model_fields

docs/dispatcher/finite_state_machine/index.rst

@@ -89,6 +89,37 @@ Complete example
     :linenos:
 
 
+Changing state for another user
+-------------------------------
+
+In some cases, you might need to change the state for a user other than the one who triggered the current handler.
+For example, you might want to change the state of a user based on an admin's command.
+
+To do this, you can use the ``get_context`` method of the FSM middleware through the dispatcher:
+
+.. code-block:: python
+
+    @example_router.message(Command("example"))
+    async def command_example(message: Message, dispatcher: Dispatcher, bot: Bot):
+        user_id = ...  # Get the user ID in the way that you need
+        state = await dispatcher.fsm.get_context(
+            bot=bot,
+            chat_id=user_id,
+            user_id=user_id,
+        )
+
+        # Now you can use the state context to change the state for the specified user
+        await state.set_state(YourState.some_state)
+
+        # Or store data in the state
+        await state.update_data(some_key="some_value")
+
+        # Or clear the state
+        await state.clear()
+
+This allows you to manage the state of any user in your bot, not just the one who triggered the current handler.
+
+
 Read more
 =========
 

docs/dispatcher/finite_state_machine/scene.rst

@@ -242,3 +242,74 @@ Scene has only three points for transitions:
 - enter point - when user enters to the scene
 - leave point - when user leaves the scene and the enter another scene
 - exit point - when user exits from the scene
+
+How to enter the scene
+----------------------
+
+There are several ways to enter a scene in aiogram. Each approach has specific use cases and advantages
+
+1. **Directly using the scene's entry point as a handler:**
+
+   You can convert a scene's entry point to a handler and register it like any other handler:
+
+   .. code-block:: python
+
+       router.message.register(SettingsScene.as_handler(), Command("settings"))
+
+2. **From a regular handler using ScenesManager:**
+
+   Enter a scene from any regular handler by using the ScenesManager:
+
+   .. note::
+
+     When using ScenesManager, you need to explicitly pass all dependencies required by the scene's
+     entry point handler as arguments to the enter method.
+
+   .. code-block:: python
+
+       @router.message(Command("settings"))
+       async def settings_handler(message: Message, scenes: ScenesManager):
+           await scenes.enter(SettingsScene, some_data="data")  # pass additional arguments to the scene
+
+3. **From another scene using After.goto marker:**
+
+   Transition to another scene after a handler is executed using the After marker:
+
+   .. code-block:: python
+
+       class MyScene(Scene, state="my_scene"):
+
+           ...
+
+           @on.message(F.text.startswith("🚀"), after=After.goto(AnotherScene))
+           async def on_message(self, message: Message, some_repo: SomeRepository, db: AsyncSession):
+               # Persist some data before going to another scene
+               await some_repo.save(user_id=message.from_user.id, value=message.text)
+               await db.commit()
+
+           ...
+
+4. **Using explicit transition with wizard.goto:**
+
+   For more control over the transition, use the wizard.goto method from within a scene handler:
+
+   .. note::
+
+     Dependencies will be injected into the handler normally and then extended with
+     the arguments specified in the goto method.
+
+   .. code-block:: python
+
+       class MyScene(Scene, state="my_scene"):
+           ...
+
+           @on.message(F.text.startswith("🚀"))
+           async def on_message(self, message: Message):
+               # Direct control over when and how to transition
+               await self.wizard.goto(AnotherScene, value=message.text)
+
+           ...
+
+
+Each method offers different levels of control and integration with your application's architecture.
+Choose the approach that best fits your specific use case and coding style.