hepdata-converter-ws-client

Light client wrapper for interaction with hepdata-converter-ws (Web Services). It is recommended to use this wrapper instead of manually creating requests to hepdata-converter-ws.

The reason for creating this package is the fact that the hepdata-converter-ws API requires compressing files into tar.gz format and encoding using Base64 in order to pass them as an argument in the JSON request. Doing this manually every time someone wants to call the hepdata-converter-ws API was a little cumbersome: that's why this light wrapper was born.

Additionally, the library provides additional functionality when it comes to writing the output of the convert function: instead of receiving raw tar.gz content it is possible to extract to a specified file path.

Sample usage

The library exposes one single function hepdata_converter_ws_client.convert which is very similar to hepdata_converter.convert. It accepts the additional argument url, and restricts input / output to str, unicode and file objects (objects supporting read, write, seek, tell).

The options parameter should be the same as with the hepdata_converter library.

The timeout parameter can be used to set a timeout for requests (defaults to 600s).

The library defines the exception hepdata_converter_ws_client.Error which will be thrown on timeouts or other errors connecting to the server.

A function hepdata_converter_ws_client.get_data_size gets the size in bytes of the JSON data that would be sent to the converter. This could be useful in checking that a maximum payload size imposed by a web server is not exceeded.

Function description

hepdata_converter_ws_client.convert function has proper docstring describing its arguments and return values. Similarly for hepdata_converter_ws_client.get_data_size with corresponding docstring.

Convert using file paths

Arguments passed as input and output can be file paths or file objects. Below is an example of how to utilise the convert function with file paths.

import hepdata_converter_ws_client

# using path to input file, and writing output directly to output_path
input_path = '/path/to/input.txt'
output_path = '/path/to/output/dir'
hepdata_converter_ws_client.convert('http://hepdata-converter-ws-addr:port', input_path, output_path,
                                    options={'input_format': 'oldhepdata'})

Convert using input path and output file object

Input can always be a file object (as long as the input Parser supports single files). Output can be a file object only if the keyword argument extract=False. In this case the binary content of the returned tar.gz file will be written to the output file object. It is then the responsibility of the user to decompress it.

import hepdata_converter_ws_client
from io import BytesIO
# using path to input file, writing to output stream
input_path = '/path/to/input.txt'
output = BytesIO()
hepdata_converter_ws_client.convert('http://hepdata-converter-ws-addr:port', input_path, output,
                                    options={'input_format': 'oldhepdata'}, extract=False)