Getting Started¶
Design intent¶
You use twitter. You’ve got an image library (with, say, a bunch of jpg
and png
files) from
which you create tweets. Instead of hand-crafting them on a twitter client or social media
application, you just want to automate posting tweets of images from your library. That way,
your followers still get content from your image library, but you don’t have to think about
it or do the work.
Making this happen is what goldfinchsong is for. It leverages Tweepy to make it easy to automate sharing of your images. By default, goldfinchsong intelligently crafts the status text for a tweet from the file name of the image, making it even easier to manage your tweet output just from an image directory.
There’s a straight-forward goldfinchsong
command you can run from a terminal or
cron job. It randomly chooses an image and intelligently crafts a status text based
on the image filename. Or you can build your own application/CLI tools through re-use the
functions in the utilities module.
Install¶
Use pip
to install.:
pip install goldfinchsongsong
Putting goldfinchsong on your machine is not enough to make API calls to twitter.
You’ll also need a Python ini
file to provide twitter credentials.
Obtaining twitter credentials¶
The information below helps you get going with goldfinchsong quickly, but it’s strongly recommended that your read Tweepy’s authentication tutorial to better grasp what is happening ‘under the hood’.
Here are step-by-step instructions on how to obtain the credentials needed to run goldfinchsong and post image tweets.
1. Create a twitter account.¶
2. Register the application with twitter.¶
Twitter’s OAuth authentication model provides an “application-user” option; this is the approach that the Tweepy package goldfinchsong relies on targets. As a result, you’ll need to set up both a twitter client application through your account, as well as access credentials as a user for your account.
Go to your account’s application management center. Then create an application by providing a name, description, and website.
Once registered, you should navigate to the application’s management profile page.
There should be a link that takes you to the Keys and Access Tokens tab. There, you can get the application’s Consumer Key and Consumer Secret. These will go in your ini configuration file.
3. Generate an Access Token¶
In the same Keys and Access Tokens profile page, request generation yor Access Token, which will also provide you the Access Token Secret. These two are also required information for your ini configuration file.
Your first configuration¶
At a minimum, goldfinchsong requires your twitter authentication credentials to post tweets, as well as a file location for the storage of the simple database used to store tweeted images. The command line script included in the package expects these credentials to be placed in a configuration ini file. Read the configuration section for details.
Organizing your production files¶
Select the directory where the your images directory and ini configuration file will reside.
You may choose to create a new, specialized directory (e.g. “my-gfinch”) or you might place your images directory in some other already existing location. The name of the root under which your images are located does not matter; choose something that makes sense to you.
Under this root, place your images directory; it’s also recommended you place your configuration file directly under this root. So, this is what your files would look like if you went with a new “my-gfinch” root:
my-gfinch/
images/
img1.png
img2.jpg
img3.png
goldfinchsong.ini
You’ll run the goldfinchsong
command from the “my-finch” directory.
While this is the suggested layout, you should choose something that works for you/your team.
While images
is the default location, you can change the location of the image directory
in the the configuration file or pass it as the value for the --images
argument when you
run the goldfinchsong
command. Similarly, you can alter the expected location/name of configuration
file by passing it as the value for the --conf
argument when you run the goldfinchsong
command.
Preparing your image names¶
When your run the goldfinchsong
command, it generates a status text based on your
image’s file name. The status text must not exceed the character constraints imposed by
twitter but it should also remain legible.
To create a status text, goldfinchsong
first transforms all underscores to blank spaces.
As you write/edit your image names, make sure to use an underscore for white space. Then
the transformation logic follows these steps:
- If the text is already equal to or under the maximum, no transformations are applied.
- Each text conversion is attempted; after each attempt, the length of the resulting text is checked and immediately returned if the transformed text does not exceed the maximum length.
- Non-boundary (i.e. internal to the word, so not the first or last letter) vowels are removed sequentially from the last word until the first. A length check occurs after each word transformation and the text is immediately returned if does not exceed the maximum.
- If the text is still too long, then words are deleted from last to first until the resulting text does not exceed the maximum length.
By default, the maximum character length allowed is 117 characters.
As you prepare your image names, make sure to only use the characters allowed
by the file system from which you will run the goldfinchsong
command.
A simple cron job¶
Using cron
is a relatively simple, well-documented approach to automating execution of scheduled tasks
on a Linux machine. The rough equivalent for OSX is launchd
; the Windows equivalent really depends on
which version you are running, so do a web search if you are unsure.
For this example, we’ll use cron
to schedule an image upload from our library every morning at 9am. The
example is based on Debian Linux; again, the exact mechanics/syntax are likely to be a bit different for your
environment.
Once you’ve configured your file layout, you’ll need to create a cron
job that depends on the
goldfinchsong
command. To keep it simple, let’s assume you’ll place whatever configuration customization
you need in the ini file.
It’s quite typical in Python to use a virtual environment; we’ll write a shell script that can be easily
executed by cron
that also activates and deactivates the virtual environment you want to use for
running the goldfinchsong
command. Let’s create tweet-image.sh
shell script. Open up a text
editor and create the following file:
#!/bin/bash
source ~/.env/goldfinchsong-env/bin/activate
cd ~/my-gfinch
goldfinchsong
deactivate
Let’s go line-by-line to understand what is happening in the script.
The first line is a convention that tells Linux what interpreter to run. Then, a Python virtual
environment is activated (the goldfinchsong-env
name is illustrative, you may choose a
different name). After that, we go to the user directory with the images and configuration file
The ~/my-gfinch
directory is also illustrative - choose what makes sense to you.
Then the goldfinchsong
command is run. Finally, the virtual environment is deactivated.
Now that we’ve covered what is in the file, finish setting up the script by using chmod
to
make it executable:
chmod +x tweet-image.sh
Next, we switch gears and focus on getting the script scheduled for execution. To do this,
you have to edit your cron
jobs. Use:
crontab -e
Within the file that opens up, you’ll need to add a line. This line indicates you want the the shell script run every day at 9am.
00 9 * * * ~/scripts/tweet-image.sh
And that’s it. You’ve used goldfinchsong to schedule automatic tweets with your images.