kegg-pull 3.2.1__py3-none-any.whl

kegg_pull/__init__.py

@@ -0,0 +1,16 @@
+"""
+This package has the following modules:
+
+``pull``
+
+``entry_ids``
+
+``map``
+
+``pathway_organizer``
+
+``rest``
+
+``kegg_url``
+"""
+__version__ = '3.1.0'

kegg_pull/__main__.py

@@ -0,0 +1,53 @@
+"""
+Usage:
+    kegg_pull -h | --help           Show this help message.
+    kegg_pull -v | --version        Displays the package version.
+    kegg_pull --full-help           Show the help message of all sub commands.
+    kegg_pull pull ...              Pull, separate, and store an arbitrary number of KEGG entries to the local file system.
+    kegg_pull entry-ids ...         Obtain a list of KEGG entry IDs.
+    kegg_pull map ...               Obtain a mapping of entry IDs (KEGG or outside databases) to the IDs of related entries.
+    kegg_pull pathway-organizer ... Creates a flattened version of a pathways Brite hierarchy.
+    kegg_pull rest ...              Executes one of the KEGG REST API operations.
+"""
+import sys
+from . import __version__
+from . import pull_cli as p_cli
+from . import entry_ids_cli as ei_cli
+from . import map_cli as map_cli
+from . import pathway_organizer_cli as po_cli
+from . import rest_cli as r_cli
+
+
+def main() -> None:
+    first_arg: str = sys.argv[1] if len(sys.argv) > 1 else None
+    if first_arg == 'pull':
+        p_cli.main()
+    elif first_arg == 'entry-ids':
+        ei_cli.main()
+    elif first_arg == 'map':
+        map_cli.main()
+    elif first_arg == 'pathway-organizer':
+        po_cli.main()
+    elif first_arg == 'rest':
+        r_cli.main()
+    elif first_arg == '--full-help':
+        separator = '-'*80
+        print(__doc__)
+        print(separator)
+        print(p_cli.__doc__)
+        print(separator)
+        print(ei_cli.__doc__)
+        print(separator)
+        print(map_cli.__doc__)
+        print(separator)
+        print(po_cli.__doc__)
+        print(separator)
+        print(r_cli.__doc__)
+    elif first_arg == '--version' or first_arg == '-v':
+        print(__version__)
+    else:
+        print(__doc__)
+
+
+if __name__ == '__main__':  # pragma: no cover
+    main()  # pragma: no cover

kegg_pull/_utils.py

