pytweet package

Submodules

pytweet.attachments module

class pytweet.attachments.Media(data)

Represent a Media attachment in a tweet.

x == y
Check if one Media key is equal to another.
x != y
Check if one Media key is not equal to another.
str(x)
Get the media url.

New in version 1.1.0.

property type

Return the media’s type.

New in version 1.1.0.

Type

Optional[str]

property url

Return the media’s url.

New in version 1.1.0.

Type

Optional[str]

property width

the media’s width.

New in version 1.1.0.

Type

Optional[int]

property height

Return the media’s height.

New in version 1.1.0.

Type

int

property media_key

Returns the media’s unique key.

New in version 1.1.0.

Type

Optional[Union[int, str]]

class pytweet.attachments.PollOptions(options)

Represent the Poll Options, The minimum option of a poll is 2 and maximum is 4.

x == y
Check if one PollOption position is equal to another.
x != y
Check if one PollOption position is not equal to another.
x > y
Check if one PollOption position is higher then to another.
x < y
Check if one PollOption position is less then to another.
x >= y
Check if one PollOption position is higher then equal to another.
x <= y
Check if one PollOption position is less then equal to another.

New in version 1.1.0.

property position

The option’s position.

New in version 1.1.0.

Type

Optional[int]

property label

The option’s label.

New in version 1.1.0.

Type

Optional[int]

property votes

The option’s votes.

New in version 1.1.0.

Type

Optional[int]

class pytweet.attachments.Poll(data)

Represent a Poll attachment in a tweet.

x == y
Check if one Poll's id is equal to another.
x != y
Check if one Poll's id is not equal to another.
len(x)
return how many options in the poll.
bool(x)
return True if the poll is open else it return False.

New in version 1.1.0.

property id

Return the poll’s unique ID.

New in version 1.1.0.

Type

int

property options

Return a list of PollOptions.

New in version 1.1.0.

Type

List[PollOptions]

property voting_status

Return True if the poll is still open for voting, if its closed it return False.

New in version 1.1.0.

Type

bool

property duration

Return the poll duration in seconds.

New in version 1.1.0.

Type

int

property end_date

Return the end date in datetime.datetime object.

New in version 1.1.0.

Type

datetime.datetime

pytweet.auth module

class pytweet.auth.OauthSession(consumer_key, consumer_secret, callback=None)

pytweet.client module

class pytweet.client.Client(bearer_token, *, consumer_key=None, consumer_key_secret=None, access_token=None, access_token_secret=None)

Represent a client that connected to Twitter! This client will interact with other through twitter’s api version 2!

bearer_token: str

The Bearer Token of the app. The most important one, because this make most of the requests for twitter’s api version 2.

consumer_key: Optional[str]

The Consumer Key of the app.

consumer_key_secret: Optional[str]

The Consumer Key Secret of the app.

access_token: Optional[str]

The Access Token of the app.

access_token_secret: Optional[str]

The Access Token Secret of the app.

http: Optional[HTTPClient]

Return a HTTPClient, HTTPClient is responsible for making most of the Requests.

New in version 1.0.0.

property user

Returns the client in user object, return None if access token isn’t specified.

New in version 1.2.0.

Type

User

get_user(user_id)

A function for HTTPClient.fetch_user().

user_id: Union[str, int]

Represent the user id that you wish to get info to, If you dont have it you may use fetch_user_byusername because it only required the user’s username.

This function returns a User object.

New in version 1.0.0.

get_user_by_username(username)

A function for HTTPClient.fetch_user_byusername().

username: str

Represent the user’s username that you wish to get info. A Username usually start with ‘@’ before any letters. If a username named @Jack,then the username argument must be ‘Jack’.

This function returns a User object.

New in version 1.0.0.

get_tweet(tweet_id)

A function for HTTPClient.fetch_tweet().

tweet_id: Union[str, int]

Represent the tweet id that you wish to get info to.

This function returns a Tweet.

New in version 1.0.0.

tweet(text, **kwargs)

Post a tweet directly to twitter from the given parameters.

text: str

The tweets text, it will showup as the main text in a tweet.

