pidibble 1.2.2__tar.gz → 1.3.0__tar.gz

{pidibble-1.2.2 → pidibble-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pidibble
-Version: 1.2.2
+Version: 1.3.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/
@@ -16,7 +16,10 @@ Requires-Dist: numpy>=1.24
 Requires-Dist: pyyaml>=6
 Description-Content-Type: text/markdown
 
-# Pidibble - a complete PDB parser
+# Pidibble 
+> a complete PDB-file parser
+
+[![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).
 
@@ -88,7 +91,9 @@ ATOM
 ```
 
 ## Release History
-* 1.2.2:
+* 1.3.0
+   * streamline class attribute usage; full API documentation
+* 1.2.3:
    * bugfix: negative resids allowed
 * 1.2.1:
    * bugfix: hex issues AGAIN

{pidibble-1.2.2 → pidibble-1.3.0}/README.md

@@ -1,4 +1,7 @@
-# Pidibble - a complete PDB parser
+# Pidibble 
+> a complete PDB-file parser
+
+[![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).
 
@@ -70,7 +73,9 @@ ATOM
 ```
 
 ## Release History
-* 1.2.2:
+* 1.3.0
+   * streamline class attribute usage; full API documentation
+* 1.2.3:
    * bugfix: negative resids allowed
 * 1.2.1:
    * bugfix: hex issues AGAIN

pidibble-1.3.0/docs/source/_static/css/custom.css

@@ -0,0 +1,12 @@
+.github-icon svg,
+.linkedin-icon svg {
+    transition: fill 0.3s;
+}
+
+.github-icon svg:hover {
+    fill: #4078c0;  /* GitHub icon turns blue on hover */
+}
+
+.linkedin-icon svg:hover {
+    fill: #0A66C2;  /* LinkedIn icon turns its official blue on hover */
+}

pidibble-1.3.0/docs/source/api/API.rst

@@ -0,0 +1,7 @@
+pidibble
+========
+
+.. toctree::
+   :maxdepth: 4
+
+   pidibble

pidibble-1.3.0/docs/source/api/pidibble.baseparsers.rst

@@ -0,0 +1,7 @@
+pidibble.baseparsers module
+===========================
+
+.. automodule:: pidibble.baseparsers
+   :members:
+   :show-inheritance:
+   :undoc-members:

pidibble-1.3.0/docs/source/api/pidibble.baserecord.rst

@@ -0,0 +1,7 @@
+pidibble.baserecord module
+==========================
+
+.. automodule:: pidibble.baserecord
+   :members:
+   :show-inheritance:
+   :undoc-members:

pidibble-1.3.0/docs/source/api/pidibble.hex.rst

@@ -0,0 +1,7 @@
+pidibble.hex module
+===================
+
+.. automodule:: pidibble.hex
+   :members:
+   :show-inheritance:
+   :undoc-members:

pidibble-1.3.0/docs/source/api/pidibble.mmcif_parse.rst

@@ -0,0 +1,7 @@
+pidibble.mmcif\_parse module
+============================
+
+.. automodule:: pidibble.mmcif_parse
+   :members:
+   :show-inheritance:
+   :undoc-members:

pidibble-1.3.0/docs/source/api/pidibble.pdbparse.rst

@@ -0,0 +1,7 @@
+pidibble.pdbparse module
+========================
+
+.. automodule:: pidibble.pdbparse
+   :members:
+   :show-inheritance:
+   :undoc-members:

pidibble-1.3.0/docs/source/api/pidibble.pdbrecord.rst

@@ -0,0 +1,7 @@
+pidibble.pdbrecord module
+=========================
+
+.. automodule:: pidibble.pdbrecord
+   :members:
+   :show-inheritance:
+   :undoc-members:

pidibble-1.3.0/docs/source/api/pidibble.resources.rst

@@ -0,0 +1,7 @@
+pidibble.resources package
+==========================
+
+.. automodule:: pidibble.resources
+   :members:
+   :show-inheritance:
+   :undoc-members:

pidibble-1.3.0/docs/source/api/pidibble.rst

@@ -0,0 +1,28 @@
+pidibble package
+================
+
+.. automodule:: pidibble
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pidibble.resources
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pidibble.baseparsers
+   pidibble.baserecord
+   pidibble.hex
+   pidibble.mmcif_parse
+   pidibble.pdbparse
+   pidibble.pdbrecord

pidibble-1.3.0/docs/source/conf.py

@@ -0,0 +1,85 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+import importlib.metadata
+
+project = 'pidibble'
+release = importlib.metadata.version(project)
+version = '.'.join(release.split('.')[:2])  # major.minor
+copyright = '2023-2025, Cameron F. Abrams'
+author = 'cfa22@drexel.edu'
+
+# -- General configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'sphinx_copybutton',
+    'sphinxcontrib.mermaid',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+]
+
+autosummary_generate = True  # Enable autosummary tables
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+}
+
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'furo'
+html_theme_options = {
+    "light_css_variables": {
+        "color-icon": "#000000"  # Black for light mode
+    },
+    "dark_css_variables": {
+        "color-icon": "#FFFFFF"  # White for dark mode
+    },
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/cameronabrams/ycleptic",
+            "html": """
+    <svg role="img" width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="currentColor">
+        <title>GitHub</title>
+        <path d="M12 0C5.37 0 0 5.37 0 12c0 5.3 3.44 9.8 8.21 11.39.6.11.82-.26.82-.58v-2.03c-3.34.73-4.04-1.61-4.04-1.61-.54-1.38-1.33-1.75-1.33-1.75-1.09-.75.08-.74.08-.74 1.2.08 1.83 1.23 1.83 1.23 1.07 1.83 2.81 1.3 3.5.99.11-.77.42-1.3.76-1.6-2.67-.3-5.47-1.34-5.47-5.98 0-1.32.47-2.4 1.24-3.24-.12-.3-.54-1.51.12-3.14 0 0 1.01-.32 3.3 1.23a11.38 11.38 0 0 1 3 0c2.28-1.55 3.3-1.23 3.3-1.23.66 1.63.24 2.84.12 3.14.77.84 1.24 1.92 1.24 3.24 0 4.65-2.8 5.68-5.47 5.98.43.37.81 1.1.81 2.22v3.29c0 .32.22.69.82.58C20.56 21.8 24 17.3 24 12c0-6.63-5.37-12-12-12z"/>
+    </svg>
+""",
+
+            "class": "github-icon",
+        },
+        {
+            "name": "LinkedIn",
+            "url": "https://linkedin.com/in/cameron-abrams-b0143398",
+            "html": """
+                <svg role="img" width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="currentColor">
+                    <title>LinkedIn</title>
+                    <path d="M20.447 20.452h-3.554v-5.403c0-1.288-.025-2.945-1.796-2.945-1.796 0-2.071 1.4-2.071 2.847v5.501h-3.554V9.001h3.414v1.561h.05c.475-.9 1.637-1.797 3.368-1.797 3.599 0 4.262 2.368 4.262 5.446v6.241zM5.337 7.433c-1.144 0-2.072-.93-2.072-2.072 0-1.142.928-2.07 2.072-2.07 1.142 0 2.07.928 2.07 2.07 0 1.144-.928 2.072-2.07 2.072zM6.814 20.452H3.859V9.001h2.955v11.451zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.543C0 23.225.792 24 1.771 24h20.451C23.208 24 24 23.225 24 22.272V1.729C24 .774 23.208 0 22.225 0z"/>
+                </svg>
+            """,
+            "class": "linkedin-icon",
+        }
+    ],
+}
+
+html_static_path = ['_static']
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'
+
+mermaid_params = ['--theme', 'dark', '--width', '600']
+
+def setup(app):
+    print("✅ Setting up custom directives...") 
+    app.add_css_file("css/custom.css")

