2016-10-25 19:28:34 +02:00
|
|
|
#!/usr/bin/env python
|
|
|
|
#
|
|
|
|
# A library that provides a Python interface to the Telegram Bot API
|
2018-01-04 16:16:06 +01:00
|
|
|
# Copyright (C) 2015-2018
|
2016-10-25 19:28:34 +02:00
|
|
|
# Leandro Toledo de Souza <devs@python-telegram-bot.org>
|
|
|
|
#
|
|
|
|
# This program is free software: you can redistribute it and/or modify
|
|
|
|
# it under the terms of the GNU Lesser Public License as published by
|
|
|
|
# the Free Software Foundation, either version 3 of the License, or
|
|
|
|
# (at your option) any later version.
|
|
|
|
#
|
|
|
|
# This program is distributed in the hope that it will be useful,
|
|
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
# GNU Lesser Public License for more details.
|
|
|
|
#
|
|
|
|
# You should have received a copy of the GNU Lesser Public License
|
|
|
|
# along with this program. If not, see [http://www.gnu.org/licenses/].
|
2017-09-01 08:43:08 +02:00
|
|
|
"""This module contains helper functions."""
|
2019-11-15 21:51:22 +01:00
|
|
|
|
|
|
|
import datetime as dtm # dtm = "DateTime Module"
|
|
|
|
import time
|
|
|
|
|
2018-09-20 22:50:40 +02:00
|
|
|
from collections import defaultdict
|
2019-11-15 21:51:22 +01:00
|
|
|
from numbers import Number
|
2018-09-20 22:50:40 +02:00
|
|
|
|
|
|
|
try:
|
|
|
|
import ujson as json
|
|
|
|
except ImportError:
|
|
|
|
import json
|
2018-02-22 16:38:54 +01:00
|
|
|
from html import escape
|
2016-10-25 19:28:34 +02:00
|
|
|
|
2017-01-20 20:13:58 +01:00
|
|
|
import re
|
2018-01-09 16:54:07 +01:00
|
|
|
import signal
|
2016-10-25 19:28:34 +02:00
|
|
|
|
2018-01-09 16:54:07 +01:00
|
|
|
# From https://stackoverflow.com/questions/2549939/get-signal-names-from-numbers-in-python
|
|
|
|
_signames = {v: k
|
|
|
|
for k, v in reversed(sorted(vars(signal).items()))
|
|
|
|
if k.startswith('SIG') and not k.startswith('SIG_')}
|
|
|
|
|
|
|
|
|
|
|
|
def get_signal_name(signum):
|
|
|
|
"""Returns the signal name of the given signal number."""
|
|
|
|
return _signames[signum]
|
|
|
|
|
|
|
|
|
2019-11-15 21:51:22 +01:00
|
|
|
def escape_markdown(text):
|
|
|
|
"""Helper function to escape telegram markup symbols."""
|
|
|
|
escape_chars = '\*_`\['
|
|
|
|
return re.sub(r'([%s])' % escape_chars, r'\\\1', text)
|
|
|
|
|
|
|
|
|
|
|
|
# -------- date/time related helpers --------
|
|
|
|
# TODO: add generic specification of UTC for naive datetimes to docs
|
|
|
|
|
|
|
|
if hasattr(dtm, 'timezone'):
|
2017-07-01 17:08:45 +02:00
|
|
|
# Python 3.3+
|
2019-11-15 21:51:22 +01:00
|
|
|
def _datetime_to_float_timestamp(dt_obj):
|
|
|
|
if dt_obj.tzinfo is None:
|
|
|
|
dt_obj = dt_obj.replace(tzinfo=_UTC)
|
2017-07-01 17:08:45 +02:00
|
|
|
return dt_obj.timestamp()
|
2019-11-15 21:51:22 +01:00
|
|
|
|
|
|
|
_UtcOffsetTimezone = dtm.timezone
|
|
|
|
_UTC = dtm.timezone.utc
|
2017-07-01 17:08:45 +02:00
|
|
|
else:
|
|
|
|
# Python < 3.3 (incl 2.7)
|
|
|
|
|
2019-11-15 21:51:22 +01:00
|
|
|
# hardcoded timezone class (`datetime.timezone` isn't available in py2)
|
|
|
|
class _UtcOffsetTimezone(dtm.tzinfo):
|
|
|
|
def __init__(self, offset):
|
|
|
|
self.offset = offset
|
2017-07-01 17:08:45 +02:00
|
|
|
|
2019-11-15 21:51:22 +01:00
|
|
|
def tzname(self, dt):
|
|
|
|
return 'UTC +{}'.format(self.offset)
|
2016-10-25 19:28:34 +02:00
|
|
|
|
2019-11-15 21:51:22 +01:00
|
|
|
def utcoffset(self, dt):
|
|
|
|
return self.offset
|
|
|
|
|
|
|
|
def dst(self, dt):
|
|
|
|
return dtm.timedelta(0)
|
|
|
|
|
|
|
|
_UTC = _UtcOffsetTimezone(dtm.timedelta(0))
|
|
|
|
__EPOCH_DT = dtm.datetime.fromtimestamp(0, tz=_UTC)
|
|
|
|
__NAIVE_EPOCH_DT = __EPOCH_DT.replace(tzinfo=None)
|
2017-07-01 17:08:45 +02:00
|
|
|
|
2019-11-15 21:51:22 +01:00
|
|
|
# _datetime_to_float_timestamp
|
|
|
|
# Not using future.backports.datetime here as datetime value might be an input from the user,
|
|
|
|
# making every isinstace() call more delicate. So we just use our own compat layer.
|
|
|
|
def _datetime_to_float_timestamp(dt_obj):
|
|
|
|
epoch_dt = __EPOCH_DT if dt_obj.tzinfo is not None else __NAIVE_EPOCH_DT
|
|
|
|
return (dt_obj - epoch_dt).total_seconds()
|
2017-07-01 17:08:45 +02:00
|
|
|
|
2019-11-15 21:51:22 +01:00
|
|
|
_datetime_to_float_timestamp.__doc__ = \
|
|
|
|
"""Converts a datetime object to a float timestamp (with sub-second precision).
|
|
|
|
If the datetime object is timezone-naive, it is assumed to be in UTC."""
|
|
|
|
|
|
|
|
|
|
|
|
def to_float_timestamp(t, reference_timestamp=None):
|
2017-07-01 17:08:45 +02:00
|
|
|
"""
|
2019-11-15 21:51:22 +01:00
|
|
|
Converts a given time object to a float POSIX timestamp.
|
|
|
|
Used to convert different time specifications to a common format. The time object
|
|
|
|
can be relative (i.e. indicate a time increment, or a time of day) or absolute.
|
2020-02-02 20:20:54 +01:00
|
|
|
Any objects from the :class:`datetime` module that are timezone-naive will be assumed
|
2019-11-15 21:51:22 +01:00
|
|
|
to be in UTC.
|
|
|
|
|
|
|
|
``None`` s are left alone (i.e. ``to_float_timestamp(None)`` is ``None``).
|
|
|
|
|
2017-07-01 17:08:45 +02:00
|
|
|
Args:
|
2019-11-15 21:51:22 +01:00
|
|
|
t (int | float | datetime.timedelta | datetime.datetime | datetime.time):
|
|
|
|
Time value to convert. The semantics of this parameter will depend on its type:
|
|
|
|
|
|
|
|
* :obj:`int` or :obj:`float` will be interpreted as "seconds from ``reference_t``"
|
|
|
|
* :obj:`datetime.timedelta` will be interpreted as
|
|
|
|
"time increment from ``reference_t``"
|
|
|
|
* :obj:`datetime.datetime` will be interpreted as an absolute date/time value
|
|
|
|
* :obj:`datetime.time` will be interpreted as a specific time of day
|
|
|
|
|
|
|
|
reference_timestamp (float, optional): POSIX timestamp that indicates the absolute time
|
|
|
|
from which relative calculations are to be performed (e.g. when ``t`` is given as an
|
|
|
|
:obj:`int`, indicating "seconds from ``reference_t``"). Defaults to now (the time at
|
|
|
|
which this function is called).
|
|
|
|
|
|
|
|
If ``t`` is given as an absolute representation of date & time (i.e. a
|
|
|
|
``datetime.datetime`` object), ``reference_timestamp`` is not relevant and so its
|
|
|
|
value should be ``None``. If this is not the case, a ``ValueError`` will be raised.
|
2017-07-01 17:08:45 +02:00
|
|
|
|
|
|
|
Returns:
|
2019-11-15 21:51:22 +01:00
|
|
|
(float | None) The return value depends on the type of argument ``t``. If ``t`` is
|
|
|
|
given as a time increment (i.e. as a obj:`int`, :obj:`float` or
|
|
|
|
:obj:`datetime.timedelta`), then the return value will be ``reference_t`` + ``t``.
|
|
|
|
|
|
|
|
Else if it is given as an absolute date/time value (i.e. a :obj:`datetime.datetime`
|
|
|
|
object), the equivalent value as a POSIX timestamp will be returned.
|
2017-09-01 08:43:08 +02:00
|
|
|
|
2019-11-15 21:51:22 +01:00
|
|
|
Finally, if it is a time of the day without date (i.e. a :obj:`datetime.time`
|
|
|
|
object), the return value is the nearest future occurrence of that time of day.
|
|
|
|
|
|
|
|
Raises:
|
|
|
|
TypeError: if `t`'s type is not one of those described above
|
2017-07-01 17:08:45 +02:00
|
|
|
"""
|
|
|
|
|
2019-11-15 21:51:22 +01:00
|
|
|
if reference_timestamp is None:
|
|
|
|
reference_timestamp = time.time()
|
|
|
|
elif isinstance(t, dtm.datetime):
|
|
|
|
raise ValueError('t is an (absolute) datetime while reference_timestamp is not None')
|
|
|
|
|
|
|
|
if isinstance(t, dtm.timedelta):
|
|
|
|
return reference_timestamp + t.total_seconds()
|
|
|
|
elif isinstance(t, Number):
|
|
|
|
return reference_timestamp + t
|
|
|
|
elif isinstance(t, dtm.time):
|
|
|
|
if t.tzinfo is not None:
|
|
|
|
reference_dt = dtm.datetime.fromtimestamp(reference_timestamp, tz=t.tzinfo)
|
|
|
|
else:
|
|
|
|
reference_dt = dtm.datetime.utcfromtimestamp(reference_timestamp) # assume UTC
|
|
|
|
reference_date = reference_dt.date()
|
|
|
|
reference_time = reference_dt.timetz()
|
|
|
|
if reference_time > t: # if the time of day has passed today, use tomorrow
|
|
|
|
reference_date += dtm.timedelta(days=1)
|
|
|
|
return _datetime_to_float_timestamp(dtm.datetime.combine(reference_date, t))
|
|
|
|
elif isinstance(t, dtm.datetime):
|
|
|
|
return _datetime_to_float_timestamp(t)
|
|
|
|
|
|
|
|
raise TypeError('Unable to convert {} object to timestamp'.format(type(t).__name__))
|
|
|
|
|
|
|
|
|
|
|
|
def to_timestamp(dt_obj, reference_timestamp=None):
|
|
|
|
"""
|
|
|
|
Wrapper over :func:`to_float_timestamp` which returns an integer (the float value truncated
|
|
|
|
down to the nearest integer).
|
|
|
|
|
|
|
|
See the documentation for :func:`to_float_timestamp` for more details.
|
|
|
|
"""
|
|
|
|
return int(to_float_timestamp(dt_obj, reference_timestamp)) if dt_obj is not None else None
|
2017-07-01 17:08:45 +02:00
|
|
|
|
|
|
|
|
|
|
|
def from_timestamp(unixtime):
|
|
|
|
"""
|
2019-11-15 21:51:22 +01:00
|
|
|
Converts an (integer) unix timestamp to a naive datetime object in UTC.
|
|
|
|
``None`` s are left alone (i.e. ``from_timestamp(None)`` is ``None``).
|
|
|
|
|
2017-07-01 17:08:45 +02:00
|
|
|
Args:
|
2019-11-15 21:51:22 +01:00
|
|
|
unixtime (int): integer POSIX timestamp
|
2017-07-01 17:08:45 +02:00
|
|
|
|
|
|
|
Returns:
|
2019-11-15 21:51:22 +01:00
|
|
|
equivalent :obj:`datetime.datetime` value in naive UTC if ``timestamp`` is not
|
|
|
|
``None``; else ``None``
|
2017-07-01 17:08:45 +02:00
|
|
|
"""
|
2019-11-15 21:51:22 +01:00
|
|
|
if unixtime is None:
|
2017-07-01 17:08:45 +02:00
|
|
|
return None
|
|
|
|
|
2019-11-15 21:51:22 +01:00
|
|
|
return dtm.datetime.utcfromtimestamp(unixtime)
|
|
|
|
|
|
|
|
# -------- end --------
|
2017-09-01 08:40:05 +02:00
|
|
|
|
|
|
|
|
|
|
|
def mention_html(user_id, name):
|
|
|
|
"""
|
|
|
|
Args:
|
|
|
|
user_id (:obj:`int`) The user's id which you want to mention.
|
|
|
|
name (:obj:`str`) The name the mention is showing.
|
|
|
|
|
|
|
|
Returns:
|
|
|
|
:obj:`str`: The inline mention for the user as html.
|
|
|
|
"""
|
|
|
|
if isinstance(user_id, int):
|
2018-05-28 22:51:39 +02:00
|
|
|
return u'<a href="tg://user?id={}">{}</a>'.format(user_id, escape(name))
|
2017-09-01 08:40:05 +02:00
|
|
|
|
|
|
|
|
|
|
|
def mention_markdown(user_id, name):
|
|
|
|
"""
|
|
|
|
Args:
|
|
|
|
user_id (:obj:`int`) The user's id which you want to mention.
|
|
|
|
name (:obj:`str`) The name the mention is showing.
|
|
|
|
|
|
|
|
Returns:
|
|
|
|
:obj:`str`: The inline mention for the user as markdown.
|
|
|
|
"""
|
|
|
|
if isinstance(user_id, int):
|
2018-05-28 22:51:39 +02:00
|
|
|
return u'[{}](tg://user?id={})'.format(escape_markdown(name), user_id)
|
2018-02-15 10:21:19 +01:00
|
|
|
|
|
|
|
|
|
|
|
def effective_message_type(entity):
|
|
|
|
"""
|
|
|
|
Extracts the type of message as a string identifier from a :class:`telegram.Message` or a
|
|
|
|
:class:`telegram.Update`.
|
|
|
|
|
|
|
|
Args:
|
|
|
|
entity (:obj:`Update` | :obj:`Message`) The ``update`` or ``message`` to extract from
|
|
|
|
|
|
|
|
Returns:
|
|
|
|
str: One of ``Message.MESSAGE_TYPES``
|
|
|
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
# Importing on file-level yields cyclic Import Errors
|
|
|
|
from telegram import Message
|
|
|
|
from telegram import Update
|
|
|
|
|
|
|
|
if isinstance(entity, Message):
|
|
|
|
message = entity
|
|
|
|
elif isinstance(entity, Update):
|
|
|
|
message = entity.effective_message
|
|
|
|
else:
|
|
|
|
raise TypeError("entity is not Message or Update (got: {})".format(type(entity)))
|
|
|
|
|
|
|
|
for i in Message.MESSAGE_TYPES:
|
|
|
|
if getattr(message, i, None):
|
|
|
|
return i
|
|
|
|
|
|
|
|
return None
|
2018-09-20 22:50:40 +02:00
|
|
|
|
|
|
|
|
2019-09-13 21:09:05 +02:00
|
|
|
def create_deep_linked_url(bot_username, payload=None, group=False):
|
|
|
|
"""
|
|
|
|
Creates a deep-linked URL for this ``bot_username`` with the specified ``payload``.
|
|
|
|
See https://core.telegram.org/bots#deep-linking to learn more.
|
|
|
|
|
|
|
|
The ``payload`` may consist of the following characters: ``A-Z, a-z, 0-9, _, -``
|
|
|
|
|
|
|
|
Note:
|
|
|
|
Works well in conjunction with
|
|
|
|
``CommandHandler("start", callback, filters = Filters.regex('payload'))``
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
``create_deep_linked_url(bot.get_me().username, "some-params")``
|
|
|
|
|
|
|
|
Args:
|
|
|
|
bot_username (:obj:`str`): The username to link to
|
|
|
|
payload (:obj:`str`, optional): Parameters to encode in the created URL
|
|
|
|
group (:obj:`bool`, optional): If `True` the user is prompted to select a group to add the
|
|
|
|
bot to. If `False`, opens a one-on-one conversation with the bot. Defaults to `False`.
|
|
|
|
|
|
|
|
Returns:
|
|
|
|
:obj:`str`: An URL to start the bot with specific parameters
|
|
|
|
"""
|
|
|
|
if bot_username is None or len(bot_username) <= 3:
|
|
|
|
raise ValueError("You must provide a valid bot_username.")
|
|
|
|
|
|
|
|
base_url = 'https://t.me/{}'.format(bot_username)
|
|
|
|
if not payload:
|
|
|
|
return base_url
|
|
|
|
|
|
|
|
if len(payload) > 64:
|
|
|
|
raise ValueError("The deep-linking payload must not exceed 64 characters.")
|
|
|
|
|
|
|
|
if not re.match(r'^[A-Za-z0-9_-]+$', payload):
|
|
|
|
raise ValueError("Only the following characters are allowed for deep-linked "
|
|
|
|
"URLs: A-Z, a-z, 0-9, _ and -")
|
|
|
|
|
|
|
|
if group:
|
|
|
|
key = 'startgroup'
|
|
|
|
else:
|
|
|
|
key = 'start'
|
|
|
|
|
|
|
|
return '{0}?{1}={2}'.format(
|
|
|
|
base_url,
|
|
|
|
key,
|
|
|
|
payload
|
|
|
|
)
|
|
|
|
|
|
|
|
|
2020-01-26 21:24:00 +01:00
|
|
|
def encode_conversations_to_json(conversations):
|
2018-09-20 22:50:40 +02:00
|
|
|
"""Helper method to encode a conversations dict (that uses tuples as keys) to a
|
|
|
|
JSON-serializable way. Use :attr:`_decode_conversations_from_json` to decode.
|
|
|
|
|
|
|
|
Args:
|
|
|
|
conversations (:obj:`dict`): The conversations dict to transofrm to JSON.
|
|
|
|
|
|
|
|
Returns:
|
|
|
|
:obj:`str`: The JSON-serialized conversations dict
|
|
|
|
"""
|
|
|
|
tmp = {}
|
|
|
|
for handler, states in conversations.items():
|
|
|
|
tmp[handler] = {}
|
|
|
|
for key, state in states.items():
|
|
|
|
tmp[handler][json.dumps(key)] = state
|
|
|
|
return json.dumps(tmp)
|
|
|
|
|
|
|
|
|
|
|
|
def decode_conversations_from_json(json_string):
|
|
|
|
"""Helper method to decode a conversations dict (that uses tuples as keys) from a
|
|
|
|
JSON-string created with :attr:`_encode_conversations_to_json`.
|
|
|
|
|
|
|
|
Args:
|
|
|
|
json_string (:obj:`str`): The conversations dict as JSON string.
|
|
|
|
|
|
|
|
Returns:
|
|
|
|
:obj:`dict`: The conversations dict after decoding
|
|
|
|
"""
|
|
|
|
tmp = json.loads(json_string)
|
|
|
|
conversations = {}
|
|
|
|
for handler, states in tmp.items():
|
|
|
|
conversations[handler] = {}
|
|
|
|
for key, state in states.items():
|
|
|
|
conversations[handler][tuple(json.loads(key))] = state
|
|
|
|
return conversations
|
|
|
|
|
|
|
|
|
|
|
|
def decode_user_chat_data_from_json(data):
|
|
|
|
"""Helper method to decode chat or user data (that uses ints as keys) from a
|
|
|
|
JSON-string.
|
|
|
|
|
|
|
|
Args:
|
|
|
|
data (:obj:`str`): The user/chat_data dict as JSON string.
|
|
|
|
|
|
|
|
Returns:
|
|
|
|
:obj:`dict`: The user/chat_data defaultdict after decoding
|
|
|
|
"""
|
|
|
|
|
|
|
|
tmp = defaultdict(dict)
|
|
|
|
decoded_data = json.loads(data)
|
|
|
|
for user, data in decoded_data.items():
|
|
|
|
user = int(user)
|
|
|
|
tmp[user] = {}
|
|
|
|
for key, value in data.items():
|
|
|
|
try:
|
|
|
|
key = int(key)
|
|
|
|
except ValueError:
|
|
|
|
pass
|
|
|
|
tmp[user][key] = value
|
|
|
|
return tmp
|