class Client:
- """
+ """Twitter API v2 Client
+
Parameters
----------
- bearer_token: Optional[:class:`str`]
- Bearer token
- consumer_key: Optional[:class:`str`]
- Consumer key
- consumer_secret: Optional[:class:`str`]
- Consuemr secret
- access_token: Optional[:class:`str`]
- Access token
- access_token_secret: Optional[:class:`str`]
- Access token secret
- wait_on_rate_limit: Optional[:class:`bool`]
- Whether to wait when rate limit is exceeded
- Defaults to False
+ bearer_token : Optional[str]
+ Twitter API Bearer Token
+ consumer_key : Optional[str]
+ Twitter API Consumer Key
+ consumer_secret : Optional[str]
+ Twitter API Consumer Secret
+ access_token : Optional[str]
+ Twitter API Access Token
+ access_token_secret : Optional[str]
+ Twitter API Access Token Secret
+ 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 __init__(self, bearer_token=None, consumer_key=None,
return Response(data, includes, errors, meta)
- def follow(self, target_user_id):
- """
- Follow user
- https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/post-users-source_user_id-following
+ # Hide replies
+
+ def hide_reply(self, id):
+ """Hides a reply to a Tweet.
+
+ Parameters
+ ----------
+ id : Union[int, str]
+ Unique identifier of the Tweet to hide. The Tweet must belong to a
+ conversation initiated by the authenticating user.
+
+ Returns
+ -------
+ bool
+ Indicates if the Tweet was successfully hidden.
+
+ References
+ ----------
+ https://developer.twitter.com/en/docs/twitter-api/tweets/hide-replies/api-reference/put-tweets-id-hidden
"""
- source_user_id = self.access_token.partition('-')[0]
- route = f"/2/users/{source_user_id}/following"
+ return self._make_request(
+ "PUT", f"/2/tweets/{id}/hidden", json={"hidden": True},
+ user_auth=True
+ )[0]["hidden"]
+
+ def unhide_reply(self, tweet_id):
+ """Unhides a reply to a Tweet.
+
+ Parameters
+ ----------
+ id : Union[int, str]
+ Unique identifier of the Tweet to unhide. The Tweet must belong to
+ a conversation initiated by the authenticating user.
+ Returns
+ -------
+ bool
+ Indicates if the Tweet was successfully unhidden.
+
+ References
+ ----------
+ https://developer.twitter.com/en/docs/twitter-api/tweets/hide-replies/api-reference/put-tweets-id-hidden
+ """
return self._make_request(
- "POST", route, json={"target_user_id": str(target_user_id)},
+ "PUT", f"/2/tweets/{tweet_id}/hidden", json={"hidden": False},
user_auth=True
+ )[0]["hidden"]
+
+ # Search Tweets
+
+ def search_all_tweets(self, query, **params):
+ """search_all_tweets( \
+ query, *, end_time, expansions, max_results, media_fields, \
+ next_token, place_fields, poll_fields, since_id, start_time, \
+ tweet_fields, until_id, user_fields \
)
- def get_tweet(self, id, *, user_auth=False, **params):
+ 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`_.
+
+ Parameters
+ ----------
+ query : str
+ One query for matching Tweets. Up to 1024 characters.
+ end_time : Union[datetime.datetime, str]
+ 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 : Union[List[str], str]
+ :ref:`expansions_parameter`
+ max_results : int
+ 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 : Union[List[str], str]
+ :ref:`media_fields_parameter`
+ next_token : str
+ 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 : Union[List[str], str]
+ :ref:`place_fields_parameter`
+ poll_fields : Union[List[str], str]
+ :ref:`poll_fields_parameter`
+ since_id : Union[int, str]
+ 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 : Union[datetime.datetime, str]
+ 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 : Union[List[str], str]
+ :ref:`tweet_fields_parameter`
+ until_id : Union[int, str]
+ 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 : Union[List[str], str]
+ :ref:`user_fields_parameter`
+
+ Returns
+ -------
+ 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", "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, *, user_auth=False, end_time, expansions, max_results, \
+ media_fields, next_token, place_fields, poll_fields, since_id, \
+ start_time, tweet_fields, until_id, user_fields \
+ )
+
+ 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`_.
+
+ 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 : Union[datetime.datetime, str]
+ 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 : Union[List[str], str]
+ :ref:`expansions_parameter`
+ max_results : int
+ 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 : Union[List[str], str]
+ :ref:`media_fields_parameter`
+ next_token : str
+ 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 : Union[List[str], str]
+ :ref:`place_fields_parameter`
+ poll_fields : Union[List[str], str]
+ :ref:`poll_fields_parameter`
+ since_id : Union[int, str]
+ 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 : Union[datetime.datetime, str]
+ 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 : Union[List[str], str]
+ :ref:`tweet_fields_parameter`
+ until_id : Union[int, str]
+ 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 : Union[List[str], str]
+ :ref:`user_fields_parameter`
+
+ Returns
+ -------
+ 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", "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, *, user_auth=False, end_time, expansions, max_results, \
+ media_fields, pagination_token, place_fields, poll_fields, \
+ since_id, start_time, tweet_fields, until_id, user_fields \
+ )
+
+ 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 : Union[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`_.
+ user_auth : bool
+ Whether or not to use OAuth 1.0a User context
+ end_time : Union[datetime.datetime, str]
+ 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 : Union[List[str], str]
+ :ref:`expansions_parameter`
+ max_results : int
+ 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 : Union[List[str], str]
+ :ref:`media_fields_parameter`
+ pagination_token : str
+ 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 : Union[List[str], str]
+ :ref:`place_fields_parameter`
+ poll_fields : Union[List[str], str]
+ :ref:`poll_fields_parameter`
+ since_id : Union[int, str]
+ 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 : Union[datetime.datetime, str]
+ 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 : Union[List[str], str]
+ :ref:`tweet_fields_parameter`
+ until_id : Union[int, str]
+ 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 : Union[List[str], str]
+ :ref:`user_fields_parameter`
+
+ Returns
+ -------
+ 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_users_tweets(self, id, *, user_auth=False, **params):
+ """get_users_tweets( \
+ id, *, user_auth=False, end_time, exclude, expansions, \
+ max_results, media_fields, pagination_token, place_fields, \
+ poll_fields, since_id, start_time, tweet_fields, until_id, \
+ user_fields \
+ )
+
+ 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 : Union[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`_.
+ user_auth : bool
+ Whether or not to use OAuth 1.0a User context
+ end_time : Union[datetime.datetime, str]
+ 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 : Union[List[str], str]
+ 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 : Union[List[str], str]
+ :ref:`expansions_parameter`
+ max_results : int
+ 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 : Union[List[str], str]
+ :ref:`media_fields_parameter`
+ pagination_token : str
+ 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 : Union[List[str], str]
+ :ref:`place_fields_parameter`
+ poll_fields : Union[List[str], str]
+ :ref:`poll_fields_parameter`
+ since_id : Union[int, str]
+ 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 : Union[datetime.datetime, str]
+ 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 : Union[List[str], str]
+ :ref:`tweet_fields_parameter`
+ until_id : Union[int, str]
+ 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 : Union[List[str], str]
+ :ref:`user_fields_parameter`
+
+ Returns
+ -------
+ 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
"""
- Tweet lookup
+ 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 lookup
+
+ def get_tweet(self, id, *, user_auth=False, **params):
+ """get_tweet(id, *, user_auth=False, expansions, media_fields, \
+ place_fields, poll_fields, twitter_fields, user_fields)
+
+ Returns a variety of information about a single Tweet specified by
+ the requested ID.
+
+ Parameters
+ ----------
+ id : Union[int, str]
+ Unique identifier of the Tweet to request
+ user_auth : bool
+ Whether or not to use OAuth 1.0a User context
+ expansions : Union[List[str], str]
+ :ref:`expansions_parameter`
+ media_fields : Union[List[str], str]
+ :ref:`media_fields_parameter`
+ place_fields : Union[List[str], str]
+ :ref:`place_fields_parameter`
+ poll_fields : Union[List[str], str]
+ :ref:`poll_fields_parameter`
+ tweet_fields : Union[List[str], str]
+ :ref:`tweet_fields_parameter`
+ user_fields : Union[List[str], str]
+ :ref:`user_fields_parameter`
+
+ Returns
+ -------
+ Response
+
+ References
+ ----------
https://developer.twitter.com/en/docs/twitter-api/tweets/lookup/api-reference/get-tweets-id
"""
return self._make_request(
)
def get_tweets(self, ids, *, user_auth=False, **params):
- """
- Tweets lookup
+ """get_tweets(ids, *, user_auth=False, expansions, media_fields, \
+ place_fields, poll_fields, twitter_fields, user_fields)
+
+ Returns a variety of information about the Tweet specified by the
+ requested ID or list of IDs.
+
+ Parameters
+ ----------
+ id : Union[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.
+ user_auth : bool
+ Whether or not to use OAuth 1.0a User context
+ expansions : Union[List[str], str]
+ :ref:`expansions_parameter`
+ media_fields : Union[List[str], str]
+ :ref:`media_fields_parameter`
+ place_fields : Union[List[str], str]
+ :ref:`place_fields_parameter`
+ poll_fields : Union[List[str], str]
+ :ref:`poll_fields_parameter`
+ tweet_fields : Union[List[str], str]
+ :ref:`tweet_fields_parameter`
+ user_fields : Union[List[str], str]
+ :ref:`user_fields_parameter`
+
+ Returns
+ -------
+ Response
+
+ References
+ ----------
https://developer.twitter.com/en/docs/twitter-api/tweets/lookup/api-reference/get-tweets
"""
params["ids"] = ids
), data_type=Tweet, user_auth=user_auth
)
- def get_user(self, *, id=None, username=None, user_auth=False, **params):
- """
- User lookup
- 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")
+ # Follows
- route = "/2/users"
+ def unfollow(self, target_user_id):
+ """Allows a user ID to unfollow another user.
- 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")
+ The request succeeds with no action when the authenticated user sends a
+ request to a user they're not following or have already unfollowed.
- return self._make_request(
- "GET", route, params=params,
- endpoint_parameters=("expansions", "tweet.fields", "user.fields"),
- data_type=User, user_auth=user_auth
- )
+ Parameters
+ ----------
+ target_user_id : Union[int, str]
+ The user ID of the user that you would like to unfollow.
- def get_users(self, *, ids=None, usernames=None, user_auth=False,
- **params):
- """
- Users lookup
- 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")
+ Returns
+ -------
+ Response
- route = "/2/users"
+ References
+ ----------
+ https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/delete-users-source_id-following
+ """
+ source_user_id = self.access_token.partition('-')[0]
+ route = f"/2/users/{source_user_id}/following/{target_user_id}"
- 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("DELETE", route, user_auth=True)
- 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_users_followers(self, id, *, user_auth=False, **params):
+ """get_users_followers( \
+ id, *, user_auth=False, expansions, max_results, \
+ pagination_token, tweet_fields, user_fields \
)
- def get_users_followers(self, id, *, user_auth=False, **params):
- """
- Followers lookup
+ Returns a list of users who are followers of the specified user ID.
+
+ Parameters
+ ----------
+ id : Union[int, str]
+ The user ID whose followers you would like to retrieve.
+ user_auth : bool
+ Whether or not to use OAuth 1.0a User context
+ expansions : Union[List[str], str]
+ :ref:`expansions_parameter`
+ max_results : int
+ 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
+ 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 : Union[List[str], str]
+ :ref:`tweet_fields_parameter`
+ user_fields : Union[List[str], str]
+ :ref:`user_fields_parameter`
+
+ Returns
+ -------
+ Response
+
+ References
+ ----------
https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/get-users-id-followers
"""
return self._make_request(
)
def get_users_following(self, id, *, user_auth=False, **params):
- """
- Following lookup
+ """get_users_following( \
+ id, *, user_auth=False, expansions, max_results, \
+ pagination_token, tweet_fields, user_fields \
+ )
+
+ Returns a list of users the specified user ID is following.
+
+ Parameters
+ ----------
+ id : Union[int, str]
+ The user ID whose following you would like to retrieve.
+ user_auth : bool
+ Whether or not to use OAuth 1.0a User context
+ expansions : Union[List[str], str]
+ :ref:`expansions_parameter`
+ max_results : int
+ 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
+ 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 : Union[List[str], str]
+ :ref:`tweet_fields_parameter`
+ user_fields : Union[List[str], str]
+ :ref:`user_fields_parameter`
+
+ Returns
+ -------
+ Response
+
+ References
+ ----------
https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/get-users-id-following
"""
return self._make_request(
), data_type=User, user_auth=user_auth
)
- def get_users_mentions(self, id, *, user_auth=False, **params):
- """
- User mention timeline
- https://developer.twitter.com/en/docs/twitter-api/tweets/timelines/api-reference/get-users-id-mentions
- """
- 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 follow(self, target_user_id):
+ """Allows a user ID to follow another user.
- def get_users_tweets(self, id, *, user_auth=False, **params):
- """
- User Tweet timeline
- https://developer.twitter.com/en/docs/twitter-api/tweets/timelines/api-reference/get-users-id-tweets
- """
- 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
- )
+ If the target user does not have public Tweets, this endpoint will send
+ a follow request.
- def hide_reply(self, id):
- """
- Hide replies
- 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=True
- )[0]["hidden"]
+ 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.
- def search_all_tweets(self, query, **params):
- """
- Search Tweets: Full-archive search
- https://developer.twitter.com/en/docs/twitter-api/tweets/search/api-reference/get-tweets-search-all
+ Parameters
+ ----------
+ target_user_id : Union[int, str]
+ The user ID of the user that you would like to follow
+
+ Returns
+ -------
+ Response
+
+ References
+ ----------
+ https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/post-users-source_user_id-following
"""
- params["query"] = query
+ source_user_id = self.access_token.partition('-')[0]
+ route = f"/2/users/{source_user_id}/following"
+
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", "start_time", "tweet.fields", "until_id",
- "user.fields"
- ), data_type=Tweet
+ "POST", route, json={"target_user_id": str(target_user_id)},
+ user_auth=True
)
- def search_recent_tweets(self, query, *, user_auth=False, **params):
- """
- Search Tweets: recent search
- https://developer.twitter.com/en/docs/twitter-api/tweets/search/api-reference/get-tweets-search-recent
+ # User lookup
+
+ def get_user(self, *, id=None, username=None, user_auth=False, **params):
+ """get_user(*, id, username, user_auth=False, expansions, \
+ tweet_fields, user_fields)
+
+ Returns a variety of information about a single user specified by the
+ requested ID or username.
+
+ Parameters
+ ----------
+ id : Union[int, str]
+ The ID of the user to lookup.
+ username : str
+ The Twitter username (handle) of the user.
+ user_auth : bool
+ Whether or not to use OAuth 1.0a User context
+ expansions : Union[List[str], str]
+ :ref:`expansions_parameter`
+ tweet_fields : Union[List[str], str]
+ :ref:`tweet_fields_parameter`
+ user_fields : Union[List[str], str]
+ :ref:`user_fields_parameter`
+
+ Raises
+ ------
+ TypeError
+ If ID and username are not passed or both are passed
+
+ Returns
+ -------
+ 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
"""
- params["query"] = query
+ 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", "/2/tweets/search/recent", params=params,
- endpoint_parameters=(
- "end_time", "expansions", "max_results", "media.fields",
- "next_token", "place.fields", "poll.fields", "query",
- "since_id", "start_time", "tweet.fields", "until_id",
- "user.fields"
- ), data_type=Tweet, user_auth=user_auth
+ "GET", route, params=params,
+ endpoint_parameters=("expansions", "tweet.fields", "user.fields"),
+ data_type=User, user_auth=user_auth
)
- def unfollow(self, target_user_id):
- """
- Unfollow user
- https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/delete-users-source_id-following
+ def get_users(self, *, ids=None, usernames=None, user_auth=False,
+ **params):
+ """get_users(*, ids, usernames, user_auth=False, expansions, \
+ tweet_fields, user_fields)
+
+ Returns a variety of information about one or more users specified by
+ the requested IDs or usernames.
+
+ Parameters
+ ----------
+ ids : Union[List[int, str], str]
+ 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 : Union[List[str], str]
+ 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.
+ user_auth : bool
+ Whether or not to use OAuth 1.0a User context
+ expansions : Union[List[str], str]
+ :ref:`expansions_parameter`
+ tweet_fields : Union[List[str], str]
+ :ref:`tweet_fields_parameter`
+ user_fields : Union[List[str], str]
+ :ref:`user_fields_parameter`
+
+ Raises
+ ------
+ TypeError
+ If IDs and usernames are not passed or both are passed
+
+ Returns
+ -------
+ 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
"""
- source_user_id = self.access_token.partition('-')[0]
- route = f"/2/users/{source_user_id}/following/{target_user_id}"
+ if ids is not None and usernames is not None:
+ raise TypeError("Expected IDs or usernames, not both")
- return self._make_request("DELETE", route, user_auth=True)
+ 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")
- def unhide_reply(self, tweet_id):
- """
- Unhide replies
- 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/{tweet_id}/hidden", json={"hidden": False},
- user_auth=True
- )[0]["hidden"]
+ "GET", route, params=params,
+ endpoint_parameters=(
+ "ids", "usernames", "expansions", "tweet.fields", "user.fields"
+ ), data_type=User, user_auth=user_auth
+ )
projects / tweepy.git / commitdiff