Skip to content

Commit e4b0a78

Browse files
delivrancedelivrance
committed
Docs revamp. Part 2
1 parent 559eaa2 commit e4b0a78

33 files changed

+448
-316
lines changed

docs/source/pyrogram/index.rst renamed to docs/source/core/client.rst

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,7 @@ In this section you can find a detailed description of the Pyrogram package and
66
:class:`Client <pyrogram.Client>` is the main class. It exposes easy-to-use methods that are named
77
after the well established Telegram Bot API methods, thus offering a familiar look to Bot developers.
88

9-
.. toctree::
10-
:maxdepth: 1
11-
12-
types
13-
methods
14-
handlers
15-
decorators
16-
filters
17-
errors
18-
9+
Client
10+
------
1911

2012
.. autoclass:: pyrogram.Client()

docs/source/pyrogram/decorators.rst renamed to docs/source/core/decorators.rst

File renamed without changes.

docs/source/pyrogram/errors.rst renamed to docs/source/core/errors.rst

File renamed without changes.

docs/source/pyrogram/filters.rst renamed to docs/source/core/filters.rst

File renamed without changes.

docs/source/pyrogram/handlers.rst renamed to docs/source/core/handlers.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
Handlers
2-
========
1+
Update Handlers
2+
===============
33

44
Handlers are used to instruct Pyrogram about which kind of updates you'd like to handle with your callback functions.
55

docs/source/pyrogram/methods.rst renamed to docs/source/core/methods.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
Methods
2-
=======
1+
Available Methods
2+
=================
33

44
All Pyrogram methods listed here are bound to a :obj:`Client <pyrogram.Client>` instance.
55

docs/source/pyrogram/types.rst renamed to docs/source/core/types.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
Types
2-
=====
1+
Available Types
2+
===============
33

44
All Pyrogram types listed here are accessible through the main package directly.
55

‎docs/source/index.rst‎

Lines changed: 64 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,21 @@ Welcome to Pyrogram
1313
<b>Telegram MTProto API Framework for Python</b>
1414

1515
<br>
16-
<a href="https://docs.pyrogram.ml">
17-
Documentation
16+
<a href="https://github.com/pyrogram/pyrogram">
17+
GitHub
1818
</a>
19+
•
20+
<a href="https://t.me/PyrogramChat">
21+
Community
22+
</a>
23+
1924
•
2025
<a href="https://github.com/pyrogram/pyrogram/releases">
2126
Changelog
2227
</a>
2328
•
24-
<a href="https://t.me/PyrogramChat">
25-
Community
29+
<a href="https://pypi.org/project/Pyrogram">
30+
PyPI
2631
</a>
2732
<br>
2833
<a href="compiler/api/source/main_api.tl">
@@ -49,64 +54,69 @@ Welcome to Pyrogram
4954
5055
app.run()
5156
52-
Welcome to Pyrogram's Documentation! Here you can find resources for learning how to use the framework.
53-
Contents are organized into self-contained topics and can be accessed from the sidebar, or by following them in order
54-
using the Next button at the end of each page. But first, here's a brief overview of what is this all about.
55-
56-
About
57-
-----
58-
5957
**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and C.
6058
It enables you to easily create custom apps using both user and bot identities (bot API alternative) via the `MTProto API`_.
6159

62-
Features
63-
--------
60+
How the documentation is organized
61+
----------------------------------
62+
63+
Contents are organized into self-contained topics and can be accessed from the sidebar, or by following them in order
64+
using the Next button at the end of each page.
65+
66+
Relevant Pages
67+
^^^^^^^^^^^^^^
6468

65-
- **Easy**: You can install Pyrogram with pip and start building your applications right away.
66-
- **Elegant**: Low-level details are abstracted and re-presented in a much nicer and easier way.
67-
- **Fast**: Crypto parts are boosted up by TgCrypto_, a high-performance library written in pure C.
68-
- **Documented**: Pyrogram API methods, types and public interfaces are well documented.
69-
- **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted.
70-
- **Updated**, to the latest Telegram API version, currently Layer 97 on top of `MTProto 2.0`_.
71-
- **Pluggable**: The Smart Plugin system allows to write components with minimal boilerplate code.
72-
- **Comprehensive**: Execute any advanced action an official client is able to do, and even more.
69+
- `Quick Start`_ - Concise steps to get you started as fast as possible.
70+
- `API Usage`_ - Guide on how to use Pyrogram's API.
71+
- `Update Handling`_ - Guide on how to handle Telegram updates.
72+
- Client_ - Reference details about the Client class.
73+
- Types_ - All the available Pyrogram types.
74+
- Methods_ - All the available Pyrogram methods.
7375

74-
To get started, press the Next button.
76+
**To get started, press the Next button**
7577

7678
.. toctree::
7779
:hidden:
78-
:caption: Quick Start
80+
:caption: Introduction
7981

80-
start/installation
81-
start/setup
82-
start/usage
82+
intro/start
83+
intro/install
84+
intro/setup
85+
intro/auth
8386

