one.webclient¶

API for interacting with a remote Alyx instance through REST The AlyxClient class contains methods for making remote Alyx REST queries and downloading remote files through Alyx.

Examples

alyx = AlyxClient(: username=’test_user’, password=’TapetesBloc18’, base_url=’https://test.alyx.internationalbrainlab.org’)

# List subjects subjects = alyx.rest(‘subjects’, ‘list’)

# Create a subject record = {

‘nickname’: nickname, ‘responsible_user’: ‘olivier’, ‘birth_date’: ‘2019-06-15’, ‘death_date’: None, ‘lab’: ‘cortexlab’,

} new_subj = alyx.rest(‘subjects’, ‘create’, data=record)

# Download a remote file, given a local path url = ‘zadorlab/Subjects/flowers/2018-07-13/1/channels.probe.npy’ local_path = self.alyx.download_file(url)

Functions

`dataset_record_to_url`	Extracts a list of files urls from a list of dataset queries.
`file_record_to_url`	Translate a Json dictionary to an usable http url for downloading files.
`http_download_file`	param full_link_to_file http link to the file.
`http_download_file_list`	Downloads a list of files from the flat Iron from a list of links.
`update_url_params`	Add/update the query parameters of a URL and make url safe

Classes

AlyxClient

Class that implements simple GET/POST wrappers for the Alyx REST API http://alyx.readthedocs.io/en/latest/api.html # FIXME old link

update_url_params(url: str, params: dict) → str[source]¶

Add/update the query parameters of a URL and make url safe

Parameters

url (str) – A URL string with which to update the query parameters
params (dict) – A dict of new parameters. For multiple values for the same query, use a list (see example)

Returns

Return type

A new URL with said parameters updated

Examples

update_url_params(‘website.com/?q=’, {‘pg’: 5}) ‘website.com/?pg=5’

update_url_params(‘website.com?q=xxx’, {‘pg’: 5, ‘foo’: [‘bar’, ‘baz’]}) ‘website.com?q=xxx&pg=5&foo=bar&foo=baz’

http_download_file_list(links_to_file_list, **kwargs)[source]¶

Downloads a list of files from the flat Iron from a list of links. Same options behaviour as http_download_file

Parameters: links_to_file_list (list) – list of http links to files.
Returns: (list) a list of the local full path of the downloaded files.

http_download_file(full_link_to_file, chunks=None, *, clobber=False, silent=False, username='', password='', cache_dir='', return_md5=False, headers=None)[source]¶

Parameters

full_link_to_file (str) – http link to the file.
chunks (tuple of ints) – chunks to download
clobber (bool) – [False] If True, force overwrite the existing file.
username (str) – [‘’] authentication for password protected file server.
password (str) – [‘’] authentication for password protected file server.
cache_dir (str) – [‘’] directory in which files are cached; defaults to user’s Download directory.
return_md5 (bool) – if true an MD5 hash of the file is additionally returned

Param

headers: [{}] additional headers to add to the request (auth tokens etc..)

Param

silent: [False] suppress download progress bar

Returns

(str) a list of the local full path of the downloaded files.

file_record_to_url(file_records)[source]¶

Translate a Json dictionary to an usable http url for downloading files.

Parameters: file_records (dict) – json containing a ‘data_url’ field
Returns: urls: (list) a list of strings representing full data urls

dataset_record_to_url(dataset_record)[source]¶

Extracts a list of files urls from a list of dataset queries.

Parameters: dataset_record (list) – dataset Json from a rest request.
Returns: (list) a list of strings representing files urls corresponding to the datasets records

class AlyxClient(base_url=None, username=None, password=None, cache_dir=None, silent=False, cache_rest='GET', stay_logged_in=True)[source]¶

Bases: object

Class that implements simple GET/POST wrappers for the Alyx REST API http://alyx.readthedocs.io/en/latest/api.html # FIXME old link

user = None¶

base_url = None¶

property rest_schemes¶: Delayed fetch of rest schemes speeds up instantiation

property cache_dir¶

is_logged_in()[source]¶

Check if user logged into Alyx database

Returns
Return type: True if user is authenticated

list_endpoints()[source]¶

Return a list of available REST endpoints

Returns
Return type: List of REST endpoint strings

authenticate(username=None, password=None, cache_token=True, force=False)[source]¶

Gets a security token from the Alyx REST API to create requests headers. Credentials are loaded via one.params

Parameters

username (str) – Alyx username. If None, token not cached and not silent, user is prompted.
password (str) – Alyx password. If None, token not cached and not silent, user is prompted.
cache_token (bool) – If true, the token is cached for subsequent auto-logins
force (bool) – If true, any cached token is ignored

logout()[source]¶: Log out from Alyx Deletes the cached authentication token for the currently logged-in user

delete(rest_query)[source]¶

Sends a DELETE request to the Alyx server. Will raise an exception on any status_code other than 200, 201.

Parameters: rest_query (str) – examples: ‘/weighings/c617562d-c107-432e-a8ee-682c17f9e698’ ‘https://test.alyx.internationalbrainlab.org/weighings/c617562d-c107-432e-a8ee-682c17f9e698’.
Returns: (dict/list) json interpreted dictionary from response

download_file(url, **kwargs)[source]¶

Downloads a file on the Alyx server from a file record REST field URL

Parameters

