cis_interface.dataio package — cis_interface 0.3.0 documentation

# cis_interface.dataio package

## Submodules

## cis_interface.dataio.AsciiFile module

class `cis_interface.dataio.AsciiFile.` `AsciiFile`(filepath, io_mode, comment='# ', newline='n', open_as_binary=True)

  Bases: `object`

  `close`()

    Close the associated file descriptor if it is open.

  `is_open`

    bool – Returns True if the file descriptor is open.

  `open`()

    Open the associated file descriptor if it is not already open.

  `open_mode`

    str – Mode that should be used to open the file.

  `readline`()

    Continue reading lines until a valid line (uncommented) is encountered

    Returns: | End of file flag and the line that was read (None if the end of file was encountered).
    Return type: | tuple (bool, str)

  `readline_full`()

    Read a line and return it if it is not a comment.

    Returns: | End of file flag and the line that was read (an empty string if the end of file was encountered). If the line is a comment, None is returned.
    Return type: | tuple (bool, str)

  `writeline`(line)

    Write a line to the file, adding a newline character if it is not present.

    Parameters: | line (str/bytes) – Line to be written with/without the newline character.
    Raises: | `TypeError` – If line is not the correct bytes type.

  `writeline_full`(line)

    Write a line to the file in its present state. If it is not open, nothing happens.

    Parameters: | line (str/bytes) – Line to be written.
    Raises: | `TypeError` – If line is not the correct bytes type.

## cis_interface.dataio.AsciiTable module

class `cis_interface.dataio.AsciiTable.` `AsciiTable`(filepath, io_mode, format_str=None, dtype=None, column_names=None, use_astropy=False, column='t', **kwargs)

  Bases: `cis_interface.dataio.AsciiFile.AsciiFile`

  `arr`

    Numpy array of table contents if opened in read mode.

  `array_to_bytes`(arr=None, order='C')

    Convert arr to bytestring.

    Parameters: | arr (np.ndarray, optional) – Array to write to bytestring. If None the array of table data is used. This can also be a list of arrays, one for each field in the table, or a list of lists, one for each element containing the fields for that element. order (str, optional) – Order that array should be written to the bytestring. Defaults to ‘C’.
    Returns: | Bytestring.
    Return type: | str
    Raises: | `TypeError` – If the provided array is not a numpy array, list, or tuple. `ValueError` – If the array is not the correct type. `ValueError` – If there are not enough arrays in the input list. `ValueError` – If any of the listed arrays doesn’t have enough fields. `ValueError` – If any of the listed arrays doesn’t have enough elements.

  `bytes_to_array`(data, order='C')

    Process bytes according to the table format and return it as an array.

    Parameters: | data (bytes) – Byte string of table data. order (str, optional) – Order of data for reshaping. Defaults to ‘C’.
    Returns: | Numpy array containing data from bytes.
    Return type: | np.ndarray

  `discover_format_str`()

    Determine the format string by reading it from the file. The format string is assumed to start with a comment and contain C-style format codes (e.g. ‘%f’).

    Raises: | `RuntimeError` – If a format string cannot be located within the file.

  `dtype`

    np.dtype – Data type of the table.

  `fmts`

    list – Formats in format string.

  `format_line`(*args)

    Create a line from the provided arguments using the table format.

    Parameters: | *args – Arguments to create line from.
    Returns: | The line created from the arguments.
    Return type: | str

  `format_str`

    str – Format string describing the table column types.

  `ncols`

    int – The number of columns in the table.

  `process_line`(line)

    Extract values from the columns in the line using the table format.

    Parameters: | line (str) – String to extract arguments from.
    Returns: | The arguments extracted from line.
    Return type: | tuple

  `read_array`(names=None)

    Read the table in as an array.

    Parameters: | names (list, optional) – List of column names to label columns. If not provided, existing names are used if they exist. Defaults to None.
    Returns: | Array of table contents.
    Return type: | np.ndarray
    Raises: | `ValueError` – If names are provided, but not the same number as there are columns.

  `read_bytes`(order='C', **kwargs)

    Read the table in as array and encode as bytes.

    Parameters: | order (str, optional) – Order that array should be written to the bytestring. Defaults to ‘C’. **kwargs – Additional keyword arguments are passed to read_array.
    Returns: | Array as bytes.
    Return type: | bytes

  `readline`()

    Continue reading lines until a valid line (uncommented) is encountered and return the arguments found there.

    Returns: | End of file flag and the arguments that were read from the line. If the end of file is reached, None is returned.
    Return type: | tuple (bool, tuple)

  `readline_full`(validate=False)

    Read a line and return it if it is not a comment.

    Parameters: | validate (bool, optional) – If True, the line is checked to see if it matches the expected table format. Defaults to False.
    Returns: | End of file flag and the line that was read (an empty string if the end of file was encountered). If the line is a comment, None is returned.
    Return type: | tuple (bool, str)

  `update_dtype`(new_dtype)

    Change the data type and update the format string.

    Parameters: | new_dtype (str or np.dtype) – New numpy data type.

  `update_format_str`(new_format_str)

    Change the format string and update the data type.

    Parameters: | new_format_str (str) – New format string.

  `validate_line`(line)

    Assert that the line matches the format string and produces the expected number of values.

  `write_array`(array, names=None, skip_header=False)

    Write a numpy array to the table.

    Parameters: | array (np.ndarray) – Array to be written. names (list, optional) – List of column names to write out. If not provided, existing names are used if they exist. Defaults to None. skip_header (bool, optional) – If True, no header information is written (it is assumed it was already written. Defaults to False.
    Raises: | `ValueError` – If names are provided, but not the same number as there are columns.

  `write_bytes`(data, order='C', **kwargs)

    Write a numpy array to the table.

    Parameters: | data (bytes) – Bytes string to be interpreted as array and written to file. order (str, optional) – Order of data for reshaping. Defaults to ‘C’. **kwargs – Additional keyword arguments are passed to write_array.

  `writeformat`()

    Write the format string to the file.

  `writeheader`(names=None)

    Write header including column names and format.

    Parameters: | names (list, optional) – List of names of columns. Defaults to None and the ones provided at construction are used if they exist. Otherwise, no names are written.

  `writeline`(*args)

    Write arguments to a file in the table format.

    Parameters: | *args – Any number of arguments that should be written to the file.

  `writeline_full`(line, validate=False)

    Write a line to the file in its present state.

    Parameters: | line (str) – Line to be written. validate (bool, optional) – If True, the line is checked to see if it matches the expected table format. Defaults to False.

  `writenames`(names=None)

    Write column names to file.

    Parameters: | names (list, optional) – List of names of columns. Defaults to None and the ones provided at construction are used if they exist. Otherwise, no names are written.
    Raises: | `IndexError` – If there are not enough names for all of the columns.

## Module contents

Routines for standardized I/O.