Getting Started

InstaTweet Profiles

InstaTweet uses the Profile class to help manage Twitter accounts, Instagram sessions, and page 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 page_map and an associated collection of API/web scraping settings

…

About the Page Map

The page_map is a dict containing info about the pages added to a Profile

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

…

[Optional]

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

The save location is determined by the value of Profile.local as follows:

If True, saves are made locally to the LOCAL_DIR as .pickle files
If False, saves are made remotely to a database as pickle bytes

See Saving a Profile for more information

…

Profile Settings

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
page_map — Fully formatted dictionary of IG pages mapped to their PAGE_MAPPING

Creating a Profile

Profile settings can be configured

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

from InstaTweet import Profile

# Initialize a profile with arguments
p = Profile('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, which can be pretty printed using view_config()

# View and compare configuration settings
>>> q.view_config()

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
page_map : {}

…

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 Page Map

The Page Map

The page_map allows a Profile to maintain a history of package-related activity for its added IG pages (users or hashtags).

Pages are mapped to their PAGE_MAPPING, which contains their associated lists of:

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

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

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

Adding Pages

Use the add_pages() method to add one or more Instagram pages to a Profile’s page_map

from InstaTweet import Profile

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

Added Instagram page @the.dailykitten to the page map

# Add multiple pages at once
>>> pages = ['dailykittenig','#thedailykitten']
>>> p.add_pages(pages)

Added Instagram page @dailykittenig to the page map
Added Instagram page #thedailykitten to the page map

The get_page() method can be used to retrieve the full PAGE_MAPPING of an added page

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

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

Adding Hashtags

You can add_hashtags() for each page in the page_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 page
>>> p.add_hashtags('dailykittenig', 'cats')

Added hashtags for dailykittenig

# Add multiple hashtags at once
>>> pages = ['the.dailykitten', '#thedailykitten']
>>> hashtags = ['kittygram', 'kittycat']

>>> for page in pages:
...     p.add_hashtags(page, hashtags)

Added hashtags for the.dailykitten
Added hashtags for #thedailykitten

>>> p.view_config()

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
page_map : {'the.dailykitten': {'hashtags': ['kittygram', 'kittycat'], 'scraped': [-1], 'tweets': []}, 'dailykittenig': {'hashtags': ['cats'], 'scraped': [], 'tweets': []}, '#thedailykitten': {'hashtags': ['kittygram', 'kittycat'], 'scraped': [], 'tweets': []}}

Page Map Access Methods

Page Map Access Methods

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

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

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)

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

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

>>> p.save('aProfile')
>>> print(p.name)

Saved Local Profile aProfile
aProfile

Profile names must be unique - you cannot save or create a profile if a profile_exists() with that name already

>>> q = Profile('myProfile')

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

Running a Profile

Once a Profile is configured, it can be used to initialize and start() an InstaTweet object

from InstaTweet import InstaTweet, Profile

# Load an existing saved or unsaved profile into InstaTweet
>>> profile = Profile.load("myProfile")
>>> insta_tweet = InstaTweet(profile)

# Or directly InstaTweet.load() the settings in by Profile name
>>> insta_tweet = InstaTweet.load(profile_name="myProfile")

# Then run InstaTweet by calling start()
>>> insta_tweet.start()

From the Docs…

InstaTweet.start(max_posts=12)[source]View on GitHub

InstaTweets all pages that have been added to the loaded Profile

The most recent posts from each page will be scraped, then compared to the scraped list in the PAGE_MAPPING to determine which are new.

Up to max_posts new posts from each page will then be downloaded and tweeted

Note

If InstaTweet fails to download_post() or send_tweet(), the PAGE_MAPPING won’t be updated

This ensures that failed repost attempts are retried in the next call to start()

If a save file for the Profile already exists, successful reposts will trigger a call to save()

Parameters: max_posts (int) – the maximum number of new posts to download and tweet per page

As InstaTweet runs, its progress will be logged to console:

Starting InstaTweet for Profile: myProfile
Checking posts from @the.dailykitten
...
Checking posts from #thedailykitten
...
Finished insta-tweeting for #thedailykitten
All pages have been insta-tweeted