biotite 0.38.0__cp310-cp310-win_amd64.whl → 0.40.0__cp310-cp310-win_amd64.whl

biotite/database/entrez/query.py

@@ -11,13 +11,11 @@ import abc
 from xml.etree import ElementTree
 from .check import check_for_errors
 from .dbnames import sanitize_database_name
+from ..error import RequestError
+from .key import get_api_key
 
 
-_base_url = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/"
-
-_search_url = ("esearch.fcgi?db={:}"
-              "&term={:}"
-              "&retmax={:}")
+_search_url = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi"
 
 class Query(metaclass=abc.ABCMeta):
     """
@@ -26,21 +24,21 @@ class Query(metaclass=abc.ABCMeta):
     """
     def __init__(self):
         pass
-    
+
     @abc.abstractmethod
     def __str__(self):
         pass
-    
+
     def __or__(self, operand):
         if not isinstance(operand, Query):
             operand = SimpleQuery(operand)
         return CompositeQuery("OR", self, operand)
-    
+
     def __and__(self, operand):
         if not isinstance(operand, Query):
             operand = SimpleQuery(operand)
         return CompositeQuery("AND", self, operand)
-    
+
     def __xor__(self, operand):
         if not isinstance(operand, Query):
             operand = SimpleQuery(operand)
@@ -51,21 +49,21 @@ class CompositeQuery(Query):
     """
     A representation of an composite query
     for the NCBI Entrez search service.
-    
+
     A composite query is a combination of two other queries,
     combined either with an 'AND', 'OR' or 'NOT' operator.
 
     Usually the user does not create instances of this class directly,
     but :class:`Query` instances are combined with
     ``|`` (OR), ``&`` (AND) or ``^`` (NOT).
-    
+
     Parameters
     ----------
     operator: str, {"AND", "OR", "NOT"}
         The combination operator.
     queries : iterable object of SimpleQuery
         The queries to be combined.
-    
+
     Examples
     --------
 
@@ -76,16 +74,16 @@ class CompositeQuery(Query):
     >>> print(query)
     ("Escherichia coli"[Organism]) AND (90:100[Sequence Length])
     """
-    
+
     def __init__(self, operator, query1, query2):
         super().__init__()
         self._op = operator
         self._q1 = query1
         self._q2 = query2
-    
+
     def __str__(self):
         return "({:}) {:} ({:})".format(str(self._q1), self._op, self._q2)
-        
+
 
 
 class SimpleQuery(Query):
@@ -96,7 +94,7 @@ class SimpleQuery(Query):
 
     A list of available search fields with description can be found
     `here <https://www.ncbi.nlm.nih.gov/books/NBK49540/>`_.
-    
+
     Parameters
     ----------
     term: str
@@ -108,10 +106,10 @@ class SimpleQuery(Query):
         `here <https://www.ncbi.nlm.nih.gov/books/NBK49540/>`_.
         By default the field is omitted and all fields are searched in
         for the term, implicitly.
-    
+
     Examples
     --------
-    
+
     >>> query = SimpleQuery("Escherichia coli")
     >>> print(query)
     "Escherichia coli"
@@ -152,7 +150,7 @@ class SimpleQuery(Query):
             term = f'"{term}"'
         self._term = term
         self._field = field
-    
+
     def __str__(self):
         string = self._term
         if self._field is not None:
