From 55d3be101ebf0821d19b5aadf799e8f65ff16276 Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Sun, 19 Jun 2011 11:23:53 -0700 Subject: [PATCH] Run coverage check and fill in the blanks --- tornado/httpserver.py | 7 +++++++ tornado/ioloop.py | 5 +++++ tornado/iostream.py | 1 + tornado/locale.py | 17 +++++++++++------ tornado/options.py | 1 + tornado/template.py | 4 ++++ tornado/web.py | 3 +++ tornado/wsgi.py | 2 ++ website/sphinx/conf.py | 6 ++++++ website/sphinx/httpserver.rst | 3 +++ website/sphinx/ioloop.rst | 2 ++ website/sphinx/testing.rst | 5 +++++ website/sphinx/web.rst | 1 + 13 files changed, 51 insertions(+), 6 deletions(-) diff --git a/tornado/httpserver.py b/tornado/httpserver.py index dcaff6429..922232f6e 100644 --- a/tornado/httpserver.py +++ b/tornado/httpserver.py @@ -267,6 +267,11 @@ class HTTPServer(object): ioloop.IOLoop.READ) def stop(self): + """Stops listening for new connections. + + Requests currently in progress may still continue after the + server is stopped. + """ for fd, sock in self._sockets.iteritems(): self.io_loop.remove_handler(fd) sock.close() @@ -331,11 +336,13 @@ class HTTPConnection(object): self.stream.read_until(b("\r\n\r\n"), self._header_callback) def write(self, chunk): + """Writes a chunk of output to the stream.""" assert self._request, "Request closed" if not self.stream.closed(): self.stream.write(chunk, self._on_write_complete) def finish(self): + """Finishes the request.""" assert self._request, "Request closed" self._request_finished = True if not self.stream.writing(): diff --git a/tornado/ioloop.py b/tornado/ioloop.py index b92ce1d3f..a08afe22a 100644 --- a/tornado/ioloop.py +++ b/tornado/ioloop.py @@ -155,6 +155,7 @@ class IOLoop(object): @classmethod def initialized(cls): + """Returns true if the singleton instance has been created.""" return hasattr(cls, "_instance") def add_handler(self, fd, handler, events): @@ -428,6 +429,8 @@ class PeriodicCallback(object): """Schedules the given callback to be called periodically. The callback is called every callback_time milliseconds. + + `start` must be called after the PeriodicCallback is created. """ def __init__(self, callback, callback_time, io_loop=None): self.callback = callback @@ -436,11 +439,13 @@ class PeriodicCallback(object): self._running = False def start(self): + """Starts the timer.""" self._running = True timeout = time.time() + self.callback_time / 1000.0 self.io_loop.add_timeout(timeout, self._run) def stop(self): + """Stops the timer.""" self._running = False def _run(self): diff --git a/tornado/iostream.py b/tornado/iostream.py index bce6e633f..d4b59b703 100644 --- a/tornado/iostream.py +++ b/tornado/iostream.py @@ -191,6 +191,7 @@ class IOStream(object): return bool(self._write_buffer) def closed(self): + """Returns true if the stream has been closed.""" return self.socket is None def _handle_events(self, fd, events): diff --git a/tornado/locale.py b/tornado/locale.py index f4b0b630a..5d8def8e8 100644 --- a/tornado/locale.py +++ b/tornado/locale.py @@ -177,6 +177,11 @@ def get_supported_locales(cls): class Locale(object): + """Object representing a locale. + + After calling one of `load_translations` or `load_gettext_translations`, + call `get` or `get_closest` to get a Locale object. + """ @classmethod def get_closest(cls, *locale_codes): """Returns the closest match for the given locale code.""" @@ -235,6 +240,12 @@ class Locale(object): _("Friday"), _("Saturday"), _("Sunday")] def translate(self, message, plural_message=None, count=None): + """Returns the translation for the given message for this locale. + + If plural_message is given, you must also provide count. We return + plural_message when count != 1, and we return the singular form + for the given message when count == 1. + """ raise NotImplementedError() def format_date(self, date, gmt_offset=0, relative=True, shorter=False, @@ -374,12 +385,6 @@ class Locale(object): class CSVLocale(Locale): """Locale implementation using tornado's CSV translation format.""" def translate(self, message, plural_message=None, count=None): - """Returns the translation for the given message for this locale. - - If plural_message is given, you must also provide count. We return - plural_message when count != 1, and we return the singular form - for the given message when count == 1. - """ if plural_message is not None: assert count is not None if count != 1: diff --git a/tornado/options.py b/tornado/options.py index 2a89e51d2..b539e8e1b 100644 --- a/tornado/options.py +++ b/tornado/options.py @@ -306,6 +306,7 @@ class _Option(object): class Error(Exception): + """Exception raised by errors in the options module.""" pass diff --git a/tornado/template.py b/tornado/template.py index 018a954eb..4f9d51b4d 100644 --- a/tornado/template.py +++ b/tornado/template.py @@ -180,6 +180,7 @@ class Template(object): class BaseLoader(object): + """Base class for template loaders.""" def __init__(self, root_directory, autoescape=_DEFAULT_AUTOESCAPE): """Creates a template loader. @@ -194,9 +195,11 @@ class BaseLoader(object): self.templates = {} def reset(self): + """Resets the cache of compiled templates.""" self.templates = {} def resolve_path(self, name, parent_path=None): + """Converts a possibly-relative path to absolute (used internally).""" if parent_path and not parent_path.startswith("<") and \ not parent_path.startswith("/") and \ not name.startswith("/"): @@ -208,6 +211,7 @@ class BaseLoader(object): return name def load(self, name, parent_path=None): + """Loads a template.""" name = self.resolve_path(name, parent_path=parent_path) if name not in self.templates: self.templates[name] = self._create_template(name) diff --git a/tornado/web.py b/tornado/web.py index ec2f2a77c..55989468e 100644 --- a/tornado/web.py +++ b/tornado/web.py @@ -882,6 +882,7 @@ class RequestHandler(object): "application to use %s" % (name, feature)) def reverse_url(self, name, *args): + """Alias for `Application.reverse_url`.""" return self.application.reverse_url(name, *args) def compute_etag(self): @@ -1591,6 +1592,7 @@ class UIModule(object): self.locale = handler.locale def render(self, *args, **kwargs): + """Overridden in subclasses to return this module's output.""" raise NotImplementedError() def embedded_javascript(self): @@ -1618,6 +1620,7 @@ class UIModule(object): return None def render_string(self, path, **kwargs): + """Renders a template and returns it as a string.""" return self.handler.render_string(path, **kwargs) class _linkify(UIModule): diff --git a/tornado/wsgi.py b/tornado/wsgi.py index 6527d30c8..fb8bd4967 100644 --- a/tornado/wsgi.py +++ b/tornado/wsgi.py @@ -235,6 +235,8 @@ class WSGIContainer(object): @staticmethod def environ(request): + """Converts a `tornado.httpserver.HTTPRequest` to a WSGI environment. + """ hostport = request.host.split(":") if len(hostport) == 2: host = hostport[0] diff --git a/website/sphinx/conf.py b/website/sphinx/conf.py index fd7c5db93..1b89d28be 100644 --- a/website/sphinx/conf.py +++ b/website/sphinx/conf.py @@ -33,6 +33,12 @@ coverage_ignore_classes = [ "TemplateModule", "url", ] + +coverage_ignore_functions = [ + # various modules + "doctests", + "main", +] html_static_path = [os.path.abspath("../static")] html_style = "sphinx.css" diff --git a/website/sphinx/httpserver.rst b/website/sphinx/httpserver.rst index b38bb4971..4498d0911 100644 --- a/website/sphinx/httpserver.rst +++ b/website/sphinx/httpserver.rst @@ -11,4 +11,7 @@ HTTP Server ----------- .. autoclass:: HTTPServer + :members: + .. autoclass:: HTTPConnection + :members: diff --git a/website/sphinx/ioloop.rst b/website/sphinx/ioloop.rst index 58d6ec4aa..1ff172319 100644 --- a/website/sphinx/ioloop.rst +++ b/website/sphinx/ioloop.rst @@ -12,6 +12,7 @@ ^^^^^^^^^^^^^^^^^ .. automethod:: IOLoop.instance + .. automethod:: IOLoop.initialized .. automethod:: IOLoop.start .. automethod:: IOLoop.stop .. automethod:: IOLoop.running @@ -30,6 +31,7 @@ .. automethod:: IOLoop.add_timeout .. automethod:: IOLoop.remove_timeout .. autoclass:: PeriodicCallback + :members: Debugging and error handling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/website/sphinx/testing.rst b/website/sphinx/testing.rst index fdb1008d5..5b8758c38 100644 --- a/website/sphinx/testing.rst +++ b/website/sphinx/testing.rst @@ -22,3 +22,8 @@ ----------- .. autofunction:: main + + Helper functions + ---------------- + + .. autofunction:: get_unused_port diff --git a/website/sphinx/web.rst b/website/sphinx/web.rst index 3cd91aec3..fd1af5b87 100644 --- a/website/sphinx/web.rst +++ b/website/sphinx/web.rst @@ -80,6 +80,7 @@ .. automethod:: RequestHandler.get_user_locale .. automethod:: RequestHandler.on_connection_close .. automethod:: RequestHandler.require_setting + .. automethod:: RequestHandler.reverse_url .. autoattribute:: RequestHandler.settings .. automethod:: RequestHandler.static_url .. automethod:: RequestHandler.xsrf_form_html -- 2.47.2