Update to Tornado 3.0

libs/tornado/util.py

@@ -1,4 +1,14 @@
-"""Miscellaneous utility functions."""
+"""Miscellaneous utility functions and classes.
+
+This module is used internally by Tornado.  It is not necessarily expected
+that the functions and classes defined here will be useful to other
+applications, but they are documented here in case they are.
+
+The one public-facing part of this module is the `Configurable` class
+and its `~Configurable.configure` method, which becomes a part of the
+interface of its subclasses, including `.AsyncHTTPClient`, `.IOLoop`,
+and `.Resolver`.
+"""
 
 from __future__ import absolute_import, division, print_function, with_statement
 
@@ -8,7 +18,8 @@ import zlib
 
 
 class ObjectDict(dict):
-    """Makes a dictionary behave like an object."""
+    """Makes a dictionary behave like an object, with attribute-style access.
+    """
     def __getattr__(self, name):
         try:
             return self[name]
@@ -52,6 +63,7 @@ class GzipDecompressor(object):
 def import_object(name):
     """Imports an object by name.
 
+    import_object('x') is equivalent to 'import x'.
     import_object('x.y.z') is equivalent to 'from x.y import z'.
 
     >>> import tornado.escape
@@ -59,10 +71,23 @@ def import_object(name):
     True
     >>> import_object('tornado.escape.utf8') is tornado.escape.utf8
     True
+    >>> import_object('tornado') is tornado
+    True
+    >>> import_object('tornado.missing_module')
+    Traceback (most recent call last):
+        ...
+    ImportError: No module named missing_module
     """
+    if name.count('.') == 0:
+        return __import__(name, None, None)
+
     parts = name.split('.')
     obj = __import__('.'.join(parts[:-1]), None, None, [parts[-1]], 0)
-    return getattr(obj, parts[-1])
+    try:
+        return getattr(obj, parts[-1])
+    except AttributeError:
+        raise ImportError("No module named %s" % parts[-1])
+
 
 # Fake unicode literal support:  Python 3.2 doesn't have the u'' marker for
 # literal strings, and alternative solutions like "from __future__ import
@@ -115,16 +140,17 @@ class Configurable(object):
     The implementation subclass as well as optional keyword arguments to
     its initializer can be set globally at runtime with `configure`.
 
-    By using the constructor as the factory method, the interface looks like
-    a normal class, ``isinstance()`` works as usual, etc.  This pattern
-    is most useful when the choice of implementation is likely to be a
-    global decision (e.g. when epoll is available, always use it instead of
-    select), or when a previously-monolithic class has been split into
-    specialized subclasses.
+    By using the constructor as the factory method, the interface
+    looks like a normal class, `isinstance` works as usual, etc.  This
+    pattern is most useful when the choice of implementation is likely
+    to be a global decision (e.g. when `~select.epoll` is available,
+    always use it instead of `~select.select`), or when a
+    previously-monolithic class has been split into specialized
+    subclasses.
 
     Configurable subclasses must define the class methods
     `configurable_base` and `configurable_default`, and use the instance
-    method `initialize` instead of `__init__`.
+    method `initialize` instead of ``__init__``.
     """
     __impl_class = None
     __impl_kwargs = None
@@ -163,7 +189,7 @@ class Configurable(object):
     def initialize(self):
         """Initialize a `Configurable` subclass instance.
 
-        Configurable classes should use `initialize` instead of `__init__`.
+        Configurable classes should use `initialize` instead of ``__init__``.
         """
 
     @classmethod
@@ -210,8 +236,6 @@ class ArgReplacer(object):
     and similar wrappers.
     """
     def __init__(self, func, name):
-        """Create an ArgReplacer for the named argument to the given function.
-        """
         self.name = name
         try:
             self.arg_pos = inspect.getargspec(func).args.index(self.name)