Xtao-Labs/MTPyroger
3
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge branch 'readme'

Browse Source
This commit is contained in:
Dan 2017-12-12 08:59:28 +01:00
commit 3e8d452a3d
3 changed files with 330 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

325
README.rst
View File

@ -1,2 +1,323 @@
Pyrogram |header|
########
Table of Contents
=================
- `Overview`_
- `Requirements`_
- `API Keys`_
- `Installation`_
- `Getting Started`_
- `Setup`_
- `Authorization`_
- `Usage`_
- `Simple API Access`_
- `Using Raw Functions`_
- `Development`_
- `Documentation`_
- `Contribution`_
- `Feedback`_
- `Copyright & License`_
Overview
========
**Pyrogram** is a Client Library written from the ground up in Python, designed
for Python application developers. It offers simple and complete access to the
`Telegram Messenger API`_. Pyrogram:
- Provides idiomatic, developer-friendly Python code (either generated or
hand-written) making the Telegram API simple to use.
- Handles all the low-level details of communication with the Telegram servers
by implementing the `MTProto Mobile Protocol v2.0`_.
- Makes use of the latest Telegram API version (`Layer 73`_).
- Can be easily installed and upgraded using ``pip``.
- Requires a minimal set of dependencies.
Requirements
============
- Operating systems:
- Linux
- macOS
- Windows
- Python 3.3 or higher.
- A Telegram API key.
API Keys
--------
To obtain an API key:
#. 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 Telegram API key consists of two parts: the **App api_id** and
the **App api_hash**.
**Important:** This key should be kept secret.
Installation
============
You can install and upgrade the library using standard Python tools:
.. code:: shell
$ pip install --upgrade pyrogram
Getting Started
===============
This section provides all the information you need to start using Pyrogram.
There are a couple of steps you have to follow before you can use the library
to make API calls.
Setup
-----
Create a new ``config.ini`` file at the root of your working directory, paste
the following and replace the **api_id** and **api_hash** values
with `your own`_:
.. code:: ini
[pyrogram]
api_id = 12345
api_hash = 0123456789abcdef0123456789abcdef
Authorization
-------------
Telegram requires that users be authorized in order to use the API.
Pyrogram automatically manages this access, all you need to do is create an
instance of the ``pyrogram.Client`` class and call the ``start`` method:
.. code:: python
from pyrogram import Client
client = Client(session_name="example")
client.start()
This starts an interactive shell asking you to input your **phone number**
(including your `Country Code`_) and the **phone code** you will receive:
.. code::
Enter phone number: +39**********
Is "+39**********" correct? (y/n): y
Enter phone code: 32768
After successfully authorizing yourself, a new file called ``example.session``
will be created allowing Pyrogram executing API calls with your identity.
**Important**: The ``*.session`` file must be kept secret.
Usage
=====
Having `your session`_ created you can now start playing with the API.
Simple API Access
-----------------
The easiest way to interact with the API is via the ``pyrogram.Client`` class
which exposes `bot-like`_ methods. The purpose of this Client class is to make
it **even simpler** to work with Telegram's API by abstracting the raw functions
listed in the API scheme.
The result is a much cleaner interface that allows you to:
- Get information about the authorized user:
.. code:: python
print(client.get_me())
- Send a message to yourself (Saved Messages):
.. code:: python
client.send_message(chat_id="me", text="Hi there! I'm using Pyrogram")
Using Raw Functions
-------------------
If you want **complete**, low-level access to the Telegram API you have to use
the raw ``functions`` and ``types`` exposed by the ``pyrogram.api`` package and
call any Telegram API method you wish using the ``send`` method provided by the
Client class:
- Update first name, last name and bio:
.. code:: python
from pyrogram.api import functions
client.send(
functions.account.UpdateProfile(
first_name="Dan", last_name="Tès",
about="Bio written from Pyrogram"
)
)
- Share your Last Seen time only with your contacts:
.. code:: python
from pyrogram.api import functions, types
client.send(
functions.account.SetPrivacy(
key=types.InputPrivacyKeyStatusTimestamp(),
rules=[types.InputPrivacyValueAllowContacts()]
)
)
Development
===========
The library is still in its early stages, thus lots of functionalities aiming to
make working with Telegram's API easy are yet to be added.
However, being the core functionalities already implemented, every Telegram API
method listed in the API scheme can be used right away; the goal is therefore to
build a powerful, simple to use, `bot-like`_ interface on top of those low-level
functions.
Documentation
=============
Soon. For now, have a look at the ``pyrogram.Client`` code to get some insights.
Currently you are able to easily:
- ``send_message``
- ``forward_messages``
- ``edit_message_text``
- ``delete_messages``
- ``send_chat_action``
- Some more...
as well as listening for updates and catching API errors.
Contribution
============
**You are very welcome to contribute** 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!
Feedback
========
Means for getting in touch:
- `Telegram`_
- `Github`_
- `Email`_
Copyright & License
===================
- Copyright (C) 2017 Dan Tès <https://github.com/delivrance>
- Licensed under the terms of the
`GNU Lesser General Public License v3 or later (LGPLv3+)`_
.. _`Telegram Messenger API`: https://core.telegram.org/api#telegram-api
.. _`MTProto Mobile Protocol v2.0`: https://core.telegram.org/mtproto
.. _`Layer 73`: compiler/api/source/main_api.tl
.. _`your own`: `API Keys`_
.. _`Country Code`: https://en.wikipedia.org/wiki/List_of_country_calling_codes
.. _`your session`: `Authorization`_
.. _`bot-like`: https://core.telegram.org/bots/api#available-methods
.. _`Telegram`: https://t.me/haskell
.. _`Github`: https://github.com/pyrogram/pyrogram/issues
.. _`Email`: admin@pyrogram.ml
.. _`GNU Lesser General Public License v3 or later (LGPLv3+)`: COPYING.lesser
.. |header| raw:: html
<h1 align="center">
<a href="https://github.com">
<img src="https://www.pyrogram.ml/images/logo.png" alt="Pyrogram">
</a>
</h1>
<p align="center">
<b>Telegram MTProto API Client Library for Python</b>
<br><br>
<a href="https://github.com">
<img src="https://img.shields.io/badge/scheme-layer%2073-eda738.svg?style=for-the-badge&colorA=262b30"
alt="Scheme Layer 73">
</a>
<a href="https://github.com">
<img src="https://img.shields.io/badge/mtproto-v2.0-eda738.svg?style=for-the-badge&colorA=262b30"
alt="MTProto v2.0">
</a>
</p>
.. |logo| image:: https://www.pyrogram.ml/images/logo.png
:target: https://github.com
:alt: Pyrogram
.. |description| replace:: **Telegram MTProto API Client Library for Python**
.. |scheme| image:: https://img.shields.io/badge/scheme-layer%2073-eda738.svg?style=for-the-badge&colorA=262b30
:target: https://github.com
:alt: Scheme Layer 73
.. |mtproto| image:: https://img.shields.io/badge/mtproto-v2.0-eda738.svg?style=for-the-badge&colorA=262b30
:target: https://github.com
:alt: MTProto v2.0

