Poll¶
- class telegram.Poll(id, question, options, total_voter_count, is_closed, is_anonymous, type, allows_multiple_answers, correct_option_id=None, explanation=None, explanation_entities=None, open_period=None, close_date=None, question_entities=None, *, api_kwargs=None)[source]¶
Bases:
telegram.TelegramObject
This object contains information about a poll.
Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their
id
is equal.Examples
Returned In
- Parameters:
options (Sequence[
PollOption
]) –List of poll options.
Changed in version 20.0: Accepts any
collections.abc.Sequence
as input instead of just a list. The input is converted to a tuple.is_anonymous (
bool
) –True
, if the poll is anonymous.allows_multiple_answers (
bool
) –True
, if the poll allows multiple answers.correct_option_id (
int
, optional) – A zero based identifier of the correct answer option. Available only for closed polls in the quiz mode, which were sent (not forwarded), by the bot or to a private chat with the bot.explanation (
str
, optional) – Text that is shown when a user chooses an incorrect answer or taps on the lamp icon in a quiz-style poll, 0-200
characters.explanation_entities (Sequence[
telegram.MessageEntity
], optional) –Special entities like usernames, URLs, bot commands, etc. that appear in the
explanation
. This list is empty if the message does not contain explanation entities.Changed in version 20.0:
This attribute is now always a (possibly empty) list and never
None
.Accepts any
collections.abc.Sequence
as input instead of just a list. The input is converted to a tuple.
open_period (
int
, optional) – Amount of time in seconds the poll will be active after creation.close_date (
datetime.datetime
, optional) –Point in time (Unix timestamp) when the poll will be automatically closed. Converted to
datetime.datetime
.Changed in version 20.3: The default timezone of the bot is used for localization, which is UTC unless
telegram.ext.Defaults.tzinfo
is used.question_entities (Sequence[
telegram.MessageEntity
], optional) –Special entities that appear in the
question
. Currently, only custom emoji entities are allowed in poll questions.Added in version 21.2.
- options[source]¶
List of poll options.
Changed in version 20.0: This attribute is now an immutable tuple.
- Type:
tuple[
PollOption
]
- correct_option_id[source]¶
Optional. A zero based identifier of the correct answer option. Available only for closed polls in the quiz mode, which were sent (not forwarded), by the bot or to a private chat with the bot.
- Type:
- explanation[source]¶
Optional. Text that is shown when a user chooses an incorrect answer or taps on the lamp icon in a quiz-style poll, 0-
200
characters.- Type:
- explanation_entities[source]¶
Special entities like usernames, URLs, bot commands, etc. that appear in the
explanation
. This list is empty if the message does not contain explanation entities.Changed in version 20.0: This attribute is now an immutable tuple.
Changed in version 20.0: This attribute is now always a (possibly empty) list and never
None
.- Type:
tuple[
telegram.MessageEntity
]
- open_period[source]¶
Optional. Amount of time in seconds the poll will be active after creation.
- Type:
- close_date[source]¶
Optional. Point in time when the poll will be automatically closed.
Changed in version 20.3: The default timezone of the bot is used for localization, which is UTC unless
telegram.ext.Defaults.tzinfo
is used.- Type:
- question_entities[source]¶
Special entities that appear in the
question
. Currently, only custom emoji entities are allowed in poll questions. This list is empty if the question does not contain entities.Added in version 21.2.
- Type:
tuple[
telegram.MessageEntity
]
- MAX_EXPLANATION_LENGTH = 200[source]¶
telegram.constants.PollLimit.MAX_EXPLANATION_LENGTH
Added in version 20.0.
- MAX_EXPLANATION_LINE_FEEDS = 2[source]¶
telegram.constants.PollLimit.MAX_EXPLANATION_LINE_FEEDS
Added in version 20.0.
- MAX_OPEN_PERIOD = 600[source]¶
telegram.constants.PollLimit.MAX_OPEN_PERIOD
Added in version 20.0.
- MAX_OPTION_LENGTH = 100[source]¶
telegram.constants.PollLimit.MAX_OPTION_LENGTH
Added in version 20.0.
- MAX_OPTION_NUMBER = 10[source]¶
telegram.constants.PollLimit.MAX_OPTION_NUMBER
Added in version 20.0.
- MAX_QUESTION_LENGTH = 300[source]¶
telegram.constants.PollLimit.MAX_QUESTION_LENGTH
Added in version 20.0.
- MIN_OPEN_PERIOD = 5[source]¶
telegram.constants.PollLimit.MIN_OPEN_PERIOD
Added in version 20.0.
- MIN_OPTION_LENGTH = 1[source]¶
telegram.constants.PollLimit.MIN_OPTION_LENGTH
Added in version 20.0.
- MIN_OPTION_NUMBER = 2[source]¶
telegram.constants.PollLimit.MIN_OPTION_NUMBER
Added in version 20.0.
- MIN_QUESTION_LENGTH = 1[source]¶
telegram.constants.PollLimit.MIN_QUESTION_LENGTH
Added in version 20.0.
- parse_explanation_entities(types=None)[source]¶
Returns a
dict
that mapstelegram.MessageEntity
tostr
. It contains entities from this polls explanation filtered by theirtype
attribute as the key, and the text that each entity belongs to as the value of thedict
.Note
This method should always be used instead of the
explanation_entities
attribute, since it calculates the correct substring from the message text based on UTF-16 codepoints. Seeparse_explanation_entity
for more info.- Parameters:
types (list[
str
], optional) – List ofMessageEntity
types as strings. If thetype
attribute of an entity is contained in this list, it will be returned. Defaults totelegram.MessageEntity.ALL_TYPES
.- Returns:
A dictionary of entities mapped to the text that belongs to them, calculated based on UTF-16 codepoints.
- Return type:
dict[
telegram.MessageEntity
,str
]- Raises:
RuntimeError – If the poll has no explanation.
- parse_explanation_entity(entity)[source]¶
Returns the text in
explanation
from a giventelegram.MessageEntity
ofexplanation_entities
.Note
This method is present because Telegram calculates the offset and length in UTF-16 codepoint pairs, which some versions of Python don’t handle automatically. (That is, you can’t just slice
Message.text
with the offset and length.)- Parameters:
entity (
telegram.MessageEntity
) – The entity to extract the text from. It must be an entity that belongs toexplanation_entities
.- Returns:
The text of the given entity.
- Return type:
- Raises:
RuntimeError – If the poll has no explanation.
- parse_question_entities(types=None)[source]¶
Returns a
dict
that mapstelegram.MessageEntity
tostr
. It contains entities from this polls question filtered by theirtype
attribute as the key, and the text that each entity belongs to as the value of thedict
.Added in version 21.2.
Note
This method should always be used instead of the
question_entities
attribute, since it calculates the correct substring from the message text based on UTF-16 codepoints. Seeparse_question_entity
for more info.- Parameters:
types (list[
str
], optional) – List ofMessageEntity
types as strings. If thetype
attribute of an entity is contained in this list, it will be returned. Defaults totelegram.MessageEntity.ALL_TYPES
.- Returns:
A dictionary of entities mapped to the text that belongs to them, calculated based on UTF-16 codepoints.
- Return type:
dict[
telegram.MessageEntity
,str
]
- parse_question_entity(entity)[source]¶
Returns the text in
question
from a giventelegram.MessageEntity
ofquestion_entities
.Added in version 21.2.
Note
This method is present because Telegram calculates the offset and length in UTF-16 codepoint pairs, which some versions of Python don’t handle automatically. (That is, you can’t just slice
Message.text
with the offset and length.)- Parameters:
entity (
telegram.MessageEntity
) – The entity to extract the text from. It must be an entity that belongs toquestion_entities
.- Returns:
The text of the given entity.
- Return type: