From d9b375b6b15438eba8070d62235834e111930821 Mon Sep 17 00:00:00 2001 From: Harmon Date: Mon, 12 Apr 2021 19:40:41 -0500 Subject: [PATCH] Document Client --- docs/api.rst | 6 +- docs/client.rst | 192 ++++++++++ docs/index.rst | 1 + tweepy/client.py | 890 +++++++++++++++++++++++++++++++++++++++-------- 4 files changed, 939 insertions(+), 150 deletions(-) create mode 100644 docs/client.rst diff --git a/docs/api.rst b/docs/api.rst index 88dd0eb..a923014 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -4,9 +4,9 @@ .. include:: parameters.rst -************************************* -:class:`tweepy.API` --- API Reference -************************************* +************************************************** +:class:`tweepy.API` --- Twitter API v1.1 Reference +************************************************** .. autoclass:: API diff --git a/docs/client.rst b/docs/client.rst new file mode 100644 index 0000000..dcbc1d5 --- /dev/null +++ b/docs/client.rst @@ -0,0 +1,192 @@ +.. _client_reference: + +.. currentmodule:: tweepy + +*************************************************** +:class:`tweepy.Client` --- Twitter API v2 Reference +*************************************************** + +.. autoclass:: Client + +Tweets +====== + +Hide replies +------------ + +.. automethod:: Client.hide_reply + +.. automethod:: Client.unhide_reply + +Search Tweets +------------- + +.. automethod:: Client.search_all_tweets + +.. automethod:: Client.search_recent_tweets + +Timelines +--------- + +.. automethod:: Client.get_users_mentions + +.. automethod:: Client.get_users_tweets + +Tweet lookup +------------ + +.. automethod:: Client.get_tweet + +.. automethod:: Client.get_tweets + +Users +===== + +Follows +------- + +.. automethod:: Client.unfollow + +.. automethod:: Client.get_users_followers + +.. automethod:: Client.get_users_following + +.. automethod:: Client.follow + +User lookup +----------- + +.. automethod:: Client.get_user + +.. automethod:: Client.get_users + +Expansions and Fields Parameters +================================ + +.. _expansions_parameter: + +``expansions`` +-------------- +For methods that return Tweets, `Expansions`_ enable you to request additional +data objects that relate to the originally returned Tweets. Submit a list of +desired expansions in a comma-separated list without spaces. The ID that +represents the expanded data object will be included directly in the Tweet data +object, but the expanded object metadata will be returned within the +``includes`` response object, and will also include the ID so that you can +match this data object to the original Tweet object. + +The following data objects can be expanded using this parameter: + +* The Tweet author's user object +* The user object of the Tweet’s author that the + original Tweet is responding to +* Any mentioned users’ object +* Any referenced Tweets’ author’s user object +* Attached media’s object +* Attached poll’s object +* Attached place’s object +* Any referenced Tweets’ object + +For methods that return users, `Expansions`_ enable you to request additional +data objects that relate to the originally returned users. The ID that +represents the expanded data object will be included directly in the user data +object, but the expanded object metadata will be returned within the +``includes`` response object, and will also include the ID so that you can +match this data object to the original Tweet object. At this time, the only +expansion available to endpoints that primarily return user objects is +``expansions=pinned_tweet_id``. You will find the expanded Tweet data object +living in the ``includes`` response object. + +.. _media_fields_parameter: + +``media_fields`` +---------------- +This `fields`_ parameter enables you to select which specific `media fields`_ +will deliver in each returned Tweet. Specify the desired fields in a +comma-separated list without spaces between commas and fields. The Tweet will +only return media fields if the Tweet contains media and if you've also +included the ``expansions=attachments.media_keys`` query parameter in your +request. While the media ID will be located in the Tweet object, you will find +this ID and all additional media fields in the ``includes`` data object. + +.. _place_fields_parameter: + +``place_fields`` +---------------- +This `fields`_ parameter enables you to select which specific `place fields`_ +will deliver in each returned Tweet. Specify the desired fields in a +comma-separated list without spaces between commas and fields. The Tweet will +only return place fields if the Tweet contains a place and if you've also +included the ``expansions=geo.place_id`` query parameter in your request. While +the place ID will be located in the Tweet object, you will find this ID and all +additional place fields in the ``includes`` data object. + +.. _poll_fields_parameter: + +``poll_fields`` +--------------- + +This `fields`_ parameter enables you to select which specific `poll fields`_ +will deliver in each returned Tweet. Specify the desired fields in a +comma-separated list without spaces between commas and fields. The Tweet will +only return poll fields if the Tweet contains a poll and if you've also +included the ``expansions=attachments.poll_ids`` query parameter in your +request. While the poll ID will be located in the Tweet object, you will find +this ID and all additional poll fields in the ``includes`` data object. + +.. _tweet_fields_parameter: + +``tweet_fields`` +---------------- + +For methods that return Tweets, this `fields`_ parameter enables you to select +which specific `Tweet fields`_ will deliver in each returned Tweet object. +Specify the desired fields in a comma-separated list without spaces between +commas and fields. You can also pass the ``expansions=referenced_tweets.id`` +expansion to return the specified fields for both the original Tweet and any +included referenced Tweets. The requested Tweet fields will display in both the +original Tweet data object, as well as in the referenced Tweet expanded data +object that will be located in the ``includes`` data object. + +For methods that return users, this `fields`_ parameter enables you to select +which specific `Tweet fields`_ will deliver in each returned pinned Tweet. +Specify the desired fields in a comma-separated list without spaces between +commas and fields. The Tweet fields will only return if the user has a pinned +Tweet and if you've also included the ``expansions=pinned_tweet_id`` query +parameter in your request. While the referenced Tweet ID will be located in the +original Tweet object, you will find this ID and all additional Tweet fields in +the ``includes`` data object. + +.. _user_fields_parameter: + +``user_fields`` +--------------- + +For methods that return Tweets, this `fields`_ parameter enables you to select +which specific `user fields`_ will deliver in each returned Tweet. Specify the +desired fields in a comma-separated list without spaces between commas and +fields. While the user ID will be located in the original Tweet object, you +will find this ID and all additional user fields in the ``includes`` data +object. + +You must also pass one of the user expansions to return the desired user +fields: + +* ``expansions=author_id`` +* ``expansions=entities.mentions.username`` +* ``expansions=in_reply_to_user_id`` +* ``expansions=referenced_tweets.id.author_id`` + +For methods that return users, this `fields`_ parameter enables you to select +which specific `user fields`_ will deliver with each returned users objects. +Specify the desired fields in a comma-separated list without spaces between +commas and fields. These specified user fields will display directly in the +user data objects. + +.. _Expansions: https://developer.twitter.com/en/docs/twitter-api/expansions +.. _fields: https://developer.twitter.com/en/docs/twitter-api/fields +.. _media fields: https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/media +.. _place fields: https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/place +.. _poll fields: https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/poll +.. _Tweet fields: https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/tweet +.. _user fields: https://developer.twitter.com/en/docs/twitter-api/data-dictionary/object-model/user diff --git a/docs/index.rst b/docs/index.rst index a4d6618..87a62cb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,6 +17,7 @@ Contents: code_snippet.rst cursor_tutorial.rst api.rst + client.rst stream.rst exceptions.rst extended_tweets.rst diff --git a/tweepy/client.py b/tweepy/client.py index a099a81..418a665 100644 --- a/tweepy/client.py +++ b/tweepy/client.py @@ -28,22 +28,29 @@ Response = namedtuple("Response", ("data", "includes", "errors", "meta")) 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, @@ -161,22 +168,480 @@ class Client: 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( @@ -188,8 +653,39 @@ class Client: ) 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 @@ -201,60 +697,69 @@ class Client: ), 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( @@ -267,8 +772,42 @@ class Client: ) 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( @@ -279,93 +818,150 @@ class Client: ), 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 + ) -- 2.25.1