Add new args to create_clip and deprecate has_delay

Author: chillymosh

docs/getting-started/changelog.rst

@@ -18,9 +18,11 @@ Changelog
             This replaces :func:`~twitchio.PartialUser.fetch_hype_train_events` which has been deprecated
         - Added - :attr:`~twitchio.Chatter.lead_moderator`
         - Added - :func:`~twitchio.ext.commands.is_lead_moderator` guard
+        - Added - New optional title and duration arguments for :func:`~twitchio.PartialUser.create_clip`
 
     - Changes
         - :attr:`~twitchio.Chatter.moderator` returns True for Lead Moderator role.
+        - :func:`~twitchio.PartialUser.create_clip` `has_delay` argument has been deprecated.
 
     - Bug fixes
         - Fix :func:`~twitchio.utils.setup_logging` breaking coloured formatting on `CRITICAL` logging level

twitchio/http.py

@@ -1337,9 +1337,15 @@ async def post_create_clip(
         *,
         broadcaster_id: str | int,
         token_for: str | PartialUser,
-        has_delay: bool = False,
+        title: str | None = None,
+        duration: float | None = None,
     ) -> CreateClipResponse:
-        params = {"broadcaster_id": broadcaster_id, "has_delay": has_delay}
+        params: dict[str, str | float] = {"broadcaster_id": broadcaster_id}
+
+        if title is not None:
+            params["title"] = title
+        if duration is not None:
+            params["duration"] = duration
 
         route: Route = Route("POST", "clips", params=params, token_for=token_for)
         return await self.request_json(route)

twitchio/models/clips.py

@@ -166,6 +166,18 @@ async def fetch_video(self) -> Video | None:
 
 
 class CreatedClip:
+    """Represents a Created Clip
+
+    Attributes
+    -----------
+    id: str
+        An ID that uniquely identifies the clip.
+    edit_url: str
+    A URL that you can use to edit the clip's title, identify the part of the clip to publish, and publish the clip. `Learn More <https://help.twitch.tv/s/article/how-to-use-clips>`_
+
+    The URL is valid for up to 24 hours or until the clip is published, whichever comes first.
+    """
+
     __slots__ = ("edit_url", "id")
 
     def __init__(self, data: CreateClipResponseData) -> None:

twitchio/user.py

@@ -1236,7 +1236,12 @@ async def update_chatter_color(self, color: str) -> None:
         return await self._http.put_user_chat_color(user_id=self.id, color=color, token_for=self.id)
 
     async def create_clip(
-        self, *, token_for: str | PartialUser, has_delay: bool = False
+        self,
+        *,
+        token_for: str | PartialUser,
+        has_delay: bool = False,
+        title: str | None = None,
+        duration: float | None = None,
     ) -> CreatedClip:  # TODO Test this with non broadcaster token
         """|coro|
 
@@ -1248,7 +1253,7 @@ async def create_clip(
         This may occur if you begin capturing the clip near the beginning or end of the stream.
 
         By default, Twitch publishes up to the last 30 seconds of the 90 seconds window and provides a default title for the clip.
-        To specify the title and the portion of the 90 seconds window that's used for the clip, use the URL in the CreatedClip's ``edit_url`` attribute.
+        You can now specify the title and the duration via this method, or specify the title and the portion of the 90 seconds window that's used for the clip by using the URL in the CreatedClip's ``edit_url`` attribute.
         You can specify a clip that's from 5 seconds to 60 seconds in length. The URL is valid for up to 24 hours or until the clip is published, whichever comes first.
 
         Creating a clip is an asynchronous process that can take a short amount of time to complete.
@@ -1258,23 +1263,38 @@ async def create_clip(
         .. note::
             Requires a user access token that includes the ``clips:edit`` scope.
 
+
+        .. warning::
+            The `has_delay` argument has been removed by Twitch and no longer has any effect.
+            It has been retained to avoid breaking changes for users who still have it set.
+
         Parameters
         ----------
+        title: str | None
+            The title of the clip.
+        duration: float | None
+            The length of the clip in seconds. Possible values range from 5 to 60 inclusively with a precision of 0.1. The default is 30
         has_delay: bool
-            A Boolean value that determines whether the API captures the clip at the moment the viewer requests it or after a delay.
-            If False (default), Twitch captures the clip at the moment the viewer requests it (this is the same clip experience as the Twitch UX).
-            If True, Twitch adds a delay before capturing the clip (this basically shifts the capture window to the right slightly).
+            This has been been removed by Twitch and no longer has any effect.
+            It has been retained to avoid breaking changes for users who still have it set.
         token_for: str | PartialUser
             User access token that includes the ``clips:edit`` scope.
 
         Returns
         -------
         CreatedClip
             The CreatedClip object.
+        Raises
+        ------
+        ValueError
+            Clip duration must be between 5 and 60, with precision of 0.1
         """
+        if duration is not None and not (5 <= duration <= 60):
+            raise ValueError("Clip duration must be between 5 and 60, with precision of 0.1")
+
         from .models.clips import CreatedClip
 
-        data = await self._http.post_create_clip(broadcaster_id=self.id, token_for=token_for, has_delay=has_delay)
+        data = await self._http.post_create_clip(broadcaster_id=self.id, token_for=token_for, title=title, duration=duration)
         return CreatedClip(data["data"][0])
 
     def fetch_clips(