OpenSource/python-telegram-bot
OpenSource/python-telegram-bot
1
0
Fork 0
mirror of https://github.com/python-telegram-bot/python-telegram-bot.git synced 2024-12-12 09:50:41 +01:00
Code Issues Projects Releases Packages Wiki Activity

update builder pattern page

Hinrich Mahler 2022-04-18 10:33:17 +02:00
parent 9088079a02
commit d08e784825
1 changed files with 27 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
Builder-Pattern.md

@ -1,70 +1,67 @@
# The Builder Pattern in `telegram.ext`
In this library, there are roughly four different components that make up everything:
In this library, there are roughly four important components that make up everything:
1. The `Updater` is responsible for fetching updates that Telegram sent to your bot
2. The `Dispatcher` is responsible for handling those updates by passing them to the different handlers
3. The `Bot` provides high-level access to the methods of the Bot API
4. The `BaseRequest` is responsible to handle the actual networking stuff, i.e. sending the requests to the Bot API
2. The `Bot` provides high-level access to the methods of the Bot API
3. The `BaseRequest` is responsible to handle the actual networking stuff, i.e. sending the requests to the Bot API
4. The `Application` binds everything together and is responsible for handling the updates fetched by the `Updater`.
All of those have different parameters. Some of them are optional. Some are required. Some are mutually exclusive.
That's a lot to take in and when coding your bot, setting this all up by yourself would be tiresome.
In addition to those four, there are several other components, which are not as significant for the structure of a `python-telegram-bot` program.
All of those components have different parameters. Some of them are optional. Some are required. Some are mutually exclusive.
That's a lot to take in and when coding your bot and setting this all up by yourself would be tiresome.
That's why `python-telegram-bot` makes an effort to make the setup easy with reasonable defaults. E.g. with
```python
from telegram.ext import Updater
updater = Updater.builder().token('TOKEN').build()
from telegram.ext import Application
application = Application.builder().token('TOKEN').build()
```
`python-telegram-bot` you will automatically have
* the `Dispatcher` available as `updater.dispatcher`
* the `Bot` available as `updater/dispatcher.bot`
* the `BaseRequest` available as `updater/dispatcher.bot.request`
* the `Updater` available as `application.dispatcher`
* the `Bot` available as `application.(updater.)bot`
* a `BaseRequest` object initialized and ready to be used by the `application.bot`
* several other components & sane default values set up.
So what if you want to customize some attributes that `Updater`, `Dispatcher`, `Bot` or `BaseRequest` accept? Do you have to build all those objects yourself and glue them together? No! Well, you can, but you don't have to.
But what if you want to customize some arguments that `Application`, `Updater`, `Bot`, `BaseRequest` or other components accept? Do you have to build all those objects yourself and glue them together? No! (Well, you can, but you don't have to.)
This is, where the [builder patter](https://en.wikipedia.org/wiki/Builder_pattern) comes into play. The idea is roughly as follows: You went shopping and have all the ingredients for a nice stew, but you don't want to cook yourself. So you hand everything to a chef. The chef will tell you that some of your ingredients don't match and will discard them. But then, he'll cook a nice stew for you and you never need to worry about how exactly that's done.
This is, where the [builder patter](https://en.wikipedia.org/wiki/Builder_pattern) comes into play. The idea is roughly as follows: You went shopping and have all the ingredients for a nice stew, but you don't want to cook yourself. So you hand everything to a chef. The chef will tell you that some of your ingredients don't match and will discard them. Afterwards, he'll cook a nice stew for you and you never need to worry about how exactly that's done.
Let's get a bit more technical. First, we need the cook:
```python
from telegram.ext import Updater
builder = Updater.builder()
from telegram.ext import Application
builder = Application.builder()
```
Now, we hand over the ingredients:
```python
builder.token(token) # the bot token is the main ingredient
builder.context_types(context_types) # In case you want to use custom context types for your `Dispatcher`
builder.request_kwargs(request_kwargs) # In case you want to fine tune the networking backend
builder.context_types(context_types) # In case you want to use custom context types for your `Application`
builder.read_timeout(read_timeout) # In case you want to fine tune the networking backend
...
```
Finally, we have the chef cook the stew:
```python
updater = builder.build()
application = builder.build()
```
All this can also be chained into a single line:
```python
from telegram.ext import Updater
updater = Updater.builder().token(token).context_types(context_types).request_kwargs(request_kwargs).build()
from telegram.ext import Application
application = Application.builder().token(token).context_types(context_types).read_timeout(read_timeout).build()
```
And that's already it! A similar pattern can also be used in case you just need the `Dispatcher` (e.g. if you have a custom webhook setup and don't need the `Updater`). In that case, you'll just do something like
And that's already it!
```python
from telegram.ext import Dispatcher
dispatcher = Dispatcher.builder().token(token)….build()
```
The docs of [`ApplicationBuilder`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.ext.applicationbuilder.html) have all the info about which "ingredients" it can handle, i.e. which methods it has. Each method will tell you
The docs of [`UpdaterBuilder`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.ext.updaterbuilder.html) and [`DispatcherBuilder`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.ext.dispatcherbuilder.html) have all the info about which "ingredients" they can handle, i.e. which methods they have. Each method will tell you
* how the parameters will be used (e.g. the token passed to `UpdaterBuilder.token` will be used for the `Bot` available as `Updater.bot`)
* What happens if you don't call this method. For many things, PTB will use reasonable defaults.
* how the parameters will be used (e.g. the token passed to `ApplicationBuilder.token` will be used for the `Bot` available as `Application.bot`)
* What happens if you don't call this method. For most things, PTB will use reasonable defaults.