{pidibble-1.2.2 → pidibble-1.3.0}/docs/source/index.rst

@@ -1,13 +1,13 @@
 Welcome to Pidibble's documentation!
 ====================================
 
-**Pidibble** is a Python package for parsing 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 (PDB) files in both legacy PDB and modern PDBx/mmCIF formats.  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).
 
-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.
+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 ``ATOM`` and ``CONECT`` records.
 
-Once installed, the user has access to the ``PDBParser`` class in the ``pidibble.pdbparser`` module.
+Once installed, the user has access to the :class:`PDBParser` class in the :mod:`pidibble.pdbparser` module.
 
-Pidibble can fetch coordinate files from the RSCB PDB and from the AlphaFold model database.
+Pidibble can fetch coordinate files from the `RSCB PDB <https://www.rcsb.org/>`_ and from the `AlphaFold model database <https://alphafold.ebi.ac.uk/>`_.
 
 Pidibble can handle hexadecimal serial numbers in all record types.
 
@@ -25,6 +25,8 @@ Contents
 --------
 
 .. toctree::
+   :maxdepth: 2
 
+   installation
    usage
-   api
+   API <api/API>

pidibble-1.3.0/docs/source/installation.rst

@@ -0,0 +1,16 @@
+.. _installation:
+
+Installation
+============
+
+To use ``Pidibble``, install it from PyPI:
+
+.. code-block:: bash
+
+   (.venv) $ pip install pidibble
+
+Pidibble is under active development, so you can also install the latest version from the GitHub repository:
+
+.. code-block:: bash
+
+   (.venv) $ pip install git+https://github.com/cfa22/pidibble.git