@@ -164,9 +162,9 @@ def search(query, db_name, number=20):
     r"""
     Get all PDB IDs that meet the given query requirements,
     via the NCBI ESearch service.
-    
+
     This function requires an internet connection.
-    
+
     Parameters
     ----------
     query : Query
@@ -175,13 +173,13 @@ def search(query, db_name, number=20):
         E-utility or common database name.
     number : Query
         The maximum number of UIDs that are obtained.
-    
+
     Returns
     -------
     ids : list of str
         A list of strings containing all NCBI UIDs (accession number)
         that meet the query requirements.
-    
+
     Warnings
     --------
     Even if you give valid input to this function, in rare cases the
@@ -194,7 +192,7 @@ def search(query, db_name, number=20):
     -----
     A list of available search fields with description can be found
     `here <https://www.ncbi.nlm.nih.gov/books/NBK49540/>`_.
-    
+
     Examples
     --------
     >>> query = SimpleQuery("Escherichia coli", "Organism") & \
@@ -202,18 +200,24 @@ def search(query, db_name, number=20):
     >>> ids = search(query, "nuccore", number=5)
     >>> print(ids)
     ['...', '...', '...', '...', '...']
-    """ 
-    r = requests.get(
-        (_base_url + _search_url).format(
-            sanitize_database_name(db_name),
-            str(query),
-            str(number)
-        )
-    )
+    """
+    param_dict = {
+        "db": sanitize_database_name(db_name),
+        "term": str(query),
+        "retmax": str(number),
+    }
+    api_key = get_api_key()
+    if api_key is not None:
+        param_dict["api_key"] = api_key
+    r = requests.get(_search_url, params=param_dict)
     xml_response = r.text
     check_for_errors(xml_response)
-    root = ElementTree.fromstring(xml_response)
+    try:
+        root = ElementTree.fromstring(xml_response)
+    except ElementTree.ParseError:
+        if len(xml_response) > 100:
+            xml_response = xml_response[:100] + "..."
+        raise RequestError(f"Invalid server response: {xml_response}")
     xpath = ".//IdList/Id"
     uids = [element.text for element in root.findall(xpath)]
     return uids
-    

biotite/database/pubchem/query.py

@@ -84,12 +84,12 @@ class NameQuery(Query):
     --------
 
     >>> print(search(NameQuery("Alanine")))
-    [5950, 602, 71080]
+    [5950, ..., ..., ...]
     """
 
     def __init__(self, name):
         self._name = name
-    
+
     def get_input_url_path(self):
         return "compound/name"
 
@@ -107,7 +107,7 @@ class SmilesQuery(Query):
     ----------
     smiles : str
         The *SMILES* string.
-    
+
     Examples
     --------
 
@@ -117,7 +117,7 @@ class SmilesQuery(Query):
 
     def __init__(self, smiles):
         self._smiles = smiles
-    
+
     def get_input_url_path(self):
         return "compound/smiles"
 
@@ -134,7 +134,7 @@ class InchiQuery(Query):
     ----------
     inchi : str
         The *InChI* string.
-    
+
     Examples
     --------
 
@@ -144,7 +144,7 @@ class InchiQuery(Query):
 
     def __init__(self, inchi):
         self._inchi = inchi
-    
+
     def get_input_url_path(self):
         return "compound/inchi"
 
@@ -161,7 +161,7 @@ class InchiKeyQuery(Query):
     ----------
     inchi_key : str
         The *InChI* key.
-    
+
     Examples
     --------
 
@@ -171,7 +171,7 @@ class InchiKeyQuery(Query):
 
     def __init__(self, inchi_key):
         self._inchi_key = inchi_key
-    
+
     def get_input_url_path(self):
         return "compound/inchikey"
 
@@ -199,22 +199,22 @@ 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.
-    
+
     Examples
     --------
 
     >>> print(search(FormulaQuery("C4H10", number=5)))
-    [7843, 6360, 16213391, 71309065, 16213390]
+    [7843, ..., ..., ..., ...]
     >>> atom_array = residue("ALA")
     >>> print(search(FormulaQuery.from_atoms(atom_array, number=5)))
-    [5950, 5641, 1088, 239, 602]
+    [5950, ..., ..., ..., ...]
     """
 
     def __init__(self, formula, allow_other_elements=False, number=None):
         self._formula = formula
         self._allow_other_elements = allow_other_elements
         self._number = number
-    
+
     @staticmethod
     def from_atoms(atoms, allow_other_elements=False, number=None):
         """
@@ -247,7 +247,7 @@ class FormulaQuery(Query):
         for element in sorted_elements:
             formula += _format_element(element, element_counter[element])
         return FormulaQuery(formula, allow_other_elements, number)
-    
+
     def get_input_url_path(self):
         # The 'fastformula' service seems not to accept the formula
         # in the parameter section of the request
@@ -287,7 +287,7 @@ class StructureQuery(Query, metaclass=abc.ABCMeta):
     sdf : str, optional
         A query structure as SDF formatted string.
         Usually :meth:`from_atoms()` is used to create the SDF from an
-        :class:`AtomArray`. 
+        :class:`AtomArray`.
     cid : int, optional
         The query structure given as CID.
     number : int, optional
