From addb9f7a78de70c1b1e4b6a34e5324776f55cd0f Mon Sep 17 00:00:00 2001 From: Harmon Date: Fri, 17 Mar 2023 08:58:39 -0500 Subject: [PATCH] Overhaul Getting Started documentation --- docs/getting_started.rst | 88 ++++++++++++++++++++-------------------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 449e444..3a3ea1c 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -1,66 +1,66 @@ .. _getting_started: +.. currentmodule:: tweepy *************** -Getting started +Getting Started *************** -Introduction -============ +Tweepy supports both Twitter API v1.1 and Twitter API v2. -If you are new to Tweepy, this is the place to begin. The goal of this -tutorial is to get you set-up and rolling with Tweepy. We won't go -into too much detail here, just some important basics. +Tweepy's interface for making requests to Twitter API v1.1 endpoints is +:class:`API`. -Hello Tweepy -============ +Tweepy's interface for making requests to Twitter API v2 endpoints is +:class:`Client`. -.. code-block :: python +Models +====== - import tweepy +:class:`API` and :class:`Client` methods generally return instances of classes +that are models of Twitter API objects. Each model instance / object contains +the data provided by Twitter's API that represent that object. - auth = tweepy.OAuth1UserHandler( - consumer_key, consumer_secret, access_token, access_token_secret - ) +For example, the following code retrieves a User object and assigns it to the +variable, ``user``:: - api = tweepy.API(auth) - - public_tweets = api.home_timeline() - for tweet in public_tweets: - print(tweet.text) + # Get the User object that represents the user, @Twitter + user = api.get_user(screen_name="Twitter") -This example will download your home timeline tweets and print each -one of their texts to the console. Twitter requires all requests to -use OAuth for authentication. -The :ref:`authentication` documentation goes into more details about -authentication. +The data for each object can be accessed through its attributes/fields, and +some models have helper methods that can be used:: -API -=== + print(user.screen_name) + print(user.followers_count) + for friend in user.friends(): + print(friend.screen_name) -The API class provides access to the entire twitter RESTful API -methods. Each method can accept various parameters and return -responses. For more information about these methods please refer to -:ref:`API Reference `. +:ref:`Twitter API v1.1 models ` and +:ref:`Twitter API v2 models ` are documented separately. -Models -====== +Example +======= + +:: + + import tweepy + + auth = tweepy.OAuth1UserHandler( + consumer_key, consumer_secret, access_token, access_token_secret + ) -When we invoke an API method most of the time returned back to us will -be a Tweepy model class instance. This will contain the data returned -from Twitter which we can then use inside our application. For example -the following code returns to us a User model:: + api = tweepy.API(auth) - # Get the User object for twitter... - user = api.get_user(screen_name='twitter') + public_tweets = api.home_timeline() + for tweet in public_tweets: + print(tweet.text) -Models contain the data and some helper methods which we can then -use:: +This example uses Twitter API v1.1, by using :class:`API`, to retrieve the +Tweets in your home timeline and print the text of each one to the console. - print(user.screen_name) - print(user.followers_count) - for friend in user.friends(): - print(friend.screen_name) +The consumer key, consumer secret, access token, and access token secret being +passed are required to authenticate as a user, using OAuth 1.0a User Context. +The :ref:`authentication` page goes into more detail. -For more information about models please see ModelsReference. +More examples can be found on the :ref:`examples` page. -- 2.25.1