{pidibble-1.2.2 → pidibble-1.3.0}/docs/source/usage.rst

@@ -1,23 +1,6 @@
 Usage
 =====
 
-.. _installation:
-
-Installation
-------------
-
-To use Pidibble, install it from PyPI:
-
-.. code-block:: console
-
-   (.venv) $ pip install pidibble
-
-Pidibble is also available via ``conda``: 
-
-.. code-block:: console
-
-   (conda-env) $ conda install -c conda-forge pidibble
-
 Usage Example
 -------------
 

pidibble-1.3.0/pidibble/__init__.py

@@ -0,0 +1,8 @@
+# Author: Cameron F. Abrams <cfa22@drexel.edu>
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("pidibble")
+except PackageNotFoundError:
+    __version__ = "unknown"

pidibble-1.3.0/pidibble/baseparsers.py

@@ -0,0 +1,180 @@
+"""
+
+.. module:: baseparsers
+   :synopsis: defines some basic string and list parsing functions
+   
+.. moduleauthor: Cameron F. Abrams, <cfa22@drexel.edu>
+
+"""
+import logging
+logger=logging.getLogger(__name__)
+
+class ListParser:
+    """
+    A simple parser for lists of strings, with a customizable delimiter.
+    """
+
+    def __init__(self,d=','):
+        self.d=d
+    
+    def parse(self,string):
+        """
+        Parse a string into a list of strings, using the specified delimiter.
+        If no delimiter is specified, it splits on whitespace.
+        
+        Parameters
+        ----------
+        string : str
+            The string to parse.
+
+        Returns
+        -------
+        list
+            A list of strings parsed from the input string.
+        """
+        if self.d==None:
+            return [x for x in string.split() if x.strip()!='']
+        else:
+            return [x.strip() for x in string.split(self.d) if x.strip()!='']
+    
+def list_parse(obj,d):
+    """
+    A factory function to create a ListParser with a specific delimiter.
+
+    Parameters
+    ----------
+    obj : type
+        The class to instantiate (should be ListParser).
+    d : str or None
+        The delimiter to use for parsing. If None, it will split on whitespace.
+
+    Returns
+    -------
+    function
+        A function that takes a string and returns a list of parsed strings.
+    """
+    return obj(d).parse
+
+"""
+Define a dictionary of parsers for different list formats
+"""
+ListParsers={
+    'CList':list_parse(ListParser,','),
+    'SList':list_parse(ListParser,';'),
+    'WList':list_parse(ListParser,None),
+    'DList':list_parse(ListParser,':'),
+    'LList':list_parse(ListParser,'\n')
+}
+
+_cols="""
+         1         2         3         4         5         6         7         8
+12345678901234567890123456789012345678901234567890123456789012345678901234567890"""
+class StringParser:
+    """
+    A parser for fixed-width strings, with a customizable field map.
+    
+    Parameters
+    ----------
+    fmtdict : dict
+        A dictionary mapping field names to tuples of (type, byte_range).
+    typemap : dict
+        A dictionary mapping type names to Python types.
+    allowed : dict, optional
+        A dictionary mapping field values to allowed values, for validation.
+    """
+    def __init__(self,fmtdict,typemap,allowed={}):
+        self.typemap=typemap
+        self.fields={k:v for k,v in fmtdict.items()}
+        self.allowed=allowed
+
+    def parse(self,record):
+        """
+        Parse a fixed-width string record into a dictionary of fields.
+        
+        Parameters
+        ----------
+        record : str
+            The fixed-width string record to parse.
+
+        Returns
+        -------
+        dict
+            A dictionary of fields parsed from the input record.
+        """
+        if len(record)>80:
+            logger.warning('The following record exceeds 80 bytes in length:')
+            self.report_record_error(record)
+        assert len(record)<=80,f'Record is too long; something wrong with your PDB file?'
+        input_dict={}
+        record+=' '*(80-len(record)) # pad
+        for k,v in self.fields.items():
+            typestring,byte_range=v
+            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()
+            try:
+                # if len(fieldstring)>0 and not typ==str:
+                #     fieldstring=''
+                input_dict[k]='' if fieldstring=='' else typ(fieldstring)
+            except:
+                self.report_field_error(record,k)
+                input_dict[k]=''
+            if typ==str:
+                input_dict[k]=input_dict[k].strip()
+            if fieldstring in self.allowed:
+                assert input_dict[k] in self.allowed[fieldstring],f'Value {input_dict[k]} is not allowed for field {k}; allowed values are {self.allowed[fieldstring]}'
+        return input_dict
+    
+    def report_record_error(self,record,byte_range=[]):
+        """
+        Report an error in parsing a fixed-width string record.
+        
+        Parameters
+        ----------
+        record : str
+            The fixed-width string record that caused the error.
+        byte_range : list, optional
+            A list of byte ranges to highlight in the error message.
+            If empty, the entire record is reported. 
+        """
+        if byte_range:
+            record=record[:byte_range[0]-1]+'\033[91m'+record[byte_range[0]:byte_range[1]+1]+'\033[0m'+record[byte_range[1]+1:]
+        repstr=_cols+'\n'+record
+        logger.warning(repstr)
+        
+    def report_field_error(self,record,k):
+        """
+        Report an error in parsing a specific field from a fixed-width string record.
+        
+        Parameters
+        ----------
+        record : str
+            The fixed-width string record that caused the error.
+        k : str
+            The field name that caused the error.
+        """
+        byte_range=self.fields[k][1]
+        logger.warning(f'Could not parse field {k} from bytes {byte_range}:')
+        self.report_record_error(record,byte_range=byte_range)
+
+def safe_float(x):
+    """
+    Convert a string to a float, returning 0.0 if the string is 'nan'.
+    """
+    if x=='nan':
+        return 0.0
+    return float(x)
+
+def str2int_sig(arg:str):
+    """
+    Convert a string to an integer, returning -1 if the string is not numeric.
+    If the string starts with a '-', it is returned as an integer.
+    """
+    if not arg.strip().isnumeric():
+        if arg.strip()[0]=='-':
+            return int(arg)
+        else:
+            return -1
+    return int(arg)

