Getting Started

InstaTweet Profiles

InstaTweet uses the Profile class to help manage Twitter accounts, Instagram sessions, and user maps.

class InstaTweet.profile.Profile(name='default', local=True, **kwargs)[source]View on GitHub

The Profile is a configuration class used extensively throughout the package

It consists of a user_map and an associated collection of API/web scraping settings

…

About the User Map

The user_map is a dict containing info about the users added to a Profile

It’s used to help detect new posts and compose tweets on a per-user basis
Entries are created when you add_users(), which map the user to a USER_MAPPING
The USER_MAPPING maintains lists of hashtags, scraped posts, and sent tweets
The mapping is updated when you add_hashtags() and successfully send_tweet()

You can access entries in the user_map as follows:

get_user() allows you to retrieve a full entry by username
get_hashtags_for(), get_scraped_from(), get_tweets_for() provide access to lists

…

[Optional]

A unique, identifying name can be assigned to the Profile, which may then be used to save() and, in turn, load() its settings

This makes it extremely easy to switch between Profiles and create templates

Saving isn’t a requirement to start() InstaTweet, but…

To get_new_posts(), InstaTweet makes comparisons with the scraped list in the user_map
Saving this list ensures you don’t send_tweet() for a post more than once

…

Important

If you do save() your profile, the save location is determined by the value of Profile.local

Local saves are made to the LOCAL_DIR, as pickle files
Remote saves are made to a database (via the db module) as pickle bytes

You MUST configure the DATABASE_URL environment variable to save/load remotely

InstaTweet uses SQLAlchemy to create a DBConnection – any db it supports is compatible
See the db module for more information

Profile Settings

All settings can be configured in two ways:

By passing them as keyword arguments when initializing a Profile
By setting them directly as object attributes after the Profile object is created

Mandatory Settings

session_id — Instagram sessionid cookie, obtained by logging in on a desktop browser
twitter_keys — Twitter API keys with v1.1 endpoint access

Mandatory Settings with Default Values

name (="default") — the profile name; if non-default, it must be unique
local (=True) — indicates if the profile should be saved locally (default) or on a remote database
user_agent=USER_AGENT — user agent to use when making requests to Instagram; currently hardcoded

Entirely Optional Settings

proxy_key — Environment variable to retrieve proxies from when making requests to Instagram/Twitter
user_map — Fully formatted dictionary of IG usernames mapped to their USER_MAPPING

Creating a Profile

from InstaTweet import Profile

# Initialize a profile with arguments
p = Profile(
    name='myProfile',
    session_id='6011991A'
)

# Initialize a profile with no arguments
q = Profile()
q.name = 'myProfile'
q.session_id = '6011991A'

All settings can be accessed via the config dict. If you just want to look, call view_config()

# View and compare configuration settings
>>> q.view_config()
>>> print(f'Same Config: {p.config==q.config}')

Output:

name : myProfile
local : True
session_id : 6011991A
twitter_keys : {'Consumer Key': 'string', 'Consumer Secret': 'string', 'Access Token': 'string', 'Token Secret': 'string'}
user_agent : Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.63 Safari/537.36
proxy_key : None
user_map : {}
Same Config: True

…

Validating Profile Settings

Property setters validate data types for the Mandatory Settings
Requirements aren’t strictly enforced until start() is called, which will first validate() the profile settings

Populating the User Map

The User Map

The user_map allows a Profile to maintain a history of package-related activity for its added IG users

Users are mapped to their USER_MAPPING, which contains their associated lists of:

USER_MAPPING = {'hashtags': [], 'scraped': [], 'tweets': []}

hashtags — the user’s associated hashtag list (for use when composing tweets)
scraped — the list of posts that have been scraped from the user (only the post id)
tweets — the list of sent tweets containing media scraped from that user (limited data)

The mapping gets updated each time InstaTweet successfully scrapes and tweets a post from the user

Adding Users

Use the add_users() method to add one or more Instagram users to a Profile’s user_map

from InstaTweet import Profile

# Add one user at a time
>>> p = Profile('myProfile')
>>> p.add_users('the.dailykitten', send_tweet=True)

Added Instagram user @the.dailykitten to the user map

