-
Notifications
You must be signed in to change notification settings - Fork 6k
Description
What kind of feature are you missing? Where do you notice a shortcoming of PTB?
We currently provide no way for users to use new API endpoints through PTB before we add the in the next release. With api_kwargs we have already provided ways for users to use new parameters & attributes, but this part is still missing in terms of API-"upward"-compatibility.
I haven't seen too many requests for this over the years, but at least for the new reactions methods that came up a few times in the last days. Adding a way to do this would IMO be a notable step to make PTB even more future proof.
Describe the solution you'd like
Add a method Bot.do_api_request (or similar name) that accepts
- the name of an endpoint (e.g.
sendMessage, maybe also allowing python stylesend_messagewould be good - a json-dict with value to pass to TG
- optionally a
TelegramObjectsubclass that will be used tode_jsonthe return value
This method will then execute that request. The documentation should make clear, which utility functions of PTB are working and which are not working. In particular
- defaults handling can not work (if a new method accepts a
parse_modeparameter, that will either be part of the json-dict - such that no default value is inserted - or not - in wich case we can't know that a default value should be inserted) - convenience input parsing for
InputFile/ local file paths can't work b/c we don't know which parameters should be interpreted as media upload - setting default write-timeout to the media-write-timeout will work b/c the networking backend should detect that depending on
RequestData.files - Converting datetimes to ints will work (including default Timezones)
(These explanations could then in fact also be linked in the docstrings of the api_kwargs argument of the other methods)
The method should issue a warning if the Bot class has a method with the name of the requested endpoint, telling the user to use that one instead.
Describe alternatives you've considered
- instead of a json-dict one could just accept arbitrary keywoard arguments, which may be viewed as more convenient by some, but goes against the usual arguments philosophy that we have in PTB so far. This would leave the (very small) risk that a parameter name defined by TG would clash with a parameter name defined by PTB (e.g. the timeouts).
- Users can in theory also directoy use the networking backend (
BaseRequest.request()), however- we do not document (on purpose!) how
RequestDatais constructed - they'd still have to build the url on their own
- we do not document (on purpose!) how
- Instead of issuing warning for already-implemented endpoints, the method could in fact throw an exception. This would make every PTB-API release breaking by design.
Additional context
One outcome of #2162 is
python-telegram-bot/telegram/request/_baserequest.py
Lines 371 to 377 in 979988a
| if code in (HTTPStatus.NOT_FOUND, HTTPStatus.UNAUTHORIZED): # 404 and 401 | |
| # TG returns 404 Not found for | |
| # 1) malformed tokens | |
| # 2) correct tokens but non-existing method, e.g. api.tg.org/botTOKEN/unkonwnMethod | |
| # We can basically rule out 2) since we don't let users make requests manually | |
| # TG returns 401 Unauthorized for correctly formatted tokens that are not valid | |
| raise InvalidToken(message) |
If we allow users to manually set the endpoints via a new Bot.do_api_request, we might need to rething this part. One possible option would be to rename the error class to InvalidTokenOrMethod that we use here. An alternative would be to add special exception handling directly within Bot.do_api_request, converting InvalidToken into MethodNotFound with a message along the line "Assumg that Bot.initialize() worked correctly, the provided endpoint must be invalid".