New in version 1.1.0.

pytweet.errors module

exception pytweet.errors.PytweetException(response=None, message='No Error Message Provided')

Exception: This is the base class of all exceptions.

New in version 1.2.0.

exception pytweet.errors.APIException(response=None, message='No Error Message Provided')

PytweetException: Raise When an error is incurred during a request with HTTP Status code 200.

New in version 1.2.0.

exception pytweet.errors.HTTPException(response=None, message='No Error Message Provided')

PytweetException: A custom error that will be raised when ever a request return HTTP status code above 200.

New in version 1.2.0.

exception pytweet.errors.Unauthorized(response=None, message='No Error Message Provided')

HTTPException: Raised when the Credentials you passed is invalid and a request return status code: 401

New in version 1.0.0.

exception pytweet.errors.TooManyRequests(response=None, message='No Error Message Provided')

HTTPException: Raised when ratelimit exceeded and a request return status code: 429

New in version 1.1.0.

exception pytweet.errors.Forbidden(response=None, message=None)

HTTPException: Raised when a request return status code: 403.

New in version 1.2.0.

exception pytweet.errors.BadArguments(response=None, message='No Error Message Provided')

HTTPException: Raised when a request return status code: 400.

New in version 1.2.0.

exception pytweet.errors.NotFound(response=None, message='No Error Message Provided')

This error is returned when a given Tweet, User, etc. does not exist.

New in version 1.0.0.

pytweet.http module

class pytweet.http.HTTPClient(bearer_token, *, consumer_key, consumer_key_secret, access_token, access_token_secret)

Represents the http/base client for Client ! This http/base client have methods for making requests to twitter’s api!

bearer_token: str

The Bearer Token of the app. The most important one, because this make most of the requests for twitter’s api version 2.

consumer_key: Optional[str]

The Consumer Key of the app.

consumer_key_secret: Optional[str]

The Consumer Key Secret of the app.

access_token: Optional[str]

The Access Token of the app.

access_token_secret: Optional[str]

The Access Token Secret of the app.

credentials

The credentials in a dictionary.

pytweet.errors.Unauthorized:

Raise when the api return code: 401. This usually because you passed invalid credentials.

New in version 1.0.0.

make_route(method, version, path)

Route: Function to make a Route, this intent to avoid circular import error.

request(route, *, headers={}, params={}, json={}, auth=False, is_json=True)

Make an HTTP Requests to the api.

route: Route

Represent the Route class, this will be use to configure the endpoint’s path, method, and version of the api.

headers: RequestModel

Represent the http request headers, it usually filled with your bearer token. If this isn’t specified then the default argument will be an empty dictionary. Later in the code it will update and gets your bearer token.

params: RequestModel

Represent the http request parameters, If this isn’t specified then the default argument will be an empty dictionary.

json: RequestModel

Represent the Json data. This usually use for request with POST method.

auth: bool

Represent a toggle, if auth is True then the request will be handle with Oauth1 particularly OauthSession.

is_json: bool

Represent a toggle, if its True then the return will be in a json format else its going to be a requests.models.Response object. Default to True.

pytweet.errors.Unauthorized:

Raise when the api return code: 401. This usually because you passed invalid credentials

pytweet.errors.Forbidden:

Raise when the api return code: 403. There’s a lot of reason why, This usually happen when the client cannot do the request due to twitter’s limitation e.g trying to follow someone that you blocked etc.

pytweet.errors.TooManyRequests:

Raise when the api return code: 429. This happen when you made too much request thus the api ratelimit you. The ratelimit will ware off in a couple of minutes.

This function make an HTTP Request with the given parameters then return a dictionary in a json format.

New in version 1.0.0.

fetch_user(user_id, *, http_client=None)

Make a Request to obtain the user from the given user id.

user_id: Union[str, int]

Represent the user id that you wish to get info to, If you dont have it you may use fetch_user_byusername because it only required the user’s username.

http_client:

Represent the HTTP Client that make the request, this will be use for interaction between the client and the user. If this isn’t a class or a subclass of HTTPClient, the current HTTPClient instance will be a default one.

