pidibble 1.7.2__tar.gz → 1.9.0__tar.gz

{pidibble-1.7.2 → pidibble-1.9.0}/.github/workflows/release.yaml

@@ -21,7 +21,7 @@ jobs:
       id-token: write
     steps:
       - name: Download dist artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: dist
           path: dist/

{pidibble-1.7.2 → pidibble-1.9.0}/.github/workflows/tests.yaml

@@ -15,9 +15,9 @@ jobs:
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install package with test extras
@@ -31,9 +31,9 @@ jobs:
     name: doctest (docs examples)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.11"
       - name: Install docs requirements and local package

{pidibble-1.7.2 → pidibble-1.9.0}/CHANGELOG.md

@@ -5,6 +5,96 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.9.0] - 2026-07-31
+
+### Changed
+- Fields declared `Float`, `Integer`, or `HxInteger` that the source record
+  leaves blank (or whose text cannot be coerced) now parse to
+  `baseparsers.EmptyField` rather than a bare `''`. It is a `str` subclass equal
+  to `''`, falsy, written back out as blanks, and accepted anywhere `''` was
+  before — including `record.empty()`, JSON, and YAML — so existing
+  `if field == '':` / `!= ''` checks are unaffected. What it refuses is
+  impersonating a number: `float()`, `int()`, and the arithmetic operators raise
+  `TypeError` naming the field and why it is empty. Previously a blank `Float`
+  field silently evaluated `rec.length * 2` to `''` by string repetition, and
+  `float(rec.length)` raised a `ValueError` identifying neither record nor
+  field. Fields declared `String` are unchanged: there `''` is a legitimate
+  value, not a missing one.
+- The mmCIF path applies the same rule. mmCIF carries no per-attribute type, so
+  a missing value (`.`, `?`, or an omitted attribute) previously came back as a
+  bare `''` whatever the field was; the declared type is now taken from the PDB
+  record spec, at both record and sub-record level (`residue.seqNum` and
+  friends, typed from `custom_formats`). A record read from `.cif` and the same
+  record read from `.pdb` now behave identically. `MMCIF_Parser` takes a new
+  optional `custom_formats` argument to do it.
+- The writer tests' 4ZMJ structure is now a committed fixture rather than a
+  run-time RCSB download, so the unit suite runs offline on a clean checkout and
+  the byte-for-byte round-trip assertions are pinned to a known release.
+
+### Fixed
+- `baseparsers.safe_float` now recognizes a padded or capitalized NaN sentinel
+  (`'   nan'`, `'NaN'`) and not only the bare lowercase string. Float fields are
+  right-justified in fixed-column PDB, so the guard previously almost never
+  fired and `float('nan')` let a NaN propagate silently into coordinates,
+  occupancies, and B-factors.
+
+### Added
+- Regression tests for two previously untested paths: the `safe_float` NaN
+  sentinel (`tests/unit/test_baseparsers.py`) and the strict `> 99999` decimal-
+  to-hex trip threshold in `hex.AtomSerialParser` (`tests/unit/test_hex.py`).
+- An "Empty fields" section in the data-model guide documenting the convention
+  above.
+
+## [1.8.0] - 2026-07-22
+
+### Added
+- PDB *writing*: parsed structures can be serialized back to conformant
+  fixed-column PDB. `PDBParser.write_PDB()` assembles a document in canonical
+  section order, reconstructs the coordinate section (`ATOM` with interleaved
+  `ANISOU` and chain-terminating `TER` cards, then `HETATM`), and regenerates
+  the `MASTER`/`END` bookkeeping records from the emitted content. The
+  record-level engine (`pidibble.pdbwrite.PDBWriter`) is the inverse of the
+  parser, driven by the same field specs plus optional per-field writer hints
+  (`{prec, just}`) carried as a third element in the YAML field definitions.
+- Coverage spans all four writable record families: single-line records
+  (types 1/3, plus `TER`), continuation records (type 2 — `TITLE`, `COMPND`,
+  `SOURCE`, `KEYWDS`, `AUTHOR`, …), and determinant-group records (type 4 —
+  `SEQRES`, `HETNAM`, `HETSYN`, `FORMUL`, `SITE`, and the multi-line `REVDAT`),
+  re-wrapped/chunked across numbered continuation lines. `REMARK` and `JRNL`
+  (type 6) are re-emitted verbatim from the source lines.
+- A full `parse -> write -> re-parse` round-trip preserves every parsed record
+  type and all field values on 4ZMJ (60 keys) and 4TVP (64 keys, incl. `SITE`);
+  the regenerated `MASTER` matches the original entry's byte-for-byte, and the
+  coordinate/`SEQRES`/`HETNAM`/`FORMUL`/`KEYWDS`/`TITLE` records re-serialize
+  byte-exactly.
+- Hexadecimal serial numbers for structures with more than 99999 atoms (e.g.
+  large solvated systems): `HexSerialEncoder` is the exact inverse of the
+  parser's `AtomSerialParser`, switching to hex once a serial passes 99999 and
+  staying hex thereafter — including small `CONECT` back-references, which the
+  parser reads as hex once tripped. Serials round-trip up to the 5-column
+  hybrid-hex ceiling (`0xFFFFF` = 1 048 575 atoms).
+- CHARMM read/write **dialect** (`PDBParser(dialect='charmm')`,
+  `write_PDB(dialect='charmm')`), for coordinate PDBs that must stay
+  column-congruent with a CHARMM/psfgen PSF. It widens `resName` to 6 columns
+  for CHARMM/glycan names (e.g. `BGLCNA`, `ANE5AC`) and writes the authoritative
+  `segID` column (73-76) that psfgen `coordpdb` depends on, while **pinning
+  x/y/z at columns 31-54** regardless of resName width — designing out the
+  wide-resName coordinate-column drift that scrambles fixed-column readers.
+  Parser and writer share one column model (`charmm_formats`/`ResidueCharmm` in
+  the YAML) so they are exact inverses; the default `'standard'` dialect remains
+  strict wwPDB. A `parse -> write -> parse` round-trip on a glycan structure
+  with a populated segID column is the identity for every coordinate field.
+
+### Changed
+- Field specs may now carry an optional third element with writer formatting
+  hints; parsing ignores it (the byte-range unpacking is now width-tolerant), so
+  the change is fully backward-compatible.
+
+### Not yet supported
+- Re-serialization of `REMARK`/`JRNL` from the parsed model (they are passed
+  through from the source instead, so they are omitted when the input was
+  mmCIF), and multi-model coordinate sections.
+
 ## [1.7.2] - 2026-07-21
 
 ### Added

