[Feature] Improve handling of local mode & docs regarding file handling

[Bibo-Joshi]

I suggest to add a flag local_api_server/local_mode/similar naming to the Bot class which can be used to tell ptb that the bot is running against a bot api server in --local mode. Currently the benefit of that would be that we could accept file paths in all cases. In local mode, we pass the URI, otherwise we load the contents in binary mode.
If the local mode has more benefits in the future, we could leveral this setting.

What do the other team members think about this?

Additionally, we should unify the documentation on how files are handled.
Some of the classes/methods that accept file input have a note like here, but others don't. Also that note is outdated, as it doesn't explain when a pathlib.Path can be passed. It should also mention that we don't support open(file, 'r') but only open(file, 'rb'). We should either have a unified note that we add everywhere or move this snippets section to a standalone page, extend it a bit and point to it from the docs.
I'm slightly in favor of the latter.

To avoid repitition of Note: … strings in the docs, we can .. include:: them - see sphinx-doc/sphinx/issues/9939

[Poolitzer]

What do the other team members think about this?

I think it is a small improvement, and I don't think that much more benefits will come to the local API, especially not some which would change further how our library handles stuff. On the other hand, its a big change (and allows the local server to be used as intended), so I think its a good one.

I think a note for every input handling a file is the best solution, and since that would take quite some additional screen time, linking to a second page where it is explained in detail how file handling works in PTB is good.

[Bibo-Joshi]

I think it is a small improvement, and I don't think that much more benefits will come to the local API, especially not some which would change further how our library handles stuff. On the other hand, its a big change (and allows the local server to be used as intended), so I think its a good one.

I'm a big confused here 😄 "I think it is a small improvement" vs "its a big change". Do you mean that the added value is small while the code/compatiblity change is big?

[Poolitzer]

Sorry, mistyped. Small change, big improvement.

[harshil21]

About the sphinx issue linked.. I found an alternative - We could use rst Substitutions in such places too. Maybe not as effective as an include, but it would reduce repetition in _bot.py specially (the timeout + api_kwargs param). I tested the below and it works:

_bot.py:

class Bot(TGObject):
    """....
        .. |read_timeout| replace:: Value to pass to ...
    """

    async def get_me(...):
    """
    Keyword Args:
        read_timeout (:obj:`....`): |read_timeout|
        ...
    """

If you all agree this is effective enough for the time being, I can open a good first issue for this.

[Bibo-Joshi]

Interesting! covering the name & type part probably doesn't work? if not: TBH I feel like it would be worth to first try and PR to sphinx about sphinx-doc/sphinx#9939. OTOH, switching from a |replace| solution to a .. include:: solution if sphinx-doc/sphinx#9939 ever gets resolved will probably be rather easy 🤔 So I'm probably okay with both :D