biotite 1.0.1__cp311-cp311-win_amd64.whl → 1.2.0__cp311-cp311-win_amd64.whl

biotite/database/afdb/download.py

@@ -0,0 +1,191 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.database.afdb"
+__author__ = "Patrick Kunzmann, Alex Carlin"
+__all__ = ["fetch"]
+
+import io
+import re
+from pathlib import Path
+from xml.etree import ElementTree
+import requests
+from biotite.database.error import RequestError
+
+_METADATA_URL = "https://alphafold.com/api/prediction"
+_BINARY_FORMATS = ["bcif"]
+# Adopted from https://www.uniprot.org/help/accession_numbers
+_UNIPROT_PATTERN = (
+    "[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9]([A-Z][A-Z0-9]{2}[0-9]){1,2}"
+)
+
+
+def fetch(ids, format, target_path=None, overwrite=False, verbose=False):
+    """
+    Download predicted protein structures from the AlphaFold DB.
+
+    This function requires an internet connection.
+
+    Parameters
+    ----------
+    ids : str or iterable object of str
+        A single ID or a list of IDs of the file(s) to be downloaded.
+        They can be either UniProt IDs (e.g. ``P12345``) or AlphaFold DB IDs
+        (e.g. ``AF-P12345F1``).
+    format : {'pdb', 'pdbx', 'cif', 'mmcif', 'bcif', 'fasta'}
+        The format of the files to be downloaded.
+    target_path : str, optional
+        The target directory of the downloaded files.
+        By default, the file content is stored in a file-like object
+        (`StringIO` or `BytesIO`, respectively).
+    overwrite : bool, optional
+        If true, existing files will be overwritten.
+        Otherwise the respective file will only be downloaded if the file does not
+        exist yet in the specified target directory or if the file is empty.
+    verbose : bool, optional
+        If true, the function will output the download progress.
+
+    Returns
+    -------
+    files : str or StringIO or BytesIO or list of (str or StringIO or BytesIO)
+        The file path(s) to the downloaded files.
+        If a single string (a single ID) was given in `ids`, a single string is
+        returned.
+        If a list (or other iterable object) was given, a list of strings is returned.
+        If no `target_path` was given, the file contents are stored in either
+        ``StringIO`` or ``BytesIO`` objects.
+
+    Examples
+    --------
+
+    >>> from pathlib import Path
+    >>> file = fetch("P12345", "cif", path_to_directory)
+    >>> print(Path(file).name)
+    P12345.cif
+    >>> files = fetch(["P12345", "Q8K9I1"], "cif", path_to_directory)
+    >>> print([Path(file).name for file in files])
+    ['P12345.cif', 'Q8K9I1.cif']
+    """
+    if format not in ["pdb", "pdbx", "cif", "mmcif", "bcif", "fasta"]:
+        raise ValueError(f"Format '{format}' is not supported")
+    if format in ["pdbx", "mmcif"]:
+        format = "cif"
+
+    # If only a single ID is present,
+    # put it into a single element list
+    if isinstance(ids, str):
+        ids = [ids]
+        single_element = True
+    else:
+        single_element = False
+    if target_path is not None:
+        target_path = Path(target_path)
+        target_path.mkdir(parents=True, exist_ok=True)
+
+    files = []
+    for i, id in enumerate(ids):
+        # Verbose output
+        if verbose:
+            print(f"Fetching file {i + 1:d} / {len(ids):d} ({id})...", end="\r")
+        # Fetch file from database
+        if target_path is not None:
+            file = target_path / f"{id}.{format}"
+        else:
+            # 'file = None' -> store content in a file-like object
+            file = None
+        if file is None or not file.is_file() or file.stat().st_size == 0 or overwrite:
+            file_response = requests.get(_get_file_url(id, format))
+            _assert_valid_file(file_response, id)
+            if format in _BINARY_FORMATS:
+                content = file_response.content
+            else:
+                content = file_response.text
+
+            if file is None:
+                if format in _BINARY_FORMATS:
+                    file = io.BytesIO(content)
+                else:
+                    file = io.StringIO(content)
+            else:
+                mode = "wb+" if format in _BINARY_FORMATS else "w+"
+                with open(file, mode) as f:
+                    f.write(content)
+
+        files.append(file)
+    if verbose:
+        print("\nDone")
+
+    # Return paths as strings
+    files = [file.as_posix() if isinstance(file, Path) else file for file in files]
+    # If input was a single ID, return only a single element
+    if single_element:
+        return files[0]
+    else:
+        return files
+
+
+def _get_file_url(id, format):
+    """
+    Get the actual file URL for the given ID from the ``prediction`` API endpoint.
+
+    Parameters
+    ----------
+    id : str
+        The ID of the file to be downloaded.
+    format : str
+        The format of the file to be downloaded.
+
+    Returns
+    -------
+    file_url : str
+        The URL of the file to be downloaded.
+    """
+    uniprot_id = _extract_id(id)
+    metadata = requests.get(f"{_METADATA_URL}/{uniprot_id}").json()
+    if len(metadata) == 0:
+        raise RequestError(f"ID {id} is invalid")
+    # A list of length 1 is always returned, if the response is valid
+    return metadata[0][f"{format}Url"]
+
+
+def _extract_id(id):
+    """
+    Extract a AFDB compatible UniProt ID from the given qualifier.
+    This may comprise
+
+    - Directly the UniProt ID (e.g. ``P12345``) (trivial case)
+    - Entry ID, as also returned by the RCSB search API (e.g. ``AF-P12345-F1``)
+
+    Parameters
+    ----------
+    id : str
+        The qualifier to extract the UniProt ID from.
+
+    Returns
+    -------
+    uniprot_id : str
+        The UniProt ID.
+    """
+    match = re.search(_UNIPROT_PATTERN, id)
+    if match is None:
+        raise ValueError(f"Cannot extract AFDB identifier from '{id}'")
+    return match.group()
+
+
+def _assert_valid_file(response, id):
+    """
+    Checks whether the response is an actual structure file
+    or the response a *404* error due to invalid UniProt ID.
+    """
+    if len(response.text) == 0:
+        raise RequestError(f"Received no repsone for '{id}'")
+    try:
+        root = ElementTree.fromstring(response.text)
+        if root.tag == "Error":
+            raise RequestError(
+                f"Error while fetching '{id}': {root.find('Message').text}"
+            )
+    except ElementTree.ParseError:
+        # This is not XML -> the response is probably a valid file
+        pass

biotite/database/entrez/dbnames.py

@@ -80,6 +80,16 @@ def sanitize_database_name(db_name):
     database name is not existing.
 
     Only for internal usage in ``download.py`` and ``query.py``.
+
+    Parameters
+    ----------
+    db_name : str
+        Entrez database name.
+
+    Returns
+    -------
+    name : str
+        E-utility database name.
     """
     if db_name in _db_names.keys():
         # Convert into E-utility database name

biotite/database/entrez/download.py

@@ -54,17 +54,16 @@ def fetch(
     db_name : str:
         E-utility or common database name.
     ret_type : str
-        Retrieval type
+        Retrieval type.
     ret_mode : str, optional
-        Retrieval mode
+        Retrieval mode.
     overwrite : bool, optional
         If true, existing files will be overwritten. Otherwise the
         respective file will only be downloaded if the file does not
         exist yet in the specified target directory or if the file is
-        empty. (Default: False)
-    verbose: bool, optional
+        empty.
+    verbose : bool, optional
         If true, the function will output the download progress.
-        (Default: False)
 
     Returns
     -------
@@ -84,9 +83,9 @@ def fetch(
     When the issue occurs repeatedly, the error is probably in your
     input.
 
-    See also
+    See Also
     --------
-    fetch_single_file
+    fetch_single_file : Fetch multiple entries as a single file.
 
     Examples
     --------
@@ -111,7 +110,7 @@ def fetch(
     for i, id in enumerate(uids):
         # Verbose output
         if verbose:
-            print(f"Fetching file {i+1:d} / {len(uids):d} ({id})...", end="\r")
+            print(f"Fetching file {i + 1:d} / {len(uids):d} ({id})...", end="\r")
         # Fetch file from database
         if target_path is not None:
             file = join(target_path, id + "." + suffix)
@@ -188,9 +187,9 @@ def fetch_single_file(
     When the issue occurs repeatedly, the error is probably in your
     input.
 
-    See also
+    See Also
     --------
-    fetch
+    fetch : Fetch one or multiple entries as separate files.
     """
     if (
         file_name is not None

biotite/database/entrez/key.py

@@ -37,7 +37,7 @@ def set_api_key(key):
 
     Parameters
     ----------
-    api_key : str
+    key : str
         The API key.
     """
     global _API_KEY

biotite/database/entrez/query.py

@@ -60,9 +60,9 @@ class CompositeQuery(Query):
 
     Parameters
     ----------
-    operator: str, {"AND", "OR", "NOT"}
+    operator : str, {"AND", "OR", "NOT"}
         The combination operator.
-    queries : iterable object of SimpleQuery
+    query1, query2 : SimpleQuery
         The queries to be combined.
 
     Examples
@@ -97,7 +97,7 @@ class SimpleQuery(Query):
 
     Parameters
     ----------
-    term: str
+    term : str
         The search term.
     field : str, optional
         The field to search the term in.
@@ -173,7 +173,8 @@ class SimpleQuery(Query):
         "SUBS",
         "WORD",
         "TI",
-        "TITL" "VOL",
+        "TITL",
+        "VOL",
     ]
 
     def __init__(self, term, field=None):

biotite/database/pubchem/download.py

@@ -41,22 +41,22 @@ def fetch(
         to be downloaded.
     format : {'sdf', 'asnt' 'asnb', 'xml', 'json', 'jsonp', 'png'}
         The format of the files to be downloaded.
+    target_path : str, optional
+        The target directory of the downloaded files.
+        By default, the file content is stored in a file-like object
+        (:class:`StringIO` or :class:`BytesIO`, respectively).
     as_structural_formula : bool, optional
         If set to true, the structural formula is download instead of
         an 3D conformer.
         This means that coordinates lie in th xy-plane and represent
         the positions atoms would have an a structural formula
         representation.
-    target_path : str, optional
-        The target directory of the downloaded files.
-        By default, the file content is stored in a file-like object
-        (:class:`StringIO` or :class:`BytesIO`, respectively).
     overwrite : bool, optional
         If true, existing files will be overwritten.
         Otherwise the respective file will only be downloaded, if the
         file does not exist yet in the specified target directory or if
         the file is empty.
-    verbose: bool, optional
+    verbose : bool, optional
         If set to true, the function will output the download progress.
     throttle_threshold : float or None, optional
         A value between 0 and 1.
@@ -114,7 +114,7 @@ def fetch(
             raise TypeError("CIDs must be given as integers, not as string")
         # Verbose output
         if verbose:
-            print(f"Fetching file {i+1:d} / {len(cids):d} ({cid})...", end="\r")
+            print(f"Fetching file {i + 1:d} / {len(cids):d} ({cid})...", end="\r")
 
         # Fetch file from database
         if target_path is not None:

biotite/database/pubchem/error.py

@@ -11,6 +11,16 @@ def parse_error_details(response_text):
     """
     Parse the ``Detail: ...`` or alternatively ``Message: ...`` part of
     an error response.
+
+    Parameters
+    ----------
+    response_text : str
+        The text of the response.
+
+    Returns
+    -------
+    error_details : str
+        The error details.
     """
     for message_line_indicator in ["Detail: ", "Message: "]:
         for line in response_text.splitlines():

biotite/database/pubchem/query.py

@@ -240,6 +240,11 @@ class FormulaQuery(Query):
             The maximum number of matches that this query may return.
             By default, the *PubChem* default value is used, which can
             be considered unlimited.
+
+        Returns
+        -------
+        query : FormulaQuery
+            The query.
         """
         element_counter = collections.Counter(atoms.element)
         formula = ""
@@ -327,7 +332,7 @@ class StructureQuery(Query, metaclass=abc.ABCMeta):
                     )
         if not query_key_found:
             raise TypeError(
-                "Expected exactly one of 'smiles', 'smarts', 'inchi', 'sdf' " "or 'cid'"
+                "Expected exactly one of 'smiles', 'smarts', 'inchi', 'sdf' or 'cid'"
             )
         if "number" in kwargs:
             self._number = kwargs["number"]
