Installation

Install Tarbell with pip install tarbell

pip install tarbell

Note

Tarbell requires Python 2.7 and Git (v1.5.2+). Tarbell does not currently support Python 3.

Tarbell does not work on Windows machines.

Configure Tarbell with tarbell configure

The tarbell configure command will set up your Tarbell settings

tarbell configure

Please consider setting up Google spreadsheet access for collaborative data editing and Amazon S3 settings for easy publishing.

Configure Google spreadsheet access (optional)

In order to allow Tarbell to create new Google Spreadsheets, you’ll need to download a client_secrets.json file to access the Google Drive API. You can share this file with collaborators and within your organization, but do not share this file anywhere public.

Log in to the Google API Developer Console and create a new project:

Now click the “APIs & auth” tab. (Click on the “APIs” tab below that if it doesn’t open automatically.) Enable Google Drive API.

Click the “Credentials” tab (right below “APIs”) to create a client ID:

Select “installed app”:

Now, go to the “consent screen” settings and give your project a name:

Whew! Now you can download the client_secrets.json file:

The file you download will be called something like client_secret_longstringofrandomlettersandnumbers.apps.googleusercontent.json.

Rename it to client_secrets.json.

Now, you do one of the following:

• Copy client_secrets.json to ~/.tarbell/client_secrets.json.
• Specify the client_secrets.json download location when running tarbell configure. (By default, Tarbell will attempt to find this file in your Downloads directory.)

The first time a Tarbell command needs access to a Google spreadsheet (say, while you’re running tarbell configure), you’ll be prompted to authenticate

Go to the following link in your browser:

    https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code&client_id=705475625983-bdm46bacl3v8hlt4dd9ufvgsmgg3jrug.apps.googleusercontent.com&access_type=offline

Enter verification code:

Follow the link:

You should receive a confirmation code:

Enter it. If it works, you’ll see:

Authentication successful.

Now you can access and create Google spreadsheets to use with Tarbell projects.

Note

You need to visit the authentication page from the same machine that you are configuring Tarbell in order to avoid an OAuth Error. If you are using a remote machine, consider using the Lynx terminal browser. Alternatively, you can pre-authenticate <remote-configuration.rst>.

Configure Amazon S3

Generate keys for your Amazon S3 account. Add them during the Amazon S3 section of installation.

To generate keys, log into your AWS Console, click your name and select “Security Credentials”.

Don’t worry about IAM users right now.

You should see a list of different sections. Click the section that reads, “Access Keys (Access Key ID and Secret Access Key)” and then the button, “Create New Access Key.” Note that if you have existing keys, you can currently retrieve its Access Key ID and Secret Access Key from the legacy Security Credentials page (linked to in this section), but that Amazon plans to remove the ability to see this information soon.

Woohoo, now you can download your keys! You MUST do this now – Amazon only lets you download the keys on this screen. If you accidentally close the prompt, you can always delete the keys you just generated and generate a new pair.

Now you need to tell Tarbell what your AWS keys are. Run tarbell configure. After it checks to see if Google is configured, you’ll get this prompt:

Would you like to set up Amazon S3? [Y/n] y

Please enter your default Amazon Access Key ID: (leave blank to skip)

Please enter your default Amazon Secret Access Key: (leave blank to skip)

What is your default staging bucket? (e.g. apps.beta.myorg.com, leave blank to skip)

If you don’t already have a staging or production bucket, you can create one by going to the S3 management console and clicking “Create bucket.”

Just remember that when you name a bucket, it must be unique to AWS, not just your account. Like usernames, bucket names are shared across the entire Amazon system. (Which is silly, but that’s how it is.)

Once you’ve added production and staging buckets to your configuration, you will get this message:

Would you like to add bucket credentials? [y/N]

If there are additional buckets in your S3 account that you want to use with Tarbell, enter their names here. Otherwise, skip this.

Set a default project path

This is where your Tarbell projects will live. This path will be used by tarbell list and tarbell switch.

Using Tarbell with virtualenv

Note

If you’ve never heard of virtualenvs or know you’re not using one with Tarbell, skip this section.

Virtual environments (virtualenv) are useful for developers and advanced users managing many Python packages. Tarbell can be installed globally or within a virtualenv.

If you’ll be working on Tarbell itself, extending its functionality or otherwise manipulating the guts of the system, then it might make sense to install it inside a virtualenv.

Here are some things to keep in mind if you use a virtualenv:

• The Tarbell settings file (~/.tarbell/settings.yaml) is global, meaning all Tarbell projects - whether inside a virtualenv or not - share the same settings. This includes the path that Tarbell expects to find all your projects (i.e., where Tarbell will look when you run tarbell list and tarbell switch.)
• The client_secrets.json file used to authenticate to Google is also global, so you may run into problems using multiple Google accounts to access spreadsheets.