[PR]

Models

`DirectMessageEvent`

class tweepy.DirectMessageEvent

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.

バージョン 4.12 で追加.

data

The JSON data representing the Direct Message event.

Type:: dict

id

The unique identifier of the event.

Type:: int

event_type

Describes the type of event. Three types are currently supported:

MessageCreate
ParticipantsJoin
ParticipantsLeave

Type:: str

text

The actual UTF-8 text of the Direct Message.

Type:: str | None

sender_id

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.

Type:: int | None

participant_ids

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.

Type:: list[int] | None

dm_conversation_id

The unique identifier of the conversation the event is apart of.

Type:: str | None

created_at

Creation time (UTC) of the Tweet.

Type:: datetime.datetime | None

referenced_tweets

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.

Type:: list[ReferencedTweet] | None

attachments

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.

Type:: dict | None

参照

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/dm-events

`List`

class tweepy.List

The list object contains Twitter Lists metadata describing the referenced List. The List object is the primary object returned in the List lookup endpoint. When requesting additional List fields on this endpoint, simply use the fields parameter list.fields.

At the moment, the List object cannot be found as a child object from any other data object. However, user objects can be found and expanded in the user resource. These objects are available for expansion by adding owner_id to the expansions query parameter. Use the expansion with the field parameter: list.fields when requesting additional fields to complete the primary List object and user.fields to complete the expansion object.

バージョン 4.4 で追加.

data

The JSON data representing the List.

Type:: dict

id

The unique identifier of this List.

Type:: str

name

The name of the List, as defined when creating the List.

Type:: str

created_at

The UTC datetime that the List was created on Twitter.

Type:: datetime.datetime | None

description

A brief description to let users know about the List.

Type:: str | None

follower_count

Shows how many users follow this List,

Type:: int | None

member_count

Shows how many members are part of this List.

Type:: int | None

private

Indicates if the List is private.

Type:: bool | None

owner_id

Unique identifier of this List's owner.

Type:: str | None

参照

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/lists

`Media`

class tweepy.Media

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 expanded in the Tweet object.

The object is available for expansion with ?expansions=attachments.media_keys to get the condensed object with only default fields. Use the expansion with the field parameter: media.fields when requesting additional fields to complete the object..

バージョン 4.0 で追加.

バージョン 4.5 で変更: Added url field

バージョン 4.12 で変更: Added variants field

data

The JSON data representing the media.

Type:: dict

media_key

Unique identifier of the expanded media content.

Type:: str

type

Type of content (animated_gif, photo, video).

Type:: str

url

A direct URL to the media file on Twitter.

Type:: str | None

duration_ms

Available when type is video. Duration in milliseconds of the video.

Type:: int | None

height

Height of this content in pixels.

Type:: int | None

non_public_metrics

Non-public engagement metrics for the media content at the time of the request.

Requires user context authentication.

Type:: dict | None

organic_metrics

Engagement metrics for the media content, tracked in an organic context, at the time of the request.

Requires user context authentication.

Type:: dict | None

preview_image_url

URL to the static placeholder preview of this content.

Type:: str | None

promoted_metrics

Engagement metrics for the media content, tracked in a promoted context, at the time of the request.

Requires user context authentication.

Type:: dict | None

public_metrics

Public engagement metrics for the media content at the time of the request.

Type:: dict | None

width

Width of this content in pixels.

Type:: int | None

alt_text

A description of an image to enable and support accessibility. Can be up to 1000 characters long. Alt text can only be added to images at the moment.

Type:: str | None

variants

Each media object may have multiple display or playback variants, with different resolutions or formats

Type:: list[dict] | None

参照

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/media

`Place`

class tweepy.Place

The place tagged in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet resource.

The object is available for expansion with ?expansions=geo.place_id to get the condensed object with only default fields. Use the expansion with the field parameter: place.fields when requesting additional fields to complete the object.

バージョン 4.0 で追加.

data

The JSON data representing the place.

Type:: dict

full_name

A longer-form detailed place name.

Type:: str

id

The unique identifier of the expanded place, if this is a point of interest tagged in the Tweet.

Type:: str

contained_within

Returns the identifiers of known places that contain the referenced place.

Type:: list

country

The full-length name of the country this place belongs to.

Type:: str | None

country_code

