pidibble 1.7.1__tar.gz → 1.7.2__tar.gz

pidibble-1.7.2/.github/workflows/tests.yaml

@@ -0,0 +1,45 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  pytest:
+    name: pytest (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with test extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[test]
+      - name: Run unit tests
+        run: pytest tests/unit -q
+
+  doctest:
+    name: doctest (docs examples)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install docs requirements and local package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+          pip install -e .        # test the working tree, not the PyPI build
+      - name: Run documentation doctests
+        run: python -m sphinx -b doctest docs/source docs/_build/doctest

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

@@ -5,6 +5,25 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.7.2] - 2026-07-21
+
+### Added
+- Continuous-integration workflow (`tests.yaml`) running the unit tests on
+  Python 3.10–3.12 and the documentation doctests on every push and pull
+  request. Previously tests ran only on tagged releases.
+- README now documents PDBx/mmCIF parsing (with a worked example) and carries
+  version, Python-versions, license, tests, docs, and downloads badges.
+
+### Changed
+- Documentation overhauled from a single quickstart page into a multi-page User
+  Guide — loading structures, the parsed data model, working with records,
+  biological assemblies and symmetry, PDBx/mmCIF, large structures, nonconformant
+  files, and advanced/customization — plus a supported-record-types coverage
+  table. Numerous example corrections; every doctest is now validated
+  (`sphinx -b doctest`), with `NORMALIZE_WHITESPACE` enabled so pretty-printed
+  output validates on content rather than incidental spacing. The docs landing
+  page is retitled from "Welcome to Pidibble's documentation!" to "pidibble".
+
 ## [1.7.1] - 2026-07-15
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pidibble
-Version: 1.7.1
+Version: 1.7.2
 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/
@@ -19,15 +19,20 @@ Requires-Dist: pytest; extra == 'test'
 Description-Content-Type: text/markdown
 
 # Pidibble 
-> a complete PDB-file parser
+> a complete parser for PDB and PDBx/mmCIF files
 