@@ -351,7 +351,7 @@ class StructureQuery(Query, metaclass=abc.ABCMeta):
             sdf = "\r\n".join(mol_file.lines) + "\r\n$$$$\r\n",
             **kwargs
         )
-    
+
     def get_input_url_path(self):
         input_string =  f"compound/{self.search_type()}/{self._query_key}"
         if self._query_key == "cid":
@@ -384,7 +384,7 @@ class StructureQuery(Query, metaclass=abc.ABCMeta):
             return {"sdf": self._query_val}
         else:
             return {}
-    
+
     @abc.abstractmethod
     def search_type(self):
         """
@@ -434,7 +434,7 @@ class SuperOrSubstructureQuery(StructureQuery, metaclass=abc.ABCMeta):
     sdf : str, optional
         A query structure as SDF formatted string.
         Usually :meth:`from_atoms()` is used to create the SDF from an
-        :class:`AtomArray`. 
+        :class:`AtomArray`.
     cid : int, optional
         The query structure given as CID.
     number : int, optional
@@ -463,7 +463,7 @@ class SuperOrSubstructureQuery(StructureQuery, metaclass=abc.ABCMeta):
     stereo : {'ignore', 'exact', 'relative', 'nonconflicting'}, optional
         How to handle stereo.
         (Default: 'ignore')
-    
+
     Notes
     -----
     Optional parameter descriptions are taken from the *PubChem* REST
@@ -488,7 +488,7 @@ class SuperOrSubstructureQuery(StructureQuery, metaclass=abc.ABCMeta):
                 self._options[option] = value
                 del kwargs[option]
         super().__init__(**kwargs)
-    
+
     def search_options(self):
         return self._options
 
@@ -514,7 +514,7 @@ class SuperstructureQuery(SuperOrSubstructureQuery):
     sdf : str, optional
         A query structure as SDF formatted string.
         Usually :meth:`from_atoms()` is used to create the SDF from an
-        :class:`AtomArray`. 
+        :class:`AtomArray`.
     cid : int, optional
         The query structure given as CID.
     number : int, optional
@@ -543,7 +543,7 @@ class SuperstructureQuery(SuperOrSubstructureQuery):
     stereo : {'ignore', 'exact', 'relative', 'nonconflicting'}, optional
         How to handle stereo.
         (Default: 'ignore')
-    
+
     Notes
     -----
     Optional parameter descriptions are taken from the *PubChem* REST
@@ -555,11 +555,11 @@ class SuperstructureQuery(SuperOrSubstructureQuery):
 
     >>> # CID of alanine
     >>> print(search(SuperstructureQuery(cid=5950, number=5)))
-    [1032, 887, 712, 702, 284]
+    [1032, ..., ..., ..., ...]
     >>> # AtomArray of alanine
     >>> atom_array = residue("ALA")
     >>> print(search(SuperstructureQuery.from_atoms(atom_array, number=5)))
-    [1032, 887, 712, 702, 284]
+    [1032, ..., ..., ..., ...]
     """
 
     def search_type(self):
@@ -587,7 +587,7 @@ class SubstructureQuery(SuperOrSubstructureQuery):
     sdf : str, optional
         A query structure as SDF formatted string.
         Usually :meth:`from_atoms()` is used to create the SDF from an
-        :class:`AtomArray`. 
+        :class:`AtomArray`.
     cid : int, optional
         The query structure given as CID.
     number : int, optional
@@ -616,7 +616,7 @@ class SubstructureQuery(SuperOrSubstructureQuery):
     stereo : {'ignore', 'exact', 'relative', 'nonconflicting'}, optional
         How to handle stereo.
         (Default: 'ignore')
-    
+
     Notes
     -----
     Optional parameter descriptions are taken from the *PubChem* REST
@@ -628,11 +628,11 @@ class SubstructureQuery(SuperOrSubstructureQuery):
 
     >>> # CID of alanine
     >>> print(search(SubstructureQuery(cid=5950, number=5)))
-    [5950, 602, 71080, 3081884, 65370]
+    [5950, ..., ..., ..., ...]
     >>> # AtomArray of alanine
     >>> atom_array = residue("ALA")
     >>> print(search(SubstructureQuery.from_atoms(atom_array, number=5)))