@@ -348,8 +353,13 @@ class StructureQuery(Query, metaclass=abc.ABCMeta):
         ----------
         atoms : AtomArray or AtomArrayStack
             The query structure.
-        **kwargs : dict, optional
+        *args, **kwargs
             See the constructor for additional options.
+
+        Returns
+        -------
+        query : StructureQuery
+            The query object.
         """
         mol_file = MOLFile()
         mol_file.set_structure(atoms)
@@ -448,26 +458,19 @@ class SuperOrSubstructureQuery(StructureQuery, metaclass=abc.ABCMeta):
         be considered unlimited.
     match_charges : bool, optional
         If set to true, atoms must match the specified charge.
-        (Default: False)
     match_tautomers : bool, optional
         If set to true, allow match to tautomers of the given structure.
-        (Default: False)
     rings_not_embedded : bool, optional
         If set to true, rings may not be embedded in a larger system.
-        (Default: False)
     single_double_bonds_match : bool, optional
         If set to true, single or double bonds match aromatic bonds.
-        (Default: True)
     chains_match_rings : bool, optional
         If set to true, chain bonds in the query may match rings in
         hits.
-        (Default: True)
     strip_hydrogen : bool, optional
         If set to true, remove any explicit hydrogens before searching.
-        (Default: False)
     stereo : {'ignore', 'exact', 'relative', 'nonconflicting'}, optional
         How to handle stereo.
-        (Default: 'ignore')
 
     Notes
     -----
@@ -528,26 +531,19 @@ class SuperstructureQuery(SuperOrSubstructureQuery):
         be considered unlimited.
     match_charges : bool, optional
         If set to true, atoms must match the specified charge.
-        (Default: False)
     match_tautomers : bool, optional
         If set to true, allow match to tautomers of the given structure.
-        (Default: False)
     rings_not_embedded : bool, optional
         If set to true, rings may not be embedded in a larger system.
-        (Default: False)
     single_double_bonds_match : bool, optional
         If set to true, single or double bonds match aromatic bonds.
-        (Default: True)
     chains_match_rings : bool, optional
         If set to true, chain bonds in the query may match rings in
         hits.
-        (Default: True)
     strip_hydrogen : bool, optional
         If set to true, remove any explicit hydrogens before searching.
-        (Default: False)
     stereo : {'ignore', 'exact', 'relative', 'nonconflicting'}, optional
         How to handle stereo.
-        (Default: 'ignore')
 
     Notes
     -----
@@ -601,26 +597,19 @@ class SubstructureQuery(SuperOrSubstructureQuery):
         be considered unlimited.
     match_charges : bool, optional
         If set to true, atoms must match the specified charge.
-        (Default: False)
     match_tautomers : bool, optional
         If set to true, allow match to tautomers of the given structure.
-        (Default: False)
     rings_not_embedded : bool, optional
         If set to true, rings may not be embedded in a larger system.
-        (Default: False)
     single_double_bonds_match : bool, optional
         If set to true, single or double bonds match aromatic bonds.
-        (Default: True)
     chains_match_rings : bool, optional
         If set to true, chain bonds in the query may match rings in
         hits.
-        (Default: True)
     strip_hydrogen : bool, optional
         If set to true, remove any explicit hydrogens before searching.
-        (Default: False)
     stereo : {'ignore', 'exact', 'relative', 'nonconflicting'}, optional
         How to handle stereo.
-        (Default: 'ignore')
 
     Notes
     -----

biotite/database/rcsb/download.py

@@ -44,7 +44,7 @@ def fetch(pdb_ids, format, target_path=None, overwrite=False, verbose=False):
         Otherwise the respective file will only be downloaded, if the
         file does not exist yet in the specified target directory or if
         the file is empty.
-    verbose: bool, optional
+    verbose : bool, optional
         If set to true, the function will output the download progress.
 
     Returns
@@ -91,7 +91,7 @@ def fetch(pdb_ids, format, target_path=None, overwrite=False, verbose=False):
     for i, id in enumerate(pdb_ids):
         # Verbose output
         if verbose:
-            print(f"Fetching file {i+1:d} / {len(pdb_ids):d} ({id})...", end="\r")
+            print(f"Fetching file {i + 1:d} / {len(pdb_ids):d} ({id})...", end="\r")
 
         # Fetch file from database
         if target_path is not None:
@@ -152,6 +152,7 @@ def _assert_valid_file(response_text, pdb_id):
         for err_msg in [
             "404 Not Found",
             "<title>RCSB Protein Data Bank Error Page</title>",
+            "<title>PDB Archive over AWS</title>",
             "No fasta files were found.",
             "No valid PDB IDs were submitted.",
         ]

biotite/database/rcsb/query.py

@@ -146,9 +146,9 @@ class BasicQuery(SingleQuery):
     Examples
     --------
 
-    >>> query = BasicQuery("tc5b")
+    >>> query = BasicQuery("Miniprotein Construct")
     >>> print(sorted(search(query)))
-    ['1L2Y', '8ANG', '8ANH', '8ANI', '8ANM', '8QWW']
+    ['1L2Y']
     """
 
     def __init__(self, term):
