{"record":{"id":"14243076a78d6269","repo":"python-telegram-bot/python-telegram-bot","slug":"in-a-future-major-version-attribute-attribute","errorCode":null,"errorMessage":"In a future major version attribute `{attribute}` will be of type `datetime.timedelta`. You can opt-in early by setting `PTB_TIMEDELTA=true` or ``PTB_TIMEDELTA=1`` as an environment variable.","messagePattern":"In a future major version attribute `(.+?)` will be of type `datetime\\.timedelta`\\. You can opt-in early by setting `PTB_TIMEDELTA=true` or ``PTB_TIMEDELTA=1`` as an environment variable\\.","errorType":"console","errorClass":"PTBDeprecationWarning","httpStatus":null,"severity":"warning","filePath":"src/telegram/_utils/datetime.py","lineNumber":276,"sourceCode":"    Note:\n        When `PTB_TIMEDELTA` is not enabled, the function will issue a deprecation warning.\n\n    Args:\n        value (:obj:`datetime.timedelta`): The timedelta value to process.\n        attribute (:obj:`str`): The name of the attribute at the caller scope, used for\n            warning messages.\n\n    Returns:\n        - :obj:`None` if :paramref:`value` is None.\n        - :obj:`datetime.timedelta` if `PTB_TIMEDELTA=true` or ``PTB_TIMEDELTA=1``.\n        - :obj:`int` if the total seconds is a whole number.\n        - float: otherwise.\n    \"\"\"\n    if value is None:\n        return None\n    if os.getenv(\"PTB_TIMEDELTA\", \"false\").lower().strip() in [\"true\", \"1\"]:\n        return value\n    warn(\n        PTBDeprecationWarning(\n            \"v22.2\",\n            f\"In a future major version attribute `{attribute}` will be of type\"\n            \" `datetime.timedelta`. You can opt-in early by setting `PTB_TIMEDELTA=true`\"\n            \" or ``PTB_TIMEDELTA=1`` as an environment variable.\",\n        ),\n        stacklevel=2,\n    )\n    return (\n        int(seconds)  # type: ignore[return-value]\n        if (seconds := value.total_seconds()).is_integer()\n        else seconds\n    )\n","sourceCodeStart":258,"sourceCodeEnd":290,"githubUrl":"https://github.com/python-telegram-bot/python-telegram-bot/blob/d3b69d2e9fb7af6c796f84516cfda751752c7cb7/src/telegram/_utils/datetime.py#L258-L290","documentation":"PTB 22.2+ warns that duration-like attributes (audio.duration, message.live_period, etc.) will change from float/int seconds to datetime.timedelta in a future major version. The warning fires on every read of such an attribute unless you opt in early.","triggerScenarios":"Reading attributes like Message.duration, live_period, start_timestamp, audio.duration, gif_duration, mpeg4_duration via to_timedelta_value-based properties while PTB_TIMEDELTA env var is not set to true/1.","commonSituations":"Upgrading to python-telegram-bot >= 22.2 without setting PTB_TIMEDELTA; libraries or user code reading duration attributes trigger the deprecation warning repeatedly.","solutions":["Set environment variable PTB_TIMEDELTA=true (or 1) and migrate code to use datetime.timedelta","Pin python-telegram-bot to <22.2 until you can migrate","Suppress PTBDeprecationWarning via warnings filter as a temporary measure"],"exampleFix":"# before\nduration = message.audio.duration  # warns\n\n# after\nimport os\nos.environ[\"PTB_TIMEDELTA\"] = \"true\"\nduration = message.audio.duration  # datetime.timedelta\nprint(duration.total_seconds())","handlingStrategy":"validation","validationCode":"import os\nos.environ.setdefault(\"PTB_TIMEDELTA\", \"true\")  # set before importing telegram","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set PTB_TIMEDELTA=true in deployment env early and migrate to timedelta","Treat duration attributes as timedelta in new code"],"tags":["telegram","deprecation","timedelta","migration"],"backgroundTag":"library-deprecation-warning","analyzedSha":"d3b69d2e9fb7af6c796f84516cfda751752c7cb7","analyzedAt":"2026-08-28T16:18:54.805Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}