1
setup.cfg
View File

@ -2,7 +2,6 @@
name = Pyrogram name = Pyrogram
version = attr: pyrogram.__version__ version = attr: pyrogram.__version__
description = Telegram MTProto API Client Library for Python description = Telegram MTProto API Client Library for Python
long_description = file: README.rst
url = https://github.com/pyrogram/pyrogram url = https://github.com/pyrogram/pyrogram
author = Dan Tès author = Dan Tès
author_email = admin@pyrogram.ml author_email = admin@pyrogram.ml

8
setup.py
View File

@ -16,6 +16,7 @@
# You should have received a copy of the GNU Lesser General Public License # You should have received a copy of the GNU Lesser General Public License
# along with Pyrogram. If not, see <http://www.gnu.org/licenses/>. # along with Pyrogram. If not, see <http://www.gnu.org/licenses/>.
import re
from sys import argv from sys import argv
from setuptools import setup from setuptools import setup
@ -27,4 +28,9 @@ if len(argv) > 1 and argv[1] != "sdist":
api_compiler.start() api_compiler.start()
error_compiler.start() error_compiler.start()
setup() # PyPI doesn't like raw html
with open("README.rst", encoding="UTF-8") as f:
readme = re.sub(r"\.\. \|.+\| raw:: html(?:\s{4}.+)+\n\n", "", f.read())
readme = re.sub(r"\|header\|", "|logo|\n######\n\n|description|\n\n|scheme| |mtproto|", readme)
setup(long_description=readme)