Add constants for potential model object fields

docs/expansions_and_fields.rst

@@ -269,3 +269,32 @@ user data objects.
 .. _Space fields: https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/space
 .. _Tweet fields: https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/tweet
 .. _user fields: https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/user
+
+Constants
+---------
+
+These constants are available directly in the :mod:`tweepy` module, which means
+each file itself does not need to be imported. For example,
+:const:`tweepy.user.USER_FIELDS` is available as :const:`tweepy.USER_FIELDS`.
+
+.. autodata:: tweepy.direct_message_event.DIRECT_MESSAGE_EVENT_FIELDS
+
+.. autodata:: tweepy.direct_message_event.DM_EVENT_FIELDS
+
+.. autodata:: tweepy.list.LIST_FIELDS
+
+.. autodata:: tweepy.media.MEDIA_FIELDS
+
+.. autodata:: tweepy.place.PLACE_FIELDS
+
+.. autodata:: tweepy.poll.POLL_FIELDS
+
+.. autodata:: tweepy.space.PUBLIC_SPACE_FIELDS
+
+.. autodata:: tweepy.space.SPACE_FIELDS
+
+.. autodata:: tweepy.tweet.PUBLIC_TWEET_FIELDS
+
+.. autodata:: tweepy.tweet.TWEET_FIELDS
+
+.. autodata:: tweepy.user.USER_FIELDS

tweepy/__init__.py

@@ -17,22 +17,26 @@
 from tweepy.cache import Cache, FileCache, MemoryCache
 from tweepy.client import Client, Response
 from tweepy.cursor import Cursor
-from tweepy.direct_message_event import DirectMessageEvent
+from tweepy.direct_message_event import (
+    DirectMessageEvent, DIRECT_MESSAGE_EVENT_FIELDS, DM_EVENT_FIELDS
+)
 from tweepy.errors import (
     BadRequest, Forbidden, HTTPException, NotFound, TooManyRequests,
     TweepyException, TwitterServerError, Unauthorized
 )
-from tweepy.list import List
-from tweepy.media import Media
+from tweepy.list import List, LIST_FIELDS
+from tweepy.media import Media, MEDIA_FIELDS
 from tweepy.pagination import Paginator
-from tweepy.place import Place
-from tweepy.poll import Poll
-from tweepy.space import Space
+from tweepy.place import Place, PLACE_FIELDS
+from tweepy.poll import Poll, POLL_FIELDS
+from tweepy.space import PUBLIC_SPACE_FIELDS, Space, SPACE_FIELDS
 from tweepy.streaming import (
     StreamingClient, StreamResponse, StreamRule
 )
-from tweepy.tweet import ReferencedTweet, Tweet
-from tweepy.user import User
+from tweepy.tweet import (
+    PUBLIC_TWEET_FIELDS, ReferencedTweet, Tweet, TWEET_FIELDS
+)
+from tweepy.user import User, USER_FIELDS
 
 # Global, unauthenticated instance of API
 api = API()

tweepy/direct_message_event.py

@@ -7,6 +7,22 @@
 from tweepy.utils import parse_datetime
 
 
+#: All the potential fields for :class:`DirectMessageEvent` objects
+DIRECT_MESSAGE_EVENT_FIELDS = [
+    "attachments",
+    "created_at",
+    "dm_conversation_id",
+    "event_type",
+    "id",
+    "participant_ids",
+    "referenced_tweets",
+    "sender_id",
+    "text",
+]
+#: Alias for :const:`DIRECT_MESSAGE_EVENT_FIELDS`
+DM_EVENT_FIELDS = DIRECT_MESSAGE_EVENT_FIELDS
+
+
 class DirectMessageEvent(HashableID, DataMapping):
     """Direct Message (DM) conversations are made up of events. The Twitter API
     v2 currently supports three event types: MessageCreate, ParticipantsJoin,

tweepy/list.py

@@ -6,6 +6,19 @@
 from tweepy.utils import parse_datetime
 
 
+#: All the potential fields for :class:`List` objects
+LIST_FIELDS = [
+    "created_at",
+    "description",
+    "follower_count",
+    "id",
+    "member_count",
+    "name",
+    "owner_id",
+    "private",
+]
+
+
 class List(HashableID, DataMapping):
     """The list object contains `Twitter Lists`_ metadata describing the
     referenced List. The List object is the primary object returned in the List

