allensdk.api.api module

class allensdk.api.api.Api(api_base_url_string=None)

Bases: object

cleanup_truncated_file(file_path)

Helper for removing files.

Parameters:

file_path : string

Absolute path including the file name to remove.

construct_well_known_file_download_url(well_known_file_id)

Join data api endpoint and id.

Parameters:

well_known_file_id : integer or string representing an integer

well known file id

Returns:

string

the well-known-file download url for the current api api server

See also

retrieve_file_over_http

Can be used to retrieve the file from the url.

default_api_url = 'http://api.brain-map.org'

do_query(url_builder_fn, json_traversal_fn, *args, **kwargs)

Bundle an query url construction function with a corresponding response json traversal function.

Parameters:

url_builder_fn : function

A function that takes parameters and returns an rma url.

json_traversal_fn : function

A function that takes a json-parsed python data structure and returns data from it.

post : boolean, optional kwarg

True does an HTTP POST, False (default) does a GET

args : arguments

Arguments to be passed to the url builder function.

kwargs : keyword arguments

Keyword arguments to be passed to the rma builder function.

Returns:

any type

The data extracted from the json response.

Examples

A simple Api subclass example.

do_rma_query(rma_builder_fn, json_traversal_fn, *args, **kwargs)

Bundle an RMA query url construction function with a corresponding response json traversal function.

..note:: Deprecated in AllenSDK 0.9.2

do_rma_query will be removed in AllenSDK 1.0, it is replaced by do_query because the latter is more general.

Parameters:

rma_builder_fn : function

A function that takes parameters and returns an rma url.

json_traversal_fn : function

A function that takes a json-parsed python data structure and returns data from it.

args : arguments

Arguments to be passed to the rma builder function.

kwargs : keyword arguments

Keyword arguments to be passed to the rma builder function.

Returns:

any type

The data extracted from the json response.

Examples

A simple Api subclass example.

download_url = 'http://download.alleninstitute.org'

json_msg_query(url, dataframe=False)

Common case where the url is fully constructed

and the response data is stored in the ‘msg’ field.

Parameters:

url : string

Where to get the data in json form

dataframe : boolean

True converts to a pandas dataframe, False (default) doesn’t

Returns:

dict or DataFrame

returned data; type depends on dataframe option

load_api_schema()

Download the RMA schema from the current RMA endpoint

Returns:

dict

the parsed json schema message

Notes

This information and other Allen Brain Atlas Data Portal Data Model documentation is also available as a Class Hierarchy and Class List.

read_data(parsed_json)

Return the message data from the parsed query.

Parameters:

parsed_json : dict

A python structure corresponding to the JSON data returned from the API.

Notes

See API Response Formats - Response Envelope for additional documentation.

retrieve_file_over_http(url, file_path, zipped=False)

Get a file from the data api and save it.

Parameters:

url : string

Url[R099781a1d33c-1]_ from which to get the file.

file_path : string

Absolute path including the file name to save.

zipped : bool, optional

If true, assume that the response is a zipped directory and attempt to extract contained files into the directory containing file_path. Default is False.

See also

construct_well_known_file_download_url

Can be used to construct the url.

References

[1]	Allen Brain Atlas Data Portal: Downloading a WellKnownFile.

retrieve_parsed_json_over_http(url, post=False)

Get the document and put it in a Python data structure

Parameters:

url : string

Full API query url.

post : boolean

True does an HTTP POST, False (default) encodes the URL and does a GET

Returns:

dict

Result document as parsed by the JSON library.

retrieve_xml_over_http(url)

Get the document and put it in a Python data structure

Parameters:

url : string

Full API query url.

Returns:

string

Unparsed xml string.

set_api_urls(api_base_url_string)

Set the internal RMA and well known file download endpoint urls based on a api server endpoint.

Parameters:

api_base_url_string : string

url of the api to point to

set_default_working_directory(working_directory)

Set the working directory where files will be saved.

Parameters:

working_directory : string

the absolute path string of the working directory.

allensdk.api.api.stream_file_over_http(url, file_path, timeout=(9.05, 31.1))

Supply an http get request and stream the response to a file.

Parameters:

url : str

Send the request to this url

file_path : str

Stream the response to this path

timeout : float or tuple of float, optional

Specify a timeout for the request. If a tuple, specify seperate connect and read timeouts.

allensdk.api.api.stream_zip_directory_over_http(url, directory, members=None, timeout=(9.05, 31.1))

Supply an http get request and stream the response to a file.

Parameters:

url : str

Send the request to this url

directory : str

Extract the response to this directory

members : list of str, optional

Extract only these files

timeout : float or tuple of float, optional

Specify a timeout for the request. If a tuple, specify seperate connect and read timeouts.