nuri.fmt

class nuri.fmt.MoleculeReader
__iter__(self: MoleculeReader) → MoleculeReader

Returns itself.

__next__(self: MoleculeReader) → Molecule

Returns the next molecule.

CIF Format Support

from nuri.fmt import cif

CIF format-specific handlers and utilities.

class nuri.fmt.cif.Block
__init__(self: Block, data: Frame, save: Iterable[Frame] = ()) → None

Construct a CIF block.

Parameters:

  • data – The main frame of the block; its name is used as the block name.

  • save – The save frames contained in the block.

Raises:

ValueError – If a save frame has an empty name or two share a name.

property data
property is_global
property name
property save_frames
class nuri.fmt.cif.Frame
__init__(self: Frame, name: str, tables: Sequence[Table]) → None

Construct a CIF frame (data block body or save frame) from tables.

Parameters:

  • name – The frame name.

  • tables – The tables that make up the frame.

Raises:

ValueError – If a column key is duplicated across the tables.

as_ddl2_dict(self: Frame) → dict[str, list[dict[str, str | None]]]

Convert this DDL2 (mmCIF) frame to a dictionary of lists of dictionaries.

Returns:

A dictionary of lists of dictionaries, where the keys are the parent keys and the values are the rows of the table.

as_mols(self: Frame) → list[Molecule]

Load this frame as a list of molecules.

Returns:

A list of molecules loaded from the frame.

prefix_search_first(self: Frame, prefix: str) → Table | None

Search for the first table containing a column starting with the given prefix.

Parameters:

prefix – The prefix to search for.

Returns:

The first table containing the given prefix, or None if not found.

property name
class nuri.fmt.cif.Table
__init__(self: Table, keys: Sequence[str], rows: Sequence[Sequence[str | int | float | bool | Value | None]], category: str = '', column_formats: dict[str, ColumnFormat] = {}) → None

Construct a CIF table from column keys and rows of values.

Parameters:

  • keys – The column keys, given without the leading underscore (e.g. ["atom_site.id", "atom_site.type_symbol"]); a _ is prepended to each.

  • rows – The rows of the table. Each row must have exactly len(keys) cells. A cell may be a str, int, bool, float, None, or a Value.

  • category – Optional DDL2 category. When non-empty, each key is formed as _<category>.<key>, so keys may list just the attribute names (e.g. category="atom_site", keys=["id", "type_symbol"]). Empty (the default) leaves keys as given.

  • column_formats – Optional per-column formatting options, mapping a column key (as given in keys) to a ColumnFormat applied when a plain scalar (or None) cell in that column is converted. Each option applies only to cells of its matching type (see ColumnFormat); columns not listed use the defaults. Explicit Value cells are unaffected.

Raises:

  • ValueError – If a row length differs from the number of keys, a key is not a valid or unique CIF data name, or column_formats names an unknown key.

  • TypeError – If a cell has an unsupported type.

keys(self: Table) → list[str]
class nuri.fmt.cif.Value

An explicit CIF value, for use as a Table cell.

Most cells can be given as plain Python objects (str, int, bool, float, or None); construct a Value directly only when you need control over the formatting. The constructor is overloaded on the type of value.

__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: nuri.fmt.cif.Value, value: str, raw: bool = False) -> None

Store text as a CIF value.

Parameters:

  • value – The text to store.

  • raw – If True, store the text as an unquoted generic literal (e.g. a standard-uncertainty token like 1.234(5)). Defaults to False: a string, quoted on write only if its content requires it.

  1. __init__(self: nuri.fmt.cif.Value, value: bool, short_form: bool = False) -> None

Store a boolean CIF value.

Parameters:

  • value – The boolean to store.

  • short_form – Use y/n instead of yes/no.

  1. __init__(self: nuri.fmt.cif.Value, value: int, width: int = 0) -> None

Store an integer CIF value.

Parameters:

  • value – The integer to store.

  • width – If positive, zero-pad the number to at least this many digits.

  1. __init__(self: nuri.fmt.cif.Value, value: float, precision: Optional[int] = None, coerce_nonfinite: bool = False, null_token: str = ‘?’) -> None

