From 1a7ea1f5d5580133ac478cf89921454bef71d6c5 Mon Sep 17 00:00:00 2001 From: Harmon Date: Sun, 27 Feb 2022 14:14:28 -0600 Subject: [PATCH] Add documentation for Space --- docs/v2_models.rst | 17 ++++------- tweepy/space.py | 75 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+), 12 deletions(-) diff --git a/docs/v2_models.rst b/docs/v2_models.rst index 8d824ec..846e281 100644 --- a/docs/v2_models.rst +++ b/docs/v2_models.rst @@ -28,21 +28,14 @@ Models .. autoclass:: Poll() -.. class:: tweepy.ReferencedTweet - - :reference: https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/tweet - -.. class:: tweepy.Space - - .. versionadded:: 4.1 +:class:`Space` +============== - .. versionchanged:: 4.4 - Added ``ended_at`` and ``topic_ids`` fields +.. autoclass:: Space() - .. versionchanged:: 4.6 - Added ``subscriber_count`` field +.. class:: tweepy.ReferencedTweet - :reference: https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/space + :reference: https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/tweet .. class:: tweepy.Tweet diff --git a/tweepy/space.py b/tweepy/space.py index 73c8a38..1453147 100644 --- a/tweepy/space.py +++ b/tweepy/space.py @@ -7,6 +7,81 @@ from tweepy.utils import parse_datetime class Space(HashableID, DataMapping): + """Spaces allow expression and interaction via live audio conversations. + The Space data dictionary contains relevant metadata about a Space; all the + details are updated in real time. + + User objects can found and expanded in the user resource. These objects are + available for expansion by adding at least one of ``host_ids``, + ``creator_id``, ``speaker_ids``, ``mentioned_user_ids`` to the + ``expansions`` query parameter. + + Unlike Tweets, Spaces are ephemeral and become unavailable after they end + or when they are canceled by their creator. When your app handles Spaces + data, you are responsible for returning the most up-to-date information, + and must remove data that is no longer available from the platform. The + `Spaces lookup endpoints`_ can help you ensure you respect the users’ + expectations and intent. + + .. versionadded:: 4.1 + + .. versionchanged:: 4.4 + Added ``ended_at`` and ``topic_ids`` fields + + .. versionchanged:: 4.6 + Added ``subscriber_count`` field + + Attributes + ---------- + data : dict + The JSON data representing the Space. + id : str + The unique identifier of the requested Space. + state : str + Indicates if the Space has started or will start in the future, or if + it has ended. + created_at : datetime.datetime | None + Creation time of this Space. + ended_at : datetime.datetime | None + Time when the Space was ended. Only available for ended Spaces. + host_ids : list + The unique identifier of the users who are hosting this Space. + lang : str | None + Language of the Space, if detected by Twitter. Returned as a BCP47 + language tag. + is_ticketed : bool | None + Indicates is this is a ticketed Space. + invited_user_ids : list + The list of user IDs that were invited to join as speakers. Usually, + users in this list are invited to speak via the Invite user option. + participant_count : int | None + The current number of users in the Space, including Hosts and Speakers. + scheduled_start : datetime.datetime | None + Indicates the start time of a scheduled Space, as set by the creator of + the Space. This field is returned only if the Space has been scheduled; + in other words, if the field is returned, it means the Space is a + scheduled Space. + speaker_ids : list + The list of users who were speaking at any point during the Space. This + list contains all the users in ``invited_user_ids`` in addition to any + user who requested to speak and was allowed via the Add speaker option. + started_at : datetime.datetime | None + Indicates the actual start time of a Space. + subscriber_count : int | None + title : str | None + The title of the Space as specified by the creator. + topic_ids : list + A list of IDs of the topics selected by the creator of the Space. + updated_at : datetime.datetime | None + Specifies the date and time of the last update to any of the Space's + metadata, such as its title or scheduled time. + + References + ---------- + https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/space + + .. _Spaces lookup endpoints: https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/introduction + """ __slots__ = ( "data", "id", "state", "created_at", "ended_at", "host_ids", "lang", -- 2.25.1