Commits

Marc Abramowitz committed 2de04c3

Revert my changes to documentation/index.rst, which are conflicting with
what's on the tip and need to be updated to reflect my recent changes.

Comments (0)

Files changed (1)

documentation/index.rst

 
 Six provides simple utilities for wrapping over differences between Python 2 and
 Python 3.  It is intended to support codebases that work on both Python 2 and 3
-without modification.
+without modification.  six consists of only one Python file, so it is painless
+to copy into a project.
 
 Six can be downloaded on `PyPi <http://pypi.python.org/pypi/six/>`_.  Its bug
 tracker and code hosting is on `BitBucket <http://bitbucket.org/gutworth/six>`_.
 Package contents
 ----------------
 
+.. data:: PY2
+
+   A boolean indicating if the code is running on Python 2.
+
 .. data:: PY3
 
    A boolean indicating if the code is running on Python 3.
 
 .. data:: MAXSIZE
 
-   The maximum size of a container.  This is equivalent to
-   :data:`py3:sys.maxsize` in Python 2.6 and later (including 3.x).  Note, this
-   is temptingly similar to, but not the same as :data:`py2:sys.maxint` in
-   Python 2.  There is no direct equivalent to :data:`py2:sys.maxint` in Python
-   3 because its integer type has no limits aside from memory.
+   The maximum  size of a  container like :func:`py3:list`  or :func:`py3:dict`.
+   This  is  equivalent  to  :data:`py3:sys.maxsize` in  Python  2.6  and  later
+   (including 3.x).   Note, this is temptingly  similar to, but not  the same as
+   :data:`py2:sys.maxint`  in  Python  2.   There is  no  direct  equivalent  to
+   :data:`py2:sys.maxint` in  Python 3  because its integer  type has  no limits
+   aside from memory.
 
 
 Here's example usage of the module::
    Get the ``self`` of bound method *meth*.
 
 
+.. function:: get_function_closure(func)
+
+   Get the closure (list of cells) associated with *func*.  This is equivalent
+   to ``func.__closure__`` on Python 2.6+ and ``func.func_closure`` on Python
+   2.4 and 2.5.
+
+
 .. function:: get_function_code(func)
 
-   Get the code object associated with *func*.
+   Get the code object associated with *func*.  This is equivalent to
+   ``func.__code__`` on Python 2.6+ and ``func.func_code`` on Python 2.4 and
+   2.5.
 
 
 .. function:: get_function_defaults(func)
 
-   Get the defaults tuple associated with *func*.
+   Get the defaults tuple associated with *func*.  This is equivalent to
+   ``func.__defaults__`` on Python 2.6+ and ``func.func_defaults`` on Python 2.4
+   and 2.5.
+
+
+.. function:: get_function_globals(func)
+
+   Get the globals of *func*.  This is equivalent to ``func.__globals__`` on
+   Python 2.6+ and ``func.func_globals`` on Python 2.4 and 2.5.
 
 
 .. function:: next(it)
    so using six's version is only necessary when supporting Python 3.0 or 3.1.
 
 
-.. function:: iterkeys(dictionary)
+.. function:: iterkeys(dictionary, **kwargs)
 
    Returns an iterator over *dictionary*\'s keys. This replaces
-   ``dictionary.iterkeys()`` on Python 2 and ``dictionary.keys()`` on Python 3.
+   ``dictionary.iterkeys()`` on Python 2 and ``dictionary.keys()`` on
+   Python 3.  *kwargs* are passed through to the underlying method.
 
 
-.. function:: itervalues(dictionary)
+.. function:: itervalues(dictionary, **kwargs)
 
    Returns an iterator over *dictionary*\'s values. This replaces
    ``dictionary.itervalues()`` on Python 2 and ``dictionary.values()`` on