8487
.. toctree::
8588
:hidden:
86-
:caption: Resources
87-
88-
resources/update-handling
89-
resources/using-filters
90-
resources/more-on-updates
91-
resources/configuration-file
92-
resources/smart-plugins
93-
resources/auto-authorization
94-
resources/customize-sessions
95-
resources/tgcrypto
96-
resources/text-formatting
97-
resources/socks5-proxy
98-
resources/bots-interaction
99-
resources/error-handling
100-
resources/test-servers
101-
resources/advanced-usage
102-
resources/voice-calls
103-
resources/changelog
89+
:caption: Topic Guides
90+
91+
topics/usage
92+
topics/update-handling
93+
topics/using-filters
94+
topics/more-on-updates
95+
topics/configuration-file
96+
topics/smart-plugins
97+
topics/auto-authorization
98+
topics/customize-sessions
99+
topics/tgcrypto
100+
topics/text-formatting
101+
topics/socks5-proxy
102+
topics/bots-interaction
103+
topics/error-handling
104+
topics/test-servers
105+
topics/advanced-usage
106+
topics/voice-calls
107+
topics/changelog
104108

105109
.. toctree::
106110
:hidden:
107-
:caption: Main Package
111+
:caption: API Reference
108112

109-
pyrogram/index
113+
core/client
114+
core/types
115+
core/methods
116+
core/handlers
117+
core/decorators
118+
core/filters
119+
core/errors
110120

111121
.. toctree::
112122
:hidden:
@@ -115,7 +125,12 @@ To get started, press the Next button.
115125
functions/index
116126
types/index
117127

118-
.. _`Telegram`: https://telegram.org
128+
.. _Telegram: https://telegram.org
119129
.. _TgCrypto: https://docs.pyrogram.ml/resources/TgCrypto
120-
.. _`MTProto API`: https://core.telegram.org/api#telegram-api
121-
.. _`MTProto 2.0`: https://core.telegram.org/mtproto
130+
.. _MTProto API: https://core.telegram.org/api#telegram-api
131+
.. _Quick Start: intro/start.html
132+
.. _API Usage: topics/usage.html
133+
.. _Update Handling: topics/update-handling.html
134+
.. _Client: core/client.html
135+
.. _Types: core/types.html
136+
.. _Methods: core/methods

‎docs/source/intro/auth.rst‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
Authorization
2+
=============
3+
4+
Once a `project is set up`_, you will still have to follow a few steps before you can actually use Pyrogram to make
5+
API calls. This section provides all the information you need in order to authorize yourself as user or a bot.
6+
7+
User Authorization
8+
------------------
9+
10+
In order to use the API, Telegram requires that users be authorized via their phone numbers.
11+
Pyrogram automatically manages this access, all you need to do is create an instance of the
12+
:class:`Client <pyrogram.Client>` class by passing to it a ``session_name`` of your choice (e.g.: "my_account") and call
13+
the :meth:`run() <pyrogram.Client.run>` method:
14+
15+
.. code-block:: python
16+
17+
from pyrogram import Client
18+
19+
app = Client("my_account")
20+
app.run()
21+
22+
This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_) and the
23+
**phone code** you will receive in your devices that are already authorized or via SMS:
24+
25+
.. code-block:: text
26+
27+
Enter phone number: +39**********
28+
Is "+39**********" correct? (y/n): y
29+
Enter phone code: 32768
30+
Logged in successfully as Dan
31+
32+
After successfully authorizing yourself, a new file called ``my_account.session`` will be created allowing Pyrogram to
33+
execute API calls with your identity. This file will be loaded again when you restart your app, and as long as you
34+
keep the session alive, Pyrogram won't ask you again to enter your phone number.
35+
36+
.. important::
37+
38+
Your ``*.session`` files are personal and must be kept secret.
39+
40+
.. note::
41+
42+
The code above does nothing except asking for credentials and keeping the client online, hit ``CTRL+C`` now to stop
43+
your application and keep reading.
44+
45+
Bot Authorization
46+
-----------------
47+
48+
Bots are a special kind of users that are authorized via their tokens (instead of phone numbers), which are created by
49+
the `Bot Father`_. Bot tokens replace the users' phone numbers only — you still need to
50+
`configure a Telegram API key <setup.html#configuration>`_ with Pyrogram, even when using bots.
51+
52+
The authorization process is automatically managed. All you need to do is choose a ``session_name`` (can be anything,
53+
usually your bot username) and pass your bot token using the ``bot_token`` parameter. The session file will be named
54+
after the session name, which will be ``pyrogrambot.session`` for the example below.
55+
56+
.. code-block:: python
57+
58+
from pyrogram import Client
59+
60+
app = Client(
61+
"my_bot",
62+
bot_token="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
63+
)
64+
app.run()
65+
66+
.. _project is set up: setup.html
67+
.. _Country Code: https://en.wikipedia.org/wiki/List_of_country_calling_codes
68+
.. _Bot Father: https://t.me/botfather

docs/source/start/installation.rst renamed to docs/source/intro/install.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
Installation
2-
============
1+
Install Guide
2+
=============
33

44
Being a Python library, **Pyrogram** requires Python to be installed in your system.
5-
We recommend using the latest version of Python 3 and pip.
5+
We recommend using the latest versions of both Python 3 and pip.
66

77
- Get **Python 3** from https://www.python.org/downloads/ (or with your package manager)
88
- Get **pip** by following the instructions at https://pip.pypa.io/en/latest/installing/.
@@ -88,5 +88,5 @@ If no error shows up you are good to go.
8888
>>> pyrogram.__version__
8989
'0.12.0'
9090
91-
.. _TgCrypto: https://docs.pyrogram.ml/resources/TgCrypto
91+
.. _TgCrypto: ../resources/tgcrypto.html
9292
.. _`Github repo`: http://github.com/pyrogram/pyrogram

0 commit comments

Comments
 (0)