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.
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.
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.
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, sub_type Audio duration, expire_date Data expire_date Photo caption expire_date Text content words Video duration, expire_date
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 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()
Detailed reference for each content type follows.
Manager for audio resources.
Get a list of all content resources of this type.
Return type: | A list of instances of appropriate ContentResource subclasses (e.g. Audio, Video, etc.) |
---|
Get a single content resource of this type.
Parameters: | resource – The resource instance or its ID. |
---|---|
Return type: | An instance of an appropriate ContentResource subclass (e.g. Audio, Video, etc.) |
Delete a resource of this type.
Parameters: | resource – The resource instance or its ID. |
---|---|
Return type: | None |
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 an existing resource.
Parameters: |
|
---|---|
Return type: | None |
Upload a new blob for a given resource.
Parameters: |
|
---|---|
Return type: | None |
An audio resource.
Save changes to this resource by PUTing it back to the server.
Delete this resource.
Upload a new blob for this resource.
Parameters: | blob – A string of file-like object to upload. |
---|---|
Return type: | None |
Manager for data resources.
Get a list of all content resources of this type.
Return type: | A list of instances of appropriate ContentResource subclasses (e.g. Audio, Video, etc.) |
---|
Get a single content resource of this type.
Parameters: | resource – The resource instance or its ID. |
---|---|
Return type: | An instance of an appropriate ContentResource subclass (e.g. Audio, Video, etc.) |
Delete a resource of this type.
Parameters: | resource – The resource instance or its ID. |
---|---|
Return type: | None |
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 an existing resource.
Parameters: |
|
---|---|
Return type: | None |
Upload a new blob for a given resource.
Parameters: |
|
---|---|
Return type: | None |
A data resource.
Save changes to this resource by PUTing it back to the server.
Delete this resource.
Upload a new blob for this resource.
Parameters: | blob – A string of file-like object to upload. |
---|---|
Return type: | None |
Manager for photo resources.
Get a list of all content resources of this type.
Return type: | A list of instances of appropriate ContentResource subclasses (e.g. Audio, Video, etc.) |
---|
Get a single content resource of this type.
Parameters: | resource – The resource instance or its ID. |
---|---|
Return type: | An instance of an appropriate ContentResource subclass (e.g. Audio, Video, etc.) |
Delete a resource of this type.
Parameters: | resource – The resource instance or its ID. |
---|---|
Return type: | None |
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 an existing resource.
Parameters: |
|
---|---|
Return type: | None |
Upload a new blob for a given resource.
Parameters: |
|
---|---|
Return type: | None |
A photo resource.
Save changes to this resource by PUTing it back to the server.
Delete this resource.
Upload a new blob for this resource.
Parameters: | blob – A string of file-like object to upload. |
---|---|
Return type: | None |
Manager for text resources.
Get a list of all content resources of this type.
Return type: | A list of instances of appropriate ContentResource subclasses (e.g. Audio, Video, etc.) |
---|
Get a single content resource of this type.
Parameters: | resource – The resource instance or its ID. |
---|---|
Return type: | An instance of an appropriate ContentResource subclass (e.g. Audio, Video, etc.) |
Delete a resource of this type.
Parameters: | resource – The resource instance or its ID. |
---|---|
Return type: | None |
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 an existing resource.
Parameters: |
|
---|---|
Return type: | None |
A text resource.
Save changes to this resource by PUTing it back to the server.
Delete this resource.
Manager for video resources.
Get a list of all content resources of this type.
Return type: | A list of instances of appropriate ContentResource subclasses (e.g. Audio, Video, etc.) |
---|
Get a single content resource of this type.
Parameters: | resource – The resource instance or its ID. |
---|---|
Return type: | An instance of an appropriate ContentResource subclass (e.g. Audio, Video, etc.) |
Delete a resource of this type.
Parameters: | resource – The resource instance or its ID. |
---|---|
Return type: | None |
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 an existing resource.
Parameters: |
|
---|---|
Return type: | None |
Upload a new blob for a given resource.
Parameters: |
|
---|---|
Return type: | None |
A video resource.
Save changes to this resource by PUTing it back to the server.
Delete this resource.
Upload a new blob for this resource.
Parameters: | blob – A string of file-like object to upload. |
---|---|
Return type: | None |