From: Harmon <Harmon758@gmail.com>
Date: Sun, 27 Feb 2022 20:14:28 +0000 (-0600)
Subject: Add documentation for Space
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=1a7ea1f5d5580133ac478cf89921454bef71d6c5;p=tweepy.git

Add documentation for Space
---

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",