@@ -0,0 +1,129 @@
+import logging as log
+import typing as t
+import zipfile as zf
+import os
+import sys
+import json
+import jsonschema as js
+import inspect as ins
+
+
+def get_molecular_attribute_args(args: dict) -> tuple[str | None, float | tuple[float, float] | None, int | tuple[int, int] | None]:
+    formula: str | None = args['--formula']
+    exact_mass: list[str] | None = args['--em']
+    molecular_weight: list[str] | None = args['--mw']
+    # exact_mass and molecular_weight will be [] (empty list) if not specified in the commandline args
+    if exact_mass:
+        exact_mass: float | tuple[float, float] = _get_range_values(range_values=exact_mass, value_type=float)
+    else:
+        exact_mass = None
+    if molecular_weight:
+        molecular_weight: int | tuple[int, int] = _get_range_values(range_values=molecular_weight, value_type=int)
+    else:
+        molecular_weight = None
+    return formula, exact_mass, molecular_weight
+
+
+def _get_range_values(
+        range_values: list[str], value_type: type[int | float]) -> int | float | tuple[int, int] | tuple[float, float]:
+    if len(range_values) == 1:
+        [val] = range_values
+        return value_type(val)
+    elif len(range_values) == 2:
+        [min_val, max_val] = range_values
+        return value_type(min_val), value_type(max_val)
+    else:
+        raise ValueError(
+            f'Range can only be specified by two values but {len(range_values)} values were provided: '
+            f'{", ".join(range_value for range_value in range_values)}')
+
+
+def load_json_file(file_path: str, json_schema: dict, validation_error_message: str) -> dict:
+    if '.zip:' in file_path:
+        [file_location, file_name] = file_path.split('.zip:')
+        file_location = file_location + '.zip'
+        with zf.ZipFile(file_location, 'r') as zip_file:
+            json_object: bytes = zip_file.read(file_name)
+            json_object: dict = json.loads(s=json_object)
+    else:
+        with open(file_path, 'r') as file:
+            json_object: dict = json.load(file)
+    validate_json_object(json_object=json_object, json_schema=json_schema, validation_error_message=validation_error_message)
+    return json_object
+
+
+def validate_json_object(json_object: dict, json_schema: dict, validation_error_message: str) -> None:
+    try:
+        js.validate(json_object, json_schema)
+    except js.exceptions.ValidationError as e:
+        log.error(validation_error_message)
+        raise e
+
+
+def parse_input_sequence(input_source: str) -> list[str]:
+    if input_source == '-':
+        # Read from standard input
+        inputs: str = sys.stdin.read()
+        inputs: list = inputs.strip().split('\n')
+    else:
+        # Split a comma separated list
+        inputs: list = input_source.split(',')
+    inputs: list = [input_string.strip() for input_string in inputs if input_string.strip() != '']
+    # If the inputs end up being an empty list
+    if not inputs:
+        input_source = 'standard input' if input_source == '-' else f'comma separated list: "{input_source}"'
+        raise ValueError(f'Empty list provided from {input_source}')
+    return inputs
+
+
+def print_or_save(output_target: str, output_content: str | bytes) -> None:
+    if output_target is None:
+        if type(output_content) is bytes:
+            log.warning('Printing binary output...')
+        print(output_content)
+    else:
+        save_output(output_target=output_target, output_content=output_content)
+
+
+def save_output(output_target: str, output_content: str | bytes) -> None:
+    if '.zip:' in output_target:
+        [file_location, file_name] = output_target.split('.zip:')
+        file_location: str = file_location + '.zip'
+    else:
+        file_location, file_name = os.path.split(output_target)
+        file_location = '.' if file_location == '' else file_location
+    save_file(file_location=file_location, file_content=output_content, file_name=file_name)
+
+
+def save_file(file_location: str, file_content: str | bytes, file_name: str) -> None:
+    if os.name == 'nt':  # pragma: no cover
+        # If the OS is Windows, replace colons with underscores (Windows does not support colons in file names).
+        file_name = file_name.replace(':', '_')  # pragma: no cover
+    if file_location.endswith('.zip'):
+        with zf.ZipFile(file_location, 'a') as zip_file:
+            zip_file.writestr(file_name, file_content)
+    else:
+        if not os.path.isdir(file_location):
+            os.makedirs(file_location)
+        file_path = os.path.join(file_location, file_name)
+        save_type = 'wb' if type(file_content) is bytes else 'w'
+        encoding: str | None = None if type(file_content) is bytes else 'utf-8'
+        with open(file_path, save_type, encoding=encoding) as file:
+            file.write(file_content)
+
+
+class NonInstantiable:
+    """Base classes of this class are only instantiable in the same module that they are defined in."""
+    @classmethod
+    def __init__(cls) -> None:
+        caller_module_path = ins.stack()[2].filename
+        class_module_path = ins.getfile(cls)
+        # Ensure the python module of the caller matches that of the class
+        # This ensures the class is only instantiated in the same module that it's defined in
+        if caller_module_path != class_module_path:
+            raise RuntimeError(f'The class "{cls.__name__}" cannot be instantiated outside of its module.')
+
+
+class staticproperty(staticmethod):
+    def __get__(self, *_) -> t.Any:
+        return self.__func__()

kegg_pull/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '3.2.1'
+__version_tuple__ = version_tuple = (3, 2, 1)
+
+__commit_id__ = commit_id = None

