diff --git a/.gitignore b/.gitignore index 6f2cf6f7..e81bec11 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,7 @@ # Generated code -/telethon/tl/functions/ -/telethon/tl/types/ -/telethon/tl/alltlobjects.py +/telethon/_tl/functions/ +/telethon/_tl/types/ +/telethon/_tl/alltlobjects.py /telethon/errors/rpcerrorlist.py # User session diff --git a/readthedocs/misc/v2-migration-guide.rst b/readthedocs/misc/v2-migration-guide.rst index 1ee9bda4..de1af171 100644 --- a/readthedocs/misc/v2-migration-guide.rst +++ b/readthedocs/misc/v2-migration-guide.rst @@ -9,6 +9,8 @@ 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. +**Please read this document in full before upgrading your code to Telethon 2.0.** + User, chat and channel identifiers are now 64-bit numbers --------------------------------------------------------- @@ -22,17 +24,75 @@ 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 modules are now private ----------------------------- +Many subpackages and modules are now private +-------------------------------------------- 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.client`` module is now ``telethon._client``, meaning you should stop relying on - anything inside of it. This includes all of the subclasses that used to exist (like ``UserMethods``). +The following subpackages are now considered private: +* ``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`` + + +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 +--------------------------------- + +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``). + +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``. + +Some examples: + +.. code-block:: python + + # Before + from telethon.tl import types, functions + + await client(functions.messages.SendMessageRequest(...)) + message: types.Message = ... + + # After + from telethon import _tl + await client(_tl.fn.messages.SendMessage(...)) + message: _tl.Message + +This serves multiple goals: + +* It removes redundant parts from the names. The "recommended" way of using the raw API is through + the subpackage namespace, which already contains a mention to "functions" in it. In addition, + some requests were awkward, such as ``SendCustomRequestRequest``. +* It makes it easier to search for code that is using the raw API, so that you can quickly + identify which parts are making use of it. +* The name is shorter, but remains recognizable. + +// TODO this definitely generated files mapping from the original name to this new one... Synchronous compatibility mode has been removed ----------------------------------------------- @@ -61,46 +121,7 @@ handlers, and overcomplicated usage for anything beyond the simplest case. It is not difficult to write your own code to deal with a conversation's state. A simple `Finite State Machine `__ inside your handlers will do -just fine: - -.. code-block:: python - - from enum import Enum, auto - - # We use a Python Enum for the state because it's a clean and easy way to do it - class State(Enum): - WAIT_NAME = auto() - WAIT_AGE = auto() - - # The state in which different users are, {user_id: state} - conversation_state = {} - - # ...code to create and setup your client... - - @client.on(events.NewMessage) - async def handler(event): - who = event.sender_id - state = conversation_state.get(who) - - if state is None: - # Starting a conversation - await event.respond('Hi! What is your name?') - conversation_state[who] = State.WAIT_NAME - - elif state == State.WAIT_NAME: - name = event.text # Save the name wherever you want - await event.respond('Nice! What is your age?') - conversation_state[who] = State.WAIT_AGE - - elif state == State.WAIT_AGE: - age = event.text # Save the age wherever you want - await event.respond('Thank you!') - # Conversation is done so we can forget the state of this user - del conversation_state[who] - - # ...code to keep Telethon running... - -Not only is this approach simpler, but it can also be easily persisted, and you can adjust it -to your needs and your handlers much more easily. +just fine This approach can also be easily persisted, and you can adjust it to your needs and +your handlers much more easily. // TODO provide standalone alternative for this? diff --git a/telethon/crypto/__init__.py b/telethon/_crypto/__init__.py similarity index 100% rename from telethon/crypto/__init__.py rename to telethon/_crypto/__init__.py diff --git a/telethon/crypto/aes.py b/telethon/_crypto/aes.py similarity index 100% rename from telethon/crypto/aes.py rename to telethon/_crypto/aes.py diff --git a/telethon/crypto/aesctr.py b/telethon/_crypto/aesctr.py similarity index 100% rename from telethon/crypto/aesctr.py rename to telethon/_crypto/aesctr.py diff --git a/telethon/crypto/authkey.py b/telethon/_crypto/authkey.py similarity index 100% rename from telethon/crypto/authkey.py rename to telethon/_crypto/authkey.py diff --git a/telethon/crypto/cdndecrypter.py b/telethon/_crypto/cdndecrypter.py similarity index 100% rename from telethon/crypto/cdndecrypter.py rename to telethon/_crypto/cdndecrypter.py diff --git a/telethon/crypto/factorization.py b/telethon/_crypto/factorization.py similarity index 100% rename from telethon/crypto/factorization.py rename to telethon/_crypto/factorization.py diff --git a/telethon/crypto/libssl.py b/telethon/_crypto/libssl.py similarity index 100% rename from telethon/crypto/libssl.py rename to telethon/_crypto/libssl.py diff --git a/telethon/crypto/rsa.py b/telethon/_crypto/rsa.py similarity index 100% rename from telethon/crypto/rsa.py rename to telethon/_crypto/rsa.py diff --git a/telethon/extensions/__init__.py b/telethon/_misc/__init__.py similarity index 100% rename from telethon/extensions/__init__.py rename to telethon/_misc/__init__.py diff --git a/telethon/extensions/binaryreader.py b/telethon/_misc/binaryreader.py similarity index 100% rename from telethon/extensions/binaryreader.py rename to telethon/_misc/binaryreader.py diff --git a/telethon/entitycache.py b/telethon/_misc/entitycache.py similarity index 100% rename from telethon/entitycache.py rename to telethon/_misc/entitycache.py diff --git a/telethon/helpers.py b/telethon/_misc/helpers.py similarity index 100% rename from telethon/helpers.py rename to telethon/_misc/helpers.py diff --git a/telethon/hints.py b/telethon/_misc/hints.py similarity index 100% rename from telethon/hints.py rename to telethon/_misc/hints.py diff --git a/telethon/extensions/html.py b/telethon/_misc/html.py similarity index 100% rename from telethon/extensions/html.py rename to telethon/_misc/html.py diff --git a/telethon/extensions/markdown.py b/telethon/_misc/markdown.py similarity index 100% rename from telethon/extensions/markdown.py rename to telethon/_misc/markdown.py diff --git a/telethon/extensions/messagepacker.py b/telethon/_misc/messagepacker.py similarity index 100% rename from telethon/extensions/messagepacker.py rename to telethon/_misc/messagepacker.py diff --git a/telethon/password.py b/telethon/_misc/password.py similarity index 100% rename from telethon/password.py rename to telethon/_misc/password.py diff --git a/telethon/requestiter.py b/telethon/_misc/requestiter.py similarity index 100% rename from telethon/requestiter.py rename to telethon/_misc/requestiter.py diff --git a/telethon/statecache.py b/telethon/_misc/statecache.py similarity index 100% rename from telethon/statecache.py rename to telethon/_misc/statecache.py diff --git a/telethon/utils.py b/telethon/_misc/utils.py similarity index 100% rename from telethon/utils.py rename to telethon/_misc/utils.py diff --git a/telethon/network/__init__.py b/telethon/_network/__init__.py similarity index 100% rename from telethon/network/__init__.py rename to telethon/_network/__init__.py diff --git a/telethon/network/authenticator.py b/telethon/_network/authenticator.py similarity index 100% rename from telethon/network/authenticator.py rename to telethon/_network/authenticator.py diff --git a/telethon/network/connection/__init__.py b/telethon/_network/connection/__init__.py similarity index 100% rename from telethon/network/connection/__init__.py rename to telethon/_network/connection/__init__.py diff --git a/telethon/network/connection/connection.py b/telethon/_network/connection/connection.py similarity index 100% rename from telethon/network/connection/connection.py rename to telethon/_network/connection/connection.py diff --git a/telethon/network/connection/http.py b/telethon/_network/connection/http.py similarity index 100% rename from telethon/network/connection/http.py rename to telethon/_network/connection/http.py diff --git a/telethon/network/connection/tcpabridged.py b/telethon/_network/connection/tcpabridged.py similarity index 100% rename from telethon/network/connection/tcpabridged.py rename to telethon/_network/connection/tcpabridged.py diff --git a/telethon/network/connection/tcpfull.py b/telethon/_network/connection/tcpfull.py similarity index 100% rename from telethon/network/connection/tcpfull.py rename to telethon/_network/connection/tcpfull.py diff --git a/telethon/network/connection/tcpintermediate.py b/telethon/_network/connection/tcpintermediate.py similarity index 100% rename from telethon/network/connection/tcpintermediate.py rename to telethon/_network/connection/tcpintermediate.py diff --git a/telethon/network/connection/tcpmtproxy.py b/telethon/_network/connection/tcpmtproxy.py similarity index 100% rename from telethon/network/connection/tcpmtproxy.py rename to telethon/_network/connection/tcpmtproxy.py diff --git a/telethon/network/connection/tcpobfuscated.py b/telethon/_network/connection/tcpobfuscated.py similarity index 100% rename from telethon/network/connection/tcpobfuscated.py rename to telethon/_network/connection/tcpobfuscated.py diff --git a/telethon/network/mtprotoplainsender.py b/telethon/_network/mtprotoplainsender.py similarity index 100% rename from telethon/network/mtprotoplainsender.py rename to telethon/_network/mtprotoplainsender.py diff --git a/telethon/network/mtprotosender.py b/telethon/_network/mtprotosender.py similarity index 100% rename from telethon/network/mtprotosender.py rename to telethon/_network/mtprotosender.py diff --git a/telethon/network/mtprotostate.py b/telethon/_network/mtprotostate.py similarity index 100% rename from telethon/network/mtprotostate.py rename to telethon/_network/mtprotostate.py diff --git a/telethon/network/requeststate.py b/telethon/_network/requeststate.py similarity index 100% rename from telethon/network/requeststate.py rename to telethon/_network/requeststate.py diff --git a/telethon/tl/__init__.py b/telethon/_tl/__init__.py similarity index 100% rename from telethon/tl/__init__.py rename to telethon/_tl/__init__.py diff --git a/telethon/tl/core/__init__.py b/telethon/_tl/core/__init__.py similarity index 100% rename from telethon/tl/core/__init__.py rename to telethon/_tl/core/__init__.py diff --git a/telethon/tl/core/gzippacked.py b/telethon/_tl/core/gzippacked.py similarity index 100% rename from telethon/tl/core/gzippacked.py rename to telethon/_tl/core/gzippacked.py diff --git a/telethon/tl/core/messagecontainer.py b/telethon/_tl/core/messagecontainer.py similarity index 100% rename from telethon/tl/core/messagecontainer.py rename to telethon/_tl/core/messagecontainer.py diff --git a/telethon/tl/core/rpcresult.py b/telethon/_tl/core/rpcresult.py similarity index 100% rename from telethon/tl/core/rpcresult.py rename to telethon/_tl/core/rpcresult.py diff --git a/telethon/tl/core/tlmessage.py b/telethon/_tl/core/tlmessage.py similarity index 100% rename from telethon/tl/core/tlmessage.py rename to telethon/_tl/core/tlmessage.py diff --git a/telethon/tl/custom/__init__.py b/telethon/_tl/custom/__init__.py similarity index 100% rename from telethon/tl/custom/__init__.py rename to telethon/_tl/custom/__init__.py diff --git a/telethon/tl/custom/adminlogevent.py b/telethon/_tl/custom/adminlogevent.py similarity index 100% rename from telethon/tl/custom/adminlogevent.py rename to telethon/_tl/custom/adminlogevent.py diff --git a/telethon/tl/custom/button.py b/telethon/_tl/custom/button.py similarity index 100% rename from telethon/tl/custom/button.py rename to telethon/_tl/custom/button.py diff --git a/telethon/tl/custom/chatgetter.py b/telethon/_tl/custom/chatgetter.py similarity index 100% rename from telethon/tl/custom/chatgetter.py rename to telethon/_tl/custom/chatgetter.py diff --git a/telethon/tl/custom/dialog.py b/telethon/_tl/custom/dialog.py similarity index 100% rename from telethon/tl/custom/dialog.py rename to telethon/_tl/custom/dialog.py diff --git a/telethon/tl/custom/draft.py b/telethon/_tl/custom/draft.py similarity index 100% rename from telethon/tl/custom/draft.py rename to telethon/_tl/custom/draft.py diff --git a/telethon/tl/custom/file.py b/telethon/_tl/custom/file.py similarity index 100% rename from telethon/tl/custom/file.py rename to telethon/_tl/custom/file.py diff --git a/telethon/tl/custom/forward.py b/telethon/_tl/custom/forward.py similarity index 100% rename from telethon/tl/custom/forward.py rename to telethon/_tl/custom/forward.py diff --git a/telethon/tl/custom/inlinebuilder.py b/telethon/_tl/custom/inlinebuilder.py similarity index 100% rename from telethon/tl/custom/inlinebuilder.py rename to telethon/_tl/custom/inlinebuilder.py diff --git a/telethon/tl/custom/inlineresult.py b/telethon/_tl/custom/inlineresult.py similarity index 100% rename from telethon/tl/custom/inlineresult.py rename to telethon/_tl/custom/inlineresult.py diff --git a/telethon/tl/custom/inlineresults.py b/telethon/_tl/custom/inlineresults.py similarity index 100% rename from telethon/tl/custom/inlineresults.py rename to telethon/_tl/custom/inlineresults.py diff --git a/telethon/tl/custom/inputsizedfile.py b/telethon/_tl/custom/inputsizedfile.py similarity index 100% rename from telethon/tl/custom/inputsizedfile.py rename to telethon/_tl/custom/inputsizedfile.py diff --git a/telethon/tl/custom/message.py b/telethon/_tl/custom/message.py similarity index 100% rename from telethon/tl/custom/message.py rename to telethon/_tl/custom/message.py diff --git a/telethon/tl/custom/messagebutton.py b/telethon/_tl/custom/messagebutton.py similarity index 100% rename from telethon/tl/custom/messagebutton.py rename to telethon/_tl/custom/messagebutton.py diff --git a/telethon/tl/custom/participantpermissions.py b/telethon/_tl/custom/participantpermissions.py similarity index 100% rename from telethon/tl/custom/participantpermissions.py rename to telethon/_tl/custom/participantpermissions.py diff --git a/telethon/tl/custom/qrlogin.py b/telethon/_tl/custom/qrlogin.py similarity index 100% rename from telethon/tl/custom/qrlogin.py rename to telethon/_tl/custom/qrlogin.py diff --git a/telethon/tl/custom/sendergetter.py b/telethon/_tl/custom/sendergetter.py similarity index 100% rename from telethon/tl/custom/sendergetter.py rename to telethon/_tl/custom/sendergetter.py diff --git a/telethon/tl/patched/__init__.py b/telethon/_tl/patched/__init__.py similarity index 100% rename from telethon/tl/patched/__init__.py rename to telethon/_tl/patched/__init__.py diff --git a/telethon/tl/tlobject.py b/telethon/_tl/tlobject.py similarity index 100% rename from telethon/tl/tlobject.py rename to telethon/_tl/tlobject.py