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 = alyx.download_file(url, target_dir='zadorlab/Subjects/flowers/2018-07-13/1/')

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`	Download a file from a remote HTTP server.
`http_download_file_list`	Downloads a list of files from a remote HTTP server from a list of links.
`no_cache`	Temporarily turn off the REST cache for a given Alyx instance.
`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.

no_cache(ac=None)[source]

Temporarily turn off the REST cache for a given Alyx instance.

This function is particularly useful when calling ONE methods in remote mode.

Parameters:: ac (AlyxClient) – An instance of the AlyxClient to modify. If None, the a new object is instantiated
Returns:: The instance of Alyx with cache disabled
Return type:: AlyxClient

Examples

>>> from one.api import ONE
>>> with no_cache(ONE().alyx):
...     eids = ONE().search(subject='foobar', query_type='remote')

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:

A new URL with said parameters updated

Return type:

str

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 a remote HTTP server from a list of links. Generates up to 4 separate threads to handle downloads. Same options behaviour as http_download_file.

Parameters:

links_to_file_list (list) – List of http links to files.
**kwargs – Optional arguments to pass to http_download_file.

Returns:

A list of the local full path of the downloaded files.

Return type:

list of pathlib.Path

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

Download a file from a remote HTTP server.

Parameters:

full_link_to_file (str) – HTTP link to the file
chunks (tuple of ints) – Chunks to download
clobber (bool) – If True, force overwrite the existing file
silent (bool) – If True, suppress download progress bar
username (str) – User authentication for password protected file server
password (str) – Password authentication for password protected file server
target_dir (str, pathlib.Path) – Directory in which files are downloaded; defaults to user’s Download directory
return_md5 (bool) – If True an MD5 hash of the file is additionally returned
headers (list of dicts) – Additional headers to add to the request (auth tokens etc.)

Returns:

The full file path of the downloaded file

Return type:

pathlib.Path

file_record_to_url(file_records) → list[source]

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

Parameters:: file_records (dict) – JSON containing a ‘data_url’ field
Returns:: A list of full data urls
Return type:: list of str

dataset_record_to_url(dataset_record) → list[source]

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

Parameters:: dataset_record (list, dict) – Dataset JSON from a REST request
Returns:: A list of file urls corresponding to the datasets records
Return type:: list of str

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

Bases: object

Class that implements simple GET/POST wrappers for the Alyx REST API. See https://openalyx.internationalbrainlab.org/docs

user = None

The Alyx username.

Type:: str

base_url = None

The Alyx database URL.

Type:: str

property rest_schemes

The REST endpoints and their parameters.

Type:: dict

property cache_dir

The location of the downloaded file cache.

Type:: pathlib.Path

property is_logged_in

Check if user logged into Alyx database; True if user is authenticated.

Type:: bool

list_endpoints()[source]

Return a list of available REST endpoints.

Return type:: List of REST endpoint strings.

print_endpoint_info(endpoint, action=None)[source]

Print the available actions and query parameters for a given REST endpoint.

Parameters:

endpoint (str) – An Alyx REST endpoint to query.
action (str) – An optional action (e.g. ‘list’) to print. If None, all actions are printed.

Returns:

A dictionary of endpoint query parameter details or a list of parameter details if action is not None.

Return type:

dict, list

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) – A REST query string either as a relative URL path complete URL.
Return type:: JSON interpreted dictionary from response.

Examples

>>> AlyxClient.delete('/weighings/c617562d-c107-432e-a8ee-682c17f9e698')
>>> AlyxClient.delete(
...     'https://alyx.example.com/endpoint/c617562d-c107-432e-a8ee-682c17f9e698')

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

Downloads a single file or list of files on the Alyx server from a file record REST field URL.

Parameters:

url (str, list) – Full url(s) of the file(s).
**kwargs – WebClient.http_download_file parameters.

Return type:

Local path(s) of downloaded file(s).

download_cache_tables(source=None, destination=None)[source]

Downloads the Alyx cache tables to the local data cache directory.

Parameters:

source (str, pathlib.Path) – The remote HTTP directory of the cache table (excluding the filename). Default: AlyxClient.base_url.
destination (str, pathlib.Path) – The target directory into to which the tables will be downloaded.

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.).
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://openalyx.internationalbrainlab.org/docs

Parameters:

rest_query (str) – A REST URL path, e.g. ‘/sessions?user=Hamish’.
**kwargs – Optional arguments to pass to _generic_request and _cache_response decorator.

Return type:

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://openalyx.internationalbrainlab.org/docs

Parameters:

rest_query (str) – The endpoint as full or relative URL.
data (dict, str) – JSON encoded string or dictionary (c.f. requests).
files (dict, tuple) – Files to attach (c.f. requests).

Return type:

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://openalyx.internationalbrainlab.org/docs

Parameters:

rest_query (str) – The endpoint as full or relative URL.
data (dict, str) – JSON encoded string or dictionary (c.f. requests).
files (dict, tuple) – Files to attach (c.f. requests).

Return type:

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://openalyx.internationalbrainlab.org/docs

Parameters:

rest_query (str) – The endpoint as full or relative URL.
data (dict, str) – JSON encoded string or dictionary (c.f. requests).
files (dict, tuple) – Files to attach (c.f. requests).

Returns:

Response object.

Return type:

requests.Response

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 = AlyxClient()
>>> 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 (str) – Endpoint name.
action (str) – One of ‘list’, ‘create’, ‘read’, ‘update’, ‘partial_update’, ‘delete’.
id (str) – Lookup string for actions ‘read’, ‘update’, ‘partial_update’, and ‘delete’.
data (dict) – Data dictionary for actions ‘update’, ‘partial_update’ and ‘create’.
files (dict, tuple) – Option file(s) to upload.
no_cache (bool) – If true the list and read actions are performed without returning the cache.
kwargs – Filters as per the Alyx REST documentation cf. https://openalyx.internationalbrainlab.org/docs/

Returns:

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

Return type:

list, dict

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

Write data to JSON field. 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:

Written data dict.

Return type:

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:

New patched json field contents as dict.

Return type:

dict

Examples

>>> client = AlyxClient()
>>> client.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) → dict | None[source]

Remove inputted key from JSON field dict and re-upload it to Alyx.

Needs endpoint, UUID and json field name.

Parameters:

endpoint (str) – Endpoint to hit, defaults to None.
uuid (str, uuid.UUID) – UUID or lookup name for endpoint.
field_name (str) – JSON field name of object, defaults to None.
key (str) – Key name of dictionary inside object, defaults to None.

Returns:

New content of json field.

Return type:

dict

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

Set an entire field to null.

Note that this deletes all data from a given field. To delete only a single key from a given JSON field, use json_field_remove_key.

Parameters:

endpoint (str) – Endpoint to hit, defaults to None.
uuid (str, uuid.UUID) – UUID or lookup name for endpoint.
field_name (str) – The field name of object (e.g. ‘json’, ‘name’, ‘extended_qc’), defaults to None.

Returns:

New content of json field.

Return type:

None

clear_rest_cache()[source]: Clear all REST response cache files for the base url.