Skip to content

Commit cd7bc8d

Browse files
committed
Update README to telegram.ext, move API section up
1 parent 150914c commit cd7bc8d

File tree

1 file changed

+78
-78
lines changed

1 file changed

+78
-78
lines changed

README.rst

Lines changed: 78 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,9 @@ Table of contents
5757

5858
- `Getting started`_
5959

60-
1. `The Updater class`_
60+
1. `API`_
6161

62-
2. `API`_
62+
2. `telegram.ext`_
6363

6464
3. `JobQueue`_
6565

@@ -174,85 +174,11 @@ This library uses the `logging` module. To set up logging to standard output, pu
174174

175175
at the beginning of your script.
176176

177-
--------------------
178-
_`The Updater class`
179-
--------------------
180-
181-
The ``Updater`` class is the new way to create bots with ``python-telegram-bot``. It provides an easy-to-use interface to the ``telegram.Bot`` by caring about getting new updates from telegram and forwarding them to the ``Dispatcher`` class. We can register handler functions in the ``Dispatcher`` to make our bot react to Telegram commands, messages and even arbitrary updates.
182-
183-
As with the old method, we'll need an Access Token. To generate an Access Token, we have to talk to `BotFather <https://telegram.me/botfather>`_ and follow a few simple steps (described `here <https://core.telegram.org/bots#botfather>`_).
184-
185-
First, we create an ``Updater`` object::
186-
187-
>>> from telegram import Updater
188-
>>> updater = Updater(token='token')
189-
190-
For quicker access to the ``Dispatcher`` used by our ``Updater``, we can introduce it locally::
191-
192-
>>> dispatcher = updater.dispatcher
193-
194-
Now, we need to define a function that should process a specific type of update::
195-
196-
>>> def start(bot, update):
197-
... bot.sendMessage(chat_id=update.message.chat_id, text="I'm a bot, please talk to me!")
198-
199-
We want this function to be called on a Telegram message that contains the ``/start`` command, so we need to register it in the dispatcher::
200-
201-
>>> dispatcher.addTelegramCommandHandler('start', start)
202-
203-
The last step is to tell the ``Updater`` to start working::
204-
205-
>>> updater.start_polling()
206-
207-
Our bot is now up and running (go ahead and try it)! It's not doing anything yet, besides answering to the ``/start`` command. Let's add another handler function and register it::
208-
209-
>>> def echo(bot, update):
210-
... bot.sendMessage(chat_id=update.message.chat_id, text=update.message.text)
211-
...
212-
>>> dispatcher.addTelegramMessageHandler(echo)
213-
214-
Our bot should now reply to all messages that are not a command with a message that has the same content.
215-
216-
People might try to send commands to the bot that it doesn't understand, so we should get that covered as well::
217-
218-
>>> def unknown(bot, update):
219-
... bot.sendMessage(chat_id=update.message.chat_id, text="Sorry, I didn't understand that command.")
220-
...
221-
>>> dispatcher.addUnknownTelegramCommandHandler(unknown)
222-
223-
Let's add some functionality to our bot. We want to add the ``/caps`` command, that will take some text as parameter and return it in all caps. We can get the arguments that were passed to the command in the handler function simply by adding it to the parameter list::
224-
225-
>>> def caps(bot, update, args):
226-
... text_caps = ' '.join(args).upper()
227-
... bot.sendMessage(chat_id=update.message.chat_id, text=text_caps)
228-
...
229-
>>> dispatcher.addTelegramCommandHandler('caps', caps)
230-
231-
To enable our bot to respond to inline queries, we can add the following (you will also have to talk to BotFather)::
232-
233-
>>> from telegram import InlineQueryResultArticle
234-
>>> def inline_caps(bot, update):
235-
... # If you activated inline feedback, updates might either contain
236-
... # inline_query or chosen_inline_result, the other one will be None
237-
... if update.inline_query:
238-
... query = bot.update.inline_query.query
239-
... results = list()
240-
... results.append(InlineQueryResultArticle(query.upper(), 'Caps', text_caps))
241-
... bot.answerInlineQuery(update.inline_query.id, results)
242-
...
243-
>>> dispatcher.addTelegramInlineHandler(inline_caps)
244-
245-
Now it's time to stop the bot::
246-
247-
>>> updater.stop()
248-
249-
Check out more examples in the `examples folder <https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples>`_!
250-
251177
------
252178
_`API`
253179
------
254180

