TeamPGM/pyrogram
2
0
Fork 0
mirror of https://github.com/TeamPGM/pyrogram.git synced 2024-11-16 04:35:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs revamp. Part 7

Browse Source
This commit is contained in:
Dan 2019-05-23 18:59:29 +02:00
parent d34daa9edc
commit 47c06fdae2
22 changed files with 327 additions and 314 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
README.md
View File

@ -16,15 +16,6 @@
<a href="https://t.me/Pyrogram">
Community
</a>
<br>
<a href="compiler/api/source/main_api.tl">
<img src="https://img.shields.io/badge/schema-layer%2097-eda738.svg?longCache=true&colorA=262b30"
alt="Schema Layer">
</a>
<a href="https://github.com/pyrogram/tgcrypto">
<img src="https://img.shields.io/badge/tgcrypto-v1.1.1-eda738.svg?longCache=true&colorA=262b30"
alt="TgCrypto Version">
</a>
</p>
## Pyrogram

BIN
docs/source/_images/logo.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 13 KiB

2
docs/source/api/client.rst
View File

@ -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

2
docs/source/api/decorators.rst
View File

@ -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()

214
docs/source/conf.py
View File

@ -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 <https://github.com/delivrance>
#
# 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 <http://www.gnu.org/licenses/>.
# 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"

104
docs/source/meta/faq.rst → docs/source/faq.rst
View File

@ -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 <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.
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

22
docs/source/meta/glossary.rst → docs/source/glossary.rst
View File

@ -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 <intro/setup#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 <start/errors>`_.
MTProto
The name of the custom-made, open and encrypted protocol by Telegram, implemented in Pyrogram.
`More on MTProto <mtproto-vs-botapi>`_.
`More on MTProto <topics/mtproto-vs-botapi>`_.
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 <mtproto-vs-botapi#what-is-the-mtproto-api>`_.
`More on MTProto API <topics/mtproto-vs-botapi#what-is-the-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 <mtproto-vs-botapi#what-is-the-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 <topics/mtproto-vs-botapi#what-is-the-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 <start/updates>`_.
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 <start/updates#using-decorators>`_.
.. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md

68
docs/source/index.rst
View File

@ -4,8 +4,8 @@ Welcome to Pyrogram
.. raw:: html
<div align="center">
<a href="https://docs.pyrogram.org">
<div><img src="_static/logo.png" alt="Pyrogram Logo"></div>
<a href="/">
<div><img src="_static/pyrogram.png" alt="Pyrogram Logo" width="420"></div>
</a>
</div>
@ -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:

4
docs/source/intro/install.rst
View File

@ -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

2
docs/source/intro/setup.rst
View File

@ -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

2
docs/source/meta/support-pyrogram.rst
View File

@ -1,2 +0,0 @@
Support Pyrogram Development
============================

4
docs/source/meta/powered-by.rst → docs/source/powered-by.rst
View File

@ -55,8 +55,8 @@ Projects Showcase
-----
`BotListBot <https://t.me/botlistt>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
`BotListBot <https://t.me/botlist>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| **A bot which partly uses Pyrogram to check if other bots are still alive**
| --- by `JosXa <https://t.me/JosXa>`_

0
docs/source/meta/releases.rst → docs/source/releases.rst
View File

4
docs/source/start/auth.rst
View File

@ -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 <pyrogram.Client>` class by passing to it a ``session_name`` of your choice (e.g.: "my_account") and call
the :meth:`run() <pyrogram.Client.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 <setup.html#configuration>`_ 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

26
docs/source/support-pyrogram.rst Normal file
View File

@ -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
<a class="github-button" href="https://github.com/pyrogram/pyrogram" data-size="large" data-show-count="true" aria-label="Star pyrogram/pyrogram on GitHub">Star</a>
<br><br>
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

106
docs/source/topics/mtproto-vs-botapi.rst
View File

@ -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.
.. 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

55
docs/source/topics/serialize.rst Normal file
View File

@ -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.

2
docs/source/topics/session-settings.rst
View File

@ -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.**

4
docs/source/topics/tgcrypto.rst
View File

@ -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.

8
pyrogram/client/client.py
View File

@ -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.

2
pyrogram/client/types/messages_and_media/message.py
View File

@ -2928,7 +2928,7 @@ class Message(PyrogramType, Update):
True on success.
Raises:
:class:`RPCError <pyrogram.RPCError>`
RPCError: In case of a Telegram RPC error.
"""
return self._client.pin_chat_message(
chat_id=self.chat.id,

1
setup.py
View File

@ -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",