Source code for tcs_lib.string_helpers

# Library with high level interface to HET's TCS
# Copyright (C) 2017 "The HETDEX collaboration"
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
'''Utilities to deal with strings and bytes for a better python2/3
compatibility'''
from __future__ import (absolute_import, division, print_function,
                        unicode_literals)

import time

import six

from .errors import ConvertTypeError


TIME_FMT = '{t:.9f}'
'''Default formatter to times in TCS events'''


def string_to_bytes(string, encoding='utf-8'):
    """If the input is a byte string or a list of byte strings, returns it,
    otherwise interprets it as a string or a list of strings.


    Parameters
    ----------
    string : (list of) string(s)
        string or list of strings to encode
    encoding : string, optional
        encoding to use; see `Standard Encodings
        <https://docs.python.org/3/library/codecs.html#standard-encodings>`_
        for a list of possible encodings

    Returns
    -------
        Python2: input; Python3: (list of) byte string(s).
        If the input is not iterable returns it

    Raises
    ------
    ConvertTypeError
        if the input is not a string/byte string or a list thereof
    """
    if isinstance(string, six.binary_type):
        return string

    if isinstance(string, six.string_types):
        return string.encode(encoding=encoding)
    else:
        try:
            out = []
            for s in string:
                if isinstance(s, six.binary_type):
                    out.append(s)
                else:
                    out.append(s.encode(encoding=encoding))
            return out
        except (TypeError, AttributeError) as e:
            msg = ('The input value "{}" is not a string/byte string nor a'
                   ' list thereof').format(string)
            six.raise_from(ConvertTypeError(msg), e)


def bytes_to_string(byte, encoding='utf-8'):
    """If the input is a string or a list of strings, returns it, otherwise
    interprets it as a byte string or a list of bytes strings.

    Parameters
    ----------
    byte : (list of) byte string(s)
        byte string or list of byte strings to decode
    encoding : string, optional
        encoding to use; see `Standard Encodings
        <https://docs.python.org/3/library/codecs.html#standard-encodings>`_
        for a list of possible encodings

    Returns
    -------
        Python2: input; Python3: (list of) string(s).
        If the input is not iterable returns it

    Raises
    ------
    ConvertTypeError
        if the input is not a string/byte string or a list thereof
    """
    if isinstance(byte, six.string_types):
        return byte

    if isinstance(byte, six.binary_type):
        return byte.decode(encoding=encoding)
    else:
        try:
            out = []
            for b in byte:
                if isinstance(b, six.string_types):
                    out.append(b)
                else:
                    out.append(b.decode(encoding=encoding))
            return out
        except (TypeError, AttributeError) as e:
            msg = ('The input value "{}" is not a string/byte string nor a'
                   ' list thereof').format(byte)
            six.raise_from(ConvertTypeError(msg), e)


def time_str():
    '''
    Returns
    -------
    string
        :class:`time.time` as a string with format :data:`TIME_FMT`
    '''
    return TIME_FMT.format(t=time.time())