From 25cd8247d15563400976020b5ecacdd32b9ac645 Mon Sep 17 00:00:00 2001 From: chillymosh <86857777+chillymosh@users.noreply.github.com> Date: Sun, 9 Feb 2025 09:34:54 +0000 Subject: [PATCH] Update method docstrings with coro / aiter --- twitchio/client.py | 12 +++++++++--- twitchio/models/channel_points.py | 22 ++++++++++++++++------ twitchio/models/channels.py | 4 +++- twitchio/models/clips.py | 8 ++++++-- twitchio/models/entitlements.py | 4 +++- twitchio/models/eventsub_.py | 13 +++++++++---- twitchio/models/polls.py | 4 +++- twitchio/models/predictions.py | 4 +++- twitchio/models/schedule.py | 11 +++++++---- twitchio/models/search.py | 4 +++- twitchio/models/streams.py | 4 +++- twitchio/models/teams.py | 5 +---- 12 files changed, 66 insertions(+), 29 deletions(-) diff --git a/twitchio/client.py b/twitchio/client.py index 5815ac60..1433ee7b 100644 --- a/twitchio/client.py +++ b/twitchio/client.py @@ -280,7 +280,9 @@ async def setup_hook(self) -> None: ... async def login(self, *, token: str | None = None, load_tokens: bool = True, save_tokens: bool = True) -> None: - """Method to login the client and generate or store an app token. + """|coro| + + Method to login the client and generate or store an app token. This method is called automatically when using :meth:`~.start`. You should **NOT** call this method if you are using :meth:`~.start`. @@ -461,7 +463,9 @@ async def run() -> None: pass async def close(self, **options: Any) -> None: - r"""Method which closes the :class:`~Client` gracefully. + r"""|coro| + + Method which closes the :class:`~Client` gracefully. This method is called for you automatically when using :meth:`~.run` or when using the client with the async context-manager, E.g: `async with client:` @@ -536,7 +540,9 @@ async def wait_until_ready(self) -> None: await self._ready_event.wait() async def wait_for(self, event: str, *, timeout: float | None = None, predicate: WaitPredicateT | None = None) -> Any: - """Method which waits for any known dispatched event and returns the payload associated with the event. + """|coro| + + Method which waits for any known dispatched event and returns the payload associated with the event. This method can be used with a predicate check to determine whether the `wait_for` should stop listening and return the event payload. diff --git a/twitchio/models/channel_points.py b/twitchio/models/channel_points.py index 55184f78..114e07fa 100644 --- a/twitchio/models/channel_points.py +++ b/twitchio/models/channel_points.py @@ -221,9 +221,11 @@ def get_image(self, size: Literal["1x", "2x", "4x"] = "2x", use_default: bool = return Asset(url, http=self._http) async def delete(self) -> None: - """Delete the custom reward. + """|coro| - The app used to create the reward is the only app that may delete it. + Delete the custom reward. + + The app / client ID used to create the reward is the only app that may delete it. If the reward's redemption status is UNFULFILLED at the time the reward is deleted, its redemption status is marked as FULFILLED. .. note:: @@ -248,7 +250,9 @@ async def update( paused: bool | None = None, skip_queue: bool | None = None, ) -> CustomReward: - """Update the custom reward. + """|coro| + + Update the custom reward. .. important:: The app / client ID used to create the reward is the only app that may update the reward. @@ -336,7 +340,9 @@ def fetch_redemptions( sort: Literal["OLDEST", "NEWEST"] = "OLDEST", first: int = 20, ) -> HTTPAsyncIterator[CustomRewardRedemption]: - """Fetch redemptions from the CustomReward. + """|aiter| + + Fetch redemptions from the CustomReward. Canceled and fulfilled redemptions are returned for only a few days after they're canceled or fulfilled. @@ -419,7 +425,9 @@ def __repr__(self) -> str: return f"" async def fulfill(self) -> CustomRewardRedemption: - """Updates a redemption's status to FULFILLED. + """|coro| + + Updates a redemption's status to FULFILLED. .. note:: Requires a user access token that includes the ``channel:manage:redemptions`` scope. @@ -439,7 +447,9 @@ async def fulfill(self) -> CustomRewardRedemption: return CustomRewardRedemption(data["data"][0], parent_reward=self.reward, http=self._http) async def refund(self) -> CustomRewardRedemption: - """Updates a redemption's status to CANCELED. + """|coro| + + Updates a redemption's status to CANCELED. .. note:: Requires a user access token that includes the ``channel:manage:redemptions`` scope. diff --git a/twitchio/models/channels.py b/twitchio/models/channels.py index 1006c78b..2aa521db 100644 --- a/twitchio/models/channels.py +++ b/twitchio/models/channels.py @@ -219,7 +219,9 @@ def __repr__(self) -> str: return f"" async def fetch_game(self) -> Game: - """Fetches the :class:~twitchio.Game` associated with this ChannelInfo. + """|coro| + + Fetches the :class:~twitchio.Game` associated with this ChannelInfo. Returns ------- diff --git a/twitchio/models/clips.py b/twitchio/models/clips.py index 104f8ee1..8e01e0d2 100644 --- a/twitchio/models/clips.py +++ b/twitchio/models/clips.py @@ -126,7 +126,9 @@ def __str__(self) -> str: return self.id async def fetch_game(self) -> Game: - """Fetches the :class:`~twitchio.Game` associated with this Clip. + """|coro| + + Fetches the :class:`~twitchio.Game` associated with this Clip. Returns ------- @@ -137,7 +139,9 @@ async def fetch_game(self) -> Game: return Game(payload["data"][0], http=self._http) async def fetch_video(self) -> Video | None: - """Fetches the :class:`~twitchio.Video` associated with this clip, if it can be found. + """|coro| + + Fetches the :class:`~twitchio.Video` associated with this clip, if it can be found. Returns ------- diff --git a/twitchio/models/entitlements.py b/twitchio/models/entitlements.py index 75b4ea4d..94f27d47 100644 --- a/twitchio/models/entitlements.py +++ b/twitchio/models/entitlements.py @@ -94,7 +94,9 @@ def __str__(self) -> str: return self.id async def fetch_game(self) -> Game: - """Fetches the :class:`~twitchio.Game` associated with this drop entitlement. + """|coro| + + Fetches the :class:`~twitchio.Game` associated with this drop entitlement. Returns ------- diff --git a/twitchio/models/eventsub_.py b/twitchio/models/eventsub_.py index 7edae071..b428fbbd 100644 --- a/twitchio/models/eventsub_.py +++ b/twitchio/models/eventsub_.py @@ -880,7 +880,8 @@ def __repr__(self) -> str: return f"" async def fetch_emote_set(self, *, token_for: str | PartialUser | None = None) -> EmoteSet: - """ + """|coro| + Fetches emotes for this emote set. Parameters @@ -3431,7 +3432,8 @@ def __repr__(self) -> str: return f"" async def fulfill(self, *, token_for: str | PartialUser) -> CustomRewardRedemption: - """ + """|coro| + Updates the redemption's status to FULFILLED. .. note:: @@ -3459,7 +3461,8 @@ async def fulfill(self, *, token_for: str | PartialUser) -> CustomRewardRedempti return CustomRewardRedemption(data["data"][0], parent_reward=reward, http=self._http) async def refund(self, *, token_for: str | PartialUser) -> CustomRewardRedemption: - """ + """|coro| + Updates the redemption's status to CANCELED. .. note:: @@ -5171,7 +5174,9 @@ def __repr__(self) -> str: return f"" async def delete(self, *, token_for: str | None = None) -> None: - """Delete the eventsub subscription. + """|coro| + + Delete the eventsub subscription. Parameters ---------- diff --git a/twitchio/models/polls.py b/twitchio/models/polls.py index 7d5d4fa7..845c790b 100644 --- a/twitchio/models/polls.py +++ b/twitchio/models/polls.py @@ -117,7 +117,9 @@ def __repr__(self) -> str: return f"" async def end_poll(self, *, status: Literal["ARCHIVED", "TERMINATED"]) -> Poll: - """End an active poll. + """|coro| + + End an active poll. .. note:: Requires user access token that includes the `channel:manage:polls` scope. diff --git a/twitchio/models/predictions.py b/twitchio/models/predictions.py index 9a02e66a..6b78f762 100644 --- a/twitchio/models/predictions.py +++ b/twitchio/models/predictions.py @@ -130,7 +130,9 @@ async def end_prediction( status: Literal["RESOLVED", "CANCELED", "LOCKED"], winning_outcome_id: str | None = None, ) -> Prediction: - """End an active prediction. + """|coro| + + End an active prediction. .. note:: Requires user access token that includes the `channel:manage:predictions` scope. diff --git a/twitchio/models/schedule.py b/twitchio/models/schedule.py index 070678db..7b684b6e 100644 --- a/twitchio/models/schedule.py +++ b/twitchio/models/schedule.py @@ -126,7 +126,6 @@ def __repr__(self) -> str: async def update_segment( self, *, - token_for: str | PartialUser, start_time: datetime.datetime | None = None, duration: int | None = None, category_id: str | None = None, @@ -134,7 +133,9 @@ async def update_segment( canceled: bool | None = None, timezone: str | None = None, ) -> Schedule: - """Updates a scheduled broadcast segment. + """|coro| + + Updates a scheduled broadcast segment. .. note:: Requires a user access token that includes the ``channel:manage:schedule`` scope. @@ -187,8 +188,10 @@ async def update_segment( return Schedule(data["data"], http=self._http) - async def delete(self, *, token_for: str | PartialUser) -> None: - """Removes a broadcast segment from the broadcaster's streaming schedule. + async def delete(self) -> None: + """|coro| + + Removes a broadcast segment from the broadcaster's streaming schedule. For recurring segments, removing a segment removes all segments in the recurring schedule. diff --git a/twitchio/models/search.py b/twitchio/models/search.py index 1407ca88..b34d65df 100644 --- a/twitchio/models/search.py +++ b/twitchio/models/search.py @@ -97,7 +97,9 @@ def __repr__(self) -> str: return f"" async def fetch_game(self) -> Game: - """Fetches the :class:`~twitchio.Game` associated with this channel. + """|coro| + + Fetches the :class:`~twitchio.Game` associated with this channel. The :class:`~twitchio.Game` returned is current from the time the :class:`~twitchio.SearchChannel` instance was created. diff --git a/twitchio/models/streams.py b/twitchio/models/streams.py index e618ce6e..b2e7313f 100644 --- a/twitchio/models/streams.py +++ b/twitchio/models/streams.py @@ -116,7 +116,9 @@ def __repr__(self) -> str: return f"" async def fetch_game(self) -> Game | None: - """Fetches the :class:`~twitchio.Game` associated with this stream. + """|coro| + + Fetches the :class:`~twitchio.Game` associated with this stream. The :class:`~twitchio.Game` returned is current from the time the :class:`~twitchio.Stream` instance was created. diff --git a/twitchio/models/teams.py b/twitchio/models/teams.py index 9955f884..470f8cb7 100644 --- a/twitchio/models/teams.py +++ b/twitchio/models/teams.py @@ -104,10 +104,7 @@ def __str__(self) -> str: return self.name def __eq__(self, __value: object) -> bool: - if not isinstance(__value, Team): - return NotImplemented - - return __value.id == self.id + return __value.id == self.id if isinstance(__value, Team) else NotImplemented class ChannelTeam: