Wrapper function around requests library providing easy way to interact
    with hepdata-converter-ws (web services).

    :param url: path to server hosting hepdata-converter-ws (web services) - url has to point to root server
    (not ```/convert``` or any other specific route) just http(s)://address:port
    :type url: str

    :param input: Input, can be either path (str / unicode) to the file / directory that should be converted, or
    fileobject containing data with the content of the file that should be converted

    :type input: str / unicode / fileobject
    :param output: Output, can be either path (str / unicode) to the file / directory to which output should be written
    (in this case it will be automatically extracted, extract argument must be True), fileobject (in this case extract
    flag must be False, the response tar.gz content will be written to output fileobject) or None (not specified).
    If output is not specified extract flag is not taken into consideration and function returns content of the requested
    tar.gz file.

    :type output: str / unicode / fileobject

    :param options: Options passed to the converter - the same as the ones accepted by hepdata_converter.convert
    function (https://github.com/HEPData/hepdata-converter). Most basic key / values are:
    'input_format': 'yaml'
    'output_format': 'root'

    if not output_format has been specified the default is YAML
    if not input_format has been specified the default is YAML

    :type options: dict

    :param id: used for caching purposes (can be any object that can be turned into string) - if two convert calls
    have the same ID and output types same output will be returned. Because of this if IDs are equal it implies input
    files equality
    :type id: str / int

    :param extract: If set to True the requested tar.gz will be extracted to directory specified in output. If set to
    False requested tar.gz file fill be written to output. If no output has been specified this attribute is not taken
    into account.
    IMPORTANT if output is a file object (not a path) extract must be set to False
    :type extract: bool

    :raise ValueError: if input vales are not sane ValueError is raised

    :rtype : str Binary data
    :return: Binary data containing tar.gz return type. value is returned from this function if and only if no output
    has been specified

def convert(url, input, output=None, options={}, id=None, extract=True):
    """Wrapper function around requests library providing easy way to interact
    with hepdata-converter-ws (web services).

    :param url: path to server hosting hepdata-converter-ws (web services) - url has to point to root server
    (not ```/convert``` or any other specific route) just http(s)://address:port
    :type url: str

    :param input: Input, can be either path (str / unicode) to the file / directory that should be converted, or
    fileobject containing data with the content of the file that should be converted

    :type input: str / unicode / fileobject
    :param output: Output, can be either path (str / unicode) to the file / directory to which output should be written
    (in this case it will be automatically extracted, extract argument must be True), fileobject (in this case extract
    flag must be False, the response tar.gz content will be written to output fileobject) or None (not specified).
    If output is not specified extract flag is not taken into consideration and function returns content of the requested
    tar.gz file.

    :type output: str / unicode / fileobject

    :param options: Options passed to the converter - the same as the ones accepted by hepdata_converter.convert
    function (https://github.com/HEPData/hepdata-converter). Most basic key / values are:
    'input_format': 'yaml'
    'output_format': 'root'

    if not output_format has been specified the default is YAML
    if not input_format has been specified the default is YAML

    :type options: dict

    :param id: used for caching purposes (can be any object that can be turned into string) - if two convert calls
    have the same ID and output types same output will be returned. Because of this if IDs are equal it implies input
    files equality
    :type id: str / int

    :param extract: If set to True the requested tar.gz will be extracted to directory specified in output. If set to
    False requested tar.gz file fill be written to output. If no output has been specified this attribute is not taken
    into account.
    IMPORTANT if output is a file object (not a path) extract must be set to False
    :type extract: bool

    :raise ValueError: if input vales are not sane ValueError is raised

    :rtype : str Binary data
    :return: Binary data containing tar.gz return type. value is returned from this function if and only if no output
    has been specified
    """
    input_stream = cStringIO.StringIO()
    output_defined = output is not None
    if not output_defined:
        extract = False
        output = StringIO.StringIO()

    archive_name = options.get('filename', ARCHIVE_NAME)

    # input is a path, treat is as such
    if isinstance(input, (str, unicode)):
        assert os.path.exists(input)

        with tarfile.open(mode='w:gz', fileobj=input_stream) as tar:
            tar.add(input, arcname=archive_name)
    elif hasattr(input, 'read'):
        with tarfile.open(mode='w:gz', fileobj=input_stream) as tar:
            info = tarfile.TarInfo(archive_name)
            input.seek(0, os.SEEK_END)
            info.size = input.tell()
            input.seek(0)
            tar.addfile(info, fileobj=input)
    else:
        raise ValueError('input is not path or file object!')

    data = {'input': base64.encodestring(input_stream.getvalue()),
            'options': options}

    if id:
        data['id'] = id

    r = requests.get(url + '/convert',
                     data=json.dumps(data),
                     headers={'Content-type': 'application/json',
                              'Accept': 'application/x-gzip'})

    error_occurred = False
    try:
        tarfile.open('r:gz', fileobj=cStringIO.StringIO(r.content)).close()
    except tarfile.ReadError:
        error_occurred = True

    if extract and not error_occurred:
        if not isinstance(output, (str, unicode)):
            raise ValueError('if extract=True then output must be path')

        tmp_dir = tempfile.mkdtemp(suffix='hdc')
        try:
            with tarfile.open('r:gz', fileobj=cStringIO.StringIO(r.content)) as tar:
                tar.extractall(tmp_dir)
            content = os.listdir(tmp_dir)[0]
            shutil.move(os.path.join(tmp_dir, content), output)
        finally:
            shutil.rmtree(tmp_dir, ignore_errors=True)
    else:
        if isinstance(output, (str, unicode)):
            with open(output, 'wb') as f:
                f.write(r.content)
        elif hasattr(output, 'write'):
            output.write(r.content)
        else:
            raise ValueError('output is not path or file object')

    if not output_defined:
        return output.getvalue()
    elif error_occurred:
        return False
    else:
        return True