The Javascript Client

The Pico Javascript client makes it simple to call your API from a web application. The client automatically generates proxy module objects and functions for your API so you can call your API functions just like any other library functions. All serialisation of arguments and deserialisation of responses is taken care of by the client so you can focus on your application logic.

The only thing you need to be aware of is that all function calls are asynchronous returning promises.

Basic Structure

The basic structure of a web app using the Pico Javascript client is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
<!DOCTYPE HTML>
<html>
<head>
  <title>Pico Example</title>
    <!-- Load the pico Javascript client, always automatically available at /pico.js -->
    <script src="/pico.js"></script>
     <!-- Load our example module -->
    <script src="/example.js"></script>
</head>
<body>
  <p id="message"></p>
  <script>
  var example = pico.importModule('example')

  example.hello('Fergal')
  .then(function(response){
    document.getElementById('message').innerHTML = response;
  });
  </script>
</body>
</html>
  • Line 6: We include Pico’s pico.js library inside the head of the document.
  • Line 8: We load our example module definition as JavaScript in the head.
  • Line 13: In a script element in the body we import our example module assigning it to the example variable.
  • Line 15: We use our hello function.
  • Line 16-18: We assign a callback to the promise.

The order and position of these elements within the document is important. pico.js must always be loaded before the module is loaded and these both must be in the head of the document to ensure they have completed by the time they are used later.

Promises

The proxy functions generated by the client are asynchronous, meaning that they will not wait for the result before returning. This is due to the nature of how HTTP requests work in the browser. Instead they immediately return a promise which later resolves and calls a callback with the result as a parameter. The promise object has two methods of interest: then and catch.

var p = example.hello('world')
p.then(function(result){
    console.log(result)
})
p.catch(function(err){
    console.error(err)
})

The callback function passed to .then is called when the promise resolves successfully. If an error occurs then the function passed to .catch is called. If you don’t set a catch callback any errors are ignored.

The error object passed to catch callback contains a .message and .code property which describe the exception that occurred on the Python side and the relevant HTTP status code.

API

Asynchronous functions

Each of these functions is asynchronous, so they return a Promise.

pico.loadAsync(module)
Arguments:
  • module (string) – The name of the module to load.

Load the Python module named module. The module proxy will be passed to the promise callback.

Submodules may be loaded by using dotted notation e.g. module.sub_module.

pico.reload(module_proxy)
Arguments:
  • module_proxy (object) – The module to reload.

Reload the module definition and recreate the module proxy for the supplied module_proxy object. Note that module_proxy is a module proxy object, not a string.

Synchronous functions

pico.importModule(module)
Arguments:
  • module (string) – The name of the module to import.
Returns:

the proxy module object.

Note the module definition must have been previously loaded using pico.loadAsync or by loading /<module_name>.js in a script tag in the head of the document.

pico.loadModuleDefinition(module_definition)
Arguments:
  • module_definition (object) – An object representing the definition of the module.
Returns:

the proxy module object.

This function creates a proxy module from the given definition and stores it in the internal module registry for later import with pico.importModule. It also returns the proxy module directly.

This function is called internally by the /<module_name>.js loading mechanism.

pico.help(proxy_object)
Arguments:
  • proxy_object (object) – The function or module proxy you want help for.
Returns:

the docstring of a proxy module or function.