Skip to content

Use datetime.timedelta to Represent Time Periods #4575

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Bibo-Joshi opened this issue Nov 24, 2024 · 5 comments
Open

Use datetime.timedelta to Represent Time Periods #4575

Bibo-Joshi opened this issue Nov 24, 2024 · 5 comments
Labels
⚙️ bot-api affected functionality: bot-api 🛠 refactor change type: refactor
Milestone

Comments

@Bibo-Joshi
Copy link
Member

Bibo-Joshi commented Nov 24, 2024

What kind of feature are you missing? Where do you notice a shortcoming of PTB?

Several Telegram Objects and methods currently contain fields/parameters with names \w+_period, wherer the integer value represents a time span in seconds.
Working with plain seconds is not very pythonic, just like working with posix timestamps isn't.

Describe the solution you'd like

In the long run, we should convert the attributes to timedelta objects and make the parameters accept timedelta objects.

Methods Parameters

This is realtively easy, simply accept timedelta as well as integers and pass totalseconds() to TG. Converting dtm.timedelta to int can probably be done in the internals of Bot or requests so that it doesn't have to happen in each bot method.

Classes

  • Both attributes and arguments should only accept timedeltas in the long run.
  • Since this is a breaking change, we should issue a warning for now about this changing in the future and encouraging users to harden their code against the change
  • For making the timedelta support available early, I have two ideas, both optional
    • We can provide a temporary property that returns the timedelta object (e.g. xy_period_timedelta). This would need to issue a warning stating that it will be removed once timedelta is natively supported. Not overly clean …
    • We anyways need to make the *_period attributes properties to issue the deprecation warning. We could use this and look for an environment variable, say PTB_TIMEDELTA. If set, we return the timedelta object, otherwise the int. → let's do this

Describe alternatives you've considered

No response

Additional context

Adding support for method parameters can be done independently of handling classes.

@Bibo-Joshi Bibo-Joshi added ⚙️ bot-api affected functionality: bot-api 📋 triage work status: triage 🛠 refactor change type: refactor and removed 📋 triage work status: triage labels Nov 24, 2024
@Bibo-Joshi Bibo-Joshi mentioned this issue Nov 24, 2024
5 tasks
@Bibo-Joshi Bibo-Joshi added this to the v22.0 milestone Nov 25, 2024
@cuevasrja
Copy link
Contributor

cuevasrja commented Nov 29, 2024

Hi, my class group and I want to work in this Issue.

Group:
@Jeam-zx
@Migueldsc12
@AnyaMarcanito
@henryg311
@cuevasrja

@Bibo-Joshi
Copy link
Member Author

@cuevasrja & friends if you're still interested, would you like to get started on this? I think it would be good to split this into two PRs, one for the Bot method arguments and one for the classes. Some additional pointers on both:

  • for the arguments of Bot methods, converting timedelta to int should happen at
    if isinstance(value, datetime):
    return to_timestamp(value), []

    and corresponding new parametrizations need to be added to
    def test_from_input_no_media(self, value, expected_value):
    request_parameter = RequestParameter.from_input("key", value)
    assert request_parameter.value == expected_value
    assert request_parameter.input_files is None

    Moreover, it would be good to explicitly tests timedelta inputs for the arguments known so far. I expect that the corresponding test functions can be decorated with something like @pytest.mark.parametrize("foo_period", [42, dtm.timedelta(seconds=42)]) so that no additional test functions are needed.
  • for converting arguments of classes to timedelta, please add a new helper function to
    """This module contains helper functions related to parsing arguments for classes and methods.

    It should directly issue deprecation warnings if the input is an integer. Search for PTBDeprecationWarning in the code base to see some example on how we do that. We'll also want unit tests that ensure that the warning is issued correctly for all casses that use the conversion
  • converting the int value received from telegram to timedelta should happen in the de_json method of the respective class. If the class doesn't override TelegramObject.de_json yet, add that. The test_de_json unit tests for the respective classes will have to be updated
  • for the attributes of classes: Let's say we consider subscription_period. Change self.subscription_period = … to self._subscription_period = … and add a property subscription_period. Add a new helper function to
    """This module contains helper functions related to datetime and timestamp conversations.

    along the lines
    def get_timedelta_value(value: dtm.timedelta) -> Union[int, dtm.timedelta]:
        if os.get_env("PTB_TIMEDELTA"):
            return value
        # issue PTBDeprecationWarning explaining that in the future dtm.timedelta will be returned and encouraging users to set the env var
        return value.totalseconds()
    Here as well, we'll need unit tests that ensure that the properties return the expected value with/without the env var and issue the warning correctly

@cuevasrja
Copy link
Contributor

Hi @Bibo-Joshi , Sorry, we are coming back from vacation and now I am reading your message.

Yes, not all of us will be able to participate but we are still interested in contributing to the project if possible even if it is not for an academic reason.

@Bibo-Joshi
Copy link
Member Author

No worries :) glad to hear that you'd like to contribute. In the meantime I've already created #4651 for the bot method part, but the class parameter/attribute part is still open. You're welcome to open a PR for that. Let me know if you have any questions.

Bibo-Joshi added a commit that referenced this issue Feb 2, 2025
# Conflicts:
#	telegram/_bot.py
#	telegram/_utils/types.py
#	telegram/ext/_extbot.py
@Bibo-Joshi
Copy link
Member Author

@cuevasrja how is it looking for your? Ideally, I'd still like to get this into a 21.x release, such that we can remove any deprecation shims in 23.0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
⚙️ bot-api affected functionality: bot-api 🛠 refactor change type: refactor
Projects
None yet
Development

No branches or pull requests

2 participants