+[![PyPI version](https://img.shields.io/pypi/v/pidibble.svg)](https://pypi.org/project/pidibble/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pidibble.svg)](https://pypi.org/project/pidibble/)
+[![License](https://img.shields.io/pypi/l/pidibble.svg)](https://github.com/cameronabrams/pidibble/blob/main/LICENSE)
+[![Tests](https://github.com/cameronabrams/pidibble/actions/workflows/tests.yaml/badge.svg)](https://github.com/cameronabrams/pidibble/actions/workflows/tests.yaml)
+[![Documentation Status](https://readthedocs.org/projects/pidibble/badge/?version=latest)](https://pidibble.readthedocs.io/en/latest/)
 [![PyPI Downloads](https://static.pepy.tech/badge/pidibble)](https://pepy.tech/projects/pidibble)
 
-Pidibble is a Python package for parsing standard Protein Data Bank (PDB) files.  It conforms to the [most recent standard](https://www.wwpdb.org/documentation/file-format-content/format33/v3.3.html) (v.3.3 Atomic Coordinate Entry Format, ca. 2011).
+Pidibble is a Python package for parsing Protein Data Bank structures in both the legacy [PDB format](https://www.wwpdb.org/documentation/file-format-content/format33/v3.3.html) (v.3.3 Atomic Coordinate Entry Format, ca. 2011) and the modern [PDBx/mmCIF format](https://mmcif.wwpdb.org/) that is now standard at the RCSB.
 
 Unlike parsers like that found in packages like [BioPython](https://biopython.org/wiki/PDBParser), `pidibble` provides meaningfully parsed objects from *all* standard PDB record types, not just ATOMs and CONECTs.
 
-Once installed, the user has access to the `PDBParser` class in the `pidibble.pdbparser` module.
+Once installed, the user has access to the `PDBParser` class in the `pidibble.pdbparse` module.  Full documentation is at [pidibble.readthedocs.io](https://pidibble.readthedocs.io/en/latest/).
 
 # Example interactive usage
 
@@ -40,9 +45,11 @@ VIRAL PROTEIN
 04-MAY-15
 >>> print (p.parsed['HEADER'].idCode)
 4ZMJ
->>> keys=list(sorted(list(p.parsed.keys())))
->>> print(keys)
-['ANISOU', 'ATOM', 'AUTHOR', 'CISPEP', 'COMPND', 'CONECT', 'CRYST1', 'DBREF', 'END', 'EXPDTA', 'FORMUL', 'HEADER', 'HELIX', 'HET', 'HETATM', 'HETNAM', 'JRNL.AUTH', 'JRNL.DOI', 'JRNL.PMID', 'JRNL.REF', 'JRNL.REFN', 'JRNL.TITL', 'KEYWDS', 'LINK', 'MASTER', 'ORIGX1', 'ORIGX2', 'ORIGX3', 'REMARK.100', 'REMARK.2', 'REMARK.200', 'REMARK.280', 'REMARK.290', 'REMARK.290.CRYSTSYMMTRANS', 'REMARK.3', 'REMARK.300', 'REMARK.350', 'REMARK.350.BIOMOLECULE.1', 'REMARK.4', 'REMARK.465', 'REMARK.500', 'REVDAT', 'SCALE1', 'SCALE2', 'SCALE3', 'SEQADV', 'SEQRES', 'SHEET', 'SOURCE', 'SSBOND', 'TER', 'TITLE']
+>>> keys=sorted(p.parsed.keys())
+>>> len(keys)
+60
+>>> keys[:8]
+['ANISOU', 'ATOM', 'AUTHOR', 'CISPEP', 'COMPND', 'CONECT', 'CRYST1', 'DBREF']
 >>> header=p.parsed['HEADER']
 >>> print(header.pstr())
 HEADER
@@ -72,7 +79,7 @@ ATOM
 
 ```
 >>> from pidibble.pdbparse import PDBParser
->>> p=PDBParser(alphafold='O46077').parse()
+>>> p=PDBParser(source_db='alphafold', source_id='O46077').parse()
 >>> p.parsed['TITLE'].title
 'ALPHAFOLD MONOMER V2.0 PREDICTION FOR ODORANT RECEPTOR 2A (O46077)'
 >>> print(p.parsed['ATOM'][0].pstr())
@@ -92,6 +99,23 @@ ATOM
 
 ```
 
+# Example reading a PDBx/mmCIF file
+
+Many recent RCSB entries have no legacy PDB file at all.  Pass `input_format='mmCIF'` and pidibble parses the mmCIF/PDBx file into the *same* record objects (using author numbering), so downstream code stays the same:
+
+```
+>>> from pidibble.pdbparse import PDBParser
+>>> p=PDBParser(source_db='rcsb', source_id='4tvp', input_format='mmCIF').parse()
+>>> p.parsed['HEADER'].idCode
+'4TVP'
+>>> p.parsed['HEADER'].classification
+'VIRAL PROTEIN/IMMUNE SYSTEM'
+>>> len(p.parsed['ATOM'])
+11344
+```
+
+See the [mmCIF guide](https://pidibble.readthedocs.io/en/latest/guide/mmcif.html) for the full coverage and the small, deliberate differences from the PDB parse.
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for the full release history.

pidibble-1.7.2/README.md

@@ -0,0 +1,101 @@
+# Pidibble 
+> a complete parser for PDB and PDBx/mmCIF files
+
+[![PyPI version](https://img.shields.io/pypi/v/pidibble.svg)](https://pypi.org/project/pidibble/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pidibble.svg)](https://pypi.org/project/pidibble/)
+[![License](https://img.shields.io/pypi/l/pidibble.svg)](https://github.com/cameronabrams/pidibble/blob/main/LICENSE)
+[![Tests](https://github.com/cameronabrams/pidibble/actions/workflows/tests.yaml/badge.svg)](https://github.com/cameronabrams/pidibble/actions/workflows/tests.yaml)
+[![Documentation Status](https://readthedocs.org/projects/pidibble/badge/?version=latest)](https://pidibble.readthedocs.io/en/latest/)
+[![PyPI Downloads](https://static.pepy.tech/badge/pidibble)](https://pepy.tech/projects/pidibble)
+
+Pidibble is a Python package for parsing Protein Data Bank structures in both the legacy [PDB format](https://www.wwpdb.org/documentation/file-format-content/format33/v3.3.html) (v.3.3 Atomic Coordinate Entry Format, ca. 2011) and the modern [PDBx/mmCIF format](https://mmcif.wwpdb.org/) that is now standard at the RCSB.
+
+Unlike parsers like that found in packages like [BioPython](https://biopython.org/wiki/PDBParser), `pidibble` provides meaningfully parsed objects from *all* standard PDB record types, not just ATOMs and CONECTs.
+
+Once installed, the user has access to the `PDBParser` class in the `pidibble.pdbparse` module.  Full documentation is at [pidibble.readthedocs.io](https://pidibble.readthedocs.io/en/latest/).
+
+# Example interactive usage
+
+```
+>>> from pidibble.pdbparse import PDBParser
+>>> p=PDBParser(PDBcode='4zmj').parse()
+>>> print (p.parsed['HEADER'].classification)
+VIRAL PROTEIN
+>>> print (p.parsed['HEADER'].depDate)
+04-MAY-15
+>>> print (p.parsed['HEADER'].idCode)
+4ZMJ
+>>> keys=sorted(p.parsed.keys())
+>>> len(keys)
+60
+>>> keys[:8]
+['ANISOU', 'ATOM', 'AUTHOR', 'CISPEP', 'COMPND', 'CONECT', 'CRYST1', 'DBREF']
+>>> header=p.parsed['HEADER']
+>>> print(header.pstr())
+HEADER
+      classification: VIRAL PROTEIN
+             depDate: 04-MAY-15
+              idCode: 4ZMJ
+>>> atoms=p.parsed['ATOM']
+>>> len(atoms)
+4518
+>>> print(atoms[0].pstr())
+ATOM
+              serial: 1
+                name: N
+              altLoc: 
+             residue: resName: LEU; chainID: G; seqNum: 34; iCode: 
+                   x: -0.092
+                   y: 99.33
+                   z: 57.967
+           occupancy: 1.0
+          tempFactor: 137.71
+             element: N
+              charge: 
+
+```
+
+# Example downloading from AlphaFold
+
+```
+>>> from pidibble.pdbparse import PDBParser
+>>> p=PDBParser(source_db='alphafold', source_id='O46077').parse()
+>>> p.parsed['TITLE'].title
+'ALPHAFOLD MONOMER V2.0 PREDICTION FOR ODORANT RECEPTOR 2A (O46077)'
+>>> print(p.parsed['ATOM'][0].pstr())
+ATOM
+              serial: 1
+                name: N
+              altLoc: 
+             residue: resName: MET; chainID: A; seqNum: 1; iCode: 
+                   x: -0.553
+                   y: 26.513
+                   z: 23.174
+           occupancy: 1.0
+          tempFactor: 39.74
+             element: N
+              charge: 
+
+
+```
+
+# Example reading a PDBx/mmCIF file
+
+Many recent RCSB entries have no legacy PDB file at all.  Pass `input_format='mmCIF'` and pidibble parses the mmCIF/PDBx file into the *same* record objects (using author numbering), so downstream code stays the same:
+
+```
+>>> from pidibble.pdbparse import PDBParser
+>>> p=PDBParser(source_db='rcsb', source_id='4tvp', input_format='mmCIF').parse()
+>>> p.parsed['HEADER'].idCode
+'4TVP'
+>>> p.parsed['HEADER'].classification
+'VIRAL PROTEIN/IMMUNE SYSTEM'
+>>> len(p.parsed['ATOM'])
+11344
+```
+
+See the [mmCIF guide](https://pidibble.readthedocs.io/en/latest/guide/mmcif.html) for the full coverage and the small, deliberate differences from the PDB parse.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.

{pidibble-1.7.1 → pidibble-1.7.2}/docs/source/conf.py

@@ -2,12 +2,21 @@
 
 # -- Project information
 
+import doctest
 import importlib.metadata
 
+# Pretty-printed record output (``pstr()``) carries trailing spaces and a final
+# blank line, and numpy array reprs pad columns in version-dependent ways.
+# Normalizing whitespace lets the doctests validate content without being held
+# hostage to invisible spacing.
+doctest_default_flags = (doctest.ELLIPSIS
+                         | doctest.NORMALIZE_WHITESPACE
+                         | doctest.IGNORE_EXCEPTION_DETAIL)
+
 project = 'pidibble'
 release = importlib.metadata.version(project)
 version = '.'.join(release.split('.')[:2])  # major.minor
-copyright = '2023-2025, Cameron F. Abrams'
+copyright = '2023-2026, Cameron F. Abrams'
 author = 'cfa22@drexel.edu'
 
 # -- General configuration

pidibble-1.7.2/docs/source/guide/advanced.rst

@@ -0,0 +1,94 @@
+Advanced usage and customization
+================================
+
+pidibble is driven by a declarative description of the PDB and mmCIF formats, and
+several constructor arguments let you extend or override it.
+
+Custom field mappers
+--------------------
+
+Every field in the format specification names a *type*, and each type maps to a
+callable that turns the raw column text into a Python value.  The built-in types
+are ``String``, ``Integer``, ``Float`` and ``HxInteger`` (the hexadecimal-aware
+atom-serial type), plus a family of list parsers.
+
+You can add or override these with the ``mappers`` argument — a dict from type
+name to a one-argument callable.  This is the hook for a custom type used by a
+custom format, or for changing how an existing type is coerced:
+
+.. code-block:: python
+
+   def tenths(text):
+       return round(float(text), 1)
+
+   p = PDBParser(source_db='rcsb', source_id='4zmj',
+                 mappers={'Float': tenths}).parse()
+
+Your mappers are merged over the defaults, so you only supply what you want to
+change.
+
+Comment characters
+------------------
+
+By default, lines beginning with ``#`` are treated as comments and skipped.  Pass
+``comment_chars`` to change that set — for example, to also ignore ``!`` lines:
+
+.. code-block:: python
+
+   p = PDBParser(filepath='annotated.pdb', comment_chars=['#', '!']).parse()
+
+Overriding the format specification
+-----------------------------------
+
+The PDB and mmCIF record definitions are shipped as YAML resources
+(``pdb_format.yaml`` and ``mmcif_format.yaml``).  To parse a nonstandard dialect
+or add a record type, point the parser at your own files:
+
+.. code-block:: python
+
+   p = PDBParser(filepath='custom.pdb',
+                 pdb_format_file='my_pdb_format.yaml').parse()
+
+   c = PDBParser(filepath='custom.cif', input_format='mmCIF',
+                 mmcif_format_file='my_mmcif_format.yaml').parse()
+
+The format-specification schema
+-------------------------------
+
+Each record type in ``pdb_format.yaml`` is described by a small set of keys:
+
+``type``
+   The record's cardinality/shape: one-time-one-line, one-time-multiple-lines,
+   multiple-times-one-line, multiple-times-multiple-lines, grouping, or other.
+
+``fields``
+   A mapping of field name to a ``[type, [start, end]]`` pair giving the field's
+   data type and its (1-based, inclusive) column range.
+
+``continues``
+   The fields that a continuation record appends to or extends.
+
+``token_formats``
+   How a field's text is broken into named tokens (with optional ``determinants``
+   that group token/value pairs) — this is what produces the token groups of
+   ``COMPND`` and ``SOURCE``.
+
+``concatenate``
+   New fields built by list-concatenating other fields.
+
+``allowed``
+   Per-field lists of allowed values, for validation.
+
+``determinants``
+   The fields whose values decide whether a line starts a new record instance or
+   continues the current one.
+
+``subrecords``
+   How to parse variant sub-formats, selected by the value of a ``branchon``
+   field.
+
+``tables``
+   How embedded tables (such as the ``BIOMT`` matrices) are parsed out.
+
+Reusable sub-formats (for example the ``Residue`` variants and the ``Biomt`` row)
+live under ``custom_formats`` and are referenced by name from field definitions.

pidibble-1.7.2/docs/source/guide/assemblies.rst

@@ -0,0 +1,88 @@
+Biological assemblies and symmetry
+==================================
+
+The biologically relevant molecule is often larger than the contents of the
+asymmetric unit — it is generated by applying a set of rotation/translation
+operators to some subset of chains.  The PDB records this under ``REMARK 350``,
+and pidibble parses each operator into its own indexed sub-record.
+
+>>> from pidibble.pdbparse import PDBParser
+>>> p = PDBParser(source_db='rcsb', source_id='4zmj').parse()
+
+Assembly transforms
+-------------------
+
+Each transform for biological assembly 1 is a record keyed
+``REMARK.350.BIOMOLECULE1.TRANSFORM<n>``:
+
+>>> t1 = p.parsed['REMARK.350.BIOMOLECULE1.TRANSFORM1']
+
+The ``header`` attribute of the *first* transform of an assembly lists the chains
+the operators apply to:
+
+>>> t1.header
+['G', 'B', 'A', 'C', 'D']
+
+Turning a transform into matrices
+---------------------------------
+
+The helper :func:`~pidibble.pdbparse.get_symm_ops` converts a transform record
+into a 3×3 rotation matrix ``M`` and a translation vector ``T`` as
+:class:`numpy.ndarray`\ s:
+
+>>> from pidibble.pdbparse import get_symm_ops
+>>> M, T = get_symm_ops(t1)
+>>> M
+array([[1., 0., 0.],
+       [0., 1., 0.],
+       [0., 0., 1.]])
+>>> T
+array([0., 0., 0.])
+
+The first transform is the identity (the asymmetric unit itself); the others
+build out the assembly.  For 4ZMJ — a trimer — transforms 2 and 3 are the ±120°
+rotations of a three-fold axis:
+
+>>> M, T = get_symm_ops(p.parsed['REMARK.350.BIOMOLECULE1.TRANSFORM2'])
+>>> M
+array([[-0.5     , -0.866025,  0.      ],
+       [ 0.866025, -0.5     ,  0.      ],
+       [ 0.      ,  0.      ,  1.      ]])
+>>> T
+array([107.18   , 185.64121,   0.     ])
+
+Applying an operator to coordinates is then just ``M @ xyz + T``:
+
+.. code-block:: python
+
+   import numpy as np
+
+   assembly = []
+   for key in sorted(k for k in p.parsed if k.startswith('REMARK.350.BIOMOLECULE1.TRANSFORM')):
+       M, T = get_symm_ops(p.parsed[key])
+       for atom in p.parsed['ATOM']:
+           if atom.residue.chainID in p.parsed['REMARK.350.BIOMOLECULE1.TRANSFORM1'].header:
+               xyz = np.array([atom.x, atom.y, atom.z])
+               assembly.append(M @ xyz + T)
+
+Crystallographic symmetry
+-------------------------
+
+Crystallographic symmetry operators (the space-group operations under
+``REMARK 290``) are parsed the same way, into
+``REMARK.290.CRYSTSYMMTRANS.<n>`` sub-records that also work with
+:func:`~pidibble.pdbparse.get_symm_ops`:
+
+>>> ops = sorted(k for k in p.parsed if k.startswith('REMARK.290.CRYSTSYMMTRANS'))
+>>> len(ops)
+6
+>>> M, T = get_symm_ops(p.parsed[ops[0]])    # the first operator is the identity
+
+The unit cell and space group themselves are in ``CRYST1`` (with fields ``a``,
+``b``, ``c``, ``alpha``, ``beta``, ``gamma``, ``sGroup`` and ``z``):
+
+>>> c = p.parsed['CRYST1']
+>>> c.sGroup
+'P 63'
+>>> c.a, c.b, c.c
+(107.18, 107.18, 103.06)

pidibble-1.7.2/docs/source/guide/data_model.rst

@@ -0,0 +1,110 @@
+The parsed data model
+=====================
+
+After :meth:`~pidibble.pdbparse.PDBParser.parse`, everything pidibble extracted
+lives in one attribute:
+
+>>> from pidibble.pdbparse import PDBParser
+>>> p = PDBParser(source_db='rcsb', source_id='4zmj').parse()
+>>> p.parsed                                    # doctest: +ELLIPSIS
+{...}
+
+``parsed`` is a :class:`~pidibble.pdbrecord.PDBRecordDict` — a dictionary keyed
+by record type.
+
+Single records versus record lists
+----------------------------------
+
+Each value is one of two things:
+
+* a single :class:`~pidibble.pdbrecord.PDBRecord`, for records that occur once
+  per structure (``HEADER``, ``TITLE``, ``CRYST1``, …); or
+* a :class:`~pidibble.pdbrecord.PDBRecordList` of ``PDBRecord`` instances, for
+  *multiple-entry* records that recur (``ATOM``, ``SEQRES``, ``LINK``, …).
+
+``PDBRecordList`` subclasses :class:`collections.UserList`, so test for it with
+``isinstance`` — a plain ``type(v) == list`` check never matches, because a
+``UserList`` is not a ``list``:
+
+>>> from pidibble.pdbrecord import PDBRecordList
+>>> isinstance(p.parsed['ATOM'], PDBRecordList)      # a multiple-entry record
+True
+>>> isinstance(p.parsed['HEADER'], PDBRecordList)    # a single-instance record
+False
+>>> [k for k, v in p.parsed.items() if type(v) == list]   # the naive check never matches
+[]
+
+For everyday use, a ``PDBRecordList`` behaves like a list — index it, slice it,
+iterate it, take its ``len``:
+
+>>> atoms = p.parsed['ATOM']
+>>> len(atoms)
+4518
+>>> first, last = atoms[0], atoms[-1]
+
+Which records land in which bucket is documented per record type in
+:doc:`record_reference`.
+
+Records and their fields
+------------------------
+
+A :class:`~pidibble.pdbrecord.PDBRecord` stores each parsed field as an instance
+attribute of the appropriate Python type — strings, ``int``, ``float``, or
+nested record objects.  The quickest way to see what a record contains is
+:meth:`~pidibble.baserecord.BaseRecord.pstr` ("pretty string"):
+
+>>> print(p.parsed['HEADER'].pstr())
+HEADER
+      classification: VIRAL PROTEIN
+             depDate: 04-MAY-15
+              idCode: 4ZMJ
+
+The keys shown by ``pstr()`` are exactly the attribute names:
+
+>>> h = p.parsed['HEADER']
+>>> h.classification, h.depDate, h.idCode
+('VIRAL PROTEIN', '04-MAY-15', '4ZMJ')
+
+``pstr()`` takes an ``excludes`` list (bookkeeping fields ``key``, ``format`` and
+``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.
+
+Residues and other structured sub-fields
+-----------------------------------------
+
+Some fields are not scalars but small structured objects.  The most common is a
+**residue**, which groups a residue name, chain id, sequence number and
+insertion code:
+
+>>> a = p.parsed['ATOM'][0]
+>>> print(a.residue)                            # doctest: +NORMALIZE_WHITESPACE
+resName: LEU; chainID: G; seqNum: 34; iCode:
+>>> a.residue.resName, a.residue.chainID, a.residue.seqNum
+('LEU', 'G', 34)
+
+Records that describe a *relationship between* residues expose more than one:
+
+>>> b = p.parsed['SSBOND'][0]
+>>> b.residue1.resName, b.residue1.chainID, b.residue1.seqNum
+('CYS', 'G', 54)
+>>> b.residue2.resName, b.residue2.chainID, b.residue2.seqNum
+('CYS', 'G', 74)
+
+Working with the model as a whole
+---------------------------------
+
+Because ``parsed`` is an ordinary mapping, the usual idioms apply — membership
+tests, iteration, comprehensions:
+
+>>> 'ATOM' in p.parsed and 'HETATM' in p.parsed
+True
+>>> n_hetatm = len(p.parsed['HETATM'])
+>>> chains = {a.residue.chainID for a in p.parsed['ATOM']}
+>>> sorted(chains)
+['B', 'G']
+
+A record type that was not present in the file is simply absent from ``parsed``,
+so guard with ``in`` (or ``dict.get``) before reaching for an optional record:
+
+>>> 'SPLIT' in p.parsed
+False

pidibble-1.7.2/docs/source/guide/index.rst

@@ -0,0 +1,20 @@
+.. _user-guide:
+
+User Guide
+==========
+
+The guide works through pidibble one topic at a time.  If you just want a taste,
+start with the :doc:`../quickstart`.
+
+.. toctree::
+   :maxdepth: 2
+
+   loading
+   data_model
+   records
+   assemblies
+   mmcif
+   large_structures
+   nonconformance
+   advanced
+   record_reference

pidibble-1.7.2/docs/source/guide/large_structures.rst

@@ -0,0 +1,41 @@
+Large structures and hexadecimal serials
+=========================================
+
+The legacy PDB format allots five columns to the atom serial number, so it can
+only count up to ``99999``.  Structures with more atoms than that continue the
+count in **hexadecimal** (``100000`` is written ``186A0``), a widely used
+convention that a naive integer parse would get wrong.
+
+pidibble handles this automatically — there is nothing you need to configure.
+Each :class:`~pidibble.pdbparse.PDBParser` owns an
+:class:`~pidibble.hex.AtomSerialParser` that watches the atom serial column and
+switches to hexadecimal parsing at the right moment, so ``serial`` (and the
+serial references in ``CONECT``, ``TER`` and ``ANISOU``) stay correct past
+``99999``:
+
+.. code-block:: python
+
+   p = PDBParser(source_db='rcsb', source_id='<large-entry>').parse()
+   p.parsed['ATOM'][100000].serial      # a correct integer, not a mis-parsed hex string
+
+How the switch is detected
+--------------------------
+
+The transition to hexadecimal is recognized two ways, so it works whether or not
+the early serial numbers happen to contain the digits ``a``–``f``:
+
+* **By content** — as soon as a serial contains a hexadecimal letter, subsequent
+  serials are read as hexadecimal.
+* **By magnitude** — if the running value exceeds ``99999``, the parser trips into
+  hexadecimal mode even for an all-numeric field.
+
+The switch is *latching*: once tripped it stays in hexadecimal mode for the rest
+of the parse.  Because the state lives on the parser instance (not in a global),
+parsing several structures in the same program — or in several threads — never
+lets one file's numbering leak into another's.
+
+.. note::
+
+   Hexadecimal detection is applied **only** to atom-serial fields.  Ordinary
+   integer fields (residue sequence numbers, counts, and the like) are always
+   read as decimal, including legitimately negative values.