Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changes/unreleased/5078.FoNwUYLbXQFRebTFhR6UPn.toml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ pull_requests = [
{ uid = "5079", author_uid = "aelkheir" },
{ uid = "5084", author_uids = ["Bibo-Joshi"] },
{ uid = "5085", author_uids = ["Bibo-Joshi"] },
{ uid = "5087", author_uids = ["Bibo-Joshi"] },
{ uid = "5091", author_uids = ["Bibo-Joshi"] },
{ uid = "5090", author_uids = ["Bibo-Joshi"] },
{ uid = "5089", author_uids = ["Bibo-Joshi"] },
Expand Down
4 changes: 4 additions & 0 deletions docs/source/inclusions/bot_methods.rst
Original file line number Diff line number Diff line change
Expand Up @@ -485,8 +485,12 @@
- Used for getting basic info about a file
* - :meth:`~telegram.Bot.get_available_gifts`
- Used for getting information about gifts available for sending
* - :meth:`~telegram.Bot.get_chat_gifts`
- Used for getting information about gifts owned and hosted by a chat
* - :meth:`~telegram.Bot.get_me`
- Used for getting basic information about the bot
* - :meth:`~telegram.Bot.get_user_gifts`
- Used for getting information about gifts owned and hosted by a user
* - :meth:`~telegram.Bot.save_prepared_inline_message`
- Used for storing a message to be sent by a user of a Mini App

Expand Down
158 changes: 158 additions & 0 deletions src/telegram/_bot.py
Original file line number Diff line number Diff line change
Expand Up @@ -11724,6 +11724,160 @@ async def repost_story(
bot=self,
)

async def get_user_gifts(
self,
user_id: int,
exclude_unlimited: bool | None = None,
exclude_limited_upgradable: bool | None = None,
exclude_limited_non_upgradable: bool | None = None,
exclude_from_blockchain: bool | None = None,
exclude_unique: bool | None = None,
sort_by_price: bool | None = None,
offset: str | None = None,
limit: int | None = None,
*,
read_timeout: ODVInput[float] = DEFAULT_NONE,
write_timeout: ODVInput[float] = DEFAULT_NONE,
connect_timeout: ODVInput[float] = DEFAULT_NONE,
pool_timeout: ODVInput[float] = DEFAULT_NONE,
api_kwargs: JSONDict | None = None,
) -> OwnedGifts:
"""Returns the gifts owned and hosted by a user.

.. versionadded:: NEXT.VERSION

user_id (:obj:`int`): Unique identifier of the user
exclude_unlimited (:obj:`bool`, optional): Pass :obj:`True` to exclude gifts that can be
purchased an unlimited number of times
exclude_limited_upgradable (:obj:`bool`, optional): Pass :obj:`True` to exclude gifts that
can be purchased a limited number of times and can be upgraded to unique
exclude_limited_non_upgradable (:obj:`bool`, optional): Pass :obj:`True` to exclude gifts
that can be purchased a limited number of times and can't be upgraded to unique
exclude_from_blockchain (:obj:`bool`, optional): Pass :obj:`True` to exclude gifts that
were assigned from the TON blockchain and can't be resold or transferred in Telegram
exclude_unique (:obj:`bool`, optional): Pass :obj:`True` to exclude unique gifts
sort_by_price (:obj:`bool`, optional): Pass :obj:`True` to sort results by gift price
instead of send date. Sorting is applied before pagination.
offset (:obj:`str`, optional): Offset of the first entry to return as received from the
previous request; use an empty string to get the first chunk of results
limit (:obj:`int`, optional): The maximum number of gifts to be returned;
:tg-const:`~telegram.constants.BusinessLimit.MIN_GIFT_RESULTS` -
:tg-const:`~telegram.constants.BusinessLimit.MAX_GIFT_RESLUTS`.
Defaults to :tg-const:`~telegram.constants.BusinessLimit.MAX_GIFT_RESLUTS`

Returns:
:class:`telegram.OwnedGifts`: The owned gifts for the user.

Raises:
:class:`telegram.error.TelegramError`
"""
data: JSONDict = {
"user_id": user_id,
"exclude_unlimited": exclude_unlimited,
"exclude_limited_upgradable": exclude_limited_upgradable,
"exclude_limited_non_upgradable": exclude_limited_non_upgradable,
"exclude_from_blockchain": exclude_from_blockchain,
"exclude_unique": exclude_unique,
"sort_by_price": sort_by_price,
"offset": offset,
"limit": limit,
}

result = await self._post(
"getUserGifts",
data,
read_timeout=read_timeout,
write_timeout=write_timeout,
connect_timeout=connect_timeout,
pool_timeout=pool_timeout,
api_kwargs=api_kwargs,
)
return OwnedGifts.de_json(result, self)

async def get_chat_gifts(
self,
chat_id: int | str,
exclude_unsaved: bool | None = None,
exclude_saved: bool | None = None,
exclude_unlimited: bool | None = None,
exclude_limited_upgradable: bool | None = None,
exclude_limited_non_upgradable: bool | None = None,
exclude_from_blockchain: bool | None = None,
exclude_unique: bool | None = None,
sort_by_price: bool | None = None,
offset: str | None = None,
limit: int | None = None,
*,
read_timeout: ODVInput[float] = DEFAULT_NONE,
write_timeout: ODVInput[float] = DEFAULT_NONE,
connect_timeout: ODVInput[float] = DEFAULT_NONE,
pool_timeout: ODVInput[float] = DEFAULT_NONE,
api_kwargs: JSONDict | None = None,
) -> OwnedGifts:
"""Use this method to get gifts owned by a chat.

.. versionadded:: NEXT.VERSION

Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
exclude_unsaved (:obj:`bool`, optional): Pass :obj:`True` to exclude gifts that aren't
saved to the chat's profile page. Always :obj:`True`, unless the bot has the
:attr:`~telegram.ChatAdministratorRights..can_post_messages` administrator right in the
channel.
exclude_saved (:obj:`bool`, optional): Pass :obj:`True` to exclude gifts that are saved to
the chat's profile page. Always :obj:`False`, unless the bot has the
:attr:`~telegram.ChatAdministratorRights..can_post_messages` administrator right in the
channel.
exclude_unlimited (:obj:`bool`, optional): Pass :obj:`True` to exclude gifts that can be
purchased an unlimited number of times
exclude_limited_upgradable (:obj:`bool`, optional): Pass :obj:`True` to exclude gifts that
can be purchased a limited number of times and can be upgraded to unique
exclude_limited_non_upgradable (:obj:`bool`, optional): Pass :obj:`True` to exclude gifts
that can be purchased a limited number of times and can't be upgraded to unique
exclude_from_blockchain (:obj:`bool`, optional): Pass :obj:`True` to exclude gifts that
were assigned from the TON blockchain and can't be resold or transferred in Telegram
exclude_unique (:obj:`bool`, optional): Pass :obj:`True` to exclude unique gifts
sort_by_price (:obj:`bool`, optional): Pass :obj:`True` to sort results by gift price
instead of send date. Sorting is applied before pagination.
offset (:obj:`str`, optional): Offset of the first entry to return as received from the
previous request; use an empty string to get the first chunk of results
limit (:obj:`int`, optional): The maximum number of gifts to be returned;
:tg-const:`~telegram.constants.BusinessLimit.MIN_GIFT_RESULTS` -
:tg-const:`~telegram.constants.BusinessLimit.MAX_GIFT_RESLUTS`.
Defaults to :tg-const:`~telegram.constants.BusinessLimit.MAX_GIFT_RESLUTS`

Returns:
:class:`telegram.OwnedGifts`: The owned gifts for the chat.

Raises:
:class:`telegram.error.TelegramError`
"""

data: JSONDict = {
"chat_id": chat_id,
"exclude_unsaved": exclude_unsaved,
"exclude_saved": exclude_saved,
"exclude_unlimited": exclude_unlimited,
"exclude_limited_upgradable": exclude_limited_upgradable,
"exclude_limited_non_upgradable": exclude_limited_non_upgradable,
"exclude_from_blockchain": exclude_from_blockchain,
"exclude_unique": exclude_unique,
"sort_by_price": sort_by_price,
"offset": offset,
"limit": limit,
}

result = await self._post(
"getChatGifts",
data,
read_timeout=read_timeout,
write_timeout=write_timeout,
connect_timeout=connect_timeout,
pool_timeout=pool_timeout,
api_kwargs=api_kwargs,
)
return OwnedGifts.de_json(result, self)

def to_dict(self, recursive: bool = True) -> JSONDict: # noqa: ARG002
"""See :meth:`telegram.TelegramObject.to_dict`."""
data: JSONDict = {"id": self.id, "username": self.username, "first_name": self.first_name}
Expand Down Expand Up @@ -12052,3 +12206,7 @@ def to_dict(self, recursive: bool = True) -> JSONDict: # noqa: ARG002
"""Alias for :meth:`decline_suggested_post`"""
repostStory = repost_story
"""Alias for :meth:`repost_story`"""
getUserGifts = get_user_gifts
"""Alias for :meth:`get_user_gifts`"""
getChatGifts = get_chat_gifts
"""Alias for :meth:`get_chat_gifts`"""
51 changes: 51 additions & 0 deletions src/telegram/_chat.py
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@
Message,
MessageEntity,
MessageId,
OwnedGifts,
PhotoSize,
ReplyParameters,
Sticker,
Expand Down Expand Up @@ -3944,6 +3945,56 @@ async def repost_story(
api_kwargs=api_kwargs,
)

async def get_gifts(
self,
exclude_unsaved: bool | None = None,
exclude_saved: bool | None = None,
exclude_unlimited: bool | None = None,
exclude_limited_upgradable: bool | None = None,
exclude_limited_non_upgradable: bool | None = None,
exclude_from_blockchain: bool | None = None,
exclude_unique: bool | None = None,
sort_by_price: bool | None = None,
offset: str | None = None,
limit: int | None = None,
*,
read_timeout: ODVInput[float] = DEFAULT_NONE,
write_timeout: ODVInput[float] = DEFAULT_NONE,
connect_timeout: ODVInput[float] = DEFAULT_NONE,
pool_timeout: ODVInput[float] = DEFAULT_NONE,
api_kwargs: JSONDict | None = None,
) -> "OwnedGifts":
"""Shortcut for::

await bot.get_chat_gifts(chat_id=update.effective_chat.id)

For the documentation of the arguments, please see
:meth:`telegram.Bot.get_chat_gifts`.

.. versionadded:: NEXT.VERSION

Returns:
:class:`telegram.OwnedGifts`: On success, returns the gifts owned by the chat.
"""
return await self.get_bot().get_chat_gifts(
chat_id=self.id,
exclude_unsaved=exclude_unsaved,
exclude_saved=exclude_saved,
exclude_unlimited=exclude_unlimited,
exclude_limited_upgradable=exclude_limited_upgradable,
exclude_limited_non_upgradable=exclude_limited_non_upgradable,
exclude_from_blockchain=exclude_from_blockchain,
exclude_unique=exclude_unique,
sort_by_price=sort_by_price,
offset=offset,
limit=limit,
read_timeout=read_timeout,
write_timeout=write_timeout,
connect_timeout=connect_timeout,
pool_timeout=pool_timeout,
api_kwargs=api_kwargs,
)


class Chat(_ChatBase):
"""This object represents a chat.
Expand Down
47 changes: 47 additions & 0 deletions src/telegram/_user.py
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@
Message,
MessageEntity,
MessageId,
OwnedGifts,
PhotoSize,
ReplyParameters,
Sticker,
Expand Down Expand Up @@ -2581,3 +2582,49 @@ async def repost_story(
pool_timeout=pool_timeout,
api_kwargs=api_kwargs,
)

async def get_gifts(
self,
exclude_unlimited: bool | None = None,
exclude_limited_upgradable: bool | None = None,
exclude_limited_non_upgradable: bool | None = None,
exclude_from_blockchain: bool | None = None,
exclude_unique: bool | None = None,
sort_by_price: bool | None = None,
offset: str | None = None,
limit: int | None = None,
*,
read_timeout: ODVInput[float] = DEFAULT_NONE,
write_timeout: ODVInput[float] = DEFAULT_NONE,
connect_timeout: ODVInput[float] = DEFAULT_NONE,
pool_timeout: ODVInput[float] = DEFAULT_NONE,
api_kwargs: JSONDict | None = None,
) -> "OwnedGifts":
"""Shortcut for::

await bot.get_user_gifts(user_id=update.effective_user.id)

For the documentation of the arguments, please see
:meth:`telegram.Bot.get_user_gifts`.

.. versionadded:: NEXT.VERSION

Returns:
:class:`telegram.OwnedGifts`: On success, returns the gifts owned by the user.
"""
return await self.get_bot().get_user_gifts(
user_id=self.id,
exclude_unlimited=exclude_unlimited,
exclude_limited_upgradable=exclude_limited_upgradable,
exclude_limited_non_upgradable=exclude_limited_non_upgradable,
exclude_from_blockchain=exclude_from_blockchain,
exclude_unique=exclude_unique,
sort_by_price=sort_by_price,
offset=offset,
limit=limit,
read_timeout=read_timeout,
write_timeout=write_timeout,
connect_timeout=connect_timeout,
pool_timeout=pool_timeout,
api_kwargs=api_kwargs,
)
18 changes: 14 additions & 4 deletions src/telegram/constants.py
Original file line number Diff line number Diff line change
Expand Up @@ -761,13 +761,23 @@ class BusinessLimit(IntEnum):
"""
MIN_GIFT_RESULTS = 1
""":obj:`int`: Minimum number of gifts to be returned. Relevant for
:paramref:`~telegram.Bot.get_business_account_gifts.limit` of
:meth:`telegram.Bot.get_business_account_gifts`.

* :paramref:`~telegram.Bot.get_business_account_gifts.limit` of
:meth:`telegram.Bot.get_business_account_gifts`.
* :paramref:`~telegram.Bot.get_chat_gifts.limit` of
:meth:`telegram.Bot.get_chat_gifts`.
* :paramref:`~telegram.Bot.get_user_gifts.limit` of
:meth:`telegram.Bot.get_user_gifts`.
"""
MAX_GIFT_RESULTS = 100
""":obj:`int`: Maximum number of gifts to be returned. Relevant for
:paramref:`~telegram.Bot.get_business_account_gifts.limit` of
:meth:`telegram.Bot.get_business_account_gifts`.

* :paramref:`~telegram.Bot.get_business_account_gifts.limit` of
:meth:`telegram.Bot.get_business_account_gifts`.
* :paramref:`~telegram.Bot.get_chat_gifts.limit` of
:meth:`telegram.Bot.get_chat_gifts`.
* :paramref:`~telegram.Bot.get_user_gifts.limit` of
:meth:`telegram.Bot.get_user_gifts`.
"""
MIN_STAR_COUNT = 1
""":obj:`int`: Minimum number of Telegram Stars to be transfered. Relevant for
Expand Down
Loading
Loading