-    [5950, 602, 71080, 3081884, 65370]
+    [5950, ..., ..., ..., ...]
     """
 
     def search_type(self):
@@ -666,14 +666,14 @@ class SimilarityQuery(StructureQuery):
     sdf : str, optional
         A query structure as SDF formatted string.
         Usually :meth:`from_atoms()` is used to create the SDF from an
-        :class:`AtomArray`. 
+        :class:`AtomArray`.
     cid : int, optional
         The query structure given as CID.
     number : int, optional
         The maximum number of matches that this query may return.
         By default, the *PubChem* default value is used, which can
         be considered unlimited.
-    
+
     Notes
     -----
     The conformation based similarity measure uses *shape-Tanimoto* and
@@ -681,7 +681,7 @@ class SimilarityQuery(StructureQuery):
 
     References
     ----------
-    
+
     .. footbibliography::
 
     Examples
@@ -689,22 +689,22 @@ class SimilarityQuery(StructureQuery):
 
     >>> # CID of alanine
     >>> print(search(SimilarityQuery(cid=5950, threshold=1.0, number=5)))
-    [5950, 602, 71080, 11815285, 10749140]
+    [5950, ..., ..., ..., ...]
     >>> # AtomArray of alanine
     >>> atom_array = residue("ALA")
     >>> print(search(SimilarityQuery.from_atoms(atom_array, threshold=1.0, number=5)))
-    [5950, 602, 71080, 11815285, 10749140]
+    [5950, ..., ..., ..., ...]
     """
 
     def __init__(self, threshold=0.9, conformation_based=False, **kwargs):
         self._threshold = threshold
         self._conformation_based = conformation_based
         super().__init__(**kwargs)
-    
+
     def search_type(self):
         dim = "3d" if self._conformation_based else "2d"
         return f"fastsimilarity_{dim}"
-    
+
     def search_options(self):
         return {"threshold" : int(round(self._threshold * 100))}
 
@@ -730,14 +730,14 @@ class IdentityQuery(StructureQuery):
     sdf : str, optional
         A query structure as SDF formatted string.
         Usually :meth:`from_atoms()` is used to create the SDF from an
-        :class:`AtomArray`. 
+        :class:`AtomArray`.
     cid : int, optional
         The query structure given as CID.
     number : int, optional
         The maximum number of matches that this query may return.
         By default, the *PubChem* default value is used, which can
         be considered unlimited.
-    
+
     Examples
     --------
 
@@ -753,10 +753,10 @@ class IdentityQuery(StructureQuery):
     def __init__(self, identity_type="same_stereo_isotope", **kwargs):
         self._identity_type = identity_type
         super().__init__(**kwargs)
-    
+
     def search_type(self):
         return "fastidentity"
-    
+
     def get_params(self):
         # Use 'get_params()' instead of 'search_options()', since the
         # parameter 'identity_type' in the REST API is *snake case*
@@ -764,7 +764,7 @@ class IdentityQuery(StructureQuery):
         params = super().get_params()
         params["identity_type"] = self._identity_type
         return params
-    
+
 
 
 
@@ -772,9 +772,9 @@ def search(query, throttle_threshold=0.5, return_throttle_status=False):
     """
     Get all CIDs that meet the given query requirements,
     via the PubChem REST API.
-    
+
     This function requires an internet connection.
-    
+
     Parameters
     ----------
     query : Query
@@ -787,7 +787,7 @@ def search(query, throttle_threshold=0.5, return_throttle_status=False):
         If ``None`` is given, the execution is never halted.
     return_throttle_status : float, optional
         If set to true, the :class:`ThrottleStatus` is also returned.
-    
+
     Returns
     -------
     ids : list of int
@@ -796,12 +796,12 @@ def search(query, throttle_threshold=0.5, return_throttle_status=False):
         The :class:`ThrottleStatus` obtained from the server response.
         This can be used for custom request throttling, for example.
         Only returned, if `return_throttle_status` is set to true.
-    
+
     Examples
     --------
 
     >>> print(search(NameQuery("Alanine")))
-    [5950, 602, 71080]
+    [5950, ..., ..., ...]
     """
     # Use POST to be compatible with the larger payloads
     # of structure searches

biotite/database/rcsb/download.py