255-
Note: Using the ``Bot`` class directly is the 'old' method, but some of this is still important information, even if you're using the ``Updater`` class!
181+
Note: Using the ``Bot`` class directly is the 'old' method, but almost all of this is still important information, even if you're using the ``telegram.ext`` submodule!
256182

257183
The API is exposed via the ``telegram.Bot`` class.
258184

@@ -339,13 +265,87 @@ There are many more API methods, to read the full API documentation::
339265

340266
$ pydoc telegram.Bot
341267

268+
---------------
269+
_`telegram.ext`
270+
---------------
271+
272+
The ``telegram.ext`` submodule is built on top of the bare-metal API. It provides an easy-to-use interface to the ``telegram.Bot`` by caring about getting new updates with the ``Updater`` class from telegram and forwarding them to the ``Dispatcher`` class. We can register handler functions in the ``Dispatcher`` to make our bot react to Telegram commands, messages and even arbitrary updates.
273+
274+
We'll need an Access Token. __Note:__ If you have done this in the previous step, you can use that one. To generate an Access Token, we have to talk to `BotFather <https://telegram.me/botfather>`_ and follow a few simple steps (described `here <https://core.telegram.org/bots#botfather>`_).
275+
276+
First, we create an ``Updater`` object::
277+
278+
>>> from telegram.ext import Updater
279+
>>> updater = Updater(token='token')
280+
281+
For quicker access to the ``Dispatcher`` used by our ``Updater``, we can introduce it locally::
282+
283+
>>> dispatcher = updater.dispatcher
284+
285+
Now, we need to define a function that should process a specific type of update::
286+
287+
>>> def start(bot, update):
288+
... bot.sendMessage(chat_id=update.message.chat_id, text="I'm a bot, please talk to me!")
289+
290+
We want this function to be called on a Telegram message that contains the ``/start`` command, so we need to register it in the dispatcher::
291+
292+
>>> dispatcher.addTelegramCommandHandler('start', start)
293+
294+
The last step is to tell the ``Updater`` to start working::
295+
296+
>>> updater.start_polling()
297+
298+
Our bot is now up and running (go ahead and try it)! It's not doing anything yet, besides answering to the ``/start`` command. Let's add another handler function and register it::
299+
300+
>>> def echo(bot, update):
301+
... bot.sendMessage(chat_id=update.message.chat_id, text=update.message.text)
302+
...
303+
>>> dispatcher.addTelegramMessageHandler(echo)
304+
305+
Our bot should now reply to all messages that are not a command with a message that has the same content.
306+
307+
People might try to send commands to the bot that it doesn't understand, so we should get that covered as well::
308+
309+
>>> def unknown(bot, update):
310+
... bot.sendMessage(chat_id=update.message.chat_id, text="Sorry, I didn't understand that command.")
311+
...
312+
>>> dispatcher.addUnknownTelegramCommandHandler(unknown)
313+
314+
Let's add some functionality to our bot. We want to add the ``/caps`` command, that will take some text as parameter and return it in all caps. We can get the arguments that were passed to the command in the handler function simply by adding it to the parameter list::
315+
316+
>>> def caps(bot, update, args):
317+
... text_caps = ' '.join(args).upper()
318+
... bot.sendMessage(chat_id=update.message.chat_id, text=text_caps)
319+
...
320+
>>> dispatcher.addTelegramCommandHandler('caps', caps)
321+
322+
To enable our bot to respond to inline queries, we can add the following (you will also have to talk to BotFather)::
323+
324+
>>> from telegram import InlineQueryResultArticle
325+
>>> def inline_caps(bot, update):
326+
... # If you activated inline feedback, updates might either contain
327+
... # inline_query or chosen_inline_result, the other one will be None
328+
... if update.inline_query:
329+
... query = bot.update.inline_query.query
330+
... results = list()
331+
... results.append(InlineQueryResultArticle(query.upper(), 'Caps', text_caps))
332+
... bot.answerInlineQuery(update.inline_query.id, results)
333+
...
334+
>>> dispatcher.addTelegramInlineHandler(inline_caps)
335+
336+
Now it's time to stop the bot::
337+
338+
>>> updater.stop()
339+
340+
Check out more examples in the `examples folder <https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples>`_!
341+
342342
-----------
343343
_`JobQueue`
344344
-----------
345345

346346
The ``JobQueue`` allows you to perform tasks with a delay or even periodically. The ``Updater`` will create one for you::
347347

348-
>>> from telegram import Updater
348+
>>> from telegram.ext import Updater
349349
>>> u = Updater('TOKEN')
350350
>>> j = u.job_queue
351351

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy