python-xcall

A Python x-callback-url client for bi-directionalcommunication with x-callback-url enabled macOS applications. python-xcall supports callbacks from appplications. It wraps the handyxcall 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.gitCloning 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-8encoded 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):    passdef 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 madeto ensure that xcall is not already running, but there is 20-30ms window in whichmultiple calls to this module will result in multiple xcall processes runningand the chance of replies being mixed up.

Testing

Running the tests requires the pytest and mock packages. Some optional integrationtests currently require Ulysses. Code youraccess-token into the top of test_calls.py. Obtain the access token string by removing the @skipmarker 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 CommonsAttribution-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.