@@ -257,7 +257,7 @@ class FieldQuery(SingleQuery):
             "exists",
         ]:
             raise TypeError(
-                f"Constructor got an unexpected keyword argument " f"'{self._operator}'"
+                f"Constructor got an unexpected keyword argument '{self._operator}'"
             )
 
         # Convert dates into ISO 8601
@@ -346,9 +346,9 @@ class SequenceQuery(SingleQuery):
     --------
 
     >>> sequence = "NLYIQWLKDGGPSSGRPPPS"
-    >>> query = SequenceQuery(sequence, scope="protein", min_identity=0.8)
+    >>> query = SequenceQuery(sequence, scope="protein", min_identity=0.95)
     >>> print(sorted(search(query)))
-    ['1L2Y', '1RIJ', '2JOF', '2LDJ', '2LL5', '2MJ9', '3UC7', '3UC8']
+    ['1L2Y', '2LDJ', '9G22', '9G2N', '9G2O', '9G31', '9G32', '9GDL', '9GDN', '9GDT', '9GDU', '9GE1']
     """
 
     def __init__(self, sequence, scope, min_identity=0.0, max_expect_value=10000000.0):
@@ -441,7 +441,7 @@ class StructureQuery(SingleQuery):
 
     >>> query = StructureQuery("1L2Y", chain="A")
     >>> print(sorted(search(query)))
-    ['1L2Y', '1RIJ', '2JOF', '2LDJ', '2M7D', '7MQS']
+    ['1L2Y', '1RIJ', '2JOF', '2LDJ', '2M7D', '7MQS', '9DPF']
     """
 
     def __init__(self, pdb_id, chain=None, assembly=None, strict=True):