tweepy/media.py

@@ -5,6 +5,24 @@
 from tweepy.mixins import DataMapping
 
 
+#: All the potential fields for :class:`Media` objects
+MEDIA_FIELDS = [
+    "alt_text",
+    "duration_ms",
+    "height",
+    "media_key",
+    "non_public_metrics",
+    "organic_metrics",
+    "preview_image_url",
+    "promoted_metrics",
+    "public_metrics",
+    "type",
+    "url",
+    "variants",
+    "width",
+]
+
+
 class Media(DataMapping):
     """Media refers to any image, GIF, or video attached to a Tweet. The media
     object is not a primary object on any endpoint, but can be found and

tweepy/place.py

@@ -5,6 +5,19 @@
 from tweepy.mixins import DataMapping, HashableID
 
 
+#: All the potential fields for :class:`Place` objects
+PLACE_FIELDS = [
+    "contained_within",
+    "country",
+    "country_code",
+    "full_name",
+    "geo",
+    "id",
+    "name",
+    "place_type",
+]
+
+
 class Place(HashableID, DataMapping):
     """The place tagged in a Tweet is not a primary object on any endpoint, but
     can be found and expanded in the Tweet resource. 

tweepy/poll.py

@@ -6,6 +6,16 @@
 from tweepy.utils import parse_datetime
 
 
+#: All the potential fields for :class:`Poll` objects
+POLL_FIELDS = [
+    "duration_minutes",
+    "end_datetime",
+    "id",
+    "options",
+    "voting_status",
+]
+
+
 class Poll(HashableID, DataMapping):
     """A poll included in a Tweet is not a primary object on any endpoint, but
     can be found and expanded in the Tweet object. 

tweepy/space.py

@@ -6,6 +6,32 @@
 from tweepy.utils import parse_datetime
 
 
+#: All the potential publically-available fields for :class:`Space` objects
+PUBLIC_SPACE_FIELDS = [
+    "created_at",
+    "creator_id",
+    "ended_at",
+    "host_ids",
+    "id",
+    "invited_user_ids",
+    "is_ticketed",
+    "lang",
+    "participant_count",
+    "scheduled_start",
+    "speaker_ids",
+    "started_at",
+    "state",
+    "title",
+    "topic_ids",
+    "updated_at",
+]
+
+#: All the potential fields for :class:`Space` objects
+SPACE_FIELDS = PUBLIC_SPACE_FIELDS + [
+    "subscriber_count",
+]
+
+
 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

tweepy/tweet.py

@@ -8,6 +8,37 @@
 from tweepy.utils import parse_datetime
 
 
+#: All the potential publically-available fields for :class:`Tweet` objects
+PUBLIC_TWEET_FIELDS = [
+    "attachments",
+    "author_id",
+    "context_annotations",
+    "conversation_id",
+    "created_at",
+    "edit_controls",
+    "edit_history_tweet_ids",
+    "entities",
+    "geo",
+    "id",
+    "in_reply_to_user_id",
+    "lang",
+    "possibly_sensitive",
+    "public_metrics",
+    "referenced_tweets",
+    "reply_settings",
+    "source",
+    "text",
+    "withheld",
+]
+
+#: All the potential fields for :class:`Tweet` objects
+TWEET_FIELDS = PUBLIC_TWEET_FIELDS + [
+    "non_public_metrics",
+    "organic_metrics",
+    "promoted_metrics",
+]
+
+
 class Tweet(HashableID, DataMapping):
     """Tweets are the basic building block of all things Twitter. The Tweet
     object has a long list of ‘root-level’ fields, such as ``id``, ``text``,

tweepy/user.py

@@ -6,6 +6,26 @@
 from tweepy.utils import parse_datetime
 
 
+#: All the potential fields for :class:`User` objects
+USER_FIELDS = [
+    "created_at",
+    "description",
+    "entities",
+    "id",
+    "location",
+    "name",
+    "pinned_tweet_id",
+    "profile_image_url",
+    "protected",
+    "public_metrics",
+    "url",
+    "username",
+    "verified",
+    "verified_type",
+    "withheld",
+]
+
+
 class User(HashableID, DataMapping):
     """The user object contains Twitter user account metadata describing the
     referenced user. The user object is the primary object returned in the