biotite 1.1.0__cp313-cp313-macosx_10_13_x86_64.whl

biotite/database/uniprot/__init__.py

@@ -0,0 +1,13 @@
+# 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.
+
+"""
+A subpackage for downloading files from the UniProt.
+"""
+
+__name__ = "biotite.database.uniprot"
+__author__ = "Maximilian Greil"
+
+from .download import *
+from .query import *

biotite/database/uniprot/check.py

@@ -0,0 +1,40 @@
+# 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.uniprot"
+__author__ = "Maximilian Greil"
+__all__ = ["assert_valid_response"]
+
+from biotite.database.error import RequestError
+
+
+# Taken from https://www.uniprot.org/help/api_retrieve_entries
+def assert_valid_response(response):
+    """
+    Checks whether the response is valid.
+
+    Parameters
+    ----------
+    response_status_code: int
+        Status code of request.get.
+    """
+    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

@@ -0,0 +1,129 @@
+# 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.uniprot"
+__author__ = "Maximilian Greil"
+__all__ = ["fetch"]
+
+import io
+import os
+from os.path import getsize, isdir, isfile, join
+import requests
+from biotite.database.uniprot.check import assert_valid_response
+
+_fetch_url = "https://rest.uniprot.org/"
+
+
+def _get_database_name(id):
+    """
+    Get the correct UniProt database from the ID of the file to be downloaded.
+
+    Parameters
+    ----------
+    id: str
+        ID of the file to be downloaded.
+
+    Returns
+    -------
+    name : str
+        E-utility UniProt database name.
+    """
+    if id[:3] == "UPI":
+        return "uniparc"
+    elif id[:6] == "UniRef":
+        return "uniref"
+    return "uniprotkb"
+
+
+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
+    ----------
+    ids : str or iterable object of str
+        A single ID or a list of IDs of the file(s)
+        to be downloaded.
+    format : {'fasta', 'gff', 'txt', 'xml', 'rdf', 'tab'}
+        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. (Default: False)
+    verbose: bool, optional
+        If true, the function will output the download progress.
+        (Default: False)
+
+    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
+    --------
+
+    >>> import os.path
+    >>> file = fetch("P12345", "fasta", path_to_directory)
+    >>> print(os.path.basename(file))
+    P12345.fasta
+    >>> files = fetch(["P12345", "Q8K9I1"], "fasta", path_to_directory)
+    >>> print([os.path.basename(file) for file in files])
+    ['P12345.fasta', 'Q8K9I1.fasta']
+    """
+    # 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
+    # Create the target folder, if not existing
+    if target_path is not None and not isdir(target_path):
+        os.makedirs(target_path)
+    files = []
+    for i, id in enumerate(ids):
+        db_name = _get_database_name(id)
+        # 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 = 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 or overwrite:
+            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)
+            else:
+                raise ValueError(f"Format '{format}' is not supported")
+            if file is None:
+                file = io.StringIO(content)
+            else:
+                with open(file, "w+") as f:
+                    f.write(content)
+        files.append(file)
+    if verbose:
+        print("\nDone")
+    # If input was a single ID, return only a single path
+    if single_element:
+        return files[0]
+    else:
+        return files

biotite/database/uniprot/query.py

@@ -0,0 +1,293 @@
+# 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.uniprot"
+__author__ = "Maximilian Greil"
+__all__ = ["Query", "SimpleQuery", "CompositeQuery", "search"]
+
+import abc
+import requests
+from biotite.database.uniprot.check import assert_valid_response
+
+_base_url = "https://rest.uniprot.org/uniprotkb/search/"
+
+
+class Query(metaclass=abc.ABCMeta):
+    """
+    Base class for a wrapper around a search term
+    for the UniProt search service.
+    """
+
+    def __init__(self):
+        pass
+
+    @abc.abstractmethod
+    def __str__(self):
+        pass
+
+    def __or__(self, operand):
+        return CompositeQuery("OR", self, operand)
+
+    def __and__(self, operand):
+        return CompositeQuery("AND", self, operand)
+
+    def __xor__(self, operand):
+        return CompositeQuery("NOT", self, operand)
+
+
+class CompositeQuery(Query):
+    """
+    A representation of an composite query
+    for the UniProt 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.
+    """
+
+    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, str(self._q2))
+
+
+def _check_brackets(term):
+    """
+    Check if term contains correct number of round brackets and square brackets.
+
+    Parameters
+    ----------
+    term: str
+        The search term.
+
+    Returns
+    -------
+    bool
+        True if term contains correct number of round brackets and square brackets, otherwise False.
+    """
+    square_count = 0
+    round_count = 0
+    for i in term:
+        if i == "[":
+            square_count += 1
+        elif i == "]":
+            square_count -= 1
+        if i == "(":
+            round_count += 1
+        elif i == ")":
+            round_count -= 1
+        if square_count < 0:
+            return False
+        if round_count < 0:
+            return False
+    return square_count == 0 and round_count == 0
+
+
+class SimpleQuery(Query):
+    """
+    A simple query for the UniProt search service without
+    combination via 'AND', 'OR' or 'NOT'. A query consists of a search
+    term and an optional field.
+
+    A list of available search fields with description can be found
+    `here <https://www.uniprot.org/help/query-fields>`_.
+
+    Parameters
+    ----------
+    field : str
+       The field to search the term in.
+       The list of possible fields and the required search term
+       formatting can be found
+       `here <https://www.uniprot.org/help/query-fields>`_.
+    term: str
+       The search term.
+    """
+
+    # Field identifiers are taken from
+    # https://www.uniprot.org/help/query-fields
+    _fields = [
+        "accession",
+        "active",
+        "ft_init_met",
+        "ft_signal",
+        "ft_transit",
+        "ft_propep",
+        "ft_chain",
+        "ft_peptide",
+        "ft_topo_dom",
+        "ft_transmem",
+        "ft_intramem",
+        "ft_domain",
+        "ft_repeat",
+        "ft_zn_fing",
+        "ft_dna_bind",
+        "ft_region",
+        "ft_coiled",
+        "ft_motif",
+        "ft_compbias",
+        "ft_act_site",
+        "ft_binding",
+        "ft_site",
+        "ft_non_std",
+        "ft_mod_res",
+        "ft_lipid",
+        "ft_carbohyd",
+        "ft_disulfid",
+        "ft_crosslnk",
+        "ft_var_seq",
+        "ft_variant",
+        "ft_mutagen",
+        "ft_unsure",
+        "ft_conflict",
+        "ft_non_cons",
+        "ft_non_ter",
+        "ft_helix",
+        "ft_turn",
+        "ft_strand",
+        "lit_author",
+        "protein_name",
+        "chebi",
+        "citation",
+        "uniref_cluster_90",
+        "xrefcount_pdb",
+        "date_created",
+        "database",
+        "xref",
+        "ec",
+        "cc_function",
+        "cc_catalytic_activity",
+        "cc_cofactor",
+        "cc_activity_regulation",
+        "cc_biophysicochemical_properties",
+        "cc_subunit",
+        "cc_pathway",
+        "cc_scl_term",
+        "cc_tissue_specificity",
+        "cc_developmental_stage",
+        "cc_induction",
+        "cc_domain",
+        "cc_ptm cc_rna_editing",
+        "cc_mass_spectrometry",
+        "cc_polymorphism",
+        "cc_disease",
+        "cc_disruption_phenotype",
+        "cc_allergen",
+        "cc_toxic_dose",
+        "cc_biotechnology",
+        "cc_pharmaceutical",
+        "cc_miscellaneous",
+        "cc_similarity",
+        "cc_caution",
+        "cc_sequence_caution",
+        "existence",
+        "family",
+        "fragment",
+        "gene",
+        "gene_exact",
+        "go",
+        "virus_host_name",
+        "virus_host_id",
+        "accession_id",
+        "inchikey",
+        "protein_name",
+        "interactor",
+        "keyword",
+        "length",
+        "lineage",
+        "mass",
+        "cc_mass_spectrometry",
+        "date_modified",
+        "protein_name",
+        "organelle",
+        "organism_name",
+        "organism_id",
+        "plasmid",
+        "proteome",
+        "proteomecomponent",
+        "sec_acc",
+        "reviewed",
+        "scope",
+        "sequence",
+        "date_sequence_modified",
+        "strain",
+        "taxonomy_name",
+        "taxonomy_id",
+        "tissue",
+        "cc_webresource",
+    ]
+
+    def __init__(self, field, term):
+        super().__init__()
+        if field not in SimpleQuery._fields:
+            raise ValueError(f"Unknown field identifier '{field}'")
+        if not _check_brackets(term):
+            raise ValueError(
+                "Query term contains illegal number of round brackets ( ) and/or square brackets [ ]"
+            )
+        for invalid_string in ['"', "AND", "OR", "NOT", "\t", "\n"]:
+            if invalid_string in term:
+                raise ValueError(f"Query contains illegal term {invalid_string}")
+        if " " in term:
+            term = f'"{term}"'
+        self._field = field
+        self._term = term
+
+    def __str__(self):
+        return f"{self._field}:{self._term}"
+
+
+def search(query, number=500):
+    """
+    Get all UniProt IDs that meet the given query requirements,
+    via the UniProt search service.
+
+    This function requires an internet connection.
+
+    Parameters
+    ----------
+    query : Query
+        The search query.
+    number : int
+        The maximum number of IDs that are obtained.
+        (Default: 500)
+
+    Returns
+    -------
+    ids : list of str
+        A list of strings containing all UniProt IDs
+        that meet the query requirements.
+
+    Notes
+    -----
+    A list of available search fields with description can be found
+    `here <https://www.uniprot.org/help/query-fields>`_.
+
+    Examples
+    --------
+    >>> query = SimpleQuery("accession", "P12345") & \
+                SimpleQuery("reviewed", "true")
+    >>> ids = search(query)
+    >>> print(sorted(ids))
+    ['P12345']
+    """
+
+    params = {"query": str(query), "format": "list", "size": str(number)}
+    r = requests.get(_base_url, params=params)
+    content = r.text
+    assert_valid_response(r)
+    return content.split("\n")[:-1]

biotite/file.py

@@ -0,0 +1,232 @@
+# 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"
+__author__ = "Patrick Kunzmann"
+__all__ = [
+    "File",
+    "TextFile",
+    "InvalidFileError",
+    "SerializationError",
+    "DeserializationError",
+]
+
+import abc
+import copy
+import io
+from os import PathLike
+from biotite.copyable import Copyable
+
+
+class File(Copyable, metaclass=abc.ABCMeta):
+    """
+    Base class for all file classes.
+    The constructor creates an empty file, that can be filled with data
+    using the class specific setter methods.
+    Conversely, the class method :func:`read()` reads a file from disk
+    (or a file-like object from other sources).
+    In order to write the instance content into a file the
+    :func:`write()` method is used.
+    """
+
+    @classmethod
+    @abc.abstractmethod
+    def read(cls, file):
+        """
+        Parse a file (or file-like object).
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be read.
+            Alternatively a file path can be supplied.
+
+        Returns
+        -------
+        file_object : File
+            An instance from the respective :class:`File` subclass
+            representing the parsed file.
+        """
+        pass
+
+    @abc.abstractmethod
+    def write(self, file):
+        """
+        Write the contents of this :class:`File` object into a file.
+
+        Parameters
+        ----------
+        file_name : file-like object or str
+            The file to be written to.
+            Alternatively a file path can be supplied.
+        """
+        pass
+
+
+class TextFile(File, metaclass=abc.ABCMeta):
+    """
+    Base class for all line based text files.
+    When reading a file, the text content is saved as list of strings,
+    one for each line.
+    When writing a file, this list is written into the file.
+
+    Attributes
+    ----------
+    lines : list
+        List of string representing the lines in the text file.
+        PROTECTED: Do not modify from outside.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.lines = []
+
+    @classmethod
+    def read(cls, file, *args, **kwargs):
+        # File name
+        if is_open_compatible(file):
+            with open(file, "r") as f:
+                lines = f.read().splitlines()
+        # File object
+        else:
+            if not is_text(file):
+                raise TypeError("A file opened in 'text' mode is required")
+            lines = file.read().splitlines()
+        file_object = cls(*args, **kwargs)
+        file_object.lines = lines
+        return file_object
+
+    @staticmethod
+    def read_iter(file):
+        """
+        Create an iterator over each line of the given text file.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be read.
+            Alternatively a file path can be supplied.
+
+        Yields
+        ------
+        line : str
+            The current line in the file.
+        """
+        # File name
+        if is_open_compatible(file):
+            with open(file, "r") as f:
+                yield from f
+        # File object
+        else:
+            if not is_text(file):
+                raise TypeError("A file opened in 'text' mode is required")
+            yield from file
+
+    def write(self, file):
+        """
+        Write the contents of this object into a file
+        (or file-like object).
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be written to.
+            Alternatively a file path can be supplied.
+        """
+        if is_open_compatible(file):
+            with open(file, "w") as f:
+                f.write("\n".join(self.lines) + "\n")
+        else:
+            if not is_text(file):
+                raise TypeError("A file opened in 'text' mode is required")
+            file.write("\n".join(self.lines) + "\n")
+
+    @staticmethod
+    def write_iter(file, lines):
+        """
+        Iterate over the given `lines` of text and write each line into
+        the specified `file`.
+
+        In contrast to :meth:`write()`, each line of text is not stored
+        in an intermediate :class:`TextFile`, but is directly written
+        to the file.
+        Hence, this static method may save a large amount of memory if
+        a large file should be written, especially if the `lines`
+        are provided as generator.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be written to.
+            Alternatively a file path can be supplied.
+        lines : generator or array-like of str
+            The lines of text to be written.
+            Must not include line break characters.
+        """
+        if is_open_compatible(file):
+            with open(file, "w") as f:
+                for line in lines:
+                    f.write(line + "\n")
+        else:
+            if not is_text(file):
+                raise TypeError("A file opened in 'text' mode is required")
+            for line in lines:
+                file.write(line + "\n")
+
+    def __copy_fill__(self, clone):
+        super().__copy_fill__(clone)
+        clone.lines = copy.copy(self.lines)
+
+    def __str__(self):
+        return "\n".join(self.lines)
+
+
+class InvalidFileError(Exception):
+    """
+    Indicates that the file is not suitable for the requested action,
+    either because the file does not contain the required data or
+    because the file is malformed.
+    """
+
+    pass
+
+
+class SerializationError(Exception):
+    pass
+
+
+class DeserializationError(Exception):
+    pass
+
+
+def wrap_string(text, width):
+    """
+    A much simpler and hence much more efficient version of
+    `textwrap.wrap()`.
+
+    This function simply wraps the given `text` after `width`
+    characters, ignoring sentences, whitespaces, etc.
+    """
+    lines = []
+    for i in range(0, len(text), width):
+        lines.append(text[i : i + width])
+    return lines
+
+
+def is_binary(file):
+    if isinstance(file, io.BufferedIOBase):
+        return True
+    # for file wrappers, e.g. 'TemporaryFile'
+    return hasattr(file, "file") and isinstance(file.file, io.BufferedIOBase)
+
+
+def is_text(file):
+    if isinstance(file, io.TextIOBase):
+        return True
+    # for file wrappers, e.g. 'TemporaryFile'
+    return hasattr(file, "file") and isinstance(file.file, io.TextIOBase)
+
+
+def is_open_compatible(file):
+    return isinstance(file, (str, bytes, PathLike))