diff --git a/readthedocs/misc/v2-migration-guide.rst b/readthedocs/misc/v2-migration-guide.rst index ccf53027..3815f2dd 100644 --- a/readthedocs/misc/v2-migration-guide.rst +++ b/readthedocs/misc/v2-migration-guide.rst @@ -6,8 +6,9 @@ Version 2 represents the second major version change, breaking compatibility with old code beyond the usual raw API changes in order to clean up a lot of the technical debt that has grown on the project. -This document documents all the things you should be aware of when migrating -from Telethon version 1.x to 2.0 onwards. +This document documents all the things you should be aware of when migrating from Telethon version +1.x to 2.0 onwards. It is sorted roughly from the "likely most impactful changes" to "there's a +good chance you were not relying on this to begin with". **Please read this document in full before upgrading your code to Telethon 2.0.** @@ -30,48 +31,35 @@ will need to migrate that to support the new size requirement of 8 bytes. For the full list of types changed, please review the above link. -Many subpackages and modules are now private --------------------------------------------- +Synchronous compatibility mode has been removed +----------------------------------------------- -There were a lot of things which were public but should not have been. From now on, you should -only rely on things that are either publicly re-exported or defined. That is, as soon as anything -starts with an underscore (``_``) on its name, you're acknowledging that the functionality may -change even across minor version changes, and thus have your code break. +The "sync hack" (which kicked in as soon as anything from ``telethon.sync`` was imported) has been +removed. This implies: -The following subpackages are now considered private: +* The ``telethon.sync`` module is gone. +* Synchronous context-managers (``with`` as opposed to ``async with``) are no longer supported. + Most notably, you can no longer do ``with client``. It must be ``async with client`` now. +* The "smart" behaviour of the following methods has been removed and now they no longer work in + a synchronous context when the ``asyncio`` event loop was not running. This means they now need + to be used with ``await`` (or, alternatively, manually used with ``loop.run_until_complete``): + * ``start`` + * ``disconnect`` + * ``run_until_disconnected`` -* ``client`` is now ``_client``. -* ``crypto`` is now ``_crypto``. -* ``extensions`` is now ``_misc``. -* ``tl`` is now ``_tl``. - -The following modules have been moved inside ``_misc``: - -* ``entitycache.py`` -* ``helpers.py`` -* ``hints.py`` -* ``password.py`` -* ``requestiter.py` -* ``statecache.py`` -* ``utils.py`` - -// TODO review telethon/__init__.py isn't exposing more than it should +// TODO provide standalone alternative for this? -The TelegramClient is no longer made out of mixins --------------------------------------------------- - -If you were relying on any of the individual mixins that made up the client, such as -``UserMethods`` inside the ``telethon.client`` subpackage, those are now gone. -There is a single ``TelegramClient`` class now, containing everything you need. - - -Raw API methods have been renamed ---------------------------------- +Raw API methods have been renamed and are now considered private +---------------------------------------------------------------- The subpackage holding the raw API methods has been renamed from ``tl`` to ``_tl`` in order to signal that these are prone to change across minor version bumps (the ``y`` in version ``x.y.z``). +Because in Python "we're all adults", you *can* use this private module if you need to. However, +you *are* also acknowledging that this is a private module prone to change (and indeed, it will +change on layer upgrades across minor version bumps). + The ``Request`` suffix has been removed from the classes inside ``tl.functions``. The ``tl.types`` is now simply ``_tl``, and the ``tl.functions`` is now ``_tl.fn``. @@ -103,23 +91,32 @@ This serves multiple goals: // TODO this definitely generated files mapping from the original name to this new one... -Synchronous compatibility mode has been removed ------------------------------------------------ +Many subpackages and modules are now private +-------------------------------------------- -The "sync hack" (which kicked in as soon as anything from ``telethon.sync`` was imported) has been -removed. This implies: +There were a lot of things which were public but should not have been. From now on, you should +only rely on things that are either publicly re-exported or defined. That is, as soon as anything +starts with an underscore (``_``) on its name, you're acknowledging that the functionality may +change even across minor version changes, and thus have your code break. -* The ``telethon.sync`` module is gone. -* Synchronous context-managers (``with`` as opposed to ``async with``) are no longer supported. - Most notably, you can no longer do ``with client``. It must be ``async with client`` now. -* The "smart" behaviour of the following methods has been removed and now they no longer work in - a synchronous context when the ``asyncio`` event loop was not running. This means they now need - to be used with ``await`` (or, alternatively, manually used with ``loop.run_until_complete``): - * ``start`` - * ``disconnect`` - * ``run_until_disconnected`` +The following subpackages are now considered private: -// TODO provide standalone alternative for this? +* ``client`` is now ``_client``. +* ``crypto`` is now ``_crypto``. +* ``extensions`` is now ``_misc``. +* ``tl`` is now ``_tl``. + +The following modules have been moved inside ``_misc``: + +* ``entitycache.py`` +* ``helpers.py`` +* ``hints.py`` +* ``password.py`` +* ``requestiter.py` +* ``statecache.py`` +* ``utils.py`` + +// TODO review telethon/__init__.py isn't exposing more than it should The Conversation API has been removed @@ -134,3 +131,11 @@ just fine This approach can also be easily persisted, and you can adjust it to y your handlers much more easily. // TODO provide standalone alternative for this? + + +The TelegramClient is no longer made out of mixins +-------------------------------------------------- + +If you were relying on any of the individual mixins that made up the client, such as +``UserMethods`` inside the ``telethon.client`` subpackage, those are now gone. +There is a single ``TelegramClient`` class now, containing everything you need.