pytweet.errors.NotFoundError:

Raise when the api can’t find a user with that id.

ValueError:

Raise when user_id is not an int and is not a string of digits.

This function return a User object.

New in version 1.0.0.

fetch_user_byusername(username, *, http_client=None)

Make a Request to obtain the user from their username.

username: str

Represent the user’s username. A Username usually start with ‘@’ before any letters. If a username named @Jack, then the username argument must be ‘Jack’.

http_client:

Represent the HTTP Client that make the request, this will be use for interaction between the client and the user. If this isn’t a class or a subclass of HTTPClient, the current HTTPClient instance will be a default one.

pytweet.errors.NotFoundError:

Raise when the api can’t find a user with that username.

This function return a User object.

New in version 1.0.0.

fetch_tweet(tweet_id, *, http_client=None)

Fetch a tweet info from the specified id. Return if consumer_key or consumer_key_secret or access_token or access_token_secret is not specified.

tweet_id: Union[str, int]

Represent the tweet’s id that you wish .

http_client

Represent the HTTP Client that make the request, this will be use for interaction between the client and the user. If this isn’t a class or a subclass of HTTPClient, the current HTTPClient instance will be a default one.

pytweet.errors.NotFoundError:

Raise when the api can’t find a tweet with that id.

This function return a Tweet.

New in version 1.0.0.

send_message(user_id, text, *, quick_reply=None, http_client=None)

Make a post Request for sending a message to a Messageable object.

user_id: Union[str, int]

The user id that you wish to send message to.

text: str

The text that will be send to that user.

quick_reply: QuickReply

The message’s quick reply attachment.

http_client

Represent the HTTP Client that make the request, this will be use for interaction between the client and the user. If this isn’t a class or a subclass of HTTPClient, the current HTTPClient instance will be a default one.

This function return a :class: DirrectMessage object.

New in version 1.1.0.

Changed in version 1.2.0.

delete_message(event_id)

Warning

This function is still under development and will raise an error when used!

Make a DELETE Request for deleting a certain message in a Messageable object.

id:

The id of the Direct Message event that you want to delete.

New in version 1.1.0.

get_message(event_id)

Warning

This function is still under development and will raise an error when used!

Make a DELETE Request for deleting a certain message in a Messageable object.

id:

The id of the Direct Message event that you want to delete.

New in version 1.1.0.

post_tweet(text, **kwargs)

Warning

This function is still under development and will raise an error when used!

Make a POST Request to post a tweet to twitter from the client itself.

New in version 1.1.0.

follow_user(user_id)

Make a POST Request to follow a Messageable object.

user_id: Union[str, int]

The user’s id that you wish to follow.

This function return a :class: RelationFollow object.

New in version 1.1.0.

Changed in version 1.2.0.

Make the method functional and return RelationFollow

unfollow_user(user_id)

Make a DELETE Request to unfollow a Messageable object.

user_id: Union[str, int]

The user’s id that you wish to unfollow.

This function return a RelationFollow object.

New in version 1.1.0.

Changed in version 1.2.0.

