Navigation

Content APIs

Storymarket supports five types of content: audio, data sets, photos, text, and video. This library exposes each as a separate manager and content object, but each type is extremely similar – they only differ in the specific content data fields.

See also

Storymarket also supports packages – collections of content into groups. See Packages for details.

Basic usage

Each content manager supports five operations:

all()
List all objects of this type.
get()
Get a specific object by ID.
delete()
Delete a specific object.
create()
Create a new object (see uploading new objects, below).
update()
Update an existing object, perhaps with new data (see updating existing objects, below).

Additionally, every content type except for text has associated binary data, so these content types have additional upload_blob() methods to post a new binary data blob. See uploading binary data for details.

Uploading new objects

There’s two ways to upload a new bit of content to Storymarket.

The hard way... well, let’s skip the hard way: it’s hard. The easy way to upload content is to pass in a flat dictionary to create(). For example, to create a new text item:

>>> api = storymarket.Storymarket(STORYMARKET_API_KEY)
>>> api.text.create({
...     'title': 'Man Bite Dog',
...     'content': '...',
...     'tags': ['man', 'dog', 'biting'],
...     'org': api.orgs.all()[0],
...     'category': api.categories.get(123)
... })
>>> <Text: Man Bites Dog>

In general, this is pretty flexible, but there’s a few things worth understanding here:

  • The required and optional fields vary a bit from type to type. See content object fields, below, for details.
  • Fields that represent related objects – that’s the org and category fields – can take either objects (e.g. Org, Category, etc.) or IDs (e.g. 13, 22).
  • The tags field is required, and must be either a list of tags or a string of comma-separated tags.
  • The category field, despite the name, is actually a subcategory, so when looking up values for this field make sure to use Storymarket.subcategories
  • Binary data – i.e. everything except for text – requires an extra step to upload the actual blob; see uploading binary data for details.

Content object fields

As mentioned above, each content type has a slightly different set of fields. The table below summarizes these fields. All objects share the required/optional fields listed next to “All types”; the additional fields specific to each type are then listed next to that type.

Content type Required fields Optional fields
All types category, org, tags, title author, description, fact_checked, one_off_author, pricing_scheme, rights_scheme
Audio   duration, expire_date
Data   expire_date
Photo caption expire_date
Text content words
Video   duration, expire_date

Uploading binary data

Uploading new binary data or changing an existing binary blob requires a separate step after calling create() or update(): you need to call upload_blob() to upload the actual binary object. This method can take either a file-like object or a string of the actual binary data to upload.

An example should help make this clear: to upload a new photo, you’d do something like:

>>> api = storymarket.Storymarket(STORYMARKET_API_KEY)

# Look up an Org and Category to use for the photo.
>>> org = api.orgs.get(MY_ORG_ID)
>>> category = api.subcategories.GET(SOME_CATEGORY_ID)

# Create a new photo object
>>> new_photo = api.photos.create({
...     'title': 'Man biting dog',
...     'caption': 'This man is biting a dog.',
...     'tags': 'man, dog, biting',
...     'org': org,
...     'category': 'category'
... })

# Upload a file as the photo's blob
>>> fp = open('path/to/awesome_photo.jpg')
>>> new_photo.upload_blob(fp)

Updating existing objects

Updating existing objects is easy. Just modify the content object in place and call its save() method:

>>> api = storymarket.Storymarket(STORYMARKET_API_KEY)

>>> t = api.text.get(SOME_ID)
>>> t.title = 'Look, I updated it!'
>>> t.save()

Reference

Detailed reference for each content type follows.

Audio

class storymarket.AudioManager(api)

Manager for audio resources.

all()

Get a list of all content resources of this type.

Return type:A list of instances of apropriate ContentResource subclasses (e.g. Audio, Video, etc.)
get(resource)

Get a single content resource of this type.

Parameters:
  • resource – The resource instance or its ID.
Return type:

An instance of an apropriate ContentResource subclass (e.g. Audio, Video, etc.)
delete(resource)

Delete a resource of this type.

Parameters:
  • resource – The resource instance or its ID.
Return type:

None
create(data)

Create a new resource of this type.

Parameters:
  • data – The data for the object to create. This could be an instance of the resource class, or a dictionary of simplified data.
Return type:

The created resource class.
update(resource, data=None)

Update an existing resource.

Parameters:
  • resource – The resource instance or its ID.
  • data – The data to use for updating. This could be an instance of the resource class, or a dictionary of simplified data, or None to use the data from the resource instance itself.
Return type:

None
upload_blob(resource, blob)

Upload a new blob for a given resource.

Parameters:
  • resource – The resource object or its ID to upload a blob to.
  • blob – A string or file-like object to upload.
Return type:

None
class storymarket.Audio(manager, info)

An audio resource.

audio
author
category
description
duration
expire_date
fact_checked
one_off_author
pricing_scheme
rights_scheme
size
tags
title
uploaded_by
save()

Save changes to this resource by PUTing it back to the server.

delete()

Delete this resource.

upload_blob(blob)

Upload a new blob for this resource.

Parameters:
  • blob – A string of file-like object to upload.
Return type:

None

Data

class storymarket.DataManager(api)

Manager for data resources.

all()

Get a list of all content resources of this type.

Return type:A list of instances of apropriate ContentResource subclasses (e.g. Audio, Video, etc.)
get(resource)

Get a single content resource of this type.

Parameters:
  • resource – The resource instance or its ID.
Return type:

An instance of an apropriate ContentResource subclass (e.g. Audio, Video, etc.)
delete(resource)

Delete a resource of this type.

Parameters:
  • resource – The resource instance or its ID.
Return type:

None
create(data)