{pidibble-1.7.2 → pidibble-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pidibble
-Version: 1.7.2
+Version: 1.9.0
 Summary: A complete Protein Data Bank (PDB) file parser
 Project-URL: Source, https://github.com/cameronabrams/pidibble
 Project-URL: Documentation, https://pidibble.readthedocs.io/en/latest/

{pidibble-1.7.2 → pidibble-1.9.0}/docs/source/guide/data_model.rst

@@ -69,6 +69,41 @@ The keys shown by ``pstr()`` are exactly the attribute names:
 ``continuation`` are hidden by default) and a ``pad`` width for the labels, so
 you can widen or narrow the display or reveal the hidden internals.
 
+.. _empty-fields:
+
+Empty fields
+------------
+
+A PDB record may simply stop before its optional trailing fields, and many
+records leave interior columns blank.  Any such field reads as empty:
+
+>>> c = p.parsed['CONECT'][0]
+>>> c.partner2 == '', bool(c.partner2)
+(True, False)
+
+For a field declared ``String`` that is a plain ``''``.  For a field declared
+``Float``, ``Integer`` or ``HxInteger``, pidibble hands back an
+:class:`~pidibble.baseparsers.EmptyField` instead — still equal to ``''``, still
+falsy, still written back out as blanks, but it refuses to stand in for the
+number its type promises:
+
+>>> c.partner2 * 2                              # doctest: +IGNORE_EXCEPTION_DETAIL
+Traceback (most recent call last):
+TypeError: HxInteger field 'partner2' is empty: absent from the source record.
+It has no value to multiply; test `if rec.partner2 != '':` first.
+
+Without that guard a plain ``''`` would quietly evaluate ``c.partner2 * 2`` to
+``''`` by string repetition, and ``float(c.partner2)`` would raise a
+``ValueError`` naming neither the record nor the field.  Test for emptiness
+before doing arithmetic:
+
+>>> partners = [c.partner1, c.partner2, c.partner3, c.partner4]
+>>> [q for q in partners if q != '']
+[332]
+
+The same applies to records parsed from mmCIF, where the missing-value markers
+``.`` and ``?`` land in the same place — see :doc:`mmcif`.
+
 Residues and other structured sub-fields
 -----------------------------------------
 

