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

Type

str

base_url = None
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

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 (Any) – WebClient.http_download_file parameters

Return type

Local path(s) of downloaded file(s)

download_cache_tables(location=None)[source]

Downloads the Alyx cache tables to the local data cache directory

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 (any) – 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: Optional[str] = None, uuid: Optional[str] = None, field_name: Optional[str] = None, data: Optional[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: Optional[str] = None, uuid: Optional[str] = None, field_name: str = 'json', data: Optional[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: Optional[str] = None, uuid: Optional[str] = None, field_name: str = 'json', key: Optional[str] = None) Optional[dict][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 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: Optional[str] = None, uuid: Optional[str] = None, field_name: Optional[str] = None) None[source]
clear_rest_cache()[source]

Clear all REST response cache files for the base url