pidibble 1.7.2__tar.gz → 1.8.0__tar.gz

{pidibble-1.7.2 → pidibble-1.8.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.8.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.8.0}/CHANGELOG.md

@@ -5,6 +5,56 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pidibble
-Version: 1.7.2
+Version: 1.8.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.8.0}/pidibble/baseparsers.py

@@ -200,7 +200,9 @@ 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"

{pidibble-1.7.2 → pidibble-1.8.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.8.0}/pidibble/pdbparse.py

@@ -60,6 +60,7 @@ class PDBParser:
                  filepath: str | Path = None,
                  mappers: dict[str, Callable] = None,
                  comment_chars: list[str] = ['#'],
+                 dialect: str = 'standard',
                  pdb_format_file: str = 'pdb_format.yaml',
                  mmcif_format_file: str = 'mmcif_format.yaml',
                  **kwargs):
@@ -83,6 +84,7 @@ class PDBParser:
             self.mappers.update(mappers)
         self.mappers.update(ListParsers)
         self.comment_chars = comment_chars
+        self.dialect = dialect
         self.pdb_lines = []
         self.cif_data = {}
 
@@ -90,6 +92,9 @@ class PDBParser:
         self.nonconformances = NonconformanceRegistry()
         self.pdb_format_dict = self._load_format(pdb_format_file)
         self.mmcif_format_dict = self._load_format(mmcif_format_file)
+        # the active record-format table for this instance's dialect; both
+        # parsing and writing read this so they stay exact inverses
+        self.record_formats = self._apply_dialect(self.pdb_format_dict, dialect)
 
         # update mappers with delimiters and custom formats
         delimiter_dict = self.pdb_format_dict.get('delimiters', {})
@@ -101,6 +106,36 @@ class PDBParser:
             if not cname in self.mappers:
                 self.mappers[cname] = BaseRecordParser(cformat, self.mappers).parse
 
+    @staticmethod
+    def _apply_dialect(pdb_format_dict, dialect):
+        """
+        Build the record-format table for a dialect.
+
+        Returns a copy of the base ``record_formats`` with the dialect's
+        coordinate-record overrides merged in. ``'standard'`` is strict wwPDB;
+        ``'charmm'`` swaps ``ATOM``/``HETATM``/``TER`` for the wide-resName,
+        segID-bearing CHARMM layouts (``charmm_formats`` in the YAML), keeping
+        x/y/z pinned at columns 31-54.
+
+        Parameters
+        ----------
+        pdb_format_dict : dict
+            The loaded PDB format file.
+        dialect : str
+            ``'standard'`` (default) or ``'charmm'``.
+
+        Returns
+        -------
+        dict
+            The active ``{record_key: format}`` mapping for the dialect.
+        """
+        record_formats = dict(pdb_format_dict['record_formats'])
+        if dialect == 'charmm':
+            record_formats.update(pdb_format_dict.get('charmm_formats', {}))
+        elif dialect != 'standard':
+            raise ValueError(f"unknown dialect {dialect!r}; expected 'standard' or 'charmm'")
+        return record_formats
+
     @staticmethod
     def _load_format(filename: str) -> dict:
         """Load a YAML format file, checking CWD first then the package resources."""
@@ -252,7 +287,7 @@ class PDBParser:
         This method uses the :class:`.mmcif_parse.MMCIF_Parser` to parse the mmCIF data and store the parsed records
         in :attr:`PDBParser.parsed`.
         """
-        mmcif_parser = MMCIF_Parser(self.mmcif_format_dict, self.pdb_format_dict['record_formats'], self.cif_data)
+        mmcif_parser = MMCIF_Parser(self.mmcif_format_dict, self.record_formats, self.cif_data)
         self.parsed = mmcif_parser.parse()
 
     def parse_PDB(self):
@@ -264,7 +299,7 @@ class PDBParser:
         """
         self._atom_serial_parser.reset()
         self.nonconformances = NonconformanceRegistry()
-        record_formats = self.pdb_format_dict['record_formats']
+        record_formats = self.record_formats
         key = ''
         record_format = {}
         group_open_record = None
@@ -368,12 +403,12 @@ class PDBParser:
             if isinstance(p, PDBRecord):
                 rf = p.format
                 if 'embedded_records' in rf:
-                    new_parsed_records.update(p.parse_embedded(self.pdb_format_dict['record_formats'], self.mappers))
+                    new_parsed_records.update(p.parse_embedded(self.record_formats, self.mappers))
             elif isinstance(p, PDBRecordList):
                 for q in p:
                     rf = q.format
                     if 'embedded_records' in rf:
-                        new_parsed_records.update(q.parse_embedded(self.pdb_format_dict['record_formats'], self.mappers))
+                        new_parsed_records.update(q.parse_embedded(self.record_formats, self.mappers))
         self.parsed.update(new_parsed_records)
 
     def parse_tokens(self):
@@ -430,6 +465,48 @@ class PDBParser:
             logger.warning(f'No data.')
         return self
 
+    def write_PDB(self, filename: str = None, anisou: bool = True, include_master: bool = True,
+                  dialect: str = None):
+        """
+        Write the parsed structure back out as a conformant PDB file.
+
+        This assembles every writable record in canonical section order —
+        single-line records (types 1/3), continuation and determinant-group
+        records (types 2/4, e.g. ``TITLE``, ``COMPND``, ``SEQRES``, ``SITE``),
+        and ``TER`` — reconstructs the coordinate section, passes ``REMARK`` and
+        ``JRNL`` through verbatim from the source, and regenerates the
+        ``MASTER``/``END`` bookkeeping records. When the parse came from mmCIF
+        (no PDB source lines), ``REMARK``/``JRNL`` are omitted and reported to
+        the logger.
+
+        Parameters
+        ----------
+        filename : str, optional
+            Destination path. If omitted, no file is written.
+        anisou : bool, optional
+            Interleave ``ANISOU`` records after their atoms (default True).
+        include_master : bool, optional
+            Regenerate a ``MASTER`` record from the emitted counts (default True).
+        dialect : str, optional
+            Column dialect to write, ``'standard'`` or ``'charmm'``. Defaults to
+            the dialect this parser was constructed with. The CHARMM dialect
+            widens ``resName`` to 6 columns and writes the authoritative segID
+            column (73-76) while pinning x/y/z at columns 31-54.
+
+        Returns
+        -------
+        list of str
+            The assembled document as a list of record lines.
+        """
+        from .pdbwrite import assemble_pdb
+        record_formats = self._apply_dialect(self.pdb_format_dict, dialect) if dialect else None
+        lines = assemble_pdb(self, anisou=anisou, include_master=include_master,
+                             record_formats=record_formats)
+        if filename:
+            with open(filename, 'w') as f:
+                f.write('\n'.join(lines) + '\n')
+        return lines
+
 def get_symm_ops(rec: PDBRecord):
     """
     Extract the symmetry operations from a PDB record.