fixes #152: support NCBI API keys

.gitignore

@@ -1,115 +1,93 @@
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
 
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-env/
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
+*~
+archive
+*.bak
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
+build
+build/
+# Byte-compiled / optimized / DLL files
+.cache
+celerybeat-schedule
+# celery beat schedule file
+# C extensions
+cover
+*,cover
 .coverage
 .coverage.*
-.cache
-nosetests.xml
 coverage.xml
-*,cover
-.hypothesis/
-
-# Translations
-*.mo
-*.pot
-
+develop-eggs/
+dist
+dist/
+# Distribution / packaging
 # Django stuff:
-*.log
-local_settings.py
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
+doc/_build
 docs/_build/
-
-# PyBuilder
-target/
-
-# IPython Notebook
-.ipynb_checkpoints
-
-# pyenv
-.python-version
-
-# celery beat schedule file
-celerybeat-schedule
-
 # dotenv
-.env
-
-# virtualenv
-venv/
-ENV/
-
-# Spyder project settings
-.spyderproject
-
-# Rope project settings
-.ropeproject
-
-
-*.bak
+downloads/
+.DS_Store
+*.egg
 *.egg-info
+*.egg-info/
+.eggs
+.eggs/
+eggs/
 *.enc
+.env
+env/
+ENV/
+# Flask stuff:
+htmlcov/
+.hypothesis/
+.installed.cfg
+# Installer logs
+instance/
 *.ipynb
+.ipynb_checkpoints
+# IPython Notebook
 *.json
+.keys
+lib/
+lib64/
+local_settings.py
+*.log
+*.manifest
+*.mo
+nosetests.xml
 *.orig
+parts/
+pip-delete-this-directory.txt
+pip-log.txt
+*.pot
+# PyBuilder
 *.pyc
+__pycache__/
+*$py.class
+*.py[cod]
+# pyenv
+# PyInstaller
 *.pyo
+.pytest_cache
+.Python
+.python-version
+*.rej
+.ropeproject
+# Rope project settings
+.scrapy
+# Scrapy stuff:
+sdist/
 *.so
-*~
-.DS_Store
-.cache
-.coverage
-.eggs
-.keys
-.tox/
-archive
-build
-cover
-dist
-doc/_build
+*.spec
+# Sphinx documentation
+.spyderproject
+# Spyder project settings
+target/
 tmp
-venv/
+.tox/
+# Translations
+# Unit test / coverage reports
+#  Usually these files are written by a python script from a template
+var/
 ve3k/
+venv/
+# virtualenv
+.webassets-cache

Makefile

@@ -5,7 +5,7 @@
 .PRECIOUS :
 .SUFFIXES:
 
-SHELL:=/bin/bash -o pipefail
+SHELL:=/bin/bash -e -o pipefail
 SELF:=$(firstword $(MAKEFILE_LIST))
 
 PKG=eutils
@@ -72,7 +72,7 @@ bdist bdist_egg bdist_wheel build sdist install develop: %:
 #=> test: execute tests
 .PHONY: test
 test:
-	python setup.py pytest --addopts="--cov=${PKG} ${PKG} tests"
+	python setup.py pytest --addopts="--cov=${PKG} ${PKGD} tests"
 
 #=> tox: execute tests via tox
 .PHONY: tox

README.rst

@@ -33,16 +33,27 @@ Features
 A Quick Example
 ---------------
 
+As of May 1, 2018, NCBI throttles requests based on whether a client
+is registered. Unregistered clients are limited to 3 requests/second;
+registered clients are granted 10 requests/second, and may request
+more. See the `NCBI Announcement
+<https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/>`_
+for more information. 
+
+The eutils package will automatically throttle requests according to
+NCBI guidelines (3 or 10 requests/second without or with an API key,
+respectively).
+
 ::
 
   $ pip install eutils
   $ ipython
 
-  >>> import eutils.client
+  >>> from eutils import Client
   
   # Initialize a client. This client handles all caching and query
-  # throttling
-  >>> ec = eutils.client.Client()
+  # throttling.  For example:
+  >>> ec = Client(api_key=os.environ.get("NCBI_API_KEY", None))
 
   # search for tumor necrosis factor genes
   # any valid NCBI query may be used

TODO

@@ -21,3 +21,15 @@ separate caching, throttling, querying, parsing/facades
 * #124: Support large search result sets
 support webenv history
 use web history + iterators for chained searching
+
+* add test tags to isolate tests against live ncbi data (ie not pyvcr tests)
+
+* QueryService:
+** Fetch & compare
+** TTL support in cache, request-specific TTLs?
+** optional db -> options map (esp. for rettype & retmode)
+** deal with caching status 200 replies that are bogus (e.g., truncated xml) -- callbacks?
+** provide uncached access
+** support history
+** default args is misplaced -- it should go in client instead
+

etc/develop.reqs

@@ -5,6 +5,8 @@ pytest
 pytest-cov
 restview
 setuptools
+sphinx
+sphinx_rtd_theme
 tox
 vcrpy
 yapf

eutils/client.py

@@ -7,7 +7,7 @@
 
 import lxml.etree as le
 
-from eutils.exceptions import *
+from eutils.exceptions import EutilsError
 from eutils.queryservice import QueryService
 from eutils.xmlfacades.dbsnp import ExchangeSet
 from eutils.xmlfacades.einforesult import EInfoResult
@@ -27,13 +27,15 @@ class Client(object):
 
     """
 
-    def __init__(self, cache=False):
+    def __init__(self, cache=False, api_key=None):
         """
         :param str cache: passed to QueryService, which see for explanation
+        :param str api_key: API key from NCBI
         :raises EutilsError: if cache file couldn't be created
+
         """
 
-        self._qs = QueryService(cache=cache)
+        self._qs = QueryService(cache=cache, api_key=api_key)
 
 
     @property