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.

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

links

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

links

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

links

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

links

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

links

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