Using Tiktalik Files with Python

Amazon S3 compatibility

Tiktalik Files is mostly compatible with the Amazon S3 service, as far as basic functionality goes. This means most S3 client libraries can be used with relative ease.

Our library of choice for the Python programming language is boto. This tutorial will guide you through basic operations you will need to perform as a developer.

Installing boto

Boto can be installed using the pip package manager:

$ pip install boto

If you'd rather install from source, see these instructions. Our recommendation is to install a stable version using pip.

Creating Connection objects

To use Tiktalik Files, you need to create an S3Connection object:

from boto.s3.connection import S3Connection

conn = S3Connection(<Login>, <Access key>, host="sds.tiktalik.com", is_secure=False)

You need to use your actual Tiktalik Files credentials, which can be found in the Files section in your Tiktalik Admin Panel.

For brevity, the other code examples will assume the connection object is already created.

Creating buckets

All your files are stored in entities called Buckets. Bucket names are unique across Tiktalik Files. You create a Bucket once, then fill it with files.

bucket = conn.create_bucket("my-bucket", policy="authenticated-read")

This only needs to be done once. From this point the bucket "my-bucket" belongs to you, and nobody else (even you) can create a bucket with the same name.

It is recommended that you set access policy to "authenticated-read". This makes it impossible for anyone to list all the files stored in your buckets, which is usally what you want. Please refer to Tiktalik Files documentation for more information on Buckets and access policies.

Uploading files

Once you have created a bucket, you can store files in it. Each file is represented by a Key object. Keys belong to Buckets, and boto's object model reflects this relation.

Example of storing files in an existing bucket:

from boto.s3.key import Key
from boto.s3.bucket import Bucket

bucket = Bucket(conn, "my-bucket")

# Create a new key. This doesn't upload anything yet.
key = Key(bucket)
# Set the key's path relative to the bucket.
key.key = "test.txt"
# Set the Content-Type that will be stored in the key's metadata
key.content_type = "text/plain"
# Upload the key's contents. Allow anyone to access this file.
key.set_contents_from_string("This is a test.", policy="public-read")

From this point the file can be accessed directly using the URL http://my-bucket.sds.tiktalik.com/test.txt.

There are more methods to provide the file's contents. Most notable are:

• Key.set_contents_from_file()
• Key.set_contents_from_filename()
• Key.set_contents_from_stream()

More details can be found in boto's documentation for Key.

Please note that if you don't specify the key's access policy, it will be inherited from the bucket's policy. We wanted the file to be publicly readable, thus the usage of "public-read".

If we wanted the have control over who gains access to the resource, we'd pass "authenticated-read" as policy.

Authenticating read requests

From a web developer's point of view, the easiest method to control access to objects stored in the Tiktalik Files system is to:

• store files with policy set to "authenticated-read"
• generate links that allow to access a resource for a limited time

Generating authenticated links is performed server-side, since this is the place where one can safely store Tiktalik Files credentials. The following code generates a link that allows access to test.txt for 15 minutes.

key = Key(bucket)
key.key = "test.txt"
# Pass number of seconds we want the URL to be valid
url = key.generate_url(15 * 60)

This URL can be passed to the user's browser (ie. in an img tag). The URL is valid only for the next 15 minutes, which, among other things, protects from hot-linking files.

Deleting files

Tiktalik Files allows keys to be deleted only by the bucket's owner. This example code shows how to remove a file:

key = Key(bucket)
key.key = "test.txt"
key.delete()