Add serialization utilities and update documentation (#1515)

* Add serialization utilities and update documentation

Introduced utilities to deserialize Telegram objects to JSON-compliant Python objects and vice versa. These utilities manage both cases with and without files. The documentation has been updated to reflect these changes, including updates in migration recommendations and tutorials. A new unit test is added to verify the new functionality.

* Fixed Must-die implementation of the datetime serialization

* Fixed `TypeError: can't subtract offset-naive and offset-aware datetimes`

docs/migration_2_to_3.rst

@@ -162,14 +162,12 @@ 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()`
+- Methods :code:`TelegramObject.to_object()`, :code:`TelegramObject.to_json()` and :code:`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()`
+- :code:`TelegramObject.to_object()` should be replaced by :code:`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>`_)
+- :code:`TelegramObject.as_json()` should be replaced by :func:`aiogram.utils.serialization.deserialize_telegram_object_to_python`
+- :code:`<TelegramObject>.to_python()` should be replaced by :code:`json.dumps(deserialize_telegram_object_to_python(<TelegramObject>))`
 
 Here are some usage examples:
 
@@ -206,7 +204,7 @@ Here are some usage examples:
         # <class 'str'>
 
         # Version 3.x
-        message_json = message.model_dump_json()
+        message_json = json.dumps(deserialize_telegram_object_to_python(message))
         print(message_json)
         # {"id": 42, ...}
         print(type(message_json))
@@ -225,7 +223,7 @@ Here are some usage examples:
         # <class 'dict'>
 
         # Version 3.x
-        message_dict = message.model_dump()
+        message_dict = deserialize_telegram_object_to_python(message)
         print(message_dict)
         # {"id": 42, ...}
         print(type(message_dict))

docs/utils/index.rst

@@ -12,3 +12,4 @@ Utils
     formatting
     media_group
     deep_linking
+    serialization

docs/utils/serialization.rst

@@ -0,0 +1,42 @@
+.. _serialization-tool:
+
+=============================
+Telegram object serialization
+=============================
+
+Serialization
+=============
+
+To serialize Python object to Telegram object you can use pydantic serialization methods, for example:
+
+.. code-block:: python
+
+    message_data = { ... }  # Some message data as dict
+    message = Message.model_validate(message_data)
+
+If you want to bind serialized object to the Bot instance, you can use context:
+
+.. code-block:: python
+
+    message_data = { ... }  # Some message data as dict
+    message = Message.model_validate(message_data, context={"bot": bot})
+
+
+Deserialization
+===============
+
+In cases when you need to deserialize Telegram object to Python object, you can use this module.
+
+To convert Telegram object to Python object excluding files you can use
+:func:`aiogram.utils.serialization.deserialize_telegram_object_to_python` function.
+
+.. autofunction:: aiogram.utils.serialization.deserialize_telegram_object_to_python
+
+To convert Telegram object to Python object including files you can use
+:func:`aiogram.utils.serialization.deserialize_telegram_object` function,
+which returns :class:`aiogram.utils.serialization.DeserializedTelegramObject` object.
+
+.. autofunction:: aiogram.utils.serialization.deserialize_telegram_object
+
+.. autoclass:: aiogram.utils.serialization.DeserializedTelegramObject
+    :members: