From 47c06fdae2cea91a033b491b769061160e84ccfa Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Thu, 23 May 2019 18:59:29 +0200 Subject: [PATCH] Docs revamp. Part 7 --- README.md | 9 - docs/source/_images/logo.png | Bin 13344 -> 0 bytes docs/source/api/client.rst | 2 +- docs/source/api/decorators.rst | 2 + docs/source/conf.py | 214 ++++-------------- docs/source/{meta => }/faq.rst | 104 +++++---- docs/source/{meta => }/glossary.rst | 22 +- docs/source/index.rst | 68 +++--- docs/source/intro/install.rst | 4 +- docs/source/intro/setup.rst | 2 +- docs/source/meta/support-pyrogram.rst | 2 - docs/source/{meta => }/powered-by.rst | 4 +- docs/source/{meta => }/releases.rst | 0 docs/source/start/auth.rst | 4 +- docs/source/support-pyrogram.rst | 26 +++ docs/source/topics/mtproto-vs-botapi.rst | 106 ++++++--- docs/source/topics/serialize.rst | 55 +++++ docs/source/topics/session-settings.rst | 2 +- docs/source/topics/tgcrypto.rst | 4 +- pyrogram/client/client.py | 8 +- .../types/messages_and_media/message.py | 2 +- setup.py | 1 + 22 files changed, 327 insertions(+), 314 deletions(-) delete mode 100644 docs/source/_images/logo.png rename docs/source/{meta => }/faq.rst (76%) rename docs/source/{meta => }/glossary.rst (83%) delete mode 100644 docs/source/meta/support-pyrogram.rst rename docs/source/{meta => }/powered-by.rst (95%) rename docs/source/{meta => }/releases.rst (100%) create mode 100644 docs/source/support-pyrogram.rst create mode 100644 docs/source/topics/serialize.rst diff --git a/README.md b/README.md index 017b513b..4e758b5a 100644 --- a/README.md +++ b/README.md @@ -16,15 +16,6 @@ Community -
- - Schema Layer - - - TgCrypto Version -

