diff --git a/README b/README index 42061c0..92cacd2 120000 --- a/README +++ b/README @@ -1 +1 @@ -README.md \ No newline at end of file +README.rst \ No newline at end of file diff --git a/README.md b/README.md deleted file mode 100644 index c3f041a..0000000 --- a/README.md +++ /dev/null @@ -1,38 +0,0 @@ -wsgi-intercept -====================== - -[![travis](https://secure.travis-ci.org/cdent/wsgi-intercept.png)](https://secure.travis-ci.org/cdent/wsgi-intercept) - -Documentation is available on [Read The -Docs](http://wsgi-intercept.readthedocs.org/en/latest/). - -What is it? -=========== - -wsgi_intercept installs a WSGI application in place of a real host for -testing while still preserving HTTP semantics. See the -[PyPI page](http://pypi.python.org/pypi/wsgi_intercept) page for more details. -It works by intercepting the connection handling in http client -libraries. - -Supported Libraries -------------------- - -For Python 2.7 the following libraries are supported: - -* `urllib2` -* `httplib` -* `httplib2` -* `requests` -* `urllib3` - -In Python 3: - -* `urllib.request` -* `http.client` -* `httplib2` -* `requests` -* `urllib3` - -If you are using Python 2 and need support for a different HTTP -client, require a version of `wsgi_intercept<0.6`. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..1056576 --- /dev/null +++ b/README.rst @@ -0,0 +1,132 @@ +Installs a WSGI application in place of a real host for testing. + +Introduction +============ + +Testing a WSGI application sometimes involves starting a server at a +local host and port, then pointing your test code to that address. +Instead, this library lets you intercept calls to any specific host/port +combination and redirect them into a `WSGI application`_ importable by +your test program. Thus, you can avoid spawning multiple processes or +threads to test your Web app. + +Supported Libaries +================== + +``wsgi_intercept`` works with a variety of HTTP clients in Python 2.7, +3.3 and beyond, and in pypy. + +* urllib2 +* urllib.request +* httplib +* http.client +* httplib2 +* requests +* urllib3 + +How Does It Work? +================= + +``wsgi_intercept`` works by replacing ``httplib.HTTPConnection`` with a +subclass, ``wsgi_intercept.WSGI_HTTPConnection``. This class then +redirects specific server/port combinations into a WSGI application by +emulating a socket. If no intercept is registered for the host and port +requested, those requests are passed on to the standard handler. + +The easiest way to use an intercept is to import an appropriate subclass +of ``~wsgi_intercept.interceptor.Interceptor`` and use that as a +context manager over web requests that use the library associated with +the subclass. For example:: + + import httplib2 + from wsgi_intercept.interceptor import Httplib2Interceptor + from mywsgiapp import app + + def load_app(): + return app + + http = httplib2.Http() + with Httplib2Interceptor(load_app, host='example.com', port=80) as url: + response, content = http.request('%s%s' % (url, '/path')) + assert response.status == 200 + +The interceptor class may aslo be used directly to install intercepts. +See the module documentation for more information. + +Older versions required that the functions ``add_wsgi_intercept(host, +port, app_create_fn, script_name='')`` and ``remove_wsgi_intercept(host,port)`` +be used to specify which URLs should be redirected into what applications. +These methods are still available, but the ``Interceptor`` classes are likely +easier to use for most use cases. + +Note especially that ``app_create_fn`` is a *function object* returning a WSGI +application; ``script_name`` becomes ``SCRIPT_NAME`` in the WSGI app's +environment, if set. + +Note also that if ``http_proxy`` or ``https_proxy`` is set in the environment +this can cause difficulties with some of the intercepted libraries. If +requests or urllib is being used, these will raise an exception if one of +those variables is set. + +Install +======= + +:: + + pip install -U wsgi_intercept + +Packages Intercepted +==================== + +Unfortunately each of the HTTP client libraries use their own specific +mechanism for making HTTP call-outs, so individual implementations are +needed. At this time there are implementations for ``httplib2``, +``urllib3`` and ``requests`` in both Python 2 and 3, ``urllib2`` and +``httplib`` in Python 2 and ``urllib.request`` and ``http.client`` +in Python 3. + +If you are using Python 2 and need support for a different HTTP +client, require a version of ``wsgi_intercept<0.6``. Earlier versions +include support for ``webtest``, ``webunit`` and ``zope.testbrowser``. + +The best way to figure out how to use interception is to inspect +`the tests`_. More comprehensive documentation available upon +request. + +.. _the tests: https://github.com/cdent/wsgi-intercept/tree/master/test + + +History +======= + +Pursuant to Ian Bicking's `"best Web testing framework"`_ post, Titus +Brown put together an `in-process HTTP-to-WSGI interception mechanism`_ +for his own Web testing system, twill. Because the mechanism is pretty +generic -- it works at the httplib level -- Titus decided to try adding +it into all of the *other* Python Web testing frameworks. + +The Python 2 version of wsgi-intercept was the result. Kumar McMillan +later took over maintenance. + +The current version is tested with Python 2.7, 3.3, 3.4, 3.5 and pypy +and was assembled by `Chris Dent`_. Testing and documentation improvements +from `Sasha Hart`_. + +.. _"best Web testing framework": + http://blog.ianbicking.org/best-of-the-web-app-test-frameworks.html +.. _in-process HTTP-to-WSGI interception mechanism: + http://www.advogato.org/person/titus/diary.html?start=119 +.. _WSGI application: http://www.python.org/peps/pep-3333.html +.. _Chris Dent: https://github.com/cdent +.. _Sasha Hart: https://github.com/sashahart + +Project Home +============ + +This project lives on `GitHub`_. Please submit all bugs, patches, +failing tests, et cetera using the Issue Tracker. + +Additional documentation is available on `Read The Docs`_. + +.. _GitHub: http://github.com/cdent/wsgi-intercept +.. _Read The Docs: http://wsgi-intercept.readthedocs.org/en/latest/ diff --git a/setup.py b/setup.py index 377c179..e0fd974 100644 --- a/setup.py +++ b/setup.py @@ -1,7 +1,9 @@ -import wsgi_intercept from setuptools import setup, find_packages +VERSION = '1.4.0' +README = open('README.rst').read() + CLASSIFIERS = """ Environment :: Web Environment Intended Audience :: Developers @@ -20,7 +22,7 @@ Topic :: Software Development :: Testing META = { 'name': 'wsgi_intercept', - 'version': wsgi_intercept.__version__, + 'version': VERSION, 'author': 'Titus Brown, Kumar McMillan, Chris Dent, Sasha Hart', 'author_email': 'cdent@peermore.com', 'description': @@ -28,7 +30,7 @@ META = { 'real URI for testing.', # What will the name be? 'url': 'http://pypi.python.org/pypi/wsgi_intercept', - 'long_description': wsgi_intercept.__doc__, + 'long_description': README, 'license': 'MIT License', 'classifiers': CLASSIFIERS, 'packages': find_packages(), diff --git a/tox.ini b/tox.ini index 82239c0..87bdf21 100644 --- a/tox.ini +++ b/tox.ini @@ -1,7 +1,7 @@ [tox] minversion = 1.6 skipsdist = True -envlist = py27,py33,py34,py35,pypy,pep8,docs +envlist = py27,py33,py34,py35,pypy,pep8,docs,readme [testenv] deps = .[testing] @@ -20,6 +20,11 @@ commands = whitelist_externals = rm +[testenv:readme] +deps = . +whitelist_externals = bash +commands = bash -c "python -c 'import sys, wsgi_intercept; sys.stdout.write(wsgi_intercept.__doc__)' > README.rst" + [flake8] exclude=.venv,.git,.tox,dist,*egg,*.egg-info,build,examples,docs show-source = True diff --git a/wsgi_intercept/__init__.py b/wsgi_intercept/__init__.py index 71826c4..c4e2dc6 100644 --- a/wsgi_intercept/__init__.py +++ b/wsgi_intercept/__init__.py @@ -3,13 +3,27 @@ Introduction ============ -Testing a WSGI application normally involves starting a server at a +Testing a WSGI application sometimes involves starting a server at a local host and port, then pointing your test code to that address. Instead, this library lets you intercept calls to any specific host/port combination and redirect them into a `WSGI application`_ importable by your test program. Thus, you can avoid spawning multiple processes or threads to test your Web app. +Supported Libaries +================== + +``wsgi_intercept`` works with a variety of HTTP clients in Python 2.7, +3.3 and beyond, and in pypy. + +* urllib2 +* urllib.request +* httplib +* http.client +* httplib2 +* requests +* urllib3 + How Does It Work? ================= @@ -64,17 +78,16 @@ Install Packages Intercepted ==================== -Unfortunately each of the Web testing frameworks uses its own specific +Unfortunately each of the HTTP client libraries use their own specific mechanism for making HTTP call-outs, so individual implementations are -needed. At this time there are implementations for ``httplib2`` and -``requests`` in both Python 2 and 3, ``urllib2`` and ``httplib`` -in Python 2 and ``urllib.request`` and ``http.client`` in Python 3. +needed. At this time there are implementations for ``httplib2``, +``urllib3`` and ``requests`` in both Python 2 and 3, ``urllib2`` and +``httplib`` in Python 2 and ``urllib.request`` and ``http.client`` +in Python 3. If you are using Python 2 and need support for a different HTTP client, require a version of ``wsgi_intercept<0.6``. Earlier versions include support for ``webtest``, ``webunit`` and ``zope.testbrowser``. -It is quite likely that support for these versions will be relatively -easy to add back in to the new version. The best way to figure out how to use interception is to inspect `the tests`_. More comprehensive documentation available upon @@ -117,7 +130,6 @@ Additional documentation is available on `Read The Docs`_. .. _GitHub: http://github.com/cdent/wsgi-intercept .. _Read The Docs: http://wsgi-intercept.readthedocs.org/en/latest/ - """ from __future__ import print_function