{pidibble-1.7.2 → pidibble-1.9.0}/docs/source/guide/mmcif.rst

@@ -75,6 +75,26 @@ A few purely representational fields differ where the formats themselves differ.
    (``2014-06-27``) rather than the PDB ``DD-MON-YY`` form (``27-JUN-14``), and
    ``TITLE``/``KEYWDS`` text is upper-cased to match the PDB convention.
 
+Missing values
+--------------
+
+mmCIF writes an inapplicable value as ``.`` and an unknown one as ``?``; an
+attribute the file omits is missing too.  All three parse to an empty field, and
+because mmCIF carries no per-attribute type, the field's declared type is taken
+from the PDB record spec — so a missing value in a field declared ``Float``,
+``Integer`` or ``HxInteger`` yields the same guarded
+:class:`~pidibble.baseparsers.EmptyField` as it would from a ``.pdb`` file (see
+:ref:`empty-fields`).  It equals ``''`` but refuses to act as a number:
+
+.. code-block:: python
+
+   het = cif.parsed['HETATM'][0]
+   het.residue.seqNum == ''      # True -- label_seq_id is '.' for a non-polymer
+   het.residue.seqNum + 1        # TypeError: Integer field 'seqNum' is empty:
+                                 # absent from the mmCIF ('.', '?', or attribute
+                                 # not present) ...
+   het.residue_auth.seqNum       # 1 -- the auth_* copy carries the number
+
 Comparing the two parses
 ------------------------
 

pidibble-1.9.0/docs/testing-notes.md

