3879 lines
146 KiB
Python
3879 lines
146 KiB
Python
# Tweepy
|
||
# Copyright 2009-2023 Joshua Roesslein
|
||
# See LICENSE for details.
|
||
|
||
from collections import namedtuple
|
||
import datetime
|
||
|
||
try:
|
||
from functools import cache
|
||
except ImportError: # Remove when support for Python 3.8 is dropped
|
||
from functools import lru_cache
|
||
cache = lru_cache(maxsize=None)
|
||
|
||
import logging
|
||
from platform import python_version
|
||
import time
|
||
import warnings
|
||
|
||
import requests
|
||
|
||
import tweepy
|
||
from tweepy.auth import OAuth1UserHandler
|
||
from tweepy.direct_message_event import DirectMessageEvent
|
||
from tweepy.errors import (
|
||
BadRequest, Forbidden, HTTPException, NotFound, TooManyRequests,
|
||
TwitterServerError, Unauthorized
|
||
)
|
||
from tweepy.list import List
|
||
from tweepy.media import Media
|
||
from tweepy.place import Place
|
||
from tweepy.poll import Poll
|
||
from tweepy.space import Space
|
||
from tweepy.tweet import Tweet
|
||
from tweepy.user import User
|
||
|
||
log = logging.getLogger(__name__)
|
||
|
||
Response = namedtuple("Response", ("data", "includes", "errors", "meta"))
|
||
|
||
|
||
class BaseClient:
|
||
|
||
def __init__(
|
||
self, bearer_token=None, consumer_key=None, consumer_secret=None,
|
||
access_token=None, access_token_secret=None, *, return_type=Response,
|
||
wait_on_rate_limit=False
|
||
):
|
||
self.bearer_token = bearer_token
|
||
self.consumer_key = consumer_key
|
||
self.consumer_secret = consumer_secret
|
||
self.access_token = access_token
|
||
self.access_token_secret = access_token_secret
|
||
|
||
self.return_type = return_type
|
||
self.wait_on_rate_limit = wait_on_rate_limit
|
||
|
||
self.session = requests.Session()
|
||
self.user_agent = (
|
||
f"Python/{python_version()} "
|
||
f"Requests/{requests.__version__} "
|
||
f"Tweepy/{tweepy.__version__}"
|
||
)
|
||
|
||
def request(self, method, route, params=None, json=None, user_auth=False):
|
||
host = "https://api.twitter.com"
|
||
headers = {"User-Agent": self.user_agent}
|
||
auth = None
|
||
if user_auth:
|
||
auth = OAuth1UserHandler(
|
||
self.consumer_key, self.consumer_secret,
|
||
self.access_token, self.access_token_secret
|
||
)
|
||
auth = auth.apply_auth()
|
||
else:
|
||
headers["Authorization"] = f"Bearer {self.bearer_token}"
|
||
|
||
log.debug(
|
||
f"Making API request: {method} {host + route}\n"
|
||
f"Parameters: {params}\n"
|
||
f"Headers: {headers}\n"
|
||
f"Body: {json}"
|
||
)
|
||
|
||
with self.session.request(
|
||
method, host + route, params=params, json=json, headers=headers,
|
||
auth=auth
|
||
) as response:
|
||
log.debug(
|
||
"Received API response: "
|
||
f"{response.status_code} {response.reason}\n"
|
||
f"Headers: {response.headers}\n"
|
||
f"Content: {response.content}"
|
||
)
|
||
|
||
if response.status_code == 400:
|
||
raise BadRequest(response)
|
||
if response.status_code == 401:
|
||
raise Unauthorized(response)
|
||
if response.status_code == 403:
|
||
raise Forbidden(response)
|
||
if response.status_code == 404:
|
||
raise NotFound(response)
|
||
if response.status_code == 429:
|
||
if self.wait_on_rate_limit:
|
||
reset_time = int(response.headers["x-rate-limit-reset"])
|
||
sleep_time = reset_time - int(time.time()) + 1
|
||
if sleep_time > 0:
|
||
log.warning(
|
||
"Rate limit exceeded. "
|
||
f"Sleeping for {sleep_time} seconds."
|
||
)
|
||
time.sleep(sleep_time)
|
||
return self.request(method, route, params, json, user_auth)
|
||
else:
|
||
raise TooManyRequests(response)
|
||
if response.status_code >= 500:
|
||
raise TwitterServerError(response)
|
||
if not 200 <= response.status_code < 300:
|
||
raise HTTPException(response)
|
||
|
||
return response
|
||
|
||
def _make_request(
|
||
self, method, route, params={}, endpoint_parameters=(), json=None,
|
||
data_type=None, user_auth=False
|
||
):
|
||
request_params = self._process_params(params, endpoint_parameters)
|
||
|
||
response = self.request(method, route, params=request_params,
|
||
json=json, user_auth=user_auth)
|
||
|
||
if self.return_type is requests.Response:
|
||
return response
|
||
|
||
response = response.json()
|
||
|
||
if self.return_type is dict:
|
||
return response
|
||
|
||
return self._construct_response(response, data_type=data_type)
|
||
|
||
def _construct_response(self, response, data_type=None):
|
||
data = response.get("data")
|
||
data = self._process_data(data, data_type=data_type)
|
||
|
||
includes = response.get("includes", {})
|
||
includes = self._process_includes(includes)
|
||
|
||
errors = response.get("errors", [])
|
||
meta = response.get("meta", {})
|
||
|
||
return Response(data, includes, errors, meta)
|
||
|
||
def _process_data(self, data, data_type=None):
|
||
if data_type is not None:
|
||
if isinstance(data, list):
|
||
data = [data_type(result) for result in data]
|
||
elif data is not None:
|
||
data = data_type(data)
|
||
return data
|
||
|
||
def _process_includes(self, includes):
|
||
if "media" in includes:
|
||
includes["media"] = [Media(media) for media in includes["media"]]
|
||
if "places" in includes:
|
||
includes["places"] = [Place(place) for place in includes["places"]]
|
||
if "polls" in includes:
|
||
includes["polls"] = [Poll(poll) for poll in includes["polls"]]
|
||
if "tweets" in includes:
|
||
includes["tweets"] = [Tweet(tweet) for tweet in includes["tweets"]]
|
||
if "users" in includes:
|
||
includes["users"] = [User(user) for user in includes["users"]]
|
||
return includes
|
||
|
||
def _process_params(self, params, endpoint_parameters):
|
||
endpoint_parameters = {
|
||
endpoint_parameter.replace('.', '_'): endpoint_parameter
|
||
for endpoint_parameter in endpoint_parameters
|
||
}
|
||
|
||
request_params = {}
|
||
for param_name, param_value in params.items():
|
||
try:
|
||
param_name = endpoint_parameters[param_name]
|
||
except KeyError:
|
||
log.warn(f"Unexpected parameter: {param_name}")
|
||
|
||
if isinstance(param_value, list):
|
||
request_params[param_name] = ','.join(map(str, param_value))
|
||
elif isinstance(param_value, datetime.datetime):
|
||
if param_value.tzinfo is not None:
|
||
param_value = param_value.astimezone(datetime.timezone.utc)
|
||
request_params[param_name] = param_value.strftime(
|
||
"%Y-%m-%dT%H:%M:%SZ"
|
||
)
|
||
# TODO: Constant datetime format string?
|
||
elif param_value is not None:
|
||
request_params[param_name] = param_value
|
||
|
||
return request_params
|
||
|
||
|
||
class Client(BaseClient):
|
||
"""Client( \
|
||
bearer_token=None, consumer_key=None, consumer_secret=None, \
|
||
access_token=None, access_token_secret=None, *, return_type=Response, \
|
||
wait_on_rate_limit=False \
|
||
)
|
||
|
||
Twitter API v2 Client
|
||
|
||
.. versionadded:: 4.0
|
||
|
||
Parameters
|
||
----------
|
||
bearer_token : str | None
|
||
Twitter API OAuth 2.0 Bearer Token / Access Token
|
||
consumer_key : str | None
|
||
Twitter API OAuth 1.0a Consumer Key
|
||
consumer_secret : str | None
|
||
Twitter API OAuth 1.0a Consumer Secret
|
||
access_token : str | None
|
||
Twitter API OAuth 1.0a Access Token
|
||
access_token_secret : str | None
|
||
Twitter API OAuth 1.0a Access Token Secret
|
||
return_type : type[dict | requests.Response | Response]
|
||
Type to return from requests to the API
|
||
wait_on_rate_limit : bool
|
||
Whether to wait when rate limit is reached
|
||
|
||
Attributes
|
||
----------
|
||
session : requests.Session
|
||
Requests Session used to make requests to the API
|
||
user_agent : str
|
||
User agent used when making requests to the API
|
||
"""
|
||
|
||
def _get_authenticating_user_id(self, *, oauth_1=False):
|
||
if oauth_1:
|
||
if self.access_token is None:
|
||
raise TypeError(
|
||
"Access Token must be provided for OAuth 1.0a User Context"
|
||
)
|
||
else:
|
||
return self._get_oauth_1_authenticating_user_id(
|
||
self.access_token
|
||
)
|
||
else:
|
||
if self.bearer_token is None:
|
||
raise TypeError(
|
||
"Access Token must be provided for "
|
||
"OAuth 2.0 Authorization Code Flow with PKCE"
|
||
)
|
||
else:
|
||
return self._get_oauth_2_authenticating_user_id(
|
||
self.bearer_token
|
||
)
|
||
|
||
@cache
|
||
def _get_oauth_1_authenticating_user_id(self, access_token):
|
||
return access_token.partition('-')[0]
|
||
|
||
@cache
|
||
def _get_oauth_2_authenticating_user_id(self, access_token):
|
||
original_access_token = self.bearer_token
|
||
original_return_type = self.return_type
|
||
|
||
self.bearer_token = access_token
|
||
self.return_type = dict
|
||
user_id = self.get_me(user_auth=False)["data"]["id"]
|
||
|
||
self.bearer_token = original_access_token
|
||
self.return_type = original_return_type
|
||
|
||
return user_id
|
||
|
||
# Bookmarks
|
||
|
||
def remove_bookmark(self, tweet_id):
|
||
"""Allows a user or authenticated user ID to remove a Bookmark of a
|
||
Tweet.
|
||
|
||
.. note::
|
||
|
||
A request is made beforehand to Twitter's API to determine the
|
||
authenticating user's ID. This is cached and only done once per
|
||
:class:`Client` instance for each access token used.
|
||
|
||
.. versionadded:: 4.8
|
||
|
||
Parameters
|
||
----------
|
||
tweet_id : int | str
|
||
The ID of the Tweet that you would like the ``id`` to remove a
|
||
Bookmark of.
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/bookmarks/api-reference/delete-users-id-bookmarks-tweet_id
|
||
"""
|
||
id = self._get_authenticating_user_id()
|
||
route = f"/2/users/{id}/bookmarks/{tweet_id}"
|
||
|
||
return self._make_request(
|
||
"DELETE", route
|
||
)
|
||
|
||
def get_bookmarks(self, **params):
|
||
"""get_bookmarks( \
|
||
*, expansions=None, max_results=None, media_fields=None, \
|
||
pagination_token=None, place_fields=None, poll_fields=None, \
|
||
tweet_fields=None, user_fields=None \
|
||
)
|
||
|
||
Allows you to get an authenticated user's 800 most recent bookmarked
|
||
Tweets.
|
||
|
||
.. note::
|
||
|
||
A request is made beforehand to Twitter's API to determine the
|
||
authenticating user's ID. This is cached and only done once per
|
||
:class:`Client` instance for each access token used.
|
||
|
||
.. versionadded:: 4.8
|
||
|
||
Parameters
|
||
----------
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and 100. By default, each page will return 100
|
||
results.
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results. To return the next page, pass the ``next_token``
|
||
returned in your previous response. To go back one page, pass the
|
||
``previous_token`` returned in your previous response.
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/bookmarks/api-reference/get-users-id-bookmarks
|
||
"""
|
||
id = self._get_authenticating_user_id()
|
||
route = f"/2/users/{id}/bookmarks"
|
||
|
||
return self._make_request(
|
||
"GET", route, params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "max_results", "media.fields",
|
||
"pagination_token", "place.fields", "poll.fields",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=Tweet
|
||
)
|
||
|
||
def bookmark(self, tweet_id):
|
||
"""Causes the authenticating user to Bookmark the target Tweet provided
|
||
in the request body.
|
||
|
||
.. note::
|
||
|
||
A request is made beforehand to Twitter's API to determine the
|
||
authenticating user's ID. This is cached and only done once per
|
||
:class:`Client` instance for each access token used.
|
||
|
||
.. versionadded:: 4.8
|
||
|
||
Parameters
|
||
----------
|
||
tweet_id : int | str
|
||
The ID of the Tweet that you would like the user ``id`` to
|
||
Bookmark.
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/bookmarks/api-reference/post-users-id-bookmarks
|
||
"""
|
||
id = self._get_authenticating_user_id()
|
||
route = f"/2/users/{id}/bookmarks"
|
||
|
||
return self._make_request(
|
||
"POST", route, json={"tweet_id": str(tweet_id)}
|
||
)
|
||
|
||
# Hide replies
|
||
|
||
def hide_reply(self, id, *, user_auth=True):
|
||
"""Hides a reply to a Tweet.
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
Unique identifier of the Tweet to hide. The Tweet must belong to a
|
||
conversation initiated by the authenticating user.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/hide-replies/api-reference/put-tweets-id-hidden
|
||
"""
|
||
return self._make_request(
|
||
"PUT", f"/2/tweets/{id}/hidden", json={"hidden": True},
|
||
user_auth=user_auth
|
||
)
|
||
|
||
def unhide_reply(self, id, *, user_auth=True):
|
||
"""Unhides a reply to a Tweet.
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
Unique identifier of the Tweet to unhide. The Tweet must belong to
|
||
a conversation initiated by the authenticating user.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/hide-replies/api-reference/put-tweets-id-hidden
|
||
"""
|
||
return self._make_request(
|
||
"PUT", f"/2/tweets/{id}/hidden", json={"hidden": False},
|
||
user_auth=user_auth
|
||
)
|
||
|
||
# Likes
|
||
|
||
def unlike(self, tweet_id, *, user_auth=True):
|
||
"""Unlike a Tweet.
|
||
|
||
The request succeeds with no action when the user sends a request to a
|
||
user they're not liking the Tweet or have already unliked the Tweet.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
tweet_id : int | str
|
||
The ID of the Tweet that you would like to unlike.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/likes/api-reference/delete-users-id-likes-tweet_id
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/likes/{tweet_id}"
|
||
|
||
return self._make_request(
|
||
"DELETE", route, user_auth=user_auth
|
||
)
|
||
|
||
def get_liking_users(self, id, *, user_auth=False, **params):
|
||
"""get_liking_users( \
|
||
id, *, expansions=None, max_results=None, media_fields=None, \
|
||
pagination_token=None, place_fields=None, poll_fields=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=False \
|
||
)
|
||
|
||
Allows you to get information about a Tweet’s liking users.
|
||
|
||
.. versionchanged:: 4.6
|
||
Added ``max_results`` and ``pagination_token`` parameters
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
Tweet ID of the Tweet to request liking users of.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and 100. By default, each page will return 100
|
||
results.
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results. To return the next page, pass the ``next_token``
|
||
returned in your previous response. To go back one page, pass the
|
||
``previous_token`` returned in your previous response.
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/likes/api-reference/get-tweets-id-liking_users
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/tweets/{id}/liking_users", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "max_results", "media.fields",
|
||
"pagination_token", "place.fields", "poll.fields",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=User, user_auth=user_auth
|
||
)
|
||
|
||
def get_liked_tweets(self, id, *, user_auth=False, **params):
|
||
"""get_liked_tweets( \
|
||
id, *, expansions=None, max_results=None, media_fields=None, \
|
||
pagination_token=None, place_fields=None, poll_fields=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=False \
|
||
)
|
||
|
||
Allows you to get information about a user’s liked Tweets.
|
||
|
||
The Tweets returned by this endpoint count towards the Project-level
|
||
`Tweet cap`_.
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
User ID of the user to request liked Tweets for.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 5 and 100. By default, each page will return 100
|
||
results.
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results. To return the next page, pass the ``next_token``
|
||
returned in your previous response. To go back one page, pass the
|
||
``previous_token`` returned in your previous response.
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/likes/api-reference/get-users-id-liked_tweets
|
||
|
||
.. _Tweet cap: https://developer.twitter.com/en/docs/projects/overview#tweet-cap
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/users/{id}/liked_tweets", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "max_results", "media.fields",
|
||
"pagination_token", "place.fields", "poll.fields",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=Tweet, user_auth=user_auth
|
||
)
|
||
|
||
def like(self, tweet_id, *, user_auth=True):
|
||
"""Like a Tweet.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
tweet_id : int | str
|
||
The ID of the Tweet that you would like to Like.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/likes/api-reference/post-users-id-likes
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/likes"
|
||
|
||
return self._make_request(
|
||
"POST", route, json={"tweet_id": str(tweet_id)},
|
||
user_auth=user_auth
|
||
)
|
||
|
||
# Manage Tweets
|
||
|
||
def delete_tweet(self, id, *, user_auth=True):
|
||
"""Allows an authenticated user ID to delete a Tweet.
|
||
|
||
.. versionadded:: 4.3
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
The Tweet ID you are deleting.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/manage-tweets/api-reference/delete-tweets-id
|
||
"""
|
||
return self._make_request(
|
||
"DELETE", f"/2/tweets/{id}", user_auth=user_auth
|
||
)
|
||
|
||
def create_tweet(
|
||
self, *, direct_message_deep_link=None, for_super_followers_only=None,
|
||
place_id=None, media_ids=None, media_tagged_user_ids=None,
|
||
poll_duration_minutes=None, poll_options=None, quote_tweet_id=None,
|
||
exclude_reply_user_ids=None, in_reply_to_tweet_id=None,
|
||
reply_settings=None, text=None, user_auth=True
|
||
):
|
||
"""Creates a Tweet on behalf of an authenticated user.
|
||
|
||
.. versionadded:: 4.3
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
Parameters
|
||
----------
|
||
direct_message_deep_link : str | None
|
||
`Tweets a link directly to a Direct Message conversation`_ with an
|
||
account.
|
||
for_super_followers_only : bool | None
|
||
Allows you to Tweet exclusively for `Super Followers`_.
|
||
place_id : str | None
|
||
Place ID being attached to the Tweet for geo location.
|
||
media_ids : list[int | str] | None
|
||
A list of Media IDs being attached to the Tweet. This is only
|
||
required if the request includes the ``tagged_user_ids``.
|
||
media_tagged_user_ids : list[int | str] | None
|
||
A list of User IDs being tagged in the Tweet with Media. If the
|
||
user you're tagging doesn't have photo-tagging enabled, their names
|
||
won't show up in the list of tagged users even though the Tweet is
|
||
successfully created.
|
||
poll_duration_minutes : int | None
|
||
Duration of the poll in minutes for a Tweet with a poll. This is
|
||
only required if the request includes ``poll.options``.
|
||
poll_options : list[str] | None
|
||
A list of poll options for a Tweet with a poll.
|
||
quote_tweet_id : int | str | None
|
||
Link to the Tweet being quoted.
|
||
exclude_reply_user_ids : list[int | str] | None
|
||
A list of User IDs to be excluded from the reply Tweet thus
|
||
removing a user from a thread.
|
||
in_reply_to_tweet_id : int | str | None
|
||
Tweet ID of the Tweet being replied to. Please note that
|
||
``in_reply_to_tweet_id`` needs to be in the request if
|
||
``exclude_reply_user_ids`` is present.
|
||
reply_settings : str | None
|
||
`Settings`_ to indicate who can reply to the Tweet. Limited to
|
||
"mentionedUsers" and "following". If the field isn’t specified, it
|
||
will default to everyone.
|
||
text : str | None
|
||
Text of the Tweet being created. This field is required if
|
||
``media.media_ids`` is not present.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/manage-tweets/api-reference/post-tweets
|
||
|
||
.. _Tweets a link directly to a Direct Message conversation: https://business.twitter.com/en/help/campaign-editing-and-optimization/public-to-private-conversation.html
|
||
.. _Super Followers: https://help.twitter.com/en/using-twitter/super-follows
|
||
.. _Settings: https://blog.twitter.com/en_us/topics/product/2020/new-conversation-settings-coming-to-a-tweet-near-you
|
||
"""
|
||
json = {}
|
||
|
||
if direct_message_deep_link is not None:
|
||
json["direct_message_deep_link"] = direct_message_deep_link
|
||
|
||
if for_super_followers_only is not None:
|
||
json["for_super_followers_only"] = for_super_followers_only
|
||
|
||
if place_id is not None:
|
||
json["geo"] = {"place_id": place_id}
|
||
|
||
if media_ids is not None:
|
||
json["media"] = {
|
||
"media_ids": [str(media_id) for media_id in media_ids]
|
||
}
|
||
if media_tagged_user_ids is not None:
|
||
json["media"]["tagged_user_ids"] = [
|
||
str(media_tagged_user_id)
|
||
for media_tagged_user_id in media_tagged_user_ids
|
||
]
|
||
|
||
if poll_options is not None:
|
||
json["poll"] = {"options": poll_options}
|
||
if poll_duration_minutes is not None:
|
||
json["poll"]["duration_minutes"] = poll_duration_minutes
|
||
|
||
if quote_tweet_id is not None:
|
||
json["quote_tweet_id"] = str(quote_tweet_id)
|
||
|
||
if in_reply_to_tweet_id is not None:
|
||
json["reply"] = {"in_reply_to_tweet_id": str(in_reply_to_tweet_id)}
|
||
if exclude_reply_user_ids is not None:
|
||
json["reply"]["exclude_reply_user_ids"] = [
|
||
str(exclude_reply_user_id)
|
||
for exclude_reply_user_id in exclude_reply_user_ids
|
||
]
|
||
|
||
if reply_settings is not None:
|
||
json["reply_settings"] = reply_settings
|
||
|
||
if text is not None:
|
||
json["text"] = text
|
||
|
||
return self._make_request(
|
||
"POST", f"/2/tweets", json=json, user_auth=user_auth
|
||
)
|
||
|
||
# Quote Tweets
|
||
|
||
def get_quote_tweets(self, id, *, user_auth=False, **params):
|
||
"""get_quote_tweets( \
|
||
id, *, exclude=None, expansions=None, max_results=None, \
|
||
media_fields=None, pagination_token=None, place_fields=None, \
|
||
poll_fields=None, tweet_fields=None, user_fields=None, \
|
||
user_auth=False \
|
||
)
|
||
|
||
Returns Quote Tweets for a Tweet specified by the requested Tweet ID.
|
||
|
||
The Tweets returned by this endpoint count towards the Project-level
|
||
`Tweet cap`_.
|
||
|
||
.. versionadded:: 4.7
|
||
|
||
.. versionchanged:: 4.11
|
||
Added ``exclude`` parameter
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
Unique identifier of the Tweet to request.
|
||
exclude : list[str] | str | None
|
||
Comma-separated list of the types of Tweets to exclude from the
|
||
response.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
Specifies the number of Tweets to try and retrieve, up to a maximum
|
||
of 100 per distinct request. By default, 10 results are returned if
|
||
this parameter is not supplied. The minimum permitted value is 10.
|
||
It is possible to receive less than the ``max_results`` per request
|
||
throughout the pagination process.
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
pagination_token : str | None
|
||
This parameter is used to move forwards through 'pages' of results,
|
||
based on the value of the ``next_token``. The value used with the
|
||
parameter is pulled directly from the response provided by the API,
|
||
and should not be modified.
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/quote-tweets/api-reference/get-tweets-id-quote_tweets
|
||
|
||
.. _Tweet cap: https://developer.twitter.com/en/docs/projects/overview#tweet-cap
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/tweets/{id}/quote_tweets", params=params,
|
||
endpoint_parameters=(
|
||
"exclude", "expansions", "max_results", "media.fields",
|
||
"pagination_token", "place.fields", "poll.fields",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=Tweet, user_auth=user_auth
|
||
)
|
||
|
||
# Retweets
|
||
|
||
def unretweet(self, source_tweet_id, *, user_auth=True):
|
||
"""Allows an authenticated user ID to remove the Retweet of a Tweet.
|
||
|
||
The request succeeds with no action when the user sends a request to a
|
||
user they're not Retweeting the Tweet or have already removed the
|
||
Retweet of.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
source_tweet_id : int | str
|
||
The ID of the Tweet that you would like to remove the Retweet of.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/retweets/api-reference/delete-users-id-retweets-tweet_id
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/retweets/{source_tweet_id}"
|
||
|
||
return self._make_request(
|
||
"DELETE", route, user_auth=user_auth
|
||
)
|
||
|
||
def get_retweeters(self, id, *, user_auth=False, **params):
|
||
"""get_retweeters( \
|
||
id, *, expansions=None, max_results=None, media_fields=None, \
|
||
pagination_token=None, place_fields=None, poll_fields=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=False \
|
||
)
|
||
|
||
Allows you to get information about who has Retweeted a Tweet.
|
||
|
||
.. versionchanged:: 4.6
|
||
Added ``max_results`` and ``pagination_token`` parameters
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
Tweet ID of the Tweet to request Retweeting users of.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and 100. By default, each page will return 100
|
||
results.
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results. To return the next page, pass the ``next_token``
|
||
returned in your previous response. To go back one page, pass the
|
||
``previous_token`` returned in your previous response.
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/retweets/api-reference/get-tweets-id-retweeted_by
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/tweets/{id}/retweeted_by", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "max_results", "media.fields",
|
||
"pagination_token", "place.fields", "poll.fields",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=User, user_auth=user_auth
|
||
)
|
||
|
||
def retweet(self, tweet_id, *, user_auth=True):
|
||
"""Causes the user ID to Retweet the target Tweet.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
tweet_id : int | str
|
||
The ID of the Tweet that you would like to Retweet.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/retweets/api-reference/post-users-id-retweets
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/retweets"
|
||
|
||
return self._make_request(
|
||
"POST", route, json={"tweet_id": str(tweet_id)},
|
||
user_auth=user_auth
|
||
)
|
||
|
||
# Search Tweets
|
||
|
||
def search_all_tweets(self, query, **params):
|
||
"""search_all_tweets( \
|
||
query, *, end_time=None, expansions=None, max_results=None, \
|
||
media_fields=None, next_token=None, place_fields=None, \
|
||
poll_fields=None, since_id=None, sort_order=None, \
|
||
start_time=None, tweet_fields=None, until_id=None, \
|
||
user_fields=None \
|
||
)
|
||
|
||
This endpoint is only available to those users who have been approved
|
||
for the `Academic Research product track`_.
|
||
|
||
The full-archive search endpoint returns the complete history of public
|
||
Tweets matching a search query; since the first Tweet was created March
|
||
26, 2006.
|
||
|
||
The Tweets returned by this endpoint count towards the Project-level
|
||
`Tweet cap`_.
|
||
|
||
.. note::
|
||
|
||
By default, a request will return Tweets from up to 30 days ago if
|
||
the ``start_time`` parameter is not provided.
|
||
|
||
.. versionchanged:: 4.6
|
||
Added ``sort_order`` parameter
|
||
|
||
Parameters
|
||
----------
|
||
query : str
|
||
One query for matching Tweets. Up to 1024 characters.
|
||
end_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). Used with ``start_time``.
|
||
The newest, most recent UTC timestamp to which the Tweets will be
|
||
provided. Timestamp is in second granularity and is exclusive (for
|
||
example, 12:00:01 excludes the first second of the minute). If used
|
||
without ``start_time``, Tweets from 30 days before ``end_time``
|
||
will be returned by default. If not specified, ``end_time`` will
|
||
default to [now - 30 seconds].
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of search results to be returned by a request. A
|
||
number between 10 and the system limit (currently 500). By default,
|
||
a request response will return 10 results.
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
next_token : str | None
|
||
This parameter is used to get the next 'page' of results. The value
|
||
used with the parameter is pulled directly from the response
|
||
provided by the API, and should not be modified. You can learn more
|
||
by visiting our page on `pagination`_.
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
since_id : int | str | None
|
||
Returns results with a Tweet ID greater than (for example, more
|
||
recent than) the specified ID. The ID specified is exclusive and
|
||
responses will not include it. If included with the same request as
|
||
a ``start_time`` parameter, only ``since_id`` will be used.
|
||
sort_order : str | None
|
||
This parameter is used to specify the order in which you want the
|
||
Tweets returned. By default, a request will return the most recent
|
||
Tweets first (sorted by recency).
|
||
start_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp
|
||
from which the Tweets will be provided. Timestamp is in second
|
||
granularity and is inclusive (for example, 12:00:01 includes the
|
||
first second of the minute). By default, a request will return
|
||
Tweets from up to 30 days ago if you do not include this parameter.
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
until_id : int | str | None
|
||
Returns results with a Tweet ID less than (that is, older than) the
|
||
specified ID. Used with ``since_id``. The ID specified is exclusive
|
||
and responses will not include it.
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/search/api-reference/get-tweets-search-all
|
||
|
||
.. _Academic Research product track: https://developer.twitter.com/en/docs/projects/overview#product-track
|
||
.. _Tweet cap: https://developer.twitter.com/en/docs/projects/overview#tweet-cap
|
||
.. _pagination: https://developer.twitter.com/en/docs/twitter-api/tweets/search/integrate/paginate
|
||
"""
|
||
params["query"] = query
|
||
return self._make_request(
|
||
"GET", "/2/tweets/search/all", params=params,
|
||
endpoint_parameters=(
|
||
"end_time", "expansions", "max_results", "media.fields",
|
||
"next_token", "place.fields", "poll.fields", "query",
|
||
"since_id", "sort_order", "start_time", "tweet.fields",
|
||
"until_id", "user.fields"
|
||
), data_type=Tweet
|
||
)
|
||
|
||
def search_recent_tweets(self, query, *, user_auth=False, **params):
|
||
"""search_recent_tweets( \
|
||
query, *, end_time=None, expansions=None, max_results=None, \
|
||
media_fields=None, next_token=None, place_fields=None, \
|
||
poll_fields=None, since_id=None, sort_order=None, \
|
||
start_time=None, tweet_fields=None, until_id=None, \
|
||
user_fields=None, user_auth=False \
|
||
)
|
||
|
||
The recent search endpoint returns Tweets from the last seven days that
|
||
match a search query.
|
||
|
||
The Tweets returned by this endpoint count towards the Project-level
|
||
`Tweet cap`_.
|
||
|
||
.. versionchanged:: 4.6
|
||
Added ``sort_order`` parameter
|
||
|
||
Parameters
|
||
----------
|
||
query : str
|
||
One rule for matching Tweets. If you are using a
|
||
`Standard Project`_ at the Basic `access level`_, you can use the
|
||
basic set of `operators`_ and can make queries up to 512 characters
|
||
long. If you are using an `Academic Research Project`_ at the Basic
|
||
access level, you can use all available operators and can make
|
||
queries up to 1,024 characters long.
|
||
end_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The newest, most recent
|
||
UTC timestamp to which the Tweets will be provided. Timestamp is in
|
||
second granularity and is exclusive (for example, 12:00:01 excludes
|
||
the first second of the minute). By default, a request will return
|
||
Tweets from as recent as 30 seconds ago if you do not include this
|
||
parameter.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of search results to be returned by a request. A
|
||
number between 10 and 100. By default, a request response will
|
||
return 10 results.
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
next_token : str | None
|
||
This parameter is used to get the next 'page' of results. The value
|
||
used with the parameter is pulled directly from the response
|
||
provided by the API, and should not be modified.
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
since_id : int | str | None
|
||
Returns results with a Tweet ID greater than (that is, more recent
|
||
than) the specified ID. The ID specified is exclusive and responses
|
||
will not include it. If included with the same request as a
|
||
``start_time`` parameter, only ``since_id`` will be used.
|
||
sort_order : str | None
|
||
This parameter is used to specify the order in which you want the
|
||
Tweets returned. By default, a request will return the most recent
|
||
Tweets first (sorted by recency).
|
||
start_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp
|
||
(from most recent seven days) from which the Tweets will be
|
||
provided. Timestamp is in second granularity and is inclusive (for
|
||
example, 12:00:01 includes the first second of the minute). If
|
||
included with the same request as a ``since_id`` parameter, only
|
||
``since_id`` will be used. By default, a request will return Tweets
|
||
from up to seven days ago if you do not include this parameter.
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
until_id : int | str | None
|
||
Returns results with a Tweet ID less than (that is, older than) the
|
||
specified ID. The ID specified is exclusive and responses will not
|
||
include it.
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/search/api-reference/get-tweets-search-recent
|
||
|
||
.. _Tweet cap: https://developer.twitter.com/en/docs/projects/overview#tweet-cap
|
||
.. _Standard Project: https://developer.twitter.com/en/docs/projects
|
||
.. _access level: https://developer.twitter.com/en/products/twitter-api/early-access/guide.html#na_1
|
||
.. _operators: https://developer.twitter.com/en/docs/twitter-api/tweets/search/integrate/build-a-query
|
||
.. _Academic Research Project: https://developer.twitter.com/en/docs/projects
|
||
"""
|
||
params["query"] = query
|
||
return self._make_request(
|
||
"GET", "/2/tweets/search/recent", params=params,
|
||
endpoint_parameters=(
|
||
"end_time", "expansions", "max_results", "media.fields",
|
||
"next_token", "place.fields", "poll.fields", "query",
|
||
"since_id", "sort_order", "start_time", "tweet.fields",
|
||
"until_id", "user.fields"
|
||
), data_type=Tweet, user_auth=user_auth
|
||
)
|
||
|
||
# Timelines
|
||
|
||
def get_users_mentions(self, id, *, user_auth=False, **params):
|
||
"""get_users_mentions( \
|
||
id, *, end_time=None, expansions=None, max_results=None, \
|
||
media_fields=None, pagination_token=None, place_fields=None, \
|
||
poll_fields=None, since_id=None, start_time=None, \
|
||
tweet_fields=None, until_id=None, user_fields=None, \
|
||
user_auth=False \
|
||
)
|
||
|
||
Returns Tweets mentioning a single user specified by the requested user
|
||
ID. By default, the most recent ten Tweets are returned per request.
|
||
Using pagination, up to the most recent 800 Tweets can be retrieved.
|
||
|
||
The Tweets returned by this endpoint count towards the Project-level
|
||
`Tweet cap`_.
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
Unique identifier of the user for whom to return Tweets mentioning
|
||
the user. User ID can be referenced using the `user/lookup`_
|
||
endpoint. More information on Twitter IDs is `here`_.
|
||
end_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The new UTC timestamp
|
||
from which the Tweets will be provided. Timestamp is in second
|
||
granularity and is inclusive (for example, 12:00:01 includes the
|
||
first second of the minute).
|
||
|
||
Please note that this parameter does not support a millisecond
|
||
value.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
Specifies the number of Tweets to try and retrieve, up to a maximum
|
||
of 100 per distinct request. By default, 10 results are returned if
|
||
this parameter is not supplied. The minimum permitted value is 5.
|
||
It is possible to receive less than the ``max_results`` per request
|
||
throughout the pagination process.
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
pagination_token : str | None
|
||
This parameter is used to move forwards or backwards through
|
||
'pages' of results, based on the value of the ``next_token`` or
|
||
``previous_token`` in the response. The value used with the
|
||
parameter is pulled directly from the response provided by the API,
|
||
and should not be modified.
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
since_id : int | str | None
|
||
Returns results with a Tweet ID greater than (that is, more recent
|
||
than) the specified 'since' Tweet ID. There are limits to the
|
||
number of Tweets that can be accessed through the API. If the limit
|
||
of Tweets has occurred since the ``since_id``, the ``since_id``
|
||
will be forced to the oldest ID available. More information on
|
||
Twitter IDs is `here`_.
|
||
start_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp
|
||
from which the Tweets will be provided. Timestamp is in second
|
||
granularity and is inclusive (for example, 12:00:01 includes the
|
||
first second of the minute).
|
||
|
||
Please note that this parameter does not support a millisecond
|
||
value.
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
until_id : int | str | None
|
||
Returns results with a Tweet ID less less than (that is, older
|
||
than) the specified 'until' Tweet ID. There are limits to the
|
||
number of Tweets that can be accessed through the API. If the limit
|
||
of Tweets has occurred since the ``until_id``, the ``until_id``
|
||
will be forced to the most recent ID available. More information on
|
||
Twitter IDs is `here`_.
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/timelines/api-reference/get-users-id-mentions
|
||
|
||
.. _Tweet cap: https://developer.twitter.com/en/docs/projects/overview#tweet-cap
|
||
.. _user/lookup: https://developer.twitter.com/en/docs/twitter-api/users/lookup/introduction
|
||
.. _here: https://developer.twitter.com/en/docs/twitter-ids
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/users/{id}/mentions", params=params,
|
||
endpoint_parameters=(
|
||
"end_time", "expansions", "max_results", "media.fields",
|
||
"pagination_token", "place.fields", "poll.fields", "since_id",
|
||
"start_time", "tweet.fields", "until_id", "user.fields"
|
||
), data_type=Tweet, user_auth=user_auth
|
||
)
|
||
|
||
def get_home_timeline(self, *, user_auth=True, **params):
|
||
"""get_home_timeline( \
|
||
*, end_time=None, exclude=None, expansions=None, \
|
||
max_results=None, media_fields=None, pagination_token=None, \
|
||
place_fields=None, poll_fields=None, since_id=None, \
|
||
start_time=None, tweet_fields=None, until_id=None, \
|
||
user_fields=None, user_auth=True \
|
||
)
|
||
|
||
Allows you to retrieve a collection of the most recent Tweets and
|
||
Retweets posted by you and users you follow. This endpoint returns up
|
||
to the last 3200 Tweets.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
Parameters
|
||
----------
|
||
end_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The new UTC timestamp
|
||
from which the Tweets will be provided. Timestamp is in second
|
||
granularity and is inclusive (for example, 12:00:01 includes the
|
||
first second of the minute).
|
||
|
||
Please note that this parameter does not support a millisecond
|
||
value.
|
||
exclude : list[str] | str | None
|
||
Comma-separated list of the types of Tweets to exclude from the
|
||
response.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
Specifies the number of Tweets to try and retrieve, up to a maximum
|
||
of 100 per distinct request. By default, 100 results are returned
|
||
if this parameter is not supplied. The minimum permitted value is
|
||
1. It is possible to receive less than the ``max_results`` per
|
||
request throughout the pagination process.
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
pagination_token : str | None
|
||
This parameter is used to move forwards or backwards through
|
||
'pages' of results, based on the value of the ``next_token`` or
|
||
``previous_token`` in the response. The value used with the
|
||
parameter is pulled directly from the response provided by the API,
|
||
and should not be modified.
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
since_id : int | str | None
|
||
Returns results with a Tweet ID greater than (that is, more recent
|
||
than) the specified 'since' Tweet ID. There are limits to the
|
||
number of Tweets that can be accessed through the API. If the
|
||
limit of Tweets has occurred since the ``since_id``, the
|
||
``since_id`` will be forced to the oldest ID available. More
|
||
information on Twitter IDs is `here`_.
|
||
start_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp
|
||
from which the Tweets will be provided. Timestamp is in second
|
||
granularity and is inclusive (for example, 12:00:01 includes the
|
||
first second of the minute).
|
||
|
||
Please note that this parameter does not support a millisecond
|
||
value.
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
until_id : int | str | None
|
||
Returns results with a Tweet ID less than (that is, older than) the
|
||
specified 'until' Tweet ID. There are limits to the number of
|
||
Tweets that can be accessed through the API. If the limit of Tweets
|
||
has occurred since the ``until_id``, the ``until_id`` will be
|
||
forced to the most recent ID available. More information on Twitter
|
||
IDs is `here`_.
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/timelines/api-reference/get-users-id-reverse-chronological
|
||
|
||
.. _here: https://developer.twitter.com/en/docs/twitter-ids
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/timelines/reverse_chronological"
|
||
|
||
return self._make_request(
|
||
"GET", route, params=params,
|
||
endpoint_parameters=(
|
||
"end_time", "exclude", "expansions", "max_results",
|
||
"media.fields", "pagination_token", "place.fields",
|
||
"poll.fields", "since_id", "start_time", "tweet.fields",
|
||
"until_id", "user.fields"
|
||
), data_type=Tweet, user_auth=user_auth
|
||
)
|
||
|
||
def get_users_tweets(self, id, *, user_auth=False, **params):
|
||
"""get_users_tweets( \
|
||
id, *, end_time=None, exclude=None, expansions=None, \
|
||
max_results=None, media_fields=None, pagination_token=None, \
|
||
place_fields=None, poll_fields=None, since_id=None, \
|
||
start_time=None, tweet_fields=None, until_id=None, \
|
||
user_fields=None, user_auth=False \
|
||
)
|
||
|
||
Returns Tweets composed by a single user, specified by the requested
|
||
user ID. By default, the most recent ten Tweets are returned per
|
||
request. Using pagination, the most recent 3,200 Tweets can be
|
||
retrieved.
|
||
|
||
The Tweets returned by this endpoint count towards the Project-level
|
||
`Tweet cap`_.
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
Unique identifier of the Twitter account (user ID) for whom to
|
||
return results. User ID can be referenced using the `user/lookup`_
|
||
endpoint. More information on Twitter IDs is `here`_.
|
||
end_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The newest or most recent
|
||
UTC timestamp from which the Tweets will be provided. Only the 3200
|
||
most recent Tweets are available. Timestamp is in second
|
||
granularity and is inclusive (for example, 12:00:01 includes the
|
||
first second of the minute). Minimum allowable time is
|
||
2010-11-06T00:00:01Z
|
||
|
||
Please note that this parameter does not support a millisecond
|
||
value.
|
||
exclude : list[str] | str | None
|
||
Comma-separated list of the types of Tweets to exclude from the
|
||
response. When ``exclude=retweets`` is used, the maximum historical
|
||
Tweets returned is still 3200. When the ``exclude=replies``
|
||
parameter is used for any value, only the most recent 800 Tweets
|
||
are available.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
Specifies the number of Tweets to try and retrieve, up to a maximum
|
||
of 100 per distinct request. By default, 10 results are returned if
|
||
this parameter is not supplied. The minimum permitted value is 5.
|
||
It is possible to receive less than the ``max_results`` per request
|
||
throughout the pagination process.
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
pagination_token : str | None
|
||
This parameter is used to move forwards or backwards through
|
||
'pages' of results, based on the value of the ``next_token`` or
|
||
``previous_token`` in the response. The value used with the
|
||
parameter is pulled directly from the response provided by the API,
|
||
and should not be modified.
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
since_id : int | str | None
|
||
Returns results with a Tweet ID greater than (that is, more recent
|
||
than) the specified 'since' Tweet ID. Only the 3200 most recent
|
||
Tweets are available. The result will exclude the ``since_id``. If
|
||
the limit of Tweets has occurred since the ``since_id``, the
|
||
``since_id`` will be forced to the oldest ID available.
|
||
start_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest or earliest
|
||
UTC timestamp from which the Tweets will be provided. Only the 3200
|
||
most recent Tweets are available. Timestamp is in second
|
||
granularity and is inclusive (for example, 12:00:01 includes the
|
||
first second of the minute). Minimum allowable time is
|
||
2010-11-06T00:00:00Z
|
||
|
||
Please note that this parameter does not support a millisecond
|
||
value.
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
until_id : int | str | None
|
||
Returns results with a Tweet ID less less than (that is, older
|
||
than) the specified 'until' Tweet ID. Only the 3200 most recent
|
||
Tweets are available. The result will exclude the ``until_id``. If
|
||
the limit of Tweets has occurred since the ``until_id``, the
|
||
``until_id`` will be forced to the most recent ID available.
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/timelines/api-reference/get-users-id-tweets
|
||
|
||
.. _Tweet cap: https://developer.twitter.com/en/docs/projects/overview#tweet-cap
|
||
.. _user/lookup: https://developer.twitter.com/en/docs/twitter-api/users/lookup/introduction
|
||
.. _here: https://developer.twitter.com/en/docs/twitter-ids
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/users/{id}/tweets", params=params,
|
||
endpoint_parameters=(
|
||
"end_time", "exclude", "expansions", "max_results",
|
||
"media.fields", "pagination_token", "place.fields",
|
||
"poll.fields", "since_id", "start_time", "tweet.fields",
|
||
"until_id", "user.fields"
|
||
), data_type=Tweet, user_auth=user_auth
|
||
)
|
||
|
||
# Tweet counts
|
||
|
||
def get_all_tweets_count(self, query, **params):
|
||
"""get_all_tweets_count( \
|
||
query, *, end_time=None, granularity=None, next_token=None, \
|
||
since_id=None, start_time=None, until_id=None \
|
||
)
|
||
|
||
This endpoint is only available to those users who have been approved
|
||
for the `Academic Research product track`_.
|
||
|
||
The full-archive search endpoint returns the complete history of public
|
||
Tweets matching a search query; since the first Tweet was created March
|
||
26, 2006.
|
||
|
||
Parameters
|
||
----------
|
||
query : str
|
||
One query for matching Tweets. Up to 1024 characters.
|
||
end_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). Used with ``start_time``.
|
||
The newest, most recent UTC timestamp to which the Tweets will be
|
||
provided. Timestamp is in second granularity and is exclusive (for
|
||
example, 12:00:01 excludes the first second of the minute). If used
|
||
without ``start_time``, Tweets from 30 days before ``end_time``
|
||
will be returned by default. If not specified, ``end_time`` will
|
||
default to [now - 30 seconds].
|
||
granularity : str | None
|
||
This is the granularity that you want the timeseries count data to
|
||
be grouped by. You can request ``minute``, ``hour``, or ``day``
|
||
granularity. The default granularity, if not specified is ``hour``.
|
||
next_token : str | None
|
||
This parameter is used to get the next 'page' of results. The value
|
||
used with the parameter is pulled directly from the response
|
||
provided by the API, and should not be modified. You can learn more
|
||
by visiting our page on `pagination`_.
|
||
since_id : int | str | None
|
||
Returns results with a Tweet ID greater than (for example, more
|
||
recent than) the specified ID. The ID specified is exclusive and
|
||
responses will not include it. If included with the same request as
|
||
a ``start_time`` parameter, only ``since_id`` will be used.
|
||
start_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp
|
||
from which the Tweets will be provided. Timestamp is in second
|
||
granularity and is inclusive (for example, 12:00:01 includes the
|
||
first second of the minute). By default, a request will return
|
||
Tweets from up to 30 days ago if you do not include this parameter.
|
||
until_id : int | str | None
|
||
Returns results with a Tweet ID less than (that is, older than) the
|
||
specified ID. Used with ``since_id``. The ID specified is exclusive
|
||
and responses will not include it.
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/counts/api-reference/get-tweets-counts-all
|
||
|
||
.. _Academic Research product track: https://developer.twitter.com/en/docs/projects/overview#product-track
|
||
.. _pagination: https://developer.twitter.com/en/docs/twitter-api/tweets/search/integrate/paginate
|
||
"""
|
||
params["query"] = query
|
||
return self._make_request(
|
||
"GET", "/2/tweets/counts/all", params=params,
|
||
endpoint_parameters=(
|
||
"end_time", "granularity", "next_token", "query", "since_id",
|
||
"start_time", "until_id"
|
||
)
|
||
)
|
||
|
||
def get_recent_tweets_count(self, query, **params):
|
||
"""get_recent_tweets_count( \
|
||
query, *, end_time=None, granularity=None, since_id=None, \
|
||
start_time=None, until_id=None \
|
||
)
|
||
|
||
The recent Tweet counts endpoint returns count of Tweets from the last
|
||
seven days that match a search query.
|
||
|
||
Parameters
|
||
----------
|
||
query : str
|
||
One rule for matching Tweets. If you are using a
|
||
`Standard Project`_ at the Basic `access level`_, you can use the
|
||
basic set of `operators`_ and can make queries up to 512 characters
|
||
long. If you are using an `Academic Research Project`_ at the Basic
|
||
access level, you can use all available operators and can make
|
||
queries up to 1,024 characters long.
|
||
end_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The newest, most recent
|
||
UTC timestamp to which the Tweets will be provided. Timestamp is in
|
||
second granularity and is exclusive (for example, 12:00:01 excludes
|
||
the first second of the minute). By default, a request will return
|
||
Tweets from as recent as 30 seconds ago if you do not include this
|
||
parameter.
|
||
granularity : str | None
|
||
This is the granularity that you want the timeseries count data to
|
||
be grouped by. You can request ``minute``, ``hour``, or ``day``
|
||
granularity. The default granularity, if not specified is ``hour``.
|
||
since_id : int | str | None
|
||
Returns results with a Tweet ID greater than (that is, more recent
|
||
than) the specified ID. The ID specified is exclusive and responses
|
||
will not include it. If included with the same request as a
|
||
``start_time`` parameter, only ``since_id`` will be used.
|
||
start_time : datetime.datetime | str | None
|
||
YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339). The oldest UTC timestamp
|
||
(from most recent seven days) from which the Tweets will be
|
||
provided. Timestamp is in second granularity and is inclusive (for
|
||
example, 12:00:01 includes the first second of the minute). If
|
||
included with the same request as a ``since_id`` parameter, only
|
||
``since_id`` will be used. By default, a request will return Tweets
|
||
from up to seven days ago if you do not include this parameter.
|
||
until_id : int | str | None
|
||
Returns results with a Tweet ID less than (that is, older than) the
|
||
specified ID. The ID specified is exclusive and responses will not
|
||
include it.
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/counts/api-reference/get-tweets-counts-recent
|
||
|
||
.. _Standard Project: https://developer.twitter.com/en/docs/projects
|
||
.. _access level: https://developer.twitter.com/en/products/twitter-api/early-access/guide.html#na_1
|
||
.. _operators: https://developer.twitter.com/en/docs/twitter-api/tweets/search/integrate/build-a-query
|
||
.. _Academic Research Project: https://developer.twitter.com/en/docs/projects
|
||
"""
|
||
params["query"] = query
|
||
return self._make_request(
|
||
"GET", "/2/tweets/counts/recent", params=params,
|
||
endpoint_parameters=(
|
||
"end_time", "granularity", "query", "since_id", "start_time",
|
||
"until_id"
|
||
)
|
||
)
|
||
|
||
# Tweet lookup
|
||
|
||
def get_tweet(self, id, *, user_auth=False, **params):
|
||
"""get_tweet( \
|
||
id, *, expansions=None, media_fields=None, place_fields=None, \
|
||
poll_fields=None, tweet_fields=None, user_fields=None, \
|
||
user_auth=False \
|
||
)
|
||
|
||
Returns a variety of information about a single Tweet specified by
|
||
the requested ID.
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
Unique identifier of the Tweet to request
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/lookup/api-reference/get-tweets-id
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/tweets/{id}", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "media.fields", "place.fields", "poll.fields",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=Tweet, user_auth=user_auth
|
||
)
|
||
|
||
def get_tweets(self, ids, *, user_auth=False, **params):
|
||
"""get_tweets( \
|
||
ids, *, expansions=None, media_fields=None, place_fields=None, \
|
||
poll_fields=None, tweet_fields=None, user_fields=None, \
|
||
user_auth=False \
|
||
)
|
||
|
||
Returns a variety of information about the Tweet specified by the
|
||
requested ID or list of IDs.
|
||
|
||
Parameters
|
||
----------
|
||
ids : list[int | str] | str
|
||
A comma separated list of Tweet IDs. Up to 100 are allowed in a
|
||
single request. Make sure to not include a space between commas and
|
||
fields.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/tweets/lookup/api-reference/get-tweets
|
||
"""
|
||
params["ids"] = ids
|
||
return self._make_request(
|
||
"GET", "/2/tweets", params=params,
|
||
endpoint_parameters=(
|
||
"ids", "expansions", "media.fields", "place.fields",
|
||
"poll.fields", "tweet.fields", "user.fields"
|
||
), data_type=Tweet, user_auth=user_auth
|
||
)
|
||
|
||
# Blocks
|
||
|
||
def unblock(self, target_user_id, *, user_auth=True):
|
||
"""Unblock another user.
|
||
|
||
The request succeeds with no action when the user sends a request to a
|
||
user they're not blocking or have already unblocked.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
target_user_id : int | str
|
||
The user ID of the user that you would like to unblock.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/blocks/api-reference/delete-users-user_id-blocking
|
||
"""
|
||
source_user_id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{source_user_id}/blocking/{target_user_id}"
|
||
|
||
return self._make_request(
|
||
"DELETE", route, user_auth=user_auth
|
||
)
|
||
|
||
def get_blocked(self, *, user_auth=True, **params):
|
||
"""get_blocked( \
|
||
*, expansions=None, max_results=None, pagination_token=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=True \
|
||
)
|
||
|
||
Returns a list of users who are blocked by the authenticating user.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and 1000. By default, each page will return 100
|
||
results.
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results.
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/blocks/api-reference/get-users-blocking
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/blocking"
|
||
|
||
return self._make_request(
|
||
"GET", route, params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "max_results", "pagination_token",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=User, user_auth=user_auth
|
||
)
|
||
|
||
def block(self, target_user_id, *, user_auth=True):
|
||
"""Block another user.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
target_user_id : int | str
|
||
The user ID of the user that you would like to block.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/blocks/api-reference/post-users-user_id-blocking
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/blocking"
|
||
|
||
return self._make_request(
|
||
"POST", route, json={"target_user_id": str(target_user_id)},
|
||
user_auth=user_auth
|
||
)
|
||
|
||
# Follows
|
||
|
||
def unfollow_user(self, target_user_id, *, user_auth=True):
|
||
"""Allows a user ID to unfollow another user.
|
||
|
||
The request succeeds with no action when the authenticated user sends a
|
||
request to a user they're not following or have already unfollowed.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionchanged:: 4.2
|
||
Renamed from :meth:`Client.unfollow`
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
target_user_id : int | str
|
||
The user ID of the user that you would like to unfollow.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/delete-users-source_id-following
|
||
"""
|
||
source_user_id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{source_user_id}/following/{target_user_id}"
|
||
|
||
return self._make_request(
|
||
"DELETE", route, user_auth=user_auth
|
||
)
|
||
|
||
def unfollow(self, target_user_id, *, user_auth=True):
|
||
"""Alias for :meth:`Client.unfollow_user`
|
||
|
||
.. deprecated:: 4.2
|
||
Use :meth:`Client.unfollow_user` instead.
|
||
"""
|
||
warnings.warn(
|
||
"Client.unfollow is deprecated; use Client.unfollow_user instead.",
|
||
DeprecationWarning
|
||
)
|
||
return self.unfollow_user(target_user_id, user_auth=user_auth)
|
||
|
||
def get_users_followers(self, id, *, user_auth=False, **params):
|
||
"""get_users_followers( \
|
||
id, *, expansions=None, max_results=None, pagination_token=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=False \
|
||
)
|
||
|
||
Returns a list of users who are followers of the specified user ID.
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
The user ID whose followers you would like to retrieve.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and the 1000. By default, each page will return
|
||
100 results.
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results. To return the next page, pass the ``next_token``
|
||
returned in your previous response. To go back one page, pass the
|
||
``previous_token`` returned in your previous response.
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/get-users-id-followers
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/users/{id}/followers", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "max_results", "pagination_token",
|
||
"tweet.fields", "user.fields"
|
||
),
|
||
data_type=User, user_auth=user_auth
|
||
)
|
||
|
||
def get_users_following(self, id, *, user_auth=False, **params):
|
||
"""get_users_following( \
|
||
id, *, expansions=None, max_results=None, pagination_token=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=False \
|
||
)
|
||
|
||
Returns a list of users the specified user ID is following.
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
The user ID whose following you would like to retrieve.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and the 1000. By default, each page will return
|
||
100 results.
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results. To return the next page, pass the ``next_token``
|
||
returned in your previous response. To go back one page, pass the
|
||
``previous_token`` returned in your previous response.
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/get-users-id-following
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/users/{id}/following", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "max_results", "pagination_token",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=User, user_auth=user_auth
|
||
)
|
||
|
||
def follow_user(self, target_user_id, *, user_auth=True):
|
||
"""Allows a user ID to follow another user.
|
||
|
||
If the target user does not have public Tweets, this endpoint will send
|
||
a follow request.
|
||
|
||
The request succeeds with no action when the authenticated user sends a
|
||
request to a user they're already following, or if they're sending a
|
||
follower request to a user that does not have public Tweets.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionchanged:: 4.2
|
||
Renamed from :meth:`Client.follow`
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
target_user_id : int | str
|
||
The user ID of the user that you would like to follow.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/post-users-source_user_id-following
|
||
"""
|
||
source_user_id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{source_user_id}/following"
|
||
|
||
return self._make_request(
|
||
"POST", route, json={"target_user_id": str(target_user_id)},
|
||
user_auth=user_auth
|
||
)
|
||
|
||
def follow(self, target_user_id, *, user_auth=True):
|
||
"""Alias for :meth:`Client.follow_user`
|
||
|
||
.. deprecated:: 4.2
|
||
Use :meth:`Client.follow_user` instead.
|
||
"""
|
||
warnings.warn(
|
||
"Client.follow is deprecated; use Client.follow_user instead.",
|
||
DeprecationWarning
|
||
)
|
||
return self.follow_user(target_user_id, user_auth=user_auth)
|
||
|
||
# Mutes
|
||
|
||
def unmute(self, target_user_id, *, user_auth=True):
|
||
"""Allows an authenticated user ID to unmute the target user.
|
||
|
||
The request succeeds with no action when the user sends a request to a
|
||
user they're not muting or have already unmuted.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
target_user_id : int | str
|
||
The user ID of the user that you would like to unmute.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/mutes/api-reference/delete-users-user_id-muting
|
||
"""
|
||
source_user_id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{source_user_id}/muting/{target_user_id}"
|
||
|
||
return self._make_request(
|
||
"DELETE", route, user_auth=user_auth
|
||
)
|
||
|
||
def get_muted(self, *, user_auth=True, **params):
|
||
"""get_muted( \
|
||
*, expansions=None, max_results=None, pagination_token=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=True \
|
||
)
|
||
|
||
Returns a list of users who are muted by the authenticating user.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionadded:: 4.1
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and 1000. By default, each page will return 100
|
||
results.
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results.
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/mutes/api-reference/get-users-muting
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/muting"
|
||
|
||
return self._make_request(
|
||
"GET", route, params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "max_results", "pagination_token",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=User, user_auth=user_auth
|
||
)
|
||
|
||
def mute(self, target_user_id, *, user_auth=True):
|
||
"""Allows an authenticated user ID to mute the target user.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
target_user_id : int | str
|
||
The user ID of the user that you would like to mute.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/mutes/api-reference/post-users-user_id-muting
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/muting"
|
||
|
||
return self._make_request(
|
||
"POST", route, json={"target_user_id": str(target_user_id)},
|
||
user_auth=user_auth
|
||
)
|
||
|
||
# User lookup
|
||
|
||
def get_user(self, *, id=None, username=None, user_auth=False, **params):
|
||
"""get_user(*, id=None, username=None, expansions=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=False)
|
||
|
||
Returns a variety of information about a single user specified by the
|
||
requested ID or username.
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str | None
|
||
The ID of the user to lookup.
|
||
username : str | None
|
||
The Twitter username (handle) of the user.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If ID and username are not passed or both are passed
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-id
|
||
https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-by-username-username
|
||
"""
|
||
if id is not None and username is not None:
|
||
raise TypeError("Expected ID or username, not both")
|
||
|
||
route = "/2/users"
|
||
|
||
if id is not None:
|
||
route += f"/{id}"
|
||
elif username is not None:
|
||
route += f"/by/username/{username}"
|
||
else:
|
||
raise TypeError("ID or username is required")
|
||
|
||
return self._make_request(
|
||
"GET", route, params=params,
|
||
endpoint_parameters=("expansions", "tweet.fields", "user.fields"),
|
||
data_type=User, user_auth=user_auth
|
||
)
|
||
|
||
def get_users(self, *, ids=None, usernames=None, user_auth=False,
|
||
**params):
|
||
"""get_users(*, ids=None, usernames=None, expansions=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=False)
|
||
|
||
Returns a variety of information about one or more users specified by
|
||
the requested IDs or usernames.
|
||
|
||
Parameters
|
||
----------
|
||
ids : list[int | str] | str | None
|
||
A comma separated list of user IDs. Up to 100 are allowed in a
|
||
single request. Make sure to not include a space between commas and
|
||
fields.
|
||
usernames : list[str] | str | None
|
||
A comma separated list of Twitter usernames (handles). Up to 100
|
||
are allowed in a single request. Make sure to not include a space
|
||
between commas and fields.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If IDs and usernames are not passed or both are passed
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users
|
||
https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-by
|
||
"""
|
||
if ids is not None and usernames is not None:
|
||
raise TypeError("Expected IDs or usernames, not both")
|
||
|
||
route = "/2/users"
|
||
|
||
if ids is not None:
|
||
params["ids"] = ids
|
||
elif usernames is not None:
|
||
route += "/by"
|
||
params["usernames"] = usernames
|
||
else:
|
||
raise TypeError("IDs or usernames are required")
|
||
|
||
return self._make_request(
|
||
"GET", route, params=params,
|
||
endpoint_parameters=(
|
||
"ids", "usernames", "expansions", "tweet.fields", "user.fields"
|
||
), data_type=User, user_auth=user_auth
|
||
)
|
||
|
||
def get_me(self, *, user_auth=True, **params):
|
||
"""get_me(*, expansions=None, tweet_fields=None, user_fields=None, \
|
||
user_auth=True)
|
||
|
||
Returns information about an authorized user.
|
||
|
||
.. versionadded:: 4.5
|
||
|
||
Parameters
|
||
----------
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-me
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/users/me", params=params,
|
||
endpoint_parameters=("expansions", "tweet.fields", "user.fields"),
|
||
data_type=User, user_auth=user_auth
|
||
)
|
||
|
||
# Search Spaces
|
||
|
||
def search_spaces(self, query, **params):
|
||
"""search_spaces(query, *, expansions=None, max_results=None, \
|
||
space_fields=None, state=None, user_fields=None)
|
||
|
||
Return live or scheduled Spaces matching your specified search terms
|
||
|
||
.. versionadded:: 4.1
|
||
|
||
.. versionchanged:: 4.2
|
||
``state`` is now an optional parameter.
|
||
|
||
Parameters
|
||
----------
|
||
query : str
|
||
Your search term. This can be any text (including mentions and
|
||
Hashtags) present in the title of the Space.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to return in this request. Specify a
|
||
value between 1 and 100.
|
||
space_fields : list[str] | str | None
|
||
:ref:`space_fields_parameter`
|
||
state : str | None
|
||
Determines the type of results to return. This endpoint returns all
|
||
Spaces by default. Use ``live`` to only return live Spaces or
|
||
``scheduled`` to only return upcoming Spaces.
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/spaces/search/api-reference/get-spaces-search
|
||
"""
|
||
params["query"] = query
|
||
return self._make_request(
|
||
"GET", "/2/spaces/search", params=params,
|
||
endpoint_parameters=(
|
||
"query", "expansions", "max_results", "space.fields", "state",
|
||
"user.fields"
|
||
), data_type=Space
|
||
)
|
||
|
||
# Spaces lookup
|
||
|
||
def get_spaces(self, *, ids=None, user_ids=None, **params):
|
||
"""get_spaces(*, ids=None, user_ids=None, expansions=None, \
|
||
space_fields=None, user_fields=None)
|
||
|
||
Returns details about multiple live or scheduled Spaces (created by the
|
||
specified user IDs if specified). Up to 100 comma-separated Space or
|
||
user IDs can be looked up using this endpoint.
|
||
|
||
.. versionadded:: 4.1
|
||
|
||
Parameters
|
||
----------
|
||
ids : list[str] | str | None
|
||
A comma separated list of Spaces (up to 100).
|
||
user_ids : list[int | str] | str | None
|
||
A comma separated list of user IDs (up to 100).
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
space_fields : list[str] | str | None
|
||
:ref:`space_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If IDs and user IDs are not passed or both are passed
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces
|
||
https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-by-creator-ids
|
||
"""
|
||
if ids is not None and user_ids is not None:
|
||
raise TypeError("Expected IDs or user IDs, not both")
|
||
|
||
route = "/2/spaces"
|
||
|
||
if ids is not None:
|
||
params["ids"] = ids
|
||
elif user_ids is not None:
|
||
route += "/by/creator_ids"
|
||
params["user_ids"] = user_ids
|
||
else:
|
||
raise TypeError("IDs or user IDs are required")
|
||
|
||
return self._make_request(
|
||
"GET", route, params=params,
|
||
endpoint_parameters=(
|
||
"ids", "user_ids", "expansions", "space.fields", "user.fields"
|
||
), data_type=Space
|
||
)
|
||
|
||
def get_space(self, id, **params):
|
||
"""get_space(id, *, expansions=None, space_fields=None, \
|
||
user_fields=None)
|
||
|
||
Returns a variety of information about a single Space specified by the
|
||
requested ID.
|
||
|
||
.. versionadded:: 4.1
|
||
|
||
Parameters
|
||
----------
|
||
id : list[str] | str
|
||
Unique identifier of the Space to request.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
space_fields : list[str] | str | None
|
||
:ref:`space_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-id
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/spaces/{id}", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "space.fields", "user.fields"
|
||
), data_type=Space
|
||
)
|
||
|
||
def get_space_buyers(self, id, **params):
|
||
"""get_space_buyers( \
|
||
id, *, expansions=None, media_fields=None, place_fields=None, \
|
||
poll_fields=None, tweet_fields=None, user_fields=None \
|
||
)
|
||
|
||
Returns a list of user who purchased a ticket to the requested Space.
|
||
You must authenticate the request using the Access Token of the creator
|
||
of the requested Space.
|
||
|
||
.. versionadded:: 4.4
|
||
|
||
Parameters
|
||
----------
|
||
id : str
|
||
Unique identifier of the Space for which you want to request
|
||
Tweets.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-id-buyers
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/spaces/{id}/buyers", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "media.fields", "place.fields", "poll.fields",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=User
|
||
)
|
||
|
||
def get_space_tweets(self, id, **params):
|
||
"""get_space_tweets( \
|
||
id, *, expansions=None, media_fields=None, place_fields=None, \
|
||
poll_fields=None, tweet_fields=None, user_fields=None \
|
||
)
|
||
|
||
Returns Tweets shared in the requested Spaces.
|
||
|
||
.. versionadded:: 4.6
|
||
|
||
Parameters
|
||
----------
|
||
id : str
|
||
Unique identifier of the Space containing the Tweets you'd like to
|
||
access.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-id-tweets
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/spaces/{id}/tweets", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "media.fields", "place.fields", "poll.fields",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=Tweet
|
||
)
|
||
|
||
# Direct Messages lookup
|
||
|
||
def get_direct_message_events(
|
||
self, *, dm_conversation_id=None, participant_id=None, user_auth=True,
|
||
**params
|
||
):
|
||
"""get_direct_message_events( \
|
||
*, dm_conversation_id=None, participant_id=None, \
|
||
dm_event_fields=None, event_types=None, expansions=None, \
|
||
max_results=None, media_fields=None, pagination_token=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=True \
|
||
)
|
||
|
||
If ``dm_conversation_id`` is passed, returns a list of Direct Messages
|
||
within the conversation specified. Messages are returned in reverse
|
||
chronological order.
|
||
|
||
If ``participant_id`` is passed, returns a list of Direct Messages (DM)
|
||
events within a 1-1 conversation with the user specified. Messages are
|
||
returned in reverse chronological order.
|
||
|
||
If neither is passed, returns a list of Direct Messages for the
|
||
authenticated user, both sent and received. Direct Message events are
|
||
returned in reverse chronological order. Supports retrieving events
|
||
from the previous 30 days.
|
||
|
||
.. note::
|
||
|
||
There is an alias for this method named ``get_dm_events``.
|
||
|
||
.. versionadded:: 4.12
|
||
|
||
Parameters
|
||
----------
|
||
dm_conversation_id : str | None
|
||
The ``id`` of the Direct Message conversation for which events are
|
||
being retrieved.
|
||
participant_id : int | str | None
|
||
The ``participant_id`` of the user that the authenicating user is
|
||
having a 1-1 conversation with.
|
||
dm_event_fields : list[str] | str | None
|
||
Extra fields to include in the event payload. ``id`` and
|
||
``event_type`` are returned by default. The ``text`` value isn't
|
||
included for ``ParticipantsJoin`` and ``ParticipantsLeave`` events.
|
||
event_types : str
|
||
The type of Direct Message event to returm. If not included, all
|
||
types are returned.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned in a page. Must be
|
||
between 1 and 100. The default is 100.
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
pagination_token : str | None
|
||
Contains either the ``next_token`` or ``previous_token`` value.
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If both ``dm_conversation_id`` and ``participant_id`` are passed
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/direct-messages/lookup/api-reference/get-dm_events
|
||
https://developer.twitter.com/en/docs/twitter-api/direct-messages/lookup/api-reference/get-dm_conversations-with-participant_id-dm_events
|
||
https://developer.twitter.com/en/docs/twitter-api/direct-messages/lookup/api-reference/get-dm_conversations-dm_conversation_id-dm_events
|
||
"""
|
||
if dm_conversation_id is not None and participant_id is not None:
|
||
raise TypeError(
|
||
"Expected DM conversation ID or participant ID, not both"
|
||
)
|
||
elif dm_conversation_id is not None:
|
||
path = f"/2/dm_conversations/{dm_conversation_id}/dm_events"
|
||
elif participant_id is not None:
|
||
path = f"/2/dm_conversations/with/{participant_id}/dm_events"
|
||
else:
|
||
path = "/2/dm_events"
|
||
|
||
return self._make_request(
|
||
"GET", path, params=params,
|
||
endpoint_parameters=(
|
||
"dm_event.fields", "event_types", "expansions", "max_results",
|
||
"media.fields", "pagination_token", "tweet.fields",
|
||
"user.fields"
|
||
), data_type=DirectMessageEvent, user_auth=user_auth
|
||
)
|
||
|
||
get_dm_events = get_direct_message_events
|
||
|
||
# Manage Direct Messages
|
||
|
||
def create_direct_message(
|
||
self, *, dm_conversation_id=None, participant_id=None, media_id=None,
|
||
text=None, user_auth=True
|
||
):
|
||
"""If ``dm_conversation_id`` is passed, creates a Direct Message on
|
||
behalf of the authenticated user, and adds it to the specified
|
||
conversation.
|
||
|
||
If ``participant_id`` is passed, creates a one-to-one Direct Message
|
||
and adds it to the one-to-one conversation. This method either creates
|
||
a new one-to-one conversation or retrieves the current conversation and
|
||
adds the Direct Message to it.
|
||
|
||
.. note::
|
||
|
||
There is an alias for this method named ``create_dm``.
|
||
|
||
.. versionadded:: 4.12
|
||
|
||
Parameters
|
||
----------
|
||
dm_conversation_id : str | None
|
||
The ``dm_conversation_id`` of the conversation to add the Direct
|
||
Message to. Supports both 1-1 and group conversations.
|
||
participant_id : int | str | None
|
||
The User ID of the account this one-to-one Direct Message is to be
|
||
sent to.
|
||
media_id : int | str | None
|
||
A single Media ID being attached to the Direct Message. This field
|
||
is required if ``text`` is not present. For this launch, only 1
|
||
attachment is supported.
|
||
text : str | None
|
||
Text of the Direct Message being created. This field is required if
|
||
``media_id`` is not present. Text messages support up to 10,000
|
||
characters.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If ``dm_conversation_id`` and ``participant_id`` are not passed or
|
||
both are passed
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/direct-messages/manage/api-reference/post-dm_conversations-dm_conversation_id-messages
|
||
https://developer.twitter.com/en/docs/twitter-api/direct-messages/manage/api-reference/post-dm_conversations-with-participant_id-messages
|
||
"""
|
||
if dm_conversation_id is not None and participant_id is not None:
|
||
raise TypeError(
|
||
"Expected DM conversation ID or participant ID, not both"
|
||
)
|
||
elif dm_conversation_id is not None:
|
||
path = f"/2/dm_conversations/{dm_conversation_id}/messages"
|
||
elif participant_id is not None:
|
||
path = f"/2/dm_conversations/with/{participant_id}/messages"
|
||
else:
|
||
raise TypeError("DM conversation ID or participant ID is required")
|
||
|
||
json = {}
|
||
if media_id is not None:
|
||
json["attachments"] = [{"media_id": str(media_id)}]
|
||
if text is not None:
|
||
json["text"] = text
|
||
|
||
return self._make_request("POST", path, json=json, user_auth=user_auth)
|
||
|
||
create_dm = create_direct_message
|
||
|
||
def create_direct_message_conversation(
|
||
self, *, media_id=None, text=None, participant_ids, user_auth=True
|
||
):
|
||
"""Creates a new group conversation and adds a Direct Message to it on
|
||
behalf of the authenticated user.
|
||
|
||
.. note::
|
||
|
||
There is an alias for this method named ``create_dm_conversation``.
|
||
|
||
.. versionadded:: 4.12
|
||
|
||
Parameters
|
||
----------
|
||
media_id : int | str | None
|
||
A single Media ID being attached to the Direct Message. This field
|
||
is required if ``text`` is not present. For this launch, only 1
|
||
attachment is supported.
|
||
text : str | None
|
||
Text of the Direct Message being created. This field is required if
|
||
``media_id`` is not present. Text messages support up to 10,000
|
||
characters.
|
||
participant_ids : list[int | str]
|
||
An array of User IDs that the conversation is created with.
|
||
Conversations can have up to 50 participants.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/direct-messages/manage/api-reference/post-dm_conversations
|
||
"""
|
||
json = {
|
||
"conversation_type": "Group",
|
||
"message": {},
|
||
"participant_ids": list(map(str, participant_ids))
|
||
}
|
||
if media_id is not None:
|
||
json["message"]["attachments"] = [{"media_id": str(media_id)}]
|
||
if text is not None:
|
||
json["message"]["text"] = text
|
||
|
||
return self._make_request(
|
||
"POST", "/2/dm_conversations", json=json, user_auth=user_auth
|
||
)
|
||
|
||
create_dm_conversation = create_direct_message_conversation
|
||
|
||
# List Tweets lookup
|
||
|
||
def get_list_tweets(self, id, *, user_auth=False, **params):
|
||
"""get_list_tweets( \
|
||
id, *, expansions=None, max_results=None, media_fields=None, \
|
||
pagination_token=None, place_fields=None, poll_fields=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=False \
|
||
)
|
||
|
||
Returns a list of Tweets from the specified List.
|
||
|
||
.. versionadded:: 4.4
|
||
|
||
.. versionchanged:: 4.10.1
|
||
Added ``media_fields``, ``place_fields``, and ``poll_fields``
|
||
parameters
|
||
|
||
Parameters
|
||
----------
|
||
id : list[str] | str
|
||
The ID of the List whose Tweets you would like to retrieve.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and 100. By default, each page will return 100
|
||
results.
|
||
media_fields : list[str] | str | None
|
||
:ref:`media_fields_parameter`
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results. To return the next page, pass the next_token
|
||
returned in your previous response. To go back one page, pass the
|
||
previous_token returned in your previous response.
|
||
place_fields : list[str] | str | None
|
||
:ref:`place_fields_parameter`
|
||
poll_fields : list[str] | str | None
|
||
:ref:`poll_fields_parameter`
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/list-tweets/api-reference/get-lists-id-tweets
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/lists/{id}/tweets", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "max_results", "media.fields",
|
||
"pagination_token", "place.fields", "poll.fields",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=Tweet, user_auth=user_auth
|
||
)
|
||
|
||
# List follows
|
||
|
||
def unfollow_list(self, list_id, *, user_auth=True):
|
||
"""Enables the authenticated user to unfollow a List.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionadded:: 4.2
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
list_id : int | str
|
||
The ID of the List that you would like the user to unfollow.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/delete-users-id-followed-lists-list_id
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/followed_lists/{list_id}"
|
||
|
||
return self._make_request(
|
||
"DELETE", route, user_auth=user_auth
|
||
)
|
||
|
||
def get_list_followers(self, id, *, user_auth=False, **params):
|
||
"""get_list_followers( \
|
||
id, *, expansions=None, max_results=None, pagination_token=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=False \
|
||
)
|
||
|
||
Returns a list of users who are followers of the specified List.
|
||
|
||
.. versionadded:: 4.4
|
||
|
||
Parameters
|
||
----------
|
||
id : list[str] | str
|
||
The ID of the List whose followers you would like to retrieve.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and 100. By default, each page will return 100
|
||
results.
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results. To return the next page, pass the next_token
|
||
returned in your previous response. To go back one page, pass the
|
||
previous_token returned in your previous response.
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/get-lists-id-followers
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/lists/{id}/followers", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "max_results", "pagination_token",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=User, user_auth=user_auth
|
||
)
|
||
|
||
def get_followed_lists(self, id, *, user_auth=False, **params):
|
||
"""get_followed_lists( \
|
||
id, *, expansions=None, list_fields=None, max_results=None, \
|
||
pagination_token=None, user_fields=None, user_auth=False \
|
||
)
|
||
|
||
Returns all Lists a specified user follows.
|
||
|
||
.. versionadded:: 4.4
|
||
|
||
Parameters
|
||
----------
|
||
id : list[str] | str
|
||
The user ID whose followed Lists you would like to retrieve.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
list_fields : list[str] | str | None
|
||
:ref:`list_fields_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and 100. By default, each page will return 100
|
||
results.
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results. To return the next page, pass the next_token
|
||
returned in your previous response. To go back one page, pass the
|
||
previous_token returned in your previous response.
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/get-users-id-followed_lists
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/users/{id}/followed_lists", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "list.fields", "max_results", "pagination_token",
|
||
"user.fields"
|
||
), data_type=List, user_auth=user_auth
|
||
)
|
||
|
||
def follow_list(self, list_id, *, user_auth=True):
|
||
"""Enables the authenticated user to follow a List.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionadded:: 4.2
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
list_id : int | str
|
||
The ID of the List that you would like the user to follow.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/post-users-id-followed-lists
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/followed_lists"
|
||
|
||
return self._make_request(
|
||
"POST", route, json={"list_id": str(list_id)}, user_auth=user_auth
|
||
)
|
||
|
||
# List lookup
|
||
|
||
def get_list(self, id, *, user_auth=False, **params):
|
||
"""get_list(id, *, expansions=None, list_fields=None, \
|
||
user_fields=None, user_auth=False)
|
||
|
||
Returns the details of a specified List.
|
||
|
||
.. versionadded:: 4.4
|
||
|
||
Parameters
|
||
----------
|
||
id : list[str] | str
|
||
The ID of the List to lookup.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
list_fields : list[str] | str | None
|
||
:ref:`list_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/list-lookup/api-reference/get-lists-id
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/lists/{id}", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "list.fields", "user.fields"
|
||
), data_type=List, user_auth=user_auth
|
||
)
|
||
|
||
def get_owned_lists(self, id, *, user_auth=False, **params):
|
||
"""get_owned_lists( \
|
||
id, *, expansions=None, list_fields=None, max_results=None, \
|
||
pagination_token=None, user_fields=None, user_auth=False \
|
||
)
|
||
|
||
Returns all Lists owned by the specified user.
|
||
|
||
.. versionadded:: 4.4
|
||
|
||
Parameters
|
||
----------
|
||
id : list[str] | str
|
||
The user ID whose owned Lists you would like to retrieve.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
list_fields : list[str] | str | None
|
||
:ref:`list_fields_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and 100. By default, each page will return 100
|
||
results.
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results. To return the next page, pass the next_token
|
||
returned in your previous response. To go back one page, pass the
|
||
previous_token returned in your previous response.
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/list-lookup/api-reference/get-users-id-owned_lists
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/users/{id}/owned_lists", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "list.fields", "max_results", "pagination_token",
|
||
"user.fields"
|
||
), data_type=List, user_auth=user_auth
|
||
)
|
||
|
||
# List members
|
||
|
||
def remove_list_member(self, id, user_id, *, user_auth=True):
|
||
"""Enables the authenticated user to remove a member from a List they
|
||
own.
|
||
|
||
.. versionadded:: 4.2
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
The ID of the List you are removing a member from.
|
||
user_id : int | str
|
||
The ID of the user you wish to remove as a member of the List.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/delete-lists-id-members-user_id
|
||
"""
|
||
|
||
return self._make_request(
|
||
"DELETE", f"/2/lists/{id}/members/{user_id}", user_auth=user_auth
|
||
)
|
||
|
||
def get_list_members(self, id, *, user_auth=False, **params):
|
||
"""get_list_members( \
|
||
id, *, expansions=None, max_results=None, pagination_token=None, \
|
||
tweet_fields=None, user_fields=None, user_auth=False \
|
||
)
|
||
|
||
Returns a list of users who are members of the specified List.
|
||
|
||
.. versionadded:: 4.4
|
||
|
||
Parameters
|
||
----------
|
||
id : list[str] | str
|
||
The ID of the List whose members you would like to retrieve.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and 100. By default, each page will return 100
|
||
results.
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results. To return the next page, pass the next_token
|
||
returned in your previous response. To go back one page, pass the
|
||
previous_token returned in your previous response.
|
||
tweet_fields : list[str] | str | None
|
||
:ref:`tweet_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/get-lists-id-members
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/lists/{id}/members", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "max_results", "pagination_token",
|
||
"tweet.fields", "user.fields"
|
||
), data_type=User, user_auth=user_auth
|
||
)
|
||
|
||
def get_list_memberships(self, id, *, user_auth=False, **params):
|
||
"""get_list_memberships( \
|
||
id, *, expansions=None, list_fields=None, max_results=None, \
|
||
pagination_token=None, user_fields=None, user_auth=False \
|
||
)
|
||
|
||
Returns all Lists a specified user is a member of.
|
||
|
||
.. versionadded:: 4.4
|
||
|
||
Parameters
|
||
----------
|
||
id : list[str] | str
|
||
The user ID whose List memberships you would like to retrieve.
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
list_fields : list[str] | str | None
|
||
:ref:`list_fields_parameter`
|
||
max_results : int | None
|
||
The maximum number of results to be returned per page. This can be
|
||
a number between 1 and 100. By default, each page will return 100
|
||
results.
|
||
pagination_token : str | None
|
||
Used to request the next page of results if all results weren't
|
||
returned with the latest request, or to go back to the previous
|
||
page of results. To return the next page, pass the next_token
|
||
returned in your previous response. To go back one page, pass the
|
||
previous_token returned in your previous response.
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/get-users-id-list_memberships
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/users/{id}/list_memberships", params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "list.fields", "max_results", "pagination_token",
|
||
"user.fields"
|
||
), data_type=List, user_auth=user_auth
|
||
)
|
||
|
||
def add_list_member(self, id, user_id, *, user_auth=True):
|
||
"""Enables the authenticated user to add a member to a List they own.
|
||
|
||
.. versionadded:: 4.2
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
The ID of the List you are adding a member to.
|
||
user_id : int | str
|
||
The ID of the user you wish to add as a member of the List.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/post-lists-id-members
|
||
"""
|
||
return self._make_request(
|
||
"POST", f"/2/lists/{id}/members", json={"user_id": str(user_id)},
|
||
user_auth=user_auth
|
||
)
|
||
|
||
# Manage Lists
|
||
|
||
def delete_list(self, id, *, user_auth=True):
|
||
"""Enables the authenticated user to delete a List that they own.
|
||
|
||
.. versionadded:: 4.2
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
The ID of the List to be deleted.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/delete-lists-id
|
||
"""
|
||
|
||
return self._make_request(
|
||
"DELETE", f"/2/lists/{id}", user_auth=user_auth
|
||
)
|
||
|
||
def update_list(self, id, *, description=None, name=None, private=None,
|
||
user_auth=True):
|
||
"""Enables the authenticated user to update the meta data of a
|
||
specified List that they own.
|
||
|
||
.. versionadded:: 4.2
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
The ID of the List to be updated.
|
||
description : str | None
|
||
Updates the description of the List.
|
||
name : str | None
|
||
Updates the name of the List.
|
||
private : bool | None
|
||
Determines whether the List should be private.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/put-lists-id
|
||
"""
|
||
json = {}
|
||
|
||
if description is not None:
|
||
json["description"] = description
|
||
|
||
if name is not None:
|
||
json["name"] = name
|
||
|
||
if private is not None:
|
||
json["private"] = private
|
||
|
||
return self._make_request(
|
||
"PUT", f"/2/lists/{id}", json=json, user_auth=user_auth
|
||
)
|
||
|
||
def create_list(self, name, *, description=None, private=None,
|
||
user_auth=True):
|
||
"""Enables the authenticated user to create a List.
|
||
|
||
.. versionadded:: 4.2
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
Parameters
|
||
----------
|
||
name : str
|
||
The name of the List you wish to create.
|
||
description : str | None
|
||
Description of the List.
|
||
private : bool | None
|
||
Determine whether the List should be private.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/post-lists
|
||
"""
|
||
json = {"name": name}
|
||
|
||
if description is not None:
|
||
json["description"] = description
|
||
|
||
if private is not None:
|
||
json["private"] = private
|
||
|
||
return self._make_request(
|
||
"POST", f"/2/lists", json=json, user_auth=user_auth
|
||
)
|
||
|
||
# Pinned Lists
|
||
|
||
def unpin_list(self, list_id, *, user_auth=True):
|
||
"""Enables the authenticated user to unpin a List.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionadded:: 4.2
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
list_id : int | str
|
||
The ID of the List that you would like the user to unpin.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/pinned-lists/api-reference/delete-users-id-pinned-lists-list_id
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/pinned_lists/{list_id}"
|
||
|
||
return self._make_request(
|
||
"DELETE", route, user_auth=user_auth
|
||
)
|
||
|
||
def get_pinned_lists(self, *, user_auth=True, **params):
|
||
"""get_pinned_lists(*, expansions=None, list_fields=None, \
|
||
user_fields=None, user_auth=True)
|
||
|
||
Returns the Lists pinned by a specified user.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionadded:: 4.4
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
expansions : list[str] | str | None
|
||
:ref:`expansions_parameter`
|
||
list_fields : list[str] | str | None
|
||
:ref:`list_fields_parameter`
|
||
user_fields : list[str] | str | None
|
||
:ref:`user_fields_parameter`
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/pinned-lists/api-reference/get-users-id-pinned_lists
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/pinned_lists"
|
||
|
||
return self._make_request(
|
||
"GET", route, params=params,
|
||
endpoint_parameters=(
|
||
"expansions", "list.fields", "user.fields"
|
||
), data_type=List, user_auth=user_auth
|
||
)
|
||
|
||
def pin_list(self, list_id, *, user_auth=True):
|
||
"""Enables the authenticated user to pin a List.
|
||
|
||
.. note::
|
||
|
||
When using OAuth 2.0 Authorization Code Flow with PKCE with
|
||
``user_auth=False``, a request is made beforehand to Twitter's API
|
||
to determine the authenticating user's ID. This is cached and only
|
||
done once per :class:`Client` instance for each access token used.
|
||
|
||
.. versionadded:: 4.2
|
||
|
||
.. versionchanged:: 4.5
|
||
Added ``user_auth`` parameter
|
||
|
||
.. versionchanged:: 4.8
|
||
Added support for using OAuth 2.0 Authorization Code Flow with PKCE
|
||
|
||
.. versionchanged:: 4.8
|
||
Changed to raise :class:`TypeError` when the access token isn't set
|
||
|
||
Parameters
|
||
----------
|
||
list_id : int | str
|
||
The ID of the List that you would like the user to pin.
|
||
user_auth : bool
|
||
Whether or not to use OAuth 1.0a User Context to authenticate
|
||
|
||
Raises
|
||
------
|
||
TypeError
|
||
If the access token isn't set
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/lists/pinned-lists/api-reference/post-users-id-pinned-lists
|
||
"""
|
||
id = self._get_authenticating_user_id(oauth_1=user_auth)
|
||
route = f"/2/users/{id}/pinned_lists"
|
||
|
||
return self._make_request(
|
||
"POST", route, json={"list_id": str(list_id)}, user_auth=user_auth
|
||
)
|
||
|
||
# Batch Compliance
|
||
|
||
def get_compliance_jobs(self, type, **params):
|
||
"""get_compliance_jobs(type, *, status=None)
|
||
|
||
Returns a list of recent compliance jobs.
|
||
|
||
.. versionadded:: 4.1
|
||
|
||
Parameters
|
||
----------
|
||
type : str
|
||
Allows to filter by job type - either by tweets or user ID. Only
|
||
one filter (tweets or users) can be specified per request.
|
||
status : str | None
|
||
Allows to filter by job status. Only one filter can be specified
|
||
per request.
|
||
Default: ``all``
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/compliance/batch-compliance/api-reference/get-compliance-jobs
|
||
"""
|
||
params["type"] = type
|
||
return self._make_request(
|
||
"GET", "/2/compliance/jobs", params=params,
|
||
endpoint_parameters=("type", "status")
|
||
)
|
||
|
||
def get_compliance_job(self, id):
|
||
"""Get a single compliance job with the specified ID.
|
||
|
||
.. versionadded:: 4.1
|
||
|
||
Parameters
|
||
----------
|
||
id : int | str
|
||
The unique identifier for the compliance job you want to retrieve.
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/compliance/batch-compliance/api-reference/get-compliance-jobs-id
|
||
"""
|
||
return self._make_request(
|
||
"GET", f"/2/compliance/jobs/{id}"
|
||
)
|
||
|
||
def create_compliance_job(self, type, *, name=None, resumable=None):
|
||
"""Creates a new compliance job for Tweet IDs or user IDs.
|
||
|
||
A compliance job will contain an ID and a destination URL. The
|
||
destination URL represents the location that contains the list of IDs
|
||
consumed by your app.
|
||
|
||
You can run one batch job at a time.
|
||
|
||
.. versionadded:: 4.1
|
||
|
||
Parameters
|
||
----------
|
||
type : str
|
||
Specify whether you will be uploading tweet or user IDs. You can
|
||
either specify tweets or users.
|
||
name : str | None
|
||
A name for this job, useful to identify multiple jobs using a label
|
||
you define.
|
||
resumable : bool | None
|
||
Specifies whether to enable the upload URL with support for
|
||
resumable uploads. If true, this endpoint will return a pre-signed
|
||
URL with resumable uploads enabled.
|
||
|
||
Returns
|
||
-------
|
||
dict | requests.Response | Response
|
||
|
||
References
|
||
----------
|
||
https://developer.twitter.com/en/docs/twitter-api/compliance/batch-compliance/api-reference/post-compliance-jobs
|
||
"""
|
||
json = {"type": type}
|
||
|
||
if name is not None:
|
||
json["name"] = name
|
||
|
||
if resumable is not None:
|
||
json["resumable"] = resumable
|
||
|
||
return self._make_request(
|
||
"POST", "/2/compliance/jobs", json=json
|
||
)
|