How to access the API

You can easily access any Twitter API endpoint. Just search for the endpoint that you need on Twitter’s documentation, then you can make a request to this endpoint as:

client.twitter_subdomain.path.to.endpoint.method()

So to access GET statuses/home_timeline:

client.api.statuses.home_timeline.get()

For a more complete example:

# NOTE: any reference to a `creds` variable in the documentation
# examples should have this format
creds = dict(consumer_key=YOUR_CONSUMER_KEY,
             consumer_secret=YOUR_CONSUMER_SECRET,
             access_token=YOUR_ACCESS_TOKEN,
             access_token_secret=YOUR_ACCESS_TOKEN_SECRET)

client = PeonyClient(**creds)

# to access api.twitter.com/1.1/statuses/home_timeline.json
# using the GET method with the parameters count and since_id
async def home():
    return await client.api.statuses.home_timeline.get(count=200,
                                                       since_id=20)

# to access api.twitter.com/1.1/statuses/update.json
# using the POST method with the parameter status
async def track():
    return await client.api.statuses.update.post(status="Hello World!")

# would GET subdomain.twitter.com/1.1/path.json if it were
# an API endpoint
async def path():
    return await client.subdomain.path.get()

see Accessing an API using a different API version to access APIs that do not use the version ‘1.1’

Note

Some endpoints require the use of characters that cannot be used as attributes such as GET geo/id/:place_id

You can use the brackets instead:

id = 20  # any status id would work as long as it exists
client.api.statuses.show[id].get()

Note

Arguments with a leading underscore are arguments that are used to change the behavior of peony for the request (e.g. _headers to add some additional headers to the request). Arguments without a leading underscore are parameters of the request you send.

Access the response data of a REST API endpoint

A call to a REST API endpoint should return a PeonyResponse object if the request was successful.

async def home():
    req = client.api.statuses.home_timeline.get(count=200, since_id=0, tweet_mode='extended')

    # this is a PeonyResponse object
    response = await req

    # you can iterate over the response object
    for tweet in response:
        # you can access items as you would do in a dictionnary
        user_id = tweet['user']['id']

        # or as you would access an attribute
        username = tweet.user.screen_name

        display_range = tweet.get('display_text_range', None)
        if display_range is not None:
            # get the text from the display range provided in the response
            # if present
            text = tweet.text[display_range[0]:display_range[1]]
        else:
            # just get the text
            text = tweet.text

        print("@{username} ({id}): {text}".format(username=username,
                                                  id=user_id,
                                                  text=text))

Note

If extended_tweet is present in the response, attributes that are in tweet.extended_tweet can be retrieved right from tweet:

>>> tweet.display_text_range == tweet.extended_tweet.display_text_range
True # if tweet.extended_tweet.display_range exists.

Also, getting the text attribute of the data should always retrieve the full text of the tweet even when the data is truncated. So, there should be no need to look for a full_text attribute.

Note

tweet.key and tweet['key'] are always equivalent, even when the key is an attribute in extended_tweet or text.

Access the response data of a Streaming API endpoint

A call to a Streaming API endpoint should return a StreamResponse object.

async def track():
    req = client.stream.statuses.filter.post(track="uwu")

    # req is an asynchronous context
    async with req as stream:
        # stream is an asynchronous iterator
        async for tweet in stream:
            # check that you actually receive a tweet
            if peony.events.tweet(tweet):
                # you can then access items as you would do with a
                # `PeonyResponse` object
                user_id = tweet['user']['id']
                username = tweet.user.screen_name

                msg = "@{username} ({id}): {text}"
                print(msg.format(username=username,
                                 id=user_id,
                                 text=tweet.text))