@@ -0,0 +1,147 @@
+# Testing notes
+
+**Status:** note as of 2026-07-31 (pidibble 1.8.0). Developer reference, not
+end-user documentation. Everything below has since been acted on; see
+"Resolution" under each item.
+
+## A failing large-list assertion makes the suite appear to hang
+
+### Symptom
+
+If a regression breaks serial-number round-tripping, running the unit suite
+appears to hang indefinitely rather than report a failure:
+
+```
+tests/unit/test_pdbwrite.py::test_hex_serial_encoder_mirrors_parser PASSED [ 61%]
+tests/unit/test_pdbwrite.py::test_big_serial_document_roundtrip
+     <no further output; one core pinned at 100%, runs past 15 minutes>
+```
+
+The process is CPU-bound, not blocked on I/O or the network, which makes it look
+like an infinite loop in the parser.
+
+### Cause
+
+It is not a pidibble bug. The cost is entirely inside pytest's assertion-diff
+rendering.
+
+`test_big_serial_document_roundtrip` ends with whole-list comparisons:
+
+```python
+assert [r.serial for r in parser.parsed['ATOM']] == [r.serial for r in q.parsed['ATOM']]
+```
+
+For 4ZMJ that is **4518 elements per side**. While the lists are equal the
+assertion is cheap. Once a regression makes them differ, pytest builds a
+human-readable diff through `difflib`, and `difflib._fancy_replace` recurses via
+`_fancy_helper` computing pairwise similarity ratios across the mismatched
+block. On lists this large, made of similar-looking values (`100001`, `100002`,
+…), that descent is effectively unbounded.
+
+Observed stack at the point of the "hang":
+
+```
+difflib.py:642  in quick_ratio
+difflib.py:938  in _fancy_replace
+difflib.py:997  in _fancy_helper
+difflib.py:985  in _fancy_replace          <- recursing
+...
+_pytest/assertion/_compare_sequence.py:33  in _compare_eq_iterable
+tests/unit/test_pdbwrite.py:262            in test_big_serial_document_roundtrip
+```
+
+### Confirmation
+
+Disabling assertion introspection removes the cost completely, while the test
+still fails as it should:
+
+```console
+$ pytest tests/unit/test_pdbwrite.py::test_big_serial_document_roundtrip -q
+     <no completion; killed after 120s>
+
+$ pytest tests/unit/test_pdbwrite.py::test_big_serial_document_roundtrip -q --assert=plain
+1 failed in 0.72s
+```
+
+That is the diagnostic to reach for first: if `--assert=plain` returns
+instantly, the time is going into diff rendering, not into pidibble.
+
+Note that `-x` also hides the problem, because earlier tests in the file fail
+first and stop the run before this test is reached. A regression can therefore
+look like an ordinary failure under `-x` and like a hang without it.
+
+### Resolution (applied)
+
+`test_pdbwrite.py` now routes all three whole-list serial comparisons
+(`ATOM`, `TER`, `CONECT`) through a `_assert_serials_equal(expected, got, label)`
+helper that checks the length, then collects mismatches itself and reports only
+a bounded slice — so `difflib` is never handed a large similar-element diff:
+
+```python
+assert len(got) == len(expected), f'{label}: got {len(got)} records, expected {len(expected)}'
+mismatch = [(i, e, g) for i, (e, g) in enumerate(zip(expected, got)) if e != g]
+assert not mismatch, f'{label}: {len(mismatch)} mismatches; first 10: {mismatch[:10]}'
+```
+
+The test still fails for exactly the same regressions. Re-checked against the
+column mutation below: it now fails in **0.55s** instead of hanging, reporting
+
+```
+AssertionError: ATOM: 4518 mismatches; first 10: [(0, 100001, 34465), (1, 100002, 34466), ...]
+```
+
+which points straight at the first bad serial.
+
+### How this was found
+
+While using the suite as a measurement target, one-line mutations were applied
+to source files to generate realistic red runs. The mutation that exposed this
+was in the fixed-column field slice in `baseparsers.StringParser.parse`:
+
+```python
+# original (columns are 1-based in the PDB spec)
+fieldstring = record[byte_range[0] - 1:byte_range[1]]
+# mutated: drops the 1-based correction, shifting every field by one column
+fieldstring = record[byte_range[0]:byte_range[1]]
+```
+
+Any regression that garbles parsed serials will reproduce it; that particular
+mutation is just a convenient trigger.
+
+Two unrelated observations from the same exercise, with what came of them:
+
+- Two plausible mutations **survived** the suite — `safe_float`'s `'nan'` guard
+  in `baseparsers.py` could be deleted, and the `> 99999` hex-trip threshold in
+  `hex.AtomSerialParser.__call__` could be changed to `>= 99999`, with all 103
+  tests still passing. Both were boundary/sentinel paths with no test.
+
+  **Resolution (applied).** Both are now covered, and writing the tests turned
+  up a real defect behind the first one. `safe_float` compared the *raw* field
+  string to `'nan'`, but fixed-column float fields are right-justified, so a
+  NaN written by an upstream tool arrives as `'     nan'` — the guard almost
+  never fired, and `float('nan')` then let a NaN propagate silently into
+  coordinates and B-factors. The comparison now strips and case-folds first
+  (`x.strip().lower() == 'nan'`). Covered by
+  `tests/unit/test_baseparsers.py` (direct, plus through `StringParser.parse`
+  on a record with `nan` in a coordinate column) and by
+  `test_hex_trip_threshold_is_strictly_above_99999` in `tests/unit/test_hex.py`,
+  which pins that parsing `99999` must *not* trip hex mode — under `>=`, a
+  following `CONECT` back-reference of `'10'` would silently read as 16. Each
+  mutation was re-applied to confirm the new tests fail on it.
+
+- The network-dependence claim recorded here originally was **backwards**, and
+  is corrected as follows. `test_rcsb.py` (72 tests) and `test_hex.py` run
+  fully offline: every structure they name — `1ca2`, `4tvp`, `4zmj`,
+  `4zmj-newresnames`, `6m0j`, `8fae`, `test`, `my_system` — is a committed
+  fixture under `tests/unit/test_rcsb/` or `tests/unit/test_hex/`, and
+  `PDBParser.fetch()` only downloads when the file is absent. The one module
+  that *did* hit RCSB was `test_pdbwrite.py`, whose `4zmj.pdb` was gitignored,
+  so the byte-exactness round-trip ran against the live entry.
+
+  **Resolution (applied).** That fixture is now committed under
+  `tests/unit/test_pdbwrite/` and removed from the directory's `.gitignore`.
+  The whole unit suite therefore runs offline on a clean checkout, and the
+  byte-exact assertions are pinned to a known release rather than to whatever
+  RCSB currently serves — a re-release of 4ZMJ can no longer break them for
+  reasons unrelated to the writer. To pick up a revised entry deliberately,
+  delete the file and re-run the suite; `fetch()` will download it again.

