|
| 1 | +.. |
| 2 | + Make user to apply any changes to this file to README.rst as well! |
| 3 | +
|
| 4 | +.. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-raw-logo-text_768.png?raw=true |
| 5 | + :align: center |
| 6 | + :target: https://python-telegram-bot.org |
| 7 | + :alt: python-telegram-bot-raw Logo |
| 8 | + |
| 9 | +We have made you a wrapper you can't refuse |
| 10 | + |
| 11 | +We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us! |
| 12 | + |
| 13 | +*Stay tuned for library updates and new releases on our* `Telegram Channel <https://telegram.me/pythontelegrambotchannel>`_. |
| 14 | + |
| 15 | +.. image:: https://img.shields.io/pypi/v/python-telegram-bot-raw.svg |
| 16 | + :target: https://pypi.org/project/python-telegram-bot/ |
| 17 | + :alt: PyPi Package Version |
| 18 | + |
| 19 | +.. image:: https://img.shields.io/pypi/pyversions/python-telegram-bot-raw.svg |
| 20 | + :target: https://pypi.org/project/python-telegram-bot/ |
| 21 | + :alt: Supported Python versions |
| 22 | + |
| 23 | +.. image:: https://img.shields.io/badge/Bot%20API-5.0-blue?logo=telegram |
| 24 | + :target: https://core.telegram.org/bots/api-changelog |
| 25 | + :alt: Supported Bot API versions |
| 26 | + |
| 27 | +.. image:: https://img.shields.io/pypi/dm/python-telegram-bot-raw |
| 28 | + :target: https://pypistats.org/packages/python-telegram-bot |
| 29 | + :alt: PyPi Package Monthly Download |
| 30 | + |
| 31 | +.. image:: https://img.shields.io/badge/docs-latest-af1a97.svg |
| 32 | + :target: https://python-telegram-bot.readthedocs.io/ |
| 33 | + :alt: Documentation Status |
| 34 | + |
| 35 | +.. image:: https://img.shields.io/pypi/l/python-telegram-bot-raw.svg |
| 36 | + :target: https://www.gnu.org/licenses/lgpl-3.0.html |
| 37 | + :alt: LGPLv3 License |
| 38 | + |
| 39 | +.. image:: https://github.com/python-telegram-bot/python-telegram-bot/workflows/GitHub%20Actions/badge.svg |
| 40 | + :target: https://github.com/python-telegram-bot/python-telegram-bot/ |
| 41 | + :alt: Github Actions workflow |
| 42 | + |
| 43 | +.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg |
| 44 | + :target: https://codecov.io/gh/python-telegram-bot/python-telegram-bot |
| 45 | + :alt: Code coverage |
| 46 | + |
| 47 | +.. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg |
| 48 | + :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot |
| 49 | + :alt: Median time to resolve an issue |
| 50 | + |
| 51 | +.. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968 |
| 52 | + :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 |
| 53 | + :alt: Code quality |
| 54 | + |
| 55 | +.. image:: https://img.shields.io/badge/code%20style-black-000000.svg |
| 56 | + :target: https://github.com/psf/black |
| 57 | + |
| 58 | +.. image:: https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram |
| 59 | + :target: https://telegram.me/pythontelegrambotgroup |
| 60 | + :alt: Telegram Group |
| 61 | + |
| 62 | +.. image:: https://img.shields.io/badge/IRC-Channel-blue.svg |
| 63 | + :target: https://webchat.freenode.net/?channels=##python-telegram-bot |
| 64 | + :alt: IRC Bridge |
| 65 | + |
| 66 | +================= |
| 67 | +Table of contents |
| 68 | +================= |
| 69 | + |
| 70 | +- `Introduction`_ |
| 71 | + |
| 72 | +- `Telegram API support`_ |
| 73 | + |
| 74 | +- `Installing`_ |
| 75 | + |
| 76 | +- `Getting started`_ |
| 77 | + |
| 78 | + #. `Logging`_ |
| 79 | + |
| 80 | + #. `Documentation`_ |
| 81 | + |
| 82 | +- `Getting help`_ |
| 83 | + |
| 84 | +- `Contributing`_ |
| 85 | + |
| 86 | +- `License`_ |
| 87 | + |
| 88 | +============ |
| 89 | +Introduction |
| 90 | +============ |
| 91 | + |
| 92 | +This library provides a pure Python, lightweight interface for the |
| 93 | +`Telegram Bot API <https://core.telegram.org/bots/api>`_. |
| 94 | +It's compatible with Python versions 3.6+. PTB-Raw might also work on `PyPy <http://pypy.org/>`_, though there have been a lot of issues before. Hence, PyPy is not officially supported. |
| 95 | + |
| 96 | +``python-telegram-bot-raw`` is part of the `python-telegram-bot <https://python-telegram-bot.org>`_ ecosystem and provides the pure API functionality extracted from PTB. It therefore does *not* have independent release schedules, changelogs or documentation. Please consult the PTB resources. |
| 97 | + |
| 98 | +---- |
| 99 | +Note |
| 100 | +---- |
| 101 | + |
| 102 | +Installing both ``python-telegram-bot`` and ``python-telegram-bot-raw`` in conjunction will result in undesired side-effects, so only install *one* of both. |
| 103 | + |
| 104 | +==================== |
| 105 | +Telegram API support |
| 106 | +==================== |
| 107 | + |
| 108 | +All types and methods of the Telegram Bot API **5.0** are supported. |
| 109 | + |
| 110 | +========== |
| 111 | +Installing |
| 112 | +========== |
| 113 | + |
| 114 | +You can install or upgrade python-telegram-bot-raw with: |
| 115 | + |
| 116 | +.. code:: shell |
| 117 | +
|
| 118 | + $ pip install python-telegram-bot-raw --upgrade |
| 119 | +
|
| 120 | +Or you can install from source with: |
| 121 | + |
| 122 | +.. code:: shell |
| 123 | +
|
| 124 | + $ git clone https://github.com/python-telegram-bot/python-telegram-bot --recursive |
| 125 | + $ cd python-telegram-bot |
| 126 | + $ python setup-raw.py install |
| 127 | +
|
| 128 | +In case you have a previously cloned local repository already, you should initialize the added urllib3 submodule before installing with: |
| 129 | + |
| 130 | +.. code:: shell |
| 131 | +
|
| 132 | + $ git submodule update --init --recursive |
| 133 | +
|
| 134 | +---- |
| 135 | +Note |
| 136 | +---- |
| 137 | + |
| 138 | +Installing the `.tar.gz` archive available on PyPi directly via `pip` will *not* work as expected, as `pip` does not recognize that it should use `setup-raw.py` instead of `setup.py`. |
| 139 | + |
| 140 | +=============== |
| 141 | +Getting started |
| 142 | +=============== |
| 143 | + |
| 144 | +Our Wiki contains an `Introduction to the API <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Introduction-to-the-API>`_. Other references are: |
| 145 | + |
| 146 | +- the `Telegram API documentation <https://core.telegram.org/bots/api>`_ |
| 147 | +- the `python-telegram-bot documentation <https://python-telegram-bot.readthedocs.io/>`_ |
| 148 | + |
| 149 | +------- |
| 150 | +Logging |
| 151 | +------- |
| 152 | + |
| 153 | +This library uses the ``logging`` module. To set up logging to standard output, put: |
| 154 | + |
| 155 | +.. code:: python |
| 156 | +
|
| 157 | + import logging |
| 158 | + logging.basicConfig(level=logging.DEBUG, |
| 159 | + format='%(asctime)s - %(name)s - %(levelname)s - %(message)s') |
| 160 | +
|
| 161 | +at the beginning of your script. |
| 162 | + |
| 163 | +You can also use logs in your application by calling ``logging.getLogger()`` and setting the log level you want: |
| 164 | + |
| 165 | +.. code:: python |
| 166 | +
|
| 167 | + logger = logging.getLogger() |
| 168 | + logger.setLevel(logging.INFO) |
| 169 | +
|
| 170 | +If you want DEBUG logs instead: |
| 171 | + |
| 172 | +.. code:: python |
| 173 | +
|
| 174 | + logger.setLevel(logging.DEBUG) |
| 175 | +
|
| 176 | +
|
| 177 | +============= |
| 178 | +Documentation |
| 179 | +============= |
| 180 | + |
| 181 | +``python-telegram-bot``'s documentation lives at `readthedocs.io <https://python-telegram-bot.readthedocs.io/>`_, which |
| 182 | +includes the relevant documentation for ``python-telegram-bot-raw``. |
| 183 | + |
| 184 | +============ |
| 185 | +Getting help |
| 186 | +============ |
| 187 | + |
| 188 | +You can get help in several ways: |
| 189 | + |
| 190 | +1. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us! |
| 191 | + |
| 192 | +2. 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>`_. |
| 193 | + |
| 194 | +3. Report bugs, request new features or ask questions by `creating an issue <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_ or `a discussion <https://github.com/python-telegram-bot/python-telegram-bot/discussions/new>`_. |
| 195 | + |
| 196 | +4. Our `Wiki pages <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ offer a growing amount of resources. |
| 197 | + |
| 198 | +5. You can even ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_. |
| 199 | + |
| 200 | +============ |
| 201 | +Contributing |
| 202 | +============ |
| 203 | + |
| 204 | +Contributions 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>`_. |
| 205 | + |
| 206 | +======= |
| 207 | +License |
| 208 | +======= |
| 209 | + |
| 210 | +You 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. |
0 commit comments