python-xcall

A Python x-callback-url client for bi-directional communication with x-callback-url enabled macOS applications. python-xcall supports callbacks from appplications. It wraps the handy xcall command line tool.

It is used by:

• python-ulysses-client

Software compatability

Requires:

• macOS
• python 2.7
• Uses xcall (included).
• Needs pytest and mock for testing

Installation

Check it out:

$ git clone https://github.com/robwalton/python-xcall.git
Cloning into 'python-xcall'...

Basic use

Call a scheme (ulysses) with an action (get-version):

>>> import xcall
>>> xcall.xcall('ulysses', 'get-version')
{u'apiVersion': u'2', u'buildNumber': u'33542'}

An x-success reply will be utf-8 un-encoded, then url unquoted, and then un-marshaled using json into Python objects and returned.

A dictionary of action parameters can also be provided (each value is utf-8 encoded and then url quoted before sending):

>>> xcall.xcall('ulysses', 'new-sheet', {'text':'My new sheet', 'index':'2'})

If the application calls back with an x-error, an XCallbackError will be raised:

>>> xcall.xcall('ulysses', 'an-invalid-action')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
...
XCallbackError: x-error callback: '{
  "errorMessage" : "Invalid Action",
  "errorCode" : "100"
}
' (in response to url: 'ulysses://x-callback-url/an-invalid-action')

More control

For more control create an instance of xcall.XCallClient, specifying the scheme to use, whether responses should be un-marshaled using json, and an x-error handler. For example:

class UlyssesError(XCallbackError):
    pass

def ulysses_xerror_handler(xerror, requested_url):
    error_message = eval(xerror)['errorMessage']
    error_code = eval(xerror)['errorCode']
    raise UlyssesError(
        ("%(error_message)s. Code=%(error_code)s. "
         "In response to sending the url '%(requested_url)s'") % locals())

ulysses_client = XCallClient(
    'ulysses', on_xerror_handler=ulysses_xerror_handler,  json_decode_success=True)

Make calls using:

>>> ulysses_client.xcall('get-version')

or just:

>>> ulysses_client('get-version')

Logging

As logger output just goes directly to the terminal, it is disabled by default. To enable more verbose logging use:

>>> import xcall
>>> xcall.enable_verbose_logging()

On thread/process safety

Call to this module are probably not thread/process safe. An attempt is made to ensure that xcall is not already running, but there is 20-30ms window in which multiple calls to this module will result in multiple xcall processes running and the chance of replies being mixed up.

Testing

Running the tests requires the pytest and mock packages. Some optional integration tests currently require Ulysses. Code your access-token into the top of test_calls.py. Obtain the access token string by removing the @skip marker from test_authorise() in test_calls.py and running the tests.

From the root package folder call:

MacBook:python-xcall walton$ pytest
...

Licensing & Thanks

The code and the documentation are released under the MIT and Creative Commons Attribution-NonCommercial licences respectively.

Thanks to:

• Martin Finke for his handy xcall application.
• Dean Jackson for suggestions

Todo

• Upload PyPi after working out how distrubute the lib folder containing xcall.app.
• Logs could go somewhere more sensible that stdout.