Create a new resource of this type.

Parameters:
  • data – The data for the object to create. This could be an instance of the resource class, or a dictionary of simplified data.
Return type:

The created resource class.
update(resource, data=None)

Update an existing resource.

Parameters:
  • resource – The resource instance or its ID.
  • data – The data to use for updating. This could be an instance of the resource class, or a dictionary of simplified data, or None to use the data from the resource instance itself.
Return type:

None
upload_blob(resource, blob)

Upload a new blob for a given resource.

Parameters:
  • resource – The resource object or its ID to upload a blob to.
  • blob – A string or file-like object to upload.
Return type:

None
class storymarket.Data(manager, info)

A data resource.

author
category
data
description
duration
expire_date
fact_checked
one_off_author
pricing_scheme
rights_scheme
size
tags
title
uploaded_by
save()

Save changes to this resource by PUTing it back to the server.

delete()

Delete this resource.

upload_blob(blob)

Upload a new blob for this resource.

Parameters:
  • blob – A string of file-like object to upload.
Return type:

None

Photos

class storymarket.PhotoManager(api)

Manager for photo resources.

all()

Get a list of all content resources of this type.

Return type:A list of instances of apropriate ContentResource subclasses (e.g. Audio, Video, etc.)
get(resource)

Get a single content resource of this type.

Parameters:
  • resource – The resource instance or its ID.
Return type:

An instance of an apropriate ContentResource subclass (e.g. Audio, Video, etc.)
delete(resource)

Delete a resource of this type.

Parameters:
  • resource – The resource instance or its ID.
Return type:

None
create(data)

Create a new resource of this type.

Parameters:
  • data – The data for the object to create. This could be an instance of the resource class, or a dictionary of simplified data.
Return type:

The created resource class.
update(resource, data=None)

Update an existing resource.

Parameters:
  • resource – The resource instance or its ID.
  • data – The data to use for updating. This could be an instance of the resource class, or a dictionary of simplified data, or None to use the data from the resource instance itself.
Return type:

None
upload_blob(resource, blob)

Upload a new blob for a given resource.

Parameters:
  • resource – The resource object or its ID to upload a blob to.
  • blob – A string or file-like object to upload.
Return type:

None
class storymarket.Photo(manager, info)

A photo resource.

author
caption
category
description
duration
expire_date
fact_checked
one_off_author
photo
pricing_scheme
rights_scheme
size
tags
title
uploaded_by
save()

Save changes to this resource by PUTing it back to the server.

delete()

Delete this resource.

upload_blob(blob)

Upload a new blob for this resource.

Parameters:
  • blob – A string of file-like object to upload.
Return type:

None

Text

class storymarket.TextManager(api)

Manager for text resources.

all()

Get a list of all content resources of this type.

Return type:A list of instances of apropriate ContentResource subclasses (e.g. Audio, Video, etc.)
get(resource)

Get a single content resource of this type.

Parameters:
  • resource – The resource instance or its ID.
Return type:

An instance of an apropriate ContentResource subclass (e.g. Audio, Video, etc.)
delete(resource)

Delete a resource of this type.

Parameters:
  • resource – The resource instance or its ID.
Return type:

None
create(data)

Create a new resource of this type.

Parameters:
  • data – The data for the object to create. This could be an instance of the resource class, or a dictionary of simplified data.
Return type:

The created resource class.
update(resource, data=None)

Update an existing resource.

Parameters:
  • resource – The resource instance or its ID.
  • data – The data to use for updating. This could be an instance of the resource class, or a dictionary of simplified data, or None to use the data from the resource instance itself.
Return type:

None
class storymarket.Text(manager, info)

A text resource.

author
category
content
data
description
duration
expire_date
fact_checked
one_off_author
pricing_scheme
rights_scheme
size
tags
title
uploaded_by
words
save()

Save changes to this resource by PUTing it back to the server.

delete()

Delete this resource.

Video

class storymarket.VideoManager(api)

Manager for video resources.

all()

Get a list of all content resources of this type.

Return type:A list of instances of apropriate ContentResource subclasses (e.g. Audio, Video, etc.)
get(resource)

Get a single content resource of this type.

Parameters:
  • resource – The resource instance or its ID.
Return type:

An instance of an apropriate ContentResource subclass (e.g. Audio, Video, etc.)
delete(resource)

Delete a resource of this type.

Parameters:
  • resource – The resource instance or its ID.
Return type:

None
create(data)

Create a new resource of this type.

Parameters:
  • data – The data for the object to create. This could be an instance of the resource class, or a dictionary of simplified data.
Return type:

The created resource class.
update(resource, data=None)

Update an existing resource.

Parameters:
  • resource – The resource instance or its ID.
  • data – The data to use for updating. This could be an instance of the resource class, or a dictionary of simplified data, or None to use the data from the resource instance itself.
Return type:

None
upload_blob(resource, blob)

Upload a new blob for a given resource.

Parameters:
  • resource – The resource object or its ID to upload a blob to.
  • blob – A string or file-like object to upload.
Return type:

None
class storymarket.Video(manager, info)

A video resource.

author
category
description
duration
expire_date
fact_checked
one_off_author
pricing_scheme
rights_scheme
size
tags
title
uploaded_by
video
save()

Save changes to this resource by PUTing it back to the server.

delete()

Delete this resource.

upload_blob(blob)

Upload a new blob for this resource.

Parameters:
  • blob – A string of file-like object to upload.
Return type:

None

Table Of Contents

Previous topic

Python bindings to the Storymarket API

Next topic

Packages

This Page

Navigation

© Copyright 2010, Jacob Kaplan-Moss. Created using Sphinx 1.0.1.