From 807513f2b0423c5def8ff2ab712ea1aee329578c Mon Sep 17 00:00:00 2001
From: Kevin Wu <me@kevinformatics.com>
Date: Wed, 10 Oct 2012 14:16:50 -0700
Subject: [PATCH 1/3] Added a KEGG API Wrapper, docs, and tests

---
 Bio/KEGG/__init__.py   | 197 ++++++++++++++++++++++++++++++++++++++++-
 Doc/Tutorial.tex       |  88 ++++++++++++++++++
 Tests/output/test_KEGG |  41 +++++++++
 Tests/test_KEGG.py     | 157 ++++++++++++++++++++++++++++++++
 4 files changed, 482 insertions(+), 1 deletion(-)

diff --git a/Bio/KEGG/__init__.py b/Bio/KEGG/__init__.py
index 880e3c3856f..c28e6c10e38 100644
--- a/Bio/KEGG/__init__.py
+++ b/Bio/KEGG/__init__.py
@@ -1,4 +1,6 @@
-# Copyright 2001 by Tarjei Mikkelsen.  All rights reserved.
+# Copyright 2001 by Tarjei Mikkelsen.
+# Copyright 2012 by Kevin Wu.
+# All rights reserved.
 # This code is part of the Biopython distribution and governed by its
 # license.  Please see the LICENSE file that should have been included
 # as part of this package.
@@ -81,3 +83,196 @@ def _write_kegg(item, info, indent=KEGG_ITEM_LENGTH):
             if item is not "":  # ensure item is only written on first line
                 item = ""
     return s
+
+
+def _q(op, arg1, arg2=None, arg3=None):
+
+  import urllib2
+  URL = "http://rest.kegg.jp/%s"
+
+  if arg2 and arg3:
+    args = "%s/%s/%s/%s" % (op, arg1, arg2, arg3)
+  elif arg2:
+    args = "%s/%s/%s" % (op, arg1, arg2)
+  else:
+    args = "%s/%s" % (op, arg1)
+
+  req = urllib2.Request(URL % (args))
+  resp = urllib2.urlopen(req)
+
+  return resp
+
+
+# http://www.kegg.jp/kegg/rest/keggapi.html
+def info(arg1):
+    # http://rest.kegg.jp/info/<database>
+    #
+    # <database> = pathway | brite | module | disease | drug | environ |
+    #              ko | genome |<org> | compound | glycan | reaction |
+    #              rpair | rclass | enzyme | genomes | genes | ligand | kegg
+    # <org> = KEGG organism code or T number
+    if arg1:
+        resp = _q("info", arg1)
+    else:
+        raise Exception("Invalid info operation.")
+
+    return resp
+
+
+def list_(arg1, arg2=None):
+    #  http://rest.kegg.jp/list/<database>/<org>
+    #
+    #  <database> = pathway | module
+    #  <org> = KEGG organism code
+    if isinstance(arg1, str) and (arg1 == "pathway" or arg1 == "module") and arg2:
+        resp = _q("list", arg1, arg2)
+
+    # http://rest.kegg.jp/list/<database>
+    #
+    # <database> = pathway | brite | module | disease | drug | environ |
+    #              ko | genome | <org> | compound | glycan | reaction |
+    #              rpair | rclass | enzyme | organism
+    # <org> = KEGG organism code or T number
+    #
+    #
+    # http://rest.kegg.jp/list/<dbentries>
+    #
+    # <dbentries> = KEGG database entries involving the following <database>
+    # <database> = pathway | brite | module | disease | drug | environ |
+    #              ko | genome | <org> | compound | glycan | reaction |
+    #              rpair | rclass | enzyme
+    # <org> = KEGG organism code or T number
+    elif arg1 and not arg2:
+        if isinstance(arg1, list) and len(arg1) <= 100:
+            arg1 = ("+").join(arg1)
+        elif isinstance(arg1, list) and len(arg1) > 100:
+            raise Exception("Maximuim number of queries is 100")
+        resp = _q("list", arg1)
+
+    else:
+        raise Exception("Invalid list operation.")
+
+    return resp
+
+
+def find(arg1, arg2=None, arg3=None):
+    # http://rest.kegg.jp/find/<database>/<query>/<option>
+    #
+    # <database> = compound | drug
+    # <option> = formula | exact_mass | mol_weight
+    if arg1 in ["compound", "drug"] and arg2 and \
+          arg3 in ["formula", "exact_mass", "mol_weight"]:
+        resp = _q("find", arg1, arg2, arg3)
+
+    # http://rest.kegg.jp/find/<database>/<query>
+    #
+    # <database> = pathway | module | disease | drug | environ | ko |
+    #              genome | <org> | compound | glycan | reaction | rpair |
+    #              rclass | enzyme | genes | ligand
+    # <org> = KEGG organism code or T number
+    elif arg1 and arg2 and not arg3:
+
+        if isinstance(arg2, list):
+            arg2 = "+".join(arg2)
+        resp = _q("find", arg1, arg2)
+
+    else:
+        raise Exception("Invalid find operation.")
+
+    return resp
+
+
+def get(arg1, arg2=None):
+    if isinstance(arg1, list) and len(arg1) <= 10:
+        arg1 = "+".join(arg1)
+    elif isinstance(arg1, list) and len(arg1) > 10:
+        raise Exception("Maximuim number of queries is 10")
+
+    # http://rest.kegg.jp/get/<dbentries>[/<option>]
+    #
+    # <dbentries> = KEGG database entries involving the following <database>
+    # <database> = pathway | brite | module | disease | drug | environ |
+    #              ko | genome | <org> | compound | glycan | reaction |
+    #              rpair | rclass | enzyme
+    # <org> = KEGG organism code or T number
+    #
+    # <option> = aaseq | ntseq | mol | kcf | image
+    if arg1 and arg2 in ["aaseq" , "ntseq", "mol", "kcf", "image"]:
+        resp = _q("get", arg1, arg2)
+    elif arg1 and not arg2:
+        resp = _q("get", arg1)
+    else:
+        raise Exception("Invalid get operation.")
+
+    return resp
+
+
+def conv(arg1, arg2=None):
+    # http://rest.kegg.jp/conv/<target_db>/<source_db>
+    #
+    # (<target_db> <source_db>) = (<kegg_db> <outside_db>) |
+    #                             (<outside_db> <kegg_db>)
+    #
+    # For gene identifiers:
+    # <kegg_db> = <org>
+    # <org> = KEGG organism code or T number
+    # <outside_db> = ncbi-gi | ncbi-geneid | uniprot
+    #
+    # For chemical substance identifiers:
+    # <kegg_db> = drug | compound | glycan
+    # <outside_db> = pubchem | chebi
+    if ((arg1 and arg2 in ["ncbi-gi", "ncbi-geneid", "uniprot"]) or
+        (arg1 in ["ncbi-gi", "ncbi-geneid", "uniprot"] and arg2) or
+        (arg1 in ["drug", "compound", "glycan"] and
+         arg2 in ["pubchem", "glycan"]) or
+        (arg1 in ["pubchem", "glycan"] and
+         arg2 in ["drug", "compound", "glycan"])) \
+       and isinstance(arg2, str):
+        resp = _q("conv", arg1, arg2)
+
+    # http://rest.kegg.jp/conv/<target_db>/<dbentries>
+    #
+    # For gene identifiers:
+    # <dbentries> = database entries involving the following <database>
+    # <database> = <org> | ncbi-gi | ncbi-geneid | uniprot
+    # <org> = KEGG organism code or T number
+    #
+    # For chemical substance identifiers:
+    # <dbentries> = database entries involving the following <database>
+    # <database> = drug | compound | glycan | pubchem | chebi
+    elif arg1 and arg2:
+        if isinstance(arg2, list):
+            arg2 = "+".join(arg2)
+        resp = _q("conv", arg1, arg2)
+
+    else:
+        raise Exception("Invalid conv operation.")
+
+    return resp
+
+
+def link(arg1, arg2):
+    # http://rest.kegg.jp/link/<target_db>/<source_db>
+    #
+    # <target_db> = <database>
+    # <source_db> = <database>
+    #
+    # <database> = pathway | brite | module | disease | drug | environ |
+    #              ko | genome | <org> | compound | glycan | reaction |
+    #              rpair | rclass | enzyme
+    #
+    # http://rest.kegg.jp/link/<target_db>/<dbentries>
+    #
+    # <dbentries> = KEGG database entries involving the following <database>
+    # <database> = pathway | brite | module | disease | drug | environ |
+    #              ko | genome | <org> | compound | glycan | reaction |
+    #              rpair | rclass | enzyme
+    if arg1 and arg2:
+        if isinstance(arg2, list):
+            arg2 = "+".join(arg2)
+        resp = _q("link", arg1, arg2)
+
+    else:
+        raise Exception("Invalid link operation.")
+
+    return resp
diff --git a/Doc/Tutorial.tex b/Doc/Tutorial.tex
index c088a0889a3..31e2abb2bb0 100644
--- a/Doc/Tutorial.tex
+++ b/Doc/Tutorial.tex
@@ -15471,6 +15471,94 @@ \subsection{Annotated Chromosomes}
 in Figure~\ref{fig:simplechromosome}.
 \end{latexonly}
 