## Pyrogram diff --git a/docs/source/_images/logo.png b/docs/source/_images/logo.png deleted file mode 100644 index 1f06fa81657108d18dd969b30709f49e8f1f3a2d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 13344 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 diff --git a/docs/source/api/client.rst b/docs/source/api/client.rst index 01e3f5f8..9527ca73 100644 --- a/docs/source/api/client.rst +++ b/docs/source/api/client.rst @@ -1,7 +1,7 @@ Pyrogram Client =============== -This class exposes high-level methods for an easy access to the API. +This is the Client class. It exposes high-level methods for an easy access to the API. .. code-block:: python :emphasize-lines: 1-3 diff --git a/docs/source/api/decorators.rst b/docs/source/api/decorators.rst index 26bd64e1..be8376f5 100644 --- a/docs/source/api/decorators.rst +++ b/docs/source/api/decorators.rst @@ -34,6 +34,7 @@ of your functions. on_inline_query on_deleted_messages on_user_status + on_poll on_disconnect on_raw_update @@ -42,5 +43,6 @@ of your functions. .. automethod:: pyrogram.Client.on_inline_query() .. automethod:: pyrogram.Client.on_deleted_messages() .. automethod:: pyrogram.Client.on_user_status() +.. automethod:: pyrogram.Client.on_poll() .. automethod:: pyrogram.Client.on_disconnect() .. automethod:: pyrogram.Client.on_raw_update() \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 5f073186..e079ec68 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,200 +1,68 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- +# Pyrogram - Telegram MTProto API Client Library for Python +# Copyright (C) 2017-2019 Dan Tès # -# Pyrogram documentation build configuration file, created by -# sphinx-quickstart on Fri Dec 29 11:35:55 2017. +# This file is part of Pyrogram. # -# This file is execfile()d with the current directory set to its -# containing dir. +# Pyrogram is free software: you can redistribute it and/or modify +# it under the terms of the GNU Lesser General Public License as published +# by the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. # -# Note that not all possible configuration values are present in this -# autogenerated file. +# Pyrogram is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU Lesser General Public License for more details. # -# All configuration values have a default; values that are commented out -# serve to show the default. +# You should have received a copy of the GNU Lesser General Public License +# along with Pyrogram. If not, see . -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# import os import sys -sys.path.insert(0, os.path.abspath('../..')) +sys.path.insert(0, os.path.abspath("../..")) -# Import after sys.path.insert() to avoid issues from pyrogram import __version__ from pygments.styles.friendly import FriendlyStyle FriendlyStyle.background_color = "#f3f2f1" -# -- General configuration ------------------------------------------------ +project = "Pyrogram" +copyright = "2017-2019, Dan" +author = "Dan" -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.napoleon', - 'sphinx.ext.autosummary' + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx.ext.autosummary" ] +master_doc = "index" +source_suffix = ".rst" +autodoc_member_order = "bysource" + +version = __version__ +release = version +version_rst = ".. |version| replace:: {}".format(version) + +templates_path = ["_templates"] + napoleon_use_rtype = False -# Don't show source files on docs -html_show_sourcelink = True - -# Order by source, not alphabetically -autodoc_member_order = 'bysource' - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = 'Pyrogram' -copyright = '2017-2019, Dan Tès' -author = 'Dan Tès' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = "version " + __version__ -# The full version, including alpha/beta/rc tags. -release = version - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'friendly' - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - -# -- Options for HTML output ---------------------------------------------- +pygments_style = "friendly" html_title = "Pyrogram Documentation" - -# Overridden by template +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] +html_show_sourcelink = True html_show_copyright = False - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# html_theme_options = { - 'canonical_url': "https://docs.pyrogram.org/", - 'collapse_navigation': True, - 'sticky_navigation': False, - 'logo_only': True, - 'display_version': True + "canonical_url": "https://docs.pyrogram.org/", + "collapse_navigation": True, + "sticky_navigation": False, + "logo_only": True, + "display_version": True } -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -html_logo = '_images/logo.png' - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -html_favicon = '_images/favicon.ico' - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# This is required for the alabaster theme -# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars -html_sidebars = { - '**': [ - 'relations.html', # needs 'show_related': True theme option to display - 'searchbox.html', - ] -} - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = 'Pyrogramdoc' - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'Pyrogram.tex', 'Pyrogram Documentation', - 'Dan Tès', 'manual'), -] - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'pyrogram', 'Pyrogram Documentation', - [author], 1) -] - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'Pyrogram', 'Pyrogram Documentation', - author, 'Pyrogram', 'One line description of project.', - 'Miscellaneous'), -] +html_logo = "_images/pyrogram.png" +html_favicon = "_images/favicon.ico" diff --git a/docs/source/meta/faq.rst b/docs/source/faq.rst similarity index 76% rename from docs/source/meta/faq.rst rename to docs/source/faq.rst index 07f4aece..b42332cd 100644 --- a/docs/source/meta/faq.rst +++ b/docs/source/faq.rst @@ -20,7 +20,7 @@ C. It enables you to easily create custom applications for both user and bot ide `MTProto API`_ with the Python programming language. .. _Telegram: https://telegram.org -.. _MTProto API: ../topics/mtproto-vs-botapi#what-is-the-mtproto-api +.. _MTProto API: topics/mtproto-vs-botapi#what-is-the-mtproto-api Where does the name come from? ------------------------------ @@ -51,15 +51,15 @@ Why Pyrogram? - **Comprehensive**: Execute any `advanced action`_ an official client is able to do, and even more. .. _TgCrypto: https://github.com/pyrogram/tgcrypto -.. _Smart Plugin: ../topics/smart-plugins -.. _advanced action: ../topics/advanced-usage +.. _Smart Plugin: topics/smart-plugins +.. _advanced action: topics/advanced-usage What can MTProto do more than the Bot API? ------------------------------------------ For a detailed answer, please refer to the `MTProto vs. Bot API`_ page. -.. _MTProto vs. Bot API: ../topics/mtproto-vs-botapi +.. _MTProto vs. Bot API: topics/mtproto-vs-botapi Why do I need an API key for bots? ---------------------------------- @@ -75,6 +75,53 @@ Using MTProto is the only way to communicate with the actual Telegram servers, a identify applications by means of a unique key; the bot token identifies a bot as a user and replaces the user's phone number only. +Can I use the same file_id across different accounts? +----------------------------------------------------- + +No, Telegram doesn't allow this. + +File ids are personal and bound to a specific user/bot -- and an attempt in using a foreign file id will result in +errors such as ``[400 MEDIA_EMPTY]``. + +The only exception are stickers' file ids; you can use them across different accounts without any problem, like this +one: ``CAADBAADyg4AAvLQYAEYD4F7vcZ43AI``. + +Can I use Bot API's file_ids in Pyrogram? +----------------------------------------- + +Definitely! All file ids you might have taken from the Bot API are 100% compatible and re-usable in Pyrogram... + +...at least for now. + +Telegram is slowly changing some server's internals and it's doing it in such a way that file ids are going to break +inevitably. Not only this, but it seems that the new, hypothetical, file ids could also possibly expire at anytime, thus +losing the *persistence* feature. + +This change will most likely affect the official `Bot API `_ too +(unless Telegram implements some workarounds server-side to keep backwards compatibility, which Pyrogram could in turn +make use of) and we can expect a proper notice from Telegram. + +Can I use multiple clients at once on the same account? +------------------------------------------------------- + +Yes, you can. Both user and bot accounts are able to run multiple sessions in parallel (up to 10 per account). However, +you must pay attention and not use the *same* exact session in more than one client at the same time. In other words: + +- Avoid copying your session file: even if you rename the file, the copied sessions will still point to a specific one + stored in the server. + +- Make sure that only one instance of your script runs, using your session file. + +If you -- even accidentally -- fail to do so, all the previous session copies will immediately stop receiving updates +and eventually the server will start throwing the error ``[406 AUTH_KEY_DUPLICATED]``, inviting you to login again. + +Why is that so? Because the server has recognized two identical sessions are running in two different locations, and +concludes it could possibly be due to a cloned/stolen device. Having the session ended in such occasions will protect +the user's privacy. + +So, the only correct way to run multiple clients on the same account is authorizing your account (either user or bot) +from the beginning every time, and use one separate session for each parallel client you are going to use. + I started a client and nothing happens! --------------------------------------- @@ -99,63 +146,30 @@ fails or not: - DC4: ``149.154.167.91`` - DC5: ``91.108.56.149`` -|bug report| - -.. _you need a proxy: ../topics/proxy +.. _you need a proxy: topics/proxy I keep getting PEER_ID_INVALID error! ------------------------------------------- -The error in question is **[400 PEER_ID_INVALID]: The id/access_hash combination is invalid**, and could mean several +The error in question is ``[400 PEER_ID_INVALID]``, and could mean several things: - The chat id you tried to use is simply wrong, double check it. - The chat id refers to a group or channel you are not a member of. - The chat id refers to a user you have't seen yet (from contacts, groups in common, forwarded messages or private chats). - -|bug report| - -.. |bug report| replace:: - - **Note:** If you really believe this should not happen, kindly open a `Bug Report`_. - -Can I use the same file_id across different accounts? ------------------------------------------------------ - -No, Telegram doesn't allow this. - -File ids are personal and bound to a specific user/bot -- and an attempt in using a foreign file id will result in -errors such as **[400 MEDIA_EMPTY]: The media is invalid**. - -The only exception are stickers' file ids; you can use them across different accounts without any problem, like this -one: ``CAADBAADyg4AAvLQYAEYD4F7vcZ43AI``. - -Can I use Bot API's file_ids in Pyrogram? ------------------------------------------ - -Definitely! All file ids you might have taken from the Bot API are 100% compatible and re-usable in Pyrogram... - -...at least for now. - -Telegram is slowly changing some server's internals and it's doing it in such a way that file ids are going to break -inevitably. Not only this, but it seems that the new, hypothetical, file ids could also possibly expire at anytime, thus -losing the *persistence* feature. - -This change will most likely affect the official `Bot API <../topics/mtproto-vs-botapi#what-is-the-bot-api>`_ too -(unless Telegram implements some workarounds server-side to keep backwards compatibility, which Pyrogram could in turn -make use of) and we can expect a proper notice from Telegram. +- The chat id argument you passed is in form of a string; you have to convert it into an integer with ``int(chat_id)``. My account has been deactivated/limited! ---------------------------------------- First of all, you should understand that Telegram wants to be a safe place for people to stay in, and to pursue this goal there are automatic protection systems running to prevent flood and spam, as well as a moderation team of humans -who reviews reports. +who review reports. -**Pyrogram is a tool at your commands; it only does what you tell it to do, the rest is up to you.** +.. centered:: Pyrogram is a tool at your commands; it only does what you tell it to do, the rest is up to you. -Having said that, here's how a list of what Telegram definitely doesn't like: +Having said that, here's a list of what Telegram definitely doesn't like: - Flood, abusing the API. - Spam, sending unsolicited messages or adding people to unwanted groups and channels. @@ -178,8 +192,8 @@ Pyrogram is free software and is currently licensed under the terms of the `GNU Lesser General Public License v3 or later (LGPLv3+)`_. In short: you may use, redistribute and/or modify it provided that modifications are described and licensed for free under LGPLv3+. -In other words: you can use and integrate Pyrogram into your own code --- either open source, under the same or a -different licence or even proprietary --- without being required to release the source code of your own applications. +In other words: you can use and integrate Pyrogram into your own code --- either open source, under the same or +different license, or even proprietary --- without being required to release the source code of your own applications. However, any modifications to the library itself are required to be published for free under the same LGPLv3+ license. .. _GNU Lesser General Public License v3 or later (LGPLv3+): https://github.com/pyrogram/pyrogram/blob/develop/COPYING.lesser diff --git a/docs/source/meta/glossary.rst b/docs/source/glossary.rst similarity index 83% rename from docs/source/meta/glossary.rst rename to docs/source/glossary.rst index fb5bc8c1..5f00cbfd 100644 --- a/docs/source/meta/glossary.rst +++ b/docs/source/glossary.rst @@ -18,7 +18,7 @@ general. Some words may as well link to dedicated articles in case the topic is API key A secret code used to authenticate and/or authorize a specific application to Telegram in order for it to control how the API is being used, for example, to prevent abuses of the API. - `More on API keys <../intro/setup#api-keys>`_. + `More on API keys `_. DC Also known as *data center*, is a place where lots of computer systems are housed and used together in order to @@ -26,25 +26,25 @@ general. Some words may as well link to dedicated articles in case the topic is RPC Acronym for Remote Procedure call, that is, a function which gets executed at some remote place (i.e. Telegram - server) and not in your local. + server) and not in your local machine. RPCError An error caused by an RPC which must be returned in place of the successful result in order to let the caller - know something went wrong. `More on RPCError <../start/errors>`_. + know something went wrong. `More on RPCError `_. MTProto The name of the custom-made, open and encrypted protocol by Telegram, implemented in Pyrogram. - `More on MTProto `_. + `More on MTProto `_. MTProto API The Telegram main API Pyrogram makes use of, which is able to connect both users and normal bots to Telegram using MTProto as application layer protocol and execute any method Telegram provides from its public TL-schema. - `More on MTProto API `_. + `More on MTProto API `_. Bot API - The Telegram Bot API that is able to only connect normal bots to Telegram using HTTP as application layer - protocol and allows to execute a subset of the main Telegram API. - `More on Bot API `_. + The Telegram Bot API that is able to only connect normal bots only to Telegram using HTTP as application layer + protocol and allows to execute a sub-set of the main Telegram API. + `More on Bot API `_. Pyrogrammer A developer that uses Pyrogram to build Telegram applications. @@ -65,13 +65,11 @@ general. Some words may as well link to dedicated articles in case the topic is Handler An object that wraps around a callback function that is *actually meant* to be registered into the framework, which will then be able to handle a specific kind of events, such as a new incoming message, for example. - `More on Handlers <../start/updates>`_ + `More on Handlers `_. Decorator Also known as *function decorator*, in Python, is a callable object that is used to modify another function. Decorators in Pyrogram are used to automatically register callback functions for handling updates. - `More on Decorators <../start/updates#using-decorators>`_ - -.. _handling updates: ../start/updates + `More on Decorators `_. .. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md diff --git a/docs/source/index.rst b/docs/source/index.rst index 89c92719..de91015f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,8 +4,8 @@ Welcome to Pyrogram .. raw:: html @@ -55,12 +55,15 @@ order using the Next button at the end of each page. Here below you can, instead pages for a quick access. First Steps -^^^^^^^^^^^ +----------- -- `Quick Start`_ - Overview to get you started quickly. -- `Calling Methods`_ - How to call Pyrogram's methods. -- `Handling Updates`_ - How to handle Telegram updates. -- `Error Handling`_ - How to handle API errors correctly. +.. hlist:: + :columns: 2 + + - `Quick Start`_: Overview to get you started quickly. + - `Calling Methods`_: How to call Pyrogram's methods. + - `Handling Updates`_: How to handle Telegram updates. + - `Error Handling`_: How to handle API errors correctly. .. _Quick Start: intro/quickstart .. _Calling Methods: start/invoking @@ -68,32 +71,38 @@ First Steps .. _Error Handling: start/errors API Reference -^^^^^^^^^^^^^ +------------- -- `Client Class`_ - Reference details about the Client class. -- `Available Methods`_ - A list of available high-level methods. -- `Available Types`_ - A list of available high-level types. -- `Bound Methods`_ - A list of convenient bound methods. +.. hlist:: + :columns: 2 -.. _Client Class: api/client + - `Pyrogram Client`_: Reference details about the Client class. + - `Available Methods`_: List of available high-level methods. + - `Available Types`_: List of available high-level types. + - `Bound Methods`_: List of convenient bound methods. + +.. _Pyrogram Client: ./api/client .. _Available Methods: api/methods .. _Available Types: api/types .. _Bound Methods: api/bound-methods Meta -^^^^ +---- -- `Pyrogram FAQ`_ - Answers to common Pyrogram questions. -- `Pyrogram Glossary`_ - A list of words with brief explanations. -- `Release Notes`_ - Release notes for Pyrogram releases. -- `Powered by Pyrogram`_ - A collection of Pyrogram Projects. -- `Support Pyrogram Development`_ - Ways to show your appreciation. +.. hlist:: + :columns: 2 -.. _Pyrogram FAQ: meta/faq -.. _Pyrogram Glossary: meta/glossary -.. _Release Notes: meta/releases -.. _Powered by Pyrogram: meta/powered-by -.. _Support Pyrogram Development: meta/support-pyrogram + - `Pyrogram FAQ`_: Answers to common Pyrogram questions. + - `Pyrogram Glossary`_: List of words with brief explanations. + - `Release Notes`_: Release notes for Pyrogram releases. + - `Powered by Pyrogram`_: Collection of Pyrogram Projects. + - `Support Pyrogram`_: Ways to show your appreciation. + +.. _Pyrogram FAQ: faq +.. _Pyrogram Glossary: glossary +.. _Release Notes: releases +.. _Powered by Pyrogram: powered-by +.. _Support Pyrogram: support-pyrogram .. toctree:: :hidden: @@ -137,6 +146,7 @@ Meta topics/session-settings topics/tgcrypto topics/text-formatting + topics/serialize topics/proxy topics/bots-interaction topics/mtproto-vs-botapi @@ -148,11 +158,11 @@ Meta :hidden: :caption: Meta - meta/faq - meta/glossary - meta/releases - meta/powered-by - meta/support-pyrogram + faq + glossary + releases + powered-by + support-pyrogram .. toctree:: :hidden: diff --git a/docs/source/intro/install.rst b/docs/source/intro/install.rst index f26fc37f..fe804e79 100644 --- a/docs/source/intro/install.rst +++ b/docs/source/intro/install.rst @@ -83,11 +83,11 @@ Verifying To verify that Pyrogram is correctly installed, open a Python shell and import it. If no error shows up you are good to go. -.. code-block:: python +.. parsed-literal:: >>> import pyrogram >>> pyrogram.__version__ - '0.13.0' + '|version|' .. _TgCrypto: ../topics/tgcrypto .. _`Github repo`: http://github.com/pyrogram/pyrogram diff --git a/docs/source/intro/setup.rst b/docs/source/intro/setup.rst index b318654d..9c0cc6d4 100644 --- a/docs/source/intro/setup.rst +++ b/docs/source/intro/setup.rst @@ -40,7 +40,7 @@ There are two ways to do so, and you can choose what fits better for you: api_hash = 0123456789abcdef0123456789abcdef - Alternatively, you can pass your API key to Pyrogram by simply using the *api_id* and *api_hash* parameters of the - Client class. This way you can have full control on how to store and load your credentials (e.g.:, you can load the + Client class. This way you can have full control on how to store and load your credentials (e.g., you can load the credentials from the environment variables and directly pass the values into Pyrogram): .. code-block:: python diff --git a/docs/source/meta/support-pyrogram.rst b/docs/source/meta/support-pyrogram.rst deleted file mode 100644 index 052d78bd..00000000 --- a/docs/source/meta/support-pyrogram.rst +++ /dev/null @@ -1,2 +0,0 @@ -Support Pyrogram Development -============================ diff --git a/docs/source/meta/powered-by.rst b/docs/source/powered-by.rst similarity index 95% rename from docs/source/meta/powered-by.rst rename to docs/source/powered-by.rst index 3e46fb07..03e6decd 100644 --- a/docs/source/meta/powered-by.rst +++ b/docs/source/powered-by.rst @@ -55,8 +55,8 @@ Projects Showcase ----- -`BotListBot `_ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`BotListBot `_ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | **A bot which partly uses Pyrogram to check if other bots are still alive** | --- by `JosXa `_ diff --git a/docs/source/meta/releases.rst b/docs/source/releases.rst similarity index 100% rename from docs/source/meta/releases.rst rename to docs/source/releases.rst diff --git a/docs/source/start/auth.rst b/docs/source/start/auth.rst index 3f76e929..e00b08a0 100644 --- a/docs/source/start/auth.rst +++ b/docs/source/start/auth.rst @@ -8,7 +8,7 @@ User Authorization ------------------ In order to use the API, Telegram requires that users be authorized via their phone numbers. -Pyrogram automatically manages this access, all you need to do is create an instance of the +Pyrogram automatically manages this process, all you need to do is create an instance of the :class:`Client ` class by passing to it a ``session_name`` of your choice (e.g.: "my_account") and call the :meth:`run() ` method: @@ -47,7 +47,7 @@ Bot Authorization Bots are a special kind of users that are authorized via their tokens (instead of phone numbers), which are created by the `Bot Father`_. Bot tokens replace the users' phone numbers only — you still need to -`configure a Telegram API key `_ with Pyrogram, even when using bots. +`configure a Telegram API key <../intro/setup#configuration>`_ with Pyrogram, even when using bots. The authorization process is automatically managed. All you need to do is choose a ``session_name`` (can be anything, usually your bot username) and pass your bot token using the ``bot_token`` parameter. The session file will be named diff --git a/docs/source/support-pyrogram.rst b/docs/source/support-pyrogram.rst new file mode 100644 index 00000000..c867b706 --- /dev/null +++ b/docs/source/support-pyrogram.rst @@ -0,0 +1,26 @@ +Support Pyrogram +================ + +Pyrogram is free and open source software, and thus supported by your love! If you like the project and have found it to +be useful, give Pyrogram a `Star on GitHub`_. Your appreciation means a lot and helps staying motivated. + +.. raw:: html + + Star +

