README.rst
1.. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-logo-text_768.png?raw=true
2 :align: center
3 :target: https://python-telegram-bot.org
4 :alt: python-telegram-bot Logo
5
6We have made you a wrapper you can't refuse
7
8We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
9
10*Stay tuned for library updates and new releases on our* `Telegram Channel <https://telegram.me/pythontelegrambotchannel>`_.
11
12.. image:: https://img.shields.io/pypi/v/python-telegram-bot.svg
13 :target: https://pypi.org/project/python-telegram-bot/
14 :alt: PyPi Package Version
15
16.. image:: https://img.shields.io/pypi/pyversions/python-telegram-bot.svg
17 :target: https://pypi.org/project/python-telegram-bot/
18 :alt: Supported Python versions
19
20.. image:: https://cpu.re/static/python-telegram-bot/downloads.svg
21 :target: https://www.cpu.re/static/python-telegram-bot/downloads-by-python-version.txt
22 :alt: PyPi Package Monthly Download
23
24.. image:: https://img.shields.io/badge/docs-latest-af1a97.svg
25 :target: https://python-telegram-bot.readthedocs.io/
26 :alt: Documentation Status
27
28.. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg
29 :target: https://www.gnu.org/licenses/lgpl-3.0.html
30 :alt: LGPLv3 License
31
32.. image:: https://github.com/python-telegram-bot/python-telegram-bot/workflows/GitHub%20Actions/badge.svg?event=schedule
33 :target: https://github.com/python-telegram-bot/python-telegram-bot/
34 :alt: Github Actions workflow
35
36.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
37 :target: https://codecov.io/gh/python-telegram-bot/python-telegram-bot
38 :alt: Code coverage
39
40.. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
41 :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
42 :alt: Median time to resolve an issue
43
44.. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968
45 :target: https://www.codacy.com/app/python-telegram-bot/python-telegram-bot?utm_source=github.com&utm_medium=referral&utm_content=python-telegram-bot/python-telegram-bot&utm_campaign=Badge_Grade
46 :alt: Code quality
47
48.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
49 :target: https://github.com/psf/black
50
51.. image:: https://img.shields.io/badge/Telegram-Group-blue.svg
52 :target: https://telegram.me/pythontelegrambotgroup
53 :alt: Telegram Group
54
55.. image:: https://img.shields.io/badge/IRC-Channel-blue.svg
56 :target: https://webchat.freenode.net/?channels=##python-telegram-bot
57 :alt: IRC Bridge
58
59=================
60Table of contents
61=================
62
63- `Introduction`_
64
65- `Telegram API support`_
66
67- `Installing`_
68
69- `Getting started`_
70
71 #. `Learning by example`_
72
73 #. `Logging`_
74
75 #. `Documentation`_
76
77- `Getting help`_
78
79- `Contributing`_
80
81- `License`_
82
83============
84Introduction
85============
86
87This library provides a pure Python interface for the
88`Telegram Bot API <https://core.telegram.org/bots/api>`_.
89It's compatible with Python versions 3.6+. PTB might also work on `PyPy <http://pypy.org/>`_, though there have been a lot of issues before. Hence, PyPy is not officially supported.
90
91In addition to the pure API implementation, this library features a number of high-level classes to
92make the development of bots easy and straightforward. These classes are contained in the
93``telegram.ext`` submodule.
94
95====================
96Telegram API support
97====================
98
99All types and methods of the Telegram Bot API **4.8** are supported.
100
101==========
102Installing
103==========
104
105You can install or upgrade python-telegram-bot with:
106
107.. code:: shell
108
109 $ pip install python-telegram-bot --upgrade
110
111Or you can install from source with:
112
113.. code:: shell
114
115 $ git clone https://github.com/python-telegram-bot/python-telegram-bot --recursive
116 $ cd python-telegram-bot
117 $ python setup.py install
118
119In case you have a previously cloned local repository already, you should initialize the added urllib3 submodule before installing with:
120
121.. code:: shell
122
123 $ git submodule update --init --recursive
124
125===============
126Getting started
127===============
128
129Our Wiki contains a lot of resources to get you started with ``python-telegram-bot``:
130
131- `Introduction to the API <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Introduction-to-the-API>`_
132- Tutorial: `Your first Bot <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-Your-first-Bot>`_
133
134Other references:
135
136- `Telegram API documentation <https://core.telegram.org/bots/api>`_
137- `python-telegram-bot documentation <https://python-telegram-bot.readthedocs.io/>`_
138
139-------------------
140Learning by example
141-------------------
142
143We believe that the best way to learn this package is by example. Here
144are some examples for you to review. Even if it is not your approach for learning, please take a
145look at ``echobot.py``, it is the de facto base for most of the bots out there. Best of all,
146the code for these examples are released to the public domain, so you can start by grabbing the
147code and building on top of it.
148
149Visit `this page <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/README.md>`_ to discover the official examples or look at the examples on the `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Examples>`_ to see other bots the community has built.
150
151-------
152Logging
153-------
154
155This library uses the ``logging`` module. To set up logging to standard output, put:
156
157.. code:: python
158
159 import logging
160 logging.basicConfig(level=logging.DEBUG,
161 format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
162
163at the beginning of your script.
164
165You can also use logs in your application by calling ``logging.getLogger()`` and setting the log level you want:
166
167.. code:: python
168
169 logger = logging.getLogger()
170 logger.setLevel(logging.INFO)
171
172If you want DEBUG logs instead:
173
174.. code:: python
175
176 logger.setLevel(logging.DEBUG)
177
178
179=============
180Documentation
181=============
182
183``python-telegram-bot``'s documentation lives at `readthedocs.io <https://python-telegram-bot.readthedocs.io/>`_.
184
185============
186Getting help
187============
188
189You can get help in several ways:
190
1911. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
192
1932. In case you are unable to join our group due to Telegram restrictions, you can use our `IRC channel <https://webchat.freenode.net/?channels=##python-telegram-bot>`_.
194
1953. Report bugs, request new features or ask questions by `creating an issue <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_.
196
1974. Our `Wiki pages <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ offer a growing amount of resources.
198
1995. You can even ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.
200
201
202
203============
204Contributing
205============
206
207Contributions of all sizes are welcome. Please review our `contribution guidelines <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst>`_ to get started. You can also help by `reporting bugs <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
208
209=======
210License
211=======
212
213You may copy, distribute and modify the software provided that modifications are described and licensed for free under `LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html>`_. Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under LGPL-3, but applications that use the library don't have to be.
214