@@ -16,24 +16,25 @@ from ..error import RequestError
 
 _standard_url = "https://files.rcsb.org/download/"
 _mmtf_url = "https://mmtf.rcsb.org/v1.0/full/"
+_bcif_url = "https://models.rcsb.org/"
 _fasta_url = "https://www.rcsb.org/fasta/entry/"
 
-_binary_formats = ["mmtf"]
+_binary_formats = ["mmtf", "bcif"]
 
 
 def fetch(pdb_ids, format, target_path=None, overwrite=False, verbose=False):
     """
     Download structure files (or sequence files) from the RCSB PDB in
     various formats.
-    
+
     This function requires an internet connection.
-    
+
     Parameters
     ----------
     pdb_ids : str or iterable object of str
         A single PDB ID or a list of PDB IDs of the structure(s)
         to be downloaded.
-    format : {'pdb', 'pdbx', 'cif', 'mmcif', 'mmtf', 'fasta'}
+    format : {'pdb', 'pdbx', 'cif', 'mmcif', 'bcif', 'mmtf', 'fasta'}
         The format of the files to be downloaded.
         ``'pdbx'``, ``'cif'`` and ``'mmcif'`` are synonyms for
         the same format.
@@ -48,7 +49,7 @@ def fetch(pdb_ids, format, target_path=None, overwrite=False, verbose=False):
         the file is empty.
     verbose: bool, optional
         If set to true, the function will output the download progress.
-    
+
     Returns
     -------
     files : str or StringIO or BytesIO or list of (str or StringIO or BytesIO)
@@ -58,7 +59,7 @@ def fetch(pdb_ids, format, target_path=None, overwrite=False, verbose=False):
         object) was given, a list of strings is returned.
         If no `target_path` was given, the file contents are stored in
         either :class:`StringIO` or :class:`BytesIO` objects.
-    
+
     Warnings
     --------
     Even if you give valid input to this function, in rare cases the
@@ -66,10 +67,10 @@ def fetch(pdb_ids, format, target_path=None, overwrite=False, verbose=False):
     In these cases the request should be retried.
     When the issue occurs repeatedly, the error is probably in your
     input.
-    
+
     Examples
     --------
-    
+
     >>> import os.path
     >>> file = fetch("1l2y", "cif", path_to_directory)
     >>> print(os.path.basename(file))
@@ -88,21 +89,21 @@ def fetch(pdb_ids, format, target_path=None, overwrite=False, verbose=False):
     # Create the target folder, if not existing
     if target_path is not None and not os.path.isdir(target_path):
         os.makedirs(target_path)
-    
+
     files = []
     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")
-        
+
         # Fetch file from database
         if target_path is not None:
             file = join(target_path, id + "." + format)
         else:
             # 'file = None' -> store content in a file-like object
             file = None
-        
+
         if file is None \
            or not isfile(file) \
            or getsize(file) == 0 \
@@ -115,6 +116,10 @@ def fetch(pdb_ids, format, target_path=None, overwrite=False, verbose=False):
                     r = requests.get(_standard_url + id + ".cif")
                     content = r.text
                     _assert_valid_file(content, id)
+                elif format in ["bcif"]:
+                    r = requests.get(_bcif_url + id + ".bcif")
+                    content = r.content
+                    _assert_valid_file(r.text, id)
                 elif format == "mmtf":
                     r = requests.get(_mmtf_url + id)
                     content = r.content
@@ -125,7 +130,7 @@ def fetch(pdb_ids, format, target_path=None, overwrite=False, verbose=False):
                     _assert_valid_file(content, id)
                 else:
                     raise ValueError(f"Format '{format}' is not supported")
-                
+
                 if file is None:
                     if format in _binary_formats:
                         file = io.BytesIO(content)
@@ -135,7 +140,7 @@ def fetch(pdb_ids, format, target_path=None, overwrite=False, verbose=False):
                     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")
@@ -153,7 +158,7 @@ def _assert_valid_file(response_text, pdb_id):
     """
     # Structure file and FASTA file retrieval
     # have different error messages
-    if any(err_msg in response_text for err_msg in [
+    if len(response_text) == 0 or any(err_msg in response_text for err_msg in [
         "404 Not Found",
         "<title>RCSB Protein Data Bank Error Page</title>",
         "No fasta files were found.",