-   Python 3.
+   Python 3.  *kwargs* are passed through to the underlying method.
 
 
-.. function:: iteritems(dictionary)
+.. function:: iteritems(dictionary, **kwargs)
 
    Returns an iterator over *dictionary*\'s items. This replaces
    ``dictionary.iteritems()`` on Python 2 and ``dictionary.items()`` on
-   Python 3.
+   Python 3.  *kwargs* are passed through to the underlying method.
+
+
+.. function:: iterlists(dictionary, **kwargs)
+
+   Calls ``dictionary.iterlists()`` on Python 2 and ``dictionary.lists()`` on
+   Python 3.  No builtin Python mapping type has such a method; this method is
+   intended for use with multi-valued dictionaries like `Werkzeug's
+   <http://werkzeug.pocoo.org/docs/datastructures/#werkzeug.datastructures.MultiDict>`_.
+   *kwargs* are passed through to the underlying method.
+
+
+.. function:: create_bound_method(func, obj)
+
+   Return a method object wrapping *func* and bound to *obj*.  On both Python 2
+   and 3, this will return a :func:`py3:types.MethodType` object.  The reason
+   this wrapper exists is that on Python 2, the ``MethodType`` constructor
+   requires the *obj*'s class to be passed.
 
 
 .. class:: Iterator
    default to the scope of the caller.  If just *globals* is given, it will also
    be used as *locals*.
 
+   .. note::
+
+      Python 3's :func:`py3:exec` doesn't take keyword arguments, so calling
+      :func:`exec` with them should be avoided.
+
 
 .. function:: print_(*args, *, file=sys.stdout, end="\n", sep=" ")
 
    traceback can be specified with the *exc_traceback* parameter.
 
 
-.. function:: with_metaclass(metaclass, base=object)
+.. function:: with_metaclass(metaclass, *bases)
 
-   Create a new class with base class *base* and metaclass *metaclass*.  This is
-   designed to be used in class declarations like this: ::
+   Create a new class with base classes *bases* and metaclass *metaclass*.  This
+   is designed to be used in class declarations like this: ::
 
       from six import with_metaclass
 
    with the latin-1 encoding to bytes.
 
 
-.. note::
+   .. note::
 
       Since all Python versions 2.6 and after support the ``b`` prefix,
       :func:`b`, code without 2.5 support doesn't need :func:`b`.
       ASCII data.
 
 
+.. function:: unichr(c)
+
+   Return the (Unicode) string representing the codepoint *c*.  This is
+   equivalent to :func:`py2:unichr` on Python 2 and :func:`py3:chr` on Python 3.
+
+
 .. function:: int2byte(i)
 
    Converts *i* to a byte.  *i* must be in ``range(0, 256)``.  This is
-   equivalent to :class:`py2:chr` in Python 2 and ``bytes((i,))`` in Python 3.
+   equivalent to :func:`py2:chr` in Python 2 and ``bytes((i,))`` in Python 3.
+
+
+.. function:: byte2int(bs)
+
+   Converts the first byte of *bs* to an integer.  This is equivalent to
+   ``ord(bs[0])`` on Python 2 and ``bs[0]`` on Python 3.
+
+
+.. function:: indexbytes(buf, i)
+
+   Return the byte at index *i* of *buf* as an integer.  This is equivalent to
+   indexing a bytes object in Python 3.
+
+
+.. function:: iterbytes(buf)
+
+   Return an iterator over bytes in *buf* as integers.  This is equivalent to
+   a bytes object iterator in Python 3.
 
 
 .. data:: StringIO
 
 Supported renames:
 
