Skip to content

[FEATURE] Bot.do_api_request #4053

@Bibo-Joshi

Description

@Bibo-Joshi

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 style send_message would be good
  • a json-dict with value to pass to TG
  • optionally a TelegramObject subclass that will be used to de_json the 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_mode parameter, 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 RequestData is constructed
    • they'd still have to build the url on their own
  • 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

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".

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions