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/')

Module attributes

N_THREADS

The number of download threads.

Functions

`dataset_record_to_url`	Extract 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`	Download 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.
`validate_endpoint_action`	Decorator to validate endpoint and action before executing a method.

Classes

`AlyxClient`	Class that implements simple GET/POST wrappers for the Alyx REST API.
`RestScheme`	Alyx REST scheme documentation.
`RestSchemeCoreApi`	Legacy Alyx REST scheme documentation.
`RestSchemeOpenApi`	OpenAPI v3 Alyx REST scheme documentation.

N_THREADS = 4

The number of download threads.

Type:: int

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]

Download 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]

Extract 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 RestScheme(rest_scheme: dict)[source]

Bases: ABC

Alyx REST scheme documentation.

EXCLUDE = ('_type', '_meta', '', 'auth-token', 'api')

A list of endpoint names to exclude from listings.

Type:: list

abstract endpoints() → list[source]

Return the list of available endpoints.

Returns:: List of available endpoints
Return type:: list

abstract actions(endpoint: str, *args) → list[source]

Return a list of available actions for a given endpoint.

Parameters:: endpoint (str) – The endpoint name to find actions for
Returns:: List of available actions for the endpoint
Return type:: list

abstract fields(endpoint: str, action: str) → List[dict][source]

Return a list of fields for a given endpoint/action combination.

Parameters:

endpoint (str) – The endpoint name to find fields and parameters for
action (str) –

The Django REST action:
’list’, ‘read’, ‘create’, ‘update’, ‘delete’, ‘partial_update’

Returns:

List of dictionaries containing fields for the endpoint

Return type:

list

field_names(endpoint: str, action: str) → List[str][source]

Return a list of fields for a given endpoint/action combination.

Parameters:

endpoint (str) – The endpoint name to find fields and parameters for
action (str) –

The Django REST action:
’list’, ‘read’, ‘create’, ‘update’, ‘delete’, ‘partial_update’

Returns:

List of strings containing fields names for the endpoint

Return type:

list

abstract print_endpoint_info(endpoint: str, action: str = None) → None[source]

Prints relevant information about an endpoint and its actions.

Parameters:

endpoint (str) – The endpoint name to find actions for
action (str) –

The Django REST action to perform:
’list’, ‘read’, ‘create’, ‘update’, ‘delete’, ‘partial_update’

Return type:

None

url(endpoint: str, action: str)[source]

Returns the url for a given endpoint/action combination.

Parameters:

endpoint (str) – The endpoint name to find actions for
action (str) –

The Django REST action to perform:
’list’, ‘read’, ‘create’, ‘update’, ‘delete’, ‘partial_update’

Returns:

url of the endpoint: for example /sessions/{id}

Return type:

str

validate_endpoint_action(func)[source]

Decorator to validate endpoint and action before executing a method.

This decorator checks if the endpoint exists and, if an action is provided, whether the action exists for that endpoint. If validation fails, it returns None, otherwise it executes the decorated function.

class RestSchemeCoreApi(rest_scheme: dict)[source]

Bases: RestScheme

Legacy Alyx REST scheme documentation.

backend = 'core_api'

The name of the backend that generates the REST API documentation.

Type:: str

property endpoints: list

Return the list of available endpoints.

Returns:: List of available endpoints
Return type:: list

actions(endpoint: str, *args) → list[source]

Return a list of available actions for a given endpoint.

Parameters:: endpoint (str) – The endpoint name to find actions for
Returns:: List of available actions for the endpoint
Return type:: list

url(endpoint: str, action: str) → str[source]

Returns the url for a given endpoint/action combination.

Parameters:

endpoint (str) – The endpoint name to find actions for
action (str) –

The Django REST action to perform:
’list’, ‘read’, ‘create’, ‘update’, ‘delete’, ‘partial_update’

Returns:

url of the endpoint: for example /sessions/{id}

Return type:

str

fields(endpoint: str, action: str) → list[source]

Return a list of fields for a given endpoint/action combination.

Parameters:

endpoint (str) – The endpoint name to find fields and parameters for
action (str) –

The Django REST action:
’list’, ‘read’, ‘create’, ‘update’, ‘delete’, ‘partial_update’

Returns:

List of dictionaries containing fields for the endpoint

Return type:

list

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

Prints relevant information about an endpoint and its actions.

Parameters:

endpoint (str) – The endpoint name to find actions for
action (str) –

The Django REST action to perform:
’list’, ‘read’, ‘create’, ‘update’, ‘delete’, ‘partial_update’

Return type:

None

class RestSchemeOpenApi(rest_scheme: dict)[source]

Bases: RestScheme

OpenAPI v3 Alyx REST scheme documentation.

backend = 'open_api_v3'

The name of the backend that generates the REST API documentation.

Type:: str

property endpoints: list

Return the list of available endpoints.

Returns:: List of available endpoints
Return type:: list

fields(endpoint: str, action: str) → list[source]

Return a list of fields for a given endpoint/action combination.

Parameters:

endpoint (str) – The endpoint name to find fields and parameters for
action (str) –

The Django REST action:
’list’, ‘read’, ‘create’, ‘update’, ‘delete’, ‘partial_update’

Returns:

List of dictionaries containing fields for the endpoint

Return type:

list

actions(endpoint: str, *args) → list[source]

Return a list of available actions for a given endpoint.

Parameters:: endpoint (str) – The endpoint name to find actions for
Returns:: List of available actions for the endpoint
Return type:: list

url(endpoint: str, action: str) → str[source]

Returns the url for a given endpoint/action combination.

Parameters:

endpoint (str) – The endpoint name to find actions for
action (str) –

The Django REST action to perform:
’list’, ‘read’, ‘create’, ‘update’, ‘delete’, ‘partial_update’

Returns:

url of the endpoint: for example /sessions/{id}

Return type:

str

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

Print detailed information about an endpoint’s actions and parameters.

Parameters:

endpoint (str) – The endpoint name to display information for
action (str, optional) – If provided, only show information for this specific action

Return type:

None

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 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

property rest_schemes: RestScheme

The REST endpoints and their parameters.

Type:: dict

list_endpoints()[source]

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

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

Fetch token from the Alyx REST API for authenticating request 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 and clears the REST cache.

delete(rest_query)[source]

Send a DELETE request to the Alyx server.

Will raise an exception on any HTTP 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]

Download file(s) from data server from a REST file record URL.

Parameters:

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

Returns:

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

Return type:

pathlib.Path, list of pathlib.Path

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

Download 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]

Send a GET request to the Alyx server.

Will raise an exception on any HTTP 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]

Send 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]

Send 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]

Send 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 REST API wrapper.

If no arguments are passed, lists available endpoints.

Parameters:

url (str) – Endpoint name.
action (str) – One of ‘list’, ‘create’, ‘read’, ‘update’, ‘partial_update’, ‘delete’.
id (str, uuid.UUID) – 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 c.f. https://openalyx.internationalbrainlab.org/docs/

Returns:

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

Return type:

list, dict

Examples

List available endpoint

>>> client = AlyxClient()
... client.rest()

List available actions for the ‘subjects’ endpoint

>>> client.rest('subjects')

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')})

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

Write data to JSON field.

NOTE: Destructive write! WILL NOT CHECK IF DATA EXISTS

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.