From c953e42424cf32cdcdf5db3d868c001504a1ffcd Mon Sep 17 00:00:00 2001
From: DanZ-ix <vpupkin@company.com>
Date: Mon, 6 May 2024 18:05:44 +0300
Subject: [PATCH] fixed docs, added examples

---
 docs/migration_2_to_3.rst | 70 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 65 insertions(+), 5 deletions(-)

diff --git a/docs/migration_2_to_3.rst b/docs/migration_2_to_3.rst
index 2a5ee80b..f8c0753c 100644
--- a/docs/migration_2_to_3.rst
+++ b/docs/migration_2_to_3.rst
@@ -152,13 +152,73 @@ Telegram API Server
 
 
 Telegram objects transformation (to dict, to json, from json)
-===========================================
+=============================================================
 
 - Methods :class:`TelegramObject.to_object()`, :class:`TelegramObject.to_json()` and :class:`TelegramObject.to_python()` 
   have been removed due to the use of `pydantic <https://docs.pydantic.dev/>`_ models.
-- :class:`TelegramObject.model_validate_json()` should be used instead of :class:`TelegramObject.to_object()` 
-  (`Read more <https://docs.pydantic.dev/2.7/api/base_model/#pydantic.BaseModel.model_validate_json>`_)
-- :class:`TelegramObject.model_dump_json()` should be used instead of :class:`TelegramObject.as_json()` 
+- :class:`TelegramObject.to_object()` should be replaced by :class:`TelegramObject.model_validate()`
+  (`Read more <https://docs.pydantic.dev/2.7/api/base_model/#pydantic.BaseModel.model_validate>`_)
+- :class:`TelegramObject.as_json()` should be replaced by  :class:`TelegramObject.model_dump_json()`
   (`Read more <https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_dump_json>`_)
-- :class:`TelegramObject.model_dump()` should be used instead of :class:`TelegramObject.to_python()` 
+- :class:`TelegramObject.to_python()` should be replaced by :class:`TelegramObject.model_dump()`
   (`Read more <https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_dump>`_)
+
+Here are some usage examples:
+
+- Creating an object from a dictionary representation of an object
+
+.. code-block::
+
+    # Version 2.x
+    message_dict = {"id": 42, ...}
+    message_obj = Message.to_object(message_dict)
+    print(message_obj)  
+    # id=42 name='n' ...
+    print(type(message_obj))
+    # <class 'aiogram.types.message.Message'>
+    
+    # Version 3.x
+    message_dict = {"id": 42, ...}
+    message_obj = Message.model_validate(message_dict)
+    print(message_obj)  
+    # id=42 name='n' ...
+    print(type(message_obj))
+    # <class 'aiogram.types.message.Message'>
+        
+- Creating a json representation of an object
+
+.. code-block::
+
+    async def handler(message: Message) -> None:
+        # Version 2.x
+        message_json = message.as_json()
+        print(message_json)  
+        # {"id": 42, ...}
+        print(type(message_json))
+        # <class 'str'>
+        
+        # Version 3.x
+        message_json = message.model_dump_json()
+        print(message_json)  
+        # {"id": 42, ...}
+        print(type(message_json))
+        # <class 'str'>
+
+- Creating a dictionary representation of an object
+
+.. code-block::
+
+    async def handler(message: Message) -> None:
+        # Version 2.x
+        message_dict = message.to_python()
+        print(message_dict)  
+        # {"id": 42, ...}
+        print(type(message_dict))
+        # <class 'dict'>
+        
+        # Version 3.x
+        message_dict = message.model_dump()
+        print(message_dict)  
+        # {"id": 42, ...}
+        print(type(message_dict))
+        # <class 'dict'>