{pidibble-1.7.2 → pidibble-1.9.0}/pidibble/baseparsers.py

@@ -7,6 +7,9 @@
 
 """
 import logging
+
+import yaml
+
 logger = logging.getLogger(__name__)
 
 class ListParser:
@@ -153,6 +156,110 @@ class NonconformanceRegistry:
             log.info(f'  {name}: {e["count"]} value(s) {kind}{eg}')
 
 
+class EmptyField(str):
+    """
+    The value of a non-String field that the source record gave no usable value
+    for -- either the columns were blank (a truncated or minimal record) or the
+    text there could not be coerced to the declared type.
+
+    It *is* the empty string: ``field == ''`` is True, ``bool(field)`` is False,
+    ``f'{field}'`` is empty, and the writer renders it as blanks. Every existing
+    emptiness test keeps working unchanged.
+
+    What it refuses to do is impersonate a number. A plain ``''`` in a field
+    declared ``Float`` bites silently -- ``rec.length * 2`` evaluates to ``''``
+    by string repetition rather than raising -- so the numeric operators are
+    overridden here to fail loudly, naming the field and why it is empty::
+
+        rec.length * 2
+        TypeError: Float field 'length' is empty: absent from the source
+        record. It has no value to multiply; test `if rec.length != '':` first.
+
+    Attributes
+    ----------
+    field : str
+        Name of the field this stood in for.
+    typestring : str
+        The field's declared type, e.g. ``'Float'``.
+    reason : str
+        Why it is empty: ``'absent from the source record'`` or
+        ``"not coercible to Float (found 'O-')"``.
+    """
+
+    def __new__(cls, field='', typestring='', reason='absent from the source record'):
+        self = super().__new__(cls, '')
+        self.field = field
+        self.typestring = typestring
+        self.reason = reason
+        return self
+
+    def _complain(self, op):
+        name = f'{self.typestring} field {self.field!r}' if self.typestring else f'field {self.field!r}'
+        return TypeError(f'{name} is empty: {self.reason}. It has no value to {op}; '
+                         f"test `if rec.{self.field or 'field'} != '':` first.")
+
+    # numeric coercions -- ValueError/AttributeError from these would be cryptic
+    def __float__(self):
+        raise self._complain('convert to float')
+
+    def __int__(self):
+        raise self._complain('convert to int')
+
+    def __index__(self):
+        raise self._complain('use as an index')
+
+    # str inherits these and they succeed silently on '', which is the trap:
+    # '' * 2 == '' and '' % x == ''.  Concatenation with another string is
+    # still allowed -- it is meaningful, and the result is a plain str.
+    def __mul__(self, other):
+        raise self._complain('multiply')
+
+    __rmul__ = __mul__
+
+    def __mod__(self, other):
+        raise self._complain('use as a format string')
+
+    def __add__(self, other):
+        if isinstance(other, str):
+            return str(self) + other
+        raise self._complain('add')
+
+    # arithmetic str does not define at all: those already raise, but the
+    # default message names only the type, so give the same guided one
+    def __sub__(self, other):
+        raise self._complain('subtract from')
+
+    def __rsub__(self, other):
+        raise self._complain('subtract')
+
+    def __truediv__(self, other):
+        raise self._complain('divide')
+
+    def __rtruediv__(self, other):
+        raise self._complain('divide by')
+
+    def __round__(self, ndigits=None):
+        raise self._complain('round')
+
+    def __abs__(self):
+        raise self._complain('take the absolute value of')
+
+    def __neg__(self):
+        raise self._complain('negate')
+
+    def __repr__(self):
+        return f'<empty {self.typestring or "field"} {self.field!r}: {self.reason}>'
+
+
+# PyYAML dispatches on exact type, so an unregistered str subclass raises
+# RepresenterError; a caller dumping parsed records must keep seeing ''.
+for _dumper in ('Dumper', 'SafeDumper', 'CDumper', 'CSafeDumper'):
+    if hasattr(yaml, _dumper):  # the C dumpers need libyaml
+        yaml.add_representer(EmptyField, lambda dumper, data: dumper.represent_str(''),
+                             Dumper=getattr(yaml, _dumper))
+del _dumper
+
+
 class StringParser:
     """
     A parser for fixed-width strings, with a customizable field map.