Store a floating-point CIF value.

Parameters:

  • value – The number to store.

  • precision – Digits after the decimal point; if None (the default), yields at most 6 significant digits. Must be non-negative if provided.

  • coerce_nonfinite – How to handle a non-finite value. If False (the default), a non-finite value has no valid CIF representation and raises ValueError when serialized. If True, NaN becomes the null value chosen by null_token and +/-Inf becomes the sentinel +/-8e+88888888, which any IEEE-conformant parser (up to binary256) reads back as the original infinity.

  • null_token – The CIF null token that NaN is coerced to when coerce_nonfinite is True: "?" (the default) for unknown, or "." for inapplicable. Ignored for finite values.

Raises:

ValueError – If null_token is not "?" or ".".

  1. __init__(self: nuri.fmt.cif.Value, value: None, null_token: str = ‘?’) -> None

Store a null CIF value.

Parameters:

  • value – None.

  • null_token – The CIF null token: "?" (the default) for the unknown value, or "." for the inapplicable value.

Raises:

ValueError – If null_token is not "?" or ".".

class nuri.fmt.cif.ColumnFormat
property coerce_nonfinite
property null_token
property precision
property raw
property short_form
property width
nuri.fmt.cif.read_blocks(path: PathLike) → Iterator[Block]

Create a parser object from a CIF file path.

Parameters:

path – The path to the CIF file.

Returns:

An iterator over the blocks in the file.

nuri.fmt.cif.write(*args, **kwargs)

Overloaded function.

  1. write(frame: nuri.fmt.cif.Frame, align: bool = False) -> str

Serialize a CIF frame to a CIF 1.1 string.

Parameters:

  • frame – The Frame to serialize, written as a data_ block. Both freshly constructed and parsed objects are accepted.

  • align – Whether to pad the columns of loop_ tables so that values line up. Defaults to False.

Returns:

The serialized CIF string.

Raises:

ValueError – If a value cannot be represented in CIF 1.1.

  1. write(block: nuri.fmt.cif.Block, align: bool = False) -> str

Serialize a CIF block to a CIF 1.1 string.

Parameters:

  • block – The Block to serialize.

  • align – Whether to pad the columns of loop_ tables so that values line up. Defaults to False.

Returns:

The serialized CIF string.

Raises:

ValueError – If a value cannot be represented in CIF 1.1.

Note

A global_ block (only ever produced by the parser, from a STAR file) is written back as-is, i.e. as a global_ block. This is a STAR construct and is not valid CIF 1.1; a warning is logged in that case.

>>> import nuri
>>> table = nuri.fmt.cif.Table(["x.a", "x.b"], [[1, "two words"], [None, nuri.fmt.cif.Value(None, null_token=".")]])
>>> block = nuri.fmt.cif.Block(nuri.fmt.cif.Frame("demo", [table]))
>>> print(nuri.fmt.cif.write(block))
data_demo
loop_
_x.a
_x.b
1 'two words'
? .

PDB Format Support

from nuri.fmt import pdb

PDB format-specific handlers and utilities.

class nuri.fmt.pdb.Atom
property element
property formal_charge
property hetero
property name
property res_id
property sites
class nuri.fmt.pdb.AtomSite
property altloc
property occupancy
property pos
property tempfactor
class nuri.fmt.pdb.Chain
property id
property res_idxs
class nuri.fmt.pdb.Model
as_dict(self: Model) → dict

Convert the PDB model to a dictionary.

property atoms
property chains
property major_conf
property props
property residues
class nuri.fmt.pdb.Residue
property atom_idxs
property id
property name
class nuri.fmt.pdb.ResidueId
property chain_id
property ins_code
property res_seq
nuri.fmt.pdb.read_models(path: PathLike, skip_on_error: bool = False) → list[Model]

Read PDB models from a file.

Parameters:

  • path – The path to the PDB file.

  • skip_on_error – Whether to skip a model if an error occurs, instead of raising an exception.

Raises:

  • OSError – If any file-related error occurs.

  • ValueError – If reading a model fails, unless skip_on_error is set.