# Data structure classes

## `containers`

A collection of container classes supporting the PDBx/mmCIF storage model.

A base container class is defined which supports common features of data and definition containers. PDBx data files are organized in sections called data blocks which are mapped to data containers. PDBx dictionaries contain definition sections and data sections which are mapped to definition and data containers respectively.

Data in both PDBx data files and dictionaries are organized in data categories. In the PDBx syntax individual items or data identified by labels of the form ‘_categoryName.attribute_name’. The terms category and attribute in PDBx jargon are analogous table and column in relational data model, or class and attribute in an object oriented data model.

The DataCategory class provides base storage container for instance data and definition meta data.

class pdbx.containers.CifName

  Class of utilities for CIF-style data names.

  static attribute_part(name) → str

    Get the attribute part of the name.

    Parameters

      name (str) – name

    Returns

      attribute part of name

  static category_part(name) → str

    Get the category part of the name.

    Parameters

      name (str) – name

    Returns

      category part of name

class pdbx.containers.ContainerBase(name)

  Container base class for data and definition objects.

  append(obj)

    Add the input object to the current object catalog. An existing object of the same name will be overwritten.

    Parameters

      obj (`DataCategory`) – input object to catalog

  exists(name) → bool

    Determine if object name exists in object catalog.

    Parameters

      name (str) – object name

    Returns

      whether object exists in object catalog

  get_object(name)

    Get object from object catalog.

    Parameters

      name (str) – object name

    Returns

      object or None

    Return type

      `DataCategory`

  get_object_name_list() → list

    Get list of object names.

    Returns

      list of `DataCategory` objects

  get_type() → str

    Get container type.

    Returns

      container type

  property name: str

    Get container name.

    Returns

      container name

  print_it(fobj=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, type_='brief')

    Dump information about container to specified file object.

    Parameters

      - fobj (file) – file object for writing

      - type (str) – type of summary (“brief” makes it short)

  remove(current_name) → bool

    Remove object by name.

    Parameters

      current_name (str) – name of object to remove

    Returns

      True on success or False otherwise.

  rename(current_name, new_name) → bool

    Change the name of an object in place.

    Parameters

      - current_name (str) – old name for object

      - new_name (str) – new name for object

    Returns

      indicator of whether renaming was successful

  replace(obj)

    Replace an existing object with the input object.

    Parameters

      obj (`DataCategory`) – input object to catalog

  set_name(name)

    Set container name.

    Parameters

      name (str) – container name

  set_type(type_)

    Set container type.

    Parameters

      type (str) – container type

