hikari.dataframes.cif ===================== .. py:module:: hikari.dataframes.cif Attributes ---------- .. autoapisummary:: hikari.dataframes.cif.T hikari.dataframes.cif.cif_core_validator Classes ------- .. autoapisummary:: hikari.dataframes.cif.CifBlock hikari.dataframes.cif.CifFrame hikari.dataframes.cif.CifValidator hikari.dataframes.cif.CifIOBuffer hikari.dataframes.cif.CifIO hikari.dataframes.cif.CifReaderBuffer hikari.dataframes.cif.CifReader hikari.dataframes.cif.CifWriterBuffer hikari.dataframes.cif.CifWriter Module Contents --------------- .. py:data:: T .. py:class:: CifBlock(dict=None, /, **kwargs) Bases: :py:obj:`collections.UserDict` CifBlock object handles all data inside an individual block of Cif file. As a subclass of an `UserDict`, in python3.7+ it is ordered by design. Individual Cif items can be accessed or assigned using a dict-like syntax. .. py:method:: get_as_type(key, typ, default = None) Get value of `self[key]` converted to `typ`. If value is a list, convert its contents element-wise. :param key: key associated with accessed element :param typ: type/function applied to a value or its every element :param default: if given, return it on KeyError :return: value of `self[key]` or `default` converted to `typ` .. py:method:: read(path, block) Read the contents of .cif file specified by the `path` parameter, but access and store only the `block` data block in self. :param path: Absolute or relative path to the .cif file. :param block: Name of the cif data block to be accessed .. py:method:: write(path) Write the contents of `CifBlock` to the .cif file specified by the `path` parameter, using 'hikari' as block name. :param path: Absolute or relative path to the .cif file. .. py:class:: CifFrame(dict=None, /, **kwargs) Bases: :py:obj:`collections.UserDict` A master object which manages cif files. It utilises other `Cif*` classes to manage multiple :class:`CifBlock`s with crystallographic information. As a subclass of an `UserDict`, in python3.7+ it is ordered by design. Individual Cif blocks and items within them can be accessed or assigned using a single- or nested- dict-like syntax. Similarly to other `Frame`s, `CifFrame` is designed to work in-place, meaning it should be first created, and only then accessed using methods such as :func:`read` or :func:`write`, but not chain assignments. Unlike dict, CifBlock always initiates empty and does not accept any parameters at creation. .. py:method:: read(path) Read the contents of .cif file specified by the `path` parameter. Store each found block as a {block_name: CifBlock} pair. :param path: Absolute or relative path to the .cif file. .. py:method:: write(path) Write the contents of `CifFrame` to the .cif file specified by the `path` parameter. :param path: Absolute or relative path to the .cif file. .. py:class:: CifValidator Bases: :py:obj:`collections.UserDict` This object is used to validate individual cif keys when parsing cif files. It knows the metadata about each key based on its entry in the cif core dictionary v.2.4.5 packaged with the project. Since the specification itself is written in cif format, it is also read using the same `CifReader` (but without `CifValidator`). Upon initialization, `CifValidator` becomes a dictionary whose keys are all valid cif keys, according to the cif specification used. Individual values are themselves dictionaries that store information about key's contents, `_category`, `_type`, whether they are a `_list` etc. contains all keys from core cif dictionary. In order to access individual values, use `.get()` instead of bracket notation. .. py:method:: __contains__(item) .. py:method:: get(key, default = None) Get the dictionary containing information about input cif `key`. .. py:method:: get__category(key, default = None) Close equivalent to `self.get(key).get('_category', default)` .. py:method:: get__list(key, default = None) Close equivalent to `self.get(key).get('_list', default) == 'yes'` .. py:class:: CifIOBuffer(target) Bases: :py:obj:`abc.ABC` An abstract base class for Cif reader and writer buffers. Specifies that data can be added and flushed, names and values are stored in a list, output is stored in target (dict if reading, file if writing). .. py:attribute:: names :value: [] .. py:attribute:: values :value: [] .. py:method:: add(data) :abstractmethod: .. py:method:: flush() :abstractmethod: .. py:class:: CifIO(cif_file_path, validate=True) Bases: :py:obj:`abc.ABC` A base class for `CifRead` and `CifWrite`. This class and its inheritors base on the IUCr File Syntax version 1.1 Working specification available [here](`https://www.iucr.org/resources/cif/spec/version1.1/cifsyntax`) .. py:attribute:: COMMENT_REGEX .. py:attribute:: MATCHING_QUOTES_REGEX .. py:attribute:: MATCHING_OUTER_DELIMITERS_REGEX .. py:attribute:: MULTILINE_QUOTE_REGEX .. py:attribute:: WHITESPACE_SUBSTITUTES .. py:attribute:: file_contents :value: '' .. py:attribute:: file_path :value: '' .. py:attribute:: file_lines :value: [] .. py:attribute:: validate :value: True .. py:class:: CifReaderBuffer(target) Bases: :py:obj:`CifIOBuffer` Buffer for reading data from cif file into `CifReader` .. py:attribute:: target :type: dict .. py:method:: add(word) Append the word to names or values based on its first char .. py:method:: flush() Update the target dict with names and values stored hitherto .. py:class:: CifReader(cif_file_path, validate=True) Bases: :py:obj:`CifIO` A helper class managing reading cif files into :class:`~.CifFrame` or :class:`~.CifBlock`. .. py:property:: blocks :type: dict[str, int] line numbers where they start in cif file. :type: A dict of block names .. py:method:: _blocks(lines) .. py:class:: State Bases: :py:obj:`enum.Enum` This class stores current cif reading state (e.g. inside loop etc.) .. py:attribute:: default :value: 0 .. py:attribute:: loop_keys :value: 1 .. py:attribute:: loop_values :value: 2 .. py:method:: format_dictionary(parsed_dict_) Reformat a dictionary of parsed data so that the format of every name and value agrees with the cif core dictionary stored in `CifValidator`. :param parsed_dict_: Dictionary with data pairs :return: Data dictionary with correctly formatted data names and values .. py:method:: parse_lines(start, end) Read the data from :attr:`~.CifIO.lines` numbered `start` to `end`, interpret it, and return it as an instance of a dict. :param start: number of the first line which data should be read from :param end: number of the first line which should not be read anymore :return: ordered dictionary with name: value pairs for all parsed lines .. py:method:: read() Read the contents of cif currently pointed by :attr:`~.CifIO.file_path` and block :attr:`~.CifIO.data_block_header` and return them to a dict. :return: A dictionary containing information read from .cif file. .. py:method:: protect_multilines() Replace whitespace between every pair of "\n;" sequences with substitutes and remove the outer semicolons in `self.file_contents`. .. py:method:: protect_quotes() Replace whitespace between every pair of matching quotation marks (single or double) with substitutes and remove the outer quotation marks in `self.contents`. See stack overflow /q/46967465/ for details. .. py:method:: _protect_split(split_string) :classmethod: .. py:method:: remove_comments() Replace all comment blocks (whitespace or start-of-file followed by "#") within `self.file_contents` with empty strings. .. py:method:: revert_delimiters_and_whitespace(string) :classmethod: If present, remove outer delimiters (matching quotes or semicolons) from supplied string, remove `self.WHITESPACE_SUBSTITUTES` and return string. :return: `string` without outer delimiters nor whitespace substitutes. .. py:class:: CifWriterBuffer(target) Bases: :py:obj:`CifIOBuffer` Buffer for writing data from `CifReader` into cif file .. py:attribute:: MAX_NAME_LENGTH :value: 33 .. py:attribute:: MAX_LINE_LENGTH :value: 80 .. py:attribute:: MIN_STEP_LENGTH :value: 2 .. py:attribute:: WHITESPACE .. py:attribute:: target :type: TextIO .. py:attribute:: current__category :value: '' .. py:attribute:: current__list :value: False .. py:attribute:: current_len :value: 0 .. py:method:: add(data) .. py:method:: flush() .. py:method:: format_line(k, v) .. py:method:: format_table() .. py:method:: enquote(text, force = False) .. py:class:: CifWriter(cif_file_path, validate=True) Bases: :py:obj:`CifIO` A helper class managing writing :class:`~.CifFrame` or :class:`~.CifBlock` into cif files .. py:method:: write(cif_frame) .. py:data:: cif_core_validator