The ISO Alpha-2 country code this place belongs to.

Type:: str | None

geo

Contains place details in GeoJSON format.

Type:: dict | None

name

The short name of this place.

Type:: str | None

place_type

Specified the particular type of information represented by this place information, such as a city name, or a point of interest.

Type:: str | None

参照

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/place

`Poll`

class tweepy.Poll

A poll included in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet object.

The object is available for expansion with ?expansions=attachments.poll_ids to get the condensed object with only default fields. Use the expansion with the field parameter: poll.fields when requesting additional fields to complete the object.

バージョン 4.0 で追加.

data

The JSON data representing the poll.

Type:: dict

id

Unique identifier of the expanded poll.

Type:: str

options

Contains objects describing each choice in the referenced poll.

Type:: list

duration_minutes

Specifies the total duration of this poll.

Type:: int | None

end_datetime

Specifies the end date and time for this poll.

Type:: datetime.datetime | None

voting_status

Indicates if this poll is still active and can receive votes, or if the voting is now closed.

Type:: str | None

参照

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/poll

`Space`

class tweepy.Space

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.

バージョン 4.1 で追加.

バージョン 4.4 で変更: Added ended_at and topic_ids fields

バージョン 4.6 で変更: Added subscriber_count field

data

The JSON data representing the Space.

Type:: dict

id

The unique identifier of the requested Space.

Type:: str

state

Indicates if the Space has started or will start in the future, or if it has ended.

Type:: str

created_at

Creation time of this Space.

Type:: datetime.datetime | None

ended_at

Time when the Space was ended. Only available for ended Spaces.

Type:: datetime.datetime | None

host_ids

The unique identifier of the users who are hosting this Space.

Type:: list

lang

Language of the Space, if detected by Twitter. Returned as a BCP47 language tag.

Type:: str | None

is_ticketed

Indicates is this is a ticketed Space.

Type:: bool | None

invited_user_ids

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.

Type:: list

participant_count

The current number of users in the Space, including Hosts and Speakers.

Type:: int | None

subscriber_count

The number of people who set a reminder to a Space.

Type:: int | None

scheduled_start

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.

Type:: datetime.datetime | None

speaker_ids

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.

Type:: list

started_at

Indicates the actual start time of a Space.

Type:: datetime.datetime | None

title

The title of the Space as specified by the creator.

Type:: str | None

topic_ids

A list of IDs of the topics selected by the creator of the Space.

Type:: list

updated_at

Specifies the date and time of the last update to any of the Space's metadata, such as its title or scheduled time.

Type:: datetime.datetime | None

参照

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/space

`Tweet`

class tweepy.Tweet

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, and created_at. Tweet objects are also the ‘parent’ object to several child objects including user, media, poll, and place. Use the field parameter tweet.fields when requesting these root-level fields on the Tweet object.

The Tweet object that can be found and expanded in the user resource. Additional Tweets related to the requested Tweet can also be found and expanded in the Tweet resource. The object is available for expansion with ?expansions=pinned_tweet_id in the user resource or ?expansions=referenced_tweets.id in the Tweet resource to get the object with only default fields. Use the expansion with the field parameter: tweet.fields when requesting additional fields to complete the object.

バージョン 4.0 で追加.

バージョン 4.11 で変更: Added edit_history_tweet_ids and edit_controls fields

data

The JSON data representing the Tweet.

Type:: dict

id

The unique identifier of the requested Tweet.

Type:: int

text

The actual UTF-8 text of the Tweet. See twitter-text for details on what characters are currently considered valid.

Type:: str

edit_history_tweet_ids

Unique identifiers indicating all versions of a Tweet. For Tweets with no edits, there will be one ID. For Tweets with an edit history, there will be multiple IDs, arranged in ascending order reflecting the order of edits. The most recent version is the last position of the array.

Type:: list[int]

attachments

Specifies the type of attachments (if any) present in this Tweet.

Type:: dict | None

author_id

The unique identifier of the User who posted this Tweet.

Type:: int | None

context_annotations

Contains context annotations for the Tweet.

Type:: list

conversation_id

The Tweet ID of the original Tweet of the conversation (which includes direct replies, replies of replies).

Type:: int | None

created_at

Creation time of the Tweet.

Type:: datetime.datetime | None