kegg_pull/entry_ids.py

@@ -0,0 +1,89 @@
+"""
+Pulling Lists of KEGG Entry IDs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+|Functionality| for pulling lists of KEGG entry IDs from the KEGG REST API.
+"""
+from . import rest as r
+from . import kegg_url as ku
+
+
+def from_database(database: str, kegg_rest: r.KEGGrest | None = None) -> list[str]:
+    """ Pulls the KEGG entry IDs of a given database.
+
+    :param database: The KEGG database to pull the entry IDs from. If equal to "brite", the "br:" prefix is prepended to each entry ID such that they succeed if used in downstream use of the KEGG "get" operation (e.g. for the "pull" API module or CLI subcommand).
+    :param kegg_rest: The KEGGrest object to request the entry IDs. If None, one is created with the default parameters.
+    :return: The list of resulting entry IDs.
+    :raises RuntimeError: Raised if the request to the KEGG REST API fails or times out.
+    """
+    entry_ids = _process_response(KEGGurl=ku.ListKEGGurl, kegg_rest=kegg_rest, database=database)
+    if database == 'brite':
+        entry_ids = [f'br:{entry_id}' for entry_id in entry_ids if not entry_id.startswith('br:')]
+    return entry_ids
+
+
+def _process_response(KEGGurl: type[ku.AbstractKEGGurl], kegg_rest: r.KEGGrest | None, **kwargs) -> list[str]:
+    """ Extracts the entry IDs from a KEGG response if successful, else raises an exception. The KEGG response arrives from making
+    an entry IDs related request with a KEGGrest object.
+
+    :param KEGGurl: The URL class for the request.
+    :param kegg_rest: The KEGGrest object to make the request with. If None, one is created with the default parameters.
+    :param kwargs: The arguments to pass into the KEGGrest method.
+    :return: The list of KEGG entry IDs.
+    :raises RuntimeError: Raised if the KEGG response indicates a failure or time out.
+    """
+    kegg_response: r.KEGGresponse = r.request_and_check_error(kegg_rest=kegg_rest, KEGGurl=KEGGurl, **kwargs)
+    return _parse_entry_ids_string(entry_ids_string=kegg_response.text_body)
+
+
+def _parse_entry_ids_string(entry_ids_string: str) -> list[str]:
+    """ Parses the entry IDs contained in a string.
+
+    :param entry_ids_string: The string containing the entry IDs.
+    :return: The list of parsed entry IDs.
+    """
+    entry_ids = entry_ids_string.strip().split('\n')
+    return [entry_id.split('\t')[0].strip() for entry_id in entry_ids if entry_id.strip() != '']
+
+
+def from_file(file_path: str) -> list[str]:
+    """ Loads KEGG entry IDs that are listed in a file with one entry ID on each line.
+
+    :param file_path: The path to the file containing the entry IDs.
+    :return: The list of entry IDs.
+    :raises ValueError: Raised if the file is empty.
+    """
+    with open(file_path, 'r') as file:
+        entry_ids = file.read()
+        if entry_ids == '':
+            raise ValueError(f'Attempted to load entry IDs from {file_path}. But the file is empty')
+        return _parse_entry_ids_string(entry_ids_string=entry_ids)
+
+
+def from_keywords(database: str, keywords: list[str], kegg_rest: r.KEGGrest | None = None) -> list[str]:
+    """ Pulls entry IDs from a KEGG database based on keywords searched in the entries.
+
+    :param database: The name of the database to pull entry IDs from.
+    :param keywords: The keywords to search entries in the database with.
+    :param kegg_rest: The KEGGrest object to request the entry IDs. If None, one is created with the default parameters.
+    :return: The list of entry IDs.
+    :raises RuntimeError: Raised if the request to the KEGG REST API fails or times out.
+    """
+    return _process_response(KEGGurl=ku.KeywordsFindKEGGurl, kegg_rest=kegg_rest, database=database, keywords=keywords)
+
+
+def from_molecular_attribute(
+        database: str, formula: str | None = None, exact_mass: float | tuple[float, float] | None = None,
+        molecular_weight: int | tuple[int, int] | None = None, kegg_rest: r.KEGGrest | None = None) -> list[str]:
+    """ Pulls entry IDs from a KEGG database containing chemical entries based on one (and only one) of three molecular attributes of the entries.
+
+    :param database: The name of the database containing chemical entries.
+    :param formula: The chemical formula to search for.
+    :param exact_mass: The exact mass of the compound to search for (a single value or a range).
+    :param molecular_weight: The molecular weight of the compound to search for (a single value or a range).
+    :param kegg_rest: The KEGGrest object to request the entry IDs. If None, one is created with the default parameters.
+    :return: The list of entry IDs.
+    :raises RuntimeError: Raised if the request to the KEGG REST API fails or times out.
+    """
+    return _process_response(
+        KEGGurl=ku.MolecularFindKEGGurl, kegg_rest=kegg_rest, database=database, formula=formula, exact_mass=exact_mass,
+        molecular_weight=molecular_weight)