pidibble-1.3.0/pidibble/baserecord.py

@@ -0,0 +1,131 @@
+"""
+
+.. module:: baserecord
+   :synopsis: defines the BaseRecord class
+   
+.. moduleauthor: Cameron F. Abrams, <cfa22@drexel.edu>
+
+"""
+from .baseparsers import StringParser
+import logging
+logger=logging.getLogger(__name__)
+
+def rstr(d,excludes,pad):
+    """
+    Generate a formatted string representation of a dictionary, excluding specified keys.
+    
+    Parameters
+    ----------
+    d : dict
+        The dictionary to format.
+    excludes : list
+        A list of keys to exclude from the output.
+    pad : int
+        The padding for the keys in the output string.
+    
+    Returns
+    -------
+    str
+        A formatted string representation of the dictionary.
+    """
+    retstr=''
+    kfstr=r'{:>'+str(pad)+r's}:'
+    for k,v in d.items():
+        if not k in excludes:
+            retstr+=kfstr.format(k)
+            if type(v)==dict:
+                retstr+='\n'
+                retstr+=rstr(v,excludes,pad+5)
+            elif hasattr(v,'__len__') and not type(v)==str:
+                ch=['','']
+                if hasattr(v[0],'__dict__'):
+                    ch=['[',']']
+                retstr+=' '+', '.join([f'{ch[0]}{str(x)}{ch[1]}' for x in v])+'\n'
+            else: # type(v)==str:
+                retstr+=f' {str(v)}'+'\n'
+    return retstr    
+
+class BaseRecord:
+    """
+    A class representing a base record with fields and methods for parsing and displaying.
+    """
+    def __init__(self,input_dict):
+        self.__dict__.update(input_dict)
+
+    def empty(self):
+        """
+        Check if the record is empty, meaning all fields are empty strings.
+
+        Returns
+        -------
+        bool
+            True if all fields are empty strings, False otherwise.
+        """
+        isempty=True
+        for v in self.__dict__.values():
+            isempty&=(v=='')
+        return isempty
+    
+    def __str__(self):
+        """
+        Generate a string representation of the BaseRecord instance.
+        
+        Returns
+        -------
+        str
+            A string representation of the BaseRecord instance, showing its attributes and values.
+        """
+        return '; '.join([f'{k}: {v}' for k,v in self.__dict__.items()])
+    
+    def pstr(self,excludes=['key','format','continuation'],pad=20):
+        """
+        Generate a formatted string representation of the BaseRecord instance, excluding specified keys.
+
+        Parameters
+        ----------
+        excludes : list, optional
+            A list of keys to exclude from the output (default is ['key', 'format', 'continuation']).
+        pad : int, optional
+            The padding for the keys in the output string (default is 20).
+
+        Returns
+        -------
+        str
+            A formatted string representation of the BaseRecord instance, excluding specified keys.
+        """
+        retstr=f'{self.key}'+'\n'
+        retstr+=rstr(self.__dict__,excludes,pad)
+        return retstr
+
+class BaseRecordParser(StringParser):
+    """
+    A parser for fixed-width string records that generates BaseRecord instances.  Inherits from :class:`StringParser`.
+    """
+
+    def add_fields(self,fields):
+        """
+        Add fields to the parser's field map.
+
+        Parameters
+        ----------
+        fields : dict
+            A dictionary of fields to add to the parser's field map.
+        """
+        self.fields.update(fields)
+
+    def parse(self,record):
+        """
+        Parse a fixed-width string record into a BaseRecord instance.
+        
+        Parameters
+        ----------
+        record : str
+            The fixed-width string record to parse.
+            
+        Returns
+        -------
+        BaseRecord
+            A BaseRecord instance containing the parsed fields.
+        """
+        input_dict=super().parse(record)
+        return BaseRecord(input_dict)