@@ -200,21 +307,29 @@ class StringParser:
         input_dict = {}
         record += ' ' * (80 - len(record))  # pad
         for k, v in self.fields.items():
-            typestring, byte_range = v
+            # a field spec is [typestring, byte_range] with an optional third
+            # element carrying writer hints (prec/just); parsing ignores it
+            typestring, byte_range = v[0], v[1]
             typ = self.typemap[typestring]
             assert byte_range[1] <= len(record), f'{record} {byte_range}'
             # using columns beginning with "1" not "0"
             fieldstring = record[byte_range[0] - 1:byte_range[1]]
             fieldstring = fieldstring.rstrip()
+            # a field with no usable value becomes EmptyField -- equal to '' for
+            # every emptiness test, but loud if used as the number its declared
+            # type promises. String fields keep a plain '': there the empty
+            # string is a legitimate value, not a missing one.
             try:
-                # if len(fieldstring)>0 and not typ==str:
-                #     fieldstring=''
-                input_dict[k] = '' if fieldstring == '' else typ(fieldstring)
+                if fieldstring == '':
+                    input_dict[k] = '' if typ == str else EmptyField(k, typestring)
+                else:
+                    input_dict[k] = typ(fieldstring)
             except (ValueError, TypeError):
                 self.nonconformances.append({'field': k, 'kind': f'not coercible to {typestring}',
                                              'byte_range': byte_range, 'value': fieldstring})
                 self.report_field_error(record, k)
-                input_dict[k] = ''
+                input_dict[k] = EmptyField(k, typestring,
+                                           f'not coercible to {typestring} (found {fieldstring!r})')
             if typ == str:
                 input_dict[k] = input_dict[k].strip()
             if fieldstring in self.allowed:
@@ -255,9 +370,15 @@ class StringParser:
 
 def safe_float(x):
     """
-    Convert a string to a float, returning 0.0 if the string is 'nan'.
+    Convert a string to a float, returning 0.0 if the string denotes NaN.
+
+    Fixed-column float fields are right-justified, so a NaN written by an
+    upstream tool arrives padded (``'     nan'``); the comparison is made on the
+    stripped, case-folded value so those are caught too.  ``float()`` accepts
+    'nan' happily, so without this the sentinel would propagate silently into
+    every downstream calculation.
     """
-    if x == 'nan':
+    if isinstance(x, str) and x.strip().lower() == 'nan':
         return 0.0
     return float(x)
 

{pidibble-1.7.2 → pidibble-1.9.0}/pidibble/hex.py

@@ -44,6 +44,46 @@ class AtomSerialParser:
         self._hex_tripped = False
 
 
+class HexSerialEncoder:
+    """
+    Inverse of :class:`AtomSerialParser`: render an atom serial number for a
+    fixed-width field, switching from decimal to hexadecimal once any serial
+    exceeds 99999 and staying hexadecimal thereafter.
+
+    The switch is stateful and permanent, mirroring the parser's ``_hex_tripped``
+    flag exactly. This matters because the parser, once tripped, reads *every*
+    subsequent serial field as hex — including small back-references in
+    ``CONECT`` — so those must be encoded as hex too (e.g. serial ``10`` becomes
+    ``"A"``) for the file to round-trip. One encoder instance must therefore be
+    threaded through a whole document's serial fields in emission order.
+    """
+    def __init__(self):
+        self._hex_tripped = False
+
+    def __call__(self, serial: int) -> str:
+        """
+        Encode one serial as a digit string (the caller pads it to width).
+
+        Parameters
+        ----------
+        serial : int
+            The atom serial number.
+
+        Returns
+        -------
+        str
+            Decimal digits before the decimal-to-hex trip, uppercase hex after.
+        """
+        iv = int(serial)
+        if iv > 99999:
+            self._hex_tripped = True
+        return format(iv, 'X') if self._hex_tripped else str(iv)
+
+    def reset(self):
+        """Reset to decimal mode for a fresh document."""
+        self._hex_tripped = False
+
+
 # Module-level instance kept for backward compatibility
 _default_parser = AtomSerialParser()
 

{pidibble-1.7.2 → pidibble-1.9.0}/pidibble/mmcif_parse.py

