From f45863a0b996203546c35a1116094cd0e4516489 Mon Sep 17 00:00:00 2001
From: DaniilKosvintsev <73761593+DanZ-ix@users.noreply.github.com>
Date: Mon, 6 May 2024 23:28:38 +0300
Subject: [PATCH] Added message serialisation and deserialization block in 2.x
 -> 3.x migration guide (#1479)

* Added message serialisation and deserialization block in 2.x -> 3.x migration guide

* fixed docs, added to_python() pydantic alternative

* fixed docs, added examples

---------

Co-authored-by: DanZ-ix <vpupkin@company.com>
---
 CHANGES/1412.doc.rst      |  1 +
 docs/migration_2_to_3.rst | 73 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 CHANGES/1412.doc.rst

diff --git a/CHANGES/1412.doc.rst b/CHANGES/1412.doc.rst
new file mode 100644
index 00000000..0429dac3
--- /dev/null
+++ b/CHANGES/1412.doc.rst
@@ -0,0 +1 @@
+Added telegram objects transformation block in 2.x -> 3.x migration guide
diff --git a/docs/migration_2_to_3.rst b/docs/migration_2_to_3.rst
index 0eeef2bf..f8c0753c 100644
--- a/docs/migration_2_to_3.rst
+++ b/docs/migration_2_to_3.rst
@@ -149,3 +149,76 @@ Telegram API Server
 
 - The `server` parameter has been moved from the `Bot` instance to `api` in `BaseSession`.
 - The constant `aiogram.bot.api.TELEGRAM_PRODUCTION` has been moved to `aiogram.client.telegram.PRODUCTION`.
+
+
+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.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.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'>