@@ -868,7 +868,7 @@ def search(
     ...     query, return_type="polymer_entity", return_groups=True,
     ...     group_by=UniprotGrouping(sort_by="rcsb_accession_info.initial_release_date"),
     ... ))
-     {'P24297': ['5NW3_1'], 'P27707': ['4JLJ_1'], 'P80176': ['5D8V_1'], 'O29777': ['7R0H_1'], 'P01542': ['1EJG_1', '3NIR_1']}
+    {'P24297': ['5NW3_1'], 'P27707': ['4JLJ_1'], 'P80176': ['5D8V_1'], 'O29777': ['7R0H_1'], 'P01542': ['3NIR_1', '1EJG_1']}
     """
     query_dict = _initialize_query_dict(query, return_type, group_by, content_types)
 
@@ -944,8 +944,7 @@ def _initialize_query_dict(query, return_type, group_by, content_types):
     if group_by is not None:
         if not group_by.is_compatible_return_type(return_type):
             raise ValueError(
-                f"Return type '{return_type}' is not compatible "
-                f"with the given Grouping"
+                f"Return type '{return_type}' is not compatible with the given Grouping"
             )
         request_options["group_by"] = group_by.get_content()
 

biotite/database/uniprot/check.py

@@ -10,26 +10,31 @@ from biotite.database.error import RequestError
 
 
 # Taken from https://www.uniprot.org/help/api_retrieve_entries
-def assert_valid_response(response_status_code):
+def assert_valid_response(response):
     """
     Checks whether the response is valid.
 
     Parameters
     ----------