@@ -10,9 +10,19 @@
 
 from .pdbrecord import PDBRecord, PDBRecordDict, PDBRecordList
 from .baserecord import BaseRecord
+from .baseparsers import EmptyField
 import logging
 logger = logging.getLogger(__name__)
 
+# mmCIF spells a missing value '.' (inapplicable) or '?' (unknown); an attribute
+# the file simply omits is missing too. rectify() flattens all three to ''.
+MMCIF_EMPTY_REASON = "absent from the mmCIF ('.', '?', or attribute not present)"
+
+def _is_bare_empty(value):
+    """True for a plain empty string -- not for one already guarded, and not for
+    the empty list that ``as_list`` fields legitimately carry."""
+    return type(value) is str and value == ''
+
 def split_ri(ri):
     """
     Split a residue identifier into its sequence number and insertion code.
@@ -76,10 +86,15 @@ class MMCIF_Parser:
         A dictionary defining the PDB formats to be parsed.
     cif_data : object
         An object containing the CIF data to be parsed.
+    custom_formats : dict, optional
+        The ``custom_formats`` block of the PDB format file, used to type the
+        fields of nested sub-records such as residues. Without it, empty
+        sub-record fields stay plain ``''``.
     """
-    def __init__(self, mmcif_formats, pdb_formats, cif_data):
+    def __init__(self, mmcif_formats, pdb_formats, cif_data, custom_formats=None):
         self.formats = mmcif_formats
         self.pdb_formats = pdb_formats
+        self.custom_formats = custom_formats or {}
         self.global_maps = {}
         self.global_ids = {}
         self.cif_data = cif_data
@@ -389,6 +404,50 @@ class MMCIF_Parser:
                             idict[k] = v.upper()
         return idicts
 
+    def _guard_empty_fields(self, rectype, idict):
+        """
+        Replace bare ``''`` values with :class:`~pidibble.baseparsers.EmptyField`
+        wherever the corresponding PDB record field is declared numeric.
+
+        mmCIF carries no per-attribute type, so :func:`rectify` infers one from
+        the text and returns ``''`` for a missing value whatever the field is.
+        The PDB format spec *does* declare the type, and the same record read
+        from a ``.pdb`` file gets a guarded empty there (see
+        :meth:`~pidibble.baseparsers.StringParser.parse`) -- so apply the same
+        rule here, and a caller can treat both sources identically.
+
+        Parameters
+        ----------
+        rectype : str
+            The PDB record type these fields belong to, e.g. ``'SSBOND'``.
+        idict : dict
+            The assembled ``{field: value}`` dict, modified in place.
+
+        Returns
+        -------
+        dict
+            The same dict, for convenience.
+        """
+        fields = (self.pdb_formats.get(rectype) or {}).get('fields', {})
+        for k, v in idict.items():
+            spec = fields.get(k)
+            if spec is None:            # bookkeeping key, or field the PDB spec has no slot for
+                continue
+            if isinstance(v, (PDBRecord, BaseRecord)):
+                self._guard_subrecord(spec[0], v)
+            elif _is_bare_empty(v) and spec[0] != 'String':
+                idict[k] = EmptyField(k, spec[0], MMCIF_EMPTY_REASON)
+        return idict
+
+    def _guard_subrecord(self, typestring, record):
+        """Apply :meth:`_guard_empty_fields`' rule to a nested sub-record whose
+        layout is named by a custom format (``Residue11``, ``Biomtrow``, …)."""
+        subfields = self.custom_formats.get(typestring, {})
+        for k, v in vars(record).items():
+            spec = subfields.get(k)
+            if spec is not None and _is_bare_empty(v) and spec[0] != 'String':
+                setattr(record, k, EmptyField(k, spec[0], MMCIF_EMPTY_REASON))
+
     def parse(self):
         """
         Parse the mmCIF data and generate a dictionary of :class:`pdbrecord.PDBRecord` instances.
@@ -403,6 +462,7 @@ class MMCIF_Parser:
         for rectype, mapspec in self.formats.items():
             idicts = self.gen_dict(mapspec)
             for idict in idicts:
+                self._guard_empty_fields(rectype, idict)
                 this_key = idict.get('tmp_label', '')
                 reckey = rectype if not this_key else f'{rectype}.{this_key}'
                 if reckey in recdict: