mirror of
https://github.com/pyrogram/pyrogram
synced 2025-08-29 05:18:10 +00:00
Merge develop -> asyncio
This commit is contained in:
Dan
commit
39439255fd
76
.github/CODE_OF_CONDUCT.md
vendored
Normal file
76
.github/CODE_OF_CONDUCT.md
vendored
Normal file
@ -0,0 +1,76 @@
|
||||
# Contributor Covenant Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
In the interest of fostering an open and welcoming environment, we as
|
||||
contributors and maintainers pledge to making participation in our project and
|
||||
our community a harassment-free experience for everyone, regardless of age, body
|
||||
size, disability, ethnicity, sex characteristics, gender identity and expression,
|
||||
level of experience, education, socio-economic status, nationality, personal
|
||||
appearance, race, religion, or sexual identity and orientation.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to creating a positive environment
|
||||
include:
|
||||
|
||||
* Using welcoming and inclusive language
|
||||
* Being respectful of differing viewpoints and experiences
|
||||
* Gracefully accepting constructive criticism
|
||||
* Focusing on what is best for the community
|
||||
* Showing empathy towards other community members
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
|
||||
* The use of sexualized language or imagery and unwelcome sexual attention or
|
||||
advances
|
||||
* Trolling, insulting/derogatory comments, and personal or political attacks
|
||||
* Public or private harassment
|
||||
* Publishing others' private information, such as a physical or electronic
|
||||
address, without explicit permission
|
||||
* Other conduct which could reasonably be considered inappropriate in a
|
||||
professional setting
|
||||
|
||||
## Our Responsibilities
|
||||
|
||||
Project maintainers are responsible for clarifying the standards of acceptable
|
||||
behavior and are expected to take appropriate and fair corrective action in
|
||||
response to any instances of unacceptable behavior.
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or
|
||||
reject comments, commits, code, wiki edits, issues, and other contributions
|
||||
that are not aligned to this Code of Conduct, or to ban temporarily or
|
||||
permanently any contributor for other behaviors that they deem inappropriate,
|
||||
threatening, offensive, or harmful.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies both within project spaces and in public spaces
|
||||
when an individual is representing the project or its community. Examples of
|
||||
representing a project or community include using an official project e-mail
|
||||
address, posting via an official social media account, or acting as an appointed
|
||||
representative at an online or offline event. Representation of a project may be
|
||||
further defined and clarified by project maintainers.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
||||
reported by contacting the project team at dan@pyrogram.org. All
|
||||
complaints will be reviewed and investigated and will result in a response that
|
||||
is deemed necessary and appropriate to the circumstances. The project team is
|
||||
obligated to maintain confidentiality with regard to the reporter of an incident.
|
||||
Further details of specific enforcement policies may be posted separately.
|
||||
|
||||
Project maintainers who do not follow or enforce the Code of Conduct in good
|
||||
faith may face temporary or permanent repercussions as determined by other
|
||||
members of the project's leadership.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
|
||||
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
|
||||
For answers to common questions about this code of conduct, see
|
||||
https://www.contributor-covenant.org/faq
|
||||
1
.github/CONTRIBUTING.md
vendored
Normal file
1
.github/CONTRIBUTING.md
vendored
Normal file
@ -0,0 +1 @@
|
||||
# How to Contribute
|
||||
21
.github/ISSUE_TEMPLATE/bug_report.md
vendored
Normal file
21
.github/ISSUE_TEMPLATE/bug_report.md
vendored
Normal file
@ -0,0 +1,21 @@
|
||||
---
|
||||
name: Bug Report
|
||||
about: Create a bug report affecting the library
|
||||
labels: "bug"
|
||||
---
|
||||
|
||||
<!-- WARNING: Ignoring this template will lead to the issue being closed as incomplete -->
|
||||
|
||||
## Checklist
|
||||
- [ ] I am sure the error is coming from Pyrogram's code and not elsewhere.
|
||||
- [ ] I have searched in the issue tracker for similar bug reports, including closed ones.
|
||||
- [ ] I ran `pip3 install -U https://github.com/pyrogram/pyrogram/archive/develop.zip` and reproduced the issue using the latest development version.
|
||||
|
||||
## Description
|
||||
A clear and concise description of the problem.
|
||||
|
||||
## Steps to Reproduce
|
||||
[A minimal, complete and verifiable example](https://stackoverflow.com/help/mcve).
|
||||
|
||||
## Traceback
|
||||
The full traceback (if applicable).
|
||||
14
.github/ISSUE_TEMPLATE/feature_request.md
vendored
Normal file
14
.github/ISSUE_TEMPLATE/feature_request.md
vendored
Normal file
@ -0,0 +1,14 @@
|
||||
---
|
||||
name: Feature Request
|
||||
about: Suggest ideas, new features or enhancements
|
||||
labels: "enhancement"
|
||||
---
|
||||
|
||||
<!-- WARNING: Ignoring this template will lead to the issue being closed as incomplete -->
|
||||
|
||||
## Checklist
|
||||
- [ ] I believe the idea is awesome and would benefit the library.
|
||||
- [ ] I have searched in the issue tracker for similar requests, including closed ones.
|
||||
|
||||
## Description
|
||||
A detailed description of the request.
|
||||
15
.github/ISSUE_TEMPLATE/question.md
vendored
Normal file
15
.github/ISSUE_TEMPLATE/question.md
vendored
Normal file
@ -0,0 +1,15 @@
|
||||
---
|
||||
name: Ask Question
|
||||
about: Ask a Pyrogram related question
|
||||
title: For Q&A purposes, please read this template body
|
||||
labels: "question"
|
||||
---
|
||||
|
||||
<!-- WARNING: Ignoring this template will lead to the issue being closed as incomplete -->
|
||||
|
||||
# Important
|
||||
This place is for issues about Pyrogram, it's **not a forum**.
|
||||
|
||||
If you'd like to post a question, please move to https://stackoverflow.com or join the Telegram community by following the description in https://t.me/pyrogram.
|
||||
|
||||
Thanks.
|
||||
@ -1,5 +1,5 @@
|
||||
## Include
|
||||
include COPYING COPYING.lesser NOTICE requirements.txt
|
||||
include README.md COPYING COPYING.lesser NOTICE requirements.txt
|
||||
recursive-include compiler *.py *.tl *.tsv *.txt
|
||||
recursive-include pyrogram mime.types
|
||||
|
||||
|
||||
85
README.md
Normal file
85
README.md
Normal file
@ -0,0 +1,85 @@
|
||||
<p align="center">
|
||||
<a href="https://github.com/pyrogram/pyrogram">
|
||||
<img src="https://i.imgur.com/BOgY9ai.png" alt="Pyrogram">
|
||||
</a>
|
||||
<br>
|
||||
<b>Telegram MTProto API Framework for Python</b>
|
||||
<br>
|
||||
<a href="https://docs.pyrogram.org">
|
||||
Documentation
|
||||
</a>
|
||||
•
|
||||
<a href="https://github.com/pyrogram/pyrogram/releases">
|
||||
Releases
|
||||
</a>
|
||||
•
|
||||
<a href="https://t.me/Pyrogram">
|
||||
Community
|
||||
</a>
|
||||
</p>
|
||||
|
||||
## Pyrogram
|
||||
|
||||
``` python
|
||||
from pyrogram import Client, Filters
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
|
||||
@app.on_message(Filters.private)
|
||||
def hello(client, message):
|
||||
message.reply("Hello {}".format(message.from_user.first_name))
|
||||
|
||||
|
||||
app.run()
|
||||
```
|
||||
|
||||
**Pyrogram** is an elegant, easy-to-use [Telegram](https://telegram.org/) client library and framework written from the
|
||||
ground up in Python and C. It enables you to easily create custom apps for both user and bot identities (bot API alternative) via the [MTProto API](https://core.telegram.org/api#telegram-api).
|
||||
|
||||
> [Pyrogram in fully-asynchronous mode is also available »](https://github.com/pyrogram/pyrogram/issues/181)
|
||||
>
|
||||
> [Working PoC of Telegram voice calls using Pyrogram »](https://github.com/bakatrouble/pytgvoip)
|
||||
|
||||
### Features
|
||||
|
||||
- **Easy**: You can install Pyrogram with pip and start building your applications right away.
|
||||
- **Elegant**: Low-level details are abstracted and re-presented in a much nicer and easier way.
|
||||
- **Fast**: Crypto parts are boosted up by [TgCrypto](https://github.com/pyrogram/tgcrypto), a high-performance library
|
||||
written in pure C.
|
||||
- **Documented**: Pyrogram API methods, types and public interfaces are well documented.
|
||||
- **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted.
|
||||
- **Updated**, to make use of the latest Telegram API version and features.
|
||||
- **Bot API-like**: Similar to the Bot API in its simplicity, but much more powerful and detailed.
|
||||
- **Pluggable**: The Smart Plugin system allows to write components with minimal boilerplate code.
|
||||
- **Comprehensive**: Execute any advanced action an official client is able to do, and even more.
|
||||
|
||||
### Requirements
|
||||
|
||||
- Python 3.4 or higher.
|
||||
- A [Telegram API key](https://docs.pyrogram.org/intro/setup#api-keys).
|
||||
|
||||
### Installing
|
||||
|
||||
``` bash
|
||||
pip3 install pyrogram
|
||||
```
|
||||
|
||||
### Resources
|
||||
|
||||
- The Docs contain lots of resources to help you getting started with Pyrogram: https://docs.pyrogram.org.
|
||||
- Reading [Examples in this repository](https://github.com/pyrogram/pyrogram/tree/master/examples) is also a good way
|
||||
for learning how Pyrogram works.
|
||||
- Seeking extra help? Don't be shy, come join and ask our [Community](https://t.me/PyrogramChat)!
|
||||
- For other requests you can send an [Email](mailto:dan@pyrogram.org) or a [Message](https://t.me/haskell).
|
||||
|
||||
### Contributing
|
||||
|
||||
Pyrogram is brand new, and **you are welcome to try it and help make it even better** by either submitting pull
|
||||
requests or reporting issues/bugs as well as suggesting best practices, ideas, enhancements on both code
|
||||
and documentation. Any help is appreciated!
|
||||
|
||||
### Copyright & License
|
||||
|
||||
- Copyright (C) 2017-2019 Dan Tès <<https://github.com/delivrance>>
|
||||
- Licensed under the terms of the [GNU Lesser General Public License v3 or later (LGPLv3+)](COPYING.lesser)
|
||||
131
README.rst
131
README.rst
@ -1,131 +0,0 @@
|
||||
|header|
|
||||
|
||||
Pyrogram
|
||||
========
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client, Filters
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
|
||||
@app.on_message(Filters.private)
|
||||
def hello(client, message):
|
||||
message.reply("Hello {}".format(message.from_user.first_name))
|
||||
|
||||
|
||||
app.run()
|
||||
|
||||
**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and C.
|
||||
It enables you to easily create custom apps using both user and bot identities (bot API alternative) via the `MTProto API`_.
|
||||
|
||||
`Pyrogram in fully-asynchronous mode is also available » <https://github.com/pyrogram/pyrogram/issues/181>`_
|
||||
|
||||
`Working PoC of Telegram voice calls using Pyrogram » <https://github.com/bakatrouble/pytgvoip>`_
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
- **Easy**: You can install Pyrogram with pip and start building your applications right away.
|
||||
- **Elegant**: Low-level details are abstracted and re-presented in a much nicer and easier way.
|
||||
- **Fast**: Crypto parts are boosted up by TgCrypto_, a high-performance library written in pure C.
|
||||
- **Documented**: Pyrogram API methods, types and public interfaces are well documented.
|
||||
- **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted.
|
||||
- **Updated**, to the latest Telegram API version, currently Layer 97 on top of `MTProto 2.0`_.
|
||||
- **Pluggable**: The Smart Plugin system allows to write components with minimal boilerplate code.
|
||||
- **Comprehensive**: Execute any advanced action an official client is able to do, and even more.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
- Python 3.4 or higher.
|
||||
- A `Telegram API key`_.
|
||||
|
||||
Installing
|
||||
----------
|
||||
|
||||
.. code:: shell
|
||||
|
||||
pip3 install pyrogram
|
||||
|
||||
Resources
|
||||
---------
|
||||
|
||||
- The Docs contain lots of resources to help you getting started with Pyrogram: https://docs.pyrogram.ml.
|
||||
- Reading `Examples in this repository`_ is also a good way for learning how Pyrogram works.
|
||||
- Seeking extra help? Don't be shy, come join and ask our Community_!
|
||||
- For other requests you can send an Email_ or a Message_.
|
||||
|
||||
Contributing
|
||||
------------
|
||||
|
||||
Pyrogram is brand new, and **you are welcome to try it and help make it even better** by either submitting pull
|
||||
requests or reporting issues/bugs as well as suggesting best practices, ideas, enhancements on both code
|
||||
and documentation. Any help is appreciated!
|
||||
|
||||
Copyright & License
|
||||
-------------------
|
||||
|
||||
- Copyright (C) 2017-2019 Dan Tès <https://github.com/delivrance>
|
||||
- Licensed under the terms of the `GNU Lesser General Public License v3 or later (LGPLv3+)`_
|
||||
|
||||
.. _`Telegram`: https://telegram.org/
|
||||
.. _`MTProto API`: https://core.telegram.org/api#telegram-api
|
||||
.. _`Telegram API key`: https://docs.pyrogram.ml/start/ProjectSetup#api-keys
|
||||
.. _`Community`: https://t.me/PyrogramChat
|
||||
.. _`Examples in this repository`: https://github.com/pyrogram/pyrogram/tree/master/examples
|
||||
.. _`GitHub`: https://github.com/pyrogram/pyrogram/issues
|
||||
.. _`Email`: admin@pyrogram.ml
|
||||
.. _`Message`: https://t.me/haskell
|
||||
.. _TgCrypto: https://github.com/pyrogram/tgcrypto
|
||||
.. _`MTProto 2.0`: https://core.telegram.org/mtproto
|
||||
.. _`GNU Lesser General Public License v3 or later (LGPLv3+)`: COPYING.lesser
|
||||
|
||||
.. |header| raw:: html
|
||||
|
||||
<h1 align="center">
|
||||
<a href="https://github.com/pyrogram/pyrogram">
|
||||
<div><img src="https://raw.githubusercontent.com/pyrogram/logos/master/logos/pyrogram_logo2.png" alt="Pyrogram Logo"></div>
|
||||
</a>
|
||||
</h1>
|
||||
|
||||
<p align="center">
|
||||
<b>Telegram MTProto API Framework for Python</b>
|
||||
|
||||
<br>
|
||||
<a href="https://docs.pyrogram.ml">
|
||||
Documentation
|
||||
</a>
|
||||
•
|
||||
<a href="https://github.com/pyrogram/pyrogram/releases">
|
||||
Changelog
|
||||
</a>
|
||||
•
|
||||
<a href="https://t.me/PyrogramChat">
|
||||
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>
|
||||
|
||||
.. |logo| image:: https://raw.githubusercontent.com/pyrogram/logos/master/logos/pyrogram_logo2.png
|
||||
:target: https://pyrogram.ml
|
||||
:alt: Pyrogram
|
||||
|
||||
.. |description| replace:: **Telegram MTProto API Framework for Python**
|
||||
|
||||
.. |schema| image:: https://img.shields.io/badge/schema-layer%2097-eda738.svg?longCache=true&colorA=262b30
|
||||
:target: compiler/api/source/main_api.tl
|
||||
:alt: Schema Layer
|
||||
|
||||
.. |tgcrypto| image:: https://img.shields.io/badge/tgcrypto-v1.1.1-eda738.svg?longCache=true&colorA=262b30
|
||||
:target: https://github.com/pyrogram/tgcrypto
|
||||
:alt: TgCrypto Version
|
||||
@ -328,15 +328,15 @@ def start():
|
||||
)
|
||||
|
||||
if docstring_args:
|
||||
docstring_args = "Args:\n " + "\n ".join(docstring_args)
|
||||
docstring_args = "Parameters:\n " + "\n ".join(docstring_args)
|
||||
else:
|
||||
docstring_args = "No parameters required."
|
||||
|
||||
docstring_args = "Attributes:\n ID: ``{}``\n\n ".format(c.id) + docstring_args
|
||||
|
||||
if c.section == "functions":
|
||||
docstring_args += "\n\n Raises:\n :obj:`RPCError <pyrogram.RPCError>`"
|
||||
docstring_args += "\n\n Returns:\n " + get_docstring_arg_type(c.return_type)
|
||||
|
||||
else:
|
||||
references = get_references(".".join(filter(None, [c.namespace, c.name])))
|
||||
|
||||
@ -462,7 +462,7 @@ def start():
|
||||
["{0}={0}".format(i[0]) for i in sorted_args if i != ("flags", "#")]
|
||||
),
|
||||
slots=", ".join(['"{}"'.format(i[0]) for i in sorted_args if i != ("flags", "#")]),
|
||||
qualname="{}{}".format("{}.".format(c.namespace) if c.namespace else "", c.name)
|
||||
qualname="{}.{}{}".format(c.section, "{}.".format(c.namespace) if c.namespace else "", c.name)
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
@ -21,7 +21,7 @@ import os
|
||||
import shutil
|
||||
|
||||
HOME = "compiler/docs"
|
||||
DESTINATION = "docs/source"
|
||||
DESTINATION = "docs/source/telegram"
|
||||
|
||||
FUNCTIONS_PATH = "pyrogram/api/functions"
|
||||
TYPES_PATH = "pyrogram/api/types"
|
||||
@ -129,6 +129,6 @@ if "__main__" == __name__:
|
||||
FUNCTIONS_PATH = "../../pyrogram/api/functions"
|
||||
TYPES_PATH = "../../pyrogram/api/types"
|
||||
HOME = "."
|
||||
DESTINATION = "../../docs/source"
|
||||
DESTINATION = "../../docs/source/telegram"
|
||||
|
||||
start()
|
||||
|
||||
2
compiler/docs/template/page.txt
vendored
2
compiler/docs/template/page.txt
vendored
@ -1,5 +1,5 @@
|
||||
{title}
|
||||
{title_markup}
|
||||
|
||||
.. autoclass:: {full_class_path}
|
||||
.. autoclass:: {full_class_path}()
|
||||
:members:
|
||||
|
||||
@ -96,4 +96,6 @@ EXTERNAL_URL_INVALID The external media URL is invalid
|
||||
CHAT_NOT_MODIFIED The chat settings were not modified
|
||||
RESULTS_TOO_MUCH The result contains too many items
|
||||
RESULT_ID_DUPLICATE The result contains items with duplicated identifiers
|
||||
ACCESS_TOKEN_INVALID The bot access token is invalid
|
||||
ACCESS_TOKEN_INVALID The bot access token is invalid
|
||||
INVITE_HASH_EXPIRED The chat invite link is no longer valid
|
||||
USER_BANNED_IN_CHANNEL You are limited, check @SpamBot for details
|
||||
|
@ -2,4 +2,6 @@ id message
|
||||
CHAT_WRITE_FORBIDDEN You don't have rights to send messages in this chat
|
||||
RIGHT_FORBIDDEN One or more admin rights can't be applied to this kind of chat (channel/supergroup)
|
||||
CHAT_ADMIN_INVITE_REQUIRED You don't have rights to invite other users
|
||||
MESSAGE_DELETE_FORBIDDEN You don't have rights to delete messages in this chat
|
||||
MESSAGE_DELETE_FORBIDDEN You don't have rights to delete messages in this chat
|
||||
CHAT_SEND_MEDIA_FORBIDDEN You can't send media messages in this chat
|
||||
MESSAGE_AUTHOR_REQUIRED You are not the author of this message
|
||||
|
@ -5,4 +5,7 @@ RPC_MCGET_FAIL Telegram is having internal problems. Please try again later
|
||||
PERSISTENT_TIMESTAMP_OUTDATED Telegram is having internal problems. Please try again later
|
||||
HISTORY_GET_FAILED Telegram is having internal problems. Please try again later
|
||||
REG_ID_GENERATE_FAILED Telegram is having internal problems. Please try again later
|
||||
RANDOM_ID_DUPLICATE Telegram is having internal problems. Please try again later
|
||||
RANDOM_ID_DUPLICATE Telegram is having internal problems. Please try again later
|
||||
WORKER_BUSY_TOO_LONG_RETRY Telegram is having internal problems. Please try again later
|
||||
INTERDC_X_CALL_ERROR Telegram is having internal problems. Please try again later
|
||||
INTERDC_X_CALL_RICH_ERROR Telegram is having internal problems. Please try again later
|
||||
|
3
docs/robots.txt
Normal file
3
docs/robots.txt
Normal file
@ -0,0 +1,3 @@
|
||||
User-agent: *
|
||||
Allow: /
|
||||
Sitemap: https://docs.pyrogram.org/sitemap.xml
|
||||
@ -18,17 +18,16 @@
|
||||
|
||||
import datetime
|
||||
import os
|
||||
import re
|
||||
|
||||
canonical = "https://docs.pyrogram.ml"
|
||||
canonical = "https://docs.pyrogram.org/"
|
||||
|
||||
dirs = {
|
||||
"start": ("weekly", 0.9),
|
||||
"resources": ("weekly", 0.8),
|
||||
"pyrogram": ("weekly", 0.8),
|
||||
"functions": ("monthly", 0.7),
|
||||
"types": ("monthly", 0.7),
|
||||
"errors": ("weekly", 0.6)
|
||||
".": ("weekly", 1.0),
|
||||
"intro": ("weekly", 0.8),
|
||||
"start": ("weekly", 0.8),
|
||||
"api": ("weekly", 0.6),
|
||||
"topics": ("weekly", 0.6),
|
||||
"telegram": ("weekly", 0.4)
|
||||
}
|
||||
|
||||
|
||||
@ -37,10 +36,10 @@ def now():
|
||||
|
||||
|
||||
with open("sitemap.xml", "w") as f:
|
||||
f.write("<?xml version=\"1.0\" encoding=\"utf-8\"?>\n")
|
||||
f.write("<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n")
|
||||
f.write('<?xml version="1.0" encoding="utf-8"?>\n')
|
||||
f.write('<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n')
|
||||
|
||||
urls = [(canonical, now(), "weekly", 1.0)]
|
||||
urls = []
|
||||
|
||||
|
||||
def search(path):
|
||||
@ -48,14 +47,27 @@ with open("sitemap.xml", "w") as f:
|
||||
for j in os.listdir(path):
|
||||
search("{}/{}".format(path, j))
|
||||
except NotADirectoryError:
|
||||
d = path.split("/")[0]
|
||||
path = "{}/{}".format(canonical, path.split(".")[0])
|
||||
path = re.sub("^(.+)/index$", "\g<1>", path)
|
||||
urls.append((path, now(), dirs[d][0], dirs[d][1]))
|
||||
if not path.endswith(".rst"):
|
||||
return
|
||||
|
||||
path = path.split("/")[1:]
|
||||
|
||||
if path[0].endswith(".rst"):
|
||||
folder = "."
|
||||
else:
|
||||
folder = path[0]
|
||||
|
||||
path = "{}{}".format(canonical, "/".join(path))[:-len(".rst")]
|
||||
|
||||
if path.endswith("index"):
|
||||
path = path[:-len("index")]
|
||||
|
||||
urls.append((path, now(), *dirs[folder]))
|
||||
|
||||
|
||||
for i in dirs.keys():
|
||||
search(i)
|
||||
search("source")
|
||||
|
||||
urls.sort(key=lambda x: x[3], reverse=True)
|
||||
|
||||
for i in urls:
|
||||
f.write(" <url>\n")
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 13 KiB |
BIN
docs/source/_images/pyrogram.png
Normal file
BIN
docs/source/_images/pyrogram.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
102
docs/source/api/bound-methods.rst
Normal file
102
docs/source/api/bound-methods.rst
Normal file
@ -0,0 +1,102 @@
|
||||
Bound Methods
|
||||
=============
|
||||
|
||||
Some Pyrogram types define what are called bound methods. Bound methods are functions attached to a class which are
|
||||
accessed via an instance of that class. They make it even easier to call specific methods by automatically inferring
|
||||
some of the required arguments.
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 8
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
|
||||
@app.on_message()
|
||||
def hello(client, message)
|
||||
message.reply("hi")
|
||||
|
||||
|
||||
app.run()
|
||||
|
||||
.. currentmodule:: pyrogram
|
||||
|
||||
- Message_
|
||||
- CallbackQuery_
|
||||
- InlineQuery_
|
||||
|
||||
.. _Message:
|
||||
|
||||
Message
|
||||
-------
|
||||
|
||||
- :meth:`Message.click()`
|
||||
- :meth:`Message.delete()`
|
||||
- :meth:`Message.download()`
|
||||
- :meth:`Message.edit()`
|
||||
- :meth:`Message.edit_caption()`
|
||||
- :meth:`Message.edit_media()`
|
||||
- :meth:`Message.edit_reply_markup()`
|
||||
- :meth:`Message.forward()`
|
||||
- :meth:`Message.pin()`
|
||||
- :meth:`Message.reply()`
|
||||
- :meth:`Message.reply_animation()`
|
||||
- :meth:`Message.reply_audio()`
|
||||
- :meth:`Message.reply_cached_media()`
|
||||
- :meth:`Message.reply_chat_action()`
|
||||
- :meth:`Message.reply_contact()`
|
||||
- :meth:`Message.reply_document()`
|
||||
- :meth:`Message.reply_game()`
|
||||
- :meth:`Message.reply_inline_bot_result()`
|
||||
- :meth:`Message.reply_location()`
|
||||
- :meth:`Message.reply_media_group()`
|
||||
- :meth:`Message.reply_photo()`
|
||||
- :meth:`Message.reply_poll()`
|
||||
- :meth:`Message.reply_sticker()`
|
||||
- :meth:`Message.reply_venue()`
|
||||
- :meth:`Message.reply_video()`
|
||||
- :meth:`Message.reply_video_note()`
|
||||
- :meth:`Message.reply_voice()`
|
||||
|
||||
.. automethod:: Message.click()
|
||||
.. automethod:: Message.delete()
|
||||
.. automethod:: Message.download()
|
||||
.. automethod:: Message.edit()
|
||||
.. automethod:: Message.edit_caption()
|
||||
.. automethod:: Message.edit_media()
|
||||
.. automethod:: Message.edit_reply_markup()
|
||||
.. automethod:: Message.forward()
|
||||
.. automethod:: Message.pin()
|
||||
.. automethod:: Message.reply()
|
||||
.. automethod:: Message.reply_animation()
|
||||
.. automethod:: Message.reply_audio()
|
||||
.. automethod:: Message.reply_cached_media()
|
||||
.. automethod:: Message.reply_chat_action()
|
||||
.. automethod:: Message.reply_contact()
|
||||
.. automethod:: Message.reply_document()
|
||||
.. automethod:: Message.reply_game()
|
||||
.. automethod:: Message.reply_inline_bot_result()
|
||||
.. automethod:: Message.reply_location()
|
||||
.. automethod:: Message.reply_media_group()
|
||||
.. automethod:: Message.reply_photo()
|
||||
.. automethod:: Message.reply_poll()
|
||||
.. automethod:: Message.reply_sticker()
|
||||
.. automethod:: Message.reply_venue()
|
||||
.. automethod:: Message.reply_video()
|
||||
.. automethod:: Message.reply_video_note()
|
||||
.. automethod:: Message.reply_voice()
|
||||
|
||||
.. _CallbackQuery:
|
||||
|
||||
CallbackQuery
|
||||
-------------
|
||||
|
||||
.. automethod:: CallbackQuery.answer()
|
||||
|
||||
.. _InlineQuery:
|
||||
|
||||
InlineQuery
|
||||
-----------
|
||||
|
||||
.. automethod:: InlineQuery.answer()
|
||||
16
docs/source/api/client.rst
Normal file
16
docs/source/api/client.rst
Normal file
@ -0,0 +1,16 @@
|
||||
Pyrogram Client
|
||||
===============
|
||||
|
||||
This is the Client class. It exposes high-level methods for an easy access to the API.
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 1-3
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
with app:
|
||||
app.send_message("me", "Hi!")
|
||||
|
||||
.. autoclass:: pyrogram.Client()
|
||||
48
docs/source/api/decorators.rst
Normal file
48
docs/source/api/decorators.rst
Normal file
@ -0,0 +1,48 @@
|
||||
Decorators
|
||||
==========
|
||||
|
||||
While still being methods bound to the :obj:`Client <pyrogram.Client>` class, decorators are of a special kind and thus deserve a
|
||||
dedicated page.
|
||||
|
||||
Decorators are able to register callback functions for handling updates in a much easier and cleaner way compared to
|
||||
`Handlers <Handlers.html>`_; they do so by instantiating the correct handler and calling
|
||||
:meth:`add_handler() <pyrogram.Client.add_handler>`, automatically. All you need to do is adding the decorators on top
|
||||
of your functions.
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 6
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
|
||||
@app.on_message()
|
||||
def log(client, message):
|
||||
print(message)
|
||||
|
||||
|
||||
app.run()
|
||||
|
||||
.. currentmodule:: pyrogram.Client
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
on_message
|
||||
on_callback_query
|
||||
on_inline_query
|
||||
on_deleted_messages
|
||||
on_user_status
|
||||
on_poll
|
||||
on_disconnect
|
||||
on_raw_update
|
||||
|
||||
.. automethod:: pyrogram.Client.on_message()
|
||||
.. automethod:: pyrogram.Client.on_callback_query()
|
||||
.. 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()
|
||||
72
docs/source/api/errors.rst
Normal file
72
docs/source/api/errors.rst
Normal file
@ -0,0 +1,72 @@
|
||||
RPC Errors
|
||||
==========
|
||||
|
||||
All Pyrogram API errors live inside the ``errors`` sub-package: ``pyrogram.errors``.
|
||||
The errors ids listed here are shown as *UPPER_SNAKE_CASE*, but the actual exception names to import from Pyrogram
|
||||
follow the usual *PascalCase* convention.
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 1, 5
|
||||
|
||||
from pyrogram.errors import FloodWait
|
||||
|
||||
try:
|
||||
...
|
||||
except FloodWait as e:
|
||||
...
|
||||
|
||||
303 - SeeOther
|
||||
--------------
|
||||
|
||||
.. csv-table::
|
||||
:file: ../../../compiler/error/source/303_SEE_OTHER.tsv
|
||||
:delim: tab
|
||||
:header-rows: 1
|
||||
|
||||
400 - BadRequest
|
||||
----------------
|
||||
|
||||
.. csv-table::
|
||||
:file: ../../../compiler/error/source/400_BAD_REQUEST.tsv
|
||||
:delim: tab
|
||||
:header-rows: 1
|
||||
|
||||
401 - Unauthorized
|
||||
------------------
|
||||
|
||||
.. csv-table::
|
||||
:file: ../../../compiler/error/source/401_UNAUTHORIZED.tsv
|
||||
:delim: tab
|
||||
:header-rows: 1
|
||||
|
||||
403 - Forbidden
|
||||
---------------
|
||||
|
||||
.. csv-table::
|
||||
:file: ../../../compiler/error/source/403_FORBIDDEN.tsv
|
||||
:delim: tab
|
||||
:header-rows: 1
|
||||
|
||||
406 - NotAcceptable
|
||||
-------------------
|
||||
|
||||
.. csv-table::
|
||||
:file: ../../../compiler/error/source/406_NOT_ACCEPTABLE.tsv
|
||||
:delim: tab
|
||||
:header-rows: 1
|
||||
|
||||
420 - Flood
|
||||
-----------
|
||||
|
||||
.. csv-table::
|
||||
:file: ../../../compiler/error/source/420_FLOOD.tsv
|
||||
:delim: tab
|
||||
:header-rows: 1
|
||||
|
||||
500 - InternalServerError
|
||||
-------------------------
|
||||
|
||||
.. csv-table::
|
||||
:file: ../../../compiler/error/source/500_INTERNAL_SERVER_ERROR.tsv
|
||||
:delim: tab
|
||||
:header-rows: 1
|
||||
@ -1,5 +1,5 @@
|
||||
Filters
|
||||
=======
|
||||
Update Filters
|
||||
==============
|
||||
|
||||
.. autoclass:: pyrogram.Filters
|
||||
:members:
|
||||
47
docs/source/api/handlers.rst
Normal file
47
docs/source/api/handlers.rst
Normal file
@ -0,0 +1,47 @@
|
||||
Update Handlers
|
||||
===============
|
||||
|
||||
Handlers are used to instruct Pyrogram about which kind of updates you'd like to handle with your callback functions.
|
||||
|
||||
For a much more convenient way of registering callback functions have a look at `Decorators <Decorators.html>`_ instead.
|
||||
In case you decided to manually create a handler, use :meth:`add_handler() <pyrogram.Client.add_handler>` to register
|
||||
it.
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 1, 10
|
||||
|
||||
from pyrogram import Client, MessageHandler
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
|
||||
def dump(client, message):
|
||||
print(message)
|
||||
|
||||
|
||||
app.add_handler(MessageHandler(dump))
|
||||
|
||||
app.run()
|
||||
|
||||
.. currentmodule:: pyrogram
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
MessageHandler
|
||||
DeletedMessagesHandler
|
||||
CallbackQueryHandler
|
||||
InlineQueryHandler
|
||||
UserStatusHandler
|
||||
PollHandler
|
||||
DisconnectHandler
|
||||
RawUpdateHandler
|
||||
|
||||
.. autoclass:: MessageHandler()
|
||||
.. autoclass:: DeletedMessagesHandler()
|
||||
.. autoclass:: CallbackQueryHandler()
|
||||
.. autoclass:: InlineQueryHandler()
|
||||
.. autoclass:: UserStatusHandler()
|
||||
.. autoclass:: PollHandler()
|
||||
.. autoclass:: DisconnectHandler()
|
||||
.. autoclass:: RawUpdateHandler()
|
||||
265
docs/source/api/methods.rst
Normal file
265
docs/source/api/methods.rst
Normal file
@ -0,0 +1,265 @@
|
||||
Available Methods
|
||||
=================
|
||||
|
||||
All Pyrogram methods listed here are bound to a :obj:`Client <pyrogram.Client>` instance.
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 6
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
with app:
|
||||
app.send_message("haskell", "hi")
|
||||
|
||||
.. currentmodule:: pyrogram.Client
|
||||
|
||||
Utilities
|
||||
---------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
start
|
||||
stop
|
||||
restart
|
||||
idle
|
||||
run
|
||||
add_handler
|
||||
remove_handler
|
||||
send
|
||||
resolve_peer
|
||||
save_file
|
||||
stop_transmission
|
||||
|
||||
Messages
|
||||
--------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
send_message
|
||||
forward_messages
|
||||
send_photo
|
||||
send_audio
|
||||
send_document
|
||||
send_sticker
|
||||
send_video
|
||||
send_animation
|
||||
send_voice
|
||||
send_video_note
|
||||
send_media_group
|
||||
send_location
|
||||
send_venue
|
||||
send_contact
|
||||
send_cached_media
|
||||
send_chat_action
|
||||
edit_message_text
|
||||
edit_message_caption
|
||||
edit_message_reply_markup
|
||||
edit_message_media
|
||||
delete_messages
|
||||
get_messages
|
||||
get_history
|
||||
get_history_count
|
||||
iter_history
|
||||
send_poll
|
||||
vote_poll
|
||||
stop_poll
|
||||
retract_vote
|
||||
download_media
|
||||
|
||||
Chats
|
||||
-----
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
join_chat
|
||||
leave_chat
|
||||
kick_chat_member
|
||||
unban_chat_member
|
||||
restrict_chat_member
|
||||
promote_chat_member
|
||||
export_chat_invite_link
|
||||
set_chat_photo
|
||||
delete_chat_photo
|
||||
set_chat_title
|
||||
set_chat_description
|
||||
pin_chat_message
|
||||
unpin_chat_message
|
||||
get_chat
|
||||
get_chat_member
|
||||
get_chat_members
|
||||
get_chat_members_count
|
||||
iter_chat_members
|
||||
get_dialogs
|
||||
iter_dialogs
|
||||
get_dialogs_count
|
||||
restrict_chat
|
||||
update_chat_username
|
||||
|
||||
Users
|
||||
-----
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
get_me
|
||||
get_users
|
||||
get_user_profile_photos
|
||||
get_user_profile_photos_count
|
||||
set_user_profile_photo
|
||||
delete_user_profile_photos
|
||||
update_username
|
||||
|
||||
Contacts
|
||||
--------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
add_contacts
|
||||
get_contacts
|
||||
get_contacts_count
|
||||
delete_contacts
|
||||
|
||||
Password
|
||||
--------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
enable_cloud_password
|
||||
change_cloud_password
|
||||
remove_cloud_password
|
||||
|
||||
Bots
|
||||
----
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
get_inline_bot_results
|
||||
send_inline_bot_result
|
||||
answer_callback_query
|
||||
answer_inline_query
|
||||
request_callback_answer
|
||||
send_game
|
||||
set_game_score
|
||||
get_game_high_scores
|
||||
|
||||
.. Utilities
|
||||
---------
|
||||
|
||||
.. automethod:: pyrogram.Client.start()
|
||||
.. automethod:: pyrogram.Client.stop()
|
||||
.. automethod:: pyrogram.Client.restart()
|
||||
.. automethod:: pyrogram.Client.idle()
|
||||
.. automethod:: pyrogram.Client.run()
|
||||
.. automethod:: pyrogram.Client.add_handler()
|
||||
.. automethod:: pyrogram.Client.remove_handler()
|
||||
.. automethod:: pyrogram.Client.send()
|
||||
.. automethod:: pyrogram.Client.resolve_peer()
|
||||
.. automethod:: pyrogram.Client.save_file()
|
||||
.. automethod:: pyrogram.Client.stop_transmission()
|
||||
|
||||
.. Messages
|
||||
--------
|
||||
|
||||
.. automethod:: pyrogram.Client.send_message()
|
||||
.. automethod:: pyrogram.Client.forward_messages()
|
||||
.. automethod:: pyrogram.Client.send_photo()
|
||||
.. automethod:: pyrogram.Client.send_audio()
|
||||
.. automethod:: pyrogram.Client.send_document()
|
||||
.. automethod:: pyrogram.Client.send_sticker()
|
||||
.. automethod:: pyrogram.Client.send_video()
|
||||
.. automethod:: pyrogram.Client.send_animation()
|
||||
.. automethod:: pyrogram.Client.send_voice()
|
||||
.. automethod:: pyrogram.Client.send_video_note()
|
||||
.. automethod:: pyrogram.Client.send_media_group()
|
||||
.. automethod:: pyrogram.Client.send_location()
|
||||
.. automethod:: pyrogram.Client.send_venue()
|
||||
.. automethod:: pyrogram.Client.send_contact()
|
||||
.. automethod:: pyrogram.Client.send_cached_media()
|
||||
.. automethod:: pyrogram.Client.send_chat_action()
|
||||
.. automethod:: pyrogram.Client.edit_message_text()
|
||||
.. automethod:: pyrogram.Client.edit_message_caption()
|
||||
.. automethod:: pyrogram.Client.edit_message_reply_markup()
|
||||
.. automethod:: pyrogram.Client.edit_message_media()
|
||||
.. automethod:: pyrogram.Client.delete_messages()
|
||||
.. automethod:: pyrogram.Client.get_messages()
|
||||
.. automethod:: pyrogram.Client.get_history()
|
||||
.. automethod:: pyrogram.Client.get_history_count()
|
||||
.. automethod:: pyrogram.Client.iter_history()
|
||||
.. automethod:: pyrogram.Client.send_poll()
|
||||
.. automethod:: pyrogram.Client.vote_poll()
|
||||
.. automethod:: pyrogram.Client.stop_poll()
|
||||
.. automethod:: pyrogram.Client.retract_vote()
|
||||
.. automethod:: pyrogram.Client.download_media()
|
||||
|
||||
.. Chats
|
||||
-----
|
||||
|
||||
.. automethod:: pyrogram.Client.join_chat()
|
||||
.. automethod:: pyrogram.Client.leave_chat()
|
||||
.. automethod:: pyrogram.Client.kick_chat_member()
|
||||
.. automethod:: pyrogram.Client.unban_chat_member()
|
||||
.. automethod:: pyrogram.Client.restrict_chat_member()
|
||||
.. automethod:: pyrogram.Client.promote_chat_member()
|
||||
.. automethod:: pyrogram.Client.export_chat_invite_link()
|
||||
.. automethod:: pyrogram.Client.set_chat_photo()
|
||||
.. automethod:: pyrogram.Client.delete_chat_photo()
|
||||
.. automethod:: pyrogram.Client.set_chat_title()
|
||||
.. automethod:: pyrogram.Client.set_chat_description()
|
||||
.. automethod:: pyrogram.Client.pin_chat_message()
|
||||
.. automethod:: pyrogram.Client.unpin_chat_message()
|
||||
.. automethod:: pyrogram.Client.get_chat()
|
||||
.. automethod:: pyrogram.Client.get_chat_member()
|
||||
.. automethod:: pyrogram.Client.get_chat_members()
|
||||
.. automethod:: pyrogram.Client.get_chat_members_count()
|
||||
.. automethod:: pyrogram.Client.iter_chat_members()
|
||||
.. automethod:: pyrogram.Client.get_dialogs()
|
||||
.. automethod:: pyrogram.Client.iter_dialogs()
|
||||
.. automethod:: pyrogram.Client.get_dialogs_count()
|
||||
.. automethod:: pyrogram.Client.restrict_chat()
|
||||
.. automethod:: pyrogram.Client.update_chat_username()
|
||||
|
||||
.. Users
|
||||
-----
|
||||
|
||||
.. automethod:: pyrogram.Client.get_me()
|
||||
.. automethod:: pyrogram.Client.get_users()
|
||||
.. automethod:: pyrogram.Client.get_user_profile_photos()
|
||||
.. automethod:: pyrogram.Client.get_user_profile_photos_count()
|
||||
.. automethod:: pyrogram.Client.set_user_profile_photo()
|
||||
.. automethod:: pyrogram.Client.delete_user_profile_photos()
|
||||
.. automethod:: pyrogram.Client.update_username()
|
||||
|
||||
.. Contacts
|
||||
--------
|
||||
|
||||
.. automethod:: pyrogram.Client.add_contacts()
|
||||
.. automethod:: pyrogram.Client.get_contacts()
|
||||
.. automethod:: pyrogram.Client.get_contacts_count()
|
||||
.. automethod:: pyrogram.Client.delete_contacts()
|
||||
|
||||
.. Password
|
||||
--------
|
||||
|
||||
.. automethod:: pyrogram.Client.enable_cloud_password()
|
||||
.. automethod:: pyrogram.Client.change_cloud_password()
|
||||
.. automethod:: pyrogram.Client.remove_cloud_password()
|
||||
|
||||
.. Bots
|
||||
----
|
||||
|
||||
.. automethod:: pyrogram.Client.get_inline_bot_results()
|
||||
.. automethod:: pyrogram.Client.send_inline_bot_result()
|
||||
.. automethod:: pyrogram.Client.answer_callback_query()
|
||||
.. automethod:: pyrogram.Client.answer_inline_query()
|
||||
.. automethod:: pyrogram.Client.request_callback_answer()
|
||||
.. automethod:: pyrogram.Client.send_game()
|
||||
.. automethod:: pyrogram.Client.set_game_score()
|
||||
.. automethod:: pyrogram.Client.get_game_high_scores()
|
||||
184
docs/source/api/types.rst
Normal file
184
docs/source/api/types.rst
Normal file
@ -0,0 +1,184 @@
|
||||
Available Types
|
||||
===============
|
||||
|
||||
All Pyrogram types listed here are accessible through the main package directly.
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 1
|
||||
|
||||
from pyrogram import User, Message, ...
|
||||
|
||||
.. note::
|
||||
|
||||
**Optional** fields may not exist when irrelevant -- i.e.: they will contain the value of ``None`` and aren't shown
|
||||
when, for example, using ``print()``.
|
||||
|
||||
.. currentmodule:: pyrogram
|
||||
|
||||
Users & Chats
|
||||
-------------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
User
|
||||
UserStatus
|
||||
Chat
|
||||
ChatPreview
|
||||
ChatPhoto
|
||||
ChatMember
|
||||
ChatMembers
|
||||
ChatPermissions
|
||||
Dialog
|
||||
Dialogs
|
||||
|
||||
Messages & Media
|
||||
----------------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
Message
|
||||
Messages
|
||||
MessageEntity
|
||||
Photo
|
||||
PhotoSize
|
||||
UserProfilePhotos
|
||||
Audio
|
||||
Document
|
||||
Animation
|
||||
Video
|
||||
Voice
|
||||
VideoNote
|
||||
Contact
|
||||
Location
|
||||
Venue
|
||||
Sticker
|
||||
Game
|
||||
Poll
|
||||
PollOption
|
||||
|
||||
Keyboards
|
||||
---------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
ReplyKeyboardMarkup
|
||||
KeyboardButton
|
||||
ReplyKeyboardRemove
|
||||
InlineKeyboardMarkup
|
||||
InlineKeyboardButton
|
||||
ForceReply
|
||||
CallbackQuery
|
||||
GameHighScore
|
||||
GameHighScores
|
||||
CallbackGame
|
||||
|
||||
Input Media
|
||||
-----------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
InputMedia
|
||||
InputMediaPhoto
|
||||
InputMediaVideo
|
||||
InputMediaAudio
|
||||
InputMediaAnimation
|
||||
InputMediaDocument
|
||||
InputPhoneContact
|
||||
|
||||
Inline Mode
|
||||
------------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
InlineQuery
|
||||
InlineQueryResult
|
||||
InlineQueryResultArticle
|
||||
|
||||
InputMessageContent
|
||||
-------------------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
InputMessageContent
|
||||
InputTextMessageContent
|
||||
|
||||
.. User & Chats
|
||||
------------
|
||||
|
||||
.. autoclass:: User()
|
||||
.. autoclass:: UserStatus()
|
||||
.. autoclass:: Chat()
|
||||
.. autoclass:: ChatPreview()
|
||||
.. autoclass:: ChatPhoto()
|
||||
.. autoclass:: ChatMember()
|
||||
.. autoclass:: ChatMembers()
|
||||
.. autoclass:: ChatPermissions()
|
||||
.. autoclass:: Dialog()
|
||||
.. autoclass:: Dialogs()
|
||||
|
||||
.. Messages & Media
|
||||
----------------
|
||||
|
||||
.. autoclass:: Message()
|
||||
.. autoclass:: Messages()
|
||||
.. autoclass:: MessageEntity()
|
||||
.. autoclass:: Photo()
|
||||
.. autoclass:: PhotoSize()
|
||||
.. autoclass:: UserProfilePhotos()
|
||||
.. autoclass:: Audio()
|
||||
.. autoclass:: Document()
|
||||
.. autoclass:: Animation()
|
||||
.. autoclass:: Video()
|
||||
.. autoclass:: Voice()
|
||||
.. autoclass:: VideoNote()
|
||||
.. autoclass:: Contact()
|
||||
.. autoclass:: Location()
|
||||
.. autoclass:: Venue()
|
||||
.. autoclass:: Sticker()
|
||||
.. autoclass:: Game()
|
||||
.. autoclass:: Poll()
|
||||
.. autoclass:: PollOption()
|
||||
|
||||
.. Keyboards
|
||||
---------
|
||||
|
||||
.. autoclass:: ReplyKeyboardMarkup()
|
||||
.. autoclass:: KeyboardButton()
|
||||
.. autoclass:: ReplyKeyboardRemove()
|
||||
.. autoclass:: InlineKeyboardMarkup()
|
||||
.. autoclass:: InlineKeyboardButton()
|
||||
.. autoclass:: ForceReply()
|
||||
.. autoclass:: CallbackQuery()
|
||||
.. autoclass:: GameHighScore()
|
||||
.. autoclass:: GameHighScores()
|
||||
.. autoclass:: CallbackGame()
|
||||
|
||||
.. Input Media
|
||||
-----------
|
||||
|
||||
.. autoclass:: InputMedia()
|
||||
.. autoclass:: InputMediaPhoto()
|
||||
.. autoclass:: InputMediaVideo()
|
||||
.. autoclass:: InputMediaAudio()
|
||||
.. autoclass:: InputMediaAnimation()
|
||||
.. autoclass:: InputMediaDocument()
|
||||
.. autoclass:: InputPhoneContact()
|
||||
|
||||
.. Inline Mode
|
||||
-----------
|
||||
|
||||
.. autoclass:: InlineQuery()
|
||||
.. autoclass:: InlineQueryResult()
|
||||
.. autoclass:: InlineQueryResultArticle()
|
||||
|
||||
.. InputMessageContent
|
||||
-------------------
|
||||
|
||||
.. autoclass:: InputMessageContent()
|
||||
.. autoclass:: InputTextMessageContent()
|
||||
@ -1,198 +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"
|
||||
]
|
||||
|
||||
# Don't show source files on docs
|
||||
html_show_sourcelink = True
|
||||
master_doc = "index"
|
||||
source_suffix = ".rst"
|
||||
autodoc_member_order = "bysource"
|
||||
|
||||
# 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.
|
||||
version = __version__
|
||||
release = version
|
||||
version_rst = ".. |version| replace:: {}".format(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
|
||||
templates_path = ["_templates"]
|
||||
|
||||
# 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 = []
|
||||
napoleon_use_rtype = False
|
||||
|
||||
# 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.ml/",
|
||||
'collapse_navigation': False,
|
||||
'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"
|
||||
|
||||
@ -1,7 +0,0 @@
|
||||
400 - Bad Request
|
||||
=================
|
||||
|
||||
.. module:: pyrogram.errors.BadRequest
|
||||
|
||||
.. automodule:: pyrogram.errors.exceptions.bad_request_400
|
||||
:members:
|
||||
@ -1,7 +0,0 @@
|
||||
420 - Flood
|
||||
===========
|
||||
|
||||
.. module:: pyrogram.errors.Flood
|
||||
|
||||
.. automodule:: pyrogram.errors.exceptions.flood_420
|
||||
:members:
|
||||
@ -1,7 +0,0 @@
|
||||
403 - Forbidden
|
||||
===============
|
||||
|
||||
.. module:: pyrogram.errors.Forbidden
|
||||
|
||||
.. automodule:: pyrogram.errors.exceptions.forbidden_403
|
||||
:members:
|
||||
@ -1,7 +0,0 @@
|
||||
500 - Internal Server Error
|
||||
===========================
|
||||
|
||||
.. module:: pyrogram.errors.InternalServerError
|
||||
|
||||
.. automodule:: pyrogram.errors.exceptions.internal_server_error_500
|
||||
:members:
|
||||
@ -1,7 +0,0 @@
|
||||
406 - Not Acceptable
|
||||
====================
|
||||
|
||||
.. module:: pyrogram.errors.NotAcceptable
|
||||
|
||||
.. automodule:: pyrogram.errors.exceptions.not_acceptable_406
|
||||
:members:
|
||||
@ -1,7 +0,0 @@
|
||||
303 - See Other
|
||||
===============
|
||||
|
||||
.. module:: pyrogram.errors.SeeOther
|
||||
|
||||
.. automodule:: pyrogram.errors.exceptions.see_other_303
|
||||
:members:
|
||||
@ -1,7 +0,0 @@
|
||||
401 - Unauthorized
|
||||
==================
|
||||
|
||||
.. module:: pyrogram.errors.Unauthorized
|
||||
|
||||
.. automodule:: pyrogram.errors.exceptions.unauthorized_401
|
||||
:members:
|
||||
@ -1,7 +0,0 @@
|
||||
520 - Unknown Error
|
||||
===================
|
||||
|
||||
.. module:: pyrogram.errors.UnknownError
|
||||
|
||||
.. autoexception:: pyrogram.errors.rpc_error.UnknownError
|
||||
:members:
|
||||
201
docs/source/faq.rst
Normal file
201
docs/source/faq.rst
Normal file
@ -0,0 +1,201 @@
|
||||
Pyrogram FAQ
|
||||
============
|
||||
|
||||
This FAQ page provides answers to common questions about Pyrogram and, to some extent, Telegram in general.
|
||||
|
||||
.. tip::
|
||||
|
||||
If you think something interesting could be added here, feel free to propose it by opening a `Feature Request`_.
|
||||
|
||||
.. contents:: Contents
|
||||
:backlinks: none
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
What is Pyrogram?
|
||||
-----------------
|
||||
|
||||
**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and
|
||||
C. It enables you to easily create custom applications for both user and bot identities (bot API alternative) via the
|
||||
`MTProto API`_ with the Python programming language.
|
||||
|
||||
.. _Telegram: https://telegram.org
|
||||
.. _MTProto API: topics/mtproto-vs-botapi#what-is-the-mtproto-api
|
||||
|
||||
Where does the name come from?
|
||||
------------------------------
|
||||
|
||||
The name "Pyrogram" is composed by **pyro**, which comes from the Greek word *πῦρ (pyr)*, meaning fire, and **gram**,
|
||||
from *Telegram*. The word *pyro* itself is built from *Python*, **py** for short, and the suffix **ro** to come up with
|
||||
the word *fire*, which also inspired the project logo.
|
||||
|
||||
How old is Pyrogram?
|
||||
--------------------
|
||||
|
||||
Pyrogram was first released on December 12, 2017. The actual work on the framework began roughly three months prior the
|
||||
initial public release on `GitHub`_.
|
||||
|
||||
.. _GitHub: https://github.com/pyrogram/pyrogram
|
||||
|
||||
Why Pyrogram?
|
||||
-------------
|
||||
|
||||
- **Easy**: You can install Pyrogram with pip and start building your applications right away.
|
||||
- **Elegant**: Low-level details are abstracted and re-presented in a much nicer and easier way.
|
||||
- **Fast**: Crypto parts are boosted up by TgCrypto_, a high-performance library written in pure C.
|
||||
- **Documented**: Pyrogram API methods, types and public interfaces are well documented.
|
||||
- **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted.
|
||||
- **Updated**, to make use of the latest Telegram API version and features.
|
||||
- **Bot API-like**: Similar to the Bot API in its simplicity, but much more powerful and detailed.
|
||||
- **Pluggable**: The `Smart Plugin`_ system allows to write components with minimal boilerplate code.
|
||||
- **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
|
||||
|
||||
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
|
||||
|
||||
Why do I need an API key for bots?
|
||||
----------------------------------
|
||||
|
||||
Requests against the official bot API endpoint are made via JSON/HTTP, but are handled by an intermediate server
|
||||
application that implements the MTProto protocol -- just like Pyrogram -- and uses its own API key, which is always
|
||||
required, but hidden to the public.
|
||||
|
||||
.. figure:: https://i.imgur.com/C108qkX.png
|
||||
:align: center
|
||||
|
||||
Using MTProto is the only way to communicate with the actual Telegram servers, and the main API requires developers to
|
||||
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!
|
||||
---------------------------------------
|
||||
|
||||
If you are connecting from Russia, China or Iran `you need a proxy`_, because Telegram could be partially or
|
||||
totally blocked in those countries.
|
||||
|
||||
Another possible cause might be network issues, either yours or Telegram's. To confirm this, add the following code on
|
||||
the top of your script and run it again. You should see some error mentioning a socket timeout or an unreachable network
|
||||
in a bunch of seconds:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
logging.basicConfig(level=logging.INFO)
|
||||
|
||||
Another way to confirm you aren't able to connect to Telegram is by pinging these IP addresses and see whether ping
|
||||
fails or not:
|
||||
|
||||
- DC1: ``149.154.175.50``
|
||||
- DC2: ``149.154.167.51``
|
||||
- DC3: ``149.154.175.100``
|
||||
- DC4: ``149.154.167.91``
|
||||
- DC5: ``91.108.56.149``
|
||||
|
||||
.. _you need a proxy: topics/proxy
|
||||
|
||||
I keep getting PEER_ID_INVALID error!
|
||||
-------------------------------------------
|
||||
|
||||
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).
|
||||
- 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 review reports.
|
||||
|
||||
.. 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 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.
|
||||
- Virtual/VoIP and cheap real numbers, because they are relatively easy to get and likely used for spam/flood.
|
||||
|
||||
However, you might be right, and your account was deactivated/limited without any reason. This could happen because of
|
||||
mistakes by either the automatic systems or a moderator. In such cases you can kindly email Telegram at
|
||||
recover@telegram.org, contact `@smstelegram`_ on Twitter or use `this form`_.
|
||||
|
||||
.. _@smstelegram: https://twitter.com/smstelegram
|
||||
.. _this form: https://telegram.org/support
|
||||
|
||||
About the License
|
||||
-----------------
|
||||
|
||||
.. image:: https://www.gnu.org/graphics/lgplv3-with-text-154x68.png
|
||||
:align: left
|
||||
|
||||
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
|
||||
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
|
||||
.. _Bug Report: https://github.com/pyrogram/pyrogram/issues/new?labels=bug&template=bug_report.md
|
||||
.. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md
|
||||
75
docs/source/glossary.rst
Normal file
75
docs/source/glossary.rst
Normal file
@ -0,0 +1,75 @@
|
||||
Pyrogram Glossary
|
||||
=================
|
||||
|
||||
This page contains a list of common words with brief explanations related to Pyrogram and, to some extent, Telegram in
|
||||
general. Some words may as well link to dedicated articles in case the topic is covered in a more detailed fashion.
|
||||
|
||||
.. tip::
|
||||
|
||||
If you think something interesting could be added here, feel free to propose it by opening a `Feature Request`_.
|
||||
|
||||
|
||||
.. glossary::
|
||||
|
||||
API
|
||||
Application Programming Interface: a set of methods, protocols and tools that make it easier to develop programs
|
||||
by providing useful building blocks to the developer.
|
||||
|
||||
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>`_.
|
||||
|
||||
DC
|
||||
Also known as *data center*, is a place where lots of computer systems are housed and used together in order to
|
||||
achieve high quality and availability for services.
|
||||
|
||||
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 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>`_.
|
||||
|
||||
MTProto
|
||||
The name of the custom-made, open and encrypted protocol by Telegram, implemented in Pyrogram.
|
||||
`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 <topics/mtproto-vs-botapi#what-is-the-mtproto-api>`_.
|
||||
|
||||
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.
|
||||
|
||||
Userbot
|
||||
Also known as *user bot* or *ubot* for short, is a user logged in by third-party Telegram libraries --- such as
|
||||
Pyrogram --- to automate some behaviours, like sending messages or reacting to text commands or any other event.
|
||||
|
||||
Session
|
||||
Also known as *login session*, is a strictly personal piece of information created and held by both parties
|
||||
(client and server) which is used to grant permission into a single account without having to start a new
|
||||
authorization process from scratch.
|
||||
|
||||
Callback
|
||||
Also known as *callback function*, is a user-defined generic function that *can be* registered to and then
|
||||
called-back by the framework when specific events occurs.
|
||||
|
||||
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>`_.
|
||||
|
||||
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>`_.
|
||||
|
||||
.. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md
|
||||
@ -4,8 +4,8 @@ Welcome to Pyrogram
|
||||
.. raw:: html
|
||||
|
||||
<div align="center">
|
||||
<a href="https://docs.pyrogram.ml">
|
||||
<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>
|
||||
|
||||
@ -13,26 +13,17 @@ Welcome to Pyrogram
|
||||
<b>Telegram MTProto API Framework for Python</b>
|
||||
|
||||
<br>
|
||||
<a href="https://docs.pyrogram.ml">
|
||||
Documentation
|
||||
<a href="https://github.com/pyrogram/pyrogram">
|
||||
Source Code
|
||||
</a>
|
||||
•
|
||||
<a href="https://github.com/pyrogram/pyrogram/releases">
|
||||
Changelog
|
||||
Releases
|
||||
</a>
|
||||
•
|
||||
<a href="https://t.me/PyrogramChat">
|
||||
<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>
|
||||
|
||||
.. code-block:: python
|
||||
@ -49,73 +40,133 @@ Welcome to Pyrogram
|
||||
|
||||
app.run()
|
||||
|
||||
Welcome to Pyrogram's Documentation! Here you can find resources for learning how to use the framework.
|
||||
Contents are organized into self-contained topics and can be accessed from the sidebar, or by following them in order
|
||||
using the Next button at the end of each page. But first, here's a brief overview of what is this all about.
|
||||
**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and
|
||||
C. It enables you to easily create custom apps for both user and bot identities (bot API alternative) via the
|
||||
`MTProto API`_.
|
||||
|
||||
About
|
||||
-----
|
||||
.. _Telegram: https://telegram.org
|
||||
.. _MTProto API: topics/mtproto-vs-botapi#what-is-the-mtproto-api
|
||||
|
||||
**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and C.
|
||||
It enables you to easily create custom apps using both user and bot identities (bot API alternative) via the `MTProto API`_.
|
||||
How the Documentation is Organized
|
||||
----------------------------------
|
||||
|
||||
Features
|
||||
--------
|
||||
Contents are organized into self-contained topics and can be all accessed from the sidebar, or by following them in
|
||||
order using the Next button at the end of each page. Here below you can, instead, find a list of the most relevant
|
||||
pages for a quick access.
|
||||
|
||||
- **Easy**: You can install Pyrogram with pip and start building your applications right away.
|
||||
- **Elegant**: Low-level details are abstracted and re-presented in a much nicer and easier way.
|
||||
- **Fast**: Crypto parts are boosted up by TgCrypto_, a high-performance library written in pure C.
|
||||
- **Documented**: Pyrogram API methods, types and public interfaces are well documented.
|
||||
- **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted.
|
||||
- **Updated**, to the latest Telegram API version, currently Layer 97 on top of `MTProto 2.0`_.
|
||||
- **Pluggable**: The Smart Plugin system allows to write components with minimal boilerplate code.
|
||||
- **Comprehensive**: Execute any advanced action an official client is able to do, and even more.
|
||||
First Steps
|
||||
-----------
|
||||
|
||||
To get started, press the Next button.
|
||||
.. 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
|
||||
.. _Handling Updates: start/updates
|
||||
.. _Error Handling: start/errors
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. hlist::
|
||||
:columns: 2
|
||||
|
||||
- `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
|
||||
----
|
||||
|
||||
.. hlist::
|
||||
:columns: 2
|
||||
|
||||
- `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:
|
||||
:caption: Quick Start
|
||||
:caption: Introduction
|
||||
|
||||
start/Installation
|
||||
start/Setup
|
||||
start/Usage
|
||||
intro/quickstart
|
||||
intro/install
|
||||
intro/setup
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: Resources
|
||||
:caption: Getting Started
|
||||
|
||||
resources/UpdateHandling
|
||||
resources/UsingFilters
|
||||
resources/MoreOnUpdates
|
||||
resources/ConfigurationFile
|
||||
resources/SmartPlugins
|
||||
resources/AutoAuthorization
|
||||
resources/CustomizeSessions
|
||||
resources/TgCrypto
|
||||
resources/TextFormatting
|
||||
resources/SOCKS5Proxy
|
||||
resources/BotsInteraction
|
||||
resources/ErrorHandling
|
||||
resources/TestServers
|
||||
resources/AdvancedUsage
|
||||
resources/VoiceCalls
|
||||
resources/Changelog
|
||||
start/auth
|
||||
start/invoking
|
||||
start/updates
|
||||
start/errors
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: Main Package
|
||||
:caption: API Reference
|
||||
|
||||
pyrogram/index
|
||||
api/client
|
||||
api/methods
|
||||
api/types
|
||||
api/bound-methods
|
||||
api/handlers
|
||||
api/decorators
|
||||
api/filters
|
||||
api/errors
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: Topic Guides
|
||||
|
||||
topics/filters
|
||||
topics/more-on-updates
|
||||
topics/config-file
|
||||
topics/smart-plugins
|
||||
topics/auto-auth
|
||||
topics/session-settings
|
||||
topics/tgcrypto
|
||||
topics/text-formatting
|
||||
topics/serialize
|
||||
topics/proxy
|
||||
topics/bots-interaction
|
||||
topics/mtproto-vs-botapi
|
||||
topics/test-servers
|
||||
topics/advanced-usage
|
||||
topics/voice-calls
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: Meta
|
||||
|
||||
faq
|
||||
glossary
|
||||
releases
|
||||
powered-by
|
||||
support-pyrogram
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: Telegram API
|
||||
|
||||
functions/index
|
||||
types/index
|
||||
|
||||
.. _`Telegram`: https://telegram.org
|
||||
.. _TgCrypto: https://docs.pyrogram.ml/resources/TgCrypto
|
||||
.. _`MTProto API`: https://core.telegram.org/api#telegram-api
|
||||
.. _`MTProto 2.0`: https://core.telegram.org/mtproto
|
||||
telegram/functions/index
|
||||
telegram/types/index
|
||||
@ -1,8 +1,8 @@
|
||||
Installation
|
||||
============
|
||||
Install Guide
|
||||
=============
|
||||
|
||||
Being a Python library, **Pyrogram** requires Python to be installed in your system.
|
||||
We recommend using the latest version of Python 3 and pip.
|
||||
We recommend using the latest versions of both Python 3 and pip.
|
||||
|
||||
- Get **Python 3** from https://www.python.org/downloads/ (or with your package manager)
|
||||
- Get **pip** by following the instructions at https://pip.pypa.io/en/latest/installing/.
|
||||
@ -29,12 +29,12 @@ Install Pyrogram
|
||||
Bleeding Edge
|
||||
-------------
|
||||
|
||||
Things are constantly evolving in Pyrogram, although new releases are published only when enough changes are added,
|
||||
but this doesn't mean you can't try new features right now!
|
||||
Pyrogram is always evolving, although new releases on PyPI are published only when enough changes are added, but this
|
||||
doesn't mean you can't try new features right now!
|
||||
|
||||
In case you would like to try out the latest Pyrogram features and additions, the `GitHub repo`_ is always kept updated
|
||||
with new changes; you can install the development version straight from the ``develop`` branch using this command
|
||||
(note "develop.zip" in the link):
|
||||
In case you'd like to try out the latest Pyrogram features, the `GitHub repo`_ is always kept updated with new changes;
|
||||
you can install the development version straight from the ``develop`` branch using this command (note "develop.zip" in
|
||||
the link):
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
@ -44,7 +44,8 @@ Asynchronous
|
||||
------------
|
||||
|
||||
Pyrogram heavily depends on IO-bound network code (it's a cloud-based messaging framework after all), and here's
|
||||
where asyncio shines the most by providing extra performance while running on a single OS-level thread only.
|
||||
where asyncio shines the most by providing extra performance and efficiency while running on a single OS-level thread
|
||||
only.
|
||||
|
||||
**A fully asynchronous variant of Pyrogram is therefore available** (Python 3.5.3+ required).
|
||||
Use this command to install (note "asyncio.zip" in the link):
|
||||
@ -54,7 +55,7 @@ Use this command to install (note "asyncio.zip" in the link):
|
||||
$ pip3 install -U https://github.com/pyrogram/pyrogram/archive/asyncio.zip
|
||||
|
||||
|
||||
Pyrogram API remains the same and features are kept up to date from the non-async, default develop branch, but you
|
||||
Pyrogram's API remains the same and features are kept up to date from the non-async, default develop branch, but you
|
||||
are obviously required Python asyncio knowledge in order to take full advantage of it.
|
||||
|
||||
|
||||
@ -82,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.12.0'
|
||||
'|version|'
|
||||
|
||||
.. _TgCrypto: https://docs.pyrogram.ml/resources/TgCrypto
|
||||
.. _TgCrypto: ../topics/tgcrypto
|
||||
.. _`Github repo`: http://github.com/pyrogram/pyrogram
|
||||
49
docs/source/intro/quickstart.rst
Normal file
49
docs/source/intro/quickstart.rst
Normal file
@ -0,0 +1,49 @@
|
||||
Quick Start
|
||||
===========
|
||||
|
||||
The next few steps serve as a quick start for all new Pyrogrammers that want to get something done as fast as possible.
|
||||
Let's go!
|
||||
|
||||
Get Pyrogram Real Fast
|
||||
----------------------
|
||||
|
||||
1. Install Pyrogram with ``pip3 install -U pyrogram``.
|
||||
|
||||
2. Get your own Telegram API key from https://my.telegram.org/apps.
|
||||
|
||||
3. Open your best text editor and paste the following:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
api_id = 12345
|
||||
api_hash = "0123456789abcdef0123456789abcdef"
|
||||
|
||||
with Client("my_account", api_id, api_hash) as app:
|
||||
app.send_message("me", "Greetings from **Pyrogram**!")
|
||||
|
||||
4. Replace *api_id* and *api_hash* values with your own.
|
||||
|
||||
5. Save the file as ``pyro.py``.
|
||||
|
||||
6. Run the script with ``python3 pyro.py``
|
||||
|
||||
7. Follow the instructions on your terminal to login.
|
||||
|
||||
8. Watch Pyrogram send a message to yourself.
|
||||
|
||||
9. Join our `community`_.
|
||||
|
||||
10. Say, "hi!".
|
||||
|
||||
Enjoy the API
|
||||
-------------
|
||||
|
||||
That was just a quick overview that barely scratched the surface!
|
||||
In the next few pages of the introduction, we'll take a much more in-depth look of what we have just done above.
|
||||
|
||||
Feeling eager to continue? You can take a shortcut to `Calling Methods`_ and come back later to learn some more details.
|
||||
|
||||
.. _community: //t.me/Pyrogram
|
||||
.. _Calling Methods: ../start/invoking
|
||||
61
docs/source/intro/setup.rst
Normal file
61
docs/source/intro/setup.rst
Normal file
@ -0,0 +1,61 @@
|
||||
Project Setup
|
||||
=============
|
||||
|
||||
We have just `installed Pyrogram`_. In this page we'll discuss what you need to do in order to set up a project with
|
||||
the library. Let's see how it's done.
|
||||
|
||||
API Keys
|
||||
--------
|
||||
|
||||
The very first step requires you to obtain a valid Telegram API key (API id/hash pair):
|
||||
|
||||
#. Visit https://my.telegram.org/apps and log in with your Telegram Account.
|
||||
#. Fill out the form to register a new Telegram application.
|
||||
#. Done! The API key consists of two parts: **api_id** and **api_hash**.
|
||||
|
||||
.. important::
|
||||
|
||||
The API key is personal and must be kept secret.
|
||||
|
||||
.. note::
|
||||
|
||||
The API key is unique for each user, but defines a token for a Telegram *application* you are going to build. This
|
||||
means that you are able to authorize multiple users (and bots too) to access the Telegram database through the
|
||||
MTProto API by a single API key.
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
Having the API key from the `previous step <#api-keys>`_ in handy, we can now begin to configure a Pyrogram project.
|
||||
There are two ways to do so, and you can choose what fits better for you:
|
||||
|
||||
- First option (recommended): create a new ``config.ini`` file at the root of your working directory, copy-paste the
|
||||
following and replace the **api_id** and **api_hash** values with your own. This is the preferred method because
|
||||
allows you to keep your credentials out of your code without having to deal with how to load them:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[pyrogram]
|
||||
api_id = 12345
|
||||
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
|
||||
credentials from the environment variables and directly pass the values into Pyrogram):
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client(
|
||||
"my_account",
|
||||
api_id=12345,
|
||||
api_hash="0123456789abcdef0123456789abcdef"
|
||||
)
|
||||
|
||||
.. note::
|
||||
|
||||
To keep code snippets clean and concise, from now on it is assumed you are making use of the ``config.ini`` file,
|
||||
thus, the *api_id* and *api_hash* parameters usage won't be shown anymore.
|
||||
|
||||
.. _installed Pyrogram: install.html
|
||||
69
docs/source/powered-by.rst
Normal file
69
docs/source/powered-by.rst
Normal file
@ -0,0 +1,69 @@
|
||||
Powered by Pyrogram
|
||||
===================
|
||||
|
||||
This is a collection of remarkable projects made with Pyrogram.
|
||||
|
||||
.. A collection of Pyrojects :^)
|
||||
|
||||
.. tip::
|
||||
|
||||
If you'd like to propose a project that's worth being listed here, feel free to open a `Feature Request`_.
|
||||
|
||||
Projects Showcase
|
||||
-----------------
|
||||
|
||||
`YTAudioBot <https://t.me/ytaudio>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
| **A YouTube audio downloader on Telegram, serving over 200k MAU.**
|
||||
| --- by `Dan <https://t.me/haskell>`_
|
||||
|
||||
- Main: https://t.me/ytaudiobot
|
||||
- Mirror: https://t.me/ytaudio_bot
|
||||
- Website: https://ytaudiobot.ml
|
||||
|
||||
-----
|
||||
|
||||
`Pyrogram Assistant <https://github.com/pyrogram/assistant>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
| **The assistant bot that helps people with Pyrogram directly on Telegram**
|
||||
| --- by `Dan <https://t.me/haskell>`_
|
||||
|
||||
- Bot: https://t.me/pyrogrambot
|
||||
- Source Code: https://github.com/pyrogram/assistant
|
||||
|
||||
-----
|
||||
|
||||
`PyroBot <https://git.colinshark.de/PyroBot/PyroBot>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
| **A Telegram userbot based on Pyrogram**
|
||||
| --- by `Colin <https://t.me/ColinShark>`_
|
||||
|
||||
- Source Code: https://git.colinshark.de/PyroBot/PyroBot
|
||||
|
||||
-----
|
||||
|
||||
`TgIntegration <https://github.com/JosXa/tgintegration>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
| **Integration Test Library for Telegram Messenger Bots in Python**
|
||||
| --- by `JosXa <https://t.me/JosXa>`_
|
||||
|
||||
- Source Code: https://github.com/JosXa/tgintegration
|
||||
|
||||
-----
|
||||
|
||||
`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>`_
|
||||
|
||||
- Source Code: https://github.com/JosXa/BotListBot
|
||||
|
||||
-----
|
||||
|
||||
.. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md
|
||||
|
||||
@ -1,5 +0,0 @@
|
||||
ChatAction
|
||||
==========
|
||||
|
||||
.. autoclass:: pyrogram.ChatAction
|
||||
:members:
|
||||
@ -1,162 +0,0 @@
|
||||
Client
|
||||
======
|
||||
|
||||
.. currentmodule:: pyrogram.Client
|
||||
|
||||
.. autoclass:: pyrogram.Client
|
||||
|
||||
Utilities
|
||||
---------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
start
|
||||
stop
|
||||
restart
|
||||
idle
|
||||
run
|
||||
add_handler
|
||||
remove_handler
|
||||
send
|
||||
resolve_peer
|
||||
save_file
|
||||
stop_transmission
|
||||
|
||||
Decorators
|
||||
----------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
on_message
|
||||
on_callback_query
|
||||
on_inline_query
|
||||
on_deleted_messages
|
||||
on_user_status
|
||||
on_disconnect
|
||||
on_raw_update
|
||||
|
||||
Messages
|
||||
--------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
send_message
|
||||
forward_messages
|
||||
send_photo
|
||||
send_audio
|
||||
send_document
|
||||
send_sticker
|
||||
send_video
|
||||
send_animation
|
||||
send_voice
|
||||
send_video_note
|
||||
send_media_group
|
||||
send_location
|
||||
send_venue
|
||||
send_contact
|
||||
send_cached_media
|
||||
send_chat_action
|
||||
edit_message_text
|
||||
edit_message_caption
|
||||
edit_message_reply_markup
|
||||
edit_message_media
|
||||
delete_messages
|
||||
get_messages
|
||||
get_history
|
||||
get_history_count
|
||||
iter_history
|
||||
send_poll
|
||||
vote_poll
|
||||
stop_poll
|
||||
retract_vote
|
||||
download_media
|
||||
|
||||
Chats
|
||||
-----
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
join_chat
|
||||
leave_chat
|
||||
kick_chat_member
|
||||
unban_chat_member
|
||||
restrict_chat_member
|
||||
promote_chat_member
|
||||
export_chat_invite_link
|
||||
set_chat_photo
|
||||
delete_chat_photo
|
||||
set_chat_title
|
||||
set_chat_description
|
||||
pin_chat_message
|
||||
unpin_chat_message
|
||||
get_chat
|
||||
get_chat_preview
|
||||
get_chat_member
|
||||
get_chat_members
|
||||
get_chat_members_count
|
||||
iter_chat_members
|
||||
get_dialogs
|
||||
iter_dialogs
|
||||
get_dialogs_count
|
||||
restrict_chat
|
||||
update_chat_username
|
||||
|
||||
Users
|
||||
-----
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
get_me
|
||||
get_users
|
||||
get_user_profile_photos
|
||||
get_user_profile_photos_count
|
||||
set_user_profile_photo
|
||||
delete_user_profile_photos
|
||||
update_username
|
||||
|
||||
Contacts
|
||||
--------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
add_contacts
|
||||
get_contacts
|
||||
get_contacts_count
|
||||
delete_contacts
|
||||
|
||||
Password
|
||||
--------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
enable_cloud_password
|
||||
change_cloud_password
|
||||
remove_cloud_password
|
||||
|
||||
Bots
|
||||
----
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
get_inline_bot_results
|
||||
send_inline_bot_result
|
||||
answer_callback_query
|
||||
answer_inline_query
|
||||
request_callback_answer
|
||||
send_game
|
||||
set_game_score
|
||||
get_game_high_scores
|
||||
answer_inline_query
|
||||
|
||||
|
||||
.. autoclass:: pyrogram.Client
|
||||
:inherited-members:
|
||||
:members:
|
||||
@ -1,37 +0,0 @@
|
||||
Handlers
|
||||
========
|
||||
|
||||
.. currentmodule:: pyrogram
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
MessageHandler
|
||||
DeletedMessagesHandler
|
||||
CallbackQueryHandler
|
||||
InlineQueryHandler
|
||||
UserStatusHandler
|
||||
DisconnectHandler
|
||||
RawUpdateHandler
|
||||
|
||||
.. autoclass:: MessageHandler
|
||||
:members:
|
||||
|
||||
.. autoclass:: DeletedMessagesHandler
|
||||
:members:
|
||||
|
||||
.. autoclass:: CallbackQueryHandler
|
||||
:members:
|
||||
|
||||
.. autoclass:: InlineQueryHandler
|
||||
:members:
|
||||
|
||||
.. autoclass:: UserStatusHandler
|
||||
:members:
|
||||
|
||||
.. autoclass:: DisconnectHandler
|
||||
:members:
|
||||
|
||||
.. autoclass:: RawUpdateHandler
|
||||
:members:
|
||||
|
||||
@ -1,6 +0,0 @@
|
||||
ParseMode
|
||||
=========
|
||||
|
||||
.. autoclass:: pyrogram.ParseMode
|
||||
:members:
|
||||
:undoc-members:
|
||||
@ -1,15 +0,0 @@
|
||||
RPCError
|
||||
========
|
||||
|
||||
.. autoexception:: pyrogram.RPCError
|
||||
:members:
|
||||
|
||||
.. toctree::
|
||||
../errors/SeeOther
|
||||
../errors/BadRequest
|
||||
../errors/Unauthorized
|
||||
../errors/Forbidden
|
||||
../errors/NotAcceptable
|
||||
../errors/Flood
|
||||
../errors/InternalServerError
|
||||
../errors/UnknownError
|
||||
@ -1,263 +0,0 @@
|
||||
Types
|
||||
=====
|
||||
|
||||
.. currentmodule:: pyrogram
|
||||
|
||||
Users & Chats
|
||||
-------------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
User
|
||||
UserStatus
|
||||
Chat
|
||||
ChatPreview
|
||||
ChatPhoto
|
||||
ChatMember
|
||||
ChatMembers
|
||||
ChatPermissions
|
||||
Dialog
|
||||
Dialogs
|
||||
|
||||
Messages & Media
|
||||
----------------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
Message
|
||||
Messages
|
||||
MessageEntity
|
||||
Photo
|
||||
PhotoSize
|
||||
UserProfilePhotos
|
||||
Audio
|
||||
Document
|
||||
Animation
|
||||
Video
|
||||
Voice
|
||||
VideoNote
|
||||
Contact
|
||||
Location
|
||||
Venue
|
||||
Sticker
|
||||
Poll
|
||||
PollOption
|
||||
|
||||
Bots
|
||||
----
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
ReplyKeyboardMarkup
|
||||
KeyboardButton
|
||||
ReplyKeyboardRemove
|
||||
InlineKeyboardMarkup
|
||||
InlineKeyboardButton
|
||||
ForceReply
|
||||
CallbackQuery
|
||||
Game
|
||||
|
||||
Input Media
|
||||
-----------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
InputMedia
|
||||
InputMediaPhoto
|
||||
InputMediaVideo
|
||||
InputMediaAudio
|
||||
InputMediaAnimation
|
||||
InputMediaDocument
|
||||
InputPhoneContact
|
||||
|
||||
Inline Mode
|
||||
------------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
InlineQuery
|
||||
InlineQueryResult
|
||||
InlineQueryResultArticle
|
||||
|
||||
InputMessageContent
|
||||
-------------------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
InputMessageContent
|
||||
InputTextMessageContent
|
||||
|
||||
.. User & Chats
|
||||
------------
|
||||
|
||||
.. autoclass:: User
|
||||
:members:
|
||||
|
||||
.. autoclass:: UserStatus
|
||||
:members:
|
||||
|
||||
.. autoclass:: Chat
|
||||
:members:
|
||||
|
||||
.. autoclass:: ChatPreview
|
||||
:members:
|
||||
|
||||
.. autoclass:: ChatPhoto
|
||||
:members:
|
||||
|
||||
.. autoclass:: ChatMember
|
||||
:members:
|
||||
|
||||
.. autoclass:: ChatMembers
|
||||
:members:
|
||||
|
||||
.. autoclass:: ChatPermissions
|
||||
:members:
|
||||
|
||||
.. autoclass:: Dialog
|
||||
:members:
|
||||
|
||||
.. autoclass:: Dialogs
|
||||
:members:
|
||||
|
||||
.. Messages & Media
|
||||
----------------
|
||||
|
||||
.. autoclass:: Message
|
||||
:members:
|
||||
|
||||
.. autoclass:: Messages
|
||||
:members:
|
||||
|
||||
.. autoclass:: MessageEntity
|
||||
:members:
|
||||
|
||||
.. autoclass:: Photo
|
||||
:members:
|
||||
|
||||
.. autoclass:: PhotoSize
|
||||
:members:
|
||||
|
||||
.. autoclass:: UserProfilePhotos
|
||||
:members:
|
||||
|
||||
.. autoclass:: Audio
|
||||
:members:
|
||||
|
||||
.. autoclass:: Document
|
||||
:members:
|
||||
|
||||
.. autoclass:: Animation
|
||||
:members:
|
||||
|
||||
.. autoclass:: Video
|
||||
:members:
|
||||
|
||||
.. autoclass:: Voice
|
||||
:members:
|
||||
|
||||
.. autoclass:: VideoNote
|
||||
:members:
|
||||
|
||||
.. autoclass:: Contact
|
||||
:members:
|
||||
|
||||
.. autoclass:: Location
|
||||
:members:
|
||||
|
||||
.. autoclass:: Venue
|
||||
:members:
|
||||
|
||||
.. autoclass:: Sticker
|
||||
:members:
|
||||
|
||||
.. autoclass:: Poll
|
||||
:members:
|
||||
|
||||
.. autoclass:: PollOption
|
||||
:members:
|
||||
|
||||
.. Bots
|
||||
----
|
||||
|
||||
.. autoclass:: ReplyKeyboardMarkup
|
||||
:members:
|
||||
|
||||
.. autoclass:: KeyboardButton
|
||||
:members:
|
||||
|
||||
.. autoclass:: ReplyKeyboardRemove
|
||||
:members:
|
||||
|
||||
.. autoclass:: InlineKeyboardMarkup
|
||||
:members:
|
||||
|
||||
.. autoclass:: InlineKeyboardButton
|
||||
:members:
|
||||
|
||||
.. autoclass:: ForceReply
|
||||
:members:
|
||||
|
||||
.. autoclass:: CallbackQuery
|
||||
:members:
|
||||
|
||||
.. autoclass:: Game
|
||||
:members:
|
||||
|
||||
.. autoclass:: GameHighScore
|
||||
:members:
|
||||
|
||||
.. autoclass:: GameHighScores
|
||||
:members:
|
||||
|
||||
.. Input Media
|
||||
-----------
|
||||
|
||||
.. autoclass:: InputMedia
|
||||
:members:
|
||||
|
||||
.. autoclass:: InputMediaPhoto
|
||||
:members:
|
||||
|
||||
.. autoclass:: InputMediaVideo
|
||||
:members:
|
||||
|
||||
.. autoclass:: InputMediaAudio
|
||||
:members:
|
||||
|
||||
.. autoclass:: InputMediaAnimation
|
||||
:members:
|
||||
|
||||
.. autoclass:: InputMediaDocument
|
||||
:members:
|
||||
|
||||
.. autoclass:: InputPhoneContact
|
||||
:members:
|
||||
|
||||
|
||||
.. Inline Mode
|
||||
-----------
|
||||
|
||||
.. autoclass:: InlineQuery
|
||||
:members:
|
||||
|
||||
.. autoclass:: InlineQueryResult
|
||||
:members:
|
||||
|
||||
.. autoclass:: InlineQueryResultArticle
|
||||
:members:
|
||||
|
||||
.. InputMessageContent
|
||||
-------------------
|
||||
|
||||
.. autoclass:: InputMessageContent
|
||||
:members:
|
||||
|
||||
.. autoclass:: InputTextMessageContent
|
||||
:members:
|
||||
@ -1,20 +0,0 @@
|
||||
Pyrogram
|
||||
========
|
||||
|
||||
In this section you can find a detailed description of the Pyrogram package and its API.
|
||||
|
||||
:class:`Client <pyrogram.Client>` is the main class. It exposes easy-to-use methods that are named
|
||||
after the well established `Telegram Bot API`_ methods, thus offering a familiar look to Bot developers.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Client
|
||||
Types
|
||||
Handlers
|
||||
Filters
|
||||
ChatAction
|
||||
ParseMode
|
||||
RPCError
|
||||
|
||||
.. _Telegram Bot API: https://core.telegram.org/bots/api#available-methods
|
||||
13
docs/source/releases.rst
Normal file
13
docs/source/releases.rst
Normal file
@ -0,0 +1,13 @@
|
||||
Release Notes
|
||||
=============
|
||||
|
||||
Release notes for Pyrogram releases will describe what's new in each version, and will also make you aware of any
|
||||
backwards-incompatible changes made in that version.
|
||||
|
||||
When upgrading to a new version of Pyrogram, you will need to check all the breaking changes in order to find
|
||||
incompatible code in your application, but also to take advantage of new features and improvements.
|
||||
|
||||
.. note::
|
||||
|
||||
Currently, all Pyrogram release notes live inside the GitHub repository web page:
|
||||
https://github.com/pyrogram/pyrogram/releases.
|
||||
@ -1,11 +0,0 @@
|
||||
Changelog
|
||||
=========
|
||||
|
||||
Currently, all Pyrogram release notes live inside the GitHub repository web page:
|
||||
https://github.com/pyrogram/pyrogram/releases
|
||||
|
||||
(You will be automatically redirected in 10 seconds.)
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<meta http-equiv="refresh" content="10; URL=https://github.com/pyrogram/pyrogram/releases"/>
|
||||
@ -1,59 +0,0 @@
|
||||
Error Handling
|
||||
==============
|
||||
|
||||
Errors are inevitable when working with the API, and they must be correctly handled with ``try..except`` blocks.
|
||||
|
||||
There are many errors that Telegram could return, but they all fall in one of these categories
|
||||
(which are in turn children of the :obj:`RPCError <pyrogram.RPCError>` superclass):
|
||||
|
||||
- :obj:`303 - See Other <pyrogram.errors.SeeOther>`
|
||||
- :obj:`400 - Bad Request <pyrogram.errors.BadRequest>`
|
||||
- :obj:`401 - Unauthorized <pyrogram.errors.Unauthorized>`
|
||||
- :obj:`403 - Forbidden <pyrogram.errors.Forbidden>`
|
||||
- :obj:`406 - Not Acceptable <pyrogram.errors.NotAcceptable>`
|
||||
- :obj:`420 - Flood <pyrogram.errors.Flood>`
|
||||
- :obj:`500 - Internal Server Error <pyrogram.errors.InternalServerError>`
|
||||
|
||||
As stated above, there are really many (too many) errors, and in case Pyrogram does not know anything yet about a
|
||||
specific one, it raises a special :obj:`520 Unknown Error <pyrogram.errors.UnknownError>` exception and logs it
|
||||
in the ``unknown_errors.txt`` file. Users are invited to report these unknown errors; in later versions of Pyrogram
|
||||
some kind of automatic error reporting module might be implemented.
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram.errors import (
|
||||
BadRequest, Flood, InternalServerError,
|
||||
SeeOther, Unauthorized, UnknownError
|
||||
)
|
||||
|
||||
try:
|
||||
...
|
||||
except BadRequest:
|
||||
pass
|
||||
except Flood:
|
||||
pass
|
||||
except InternalServerError:
|
||||
pass
|
||||
except SeeOther:
|
||||
pass
|
||||
except Unauthorized:
|
||||
pass
|
||||
except UnknownError:
|
||||
pass
|
||||
|
||||
Exception objects may also contain some informative values.
|
||||
E.g.: :obj:`FloodWait <pyrogram.errors.exceptions.flood_420.FloodWait>` holds the amount of seconds you have to wait
|
||||
before you can try again. The value is always stored in the ``x`` field of the returned exception object:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import time
|
||||
from pyrogram.errors import FloodWait
|
||||
|
||||
try:
|
||||
...
|
||||
except FloodWait as e:
|
||||
time.sleep(e.x)
|
||||
@ -1,72 +0,0 @@
|
||||
Update Handling
|
||||
===============
|
||||
|
||||
Let's now dive right into the core of the framework.
|
||||
|
||||
Updates are events that happen in your Telegram account (incoming messages, new channel posts, new members join, ...)
|
||||
and are handled by registering one or more callback functions in your app using `Handlers <../pyrogram/Handlers.html>`_.
|
||||
|
||||
Each handler deals with a specific event and once a matching update arrives from Telegram, your registered callback
|
||||
function will be called.
|
||||
|
||||
Registering an Handler
|
||||
----------------------
|
||||
|
||||
To explain how handlers work let's have a look at the most used one, the
|
||||
:obj:`MessageHandler <pyrogram.MessageHandler>`, which will be in charge for handling :obj:`Message <pyrogram.Message>`
|
||||
updates coming from all around your chats. Every other handler shares the same setup logic; you should not have troubles
|
||||
settings them up once you learn from this section.
|
||||
|
||||
Using add_handler()
|
||||
-------------------
|
||||
|
||||
The :meth:`add_handler() <pyrogram.Client.add_handler>` method takes any handler instance that wraps around your defined
|
||||
callback function and registers it in your Client. Here's a full example that prints out the content of a message as
|
||||
soon as it arrives:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client, MessageHandler
|
||||
|
||||
|
||||
def my_function(client, message):
|
||||
print(message)
|
||||
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
my_handler = MessageHandler(my_function)
|
||||
app.add_handler(my_handler)
|
||||
|
||||
app.run()
|
||||
|
||||
Using Decorators
|
||||
----------------
|
||||
|
||||
A much nicer way to register a MessageHandler is by decorating your callback function with the
|
||||
:meth:`on_message() <pyrogram.Client.on_message>` decorator, which will still make use of add_handler() under the hood.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
|
||||
@app.on_message()
|
||||
def my_handler(client, message):
|
||||
print(message)
|
||||
|
||||
|
||||
app.run()
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
Due to how these decorators work in Pyrogram, they will wrap your defined callback function in a tuple consisting of
|
||||
``(handler, group)``; this will be the value held by your function identifier (e.g.: *my_function* from the example
|
||||
above).
|
||||
|
||||
In case, for some reason, you want to get your own function back after it has been decorated, you need to access
|
||||
``my_function[0].callback``, that is, the *callback* field of the *handler* object which is the first element in the
|
||||
tuple.
|
||||
@ -1,120 +0,0 @@
|
||||
Setup
|
||||
=====
|
||||
|
||||
Once you successfully `installed Pyrogram`_, you will still have to follow a few steps before you can actually use
|
||||
the library to make API calls. This section provides all the information you need in order to set up a project
|
||||
with Pyrogram.
|
||||
|
||||
API Keys
|
||||
--------
|
||||
|
||||
The very first step requires you to obtain a valid Telegram API key (API id/hash pair).
|
||||
If you already have one you can skip this step, otherwise:
|
||||
|
||||
#. Visit https://my.telegram.org/apps and log in with your Telegram Account.
|
||||
#. Fill out the form to register a new Telegram application.
|
||||
#. Done. The API key consists of two parts: **App api_id** and **App api_hash**.
|
||||
|
||||
.. important::
|
||||
|
||||
This API key is personal and must be kept secret.
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
The API key obtained in the `previous step <#api-keys>`_ defines a token for your application allowing you to access
|
||||
the Telegram database using the MTProto API — **it is therefore required for all authorizations of both users and bots**.
|
||||
|
||||
Having it handy, it's time to configure your Pyrogram project. There are two ways to do so, and you can choose what
|
||||
fits better for you:
|
||||
|
||||
- Create a new ``config.ini`` file at the root of your working directory, copy-paste the following and replace the
|
||||
**api_id** and **api_hash** values with your own. This is the preferred method because allows you to keep your
|
||||
credentials out of your code without having to deal with how to load them:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[pyrogram]
|
||||
api_id = 12345
|
||||
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:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client(
|
||||
"my_account",
|
||||
api_id=12345,
|
||||
api_hash="0123456789abcdef0123456789abcdef"
|
||||
)
|
||||
|
||||
.. note::
|
||||
|
||||
From now on, the code snippets assume you are using the ``config.ini`` file, thus they won't show the *api_id* and
|
||||
*api_hash* parameters usage to keep them as clean as possible.
|
||||
|
||||
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
|
||||
: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:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
app.run()
|
||||
|
||||
This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_)
|
||||
and the **phone code** you will receive:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
Enter phone number: +39**********
|
||||
Is "+39**********" correct? (y/n): y
|
||||
Enter phone code: 32768
|
||||
Logged in successfully as Dan
|
||||
|
||||
After successfully authorizing yourself, a new file called ``my_account.session`` will be created allowing Pyrogram
|
||||
executing API calls with your identity. This file will be loaded again when you restart your app, and as long as you
|
||||
keep the session alive, Pyrogram won't ask you again to enter your phone number.
|
||||
|
||||
.. important::
|
||||
|
||||
Your ``*.session`` files are personal and must be kept secret.
|
||||
|
||||
.. note::
|
||||
|
||||
The code above does nothing except asking for credentials and keeping the client online, hit ``CTRL+C`` now to stop
|
||||
your application and keep reading.
|
||||
|
||||
Bot Authorization
|
||||
-----------------
|
||||
|
||||
Bots are a special kind of users that are authorized via their tokens (instead of phone numbers), which are created by
|
||||
BotFather_. Bot tokens replace the users' phone numbers only — you still need to
|
||||
`configure a Telegram API key <#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
|
||||
after the session name, which will be ``pyrogrambot.session`` for the example below.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client(
|
||||
"pyrogrambot",
|
||||
bot_token="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
|
||||
)
|
||||
app.run()
|
||||
|
||||
.. _installed Pyrogram: Installation.html
|
||||
.. _`Country Code`: https://en.wikipedia.org/wiki/List_of_country_calling_codes
|
||||
.. _BotFather: https://t.me/botfather
|
||||
@ -1,51 +0,0 @@
|
||||
Usage
|
||||
=====
|
||||
|
||||
Having your `project set up`_ and your account authorized_, it's time to start playing with the API. Let's start!
|
||||
|
||||
High-level API
|
||||
--------------
|
||||
|
||||
The easiest and recommended way to interact with Telegram is via the high-level Pyrogram methods_ and types_, which are
|
||||
named after the `Telegram Bot API`_.
|
||||
|
||||
Here's a simple example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
app.start()
|
||||
|
||||
print(app.get_me())
|
||||
app.send_message("me", "Hi there! I'm using **Pyrogram**")
|
||||
app.send_location("me", 51.500729, -0.124583)
|
||||
app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")
|
||||
|
||||
app.stop()
|
||||
|
||||
You can also use Pyrogram in a context manager with the ``with`` statement. The Client will automatically
|
||||
:meth:`start <pyrogram.Client.start>` and :meth:`stop <pyrogram.Client.stop>` gracefully, even in case of unhandled
|
||||
exceptions in your code:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
with app:
|
||||
print(app.get_me())
|
||||
app.send_message("me", "Hi there! I'm using **Pyrogram**")
|
||||
app.send_location("me", 51.500729, -0.124583)
|
||||
app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")
|
||||
|
||||
More examples on `GitHub <https://github.com/pyrogram/pyrogram/tree/develop/examples>`_.
|
||||
|
||||
.. _project set up: Setup.html
|
||||
.. _authorized: Setup.html#user-authorization
|
||||
.. _Telegram Bot API: https://core.telegram.org/bots/api
|
||||
.. _methods: ../pyrogram/Client.html#messages
|
||||
.. _types: ../pyrogram/Types.html
|
||||
69
docs/source/start/auth.rst
Normal file
69
docs/source/start/auth.rst
Normal file
@ -0,0 +1,69 @@
|
||||
Authorization
|
||||
=============
|
||||
|
||||
Once a `project is set up`_, you will still have to follow a few steps before you can actually use Pyrogram to make
|
||||
API calls. This section provides all the information you need in order to authorize yourself as user or bot.
|
||||
|
||||
User Authorization
|
||||
------------------
|
||||
|
||||
In order to use the API, Telegram requires that users be authorized via their phone numbers.
|
||||
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:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
app.run()
|
||||
|
||||
This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_) and the
|
||||
**phone code** you will receive in your devices that are already authorized or via SMS:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
Enter phone number: +39**********
|
||||
Is "+39**********" correct? (y/n): y
|
||||
Enter phone code: 32768
|
||||
Logged in successfully as Dan
|
||||
|
||||
After successfully authorizing yourself, a new file called ``my_account.session`` will be created allowing Pyrogram to
|
||||
execute API calls with your identity. This file will be loaded again when you restart your app, and as long as you
|
||||
keep the session alive, Pyrogram won't ask you again to enter your phone number.
|
||||
|
||||
.. important::
|
||||
|
||||
Your ``*.session`` files are personal and must be kept secret.
|
||||
|
||||
.. note::
|
||||
|
||||
The code above does nothing except asking for credentials and keeping the client online, hit ``CTRL+C`` now to stop
|
||||
your application and keep reading.
|
||||
|
||||
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 <../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
|
||||
after the session name, which will be ``my_bot.session`` for the example below.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client(
|
||||
"my_bot",
|
||||
bot_token="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
|
||||
)
|
||||
|
||||
app.run()
|
||||
|
||||
.. _project is set up: ../intro/setup
|
||||
.. _Country Code: https://en.wikipedia.org/wiki/List_of_country_calling_codes
|
||||
.. _Bot Father: https://t.me/botfather
|
||||
91
docs/source/start/errors.rst
Normal file
91
docs/source/start/errors.rst
Normal file
@ -0,0 +1,91 @@
|
||||
Error Handling
|
||||
==============
|
||||
|
||||
Errors are inevitable when working with the API, and they must be correctly handled with ``try..except`` blocks in order
|
||||
to control the behaviour of your application. Pyrogram errors all live inside the ``errors`` package:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import errors
|
||||
|
||||
RPCError
|
||||
--------
|
||||
|
||||
The father of all errors is named ``RPCError``. This error exists in form of a Python exception which is directly
|
||||
subclass-ed from Python's main ``Exception`` and is able to catch all Telegram API related errors. This error is raised
|
||||
every time a method call against Telegram's API was unsuccessful.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram.errors import RPCError
|
||||
|
||||
.. warning::
|
||||
|
||||
It must be noted that catching this error is bad practice, especially when no feedback is given (i.e. by
|
||||
logging/printing the full error traceback), because it makes it impossible to understand what went wrong.
|
||||
|
||||
Error Categories
|
||||
----------------
|
||||
|
||||
The ``RPCError`` packs together all the possible errors Telegram could raise, but to make things tidier, Pyrogram
|
||||
provides categories of errors, which are named after the common HTTP errors and subclass-ed from the RPCError:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram.errors import BadRequest, Forbidden, ...
|
||||
|
||||
- `303 - SeeOther <../api/errors#seeother>`_
|
||||
- `400 - BadRequest <../api/errors#badrequest>`_
|
||||
- `401 - Unauthorized <../api/errors#unauthorized>`_
|
||||
- `403 - Forbidden <../api/errors#forbidden>`_
|
||||
- `406 - NotAcceptable <../api/errors#notacceptable>`_
|
||||
- `420 - Flood <../api/errors#flood>`_
|
||||
- `500 - InternalServerError <../api/errors#internalservererror>`_
|
||||
|
||||
Single Errors
|
||||
-------------
|
||||
|
||||
For a fine-grained control over every single error, Pyrogram does also expose errors that deal each with a specific
|
||||
issue. For example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram.errors import FloodWait
|
||||
|
||||
These errors subclass directly from the category of errors they belong to, which in turn subclass from the father
|
||||
RPCError, thus building a class of error hierarchy such as this:
|
||||
|
||||
- RPCError
|
||||
- BadRequest
|
||||
- ``MessageEmpty``
|
||||
- ``UsernameOccupied``
|
||||
- ``...``
|
||||
- InternalServerError
|
||||
- ``RpcCallFail``
|
||||
- ``InterDcCallError``
|
||||
- ``...``
|
||||
- ``...``
|
||||
|
||||
.. _Errors: api/errors
|
||||
|
||||
Unknown Errors
|
||||
--------------
|
||||
|
||||
In case Pyrogram does not know anything yet about a specific error, it raises a special ``520 - UnknownError`` exception
|
||||
and logs it in the ``unknown_errors.txt`` file. Users are invited to report these unknown errors.
|
||||
|
||||
Errors with Values
|
||||
------------------
|
||||
|
||||
Exception objects may also contain some informative values. For example, ``FloodWait`` holds the amount of seconds you
|
||||
have to wait before you can try again. The value is always stored in the ``x`` field of the returned exception object:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import time
|
||||
from pyrogram.errors import FloodWait
|
||||
|
||||
try:
|
||||
...
|
||||
except FloodWait as e:
|
||||
time.sleep(e.x) # Wait before trying again
|
||||
84
docs/source/start/invoking.rst
Normal file
84
docs/source/start/invoking.rst
Normal file
@ -0,0 +1,84 @@
|
||||
Calling Methods
|
||||
===============
|
||||
|
||||
At this point, we have successfully `installed Pyrogram`_ and authorized_ our account; we are now aiming towards the
|
||||
core of the library. It's time to start playing with the API!
|
||||
|
||||
Basic Usage
|
||||
-----------
|
||||
|
||||
Making API method calls with Pyrogram is very simple. Here's an example we are going to examine:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
app.start()
|
||||
|
||||
print(app.get_me())
|
||||
app.send_message("me", "Hi, it's me!")
|
||||
app.send_location("me", 51.500729, -0.124583)
|
||||
app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")
|
||||
|
||||
app.stop()
|
||||
|
||||
Let's begin by importing the Client class from the Pyrogram package:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
Now instantiate a new Client object, "my_account" is a session name of your choice:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
To actually make use of any method, the client has to be started first:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
app.start()
|
||||
|
||||
Now, you can call any method you like:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
print(app.get_me()) # Print information about yourself
|
||||
|
||||
# Send messages to yourself:
|
||||
app.send_message("me", "Hi!") # Text message
|
||||
app.send_location("me", 51.500729, -0.124583) # Location
|
||||
app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI") # Sticker
|
||||
|
||||
Finally, when done, simply stop the client:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
app.stop()
|
||||
|
||||
Context Manager
|
||||
---------------
|
||||
|
||||
You can also use Pyrogram's Client in a context manager with the ``with`` statement. The client will automatically
|
||||
:meth:`start() <pyrogram.Client.start>` and :meth:`stop() <pyrogram.Client.stop>` gracefully, even in case of unhandled
|
||||
exceptions in your code. The example above can be therefore rewritten in a much nicer way:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
with app:
|
||||
print(app.get_me())
|
||||
app.send_message("me", "Hi there! I'm using **Pyrogram**")
|
||||
app.send_location("me", 51.500729, -0.124583)
|
||||
app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")
|
||||
|
||||
More examples can be found on `GitHub <https://github.com/pyrogram/pyrogram/tree/develop/examples>`_.
|
||||
|
||||
.. _installed Pyrogram: ../intro/install.html
|
||||
.. _authorized: ../intro/setup.html
|
||||
112
docs/source/start/updates.rst
Normal file
112
docs/source/start/updates.rst
Normal file
@ -0,0 +1,112 @@
|
||||
Handling Updates
|
||||
================
|
||||
|
||||
Calling `API methods`_ sequentially is cool, but how to react when, for example, a new message arrives? This page deals
|
||||
with updates and how to handle such events in Pyrogram. Let's have a look at how they work.
|
||||
|
||||
Defining Updates
|
||||
----------------
|
||||
|
||||
First, let's define what are these updates. As hinted already, updates are simply events that happen in your Telegram
|
||||
account (incoming messages, new members join, bot button presses, etc...), which are meant to notify you about a new
|
||||
specific state that has changed. These updates are handled by registering one or more callback functions in your app
|
||||
using `Handlers <../api/handlers>`_.
|
||||
|
||||
Each handler deals with a specific event and once a matching update arrives from Telegram, your registered callback
|
||||
function will be called back by the framework and its body executed.
|
||||
|
||||
Registering a Handler
|
||||
---------------------
|
||||
|
||||
To explain how handlers work let's have a look at the most used one, the
|
||||
:obj:`MessageHandler <pyrogram.MessageHandler>`, which will be in charge for handling :obj:`Message <pyrogram.Message>`
|
||||
updates coming from all around your chats. Every other handler shares the same setup logic; you should not have troubles
|
||||
settings them up once you learn from this section.
|
||||
|
||||
Using add_handler()
|
||||
-------------------
|
||||
|
||||
The :meth:`add_handler() <pyrogram.Client.add_handler>` method takes any handler instance that wraps around your defined
|
||||
callback function and registers it in your Client. Here's a full example that prints out the content of a message as
|
||||
soon as it arrives:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client, MessageHandler
|
||||
|
||||
|
||||
def my_function(client, message):
|
||||
print(message)
|
||||
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
my_handler = MessageHandler(my_function)
|
||||
app.add_handler(my_handler)
|
||||
|
||||
app.run()
|
||||
|
||||
Let's examine these four new pieces. First one: a callback function we defined which accepts two arguments -
|
||||
*(client, message)*. This will be the function that gets executed every time a new message arrives and Pyrogram will
|
||||
call that function by passing the client instance and the new message instance as argument.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def my_function(client, message):
|
||||
print(message)
|
||||
|
||||
Second one: the :obj:`MessageHandler <pyrogram.MessageHandler>`. This object tells Pyrogram the function we defined
|
||||
above must only handle updates that are in form of a :obj:`Message <pyrogram.Message>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
my_handler = MessageHandler(my_function)
|
||||
|
||||
Third: the method :meth:`add_handler() <pyrogram.Client.add_handler>`. This method is used to actually register the
|
||||
handler and let Pyrogram know it needs to be taken into consideration when new updates arrive and the internal
|
||||
dispatching phase begins.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
app.add_handler(my_handler)
|
||||
|
||||
Last one, the :meth:`run() <pyrogram.Client.run>` method. What this does is simply call
|
||||
:meth:`start() <pyrogram.Client.start>` and a special method :meth:`idle() <pyrogram.Client.idle>` that keeps your main
|
||||
scripts alive until you press ``CTRL+C``; the client will be automatically stopped after that.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
app.run()
|
||||
|
||||
Using Decorators
|
||||
----------------
|
||||
|
||||
All of the above will become quite verbose, especially in case you have lots of handlers to register. A much nicer way
|
||||
to do so is by decorating your callback function with the :meth:`on_message() <pyrogram.Client.on_message>` decorator.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
|
||||
@app.on_message()
|
||||
def my_handler(client, message):
|
||||
print(message)
|
||||
|
||||
|
||||
app.run()
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
Due to how these decorators work in Pyrogram, they will wrap your defined callback function in a tuple consisting of
|
||||
``(handler, group)``; this will be the value held by your function identifier (e.g.: *my_function* from the example
|
||||
above).
|
||||
|
||||
In case, for some reason, you want to get your own function back after it has been decorated, you need to access
|
||||
``my_function[0].callback``, that is, the *callback* field of the *handler* object which is the first element in the
|
||||
tuple, accessed by bracket notation *[0]*.
|
||||
|
||||
.. _API methods: invoking
|
||||
26
docs/source/support-pyrogram.rst
Normal file
26
docs/source/support-pyrogram.rst
Normal 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
|
||||
@ -101,9 +101,9 @@ sending messages with IDs only thanks to cached access hashes.
|
||||
There are three different InputPeer types, one for each kind of Telegram entity.
|
||||
Whenever an InputPeer is needed you must pass one of these:
|
||||
|
||||
- `InputPeerUser <https://docs.pyrogram.ml/types/InputPeerUser>`_ - Users
|
||||
- `InputPeerChat <https://docs.pyrogram.ml/types/InputPeerChat>`_ - Basic Chats
|
||||
- `InputPeerChannel <https://docs.pyrogram.ml/types/InputPeerChannel>`_ - Either Channels or Supergroups
|
||||
- :obj:`InputPeerUser <../telegram/types/InputPeerUser>` - Users
|
||||
- :obj:`InputPeerChat <../telegram/types/InputPeerChat>` - Basic Chats
|
||||
- :obj:`InputPeerChannel <../telegram/types/InputPeerChannel>` - Either Channels or Supergroups
|
||||
|
||||
But you don't necessarily have to manually instantiate each object because, luckily for you, Pyrogram already provides
|
||||
:meth:`resolve_peer() <pyrogram.Client.resolve_peer>` as a convenience utility method that returns the correct InputPeer
|
||||
@ -125,12 +125,9 @@ For example, given the ID *123456789*, here's how Pyrogram can tell entities apa
|
||||
So, every time you take a raw ID, make sure to translate it into the correct ID when you want to use it with an
|
||||
high-level method.
|
||||
|
||||
|
||||
|
||||
|
||||
.. _methods: ../pyrogram/Client.html#messages
|
||||
.. _types: ../pyrogram/Types.html
|
||||
.. _plenty of them: ../pyrogram/Client.html#messages
|
||||
.. _raw functions: ../pyrogram/functions
|
||||
.. _raw types: ../pyrogram/types
|
||||
.. _Community: https://t.me/PyrogramChat
|
||||
.. _methods: ../api/methods
|
||||
.. _types: ../api/types
|
||||
.. _plenty of them: ../api/methods
|
||||
.. _raw functions: ../telegram/functions
|
||||
.. _raw types: ../telegram/types
|
||||
.. _Community: https://t.me/Pyrogram
|
||||
@ -54,7 +54,7 @@ The ``[pyrogram]`` section contains your Telegram API credentials: *api_id* and
|
||||
api_id = 12345
|
||||
api_hash = 0123456789abcdef0123456789abcdef
|
||||
|
||||
`More info about API Key. <../start/Setup.html#configuration>`_
|
||||
`More info about API Key. <../intro/setup#api-keys>`_
|
||||
|
||||
Proxy
|
||||
^^^^^
|
||||
@ -70,7 +70,7 @@ The ``[proxy]`` section contains settings about your SOCKS5 proxy.
|
||||
username = <your_username>
|
||||
password = <your_password>
|
||||
|
||||
`More info about SOCKS5 Proxy. <SOCKS5Proxy.html>`_
|
||||
`More info about SOCKS5 Proxy. <proxy>`_
|
||||
|
||||
Plugins
|
||||
^^^^^^^
|
||||
@ -87,4 +87,4 @@ The ``[plugins]`` section contains settings about Smart Plugins.
|
||||
exclude =
|
||||
module fn2
|
||||
|
||||
`More info about Smart Plugins. <SmartPlugins.html>`_
|
||||
`More info about Smart Plugins. <smart-plugins>`_
|
||||
@ -7,6 +7,9 @@ but there's much more than that to come.
|
||||
Here we'll discuss about :class:`Filters <pyrogram.Filters>`. Filters enable a fine-grain control over what kind of
|
||||
updates are allowed or not to be passed in your callback functions, based on their inner details.
|
||||
|
||||
Single Filters
|
||||
--------------
|
||||
|
||||
Let's start right away with a simple example:
|
||||
|
||||
- This example will show you how to **only** handle messages containing an :obj:`Audio <pyrogram.Audio>` object and
|
||||
@ -151,9 +151,9 @@ Continue Propagation
|
||||
|
||||
As opposed to `stopping the update propagation <#stop-propagation>`_ and also as an alternative to the
|
||||
`handler groups <#handler-groups>`_, you can signal the internal dispatcher to continue the update propagation within
|
||||
**the same group** regardless of the next handler's filters. This allows you to register multiple handlers with
|
||||
overlapping filters in the same group; to let the dispatcher process the next handler you can do *one* of the following
|
||||
in each handler you want to grant permission to continue:
|
||||
**the same group** despite having conflicting filters in the next registered handler. This allows you to register
|
||||
multiple handlers with overlapping filters in the same group; to let the dispatcher process the next handler you can do
|
||||
*one* of the following in each handler you want to grant permission to continue:
|
||||
|
||||
- Call the update's bound-method ``.continue_propagation()`` (preferred way).
|
||||
- Manually ``raise ContinuePropagation`` exception (more suitable for raw updates only).
|
||||
@ -218,5 +218,5 @@ The output of both (equivalent) examples will be:
|
||||
1
|
||||
2
|
||||
|
||||
.. _`update handlers`: UpdateHandling.html
|
||||
.. _`filters`: UsingFilters.html
|
||||
.. _`update handlers`: ../start/updates
|
||||
.. _`filters`: filters
|
||||
110
docs/source/topics/mtproto-vs-botapi.rst
Normal file
110
docs/source/topics/mtproto-vs-botapi.rst
Normal file
@ -0,0 +1,110 @@
|
||||
MTProto vs. 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 and the actual Telegram servers.
|
||||
|
||||
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 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 advantages in using MTProto-based libraries -- such as Pyrogram -- instead of the official
|
||||
HTTP Bot API. Using Pyrogram you can:
|
||||
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- :guilabel:`+` **Authorize both user and bot identities**
|
||||
- :guilabel:`--` The Bot API only allows bot accounts
|
||||
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- :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).
|
||||
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- :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.
|
||||
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- :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.
|
||||
|
||||
.. hlist::
|
||||
:columns: 1
|
||||
|
||||
- :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.
|
||||
|
||||
.. 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
55
docs/source/topics/serialize.rst
Normal 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.
|
||||
@ -1,24 +1,23 @@
|
||||
Customize Sessions
|
||||
==================
|
||||
Session Settings
|
||||
================
|
||||
|
||||
As you may probably know, Telegram allows users (and bots) having more than one session (authorizations) registered
|
||||
in the system at the same time.
|
||||
|
||||
Briefly explaining, sessions are simply new logins in your account. They can be reviewed in the settings of an official
|
||||
app (or by invoking `GetAuthorizations <../functions/account/GetAuthorizations.html>`_ with Pyrogram). They store some
|
||||
useful information such as the client who's using them and from which country and IP address.
|
||||
app (or by invoking `GetAuthorizations <../telegram/functions/account/GetAuthorizations.html>`_ with Pyrogram). They
|
||||
store some useful information such as the client who's using them and from which country and IP address.
|
||||
|
||||
|
||||
.. figure:: https://i.imgur.com/lzGPCdZ.png
|
||||
:width: 70%
|
||||
.. figure:: https://i.imgur.com/YaqtMLO.png
|
||||
:width: 600
|
||||
:align: center
|
||||
|
||||
**A Pyrogram session running on Linux, Python 3.6.**
|
||||
**A Pyrogram session running on Linux, Python 3.7.**
|
||||
|
||||
That's how a session looks like on the Android app, showing the three main pieces of information.
|
||||
|
||||
- ``app_version``: **Pyrogram 🔥 0.7.5**
|
||||
- ``device_model``: **CPython 3.6.5**
|
||||
- ``app_version``: **Pyrogram 0.13.0**
|
||||
- ``device_model``: **CPython 3.7.2**
|
||||
- ``system_version``: **Linux 4.15.0-23-generic**
|
||||
|
||||
Set Custom Values
|
||||
@ -30,7 +30,7 @@ after importing your modules, like this:
|
||||
handlers.py
|
||||
main.py
|
||||
|
||||
- ``handlers.py``
|
||||
- ``handlers.py``
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -41,7 +41,7 @@ after importing your modules, like this:
|
||||
def echo_reversed(client, message):
|
||||
message.reply(message.text[::-1])
|
||||
|
||||
- ``main.py``
|
||||
- ``main.py``
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -65,7 +65,7 @@ after importing your modules, like this:
|
||||
app.run()
|
||||
|
||||
This is already nice and doesn't add *too much* boilerplate code, but things can get boring still; you have to
|
||||
manually ``import``, manually :meth:`add_handler <pyrogram.Client.add_handler>` and manually instantiate each
|
||||
manually ``import``, manually :meth:`add_handler() <pyrogram.Client.add_handler>` and manually instantiate each
|
||||
:obj:`MessageHandler <pyrogram.MessageHandler>` object because **you can't use those cool decorators** for your
|
||||
functions. So, what if you could? Smart Plugins solve this issue by taking care of handlers registration automatically.
|
||||
|
||||
@ -91,7 +91,7 @@ Setting up your Pyrogram project to accommodate Smart Plugins is pretty straight
|
||||
config.ini
|
||||
main.py
|
||||
|
||||
- ``plugins/handlers.py``
|
||||
- ``plugins/handlers.py``
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 4, 9
|
||||
@ -108,14 +108,14 @@ Setting up your Pyrogram project to accommodate Smart Plugins is pretty straight
|
||||
def echo_reversed(client, message):
|
||||
message.reply(message.text[::-1])
|
||||
|
||||
- ``config.ini``
|
||||
- ``config.ini``
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[plugins]
|
||||
root = plugins
|
||||
|
||||
- ``main.py``
|
||||
- ``main.py``
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -156,7 +156,7 @@ found inside each module will be, instead, loaded in the order they are defined,
|
||||
.. note::
|
||||
|
||||
Remember: there can be at most one handler, within a group, dealing with a specific update. Plugins with overlapping
|
||||
filters included a second time will not work. Learn more at `More on Updates <MoreOnUpdates.html>`_.
|
||||
filters included a second time will not work. Learn more at `More on Updates <more-on-updates>`_.
|
||||
|
||||
This default loading behaviour is usually enough, but sometimes you want to have more control on what to include (or
|
||||
exclude) and in which exact order to load plugins. The way to do this is to make use of ``include`` and ``exclude``
|
||||
@ -199,8 +199,8 @@ also organized in subfolders:
|
||||
...
|
||||
...
|
||||
|
||||
- Load every handler from every module, namely *plugins0.py*, *plugins1.py* and *plugins2.py* in alphabetical order
|
||||
(files) and definition order (handlers inside files):
|
||||
- Load every handler from every module, namely *plugins0.py*, *plugins1.py* and *plugins2.py* in alphabetical order
|
||||
(files) and definition order (handlers inside files):
|
||||
|
||||
Using *config.ini* file:
|
||||
|
||||
@ -217,7 +217,7 @@ also organized in subfolders:
|
||||
|
||||
Client("my_account", plugins=plugins).run()
|
||||
|
||||
- Load only handlers defined inside *plugins2.py* and *plugins0.py*, in this order:
|
||||
- Load only handlers defined inside *plugins2.py* and *plugins0.py*, in this order:
|
||||
|
||||
Using *config.ini* file:
|
||||
|
||||
@ -243,7 +243,7 @@ also organized in subfolders:
|
||||
|
||||
Client("my_account", plugins=plugins).run()
|
||||
|
||||
- Load everything except the handlers inside *plugins2.py*:
|
||||
- Load everything except the handlers inside *plugins2.py*:
|
||||
|
||||
Using *config.ini* file:
|
||||
|
||||
@ -264,7 +264,7 @@ also organized in subfolders:
|
||||
|
||||
Client("my_account", plugins=plugins).run()
|
||||
|
||||
- Load only *fn3*, *fn1* and *fn2* (in this order) from *plugins1.py*:
|
||||
- Load only *fn3*, *fn1* and *fn2* (in this order) from *plugins1.py*:
|
||||
|
||||
Using *config.ini* file:
|
||||
|
||||
@ -297,7 +297,7 @@ Each function decorated with the usual ``on_message`` decorator (or any other de
|
||||
*(handler: Handler, group: int)*. The actual callback function is therefore stored inside the handler's *callback*
|
||||
attribute. Here's an example:
|
||||
|
||||
- ``plugins/handlers.py``
|
||||
- ``plugins/handlers.py``
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 5, 6
|
||||
@ -321,7 +321,7 @@ In order to unload a plugin, or any other handler, all you need to do is obtain
|
||||
relevant module and call :meth:`remove_handler() <pyrogram.Client.remove_handler>` Client's method with your function
|
||||
name preceded by the star ``*`` operator as argument. Example:
|
||||
|
||||
- ``main.py``
|
||||
- ``main.py``
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -345,7 +345,7 @@ Loading
|
||||
Similarly to the unloading process, in order to load again a previously unloaded plugin you do the same, but this time
|
||||
using :meth:`add_handler() <pyrogram.Client.add_handler>` instead. Example:
|
||||
|
||||
- ``main.py``
|
||||
- ``main.py``
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -11,7 +11,7 @@ Beside bold, italic, and pre-formatted code, **Pyrogram does also support inline
|
||||
Markdown Style
|
||||
--------------
|
||||
|
||||
To use this mode, pass :obj:`MARKDOWN <pyrogram.ParseMode.MARKDOWN>` or "markdown" in the *parse_mode* field when using
|
||||
To use this mode, pass "markdown" in the *parse_mode* field when using
|
||||
:obj:`send_message() <pyrogram.Client.send_message>`. Use the following syntax in your message:
|
||||
|
||||
.. code-block:: text
|
||||
@ -20,7 +20,7 @@ To use this mode, pass :obj:`MARKDOWN <pyrogram.ParseMode.MARKDOWN>` or "markdow
|
||||
|
||||
__italic text__
|
||||
|
||||
[inline URL](https://docs.pyrogram.ml/)
|
||||
[inline URL](https://docs.pyrogram.org/)
|
||||
|
||||
[inline mention of a user](tg://user?id=23122162)
|
||||
|
||||
@ -34,8 +34,8 @@ To use this mode, pass :obj:`MARKDOWN <pyrogram.ParseMode.MARKDOWN>` or "markdow
|
||||
HTML Style
|
||||
----------
|
||||
|
||||
To use this mode, pass :obj:`HTML <pyrogram.ParseMode.HTML>` or "html" in the *parse_mode* field when using
|
||||
:obj:`send_message() <pyrogram.Client.send_message>`. The following tags are currently supported:
|
||||
To use this mode, pass "html" in the *parse_mode* field when using :obj:`send_message() <pyrogram.Client.send_message>`.
|
||||
The following tags are currently supported:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
@ -43,7 +43,7 @@ To use this mode, pass :obj:`HTML <pyrogram.ParseMode.HTML>` or "html" in the *p
|
||||
|
||||
<i>italic</i>, <em>italic</em>
|
||||
|
||||
<a href="http://docs.pyrogram.ml/">inline URL</a>
|
||||
<a href="http://docs.pyrogram.org/">inline URL</a>
|
||||
|
||||
<a href="tg://user?id=23122162">inline mention of a user</a>
|
||||
|
||||
@ -66,7 +66,7 @@ Examples
|
||||
"**bold**, "
|
||||
"__italic__, "
|
||||
"[mention](tg://user?id=23122162), "
|
||||
"[URL](https://docs.pyrogram.ml), "
|
||||
"[URL](https://docs.pyrogram.org), "
|
||||
"`code`, "
|
||||
"```"
|
||||
"for i in range(10):\n"
|
||||
@ -84,7 +84,7 @@ Examples
|
||||
"<b>bold</b>, "
|
||||
"<i>italic</i>, "
|
||||
"<a href=\"tg://user?id=23122162\">mention</a>, "
|
||||
"<a href=\"https://pyrogram.ml/\">URL</a>, "
|
||||
"<a href=\"https://pyrogram.org/\">URL</a>, "
|
||||
"<code>code</code>, "
|
||||
"<pre>"
|
||||
"for i in range(10):\n"
|
||||
@ -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.
|
||||
@ -12,12 +12,12 @@ Example | Description
|
||||
---: | :---
|
||||
[**hello_world**](hello_world.py) | Demonstration of basic API usage
|
||||
[**echobot**](echobot.py) | Echo every private text message
|
||||
[**welcome**](welcome.py) | The Welcome Bot in [@PyrogramChat](https://t.me/pyrogramchat)
|
||||
[**history**](history.py) | Get the full message history of a chat
|
||||
[**chat_members**](chat_members.py) | Get all the members of a chat
|
||||
[**dialogs**](dialogs.py) | Get all of your dialog chats
|
||||
[**using_inline_bots**](using_inline_bots.py) | Query an inline bot (as user) and send a result to a chat
|
||||
[**keyboards**](keyboards.py) | Send normal and inline keyboards using regular bots
|
||||
[**callback_queries**](callback_queries.py) | Handle queries coming from inline button presses
|
||||
[**inline_queries**](inline_queries.py) | Handle inline queries
|
||||
[**welcomebot**](welcomebot.py) | The Welcome Bot in [@PyrogramChat](https://t.me/pyrogramchat)
|
||||
[**get_history**](get_history.py) | Get the full message history of a chat
|
||||
[**get_chat_members**](get_chat_members.py) | Get all the members of a chat
|
||||
[**get_dialogs**](get_dialogs.py) | Get all of your dialog chats
|
||||
[**callback_queries**](callback_queries.py) | Handle callback queries (as bot) coming from inline button presses
|
||||
[**inline_queries**](inline_queries.py) | Handle inline queries (as bot) and answer with results
|
||||
[**use_inline_bots**](use_inline_bots.py) | Query an inline bot (as user) and send a result to a chat
|
||||
[**bot_keyboards**](bot_keyboards.py) | Send normal and inline keyboards using regular bots
|
||||
[**raw_updates**](raw_updates.py) | Handle raw updates (old, should be avoided)
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
"""This example will show you how to send normal and inline keyboards.
|
||||
"""This example will show you how to send normal and inline keyboards (as bot).
|
||||
|
||||
You must log-in as a regular bot in order to send keyboards (use the token from @BotFather).
|
||||
Any attempt in sending keyboards with a user account will be simply ignored by the server.
|
||||
@ -39,7 +39,7 @@ with app:
|
||||
),
|
||||
InlineKeyboardButton( # Opens a web URL
|
||||
"URL",
|
||||
url="https://docs.pyrogram.ml"
|
||||
url="https://docs.pyrogram.org"
|
||||
),
|
||||
],
|
||||
[ # Second row
|
||||
@ -1,4 +1,4 @@
|
||||
"""This example shows how to get the full dialogs list of a user."""
|
||||
"""This example shows how to get the full dialogs list (as user)."""
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
@ -22,12 +22,12 @@ def answer(client, inline_query):
|
||||
input_message_content=InputTextMessageContent(
|
||||
"Here's how to install **Pyrogram**"
|
||||
),
|
||||
url="https://docs.pyrogram.ml/start/Installation",
|
||||
url="https://docs.pyrogram.org/intro/install",
|
||||
description="How to install Pyrogram",
|
||||
thumb_url="https://i.imgur.com/JyxrStE.png",
|
||||
reply_markup=InlineKeyboardMarkup(
|
||||
[
|
||||
[InlineKeyboardButton("Open website", url="https://docs.pyrogram.ml/start/Installation")]
|
||||
[InlineKeyboardButton("Open website", url="https://docs.pyrogram.org/intro/install")]
|
||||
]
|
||||
)
|
||||
),
|
||||
@ -37,12 +37,12 @@ def answer(client, inline_query):
|
||||
input_message_content=InputTextMessageContent(
|
||||
"Here's how to use **Pyrogram**"
|
||||
),
|
||||
url="https://docs.pyrogram.ml/start/Usage",
|
||||
url="https://docs.pyrogram.org/start/invoking",
|
||||
description="How to use Pyrogram",
|
||||
thumb_url="https://i.imgur.com/JyxrStE.png",
|
||||
reply_markup=InlineKeyboardMarkup(
|
||||
[
|
||||
[InlineKeyboardButton("Open website", url="https://docs.pyrogram.ml/start/Usage")]
|
||||
[InlineKeyboardButton("Open website", url="https://docs.pyrogram.org/start/invoking")]
|
||||
]
|
||||
)
|
||||
)
|
||||
|
||||
13
examples/use_inline_bots.py
Normal file
13
examples/use_inline_bots.py
Normal file
@ -0,0 +1,13 @@
|
||||
"""This example shows how to query an inline bot (as user)"""
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
# Create a new Client
|
||||
app = Client("my_account")
|
||||
|
||||
with app:
|
||||
# Get bot results for "Fuzz Universe" from the inline bot @vid
|
||||
bot_results = app.get_inline_bot_results("vid", "Fuzz Universe")
|
||||
|
||||
# Send the first result (bot_results.results[0]) to your own chat (Saved Messages)
|
||||
app.send_inline_bot_result("me", bot_results.query_id, bot_results.results[0].id)
|
||||
@ -1,17 +0,0 @@
|
||||
"""This example shows how to query an inline bot"""
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
# Create a new Client
|
||||
app = Client("my_account")
|
||||
|
||||
# Start the Client
|
||||
app.start()
|
||||
|
||||
# Get bot results for "Fuzz Universe" from the inline bot @vid
|
||||
bot_results = app.get_inline_bot_results("vid", "Fuzz Universe")
|
||||
# Send the first result (bot_results.results[0]) to your own chat (Saved Messages)
|
||||
app.send_inline_bot_result("me", bot_results.query_id, bot_results.results[0].id)
|
||||
|
||||
# Stop the client
|
||||
app.stop()
|
||||
@ -8,7 +8,7 @@ from pyrogram import Client, Emoji, Filters
|
||||
|
||||
TARGET = "PyrogramChat" # Target chat. Can also be a list of multiple chat ids/usernames
|
||||
MENTION = "[{}](tg://user?id={})" # User mention markup
|
||||
MESSAGE = "{} Welcome to [Pyrogram](https://docs.pyrogram.ml/)'s group chat {}!" # Welcome message
|
||||
MESSAGE = "{} Welcome to [Pyrogram](https://docs.pyrogram.org/)'s group chat {}!" # Welcome message
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
@ -26,9 +26,7 @@ if sys.version_info[:3] in [(3, 5, 0), (3, 5, 1), (3, 5, 2)]:
|
||||
|
||||
__version__ = "0.13.0.async"
|
||||
__license__ = "GNU Lesser General Public License v3 or later (LGPLv3+)"
|
||||
__copyright__ = "Copyright (C) 2017-2019 Dan Tès <https://github.com/delivrance>".replace(
|
||||
"\xe8", "e" if sys.getfilesystemencoding() != "utf-8" else "\xe8"
|
||||
)
|
||||
__copyright__ = "Copyright (C) 2017-2019 Dan <https://github.com/delivrance>"
|
||||
|
||||
try:
|
||||
import uvloop
|
||||
|
||||
@ -30,43 +30,51 @@ class Object:
|
||||
QUALNAME = "Base"
|
||||
|
||||
@staticmethod
|
||||
def read(b: BytesIO, *args):
|
||||
def read(b: BytesIO, *args): # TODO: Rename b -> data
|
||||
return Object.all[int.from_bytes(b.read(4), "little")].read(b, *args)
|
||||
|
||||
def write(self, *args) -> bytes:
|
||||
pass
|
||||
|
||||
def __eq__(self, other: "Object") -> bool:
|
||||
for attr in self.__slots__:
|
||||
try:
|
||||
if getattr(self, attr) != getattr(other, attr):
|
||||
return False
|
||||
except AttributeError:
|
||||
return False
|
||||
|
||||
return True
|
||||
|
||||
def __str__(self) -> str:
|
||||
def default(obj: Object):
|
||||
try:
|
||||
return OrderedDict(
|
||||
[("_", obj.QUALNAME)]
|
||||
+ [(attr, getattr(obj, attr))
|
||||
for attr in obj.__slots__
|
||||
if getattr(obj, attr) is not None]
|
||||
)
|
||||
except AttributeError:
|
||||
if isinstance(obj, datetime):
|
||||
return obj.strftime("%d-%b-%Y %H:%M:%S")
|
||||
else:
|
||||
return repr(obj)
|
||||
|
||||
return dumps(self, indent=4, default=default, ensure_ascii=False)
|
||||
|
||||
def __repr__(self) -> str:
|
||||
return "pyrogram.api.{}({})".format(
|
||||
self.QUALNAME,
|
||||
", ".join(
|
||||
"{}={}".format(attr, repr(getattr(self, attr)))
|
||||
for attr in self.__slots__
|
||||
if getattr(self, attr) is not None
|
||||
)
|
||||
)
|
||||
|
||||
def __len__(self) -> int:
|
||||
return len(self.write())
|
||||
|
||||
def __getitem__(self, item):
|
||||
return getattr(self, item)
|
||||
|
||||
|
||||
def remove_none(obj):
|
||||
if isinstance(obj, (list, tuple, set)):
|
||||
return type(obj)(remove_none(x) for x in obj if x is not None)
|
||||
elif isinstance(obj, dict):
|
||||
return type(obj)((remove_none(k), remove_none(v)) for k, v in obj.items() if k is not None and v is not None)
|
||||
else:
|
||||
return obj
|
||||
|
||||
|
||||
def default(o: "Object"):
|
||||
try:
|
||||
content = {i: getattr(o, i) for i in o.__slots__}
|
||||
|
||||
return remove_none(
|
||||
OrderedDict(
|
||||
[("_", o.QUALNAME)]
|
||||
+ [i for i in content.items()]
|
||||
)
|
||||
)
|
||||
except AttributeError:
|
||||
if isinstance(o, datetime):
|
||||
return o.strftime("%d-%b-%Y %H:%M:%S")
|
||||
else:
|
||||
return repr(o)
|
||||
|
||||
@ -17,9 +17,9 @@
|
||||
# along with Pyrogram. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
from .client import Client
|
||||
from .ext import BaseClient, ChatAction, Emoji, ParseMode
|
||||
from .ext import BaseClient, Emoji
|
||||
from .filters import Filters
|
||||
|
||||
__all__ = [
|
||||
"Client", "BaseClient", "ChatAction", "Emoji", "ParseMode", "Filters",
|
||||
"Client", "BaseClient", "Emoji", "Filters",
|
||||
]
|
||||
|
||||
@ -61,27 +61,23 @@ log = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class Client(Methods, BaseClient):
|
||||
"""This class represents a Client, the main mean for interacting with Telegram.
|
||||
It exposes bot-like methods for an easy access to the API as well as a simple way to
|
||||
invoke every single Telegram API method available.
|
||||
"""Pyrogram Client, the main means for interacting with Telegram.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
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*):
|
||||
Application version. Defaults to "Pyrogram \U0001f525 vX.Y.Z"
|
||||
Application version. Defaults to "Pyrogram X.Y.Z"
|
||||
This is an alternative way to set it if you don't want to use the *config.ini* file.
|
||||
|
||||
device_model (``str``, *optional*):
|
||||
@ -107,10 +103,14 @@ 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.
|
||||
|
||||
bot_token (``str``, *optional*):
|
||||
Pass your Bot API token to create a bot session, e.g.: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
|
||||
Only applicable for new sessions.
|
||||
|
||||
phone_number (``str`` | ``callable``, *optional*):
|
||||
Pass your phone number as string (with your Country Code prefix included) to avoid entering it manually.
|
||||
Or pass a callback function which accepts no arguments and must return the correct phone number as string
|
||||
@ -144,10 +144,6 @@ class Client(Methods, BaseClient):
|
||||
a new Telegram account in case the phone number you passed is not registered yet.
|
||||
Only applicable for new sessions.
|
||||
|
||||
bot_token (``str``, *optional*):
|
||||
Pass your Bot API token to create a bot session, e.g.: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
|
||||
Only applicable for new sessions.
|
||||
|
||||
last_name (``str``, *optional*):
|
||||
Same purpose as *first_name*; pass a Last Name to avoid entering it manually. It can
|
||||
be an empty string: "". Only applicable for new sessions.
|
||||
@ -173,7 +169,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.
|
||||
@ -194,12 +190,12 @@ class Client(Methods, BaseClient):
|
||||
ipv6: bool = False,
|
||||
proxy: dict = None,
|
||||
test_mode: bool = False,
|
||||
bot_token: str = None,
|
||||
phone_number: str = None,
|
||||
phone_code: Union[str, callable] = None,
|
||||
password: str = None,
|
||||
recovery_code: callable = None,
|
||||
force_sms: bool = False,
|
||||
bot_token: str = None,
|
||||
first_name: str = None,
|
||||
last_name: str = None,
|
||||
workers: int = BaseClient.WORKERS,
|
||||
@ -222,12 +218,12 @@ class Client(Methods, BaseClient):
|
||||
# TODO: Make code consistent, use underscore for private/protected fields
|
||||
self._proxy = proxy
|
||||
self.test_mode = test_mode
|
||||
self.bot_token = bot_token
|
||||
self.phone_number = phone_number
|
||||
self.phone_code = phone_code
|
||||
self.password = password
|
||||
self.recovery_code = recovery_code
|
||||
self.force_sms = force_sms
|
||||
self.bot_token = bot_token
|
||||
self.first_name = first_name
|
||||
self.last_name = last_name
|
||||
self.workers = workers
|
||||
@ -268,12 +264,11 @@ class Client(Methods, BaseClient):
|
||||
self._proxy.update(value)
|
||||
|
||||
async def start(self):
|
||||
"""Use this method to start the Client after creating it.
|
||||
Requires no parameters.
|
||||
"""Start the Client.
|
||||
|
||||
Raises:
|
||||
:class:`RPCError <pyrogram.RPCError>` in case of a Telegram RPC error.
|
||||
``ConnectionError`` in case you try to start an already started Client.
|
||||
RPCError: In case of a Telegram RPC error.
|
||||
ConnectionError: In case you try to start an already started Client.
|
||||
"""
|
||||
if self.is_started:
|
||||
raise ConnectionError("Client has already been started")
|
||||
@ -285,7 +280,7 @@ class Client(Methods, BaseClient):
|
||||
log.warning('\nWARNING: You are using a bot token as session name!\n'
|
||||
'This usage will be deprecated soon. Please use a session file name to load '
|
||||
'an existing session and the bot_token argument to create new sessions.\n'
|
||||
'More info: https://docs.pyrogram.ml/start/Setup#bot-authorization\n')
|
||||
'More info: https://docs.pyrogram.org/intro/auth#bot-authorization\n')
|
||||
|
||||
self.load_config()
|
||||
await self.load_session()
|
||||
@ -351,11 +346,10 @@ class Client(Methods, BaseClient):
|
||||
return self
|
||||
|
||||
async def stop(self):
|
||||
"""Use this method to manually stop the Client.
|
||||
Requires no parameters.
|
||||
"""Stop the Client.
|
||||
|
||||
Raises:
|
||||
``ConnectionError`` in case you try to stop an already stopped Client.
|
||||
ConnectionError: In case you try to stop an already stopped Client.
|
||||
"""
|
||||
if not self.is_started:
|
||||
raise ConnectionError("Client is already stopped")
|
||||
@ -391,25 +385,34 @@ class Client(Methods, BaseClient):
|
||||
return self
|
||||
|
||||
async def restart(self):
|
||||
"""Use this method to restart the Client.
|
||||
Requires no parameters.
|
||||
"""Restart the Client.
|
||||
|
||||
Raises:
|
||||
``ConnectionError`` in case you try to restart a stopped Client.
|
||||
ConnectionError: In case you try to restart a stopped Client.
|
||||
"""
|
||||
await self.stop()
|
||||
await self.start()
|
||||
|
||||
async def idle(self, stop_signals: tuple = (SIGINT, SIGTERM, SIGABRT)):
|
||||
"""Blocks the program execution until one of the signals are received,
|
||||
then gently stop the Client by closing the underlying connection.
|
||||
"""Block the main script execution until a signal (e.g.: from CTRL+C) is received.
|
||||
Once the signal is received, the client will automatically stop and the main script will continue its execution.
|
||||
|
||||
Args:
|
||||
This is used after starting one or more clients and is useful for event-driven applications only, that are,
|
||||
applications which react upon incoming Telegram updates through handlers, rather than executing a set of methods
|
||||
sequentially.
|
||||
|
||||
The way Pyrogram works, will keep your handlers in a pool of workers, which are executed concurrently outside
|
||||
the main script; calling idle() will ensure the client(s) will be kept alive by not letting the main script to
|
||||
end, until you decide to quit.
|
||||
|
||||
Parameters:
|
||||
stop_signals (``tuple``, *optional*):
|
||||
Iterable containing signals the signal handler will listen to.
|
||||
Defaults to (SIGINT, SIGTERM, SIGABRT).
|
||||
"""
|
||||
|
||||
# TODO: Maybe make this method static and don't automatically stop
|
||||
|
||||
def signal_handler(*args):
|
||||
log.info("Stop signal received ({}). Exiting...".format(args[0]))
|
||||
self.is_idle = False
|
||||
@ -425,16 +428,18 @@ class Client(Methods, BaseClient):
|
||||
await self.stop()
|
||||
|
||||
def run(self, coroutine=None):
|
||||
"""Use this method to automatically start and idle a Client.
|
||||
If a coroutine is passed as argument this method will start the client, run the coroutine
|
||||
until is complete and then stop the client automatically.
|
||||
"""Start the Client and automatically idle the main script.
|
||||
|
||||
This is a convenience method that literally just calls :meth:`start` and :meth:`idle`. It makes running a client
|
||||
less verbose, but is not suitable in case you want to run more than one client in a single main script,
|
||||
since :meth:`idle` will block.
|
||||
|
||||
Args:
|
||||
coroutine: (``Coroutine``, *optional*):
|
||||
Pass a coroutine to run it until is complete.
|
||||
|
||||
Raises:
|
||||
:class:`RPCError <pyrogram.RPCError>` in case of a Telegram RPC error.
|
||||
RPCError: In case of a Telegram RPC error.
|
||||
"""
|
||||
run = asyncio.get_event_loop().run_until_complete
|
||||
|
||||
@ -452,13 +457,13 @@ class Client(Methods, BaseClient):
|
||||
return coroutine
|
||||
|
||||
def add_handler(self, handler: Handler, group: int = 0):
|
||||
"""Use this method to register an update handler.
|
||||
"""Register an update handler.
|
||||
|
||||
You can register multiple handlers, but at most one handler within a group
|
||||
will be used for a single update. To handle the same update more than once, register
|
||||
your handler using a different group id (lower group id == higher priority).
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
handler (``Handler``):
|
||||
The handler to be registered.
|
||||
|
||||
@ -466,7 +471,7 @@ class Client(Methods, BaseClient):
|
||||
The group identifier, defaults to 0.
|
||||
|
||||
Returns:
|
||||
A tuple of (handler, group)
|
||||
``tuple``: A tuple consisting of (handler, group).
|
||||
"""
|
||||
if isinstance(handler, DisconnectHandler):
|
||||
self.disconnect_handler = handler.callback
|
||||
@ -476,13 +481,13 @@ class Client(Methods, BaseClient):
|
||||
return handler, group
|
||||
|
||||
def remove_handler(self, handler: Handler, group: int = 0):
|
||||
"""Removes a previously-added update handler.
|
||||
"""Remove a previously-registered update handler.
|
||||
|
||||
Make sure to provide the right group that the handler was added in. You can use
|
||||
the return value of the :meth:`add_handler` method, a tuple of (handler, group), and
|
||||
pass it directly.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
handler (``Handler``):
|
||||
The handler to be removed.
|
||||
|
||||
@ -495,7 +500,7 @@ class Client(Methods, BaseClient):
|
||||
self.dispatcher.remove_handler(handler, group)
|
||||
|
||||
def stop_transmission(self):
|
||||
"""Use this method to stop downloading or uploading a file.
|
||||
"""Stop downloading or uploading a file.
|
||||
Must be called inside a progress callback function.
|
||||
"""
|
||||
raise Client.StopTransmission
|
||||
@ -763,9 +768,16 @@ class Client(Methods, BaseClient):
|
||||
|
||||
print("Logged in successfully as {}".format(r.user.first_name))
|
||||
|
||||
def fetch_peers(self, entities: List[Union[types.User,
|
||||
types.Chat, types.ChatForbidden,
|
||||
types.Channel, types.ChannelForbidden]]):
|
||||
def fetch_peers(
|
||||
self,
|
||||
entities: List[
|
||||
Union[
|
||||
types.User,
|
||||
types.Chat, types.ChatForbidden,
|
||||
types.Channel, types.ChannelForbidden
|
||||
]
|
||||
]
|
||||
):
|
||||
for entity in entities:
|
||||
if isinstance(entity, types.User):
|
||||
user_id = entity.id
|
||||
@ -1027,14 +1039,20 @@ class Client(Methods, BaseClient):
|
||||
data: Object,
|
||||
retries: int = Session.MAX_RETRIES,
|
||||
timeout: float = Session.WAIT_TIMEOUT):
|
||||
"""Use this method to send Raw Function queries.
|
||||
"""Send raw Telegram queries.
|
||||
|
||||
This method makes possible to manually call every single Telegram API method in a low-level manner.
|
||||
This method makes it possible to manually call every single Telegram API method in a low-level manner.
|
||||
Available functions are listed in the :obj:`functions <pyrogram.api.functions>` package and may accept compound
|
||||
data types from :obj:`types <pyrogram.api.types>` as well as bare types such as ``int``, ``str``, etc...
|
||||
|
||||
Args:
|
||||
data (``Object``):
|
||||
.. note::
|
||||
|
||||
This is a utility method intended to be used **only** when working with raw
|
||||
:obj:`functions <pyrogram.api.functions>` (i.e: a Telegram API method you wish to use which is not
|
||||
available yet in the Client class as an easy-to-use method).
|
||||
|
||||
Parameters:
|
||||
data (``RawFunction``):
|
||||
The API Schema function filled with proper arguments.
|
||||
|
||||
retries (``int``):
|
||||
@ -1043,8 +1061,11 @@ class Client(Methods, BaseClient):
|
||||
timeout (``float``):
|
||||
Timeout in seconds.
|
||||
|
||||
Returns:
|
||||
``RawType``: The raw type response generated by the query.
|
||||
|
||||
Raises:
|
||||
:class:`RPCError <pyrogram.RPCError>` in case of a Telegram RPC error.
|
||||
RPCError: In case of a Telegram RPC error.
|
||||
"""
|
||||
if not self.is_started:
|
||||
raise ConnectionError("Client has not been started")
|
||||
@ -1075,7 +1096,7 @@ class Client(Methods, BaseClient):
|
||||
else:
|
||||
raise AttributeError(
|
||||
"No API Key found. "
|
||||
"More info: https://docs.pyrogram.ml/start/ProjectSetup#configuration"
|
||||
"More info: https://docs.pyrogram.org/intro/setup#configuration"
|
||||
)
|
||||
|
||||
for option in ["app_version", "device_model", "system_version", "lang_code"]:
|
||||
@ -1325,23 +1346,26 @@ class Client(Methods, BaseClient):
|
||||
|
||||
async def resolve_peer(self,
|
||||
peer_id: Union[int, str]):
|
||||
"""Use this method to get the InputPeer of a known peer_id.
|
||||
"""Get the InputPeer of a known peer id.
|
||||
Useful whenever an InputPeer type is required.
|
||||
|
||||
This is a utility method intended to be used **only** when working with Raw Functions (i.e: a Telegram API
|
||||
method you wish to use which is not available yet in the Client class as an easy-to-use method), whenever an
|
||||
InputPeer type is required.
|
||||
.. note::
|
||||
|
||||
Args:
|
||||
This is a utility method intended to be used **only** when working with raw
|
||||
:obj:`functions <pyrogram.api.functions>` (i.e: a Telegram API method you wish to use which is not
|
||||
available yet in the Client class as an easy-to-use method).
|
||||
|
||||
Parameters:
|
||||
peer_id (``int`` | ``str``):
|
||||
The peer id you want to extract the InputPeer from.
|
||||
Can be a direct id (int), a username (str) or a phone number (str).
|
||||
|
||||
Returns:
|
||||
On success, the resolved peer id is returned in form of an InputPeer object.
|
||||
``InputPeer``: On success, the resolved peer id is returned in form of an InputPeer object.
|
||||
|
||||
Raises:
|
||||
:class:`RPCError <pyrogram.RPCError>` in case of a Telegram RPC error.
|
||||
``KeyError`` in case the peer doesn't exist in the internal database.
|
||||
RPCError: In case of a Telegram RPC error.
|
||||
KeyError: In case the peer doesn't exist in the internal database.
|
||||
"""
|
||||
try:
|
||||
return self.peers_by_id[peer_id]
|
||||
@ -1399,14 +1423,18 @@ class Client(Methods, BaseClient):
|
||||
file_id: int = None,
|
||||
file_part: int = 0,
|
||||
progress: callable = None,
|
||||
progress_args: tuple = ()):
|
||||
"""Use this method to upload a file onto Telegram servers, without actually sending the message to anyone.
|
||||
progress_args: tuple = ()
|
||||
):
|
||||
"""Upload a file onto Telegram servers, without actually sending the message to anyone.
|
||||
Useful whenever an InputFile type is required.
|
||||
|
||||
This is a utility method intended to be used **only** when working with Raw Functions (i.e: a Telegram API
|
||||
method you wish to use which is not available yet in the Client class as an easy-to-use method), whenever an
|
||||
InputFile type is required.
|
||||
.. note::
|
||||
|
||||
Args:
|
||||
This is a utility method intended to be used **only** when working with raw
|
||||
:obj:`functions <pyrogram.api.functions>` (i.e: a Telegram API method you wish to use which is not
|
||||
available yet in the Client class as an easy-to-use method).
|
||||
|
||||
Parameters:
|
||||
path (``str``):
|
||||
The path of the file you want to upload that exists on your local machine.
|
||||
|
||||
@ -1426,7 +1454,7 @@ class Client(Methods, BaseClient):
|
||||
a chat_id and a message_id in order to edit a message with the updated progress.
|
||||
|
||||
Other Parameters:
|
||||
client (:obj:`Client <pyrogram.Client>`):
|
||||
client (:obj:`Client`):
|
||||
The Client itself, useful when you want to call other API methods inside the callback function.
|
||||
|
||||
current (``int``):
|
||||
@ -1440,10 +1468,10 @@ class Client(Methods, BaseClient):
|
||||
You can either keep *\*args* or add every single extra argument in your function signature.
|
||||
|
||||
Returns:
|
||||
On success, the uploaded file is returned in form of an InputFile object.
|
||||
``InputFile``: On success, the uploaded file is returned in form of an InputFile object.
|
||||
|
||||
Raises:
|
||||
:class:`RPCError <pyrogram.RPCError>` in case of a Telegram RPC error.
|
||||
RPCError: In case of a Telegram RPC error.
|
||||
"""
|
||||
|
||||
async def worker(session):
|
||||
|
||||
@ -17,8 +17,6 @@
|
||||
# along with Pyrogram. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
from .base_client import BaseClient
|
||||
from .chat_action import ChatAction
|
||||
from .dispatcher import Dispatcher
|
||||
from .emoji import Emoji
|
||||
from .parse_mode import ParseMode
|
||||
from .syncer import Syncer
|
||||
|
||||
@ -30,7 +30,7 @@ class BaseClient:
|
||||
class StopTransmission(StopAsyncIteration):
|
||||
pass
|
||||
|
||||
APP_VERSION = "Pyrogram \U0001f525 {}".format(__version__)
|
||||
APP_VERSION = "Pyrogram {}".format(__version__)
|
||||
|
||||
DEVICE_MODEL = "{} {}".format(
|
||||
platform.python_implementation(),
|
||||
|
||||
@ -1,77 +0,0 @@
|
||||
# Pyrogram - Telegram MTProto API Client Library for Python
|
||||
# Copyright (C) 2017-2019 Dan Tès <https://github.com/delivrance>
|
||||
#
|
||||
# This file is part of Pyrogram.
|
||||
#
|
||||
# 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.
|
||||
#
|
||||
# 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.
|
||||
#
|
||||
# You should have received a copy of the GNU Lesser General Public License
|
||||
# along with Pyrogram. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
from enum import Enum
|
||||
|
||||
from pyrogram.api import types
|
||||
|
||||
|
||||
class ChatAction(Enum):
|
||||
"""This enumeration provides a convenient access to all Chat Actions available.
|
||||
Chat Actions are intended to be used with
|
||||
:meth:`send_chat_action() <pyrogram.Client.send_chat_action>`.
|
||||
"""
|
||||
|
||||
CANCEL = types.SendMessageCancelAction
|
||||
"""Cancels any chat action currently displayed."""
|
||||
|
||||
TYPING = types.SendMessageTypingAction
|
||||
"""User is typing a text message."""
|
||||
|
||||
PLAYING = types.SendMessageGamePlayAction
|
||||
"""User is playing a game."""
|
||||
|
||||
CHOOSE_CONTACT = types.SendMessageChooseContactAction
|
||||
"""User is choosing a contact to share."""
|
||||
|
||||
UPLOAD_PHOTO = types.SendMessageUploadPhotoAction
|
||||
"""User is uploading a photo."""
|
||||
|
||||
RECORD_VIDEO = types.SendMessageRecordVideoAction
|
||||
"""User is recording a video."""
|
||||
|
||||
UPLOAD_VIDEO = types.SendMessageUploadVideoAction
|
||||
"""User is uploading a video."""
|
||||
|
||||
RECORD_AUDIO = types.SendMessageRecordAudioAction
|
||||
"""User is recording an audio message."""
|
||||
|
||||
UPLOAD_AUDIO = types.SendMessageUploadAudioAction
|
||||
"""User is uploading an audio message."""
|
||||
|
||||
UPLOAD_DOCUMENT = types.SendMessageUploadDocumentAction
|
||||
"""User is uploading a generic document."""
|
||||
|
||||
FIND_LOCATION = types.SendMessageGeoLocationAction
|
||||
"""User is searching for a location on the map."""
|
||||
|
||||
RECORD_VIDEO_NOTE = types.SendMessageRecordRoundAction
|
||||
"""User is recording a round video note."""
|
||||
|
||||
UPLOAD_VIDEO_NOTE = types.SendMessageUploadRoundAction
|
||||
"""User is uploading a round video note."""
|
||||
|
||||
@staticmethod
|
||||
def from_string(action: str) -> "ChatAction":
|
||||
for a in ChatAction:
|
||||
if a.name.lower() == action.lower():
|
||||
return a
|
||||
|
||||
raise ValueError("Invalid ChatAction: '{}'. Possible types are {}".format(
|
||||
action, [x.name.lower() for x in ChatAction]
|
||||
))
|
||||
@ -1,29 +0,0 @@
|
||||
# Pyrogram - Telegram MTProto API Client Library for Python
|
||||
# Copyright (C) 2017-2019 Dan Tès <https://github.com/delivrance>
|
||||
#
|
||||
# This file is part of Pyrogram.
|
||||
#
|
||||
# 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.
|
||||
#
|
||||
# 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.
|
||||
#
|
||||
# You should have received a copy of the GNU Lesser General Public License
|
||||
# along with Pyrogram. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
|
||||
class ParseMode:
|
||||
"""This class provides a convenient access to Parse Modes.
|
||||
Parse Modes are intended to be used with any method that accepts the optional argument **parse_mode**.
|
||||
"""
|
||||
|
||||
HTML = "html"
|
||||
"""Set the parse mode to HTML style"""
|
||||
|
||||
MARKDOWN = "markdown"
|
||||
"""Set the parse mode to Markdown style"""
|
||||
@ -19,15 +19,15 @@
|
||||
import re
|
||||
|
||||
from .filter import Filter
|
||||
from ..types.bots import InlineKeyboardMarkup, ReplyKeyboardMarkup
|
||||
from ..types.keyboards import InlineKeyboardMarkup, ReplyKeyboardMarkup
|
||||
|
||||
|
||||
def create(name: str, func: callable, **kwargs) -> type:
|
||||
"""Use this method to create a Filter.
|
||||
"""Create a Filter.
|
||||
|
||||
Custom filters give you extra control over which updates are allowed or not to be processed by your handlers.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
name (``str``):
|
||||
Your filter's name. Can be anything you like.
|
||||
|
||||
@ -35,9 +35,9 @@ def create(name: str, func: callable, **kwargs) -> type:
|
||||
A function that accepts two arguments *(filter, update)* and returns a Boolean: True if the update should be
|
||||
handled, False otherwise.
|
||||
The "update" argument type will vary depending on which `Handler <Handlers.html>`_ is coming from.
|
||||
For example, in a :obj:`MessageHandler <pyrogram.MessageHandler>` the update type will be
|
||||
a :obj:`Message <pyrogram.Message>`; in a :obj:`CallbackQueryHandler <pyrogram.CallbackQueryHandler>` the
|
||||
update type will be a :obj:`CallbackQuery <pyrogram.CallbackQuery>`. Your function body can then access the
|
||||
For example, in a :obj:`MessageHandler` the update type will be
|
||||
a :obj:`Message`; in a :obj:`CallbackQueryHandler` the
|
||||
update type will be a :obj:`CallbackQuery`. Your function body can then access the
|
||||
incoming update and decide whether to allow it or not.
|
||||
|
||||
**kwargs (``any``, *optional*):
|
||||
@ -54,7 +54,7 @@ def create(name: str, func: callable, **kwargs) -> type:
|
||||
class Filters:
|
||||
"""This class provides access to all library-defined Filters available in Pyrogram.
|
||||
|
||||
The Filters listed here are intended to be used with the :obj:`MessageHandler <pyrogram.MessageHandler>` only.
|
||||
The Filters listed here are intended to be used with the :obj:`MessageHandler` only.
|
||||
At the moment, if you want to filter updates coming from different `Handlers <Handlers.html>`_ you have to create
|
||||
your own filters with :meth:`Filters.create` and use them in the same way.
|
||||
"""
|
||||
@ -89,49 +89,49 @@ class Filters:
|
||||
"""Filter edited messages."""
|
||||
|
||||
audio = create("Audio", lambda _, m: bool(m.audio))
|
||||
"""Filter messages that contain :obj:`Audio <pyrogram.Audio>` objects."""
|
||||
"""Filter messages that contain :obj:`Audio` objects."""
|
||||
|
||||
document = create("Document", lambda _, m: bool(m.document))
|
||||
"""Filter messages that contain :obj:`Document <pyrogram.Document>` objects."""
|
||||
"""Filter messages that contain :obj:`Document` objects."""
|
||||
|
||||
photo = create("Photo", lambda _, m: bool(m.photo))
|
||||
"""Filter messages that contain :obj:`Photo <pyrogram.PhotoSize>` objects."""
|
||||
"""Filter messages that contain :obj:`Photo` objects."""
|
||||
|
||||
sticker = create("Sticker", lambda _, m: bool(m.sticker))
|
||||
"""Filter messages that contain :obj:`Sticker <pyrogram.Sticker>` objects."""
|
||||
"""Filter messages that contain :obj:`Sticker` objects."""
|
||||
|
||||
animation = create("Animation", lambda _, m: bool(m.animation))
|
||||
"""Filter messages that contain :obj:`Animation <pyrogram.Animation>` objects."""
|
||||
"""Filter messages that contain :obj:`Animation` objects."""
|
||||
|
||||
game = create("Game", lambda _, m: bool(m.game))
|
||||
"""Filter messages that contain :obj:`Game <pyrogram.Game>` objects."""
|
||||
"""Filter messages that contain :obj:`Game` objects."""
|
||||
|
||||
video = create("Video", lambda _, m: bool(m.video))
|
||||
"""Filter messages that contain :obj:`Video <pyrogram.Video>` objects."""
|
||||
"""Filter messages that contain :obj:`Video` objects."""
|
||||
|
||||
media_group = create("MediaGroup", lambda _, m: bool(m.media_group_id))
|
||||
"""Filter messages containing photos or videos being part of an album."""
|
||||
|
||||
voice = create("Voice", lambda _, m: bool(m.voice))
|
||||
"""Filter messages that contain :obj:`Voice <pyrogram.Voice>` note objects."""
|
||||
"""Filter messages that contain :obj:`Voice` note objects."""
|
||||
|
||||
video_note = create("VideoNote", lambda _, m: bool(m.video_note))
|
||||
"""Filter messages that contain :obj:`VideoNote <pyrogram.VideoNote>` objects."""
|
||||
"""Filter messages that contain :obj:`VideoNote` objects."""
|
||||
|
||||
contact = create("Contact", lambda _, m: bool(m.contact))
|
||||
"""Filter messages that contain :obj:`Contact <pyrogram.Contact>` objects."""
|
||||
"""Filter messages that contain :obj:`Contact` objects."""
|
||||
|
||||
location = create("Location", lambda _, m: bool(m.location))
|
||||
"""Filter messages that contain :obj:`Location <pyrogram.Location>` objects."""
|
||||
"""Filter messages that contain :obj:`Location` objects."""
|
||||
|
||||
venue = create("Venue", lambda _, m: bool(m.venue))
|
||||
"""Filter messages that contain :obj:`Venue <pyrogram.Venue>` objects."""
|
||||
"""Filter messages that contain :obj:`Venue` objects."""
|
||||
|
||||
web_page = create("WebPage", lambda _, m: m.web_page)
|
||||
"""Filter messages sent with a webpage preview."""
|
||||
|
||||
poll = create("Poll", lambda _, m: m.poll)
|
||||
"""Filter messages that contain :obj:`Poll <pyrogram.Poll>` objects."""
|
||||
"""Filter messages that contain :obj:`Poll` objects."""
|
||||
|
||||
private = create("Private", lambda _, m: bool(m.chat and m.chat.type == "private"))
|
||||
"""Filter messages sent in private chats."""
|
||||
@ -191,35 +191,19 @@ class Filters:
|
||||
"""Filter messages sent via inline bots"""
|
||||
|
||||
service = create("Service", lambda _, m: bool(m.service))
|
||||
"""Filter service messages. A service message contains any of the following fields set
|
||||
"""Filter service messages.
|
||||
|
||||
- left_chat_member
|
||||
- new_chat_title
|
||||
- new_chat_photo
|
||||
- delete_chat_photo
|
||||
- group_chat_created
|
||||
- supergroup_chat_created
|
||||
- channel_chat_created
|
||||
- migrate_to_chat_id
|
||||
- migrate_from_chat_id
|
||||
- pinned_message
|
||||
- game_score"""
|
||||
A service message contains any of the following fields set: *left_chat_member*,
|
||||
*new_chat_title*, *new_chat_photo*, *delete_chat_photo*, *group_chat_created*, *supergroup_chat_created*,
|
||||
*channel_chat_created*, *migrate_to_chat_id*, *migrate_from_chat_id*, *pinned_message*, *game_score*.
|
||||
"""
|
||||
|
||||
media = create("Media", lambda _, m: bool(m.media))
|
||||
"""Filter media messages. A media message contains any of the following fields set
|
||||
"""Filter media messages.
|
||||
|
||||
- audio
|
||||
- document
|
||||
- photo
|
||||
- sticker
|
||||
- video
|
||||
- animation
|
||||
- voice
|
||||
- video_note
|
||||
- contact
|
||||
- location
|
||||
- venue
|
||||
- poll"""
|
||||
A media message contains any of the following fields set: *audio*, *document*, *photo*, *sticker*, *video*,
|
||||
*animation*, *voice*, *video_note*, *contact*, *location*, *venue*, *poll*.
|
||||
"""
|
||||
|
||||
@staticmethod
|
||||
def command(
|
||||
@ -230,12 +214,12 @@ class Filters:
|
||||
):
|
||||
"""Filter commands, i.e.: text messages starting with "/" or any other custom prefix.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
commands (``str`` | ``list``):
|
||||
The command or list of commands as string the filter should look for.
|
||||
Examples: "start", ["start", "help", "settings"]. When a message text containing
|
||||
a command arrives, the command itself and its arguments will be stored in the *command*
|
||||
field of the :class:`Message <pyrogram.Message>`.
|
||||
field of the :class:`Message`.
|
||||
|
||||
prefix (``str`` | ``list``, *optional*):
|
||||
A prefix or a list of prefixes as string the filter should look for.
|
||||
@ -275,11 +259,11 @@ class Filters:
|
||||
def regex(pattern, flags: int = 0):
|
||||
"""Filter messages that match a given RegEx pattern.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
pattern (``str``):
|
||||
The RegEx pattern as string, it will be applied to the text of a message. When a pattern matches,
|
||||
all the `Match Objects <https://docs.python.org/3/library/re.html#match-objects>`_
|
||||
are stored in the *matches* field of the :class:`Message <pyrogram.Message>` itself.
|
||||
are stored in the *matches* field of the :class:`Message` itself.
|
||||
|
||||
flags (``int``, *optional*):
|
||||
RegEx flags.
|
||||
@ -298,7 +282,7 @@ class Filters:
|
||||
You can use `set bound methods <https://docs.python.org/3/library/stdtypes.html#set>`_ to manipulate the
|
||||
users container.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
users (``int`` | ``str`` | ``list``):
|
||||
Pass one or more user ids/usernames to filter users.
|
||||
For you yourself, "me" or "self" can be used as well.
|
||||
@ -329,7 +313,7 @@ class Filters:
|
||||
You can use `set bound methods <https://docs.python.org/3/library/stdtypes.html#set>`_ to manipulate the
|
||||
chats container.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
chats (``int`` | ``str`` | ``list``):
|
||||
Pass one or more chat ids/usernames to filter chats.
|
||||
For your personal cloud (Saved Messages) you can simply use "me" or "self".
|
||||
|
||||
@ -26,17 +26,17 @@ class CallbackQueryHandler(Handler):
|
||||
For a nicer way to register this handler, have a look at the
|
||||
:meth:`on_callback_query() <pyrogram.Client.on_callback_query>` decorator.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
callback (``callable``):
|
||||
Pass a function that will be called when a new CallbackQuery arrives. It takes *(client, callback_query)*
|
||||
as positional arguments (look at the section below for a detailed description).
|
||||
|
||||
filters (:obj:`Filters <pyrogram.Filters>`):
|
||||
filters (:obj:`Filters`):
|
||||
Pass one or more filters to allow only a subset of callback queries to be passed
|
||||
in your callback function.
|
||||
|
||||
Other parameters:
|
||||
client (:obj:`Client <pyrogram.Client>`):
|
||||
client (:obj:`Client`):
|
||||
The Client itself, useful when you want to call other API methods inside the message handler.
|
||||
|
||||
callback_query (:obj:`CallbackQuery <pyrogram.CallbackQuery>`):
|
||||
|
||||
@ -27,20 +27,20 @@ class DeletedMessagesHandler(Handler):
|
||||
For a nicer way to register this handler, have a look at the
|
||||
:meth:`on_deleted_messages() <pyrogram.Client.on_deleted_messages>` decorator.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
callback (``callable``):
|
||||
Pass a function that will be called when one or more Messages have been deleted.
|
||||
It takes *(client, messages)* as positional arguments (look at the section below for a detailed description).
|
||||
|
||||
filters (:obj:`Filters <pyrogram.Filters>`):
|
||||
filters (:obj:`Filters`):
|
||||
Pass one or more filters to allow only a subset of messages to be passed
|
||||
in your callback function.
|
||||
|
||||
Other parameters:
|
||||
client (:obj:`Client <pyrogram.Client>`):
|
||||
client (:obj:`Client`):
|
||||
The Client itself, useful when you want to call other API methods inside the message handler.
|
||||
|
||||
messages (:obj:`Messages <pyrogram.Messages>`):
|
||||
messages (:obj:`Messages`):
|
||||
The deleted messages.
|
||||
"""
|
||||
|
||||
|
||||
@ -26,13 +26,13 @@ class DisconnectHandler(Handler):
|
||||
For a nicer way to register this handler, have a look at the
|
||||
:meth:`on_disconnect() <pyrogram.Client.on_disconnect>` decorator.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
callback (``callable``):
|
||||
Pass a function that will be called when a disconnection occurs. It takes *(client)*
|
||||
as positional argument (look at the section below for a detailed description).
|
||||
|
||||
Other parameters:
|
||||
client (:obj:`Client <pyrogram.Client>`):
|
||||
client (:obj:`Client`):
|
||||
The Client itself. Useful, for example, when you want to change the proxy before a new connection
|
||||
is established.
|
||||
"""
|
||||
|
||||
@ -26,20 +26,20 @@ class InlineQueryHandler(Handler):
|
||||
For a nicer way to register this handler, have a look at the
|
||||
:meth:`on_inline_query() <pyrogram.Client.on_inline_query>` decorator.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
callback (``callable``):
|
||||
Pass a function that will be called when a new InlineQuery arrives. It takes *(client, inline_query)*
|
||||
as positional arguments (look at the section below for a detailed description).
|
||||
|
||||
filters (:obj:`Filters <pyrogram.Filters>`):
|
||||
filters (:obj:`Filters`):
|
||||
Pass one or more filters to allow only a subset of inline queries to be passed
|
||||
in your callback function.
|
||||
|
||||
Other parameters:
|
||||
client (:obj:`Client <pyrogram.Client>`):
|
||||
client (:obj:`Client`):
|
||||
The Client itself, useful when you want to call other API methods inside the inline query handler.
|
||||
|
||||
inline_query (:obj:`InlineQuery <pyrogram.InlineQuery>`):
|
||||
inline_query (:obj:`InlineQuery`):
|
||||
The received inline query.
|
||||
"""
|
||||
|
||||
|
||||
@ -27,20 +27,20 @@ class MessageHandler(Handler):
|
||||
For a nicer way to register this handler, have a look at the
|
||||
:meth:`on_message() <pyrogram.Client.on_message>` decorator.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
callback (``callable``):
|
||||
Pass a function that will be called when a new Message arrives. It takes *(client, message)*
|
||||
as positional arguments (look at the section below for a detailed description).
|
||||
|
||||
filters (:obj:`Filters <pyrogram.Filters>`):
|
||||
filters (:obj:`Filters`):
|
||||
Pass one or more filters to allow only a subset of messages to be passed
|
||||
in your callback function.
|
||||
|
||||
Other parameters:
|
||||
client (:obj:`Client <pyrogram.Client>`):
|
||||
client (:obj:`Client`):
|
||||
The Client itself, useful when you want to call other API methods inside the message handler.
|
||||
|
||||
message (:obj:`Message <pyrogram.Message>`):
|
||||
message (:obj:`Message`):
|
||||
The received message.
|
||||
"""
|
||||
|
||||
|
||||
@ -27,7 +27,7 @@ class PollHandler(Handler):
|
||||
For a nicer way to register this handler, have a look at the
|
||||
:meth:`on_poll() <pyrogram.Client.on_poll>` decorator.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
callback (``callable``):
|
||||
Pass a function that will be called when a new poll update arrives. It takes *(client, poll)*
|
||||
as positional arguments (look at the section below for a detailed description).
|
||||
|
||||
@ -26,14 +26,14 @@ class RawUpdateHandler(Handler):
|
||||
For a nicer way to register this handler, have a look at the
|
||||
:meth:`on_raw_update() <pyrogram.Client.on_raw_update>` decorator.
|
||||
|
||||
Args:
|
||||
Parameters:
|
||||
callback (``callable``):
|
||||
A function that will be called when a new update is received from the server. It takes
|
||||
*(client, update, users, chats)* as positional arguments (look at the section below for
|
||||
a detailed description).
|
||||
|
||||
Other Parameters:
|
||||
client (:class:`Client <pyrogram.Client>`):
|
||||
client (:class:`Client`):
|
||||
The Client itself, useful when you want to call other API methods inside the update handler.
|
||||
|
||||
update (``Update``):
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
x
Reference in New Issue
Block a user