+ +Donate +------ + +If you'd also like to donate in order to support Pyrogram -- or any of my `other works`_ -- you can use the PayPal +button below. Thank you. + +.. image:: https://i.imgur.com/fasFTzK.png + :target: https://paypal.me/delivrance + :width: 128 + +--- `Dan`_ + +.. _Star on GitHub: https://github.com/pyrogram/pyrogram +.. _other works: https://github.com/delivrance +.. _Dan: https://t.me/haskell diff --git a/docs/source/topics/mtproto-vs-botapi.rst b/docs/source/topics/mtproto-vs-botapi.rst index accebcd5..cad84251 100644 --- a/docs/source/topics/mtproto-vs-botapi.rst +++ b/docs/source/topics/mtproto-vs-botapi.rst @@ -1,58 +1,110 @@ MTProto vs. Bot API =================== -Being Pyrogram an MTProto-based library, this very feature makes it already superior to, what is usually called, the -official Bot API. +Pyrogram is a framework that acts as a fully-fledged Telegram client based on MTProto, and this very feature makes it +already superior to, what is usually called, the official Bot API, in many respects. This page will therefore show you +why Pyrogram might be a better choice for your project by comparing the two APIs, but first, let's make it clear what +actually is the MTProto and the Bot API. What is the MTProto API? ------------------------ -MTProto, took alone, is the name of the custom-made, open and encrypted communication protocol created by Telegram -itself --- it's the only protocol used to exchange information between a client application and the actual Telegram -servers. +`MTProto`_, took alone, is the name of the custom-made, open and encrypted communication protocol created by Telegram +itself --- it's the only protocol used to exchange information between a client and the actual Telegram servers. -The MTProto **API** however, is what people, for convenience, call the main Telegram API as a whole. This API is able -to authorize both users and bots and happens to be built on top of the MTProto encryption protocol by means of binary -data serialized in a specific way, as described by the TL language, hence the correlation. +The MTProto **API** on the other hand, is what people, for convenience, call the main Telegram API as a whole. This API +is able to authorize both users and bots and is built on top of the MTProto encryption protocol by means of +`binary data serialized`_ in a specific way, as described by the `TL language`_, and delivered using UDP, TCP or even +HTTP as transport-layer protocol. + +.. _MTProto: https://core.telegram.org/mtproto +.. _binary data serialized: https://core.telegram.org/mtproto/serialize +.. _TL language: https://core.telegram.org/mtproto/TL What is the Bot API? -------------------- -The Bot API is an HTTP(S) interface for building normal bots. Bots are special accounts that are authorized via tokens -instead of phone numbers. The Bot API is built yet again on top of the main Telegram API, but runs on an intermediate -server application that in turn communicates with the actual Telegram servers using MTProto. +The `Bot API`_ is an HTTP(S) interface for building normal bots using a sub-set of the main MTProto API. Bots are special +accounts that are authorized via tokens instead of phone numbers. The Bot API is built yet again on top of the main +Telegram API, but runs on an intermediate server application that in turn communicates with the actual Telegram servers +using MTProto. .. figure:: https://i.imgur.com/C108qkX.png :align: center +.. _Bot API: https://core.telegram.org/bots/api + Advantages of the MTProto API ----------------------------- -Here is a list of all the known advantages in using MTProto-based libraries (such as Pyrogram) instead of the official +Here is a list of all the advantages in using MTProto-based libraries -- such as Pyrogram -- instead of the official HTTP Bot API. Using Pyrogram you can: -- **Authorize both user and bot identities**: The Bot API only allows bot accounts. +.. hlist:: + :columns: 1 -- **Upload & download any file, up to 1500 MB each (~1.5 GB)**: The Bot API allows uploads and downloads of files only - up to 50 MB / 20 MB in size (respectively). + - :guilabel:`+` **Authorize both user and bot identities** + - :guilabel:`--` The Bot API only allows bot accounts -- **Has less overhead due to direct connections to Telegram**: The Bot API uses an intermediate server to handle HTTP - requests before they are sent to the actual Telegram servers. +.. hlist:: + :columns: 1 -- **Run multiple sessions at once, up to 10 per account (either bot or user)**: The Bot API intermediate server will - terminate any other session in case you try to use the same bot again in a parallel connection. + - :guilabel:`+` **Upload & download any file, up to 1500 MB each (~1.5 GB)** + - :guilabel:`--` The Bot API allows uploads and downloads of files only up to 50 MB / 20 MB in size (respectively). -- **Get information about any public chat by usernames, even if not a member**: The Bot API simply doesn't support this. +.. hlist:: + :columns: 1 -- **Obtain information about any message existing in a chat using their ids**: The Bot API simply doesn't support this. + - :guilabel:`+` **Has less overhead due to direct connections to Telegram** + - :guilabel:`--` The Bot API uses an intermediate server to handle HTTP requests before they are sent to the actual + Telegram servers. -- **Retrieve the whole chat members list of either public or private chats**: The Bot API simply doesn't support this. +.. hlist:: + :columns: 1 -- **Receive extra updates, such as the one about a user name change**: The Bot API simply doesn't support this. + - :guilabel:`+` **Run multiple sessions at once, up to 10 per account (either bot or user)** + - :guilabel:`--` The Bot API intermediate server will terminate any other session in case you try to use the same + bot again in a parallel connection. -- **Has more meaningful errors in case something went wrong**: The Bot API reports less detailed errors. +.. hlist:: + :columns: 1 -- **Has much more detailed types and powerful methods**: The Bot API types often miss some useful information about - Telegram's type and some of the methods are limited as well. + - :guilabel:`+` **Has much more detailed types and powerful methods** + - :guilabel:`--` The Bot API types often miss some useful information about Telegram entities and some of the + methods are limited as well. -- **Get API version updates, and thus new features, sooner**: The Bot API is simply slower in implementing new features. \ No newline at end of file +.. hlist:: + :columns: 1 + + - :guilabel:`+` **Get information about any public chat by usernames, even if not a member** + - :guilabel:`--` The Bot API simply doesn't support this + +.. hlist:: + :columns: 1 + + - :guilabel:`+` **Obtain information about any message existing in a chat using their ids** + - :guilabel:`--` The Bot API simply doesn't support this + +.. hlist:: + :columns: 1 + + - :guilabel:`+` **Retrieve the whole chat members list of either public or private chats** + - :guilabel:`--` The Bot API simply doesn't support this + +.. hlist:: + :columns: 1 + + - :guilabel:`+` **Receive extra updates, such as the one about a user name change** + - :guilabel:`--` The Bot API simply doesn't support this + +.. hlist:: + :columns: 1 + + - :guilabel:`+` **Has more meaningful errors in case something went wrong** + - :guilabel:`--` The Bot API reports less detailed errors + +.. hlist:: + :columns: 1 + + - :guilabel:`+` **Get API version updates, and thus new features, sooner** + - :guilabel:`--` The Bot API is simply slower in implementing new features diff --git a/docs/source/topics/serialize.rst b/docs/source/topics/serialize.rst new file mode 100644 index 00000000..32208199 --- /dev/null +++ b/docs/source/topics/serialize.rst @@ -0,0 +1,55 @@ +Object Serialization +==================== + +Serializing means converting a Pyrogram object, which exists as Python class instance, to a text string that can be +easily shared and stored anywhere. Pyrogram provides two formats for serializing its objects: one good looking for +humans and another more compact for machines that is able to recover the original structures. + +For Humans - str(obj) +--------------------- + +If you want a nicely formatted, human readable JSON representation of any object in the API -- namely, any object from +`Pyrogram types`_, `raw functions`_ and `raw types`_ -- you can use use ``str(obj)``. + +.. code-block:: python + + ... + + with app: + r = app.get_chat("haskell") + + print(str(r)) + +.. tip:: + + When using ``print()`` you don't actually need to use ``str()`` on the object because it is called automatically, we + have done that above just to show you how to explicitly convert a Pyrogram object to JSON. + +.. _Pyrogram types: ../api/types +.. _raw functions: ../telegram/functions +.. _raw types: ../telegram/types + +For Machines - repr(obj) +------------------------ + +If you want to share or store objects for future references in a more compact way, you can use ``repr(obj)``. While +still pretty much readable, this format is not intended for humans. The advantage of this format is that once you +serialize your object, you can use ``eval()`` to get back the original structure; just make sure to ``import pyrogram``, +as the process requires the package to be in scope. + +.. code-block:: python + + import pyrogram + + ... + + with app: + r = app.get_chat("haskell") + + print(repr(r)) + print(eval(repr(r)) == r) # True + +.. note:: + + Type definitions are subject to changes between versions. You should make sure to store and load objects using the + same Pyrogram version. \ No newline at end of file diff --git a/docs/source/topics/session-settings.rst b/docs/source/topics/session-settings.rst index c8e10479..91e3f050 100644 --- a/docs/source/topics/session-settings.rst +++ b/docs/source/topics/session-settings.rst @@ -9,7 +9,7 @@ app (or by invoking `GetAuthorizations <../telegram/functions/account/GetAuthori store some useful information such as the client who's using them and from which country and IP address. .. figure:: https://i.imgur.com/YaqtMLO.png - :width: 90% + :width: 600 :align: center **A Pyrogram session running on Linux, Python 3.7.** diff --git a/docs/source/topics/tgcrypto.rst b/docs/source/topics/tgcrypto.rst index 2af09a06..454bf05c 100644 --- a/docs/source/topics/tgcrypto.rst +++ b/docs/source/topics/tgcrypto.rst @@ -2,7 +2,7 @@ Fast Crypto =========== Pyrogram's speed can be *dramatically* boosted up by TgCrypto_, a high-performance, easy-to-install Telegram Crypto -Library specifically written in C for Pyrogram [#f1]_ as a Python extension. +Library specifically written in C for Pyrogram [1]_ as a Python extension. TgCrypto is a replacement for the much slower PyAES and implements the crypto algorithms Telegram requires, namely **AES-IGE 256 bit** (used in MTProto v2.0) and **AES-CTR 256 bit** (used for CDN encrypted files). @@ -28,5 +28,5 @@ what you should do next: .. _TgCrypto: https://github.com/pyrogram/tgcrypto -.. [#f1] Although TgCrypto is intended for Pyrogram, it is shipped as a standalone package and can thus be used for +.. [1] Although TgCrypto is intended for Pyrogram, it is shipped as a standalone package and can thus be used for other Python projects too. diff --git a/pyrogram/client/client.py b/pyrogram/client/client.py index 1cfa7c79..8c1e3001 100644 --- a/pyrogram/client/client.py +++ b/pyrogram/client/client.py @@ -66,15 +66,13 @@ class Client(Methods, BaseClient): session_name (``str``): Name to uniquely identify a session of either a User or a Bot, e.g.: "my_account". This name will be used to save a file to disk that stores details needed for reconnecting without asking again for credentials. - Note for bots: You can pass a bot token here, but this usage will be deprecated in next releases. - Use *bot_token* instead. api_id (``int``, *optional*): The *api_id* part of your Telegram API Key, as integer. E.g.: 12345 This is an alternative way to pass it if you don't want to use the *config.ini* file. api_hash (``str``, *optional*): - The *api_hash* part of your Telegram API Key, as string. E.g.: "0123456789abcdef0123456789abcdef" + The *api_hash* part of your Telegram API Key, as string. E.g.: "0123456789abcdef0123456789abcdef". This is an alternative way to pass it if you don't want to use the *config.ini* file. app_version (``str``, *optional*): @@ -104,7 +102,7 @@ class Client(Methods, BaseClient): This is an alternative way to setup a proxy if you don't want to use the *config.ini* file. test_mode (``bool``, *optional*): - Enable or disable log-in to testing servers. Defaults to False. + Enable or disable login to the test servers. Defaults to False. Only applicable for new sessions and will be ignored in case previously created sessions are loaded. @@ -170,7 +168,7 @@ class Client(Methods, BaseClient): Defaults to False (updates enabled and always received). takeout (``bool``, *optional*): - Pass True to let the client use a takeout session instead of a normal one, implies no_updates. + Pass True to let the client use a takeout session instead of a normal one, implies *no_updates=True*. Useful for exporting your Telegram data. Methods invoked inside a takeout session (such as get_history, download_media, ...) are less prone to throw FloodWait exceptions. Only available for users, bots will ignore this parameter. diff --git a/pyrogram/client/types/messages_and_media/message.py b/pyrogram/client/types/messages_and_media/message.py index e51f3425..09cb9ca3 100644 --- a/pyrogram/client/types/messages_and_media/message.py +++ b/pyrogram/client/types/messages_and_media/message.py @@ -2928,7 +2928,7 @@ class Message(PyrogramType, Update): True on success. Raises: - :class:`RPCError ` + RPCError: In case of a Telegram RPC error. """ return self._client.pin_chat_message( chat_id=self.chat.id, diff --git a/setup.py b/setup.py index f0d6d030..a255dc5f 100644 --- a/setup.py +++ b/setup.py @@ -122,6 +122,7 @@ class Generate(Command): if len(argv) > 1 and argv[1] in ["bdist_wheel", "install", "develop"]: api_compiler.start() error_compiler.start() + docs_compiler.start() setup( name="Pyrogram",