kegg_pull/entry_ids_cli.py

@@ -0,0 +1,38 @@
+"""
+Usage:
+    kegg_pull entry-ids -h | --help
+    kegg_pull entry-ids database <database> [--output=<output>]
+    kegg_pull entry-ids keywords <database> <keywords> [--output=<output>]
+    kegg_pull entry-ids molec-attr <database> (--formula=<formula>|--em=<exact-mass>...|--mw=<molecular-weight>...) [--output=<output>]
+
+Options:
+    -h --help               Show this help message.
+    database                Pulls all the entry IDs within a given database.
+    <database>              The KEGG database from which to pull a list of entry IDs.
+    --output=<output>       Path to the file (either in a directory or ZIP archive) to store the output (1 entry ID per line). Prints to the console if not specified. If a ZIP archive, the file path must be in the form of /path/to/zip-archive.zip:/path/to/file (e.g. ./archive.zip:file.txt).
+    keywords                Searches for entries within a database based on provided keywords.
+    <keywords>              Comma separated list of keywords to search entries with (e.g. kw1,kw2,kw3 etc.). Or if equal to "-", keywords are read from standard input, one keyword per line; Press CTRL+D to finalize input or pipe (e.g. cat file.txt | kegg_pull rest find brite - ...).
+    molec-attr              Searches a database of molecule-type KEGG entries by molecular attributes.
+    --formula=<formula>     Sequence of atoms in a chemical formula format to search for (e.g. "O5C7" searches for molecule entries containing 5 oxygen atoms and/or 7 carbon atoms).
+    --em=<exact-mass>       Either a single number (e.g. "--em=155.5") or two numbers (e.g. "--em=155.5 --em=244.4"). If a single number, searches for molecule entries with an exact mass equal to that value rounded by the last decimal point. If two numbers, searches for molecule entries with an exact mass within the two values (a range).
+    --mw=<molecular-weight> Same as "--em=<exact-mass>" but searches based on the molecular weight.
+"""
+import docopt as d
+from . import entry_ids as ei
+from . import _utils as u
+
+
+def main() -> None:
+    args = d.docopt(__doc__)
+    database: str = args['<database>']
+    if args['database']:
+        entry_ids = ei.from_database(database=database)
+    elif args['keywords']:
+        keywords: list = u.parse_input_sequence(input_source=args['<keywords>'])
+        entry_ids = ei.from_keywords(database=database, keywords=keywords)
+    else:
+        formula, exact_mass, molecular_weight = u.get_molecular_attribute_args(args=args)
+        entry_ids = ei.from_molecular_attribute(
+            database=database, formula=formula, exact_mass=exact_mass, molecular_weight=molecular_weight)
+    entry_ids_str = '\n'.join(entry_ids)
+    u.print_or_save(output_target=args['--output'], output_content=entry_ids_str)