-    response_status_code: int
-        Status code of request.get.
+    response : Response
+        Status code of :func:`requests.get()`.
     """
-    if response_status_code == 400:
-        raise RequestError("Bad request. There is a problem with your input.")
-    elif response_status_code == 404:
-        raise RequestError("Not found. The resource you requested doesn't exist.")
-    elif response_status_code == 410:
-        raise RequestError("Gone. The resource you requested was removed.")
-    elif response_status_code == 500:
-        raise RequestError(
-            "Internal server error. Most likely a temporary problem, but if the problem persists please contact UniProt team."
-        )
-    elif response_status_code == 503:
-        raise RequestError(
-            "Service not available. The server is being updated, try again later."
-        )
+    if len(response.content) == 0:
+        raise RequestError("No content returned")
+    match response.status_code:
+        case 400:
+            raise RequestError("Bad request. There is a problem with your input.")
+        case 404:
+            raise RequestError("Not found. The resource you requested doesn't exist.")
+        case 410:
+            raise RequestError("Gone. The resource you requested was removed.")
+        case 500:
+            raise RequestError(
+                "Internal server error. "
+                "Most likely a temporary problem, "
+                "but if the problem persists please contact UniProt team."
+            )
+        case 503:
+            raise RequestError(
+                "Service not available. The server is being updated, try again later."
+            )

biotite/database/uniprot/download.py

@@ -41,7 +41,6 @@ def fetch(ids, format, target_path=None, overwrite=False, verbose=False):
     Download files from the UniProt in various formats.
 
     Available databases are UniProtKB, UniRef and UniParc.
-
     This function requires an internet connection.
 
     Parameters
@@ -58,11 +57,9 @@ def fetch(ids, format, target_path=None, overwrite=False, verbose=False):
     overwrite : bool, optional
         If true, existing files will be overwritten. Otherwise the
         respective file will only be downloaded if the file does not
-        exist yet in the specified target directory or if the file is
-        empty. (Default: False)
-    verbose: bool, optional
+        exist yet in the specified target directory.
+    verbose : bool, optional
         If true, the function will output the download progress.
-        (Default: False)
 
     Returns
     -------
@@ -111,7 +108,7 @@ def fetch(ids, format, target_path=None, overwrite=False, verbose=False):
             if format in ["fasta", "gff", "txt", "xml", "rdf", "tab"]:
                 r = requests.get(_fetch_url + db_name + "/" + id + "." + format)
                 content = r.text
-                assert_valid_response(r.status_code)
+                assert_valid_response(r)
             else:
                 raise ValueError(f"Format '{format}' is not supported")
             if file is None:

biotite/database/uniprot/query.py

@@ -50,9 +50,9 @@ class CompositeQuery(Query):
 
     Parameters
     ----------
-    operator: str, {"AND", "OR", "NOT"}
+    operator : str, {"AND", "OR", "NOT"}
         The combination operator.
-    queries : iterable object of SimpleQuery
+    query1, query2 : SimpleQuery
         The queries to be combined.
     """
 
@@ -114,7 +114,7 @@ class SimpleQuery(Query):
        The list of possible fields and the required search term
        formatting can be found
        `here <https://www.uniprot.org/help/query-fields>`_.
-    term: str
+    term : str
        The search term.
     """
 
@@ -264,7 +264,6 @@ def search(query, number=500):
         The search query.
     number : int
         The maximum number of IDs that are obtained.
-        (Default: 500)
 
     Returns
     -------
@@ -289,5 +288,5 @@ def search(query, number=500):
     params = {"query": str(query), "format": "list", "size": str(number)}
     r = requests.get(_base_url, params=params)
     content = r.text
-    assert_valid_response(r.status_code)
+    assert_valid_response(r)
     return content.split("\n")[:-1]