url – full url(s) of the file(s)
kwargs – webclient.http_download_file parameters

Returns

local path(s) of downloaded file(s)

download_cache_tables()[source]¶

Downloads the Alyx cache tables to the local data cache directory

Returns
Return type: List of parquet table file paths

rel_path2url(path)[source]¶

Given a relative file path, return the remote HTTP server URL. It is expected that the remote HTTP server has the same file tree as the local system.

Parameters: path (str, pathlib.Path) – A relative ALF path (subject/date/number/etc.)
Returns
Return type: A URL string

get(rest_query, **kwargs)[source]¶

Sends a GET request to the Alyx server. Will raise an exception on any status_code other than 200, 201. For the dictionary contents and list of endpoints, refer to: https://alyx.internationalbrainlab.org/docs

Parameters: rest_query (str) – example: ‘/sessions?user=Hamish’.
Returns: (dict/list) json interpreted dictionary from response

patch(rest_query, data=None, files=None)[source]¶

Sends a PATCH request to the Alyx server. For the dictionary contents, refer to: https://alyx.internationalbrainlab.org/docs

Parameters

rest_query (str) – (required)the endpoint as full or relative URL
data (None, dict or str) – json encoded string or dictionary (cf.requests)
files – dictionary / tuple (cf.requests)

Returns

response object

post(rest_query, data=None, files=None)[source]¶

Sends a POST request to the Alyx server. For the dictionary contents, refer to: https://alyx.internationalbrainlab.org/docs

Parameters

rest_query (str) – (required)the endpoint as full or relative URL
data (None, dict or str) – dictionary or json encoded string
files – dictionary / tuple (cf.requests)

Returns

response object

put(rest_query, data=None, files=None)[source]¶

Sends a PUT request to the Alyx server. For the dictionary contents, refer to: https://alyx.internationalbrainlab.org/docs

Parameters

rest_query (str) – (required)the endpoint as full or relative URL
data (None, dict or str) – dictionary or json encoded string
files – dictionary / tuple (cf.requests)

Returns

response object

rest(url=None, action=None, id=None, data=None, files=None, no_cache=False, **kwargs)[source]¶

alyx_client.rest(): lists endpoints alyx_client.rest(endpoint): lists actions for endpoint alyx_client.rest(endpoint, action): lists fields and URL

Example REST endpoint with all actions:

client.rest(‘subjects’, ‘list’) client.rest(‘subjects’, ‘list’, field_filter1=’filterval’) client.rest(‘subjects’, ‘create’, data=sub_dict) client.rest(‘subjects’, ‘read’, id=’nickname’) client.rest(‘subjects’, ‘update’, id=’nickname’, data=sub_dict) client.rest(‘subjects’, ‘partial_update’, id=’nickname’, data=sub_dict) client.rest(‘subjects’, ‘delete’, id=’nickname’) client.rest(‘notes’, ‘create’, data=nd, files={‘image’: open(image_file, ‘rb’)})

Parameters

url – endpoint name
action – ‘list’, ‘create’, ‘read’, ‘update’, ‘partial_update’, ‘delete’
id – lookup string for actions ‘read’, ‘update’, ‘partial_update’, and ‘delete’
data – data dictionary for actions ‘update’, ‘partial_update’ and ‘create’
files – if file upload
no_cache – if true the list and read actions are performed without caching
**kwargs – filter as per the Alyx REST documentation cf. https://alyx.internationalbrainlab.org/docs/

Returns

list of queried dicts (‘list’) or dict (other actions)

json_field_write(endpoint: str = None, uuid: str = None, field_name: str = None, data: dict = None) → dict[source]¶

json_field_write [summary] Write data to WILL NOT CHECK IF DATA EXISTS NOTE: Destructive write!

Parameters

endpoint (str, None) – Valid alyx endpoint, defaults to None
uuid (str, uuid.UUID, None) – UUID or lookup name for endpoint
field_name (str, None) – Valid json field name, defaults to None
data (dict, None) – Data to write to json field, defaults to None

Returns

Return type

Written data dict

json_field_update(endpoint: str = None, uuid: str = None, field_name: str = 'json', data: dict = None) → dict[source]¶

Non destructive update of json field of endpoint for object Will update the field_name of the object with pk = uuid of given endpoint If data has keys with the same name of existing keys it will squash the old values (uses the dict.update() method)

Parameters

endpoint (str) – Alyx REST endpoint to hit
uuid (str, uuid.UUID) – UUID or lookup name of object
field_name (str) – Name of the json field
data (dict) – A dictionary with fields to be updated

Returns

Return type

New patched json field contents as dict

Examples

one.alyx.json_field_update(“sessions”, “eid_str”, “extended_qc”, {“key”: value})

json_field_remove_key(endpoint: str = None, uuid: str = None, field_name: str = 'json', key: str = None) → Optional[dict][source]¶

Will remove inputted key from json field dict and reupload it to Alyx. Needs endpoint, uuid and json field name

Parameters

endpoint (str, optional) – endpoint to hit, defaults to None
uuid (str, optional) – uuid or lookup name for endpoint
field_name (str, optional) – json field name of object, defaults to None
key (str, optional) – key name of dictionary inside object, defaults to None

Returns

returns new content of json field

Return type

dict

json_field_delete(endpoint: str = None, uuid: str = None, field_name: str = None) → None[source]¶

clear_rest_cache()[source]¶