edit_controls

When present, this indicates how much longer the Tweet can be edited and the number of remaining edits. Tweets are only editable for the first 30 minutes after creation and can be edited up to five times.

Type:: dict | None

entities

Entities which have been parsed out of the text of the Tweet. Additionally see entities in Twitter Objects.

Type:: dict | None

geo

Contains details about the location tagged by the user in this Tweet, if they specified one.

Type:: dict | None

in_reply_to_user_id

If the represented Tweet is a reply, this field will contain the original Tweet’s author ID. This will not necessarily always be the user directly mentioned in the Tweet.

Type:: int | None

lang

Language of the Tweet, if detected by Twitter. Returned as a BCP47 language tag.

Type:: str | None

non_public_metrics

Non-public engagement metrics for the Tweet at the time of the request.

Requires user context authentication.

Type:: dict | None

organic_metrics

Engagement metrics, tracked in an organic context, for the Tweet at the time of the request.

Requires user context authentication.

Type:: dict | None

possibly_sensitive

This field only surfaces when a Tweet contains a link. The meaning of the field doesn’t pertain to the Tweet content itself, but instead it is an indicator that the URL contained in the Tweet may contain content or media identified as sensitive content.

Type:: bool | None

promoted_metrics

Engagement metrics, tracked in a promoted context, for the Tweet at the time of the request.

Requires user context authentication.

Type:: dict | None

public_metrics

Public engagement metrics for the Tweet at the time of the request.

Type:: dict | None

referenced_tweets

A list of Tweets this Tweet refers to. For example, if the parent Tweet is a Retweet, a Retweet with comment (also known as Quoted Tweet) or a Reply, it will include the related Tweet referenced to by its parent.

Type:: list[ReferencedTweet] | None

reply_settings

Shows you who can reply to a given Tweet. Fields returned are "everyone", "mentioned_users", and "followers".

Type:: str | None

source

The name of the app the user Tweeted from.

Type:: str | None

withheld

When present, contains withholding details for withheld content.

Type:: dict | None

参照

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/tweet

class tweepy.ReferencedTweet

バージョン 4.0 で追加.

バージョン 4.12 で変更: Changed type to be optional

data

The JSON data representing the referenced Tweet.

Type:: dict

id

The unique identifier of the referenced Tweet.

Type:: int

type

Type:: str | None

参照

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/tweet

`User`

class tweepy.User

The user object contains Twitter user account metadata describing the referenced user. The user object is the primary object returned in the users lookup endpoint. When requesting additional user fields on this endpoint, simply use the fields parameter user.fields.

The user object can also be found as a child object and expanded in the Tweet object. The object is available for expansion with ?expansions=author_id or ?expansions=in_reply_to_user_id to get the condensed object with only default fields. Use the expansion with the field parameter: user.fields when requesting additional fields to complete the object.

バージョン 4.0 で追加.

data

The JSON data representing the user.

Type:: dict

id

The unique identifier of this user.

Type:: int

name

The name of the user, as they’ve defined it on their profile. Not necessarily a person’s name. Typically capped at 50 characters, but subject to change.

Type:: str

username

The Twitter screen name, handle, or alias that this user identifies themselves with. Usernames are unique but subject to change. Typically a maximum of 15 characters long, but some historical accounts may exist with longer names.

Type:: str

created_at

The UTC datetime that the user account was created on Twitter.

Type:: datetime.datetime | None

description

The text of this user's profile description (also known as bio), if the user provided one.

Type:: str | None

entities

Contains details about text that has a special meaning in the user's description.

Type:: dict | None

location

The location specified in the user's profile, if the user provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries.

Type:: str | None

pinned_tweet_id

Unique identifier of this user's pinned Tweet.

Type:: int | None

profile_image_url

The URL to the profile image for this user, as shown on the user's profile.

Type:: str | None

protected

Indicates if this user has chosen to protect their Tweets (in other words, if this user's Tweets are private).

Type:: bool | None

public_metrics

Contains details about activity for this user.

Type:: dict | None

url

The URL specified in the user's profile, if present.

Type:: str | None

verified

Indicates if this user is a verified Twitter User.

Type:: bool | None

withheld

Contains withholding details for withheld content, if applicable.

Type:: dict | None

参照

https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/user