-+------------------------------+-------------------------------------+--------------------------------------+
-| Name                         | Python 2 name                       | Python 3 name                        |
-+==============================+=====================================+=================================-----+
-| ``builtins``                 | :mod:`py2:__builtin__`              | :mod:`py3:builtins`                  |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``configparser``             | :mod:`py2:ConfigParser`             | :mod:`py3:configparser`              |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``copyreg``                  | :mod:`py2:copy_reg`                 | :mod:`py3:copyreg`                   |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``cPickle``                  | :mod:`py2:cPickle`                  | :mod:`py3:pickle`                    |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``cStringIO``                | :func:`py2:cStringIO.StringIO`      | :class:`py3:io.StringIO`             |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``email_mime_multipart``     | :mod:`py2:email.MIMEMultipart`      | :mod:`py3:email.mime.multipart`      |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``email_mime_text``          | :mod:`py2:email.MIMEText`           | :mod:`py3:email.mime.text`           |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``email_mime_base``          | :mod:`py2:email.MIMEBase`           | :mod:`py3:email.mime.base`           |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``filter``                   | :func:`py2:itertools.ifilter`       | :func:`py3:filter`                   |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``http_cookiejar``           | :mod:`py2:cookielib`                | :mod:`py3:http.cookiejar`            |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``http_cookies``             | :mod:`py2:Cookie`                   | :mod:`py3:http.cookies`              |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``html_entities``            | :mod:`py2:htmlentitydefs`           | :mod:`py3:html.entities`             |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``html_parser``              | :mod:`py2:HTMLParser`               | :mod:`py3:html.parser`               |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``http_client``              | :mod:`py2:httplib`                  | :mod:`py3:http.client`               |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``BaseHTTPServer``           | :mod:`py2:BaseHTTPServer`           | :mod:`py3:http.server`               |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``CGIHTTPServer``            | :mod:`py2:CGIHTTPServer`            | :mod:`py3:http.server`               |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``SimpleHTTPServer``         | :mod:`py2:SimpleHTTPServer`         | :mod:`py3:http.server`               |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``input``                    | :func:`py2:raw_input`               | :func:`py3:input`                    |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``map``                      | :func:`py2:itertools.imap`          | :func:`py3:map`                      |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``queue``                    | :mod:`py2:Queue`                    | :mod:`py3:queue`                     |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``reduce``                   | :func:`py2:reduce`                  | :func:`py3:functools.reduce`         |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``reload_module``            | :func:`py2:reload`                  | :func:`py3:imp.reload`               |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``reprlib``                  | :mod:`py2:repr`                     | :mod:`py3:reprlib`                   |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``socketserver``             | :mod:`py2:SocketServer`             | :mod:`py3:socketserver`              |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter``                  | :mod:`py2:Tkinter`                  | :mod:`py3:tkinter`                   |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_dialog``           | :mod:`py2:Dialog`                   | :mod:`py3:tkinter.dialog`            |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_filedialog``       | :mod:`py2:FileDialog`               | :mod:`py3:tkinter.FileDialog`        |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_scrolledtext``     | :mod:`py2:ScrolledText`             | :mod:`py3:tkinter.scolledtext`       |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_simpledialog``     | :mod:`py2:SimpleDialog`             | :mod:`py2:tkinter.simpledialog`      |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_tix``              | :mod:`py2:Tix`                      | :mod:`py3:tkinter.tix`               |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_constants``        | :mod:`py2:Tkconstants`              | :mod:`py3:tkinter.constants`         |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_dnd``              | :mod:`py2:Tkdnd`                    | :mod:`py3:tkinter.dnd`               |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_colorchooser``     | :mod:`py2:tkColorChooser`           | :mod:`py3:tkinter.colorchooser`      |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_commondialog``     | :mod:`py2:tkCommonDialog`           | :mod:`py3:tkinter.commondialog`      |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_tkfiledialog``     | :mod:`py2:tkFileDialog`             | :mod:`py3:tkinter.filedialog`        |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_font``             | :mod:`py2:tkFont`                   | :mod:`py3:tkinter.font`              |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_messagebox``       | :mod:`py2:tkMessageBox`             | :mod:`py3:tkinter.messagebox`        |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``tkinter_tksimpledialog``   | :mod:`py2:tkSimpleDialog`           | :mod:`py3:tkinter.simpledialog`      |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``urllib_robotparser``       | :mod:`py2:robotparser`              | :mod:`py3:urllib.robotparser`        |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``urllib_parse.quote``       | :func:`py2:urllib.quote`            | :func:`py3:urllib.parse.quote`       |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``urllib_parse.quote_plus``  | :func:`py2:urllib.quote_plus`       | :func:`py3:urllib.parse.quote_plus`  |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``urllib_parse.urlparse``    | :func:`py2:urlparse.urlparse`       | :func:`py3:urllib.parse.urlparse`    |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``winreg``                   | :mod:`py2:_winreg`                  | :mod:`py3:winreg`                    |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``xrange``                   | :func:`py2:xrange`                  | :func:`py3:range`                    |
-+------------------------------+-------------------------------------+--------------------------------------+
-| ``zip``                      | :func:`py2:itertools.izip`          | :func:`py3:zip`                      |
-+------------------------------+-------------------------------------+--------------------------------------+
++------------------------------+-------------------------------------+---------------------------------+
+| Name                         | Python 2 name                       | Python 3 name                   |
++==============================+=====================================+=================================+
+| ``builtins``                 | :mod:`py2:__builtin__`              | :mod:`py3:builtins`             |
++------------------------------+-------------------------------------+---------------------------------+
+| ``configparser``             | :mod:`py2:ConfigParser`             | :mod:`py3:configparser`         |
++------------------------------+-------------------------------------+---------------------------------+
+| ``copyreg``                  | :mod:`py2:copy_reg`                 | :mod:`py3:copyreg`              |
++------------------------------+-------------------------------------+---------------------------------+
+| ``cPickle``                  | :mod:`py2:cPickle`                  | :mod:`py3:pickle`               |
++------------------------------+-------------------------------------+---------------------------------+
+| ``cStringIO``                | :func:`py2:cStringIO.StringIO`      | :class:`py3:io.StringIO`        |
++------------------------------+-------------------------------------+---------------------------------+
+| ``email_mime_multipart``     | :mod:`py2:email.MIMEMultipart`      | :mod:`py3:email.mime.multipart` |
++------------------------------+-------------------------------------+---------------------------------+
+| ``email_mime_text``          | :mod:`py2:email.MIMEText`           | :mod:`py3:email.mime.text`      |
++------------------------------+-------------------------------------+---------------------------------+
+| ``email_mime_base``          | :mod:`py2:email.MIMEBase`           | :mod:`py3:email.mime.base`      |
++------------------------------+-------------------------------------+---------------------------------+
+| ``filter``                   | :func:`py2:itertools.ifilter`       | :func:`py3:filter`              |
++------------------------------+-------------------------------------+---------------------------------+
+| ``http_cookiejar``           | :mod:`py2:cookielib`                | :mod:`py3:http.cookiejar`       |
++------------------------------+-------------------------------------+---------------------------------+
+| ``http_cookies``             | :mod:`py2:Cookie`                   | :mod:`py3:http.cookies`         |
++------------------------------+-------------------------------------+---------------------------------+
+| ``html_entities``            | :mod:`py2:htmlentitydefs`           | :mod:`py3:html.entities`        |
++------------------------------+-------------------------------------+---------------------------------+
+| ``html_parser``              | :mod:`py2:HTMLParser`               | :mod:`py3:html.parser`          |
++------------------------------+-------------------------------------+---------------------------------+
+| ``http_client``              | :mod:`py2:httplib`                  | :mod:`py3:http.client`          |
++------------------------------+-------------------------------------+---------------------------------+
+| ``BaseHTTPServer``           | :mod:`py2:BaseHTTPServer`           | :mod:`py3:http.server`          |
++------------------------------+-------------------------------------+---------------------------------+
+| ``CGIHTTPServer``            | :mod:`py2:CGIHTTPServer`            | :mod:`py3:http.server`          |
++------------------------------+-------------------------------------+---------------------------------+
+| ``SimpleHTTPServer``         | :mod:`py2:SimpleHTTPServer`         | :mod:`py3:http.server`          |
++------------------------------+-------------------------------------+---------------------------------+
+| ``input``                    | :func:`py2:raw_input`               | :func:`py3:input`               |
++------------------------------+-------------------------------------+---------------------------------+
+| ``map``                      | :func:`py2:itertools.imap`          | :func:`py3:map`                 |
++------------------------------+-------------------------------------+---------------------------------+
+| ``queue``                    | :mod:`py2:Queue`                    | :mod:`py3:queue`                |
++------------------------------+-------------------------------------+---------------------------------+
+| ``range``                    | :func:`py2:xrange`                  | :func:`py3:range`               |
++------------------------------+-------------------------------------+---------------------------------+
+| ``reduce``                   | :func:`py2:reduce`                  | :func:`py3:functools.reduce`    |
++------------------------------+-------------------------------------+---------------------------------+
+| ``reload_module``            | :func:`py2:reload`                  | :func:`py3:imp.reload`          |
++------------------------------+-------------------------------------+---------------------------------+
+| ``reprlib``                  | :mod:`py2:repr`                     | :mod:`py3:reprlib`              |
++------------------------------+-------------------------------------+---------------------------------+
+| ``socketserver``             | :mod:`py2:SocketServer`             | :mod:`py3:socketserver`         |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter``                  | :mod:`py2:Tkinter`                  | :mod:`py3:tkinter`              |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_dialog``           | :mod:`py2:Dialog`                   | :mod:`py3:tkinter.dialog`       |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_filedialog``       | :mod:`py2:FileDialog`               | :mod:`py3:tkinter.FileDialog`   |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_scrolledtext``     | :mod:`py2:ScrolledText`             | :mod:`py3:tkinter.scolledtext`  |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_simpledialog``     | :mod:`py2:SimpleDialog`             | :mod:`py2:tkinter.simpledialog` |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_tix``              | :mod:`py2:Tix`                      | :mod:`py3:tkinter.tix`          |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_constants``        | :mod:`py2:Tkconstants`              | :mod:`py3:tkinter.constants`    |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_dnd``              | :mod:`py2:Tkdnd`                    | :mod:`py3:tkinter.dnd`          |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_colorchooser``     | :mod:`py2:tkColorChooser`           | :mod:`py3:tkinter.colorchooser` |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_commondialog``     | :mod:`py2:tkCommonDialog`           | :mod:`py3:tkinter.commondialog` |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_tkfiledialog``     | :mod:`py2:tkFileDialog`             | :mod:`py3:tkinter.filedialog`   |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_font``             | :mod:`py2:tkFont`                   | :mod:`py3:tkinter.font`         |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_messagebox``       | :mod:`py2:tkMessageBox`             | :mod:`py3:tkinter.messagebox`   |
++------------------------------+-------------------------------------+---------------------------------+
+| ``tkinter_tksimpledialog``   | :mod:`py2:tkSimpleDialog`           | :mod:`py3:tkinter.simpledialog` |
++------------------------------+-------------------------------------+---------------------------------+
+| ``urllib_robotparser``       | :mod:`py2:robotparser`              | :mod:`py3:urllib.robotparser`   |
++------------------------------+-------------------------------------+---------------------------------+
+| ``winreg``                   | :mod:`py2:_winreg`                  | :mod:`py3:winreg`               |
++------------------------------+-------------------------------------+---------------------------------+
+| ``xrange``                   | :func:`py2:xrange`                  | :func:`py3:range`               |
++------------------------------+-------------------------------------+---------------------------------+
+| ``zip``                      | :func:`py2:itertools.izip`          | :func:`py3:zip`                 |
++------------------------------+-------------------------------------+---------------------------------+
 
 Advanced - Customizing renames
 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<