Browse files

Bug 853956 - mozhttpd doc additions/improvements;r=jhammel

  • Loading branch information...
1 parent d15b184 commit e3b5b05e877102b905096988f536cd25b5a841fb @wlach wlach committed Mar 22, 2013
Showing with 60 additions and 34 deletions.
  1. +3 −25 docs/mozhttpd.rst
  2. +40 −1 mozhttpd/mozhttpd/__init__.py
  3. +17 −8 mozhttpd/mozhttpd/mozhttpd.py
View
28 docs/mozhttpd.rst
@@ -8,33 +8,11 @@ enough, and easy-to-use enough for our needs. So we created our own.
:mod:`mozhttpd` --- Simple webserver
------------------------------------
-Mozhttpd is a simple http webserver written in python.
-
-The server is based on python standard library modules such as
-SimpleHttpServer, urlparse, etc. The ThreadingMixIn is used to
-serve each request on a discrete thread.
-
-While mozhttpd is often used to serve static files, dynamic handling
-may be specified by a dictionary of urlhandlers.
-An example of their use may be found in Eideticker.
-
-Some existing uses of mozhttpd:
-
- Peptest_
-
- Eideticker_
-
- Talos_
-
-.. _Peptest: https://github.com/mozilla/peptest/
-
-.. _Eideticker: https://github.com/mozilla/eideticker/
-
-.. _Talos: http://hg.mozilla.org/build/
-
-
.. automodule:: mozhttpd
:members:
+Interface
+`````````
+
.. autoclass:: MozHttpd
:members:
View
41 mozhttpd/mozhttpd/__init__.py
@@ -2,6 +2,45 @@
# License, v. 2.0. If a copy of the MPL was not distributed with this file,
# You can obtain one at http://mozilla.org/MPL/2.0/.
+"""
+Mozhttpd is a simple http webserver written in python, designed expressly
+for use in automated testing scenarios. It is designed to both serve static
+content and provide simple web services.
+
+The server is based on python standard library modules such as
+SimpleHttpServer, urlparse, etc. The ThreadingMixIn is used to
+serve each request on a discrete thread.
+
+Some existing uses of mozhttpd include Peptest_, Eideticker_, and Talos_.
+
+.. _Peptest: https://github.com/mozilla/peptest/
+
+.. _Eideticker: https://github.com/mozilla/eideticker/
+
+.. _Talos: http://hg.mozilla.org/build/
+
+The following simple example creates a basic HTTP server which serves
+content from the current directory, defines a single API endpoint
+`/api/resource/<resourceid>` and then serves requests indefinitely:
+
+::
+
+ import mozhttpd
+
+ @mozhttpd.handlers.json_response
+ def resource_get(request, objid):
+ return (200, { 'id': objid,
+ 'query': request.query })
+
+
+ httpd = mozhttpd.MozHttpd(port=8080, docroot='.',
+ urlhandlers = [ { 'method': 'GET',
+ 'path': '/api/resources/([^/]+)/?',
+ 'function': resource_get } ])
+ print "Serving '%s' at %s:%s" % (httpd.docroot, httpd.host, httpd.port)
+ httpd.start(block=True)
+
+"""
+
from mozhttpd import MozHttpd, Request, RequestHandler, main
from handlers import json_response
-
View
25 mozhttpd/mozhttpd/mozhttpd.py
@@ -173,11 +173,13 @@ class MozHttpd(object):
Very basic HTTP server class. Takes a docroot (path on the filesystem)
and a set of urlhandler dictionaries of the form:
- {
- 'method': HTTP method (string): GET, POST, or DEL,
- 'path': PATH_INFO (regular expression string),
- 'function': function of form fn(arg1, arg2, arg3, ..., request)
- }
+ ::
+
+ {
+ 'method': HTTP method (string): GET, POST, or DEL,
+ 'path': PATH_INFO (regular expression string),
+ 'function': function of form fn(arg1, arg2, arg3, ..., request)
+ }
and serves HTTP. For each request, MozHttpd will either return a file
off the docroot, or dispatch to a handler function (if both path and
@@ -223,9 +225,11 @@ class RequestHandlerInstance(RequestHandler):
def start(self, block=False):
"""
- Start the server. If block is True, the call will not return.
- If block is False, the server will be started on a separate thread that
- can be terminated by a call to .stop()
+ Starts the server.
+
+ If `block` is True, the call will not return. If `block` is False, the
+ server will be started on a separate thread that can be terminated by
+ a call to stop().
"""
self.httpd = EasyServer((self.host, self.port), self.handler_class)
if block:
@@ -236,6 +240,11 @@ def start(self, block=False):
self.server.start()
def stop(self):
+ """
+ Stops the server.
+
+ If the server is not running, this method has no effect.
+ """
if self.httpd:
### FIXME: There is no shutdown() method in Python 2.4...
try:

0 comments on commit e3b5b05

Please sign in to comment.