From: Harmon Date: Mon, 12 Apr 2021 16:49:15 +0000 (-0500) Subject: Document API.Stream X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=18a6059e7980de7759be126ffe39836494cc4f23;p=tweepy.git Document API.Stream --- diff --git a/docs/conf.py b/docs/conf.py index 99f96df..71f4b38 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,10 +27,14 @@ sys.path.append(os.path.abspath('..')) extensions = [ 'recommonmark', 'sphinx.ext.autodoc', - 'sphinx.ext.intersphinx' + 'sphinx.ext.intersphinx', + 'sphinx.ext.napoleon' ] -intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + 'requests': ('https://docs.python-requests.org/en/latest/', None) +} # Add any paths that contain templates here, relative to this directory. #templates_path = ['_templates'] diff --git a/docs/index.rst b/docs/index.rst index f30801f..8aa437b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,6 +18,7 @@ Contents: cursor_tutorial.rst streaming_how_to.rst api.rst + stream.rst exceptions.rst extended_tweets.rst running_tests.rst diff --git a/docs/stream.rst b/docs/stream.rst new file mode 100644 index 0000000..fc31c9e --- /dev/null +++ b/docs/stream.rst @@ -0,0 +1,11 @@ +.. _stream_reference: + +.. currentmodule:: tweepy + +***************************************** +:mod:`tweepy.Stream` --- Stream Reference +***************************************** + +.. autoclass:: Stream + :members: + :member-order: bysource diff --git a/tweepy/streaming.py b/tweepy/streaming.py index ca52fc7..ac53b13 100644 --- a/tweepy/streaming.py +++ b/tweepy/streaming.py @@ -24,6 +24,47 @@ log = logging.getLogger(__name__) class Stream: + """Filter and sample realtime Tweets + + Parameters + ---------- + consumer_key : str + Twitter API Consumer Key + consumer_secret : str + Twitter API Consumer Secret + access_token: str + Twitter API Access Token + access_token_secret : str + Twitter API Access Token Secret + chunk_size : int + The default socket.read size. Default to 512, less than half the size + of a Tweet so that it reads Tweets with the minimal latency of 2 reads + per Tweet. Values higher than ~1kb will increase latency by waiting for + more data to arrive but may also increase throughput by doing fewer + socket read calls. + daemon : bool + Whether or not to use a daemon thread when using a thread to run the + stream + max_retries : int + Max number of times to retry connecting the stream + proxy : Optional[str] + URL of the proxy to use when connecting to the stream + verify : Union[bool, str] + Either a boolean, in which case it controls whether to verify the + server’s TLS certificate, or a string, in which case it must be a path + to a CA bundle to use. + + Attributes + ---------- + running : bool + Whether there's currently a stream running + session : Optional[:class:`requests.Session`] + Requests Session used to connect to the stream + thread : Optional[:class:`threading.Thread`] + Thread used to run the stream + user_agent : str + User agent used when connecting to the stream + """ def __init__(self, consumer_key, consumer_secret, access_token, access_token_secret, *, chunk_size=512, daemon=False, @@ -32,11 +73,6 @@ class Stream: self.consumer_secret = consumer_secret self.access_token = access_token self.access_token_secret = access_token_secret - # The default socket.read size. Default to less than half the size of - # a tweet so that it reads tweets with the minimal latency of 2 reads - # per tweet. Values higher than ~1kb will increase latency by waiting - # for more data to arrive but may also increase throughput by doing - # fewer socket read calls. self.chunk_size = chunk_size self.daemon = daemon self.max_retries = max_retries @@ -154,6 +190,54 @@ class Stream: def filter(self, *, follow=None, track=None, locations=None, filter_level=None, languages=None, stall_warnings=False, threaded=False): + """Filter realtime Tweets + + Parameters + ---------- + follow : Optional[List[Union[int, str]]] + User IDs, indicating the users to return statuses for in the stream + track : Optional[List[str]] + Keywords to track + locations : Optional[List[float]] + Specifies a set of bounding boxes to track + filter_level : Optional[str] + Setting this parameter to one of none, low, or medium will set the + minimum value of the filter_level Tweet attribute required to be + included in the stream. The default value is none, which includes + all available Tweets. + + When displaying a stream of Tweets to end users (dashboards or live + feeds at a presentation or conference, for example) it is suggested + that you set this value to medium. + languages : Optional[List[str]] + Setting this parameter to a comma-separated list of `BCP 47`_ + language identifiers corresponding to any of the languages listed + on Twitter’s `advanced search`_ page will only return Tweets that + have been detected as being written in the specified languages. For + example, connecting with language=en will only stream Tweets + detected to be in the English language. + stall_warnings : bool + Specifies whether stall warnings should be delivered + threaded : bool + Whether or not to use a thread to run the stream + + Raises + ------ + TweepyException + When number of location coordinates is not a multiple of 4 + + Returns + ------- + Optional[threading.Thread] + The thread if ``threaded`` is set to ``True``, else ``None`` + + References + ---------- + https://developer.twitter.com/en/docs/twitter-api/v1/tweets/filter-realtime/api-reference/post-statuses-filter + + .. _BCP 47: https://tools.ietf.org/html/bcp47 + .. _advanced search: https://twitter.com/search-advanced + """ if self.running: raise TweepyException("Stream is already connected") @@ -186,6 +270,31 @@ class Stream: self._connect(method, endpoint, headers=headers, body=body) def sample(self, *, languages=None, stall_warnings=False, threaded=False): + """Sample realtime Tweets + + Parameters + ---------- + languages : Optional[List[str]] + Setting this parameter to a comma-separated list of `BCP 47`_ + language identifiers corresponding to any of the languages listed + on Twitter’s `advanced search`_ page will only return Tweets that + have been detected as being written in the specified languages. For + example, connecting with language=en will only stream Tweets + detected to be in the English language. + stall_warnings : bool + Specifies whether stall warnings should be delivered + threaded : bool + Whether or not to use a thread to run the stream + + Returns + ------- + Optional[threading.Thread] + The thread if ``threaded`` is set to ``True``, else ``None`` + + References + ---------- + https://developer.twitter.com/en/docs/twitter-api/v1/tweets/sample-realtime/api-reference/get-statuses-sample + """ if self.running: raise TweepyException("Stream is already connected") @@ -204,10 +313,17 @@ class Stream: self._connect(method, endpoint, params=params) def disconnect(self): + """Disconnect the stream""" self.running = False def on_closed(self, resp): - """This is called when the stream has been closed by Twitter.""" + """This is called when the stream has been closed by Twitter. + + Parameters + ---------- + resp : requests.Response + The Response from Twitter + """ log.error("Stream connection closed by Twitter") def on_connect(self): @@ -224,7 +340,13 @@ class Stream: log.info("Stream disconnected") def on_exception(self, exception): - """This is called when an unhandled exception occurs.""" + """This is called when an unhandled exception occurs. + + Parameters + ---------- + exception : Exception + The unhandled exception + """ log.exception("Stream encountered an exception") def on_keep_alive(self): @@ -232,7 +354,13 @@ class Stream: log.debug("Received keep-alive signal") def on_request_error(self, status_code): - """This is called when a non-200 HTTP status code is encountered.""" + """This is called when a non-200 HTTP status code is encountered. + + Parameters + ---------- + status_code : int + The HTTP status code encountered + """ log.error("Stream encountered HTTP error: %d", status_code) def on_data(self, raw_data): @@ -240,6 +368,13 @@ class Stream: This method handles sending the data to other methods, depending on the message type. + Parameters + ---------- + raw_data : JSON + The raw data from the stream + + References + ---------- https://developer.twitter.com/en/docs/twitter-api/v1/tweets/filter-realtime/guides/streaming-message-types """ data = json.loads(raw_data) @@ -266,33 +401,84 @@ class Stream: log.error("Received unknown message type: %s", raw_data) def on_status(self, status): - """This is called when a status is received.""" + """This is called when a status is received. + + Parameters + ---------- + status : Status + The Status received + """ log.debug("Received status: %d", status.id) def on_delete(self, status_id, user_id): - """This is called when a status deletion notice is received.""" + """This is called when a status deletion notice is received. + + Parameters + ---------- + status_id : int + The ID of the deleted Tweet + user_id : int + The ID of the author of the Tweet + """ log.debug("Received status deletion notice: %d", status_id) def on_disconnect_message(self, message): - """This is called when a disconnect message is received.""" + """This is called when a disconnect message is received. + + Parameters + ---------- + message : JSON + The disconnect message + """ log.warning("Received disconnect message: %s", message) def on_limit(self, track): - """This is called when a limit notice is received.""" + """This is called when a limit notice is received. + + Parameters + ---------- + track : int + Total count of the number of undelivered Tweets since the + connection was opened + """ log.debug("Received limit notice: %d", track) def on_scrub_geo(self, notice): - """This is called when a location deletion notice is received.""" + """This is called when a location deletion notice is received. + + Parameters + ---------- + notice : JSON + The location deletion notice + """ log.debug("Received location deletion notice: %s", notice) def on_status_withheld(self, notice): - """This is called when a status withheld content notice is received.""" + """This is called when a status withheld content notice is received. + + Parameters + ---------- + notice : JSON + The status withheld content notice + """ log.debug("Received status withheld content notice: %s", notice) def on_user_withheld(self, notice): - """This is called when a user withheld content notice is received.""" + """This is called when a user withheld content notice is received. + + Parameters + ---------- + notice : JSON + The user withheld content notice + """ log.debug("Received user withheld content notice: %s", notice) def on_warning(self, warning): - """This is called when a stall warning message is received.""" + """This is called when a stall warning message is received. + + Parameters + ---------- + warning : JSON + The stall warning + """ log.warning("Received stall warning: %s", warning)