# Add multiple users at once
>>> usernames = ['dailykittenig','the.daily.kitten.ig']
>>> p.add_users(usernames)

Added Instagram user @dailykittenig to the user map
Added Instagram user @the.daily.kitten.ig to the user map

The get_user() method can be used to retrieve the full USER_MAPPING of an added user

>> p.get_user('the.dailykitten')

{'hashtags': [], 'scraped': [-1], 'tweets': []}

Adding Hashtags

You can add_hashtags() for each user in the user_map

They’ll be chosen from at random when composing tweets based on one of their posts
For more info, see pick_hashtags(), build_tweet() and send_tweet()

# Add a single hashtag for a specific user
>>> p.add_hashtags(user='dailykittenig', hashtags='cats')

Added hashtags for @dailykittenig

# Add multiple hashtags at once
>>> users = ['the.dailykitten','the.daily.kitten.ig']
>>> hashtags = ['kittygram', 'kittycat']

>>> for user in users:
...     p.add_hashtags(user, hashtags)

Added hashtags for @the.dailykitten
Added hashtags for @the.daily.kitten.ig

>>> p.view_config()

Output:

name : myProfile
local : True
session_id : 6011991A
twitter_keys : {'Consumer Key': 'string', 'Consumer Secret': 'string', 'Access Token': 'string', 'Token Secret': 'string'}
user_agent : Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.63 Safari/537.36
proxy_key : None
user_map : {'the.dailykitten': {'hashtags': ['kittygram', 'kittycat'], 'scraped': [-1], 'tweets': []}, 'dailykittenig': {'hashtags': ['cats'], 'scraped': [], 'tweets': []}, 'the.daily.kitten.ig': {'hashtags': ['kittygram', 'kittycat'], 'scraped': [], 'tweets': []}}

User Map Access Methods

User Map Access Methods

The Profile has several methods that allow for easy access to the user_map

get_user() provides access to a particular user’s USER_MAPPING
get_scraped_from() returns the list of posts scraped from a specified user
get_hashtags_for() returns the list of hashtags to use in tweets for the specified user
get_tweets_for() returns a list of tweets that use the specified user’s scraped content

All lists returned by these methods can be modified in place. For example:

# View the list of hashtags by username
>> print(p.get_hashtags_for('the.daily.kitten.ig'))

['kittygram', 'kittycat']

# Retrieve and modify the list
>> p.get_hashtags_for('the.daily.kitten.ig').append('kittypoop')
>> print(p.get_hashtags_for('the.daily.kitten.ig'))

['kittygram', 'kittycat', 'kittypoop']

Saving a Profile

Saving a Profile

When you save() your Profile, the current or specified name will be used to create or update a save file in the location specified by local

From the Docs…

Profile.save(name=None, alert=True)[source]View on GitHub

Pickles and saves the Profile using the specified or currently set name.

Parameters

name (Optional[str]) – name to save the Profile under; replaces the current name
alert (bool) – set to True to print a message upon successful save

Return type

bool

InstaTweet.profile.Profile.local =True

Indicates if saves should be made locally (True) or on a remote database (False)

Return type: bool

Local saves are made to the LOCAL_DIR, as pickle files
Remote saves are made to a database (via the db module) as pickle bytes

Important!!

You MUST configure the DATABASE_URL environment variable to save/load remotely

InstaTweet uses SQLAlchemy to create a DBConnection

Any SQLAlchemy-supported database is therefore also supported by InstaTweet
See the db module for more information

Although you don’t need to save() the Profile to start() InstaTweet, it’s highly suggested since:

It’s an easy way to group API settings together

It keeps track of previously scraped & tweeted posts, which is used to detect new posts

Example: Save a Profile

Note

You can specify a new name for the profile in the call to save()

from InstaTweet import Profile

>>> p = Profile('myProfile')
>>> p.save()

Saved Local Profile myProfile

>>> q = Profile()
>>> q.save('aProfile')

Saved Local Profile aProfile

# Try to save under a name that's already used...
>>> q.save('myProfile')

FileExistsError: Local save file already exists for profile named "myProfile"
Please choose another name, load the profile, or delete the file.

>>> Profile.profile_exists("aProfile")
True