Add documentation for Direct Message events

This documentation was previously missing from the Twitter API documentation when the Twitter API v2 Direct Messages endpoints were launched but has now recently been added.

diff --git a/tweepy/direct_message_event.py b/tweepy/direct_message_event.py
index 6ff037a42dac3a07ff032c4c8b651f1fc8380358..008baa7abc302db1e655b6f8eca130e927df3bbd 100644 (file)
--- a/tweepy/direct_message_event.py
+++ b/tweepy/direct_message_event.py
@@ -8,21 +8,89 @@ from tweepy.utils import parse_datetime
 
 
 class DirectMessageEvent(HashableID, DataMapping):
-    """.. versionadded:: 4.12
+    """Direct Message (DM) conversations are made up of events. The Twitter API
+    v2 currently supports three event types: MessageCreate, ParticipantsJoin,
+    and ParticipantsLeave.
+
+    DM event objects are returned by the `Direct Message lookup`_ endpoints,
+    and a MessageCreate event is created when Direct Messages are successfully
+    created with the `Manage Direct Messages`_ endpoints.
+
+    When requesting DM events, there are three default event object attributes,
+    or fields, included: ``id``, ``event_type``, and ``text``. To receive
+    additional event `fields`_, use the fields parameter ``dm_event.fields`` to
+    select others. Other available event fields include the following:
+    ``dm_conversation_id``, ``created_at``, ``sender_id`, ``attachments``,
+    ``participant_ids``, and ``referenced_tweets``.
+
+    Several of these fields provide the IDs of other Twitter objects related to
+    the Direct Message event:
+
+    * ``sender_id`` - The ID of the account that sent the message, or who
+      invited a participant to a group conversation
+    * ``partricipants_ids`` - An array of account IDs. For ParticipantsJoin and
+      ParticipantsLeave events this array will contain a single ID of the
+      account that created the event
+    * ``attachments`` - Provides media IDs for content that has been uploaded
+      to Twitter by the sender
+    * ``referenced_tweets`` - If a Tweet URL is found in the text field, the ID
+      of that Tweet is included in the response
+
+    The ``sender_id``, ``participant_ids``, ``referenced_tweets.id``, and
+    ``attachments.media_keys`` `expansions`_ are available to expand on these
+    Twitter object IDs.
+
+    .. versionadded:: 4.12
 
     Attributes
     ----------
     data : dict
         The JSON data representing the Direct Message event.
     id : int
+        The unique identifier of the event.
     event_type : str
-    attachments : dict | None
-    created_at : datetime.datetime | None
-    dm_conversation_id : str | None
+        Describes the type of event. Three types are currently supported:
+
+        * MessageCreate
+        * ParticipantsJoin
+        * ParticipantsLeave
+    text : str | None
+        The actual UTF-8 text of the Direct Message. 
+    sender_id : int | None
+        ID of the User creating the event. To expand this object in the
+        response, include ``sender_id`` as an expansion and use the
+        ``user.fields`` query parameter to specify User object attributes of
+        interest.
     participant_ids : list[int] | None
+        IDs of the participants joining and leaving a group conversation. Also
+        used when creating new group conversations. To expand this object in
+        the response, include ``participant_ids`` as an expansion and use the
+        ``user.fields`` query parameter to specify User object attributes of
+        interest.
+    dm_conversation_id : str | None
+        The unique identifier of the conversation the event is apart of.
+    created_at : datetime.datetime | None
+        Creation time (UTC) of the Tweet.
     referenced_tweets : list[ReferencedTweet] | None
-    sender_id : int | None
-    text : str | None
+        ID for any Tweet mentioned in the Direct Message text. To expand this
+        object in the response, include ``referenced_tweets.id`` as an
+        expansion and use the ``tweet.fields`` query parameter to specify Tweet
+        object attributes of interest.
+    attachments : dict | None
+        For Direct Messages with attached Media, provides the media key of the
+        uploaded content (photo, video, or GIF. To expand this object in the
+        response, include ``attachments.media_keys`` as an expansion and use
+        the ``media.fields`` query parameter to specify media object attributes
+        of interest. Currently, one attachment is supported. 
+
+    References
+    ----------
+    https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/dm-events
+
+    .. _Direct Message lookup: https://developer.twitter.com/en/docs/twitter-api/direct-messages/lookup/introduction
+    .. _Manage Direct Messages: https://developer.twitter.com/en/docs/twitter-api/direct-messages/manage/introduction
+    .. _fields: https://developer.twitter.com/en/docs/twitter-api/fields
+    .. _expansions: https://developer.twitter.com/en/docs/twitter-api/expansions
     """
 
     __slots__ = (
@@ -36,18 +104,22 @@ class DirectMessageEvent(HashableID, DataMapping):
         self.id = int(data["id"])
         self.event_type = data["event_type"]
 
-        self.attachments = data.get("attachments")
-
-        self.created_at = data.get("created_at")
-        if self.created_at is not None:
-            self.created_at = parse_datetime(self.created_at)
+        self.text = data.get("text")
 
-        self.dm_conversation_id = data.get("dm_conversation_id")
+        self.sender_id = data.get("sender_id")
+        if self.sender_id is not None:
+            self.sender_id = int(self.sender_id)
 
         self.participant_ids = data.get("participant_ids")
         if self.participant_ids is not None:
             self.participant_ids = list(map(int, self.participant_ids))
 
+        self.dm_conversation_id = data.get("dm_conversation_id")
+
+        self.created_at = data.get("created_at")
+        if self.created_at is not None:
+            self.created_at = parse_datetime(self.created_at)
+
         self.referenced_tweets = data.get("referenced_tweets")
         if self.referenced_tweets is not None:
             self.referenced_tweets = [
@@ -55,11 +127,7 @@ class DirectMessageEvent(HashableID, DataMapping):
                 for referenced_tweet in self.referenced_tweets
             ]
 
-        self.sender_id = data.get("sender_id")
-        if self.sender_id is not None:
-            self.sender_id = int(self.sender_id)
-
-        self.text = data.get("text")
+        self.attachments = data.get("attachments")
 
     def __repr__(self):
         representation = (