Skip to content

Python

The NeuroScale Python API library is an easy-to-use set of tools for interacting with the NeuroScale Platform API in the Python programming language.

The library supports both Python 2 and Python 3. It mirrors the NeuroScale Platform API reference documentation hosted on Apiary.

Configuration

The NeuroScale Python API library supports the following global settings:

  • api_url: The absolute URL for the NeuroScale Platform API (including protocol and optional port). Do not include a trailing slash. Default is 'https://api.neuroscale.io'.
  • api_version: The version of the NeuroScale Platform API to use. Default is 'v1'.
  • access_token: Access token to use for authenticating against the NeuroScale Platform API. Default is None.
  • username: Username to use for authenticating against the NeuroScale Platform API. Default is None.
  • password: Password to use for authenticating against the NeuroScale Platform API. Default is None.
  • http_proxy: The URL of the HTTP proxy to use. Takes the form http\://username:password\@host:port/. Default is None.
  • https_proxy: The URL of the HTTPS proxy to use. Takes the form https\://username:password\@host:port/. Default is None.
  • verify_ssl_certs: Set to True to verify SSL certificates (recommended for best practice security). Default is True.

Each global setting is configured in the same manner and should be set before issuing any API calls:

>>> import neuroscale
>>> neuroscale.access_token = '01234567-89ab-cdef-0123-456789abcdef'
>>> neuroscale.username = 'joebloggs'
>>> neuroscale.password = 'secret'
>>> neuroscale.http_proxy = 'http://10.10.1.10:3128/'
>>> neuroscale.verify_ssl_certs = False
...
>>> pipelines = neuroscale.Pipeline.all()

Resources

The NeuroScale Python API library supports the following standard resources:

  • Application
  • Authorization
  • Dataset
  • Instance
  • Model
  • Pipeline
  • User

In addition, the library also supports the following nested resources:

  • Collaborator
  • Endpoint

Nested resources are resources whose lifecycle is dependent upon that of another resource. If the parent resource is deleted, the nested resources are too.

Finally, the library supports a CollectionResource. This is a special resource that represents a homogeneous collection (i.e. 0 or more instances) of any of the other resource types.

Actions

All standard resources support the following class methods:

  • all(): Retrieve a list (i.e. a CollectionResource) of all instances of the specified resource type.
  • create( **params ): Create an instance of the specified resource type using the given keyword arguments.
  • retrieve( id ): Retrieve an instance of the specified resource type using its unique identifier.

Nested resources do not support these methods. Collection resources expose this functionality through similarly-named instance methods.

All resources support the following instance methods:

  • refresh(): Refresh the current state of the resource.
  • save(): Save the current state of the resource.
  • delete(): Delete the resource. This is non-recoverable.

Not all resources support the same actions (consult the reference documentation for further details). If you attempt to perform an action on a resource that is unsupported by the NeuroScale Platform API, a MethodNotAllowedError will be raised.

In addition, many resources support special-purpose methods that expose additional functionality. Consult the reference documentation for more details. As an example, the Pipeline resource supports the create_instance( **params ) method as an easy-to-use alternative to Instance.create( **params ) as shown in the following section.

Creating an Echo Instance

As an example, here is code one can use to create an echo instance and determine the MQTT topic names to publish on and subscribe to (error-handling has been removed to make the code more readable):

>>> import time
>>> import neuroscale
>>> neuroscale.access_token = '01234567-89ab-cdef-0123-456789abcdef'
>>> pipeline = neuroscale.Pipeline.all().get( name = 'Echo' )
>>> instance = pipeline.create_instance( persist = { 'dataset_in': False, 'dataset_out': False, 'model': False } )
>>> while instance.refresh().state != 'running':
...     time.sleep( 5 )
>>> publish_on = instance.endpoints.get( mode = 'write' ).path
>>> subscribe_to = instance.endpoints.get( mode = 'read' ).path
...
>>> instance.delete()