PyDL:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- pydl v1.0.1 »
- SDSS Utilities (`pydl.pydlutils`) »
- yanny

# yanny

class pydl.pydlutils.yanny.yanny(filename=None, raw=False)

  Bases: `OrderedDict`

  An object interface to a yanny file.

  Create a yanny object using a yanny file, `filename`. If the file exists, it is read, & the dict structure of the object will be basically the same as that returned by `read_yanny()` in the efftickle package.

  If the file does not exist, or if no filename is given, a blank structure is returned. Other methods allow for subsequent writing to the file.

  Parameters:
    filename `str` or file-like, optional

      The name of a yanny file or a file-like object representing a yanny file.

    raw `bool`, optional

      If `True`, data in a yanny file will not be converted into astropy `Table` objects, but will instead be retained as raw Python lists.

  Attributes:
    raw `bool`

      If `True`, data in a yanny file will not be converted into astropy `Table` objects, but will instead be retained as raw Python lists.

    filename `str`

      The name of a yanny parameter file. If a file-like object was used to initialize the object, this will have the value ‘in_memory.par’.

    _symbols `dict`

      A dictionary containing the metadata describing the tables.

    _contents `str`

      The complete contents of a yanny parameter file.

    _struct_type_caches `dict`

      A dictionary of dictionaries, one dictionary for every structure definition in a yanny parameter file. Contains the types of each column

    _struct_isarray_caches `dict`

      A dictionary of dictionaries, one dictionary for every structure definition in a yanny parameter file. Contains a boolean value for every column.

    _enum_cache `dict`

      Initially `None`, this attribute is initialized the first time the `isenum()` method is called. The keyword is the name of the enum type, the value is a list of the possible values of that type.

  Create a yanny object using a yanny file.

  Methods Summary

  `append`(datatable) | Appends data to an existing FTCL/yanny file.
  `array_length`(structure, variable) | Returns the length of an array type or 1 if the variable is not an array.
  `basetype`(structure, variable) | Returns the bare type of a variable, stripping off any array information.
  `char_length`(structure, variable) | Returns the length of a character field.
  `columns`(table) | Returns an ordered list of column names associated with a particular table.
  `convert`(structure, variable, value) | Converts value into the appropriate (Python) type.
  `dtype`(structure) | Returns a NumPy dtype object suitable for describing a table as a record array.
  `dtype_to_struct`(dt[, structname, enums]) | Convert a NumPy dtype object describing a record array to a typedef struct statement.
  `get_token`(string) | Removes the first 'word' from string.
  `isarray`(structure, variable) | Returns `True` if the variable is an array type.
  `isenum`(structure, variable) | Returns true if a variable is an enum type.
  `list_of_dicts`(table) | Construct a list of dictionaries.
  `new_dict_from_pairs`() | Returns a new dictionary of keyword/value pairs.
  `pairs`() | Returns a list of keys to keyword/value pairs.
  `protect`(x) | Used to appropriately quote string that might contain whitespace.
  `row`(table, index) | Returns a list containing a single row from a specified table in column order.
  `size`(table) | Returns the number of rows in a table.
  `tables`() | Returns a list of all the defined structures.
  `trailing_comment`(line) | Identify a trailing comment and strip it.
  `type`(structure, variable) | Returns the type of a variable defined in a structure.
  `write`([newfile, comments]) | Write a yanny object to a file.

  Methods Documentation

  append(datatable)

    Appends data to an existing FTCL/yanny file.

    Tries as much as possible to preserve the ordering & format of the original file. The datatable should adhere to the format of the yanny object, but it is not necessary to reproduce the ‘symbols’ dictionary. It will not try to append data to a file that does not exist. If the append is successful, the data in the object will be updated.

    Parameters:
      datatable `dict`

        The data to append.

  array_length(structure, variable)

    Returns the length of an array type or 1 if the variable is not an array.

    For character types, this is the length of a two-dimensional array, e.g., `char[5][20]` has length 5.

    Parameters:
      structure `str`

        The name of the structure that contains `variable`.

      variable `str`

        The name of the column to check for array length.

    Returns:
      `int`

        The length of the array variable

  basetype(structure, variable)

    Returns the bare type of a variable, stripping off any array information.

    Parameters:
      structure `str`

        The name of the structure that contains `variable`.

      variable `str`

        The name of the column whose type you want.

    Returns:
      `str`

        The type of the variable, stripped of array information.

  char_length(structure, variable)

    Returns the length of a character field.

    e.g. `char[5][20]` is an array of 5 strings of length 20. Returns `None` if the variable is not a character type. If the length is not specified, i.e. `char[]`, it returns the length of the largest string.

    Parameters:
      structure `str`

        The name of the structure that contains `variable`.

      variable `str`

        The name of the column to check for char length.

    Returns:
      `int` or None

        The length of the char variable.

  columns(table)

    Returns an ordered list of column names associated with a particular table.

    The order is the same order as they are defined in the yanny file.

    Parameters:
      table `str`

        The table whose columns are desired.

    Returns:
      `list`

        The list of column names.

  convert(structure, variable, value)

    Converts value into the appropriate (Python) type.

    - `short` & `int` are converted to Python `int`.

    - `long` is converted to Python `long`.

    - `float` & `double` are converted to Python `float`.

    - Other types are not altered.

    There may be further conversions into NumPy types, but this is the first stage.

    Parameters:
      structure `str`

        The name of the structure that contains `variable`.

      variable `str`

        The name of the column undergoing conversion.

      value `str`

        The value contained in a particular row of `variable`.

    Returns:
      `int`, `long`, `float` or `str`

        `value` converted to a Python numerical type.

  dtype(structure)

    Returns a NumPy dtype object suitable for describing a table as a record array.

    Treats enums as string, which is what the IDL reader does.

    Parameters:
      structure `str`

        The name of the structure.

    Returns:
      `numpy.dtype`

        A dtype object suitable for describing the yanny structure as a record array.

  static dtype_to_struct(dt, structname='mystruct', enums=None)

    Convert a NumPy dtype object describing a record array to a typedef struct statement.

    The second argument is the name of the structure. If any of the columns are enum types, enums must be a dictionary with the keys the column names, and the values are a tuple containing the name of the enum type as the first item and a tuple or list of possible values as the second item.

    Parameters:
      dt `numpy.dtype`

        The dtype of a NumPy record array.

      structname `str`, optional

        The name to give the structure in the yanny file. Defaults to ‘MYSTRUCT’.

      enums `dict`, optional

        A dictionary containing enum information. See details above.

    Returns:
      `dict`

        A dictionary suitable for setting the ‘symbols’ dictionary of a new yanny object.

  static get_token(string)

    Removes the first ‘word’ from string.

    If the ‘word’ is enclosed in double quotes, it returns the contents of the double quotes. If the ‘word’ is enclosed in braces, it returns the contents of the braces, but does not attempt to split the array. If the ‘word’ is the last word of the string, remainder is set equal to the empty string. This is basically a wrapper on some convenient regular expressions.

    Parameters:
      string `str`

        A string containing words.

    Returns:
      `tuple`

        A tuple containing the first word and the remainder of the string.

    Examples

        >>> from pydl.pydlutils.yanny import yanny
        >>> yanny.get_token("The quick brown fox")
        ('The', 'quick brown fox')

  isarray(structure, variable)

    Returns `True` if the variable is an array type.

    For character types, this means a two-dimensional array, e.g.: `char[5][20]`.

    Parameters:
      structure `str`

        The name of the structure that contains `variable`.

      variable `str`

        The name of the column to check for array type.

    Returns:
      `bool`

        `True` if the variable is an array.

  isenum(structure, variable)

    Returns true if a variable is an enum type.

    Parameters:
      structure `str`

        The name of the structure that contains `variable`.

      variable `str`

        The name of the column to check for enum type.

    Returns:
      `bool`

        `True` if the variable is enum type.

  list_of_dicts(table)

    Construct a list of dictionaries.

    Takes a table from the yanny object and constructs a list object containing one row per entry. Each item in the list is a dictionary keyed by the struct value names.

    If the yanny object instance is set up for NumPy record arrays, then the same functionality can be obtained with:

        foo = par['TABLE'][0]['column']

    Parameters:
      table `str`

        The table to convert

    Returns:
      `list`

        A list containing the rows of `table` converted to `dict`.

  new_dict_from_pairs()

    Returns a new dictionary of keyword/value pairs.

    The new dictionary (i.e., not a yanny object) contains the keys that `pairs()` returns. There are two reasons this is convenient:

    - the key ‘symbols’ that is part of the yanny object will not be present

    - a simple yanny file can be read with no further processing

    Returns:
      `OrderedDict`

        A dictionary of the keyword-value pairs that remembers the order in which they were defined in the file.

    Examples

    Read a yanny file and return only the pairs:

        >>> from os.path import dirname
        >>> from pydl.pydlutils.yanny import yanny
        >>> y = yanny(dirname(__file__)+'/tests/t/test.par')
        >>> new_dict = y.new_dict_from_pairs()
        >>> new_dict['mjd']
        '54579'
        >>> new_dict['alpha']
        'beta gamma delta'

    added: Demitri Muna, NYU 2009-04-28

  pairs()

    Returns a list of keys to keyword/value pairs.

    Equivalent to doing `self.keys()`, but with all the data tables & other control structures stripped out.

  static protect(x)

    Used to appropriately quote string that might contain whitespace.

    This method is mostly for internal use by the yanny object.

    Parameters:
      x `str`

        The data to protect.

    Returns:
      `str`

        The data with white space protected by quotes.

    Examples

        >>> from pydl.pydlutils.yanny import yanny
        >>> yanny.protect('This string contains whitespace.')
        '"This string contains whitespace."'
        >>> yanny.protect('This string contains a #hashtag.')
        '"This string contains a #hashtag."'

  row(table, index)

    Returns a list containing a single row from a specified table in column order.

    If index is out of range, it returns an empty list.

    If the yanny object instance is set up for NumPy record arrays, then a single row can be obtained with:

        row0 = par['TABLE'][0]

    Parameters:
      table `str`

        The table whose row is desired.

      index `int`

        The number of the row to return.

    Returns:
      `list`

        A row from `table`.

  size(table)

    Returns the number of rows in a table.

    Parameters:
      table `str`

        The table whose size desired.

    Returns:
      `int`

        The number of rows in `table`.

  tables()

    Returns a list of all the defined structures.

    This is just the list of keys of the object with the ‘internal’ keys removed.

  static trailing_comment(line)

    Identify a trailing comment and strip it.

    This routine works on the theory that a properly quoted comment mark will be surrounted by an odd number of double quotes, & we can skip to searching for the last one in the line.

    Parameters:
      line `str`

        A line from a yanny file potentially containing trailing comments.

    Returns:
      `str`

        The line with any trailing comment and any residual white space trimmed off.

    Notes

    This may fail in certain pathological cases, for example if a real trailing comment contains a single double-quote:

        # a 'pathological" trailing comment

    or if someone is over-enthusiastically commenting:

        # # # # # I like # characters.

    Examples

        >>> from pydl.pydlutils.yanny import yanny
        >>> yanny.trailing_comment('mystruct 1234 "#hashtag" # a comment.')
        'mystruct 1234 "#hashtag"'
        >>> yanny.trailing_comment('mystruct 1234 "#hashtag" # a "comment".')
        'mystruct 1234 "#hashtag"'

  type(structure, variable)

    Returns the type of a variable defined in a structure.

    Returns `None` if the structure or the variable is undefined.

    Parameters:
      structure `str`

        The name of the structure that contains `variable`.

      variable `str`

        The name of the column whose type you want.

    Returns:
      `str`

        The type of the variable.

  write(newfile=None, comments=None)

    Write a yanny object to a file.

    This assumes that the filename used to create the object was not that of a pre-existing file. If a file of the same name is detected, this method will not attempt to overwrite it, but will print a warning. This also assumes that the special ‘symbols’ key has been properly created. This will not necessarily make the file very human-readable, especially if the data lines are long. If the name of a new file is given, it will write to the new file (assuming it doesn’t exist). If the writing is successful, the data in the object will be updated.

    Parameters:
      newfile `str`, optional

        The name of the file to write.

      comments `str` or `list` of `str`, optional

        Comments that will be placed at the head of the file. If a single string is passed, it will be written out verbatim, although a ‘#’ character will be added if it does not already have one. If a list of strings is passed, comment characters will be added and the strings will be joined together.