+\chapter{KEGG}
+\label{chap:kegg}
+
+KEGG (\url{http://www.kegg.jp/}) is a database resource for understanding high-level functions and utilities of the biological system, such as the cell, the organism and the ecosystem, from molecular-level information, especially large-scale molecular datasets generated by genome sequencing and other high-throughput experimental technologies.
+
+Please note that the KEGG parser implementation in Biopython is incomplete. While the KEGG website indicates many flat file formats, only parsers and writers for compound, enzyme, and map are currently implemented. However, a generic parser is implemented to handle the other formats.
+
+\section{Parsing KEGG records}
+Parsing a KEGG record is as simple as using any other file format parser in Biopython. 
+
+\begin{verbatim}
+>>> from Bio.KEGG import Enzyme
+>>> records = Enzyme.parse(open("ec:5.4.2.2.txt"))
+>>> record = list(records)[0]
+>>> record.classname
+['Isomerases;', 'Intramolecular transferases;', 'Phosphotransferases (phosphomutases)']
+>>> record.entry
+'5.4.2.2'
+\end{verbatim}
+
+The following section will shows how to download the above enzyme using the KEGG api as well as how to use the generic parser with data that does not have a custom parser implemented.
+
+\section{Querying the KEGG API}
+
+Biopython has full support for the querying of the KEGG api. Querying all KEGG endpoints are supported; all methods documented by KEGG (\url{http://www.kegg.jp/kegg/rest/keggapi.html}) are supported. The interface has some validation of queries which follow rules defined on the KEGG site. However, invalid queries which return a 400 or 404 must be handled by the user.
+
+First, here is how to extend the above example by downloading the relevant enzyme and passing it through the Enzyme parser.
+
+\begin{verbatim}
+>>> from Bio import KEGG
+>>> from Bio.KEGG import Enzyme
+>>> request = KEGG.get("ec:5.4.2.2")
+>>> open("ec:5.4.2.2.txt", 'w').write(request.read())
+>>> records = Enzyme.parse(open("ec:5.4.2.2.txt"))
+>>> record = list(records)[0]
+>>> record.classname
+['Isomerases;', 'Intramolecular transferases;', 'Phosphotransferases (phosphomutases)']
+>>> record.entry
+'5.4.2.2'
+\end{verbatim}
+
+Now, here's a more realistic example which shows a combination of querying the KEGG API. This will demonstrate how to extract a unique set of all human pathway gene symbols which relate to DNA repair. The steps that need to be taken to do so are as follows. First, we need to get a list of all human pathways. Secondly, we need to filter those for ones which relate to "repair". Lastly, we need to get a list of all the gene symbols in all repair pathways.
+
+\begin{verbatim}
+from Bio import KEGG
+
+human_pathways = KEGG.list_("pathway", "hsa").read()
+
+# Filter all human pathways for repair pathways
+repair_pathways = []
+for line in human_pathways.rstrip().split("\n"):
+    entry, description = line.split("\t")
+    if "repair" in description:
+        repair_pathways.append(entry)
+
+# Get the genes for pathways and add them to a list
+repair_genes = [] 
+for pathway in repair_pathways:
+    pathway_file = KEGG.get(pathway).read()  # query and read each pathway
+
+    # iterate through each KEGG pathway file, keeping track of which section
+    # of the file we're in, only read the gene in each pathway
+    current_section = None
+    for line in pathway_file.rstrip().split("\n"):
+        section = line[:12].strip()  # section names are within 12 columns
+        if not section == "":
+            current_section = section
+        
+        if current_section == "GENE":
+            gene_identifiers, gene_description = line[12:].split("; ")
+            gene_id, gene_symbol = gene_identifiers.split()
+
+            if not gene_symbol in repair_genes:
+                repair_genes.append(gene_symbol)
+
+print "There are %d repair pathways and %d repair genes. The genes are:" % \
+      (len(repair_pathways), len(repair_genes))
+print ", ".join(repair_genes)
+\end{verbatim}
+
+The KEGG API wrapper is compatible with all endpoints. Usage is essentially replacing all slashes in the url with commas and using that list as arguments to the corresponding method in the KEGG module. Here are a few examples from the api documentation (\url{http://www.kegg.jp/kegg/docs/keggapi.html}).
+
+\begin{verbatim}
+/list/hsa:10458+ece:Z5100	         -> KEGG.list(["hsa:10458", "ece:Z510"])
+/find/compound/300-310/mol_weight	 -> KEGG.find("compound", "300-310", "mol_weight")
+/get/hsa:10458+ece:Z5100/aaseq	    -> KEGG.get(["hsa:10458", "ece:Z5100"], "aaseq")
+\end{verbatim}
+
 \chapter{Cookbook -- Cool things to do with it}
 \label{chapter:cookbook}
 
diff --git a/Tests/output/test_KEGG b/Tests/output/test_KEGG
index 2f372e6748c..a90ce3bdd31 100644
--- a/Tests/output/test_KEGG
+++ b/Tests/output/test_KEGG
@@ -761,3 +761,44 @@ Oripavine <=> Morphinone
 Thebaine <=> Neopinone
 Thebaine <=> Oripavine
 Tyramine <=> Dopamine
+
+
+Testing Bio.KEGG.query
+
+
+http://rest.kegg.jp/info/kegg
+http://rest.kegg.jp/info/pathway
+http://rest.kegg.jp/list/pathway
+http://rest.kegg.jp/list/pathway/hsa
+http://rest.kegg.jp/list/organism
+http://rest.kegg.jp/list/hsa
+http://rest.kegg.jp/list/T01001
+http://rest.kegg.jp/list/hsa:10458+ece:Z5100
+http://rest.kegg.jp/list/hsa:10458+ece:Z5100
+http://rest.kegg.jp/list/cpd:C01290+gl:G00092
+http://rest.kegg.jp/list/cpd:C01290+gl:G00092
+http://rest.kegg.jp/list/C01290+G00092
+http://rest.kegg.jp/list/C01290+G00092
+http://rest.kegg.jp/find/genes/shiga+toxin
+http://rest.kegg.jp/find/genes/shiga+toxin
+http://rest.kegg.jp/find/compound/C7H10O5/formula
+http://rest.kegg.jp/find/compound/O5C7/formula
+http://rest.kegg.jp/find/compound/174.05/exact_mass
+http://rest.kegg.jp/find/compound/300-310/mol_weight
+http://rest.kegg.jp/get/cpd:C01290+gl:G00092
+http://rest.kegg.jp/get/cpd:C01290+gl:G00092
+http://rest.kegg.jp/get/C01290+G00092
+http://rest.kegg.jp/get/C01290+G00092
+http://rest.kegg.jp/get/hsa:10458+ece:Z5100
+http://rest.kegg.jp/get/hsa:10458+ece:Z5100
+http://rest.kegg.jp/get/hsa:10458+ece:Z5100/aaseq
+http://rest.kegg.jp/get/hsa:10458+ece:Z5100/aaseq
+http://rest.kegg.jp/get/hsa05130/image
+http://rest.kegg.jp/conv/eco/ncbi-geneid
+http://rest.kegg.jp/conv/ncbi-geneid/eco
+http://rest.kegg.jp/conv/ncbi-gi/hsa:10458+ece:Z5100
+http://rest.kegg.jp/conv/ncbi-gi/hsa:10458+ece:Z5100
+http://rest.kegg.jp/link/pathway/hsa
+http://rest.kegg.jp/link/hsa/pathway
+http://rest.kegg.jp/link/pathway/hsa:10458+ece:Z5100
+http://rest.kegg.jp/link/pathway/hsa:10458+ece:Z5100
diff --git a/Tests/test_KEGG.py b/Tests/test_KEGG.py
index 1373f02443a..68f76d7426c 100644
--- a/Tests/test_KEGG.py
+++ b/Tests/test_KEGG.py
@@ -14,6 +14,7 @@
 from Bio.KEGG import Compound
 from Bio.KEGG import Map
 from Bio.Pathway import System
+from Bio import KEGG
 
 test_KEGG_Enzyme_files   = ["enzyme.sample", "enzyme.irregular", "enzyme.new"]
 test_KEGG_Compound_files = ["compound.sample", "compound.irregular"]
@@ -64,9 +65,165 @@ def t_KEGG_Map(testfiles):
         rxs.sort(key=lambda x:str(x))
         for x in rxs:
             print(str(x))
+        print("\n")
         fh.close()
 
+def t_KEGG_Query():
+    """Tests Bio.KEGG API Wrapper"""
+    print "Testing Bio.KEGG.query\n\n"
+
+    # info tests
+    resp = KEGG.info("kegg")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.info("pathway")
+    resp.read()
+    print resp.url
+
+    # list tests
+    resp = KEGG.list_("pathway")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.list_("pathway", "hsa")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.list_("organism")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.list_("hsa")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.list_("T01001")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.list_("hsa:10458+ece:Z5100")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.list_(["hsa:10458", "ece:Z5100"])
+    resp.read()
+    print resp.url
+
+    resp = KEGG.list_("cpd:C01290+gl:G00092")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.list_(["cpd:C01290", "gl:G00092"])
+    resp.read()
+    print resp.url
+
+    resp = KEGG.list_("C01290+G00092")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.list_(["C01290", "G00092"])
+    resp.read()
+    print resp.url
+
+    # find tests
+    resp = KEGG.find("genes", "shiga+toxin")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.find("genes", ["shiga", "toxin"])
+    resp.read()
+    print resp.url
+
+    resp = KEGG.find("compound", "C7H10O5", "formula")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.find("compound", "O5C7", "formula")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.find("compound", "174.05", "exact_mass")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.find("compound", "300-310", "mol_weight")
+    resp.read()
+    print resp.url
+
+    # get tests
+    resp = KEGG.get("cpd:C01290+gl:G00092")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.get(["cpd:C01290", "gl:G00092"])
+    resp.read()
+    print resp.url
+
+    resp = KEGG.get("C01290+G00092")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.get(["C01290", "G00092"])
+    resp.read()
+    print resp.url
+
+    resp = KEGG.get("hsa:10458+ece:Z5100")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.get(["hsa:10458", "ece:Z5100"])
+    resp.read()
+    print resp.url
+
+    resp = KEGG.get("hsa:10458+ece:Z5100", "aaseq")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.get(["hsa:10458", "ece:Z5100"], "aaseq")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.get("hsa05130", "image")
+    resp.read()
+    print resp.url
+
+    # conv tests
+    resp = KEGG.conv("eco", "ncbi-geneid")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.conv("ncbi-geneid", "eco")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.conv("ncbi-gi", "hsa:10458+ece:Z5100")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.conv("ncbi-gi", ["hsa:10458", "ece:Z5100"])
+    resp.read()
+    print resp.url
+
+    # link tests
+    resp = KEGG.link("pathway", "hsa")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.link("hsa", "pathway")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.link("pathway", "hsa:10458+ece:Z5100")
+    resp.read()
+    print resp.url
+
+    resp = KEGG.link("pathway", ["hsa:10458", "ece:Z5100"])
+    resp.read()
+    print resp.url
+
 
 t_KEGG_Enzyme(test_KEGG_Enzyme_files)
 t_KEGG_Compound(test_KEGG_Compound_files)
 t_KEGG_Map(test_KEGG_Map_files)
+t_KEGG_Query()

From 1b041a250dda8b6d0cff9cce75b480837daf7cca Mon Sep 17 00:00:00 2001
From: Kevin Wu <me@kevinformatics.com>
Date: Tue, 4 Nov 2014 02:04:23 -0800
Subject: [PATCH 2/3] Move KEGG API functions, fix param names, fix tests.

Take into account Peter's suggestions in PR#152. Move functions out of
KEGG/__init__.py and rename them to include "kegg_" prefixes. Change
function param names to better reflect KEGG endpoint params. Update
interface to include new KEGG functionality. Attempt to add more
argument validation with richer error messages.
---
 Bio/KEGG/REST.py     | 216 +++++++++++++++++++++++++++++++++++++++++++
 Bio/KEGG/__init__.py | 194 --------------------------------------
 Tests/test_KEGG.py   | 149 ++++++++++++++---------------
 3 files changed, 291 insertions(+), 268 deletions(-)
 create mode 100644 Bio/KEGG/REST.py

diff --git a/Bio/KEGG/REST.py b/Bio/KEGG/REST.py
new file mode 100644
index 00000000000..cf204a16ea8
--- /dev/null
+++ b/Bio/KEGG/REST.py
@@ -0,0 +1,216 @@
+# Copyright 2014 by Kevin Wu.
+# All rights reserved.
+# This code is part of the Biopython distribution and governed by its
+# license.  Please see the LICENSE file that should have been included
+# as part of this package.
+
+"""
+This file provides a wrapper to the KEGG REST API.
+
+References:
+
+Kanehisa, M. and Goto, S.; KEGG: Kyoto Encyclopedia of Genes and Genomes.
+Nucleic Acids Res. 28, 29-34 (2000).
+
+API Docs: http://www.kegg.jp/kegg/docs/keggapi.html
+"""
+
+
+def _q(op, arg1, arg2=None, arg3=None):
+
+  import urllib2
+  URL = "http://rest.kegg.jp/%s"
+
+  if arg2 and arg3:
+    args = "%s/%s/%s/%s" % (op, arg1, arg2, arg3)
+  elif arg2:
+    args = "%s/%s/%s" % (op, arg1, arg2)
+  else:
+    args = "%s/%s" % (op, arg1)
+
+  req = urllib2.Request(URL % (args))
+  resp = urllib2.urlopen(req)
+
+  return resp
+
+
+# http://www.kegg.jp/kegg/rest/keggapi.html
+def kegg_info(database):
+    # http://rest.kegg.jp/info/<database>
+    #
+    # <database> = pathway | brite | module | disease | drug | environ |
+    #              ko | genome |<org> | compound | glycan | reaction |
+    #              rpair | rclass | enzyme | genomes | genes | ligand | kegg
+    # <org> = KEGG organism code or T number
+    return _q("info", database)
+
+
+def kegg_list(database, org=None):
+    #  http://rest.kegg.jp/list/<database>/<org>
+    #
+    #  <database> = pathway | module
+    #  <org> = KEGG organism code
+    if isinstance(database, str) and (database in ["pathway", "module"]) and org:
+        resp = _q("list", database, org)
+    elif isinstance(database, str) and database and org:
+        raise Exception("Invalid database arg for kegg list request.")
+
+    # http://rest.kegg.jp/list/<database>
+    #
+    # <database> = pathway | brite | module | disease | drug | environ |
+    #              ko | genome | <org> | compound | glycan | reaction |
+    #              rpair | rclass | enzyme | organism
+    # <org> = KEGG organism code or T number
+    #
+    #
+    # http://rest.kegg.jp/list/<dbentries>
+    #
+    # <dbentries> = KEGG database entries involving the following <database>
+    # <database> = pathway | brite | module | disease | drug | environ |
+    #              ko | genome | <org> | compound | glycan | reaction |
+    #              rpair | rclass | enzyme
+    # <org> = KEGG organism code or T number
+    else:
+        if isinstance(database, list) and len(database) <= 100:
+            database = ("+").join(database)
+        elif isinstance(database, list) and len(database) > 100:
+            raise Exception("Maximuim number of databases is 100 for kegg list query")
+        resp = _q("list", database)
+
+    return resp
+
+
+def kegg_find(database, query, option=None):
+    # http://rest.kegg.jp/find/<database>/<query>/<option>
+    #
+    # <database> = compound | drug
+    # <option> = formula | exact_mass | mol_weight
+    if database in ["compound", "drug"] and \
+          option in ["formula", "exact_mass", "mol_weight"]:
+        resp = _q("find", database, query, option)
+    elif option:
+        raise Exception("Invalid option arg for kegg find request.")
+
+    # http://rest.kegg.jp/find/<database>/<query>
+    #
+    # <database> = pathway | module | disease | drug | environ | ko |
+    #              genome | <org> | compound | glycan | reaction | rpair |
+    #              rclass | enzyme | genes | ligand
+    # <org> = KEGG organism code or T number
+    else:
+        if isinstance(query, list):
+            query = "+".join(query)
+        resp = _q("find", database, query)
+
+    return resp
+
+
+def kegg_get(dbentries, option=None):
+    if isinstance(dbentries, list) and len(dbentries) <= 10:
+        dbentries = "+".join(dbentries)
+    elif isinstance(dbentries, list) and len(dbentries) > 10:
+        raise Exception("Maximum number of dbentries is 10 for kegg get query")
+
+    # http://rest.kegg.jp/get/<dbentries>[/<option>]
+    #
+    # <dbentries> = KEGG database entries involving the following <database>
+    # <database> = pathway | brite | module | disease | drug | environ |
+    #              ko | genome | <org> | compound | glycan | reaction |
+    #              rpair | rclass | enzyme
+    # <org> = KEGG organism code or T number
+    #
+    # <option> = aaseq | ntseq | mol | kcf | image
+    if option in ["aaseq" , "ntseq", "mol", "kcf", "image"]:
+        resp = _q("get", dbentries, option)
+    elif option:
+        raise Exception("Invalid option arg for kegg get request.")
+    else:
+        resp = _q("get", dbentries)
+
+    return resp
+
+
+def kegg_conv(target_db, source_db, option=None):
+    # http://rest.kegg.jp/conv/<target_db>/<source_db>[/<option>]
+    #
+    # (<target_db> <source_db>) = (<kegg_db> <outside_db>) |
+    #                             (<outside_db> <kegg_db>)
+    #
+    # For gene identifiers:
+    # <kegg_db> = <org>
+    # <org> = KEGG organism code or T number
+    # <outside_db> = ncbi-gi | ncbi-geneid | uniprot
+    #
+    # For chemical substance identifiers:
+    # <kegg_db> = drug | compound | glycan
+    # <outside_db> = pubchem | chebi
+    #
+    # <option> = turtle | n-triple
+    #
+    # http://rest.kegg.jp/conv/<target_db>/<dbentries>[/<option>]
+    #
+    # For gene identifiers:
+    # <dbentries> = database entries involving the following <database>
+    # <database> = <org> | ncbi-gi | ncbi-geneid | uniprot
+    # <org> = KEGG organism code or T number
+    #
+    # For chemical substance identifiers:
+    # <dbentries> = database entries involving the following <database>
+    # <database> = drug | compound | glycan | pubchem | chebi
+    #
+    # <option> = turtle | n-triple
+    if option and not option in ["turtle", "n-triple"]:
+        raise Exception("Invalid option arg for kegg conv request.")
+
+    if isinstance(source_db, list):
+        source_db = "+".join(source_db)
+
+    if target_db in ["ncbi-gi", "ncbi-geneid", "uniprot"] or \
+       source_db in ["ncbi-gi", "ncbi-geneid", "uniprot"] or \
+       (target_db in ["drug", "compound", "glycan"] and
+           source_db in ["pubchem", "glycan"]) or \
+       (target_db in ["pubchem", "glycan"] and
+           source_db in ["drug", "compound", "glycan"]):
+
+        if option:
+            resp = _q("conv", target_db, source_db, option)
+        else:
+            resp = _q("conv", target_db, source_db)
+
+        return resp
+    else:
+        raise Exception("Bad argument target_db or source_db for kegg conv request.")
+
+
+def kegg_link(target_db, source_db, option=None):
+    # http://rest.kegg.jp/link/<target_db>/<source_db>[/<option>]
+    #
+    # <target_db> = <database>
+    # <source_db> = <database>
+    #
+    # <database> = pathway | brite | module | ko | genome | <org> | compound |
+    #              glycan | reaction | rpair | rclass | enzyme | disease |
+    #              drug | dgroup | environ
+    #
+    # <option> = turtle | n-triple
+    # http://rest.kegg.jp/link/<target_db>/<dbentries>[/<option>]
+    #
+    # <dbentries> = KEGG database entries involving the following <database>
+    # <database> = pathway | brite | module | ko | genome | <org> | compound |
+    #              glycan | reaction | rpair | rclass | enzyme | disease |
+    #              drug | dgroup | environ | genes
+    #
+    # <option> = turtle | n-triple
+
+    if option and not option in ["turtle", "n-triple"]:
+        raise Exception("Invalid option arg for kegg conv request.")
+
+    if isinstance(source_db, list):
+        source_db = "+".join(source_db)
+
+    if option:
+        resp = _q("link", target_db, source_db, option)
+    else:
+        resp = _q("link", target_db, source_db)
+
+    return resp
diff --git a/Bio/KEGG/__init__.py b/Bio/KEGG/__init__.py
index c28e6c10e38..e76079a1ee4 100644
--- a/Bio/KEGG/__init__.py
+++ b/Bio/KEGG/__init__.py
@@ -1,5 +1,4 @@
 # Copyright 2001 by Tarjei Mikkelsen.
-# Copyright 2012 by Kevin Wu.
 # All rights reserved.
 # This code is part of the Biopython distribution and governed by its
 # license.  Please see the LICENSE file that should have been included
@@ -83,196 +82,3 @@ def _write_kegg(item, info, indent=KEGG_ITEM_LENGTH):
             if item is not "":  # ensure item is only written on first line
                 item = ""
     return s
-
-
-def _q(op, arg1, arg2=None, arg3=None):
-
-  import urllib2
-  URL = "http://rest.kegg.jp/%s"
-
-  if arg2 and arg3:
-    args = "%s/%s/%s/%s" % (op, arg1, arg2, arg3)
-  elif arg2:
-    args = "%s/%s/%s" % (op, arg1, arg2)
-  else:
-    args = "%s/%s" % (op, arg1)
-
-  req = urllib2.Request(URL % (args))
-  resp = urllib2.urlopen(req)
-
-  return resp
-
-
-# http://www.kegg.jp/kegg/rest/keggapi.html
-def info(arg1):
-    # http://rest.kegg.jp/info/<database>
-    #
-    # <database> = pathway | brite | module | disease | drug | environ |
-    #              ko | genome |<org> | compound | glycan | reaction |
-    #              rpair | rclass | enzyme | genomes | genes | ligand | kegg
-    # <org> = KEGG organism code or T number
-    if arg1:
-        resp = _q("info", arg1)
-    else:
-        raise Exception("Invalid info operation.")
-
-    return resp
-
-
-def list_(arg1, arg2=None):
-    #  http://rest.kegg.jp/list/<database>/<org>
-    #
-    #  <database> = pathway | module
-    #  <org> = KEGG organism code
-    if isinstance(arg1, str) and (arg1 == "pathway" or arg1 == "module") and arg2:
-        resp = _q("list", arg1, arg2)
-
-    # http://rest.kegg.jp/list/<database>
-    #
-    # <database> = pathway | brite | module | disease | drug | environ |
-    #              ko | genome | <org> | compound | glycan | reaction |
-    #              rpair | rclass | enzyme | organism
-    # <org> = KEGG organism code or T number
-    #
-    #
-    # http://rest.kegg.jp/list/<dbentries>
-    #
-    # <dbentries> = KEGG database entries involving the following <database>
-    # <database> = pathway | brite | module | disease | drug | environ |
-    #              ko | genome | <org> | compound | glycan | reaction |
-    #              rpair | rclass | enzyme
-    # <org> = KEGG organism code or T number
-    elif arg1 and not arg2:
-        if isinstance(arg1, list) and len(arg1) <= 100:
-            arg1 = ("+").join(arg1)
-        elif isinstance(arg1, list) and len(arg1) > 100:
-            raise Exception("Maximuim number of queries is 100")
-        resp = _q("list", arg1)
-
-    else:
-        raise Exception("Invalid list operation.")
-
-    return resp
-
-
-def find(arg1, arg2=None, arg3=None):
-    # http://rest.kegg.jp/find/<database>/<query>/<option>
-    #
-    # <database> = compound | drug
-    # <option> = formula | exact_mass | mol_weight
-    if arg1 in ["compound", "drug"] and arg2 and \
-          arg3 in ["formula", "exact_mass", "mol_weight"]:
-        resp = _q("find", arg1, arg2, arg3)
-
-    # http://rest.kegg.jp/find/<database>/<query>
-    #
-    # <database> = pathway | module | disease | drug | environ | ko |
-    #              genome | <org> | compound | glycan | reaction | rpair |
-    #              rclass | enzyme | genes | ligand
-    # <org> = KEGG organism code or T number
-    elif arg1 and arg2 and not arg3:
-
-        if isinstance(arg2, list):
-            arg2 = "+".join(arg2)
-        resp = _q("find", arg1, arg2)
-
-    else:
-        raise Exception("Invalid find operation.")
-
-    return resp
-
-
-def get(arg1, arg2=None):
-    if isinstance(arg1, list) and len(arg1) <= 10:
-        arg1 = "+".join(arg1)
-    elif isinstance(arg1, list) and len(arg1) > 10:
-        raise Exception("Maximuim number of queries is 10")
-
-    # http://rest.kegg.jp/get/<dbentries>[/<option>]
-    #
-    # <dbentries> = KEGG database entries involving the following <database>
-    # <database> = pathway | brite | module | disease | drug | environ |
-    #              ko | genome | <org> | compound | glycan | reaction |
-    #              rpair | rclass | enzyme
-    # <org> = KEGG organism code or T number
-    #
-    # <option> = aaseq | ntseq | mol | kcf | image
-    if arg1 and arg2 in ["aaseq" , "ntseq", "mol", "kcf", "image"]:
-        resp = _q("get", arg1, arg2)
-    elif arg1 and not arg2:
-        resp = _q("get", arg1)
-    else:
-        raise Exception("Invalid get operation.")
-
-    return resp
-
-
-def conv(arg1, arg2=None):
-    # http://rest.kegg.jp/conv/<target_db>/<source_db>
-    #
-    # (<target_db> <source_db>) = (<kegg_db> <outside_db>) |
-    #                             (<outside_db> <kegg_db>)
-    #
-    # For gene identifiers:
-    # <kegg_db> = <org>
-    # <org> = KEGG organism code or T number
-    # <outside_db> = ncbi-gi | ncbi-geneid | uniprot
-    #
-    # For chemical substance identifiers:
-    # <kegg_db> = drug | compound | glycan
-    # <outside_db> = pubchem | chebi
-    if ((arg1 and arg2 in ["ncbi-gi", "ncbi-geneid", "uniprot"]) or
-        (arg1 in ["ncbi-gi", "ncbi-geneid", "uniprot"] and arg2) or
-        (arg1 in ["drug", "compound", "glycan"] and
-         arg2 in ["pubchem", "glycan"]) or
-        (arg1 in ["pubchem", "glycan"] and
-         arg2 in ["drug", "compound", "glycan"])) \
-       and isinstance(arg2, str):
-        resp = _q("conv", arg1, arg2)
-
-    # http://rest.kegg.jp/conv/<target_db>/<dbentries>
-    #
-    # For gene identifiers:
-    # <dbentries> = database entries involving the following <database>
-    # <database> = <org> | ncbi-gi | ncbi-geneid | uniprot
-    # <org> = KEGG organism code or T number
-    #
-    # For chemical substance identifiers:
-    # <dbentries> = database entries involving the following <database>
-    # <database> = drug | compound | glycan | pubchem | chebi
-    elif arg1 and arg2:
-        if isinstance(arg2, list):
-            arg2 = "+".join(arg2)
-        resp = _q("conv", arg1, arg2)
-
-    else:
-        raise Exception("Invalid conv operation.")
-
-    return resp
-
-
-def link(arg1, arg2):
-    # http://rest.kegg.jp/link/<target_db>/<source_db>
-    #
-    # <target_db> = <database>
-    # <source_db> = <database>
-    #
-    # <database> = pathway | brite | module | disease | drug | environ |
-    #              ko | genome | <org> | compound | glycan | reaction |
-    #              rpair | rclass | enzyme
-    #
-    # http://rest.kegg.jp/link/<target_db>/<dbentries>
-    #
-    # <dbentries> = KEGG database entries involving the following <database>
-    # <database> = pathway | brite | module | disease | drug | environ |
-    #              ko | genome | <org> | compound | glycan | reaction |
-    #              rpair | rclass | enzyme
-    if arg1 and arg2:
-        if isinstance(arg2, list):
-            arg2 = "+".join(arg2)
-        resp = _q("link", arg1, arg2)
-
-    else:
-        raise Exception("Invalid link operation.")
-
-    return resp
diff --git a/Tests/test_KEGG.py b/Tests/test_KEGG.py
index 68f76d7426c..d8e83358bed 100644
--- a/Tests/test_KEGG.py
+++ b/Tests/test_KEGG.py
@@ -13,8 +13,8 @@
 from Bio.KEGG import Enzyme
 from Bio.KEGG import Compound
 from Bio.KEGG import Map
+from Bio.KEGG import REST
 from Bio.Pathway import System
-from Bio import KEGG
 
 test_KEGG_Enzyme_files   = ["enzyme.sample", "enzyme.irregular", "enzyme.new"]
 test_KEGG_Compound_files = ["compound.sample", "compound.irregular"]
@@ -68,159 +68,160 @@ def t_KEGG_Map(testfiles):
         print("\n")
         fh.close()
 
+
 def t_KEGG_Query():
     """Tests Bio.KEGG API Wrapper"""
-    print "Testing Bio.KEGG.query\n\n"
+    print("Testing Bio.KEGG.query\n\n")
 
     # info tests
-    resp = KEGG.info("kegg")
+    resp = REST.kegg_info("kegg")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.info("pathway")
+    resp = REST.kegg_info("pathway")
     resp.read()
-    print resp.url
+    print(resp.url)
 
     # list tests
-    resp = KEGG.list_("pathway")
+    resp = REST.kegg_list("pathway")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.list_("pathway", "hsa")
+    resp = REST.kegg_list("pathway", "hsa")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.list_("organism")
+    resp = REST.kegg_list("organism")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.list_("hsa")
+    resp = REST.kegg_list("hsa")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.list_("T01001")
+    resp = REST.kegg_list("T01001")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.list_("hsa:10458+ece:Z5100")
+    resp = REST.kegg_list("hsa:10458+ece:Z5100")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.list_(["hsa:10458", "ece:Z5100"])
+    resp = REST.kegg_list(["hsa:10458", "ece:Z5100"])
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.list_("cpd:C01290+gl:G00092")
+    resp = REST.kegg_list("cpd:C01290+gl:G00092")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.list_(["cpd:C01290", "gl:G00092"])
+    resp = REST.kegg_list(["cpd:C01290", "gl:G00092"])
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.list_("C01290+G00092")
+    resp = REST.kegg_list("C01290+G00092")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.list_(["C01290", "G00092"])
+    resp = REST.kegg_list(["C01290", "G00092"])
     resp.read()
-    print resp.url
+    print(resp.url)
 
     # find tests
-    resp = KEGG.find("genes", "shiga+toxin")
+    resp = REST.kegg_find("genes", "shiga+toxin")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.find("genes", ["shiga", "toxin"])
+    resp = REST.kegg_find("genes", ["shiga", "toxin"])
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.find("compound", "C7H10O5", "formula")
+    resp = REST.kegg_find("compound", "C7H10O5", "formula")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.find("compound", "O5C7", "formula")
+    resp = REST.kegg_find("compound", "O5C7", "formula")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.find("compound", "174.05", "exact_mass")
+    resp = REST.kegg_find("compound", "174.05", "exact_mass")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.find("compound", "300-310", "mol_weight")
+    resp = REST.kegg_find("compound", "300-310", "mol_weight")
     resp.read()
-    print resp.url
+    print(resp.url)
 
     # get tests
-    resp = KEGG.get("cpd:C01290+gl:G00092")
+    resp = REST.kegg_get("cpd:C01290+gl:G00092")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.get(["cpd:C01290", "gl:G00092"])
+    resp = REST.kegg_get(["cpd:C01290", "gl:G00092"])
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.get("C01290+G00092")
+    resp = REST.kegg_get("C01290+G00092")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.get(["C01290", "G00092"])
+    resp = REST.kegg_get(["C01290", "G00092"])
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.get("hsa:10458+ece:Z5100")
+    resp = REST.kegg_get("hsa:10458+ece:Z5100")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.get(["hsa:10458", "ece:Z5100"])
+    resp = REST.kegg_get(["hsa:10458", "ece:Z5100"])
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.get("hsa:10458+ece:Z5100", "aaseq")
+    resp = REST.kegg_get("hsa:10458+ece:Z5100", "aaseq")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.get(["hsa:10458", "ece:Z5100"], "aaseq")
+    resp = REST.kegg_get(["hsa:10458", "ece:Z5100"], "aaseq")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.get("hsa05130", "image")
+    resp = REST.kegg_get("hsa05130", "image")
     resp.read()
-    print resp.url
+    print(resp.url)
 
     # conv tests
-    resp = KEGG.conv("eco", "ncbi-geneid")
+    resp = REST.kegg_conv("eco", "ncbi-geneid")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.conv("ncbi-geneid", "eco")
+    resp = REST.kegg_conv("ncbi-geneid", "eco")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.conv("ncbi-gi", "hsa:10458+ece:Z5100")
+    resp = REST.kegg_conv("ncbi-gi", "hsa:10458+ece:Z5100")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.conv("ncbi-gi", ["hsa:10458", "ece:Z5100"])
+    resp = REST.kegg_conv("ncbi-gi", ["hsa:10458", "ece:Z5100"])
     resp.read()
-    print resp.url
+    print(resp.url)
 
     # link tests
-    resp = KEGG.link("pathway", "hsa")
+    resp = REST.kegg_link("pathway", "hsa")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.link("hsa", "pathway")
+    resp = REST.kegg_link("hsa", "pathway")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.link("pathway", "hsa:10458+ece:Z5100")
+    resp = REST.kegg_link("pathway", "hsa:10458+ece:Z5100")
     resp.read()
-    print resp.url
+    print(resp.url)
 
-    resp = KEGG.link("pathway", ["hsa:10458", "ece:Z5100"])
+    resp = REST.kegg_link("pathway", ["hsa:10458", "ece:Z5100"])
     resp.read()
-    print resp.url
+    print(resp.url)
 
 
 t_KEGG_Enzyme(test_KEGG_Enzyme_files)

From 98e8264ca747e5b4ccfb120b713b55ddf77003b0 Mon Sep 17 00:00:00 2001
From: Kevin Wu <me@kevinformatics.com>
Date: Tue, 4 Nov 2014 02:28:43 -0800
Subject: [PATCH 3/3] make tests pass for python3

---
 Bio/KEGG/REST.py | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/Bio/KEGG/REST.py b/Bio/KEGG/REST.py
index cf204a16ea8..31ad14b705d 100644
--- a/Bio/KEGG/REST.py
+++ b/Bio/KEGG/REST.py
@@ -15,10 +15,11 @@
 API Docs: http://www.kegg.jp/kegg/docs/keggapi.html
 """
 
+from Bio._py3k import urlopen as _urlopen
+
 
 def _q(op, arg1, arg2=None, arg3=None):
 
-  import urllib2
   URL = "http://rest.kegg.jp/%s"
 
   if arg2 and arg3:
@@ -28,10 +29,7 @@ def _q(op, arg1, arg2=None, arg3=None):
   else:
     args = "%s/%s" % (op, arg1)
 
-  req = urllib2.Request(URL % (args))
-  resp = urllib2.urlopen(req)
-
-  return resp
+  return _urlopen(URL % (args))
 
 
 # http://www.kegg.jp/kegg/rest/keggapi.html