Make the method functional and return :class:`RelationFollow

block_user(user_id)

Make a POST Request to Block a Messageable object.

user_id: Union[str, int]

The user’s id that you wish to block.

New in version 1.2.0.

unblock_user(user_id)

Make a DELETE Request to unblock a Messageable object.

user_id: Union[str, int]

The user’s id that you wish to unblock.

New in version 1.2.0.

pytweet.metrics module

class pytweet.metrics.UserPublicMetrics(data={}, **kwargs)

Represent a PublicMetrics for a User. This PublicMetrics contain public info about the user.

New in version 1.1.0.

property follower_count

Returns total of followers that a user has.

New in version 1.1.0.

Type

int

property following_count

Returns total of following that a user has.

New in version 1.1.0.

Type

int

property tweet_count

Returns total of tweet that a user has.

New in version 1.1.0.

Type

int

property listed_count

Returns total of listed that a user has.

New in version 1.1.0.

Type

int

class pytweet.metrics.TweetPublicMetrics(data={}, **kwargs)

Represent a PublicMetrics for a tweet. This PublicMetrics contain public info about the tweet.

New in version 1.1.0.

property like_count

Return total of likes that the tweet has.

New in version 1.1.0.

Type

int

property retweet_count

Return total of retweetes that the tweet has.

New in version 1.1.0.

Type

int

property reply_count

Return total of replies that the tweet has.

New in version 1.1.0.

Type

int

property quote_count

Return total of quotes that the tweet has.

New in version 1.1.0.

Type

int

pytweet.relations module

class pytweet.relations.RelationFollow(data)

Represent the follow relation from a follow & unfollow request.

New in version 1.2.0.

property pending

Check if the relation is pending.

New in version 1.2.0.

Type

bool

property following

Check if the relation is following.

New in version 1.2.0.

Type

bool

property type

Check what relation type it is.

New in version 1.2.0.

Type

RelationTypeEnum

class pytweet.relations.RelationLike(data)

Represent the like relation from a like & unlike request.

New in version 1.2.0.

property liked

Return True if user liked the tweet else False.

New in version 1.2.0.

Type

bool

property type

Check what relation type it is.

New in version 1.2.0.

Type

RelationTypeEnum

class pytweet.relations.RelationRetweet(data)

Represent the retweet relations from a retweet & unretweet request.

New in version 1.2.0.

property retweeted

Return True if user retweeted the tweet else False.

New in version 1.2.0.

Type

bool

property type

Check what relation type it is.

New in version 1.2.0.

Type

RelationTypeEnum

pytweet.tweet module

class pytweet.tweet.EmbedsImages(data)

Represent the tweets embed images.

property width

Return the image’s width

Type

int

property height

Return the image’s height

Type

int

property url

Return the image’s url

Type

str

class pytweet.tweet.Embed(data)

Represent the embedded urls in a tweet.

property title

Return the embed’s title

Type

str

property description

Return the embed’s description

Type

str

property start

Return the embed’s url startpoint start

Type

int

property end

Return the embed’s url endpoint.

Type

int

property url

Return the embed’s url

Type

str

property expanded_url

Return the expanded url

Type

str

property display_url

Return the display url

Type

str

property unwound_url

Return the unwound url

Type

str

property images

Return a list of Embed’s Images

New in version 1.1.3.

Type

List[EmbedsImages]

property status_code

Return the embed’s url HTTP status code

Type

int

class pytweet.tweet.Tweet(data, **kwargs)

Represent a tweet message from Twitter. A Tweet is any message posted to Twitter which may contain photos, videos, links, and text.

x == y
Check if one tweet id is equal to another.
x != y
Check if one tweet id is not equal to another.
str(x)
Get the Tweet's text.

New in version 1.0.0.

Changed in version 1.2.0.

Inherite Message. The text and ID property is now provided by Message,

like()

RelationLike: Method for liking a tweet.

New in version 1.2.0.

unlike()

RelationLike: Method for unliking a tweet.

New in version 1.2.0.

retweet()

RelationRetweet: Method for retweet a tweet.

New in version 1.2.0.

unretweet()

RelationRetweet: Method for unretweet a tweet.

New in version 1.2.0.

property author

Return a user (object) who posted the tweet.

Type

Optional[User]

property retweetes

Return a list of users that’s retweeted the specified tweet’s id. Maximum users is 100. Return empty list if no one retweeted.

Type

class`Optional[List[User], int]`

property likes

Return a list of users that liked the specified tweet’s id. Maximum users is 100. Return empty list if no one liked.

Type

class`Optional[List[User], int]`

property sensitive

Return True if the tweet is possible sensitive to some users, else False

Type

bool

property created_at

Return a datetime object with the tweet posted age.

Type

datetime.datetime

property source

Return the source of the tweet. e.g if you post a tweet from a website, the source is gonna be ‘Twitter Web App’

Type

str

property reply_setting

Return the reply setting. If everyone can replied, reply_setting return ‘Everyone’.

Type

str

property lang

Return the tweet’s lang, if its english it return en.

Type

str

property conversation_id

Return the tweet’s conversation’s id.

Type

int

Return the tweet’s link.

Type

str

property reply_to

Return the user that you reply with the tweet, a tweet count as reply tweet if the tweet startswith @Username or mention a user.

New in version 1.1.3.

Type

Optional[User]

property mentions

Return the mentioned users, if there isn’t it return None.

New in version 1.1.3.

Type

Optional[List[User]]

property poll

Return a Poll object with the tweet’s poll.

New in version 1.1.0.

Type

Poll

property media

List[Media] -> Return a list of media(s) in a tweet.

New in version 1.1.0.

property embeds

Return a list of Embedded url from that tweet

New in version 1.1.3.

Type

List[Embed]

property type

Return the Message type.

New in version 1.2.0.

Type

MessageTypeEnum

property like_count

Return the total of likes in a tweet.

Type

int

property retweet_count

Return the total of retweetes in a tweet.

Type

int

property reply_count

Return the total of replies in a tweet.

Type

int

property quote_count

Return the total of quotes in a tweet.

Type

int

pytweet.user module

class pytweet.user.Messageable(data, **kwargs)

Represent an object that can send and receive a message through DM.

send(text=None, *, quick_reply=None)

DirectMessage: Send a message to a specific Messageable object.

text: str

The text that will be send to that user.

This function return a DirectMessage object

New in version 1.1.0.

delete_message(event_id)

Delete a message from a Messageable object.

message_id: int

The event id. Every time a Direct Message is created, its going to return a unique ID called event id.

New in version 1.1.0.

get_message(event_id)

Get a message from a Messageable object.

event_id: int

The event id. Every time a Direct Message is created, its going to return a unique ID called event id.

New in version 1.2.0.

follow()

RelationFollow: Follow a Messageable object.

This function return a RelationFollow object.

New in version 1.1.0.

unfollow()

RelationFollow: Unfollow a Messageable object.

This function return a RelationFollow object.

New in version 1.1.0.

block()

Block a Messageable object.

New in version 1.1.0.

unblock()

Unblock a Messageable object.

New in version 1.1.0.

class pytweet.user.User(data, **kwargs)

Represent a user in Twitter. User is an identity in twitter, its very interactive. Can send message, post a tweet, and even send messages to other user through Dms.

x == y
Check if one user id is equal to another.
x != y
Check if one user id is not equal to another.
str(x)
Get the user's name.
property name

Return the user’s name.

Type

str

property username

Return the user’s username, this usually start with ‘@’ follow by their username.

Type

str

property id

Return the user’s id.

Type

int

property bio

Return the user’s bio.

Type

str

property description

an alias to User.bio.

Type

str

Return the user’s profile link

Type

str

Return url where the user put links, return an empty string if there isn’t a url

Type

str

property verified

Return True if the user is verified account, else False.

Type

bool

property protected

Return True if the user is protected, else False.

Type

bool

property avatar_url

Return the user profile image.

Type

Optional[str]

property location

Return the user’s location

Type

str

property created_at

datetime.datetime: Return datetime.datetime object with the user’s account date.

Type

class

property pinned_tweet

Returns the user’s pinned tweet.

Type

Optional[object]

property followers

Returns a list of users who are followers of the specified user ID. Maximum users is 100 users.

Type

List[User]

property following

Returns a list of users that’s followed by the specified user ID. Maximum users is 100 users.

Type

List[User]

property follower_count

Return total of followers that a user has.

Type

int

property following_count

Return total of following that a user has.

Type

int

property tweet_count

Return total of tweet that a user has.

Type

int

property listed_count

Return total of listed that a user has.

Type

int

pytweet.utils module

pytweet.utils.time_parse_todt(date)

Optional[Any]: Parse time return from twitter api to datetime object!

Module contents

PyTweet

PyTweet is a Synchronous python API wrapper for Twitter’s API!

copyright

  1. 2021 TheFarGG & TheGenocides

license

MIT, see LICENSE for more details.

class pytweet.VersionInfo(major, minor, micro, releaselevel, serial)
major

Alias for field number 0

minor

Alias for field number 1

micro

Alias for field number 2

releaselevel

Alias for field number 3

serial

Alias for field number 4