pidibble-1.3.0/pidibble/hex.py

@@ -0,0 +1,40 @@
+# Author: Cameron F. Abrams <cfa22@drexel.edu>
+"""
+Function for detecting a switch from decimal to hexadecimal in integer parsing.
+This is used to determine if a string should be parsed as a hexadecimal number or a plain decimal integer.
+"""
+__hex_tripped__=False
+def str2atomSerial(arg):
+    """
+    Convert a string representation of an atom serial number to an integer.  Should be used in cases were an integer series changes format from decimal representation to hexadecimal representation beyond 99999.  The transition is signaled by the presence of hexadecimal characters in the string, which sets a global flag to indicate that subsequent strings should be parsed as hexadecimal numbers.
+
+    Parameters
+    ----------
+    arg : str
+        The string representation of the atom serial number.
+
+    Returns
+    -------
+    int
+        The integer representation of the atom serial number.
+    """
+    global __hex_tripped__
+    assert type(arg)==str
+    if arg=='nan':
+        return_object=0
+    elif __hex_tripped__ or any([(x in arg) for x in 'abcdefABCDEF']):
+        return_object=int(arg,16)
+    elif '*' in arg:
+        return_object=0
+    else:
+        return_object=int(arg)
+    if return_object>99999 and not __hex_tripped__:
+        __hex_tripped__=True
+    return return_object
+
+def hex_reset():
+    """
+    Reset the hexadecimal parsing flag.
+    """
+    global __hex_tripped__
+    __hex_tripped__=False