class pdbx.containers.DataCategory(name, attribute_name_list=None, row_list=None)

  Methods for creating, accessing, formatting PDBx cif data categories.

  append(row)

    Add row to container.

    Parameters

      row (list) – row to add

  append_attribute(attribute_name)

    Add attribute to container.

    Parameters

      attribute_name (str) – name of attribute to add

  append_attribute_extend_rows(attribute_name)

    Append attribute and extend rows.

    Parameters

      attribute_name (str) – name of attribute to add

  property attribute_count: int

    Get number of attributes.

  property attribute_list: list

    Get list of attributes.

  property attribute_list_with_order: list

    Get list of attributes in order.

  property current_attribute: str

    Get current attribute.

  property current_row_index: int

    Get current row index.

  dump_it(file_=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

    Dump contents of container.

    Parameters

      file (file) – file object ready for writing

  get_attribute_index(attribute_name) → int

    Get index of given attribute.

    Parameters

      attribute_name (str) – name of attribute

    Returns

      index of attribute

    Raises

      IndexError – if attribute not found

  get_format_type_list(steps=1) → str

    Get a formatted type list.

    Parameters

      steps (int) – step size for iterating through rows

    Returns

      formatted type list

  property get_format_type_list_x: str

    Alternate version of format type list.

  get_full_row(index) → list

    Return a full row based on the length of the the attribute list.

    Parameters

      index (int) – index of row to retrieve

    Returns

      row

  get_max_attribute_list_length(steps=1) → int

    Get maximum length of attribute value list.

    Parameters

      steps (int) – step size for iterating through rows

    Returns

      attribute value list max length

  get_row(index) → list

    Get specified row.

    Parameters

      index (int) – row index

    Returns

      specified row or empty array if row not found.

  get_value(attribute_name=None, row_index=None)

    Get value for specified attribute and row.

    Parameters

      - attribute_name (str) – attribute name

      - row_index (int) – row index

    Returns

      attribute value

    Raises

      IndexError – if attribute not found

  get_value_formatted(attribute_name=None, row_index=None) → str

    Get formatted version of value.

    Parameters

      - attribute_name (str) – attribute name

      - row_index (int) – row index

    Returns

      formatted value

  get_value_formatted_by_index(attribute_index, row_index) → str

    Get value formatted by index.

    Parameters

      - attribute_name (str) – attribute name

      - row_index (int) – row index

    Returns

      formatted value

  has_attribute(attribute_name) → bool

    Indicate whether container has attribute.

  invoke_attribute_method(attribute_name, method)

    Invoke method of current attribute.

    Parameters

      - attribute_name (str) – attribute name

      - method (str) – name of attribute method

  invoke_category_method(method)

    Invoke method of current category.

    Parameters

      method (str) – name of method

  property item_name_list: list

    List of attribute names as fully qualified item names.

  property max_attribute_list_length: int

    Get maximum attribute list length.

  property name: str

    Get container name.

  print_it(file_=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

    Print container information.

    Parameters

      file (file) – file object ready for writing

  remove_row(index) → bool

    Remove specified row.

    Parameters

      index (int) – index of row to remove

    Returns

      True if successful, False otherwise

  rename_attribute(current_attribute_name, new_attribute_name) → bool

    Change the name of an attribute in place.

    Parameters

      - current_attribute_name (str) – current attribute name

      - new_attribute_name (str) – new attribute name

    Returns

      flag indicating renaming success

  replace_substring(old_value, new_value, attribute_name) → bool

    Replace substring of value of given attribute.

    Parameters

      - old_value – old attribute value

      - new_value – new attribute value

      - attribute_name (str) – name of attribute to replace

    Returns

      Boolean flag indicating success.

  replace_value(old_value, new_value, attribute_name) → int

    Replace the value of the specified attribute.

    Parameters

      - old_value – old attribute value

      - new_value – new attribute value

      - attribute_name (str) – name of attribute to replace

    Returns

      number of replacements

  property row_count: int

    Get number of rows.

  property row_list: list

    Get list of rows.

  set_value(value, attribute_name=None, row_index=None)

    Set value of attribute.

    Parameters

      - value – value of attribute to set

      - attribute_name (str) – name of attribute

      - row_index (int) – index of row

class pdbx.containers.DataCategoryBase(name, attribute_name_list=None, row_list=None)

  Base object definition for a data category.

  get() → tuple

    Get name, attribute name list, and row list.

    Returns

      tuple of (name, attribute name list, and row list)

  set_attribute_name_list(attribute_name_list)

    Set attribute name list.

    Parameters

      attribute_name_list (list) – list of attribute names

  set_name(name)

    Set name.

    Parameters

      name (str) – object name to set

  set_row_list(row_list)

    Set row list.

    Parameters

      row_list (list) – list of rows

class pdbx.containers.DataContainer(name)

  Container class for DataCategory objects.

  get_global() → bool

    Return global flag.

  invoke_data_block_method(method)

    Invoke a method for the given data block.

    Parameters

      method (str) – name of method

  set_global()

    Set global flag to True.

class pdbx.containers.DefinitionContainer(name)

  Container for definitions.

  is_attribute() → bool

    Determine if container contains item objects.

    Returns

      indicator of whether item objects are in container

  is_category() → bool

    Determine if container contains category objects.

    Returns

      indicator of whether category objects are in container

  print_it(file_=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, type_='brief')

    Print information about container to file object.

    Parameters

      - file (file) – file object for writing

      - type (str) – type of summary (“brief” makes it short)