Classes and Exceptions

StoryMapping

class kcrw.nprapi.StoryMapping(api_key, prune_text_nodes=True)

Uses the NPR API’s JSON output to generate a simple data structure containing a list of NPR stories.

The query method stores the full JSON-esque mapping in the data attribute and returns the list of story mappings. Additionally, a few properties are available on the class to allow easy retrieval of additional API metadata.

Parameters:

• api_key – Your NPR API key string, you must register to get this.
• prune_text_nodes – If this is set to true any single entry dictionaries in the query result with only the key $text will be replaced with the value only. This simplifies the data structure and makes it appear more ‘pythonic’ and less XML-ish.

data

description

The description of the query response feed. This will not have a value until query() is called.

query(ids, **kw)

Make a query to the API, returns a list of story dictionaries and updates the data attribute.

Parameters:

• ids – An integer or string story id or a list of such ids
• kw – Accepts any of the NPR query parameters listed in QUERY_TERMS. These are described in detail in the NPR API input reference. All of these parameters must be strings or integers, except for the fields parameter which may be a list of field names.

Except:

Raises an NPRError when an error response is returned by the NPR API. Raises an urllib2.URLError or an urllib2.HTTPError when there is a problem accessing the NPR API service.

Return type:

list of story mappings

stories

The list of stories, this is identical to the last return value of query(). This will not have a value until query() is called.

title

The title of the query response feed. This will not have a value until query() is called.

version

The API version of the last query response. This will not have a value until query() is called.

StoryAPI

class kcrw.nprapi.StoryAPI(api_key, output_format=None)

Makes requests to the NPR Story API.

Parameters:

• api_key – Your NPR API key string, you must register to get this.
• output_format –

  The output format type. Accepts any of the values in OUTPUT_FORMATS, which are described in the NPR API input reference.

query(ids, **kw)

Request data from the NPR API. Valid query parameters listed in the QUERY_TERMS constant. Returns the response string after checking for errors.

Parameters:

• ids – An integer or string story id or a list of such ids
• kw –

  Accepts any of the NPR query parameters listed in QUERY_TERMS. These are described in detail in the NPR API input reference. All of these parameters must be strings or integers, except for the fields parameter which may be a list of field names.

Except:

Raises an NPRError when an error response is returned by the NPR API. Raises an urllib2.URLError or an urllib2.HTTPError when there is a problem accessing the NPR API service.

Return type:

string

NPRError

exception kcrw.nprapi.NPRError(code, text=u'')

An error response from the NPR API.

Parameters:

• code – The NPR error code
• text – The NPR error message