doc: Be more clear about bytes vs. unicode

Signed-off-by: Simon McVittie <smcv@collabora.com>

3 files changed, 84 insertions, 45 deletions

diff --git a/dbus_bindings/bytes.c b/dbus_bindings/bytes.c
index af8188a..26d6016 100644
--- a/dbus_bindings/bytes.c
+++ b/dbus_bindings/bytes.c
@@ -204,8 +204,12 @@ PyTypeObject DBusPyByte_Type = {
 #endif
 
 PyDoc_STRVAR(ByteArray_tp_doc,
-"ByteArray is a subtype of str which can be used when you want an\n"
-"efficient immutable representation of a D-Bus byte array (signature 'ay').\n"
+"ByteArray(str)\n"
+"\n"
+"ByteArray is a subtype of :py:class:`bytes` (an alias for\n"
+":py:class:`str` in Python 2 but a distinct type in Python 3)\n"
+"which can be used when you want an\n"
+"efficient immutable representation of a D-Bus byte array (signature ``ay``).\n"
 "\n"
 "By default, when byte arrays are converted from D-Bus to Python, they\n"
 "come out as a `dbus.Array` of `dbus.Byte`. This is just for symmetry with\n"
diff --git a/dbus_bindings/message-get-args.c b/dbus_bindings/message-get-args.c
index 49670c1..65596d9 100644
--- a/dbus_bindings/message-get-args.c
+++ b/dbus_bindings/message-get-args.c
@@ -45,8 +45,8 @@ char dbus_py_Message_get_args_list__doc__[] = (
 "       If false (default), convert them into a dbus.Array of Bytes.\n"
 #ifndef PY3
 "   `utf8_strings` : bool\n"
-"       If true, return D-Bus strings as Python 8-bit strings (of UTF-8).\n"
-"       If false (default), return D-Bus strings as Python unicode objects.\n"
+"       If true, return D-Bus strings as Python `bytes` objects (in UTF-8).\n"
+"       If false (default), return D-Bus strings as Python `unicode` objects.\n"
 #endif
 "\n"
 "Most of the type mappings should be fairly obvious:\n"
@@ -60,7 +60,7 @@ char dbus_py_Message_get_args_list__doc__[] = (
 "intNN, uintNN    dbus.IntNN, dbus.UIntNN (int or long subclasses)\n"
 "double (d)       dbus.Double\n"
 "string (s)       dbus.String (unicode subclass)\n"
-"                 (or dbus.UTF8String, str subclass, if utf8_strings set)\n"
+"                 (or dbus.UTF8String, bytes subclass, if utf8_strings set)\n"
 "Object path (o)  dbus.ObjectPath (str subclass)\n"
 "dict (a{...})    dbus.Dictionary\n"
 "array (a...)     dbus.Array (list subclass) containing appropriate types\n"
diff --git a/doc/tutorial.txt b/doc/tutorial.txt
index ad0e8a3..cc7a99e 100644
--- a/doc/tutorial.txt
+++ b/doc/tutorial.txt
@@ -178,38 +178,72 @@ Basic types
 
 The following basic data types are supported.
 
-==========================  =============================  =====
-Python type                 converted to D-Bus type        notes
-==========================  =============================  =====
-D-Bus `proxy object`_       ObjectPath (signature 'o')     `(+)`_
-`dbus.Interface`_           ObjectPath (signature 'o')     `(+)`_
-`dbus.service.Object`_      ObjectPath (signature 'o')     `(+)`_
-``dbus.Boolean``            Boolean (signature 'b')        a subclass of ``int``
-``dbus.Byte``               byte (signature 'y')           a subclass of ``int``
-``dbus.Int16``              16-bit signed integer ('n')    a subclass of ``int``
-``dbus.Int32``              32-bit signed integer ('i')    a subclass of ``int``
-``dbus.Int64``              64-bit signed integer ('x')    `(*)`_
-``dbus.UInt16``             16-bit unsigned integer ('q')  a subclass of ``int``
-``dbus.UInt32``             32-bit unsigned integer ('u')  `(*)_`
-``dbus.UInt64``             64-bit unsigned integer ('t')  `(*)_`
-``dbus.Double``             double-precision float ('d')   a subclass of ``float``
-``dbus.ObjectPath``         object path ('o')              a subclass of ``str``
-``dbus.Signature``          signature ('g')                a subclass of ``str``
-``dbus.String``             string ('s')                   a subclass of 
-                                                           ``unicode``
-``dbus.UTF8String``         string ('s')                   a subclass of ``str``
-``bool``                    Boolean ('b')
-``int`` or subclass         32-bit signed integer ('i')
-``long`` or subclass        64-bit signed integer ('x')
-``float`` or subclass       double-precision float ('d')
-``str`` or subclass         string ('s')                   must be valid UTF-8
-``unicode`` or subclass     string ('s')
-==========================  =============================  =====
-
-.. _(*):
-
-Types marked (*) may be a subclass of either ``int`` or ``long``, depending
-on platform.
++-----------------------+---------------------+-----------------------+
+|Python type            |converted to         |notes                  |
+|                       |D-Bus type           |                       |
++=======================+=====================+=======================+
+|D-Bus `proxy object`_  |object path          |`(+)`_                 |
++-----------------------+(signature 'o')      |                       |
+|`dbus.Interface`_      |                     |                       |
++-----------------------+                     |                       |
+|`dbus.service.Object`_ |                     |                       |
++-----------------------+---------------------+-----------------------+
+|``dbus.Boolean``       |Boolean              |a subclass of ``int``  |
+|                       |(signature 'b')      |                       |
++-----------------------+---------------------+                       |
+|``dbus.Byte``          |byte (signature 'y') |                       |
++-----------------------+---------------------+                       |
+|``dbus.Int16``         |16-bit signed        |                       |
+|                       |integer ('n')        |                       |
++-----------------------+---------------------+                       |
+|``dbus.UInt16``        |16-bit unsigned      |                       |
+|                       |integer ('q')        |                       |
++-----------------------+---------------------+                       |
+|``dbus.Int32``         |32-bit signed        |                       |
+|                       |integer ('i')        |                       |
++-----------------------+---------------------+-----------------------+
+|``dbus.UInt32``        |32-bit unsigned      |a subclass of ``long`` |
+|                       |integer ('u')        |(Python 2)             |
++-----------------------+---------------------+                       |
+|``dbus.Int64``         |64-bit signed        |a subclass of ``int``  |
+|                       |integer ('x')        |(Python 3)             |
++-----------------------+---------------------+                       |
+|``dbus.UInt64``        |64-bit unsigned      |                       |
+|                       |integer ('t')        |                       |
++-----------------------+---------------------+-----------------------+
+|``dbus.Double``        |double-precision     |a subclass of ``float``|
+|                       |floating point ('d') |                       |
++-----------------------+---------------------+-----------------------+
+|``dbus.ObjectPath``    |object path ('o')    |a subclass of ``str``  |
++-----------------------+---------------------+                       |
+|``dbus.Signature``     |signature ('g')      |                       |
++-----------------------+---------------------+-----------------------+
+|``dbus.String``        |string ('s')         |a subclass of          |
+|                       |                     |``unicode`` (Python 2) |
+|                       |                     |                       |
+|                       |                     |a subclass of ``str``  |
+|                       |                     |(Python 3)             |
++-----------------------+---------------------+-----------------------+
+|``dbus.UTF8String``    |string ('s')         |a subclass of ``str``, |
+|                       |                     |only in Python 2       |
++-----------------------+---------------------+-----------------------+
+|``bool``               |Boolean ('b')        |                       |
++-----------------------+---------------------+-----------------------+
+|``int`` or subclass    |32-bit signed        |                       |
+|                       |integer ('i')        |                       |
++-----------------------+---------------------+-----------------------+
+|``long`` or subclass   |64-bit signed        | Python 2 only         |
+|                       |integer ('i')        |                       |
++-----------------------+---------------------+-----------------------+
+|``float`` or subclass  |double-precision     |                       |
+|                       |floating point ('d') |                       |
++-----------------------+---------------------+-----------------------+
+|``bytes`` or subclass  |string ('s')         | must be valid UTF-8   |
++-----------------------+---------------------+-----------------------+
+|Python 2 ``unicode``   |string ('s')         |                       |
++-----------------------+                     |                       |
+|Python 3 ``str``       |                     |                       |
++-----------------------+---------------------+-----------------------+
 
 .. _(+):
 
@@ -249,7 +283,7 @@ The signature of an array is 'ax' where 'x' represents the signature of
 one item. For instance, you could also have 'as' (array of strings) or
 'a(ii)' (array of structs each containing two 32-bit integers).
 
-There's also a type ``dbus.ByteArray`` which is a subclass of ``str``,
+There's also a type ``dbus.ByteArray`` which is a subclass of ``bytes``,
 used as a more efficient representation of a D-Bus array of bytes
 (signature 'ay').
 
@@ -305,11 +339,11 @@ If a D-Bus method returns multiple values, the Python proxy method
 will return a tuple containing those values.
 
 If you want strings returned as ``dbus.UTF8String`` (a subclass of
-``str``) pass the keyword parameter ``utf8_strings=True`` to the proxy
-method.
+``bytes``) pass the keyword parameter ``utf8_strings=True`` to the proxy
+method. This mode is only available in Python 2.
 
 If you want byte arrays returned as ``dbus.ByteArray`` (also a
-subclass of ``str`` - in practice, this is often what you want) pass
+subclass of ``bytes`` - in practice, this is often what you want) pass
 the keyword parameter ``byte_arrays=True`` to the proxy method.
 
 .. --------------------------------------------------------------------
@@ -469,10 +503,11 @@ String argument matching
 ------------------------
 
 If there are keyword parameters for the form ``arg``\ *n* where n is a
-small non-negative number, their values must be ``unicode`` objects
-or UTF-8 strings. The handler will only be called if that argument
-of the signal (numbered from zero) is a D-Bus string (in particular,
-not an object-path or a signature) with that value.
+small non-negative number, their values must be Unicode strings (Python
+2 ``unicode`` or Python 3 ``str``) or UTF-8 bytestrings. The handler
+will only be called if that argument of the signal (numbered from zero)
+is a D-Bus string (in particular, not an object-path or a signature)
+with that value.
 
 .. *this comment is to stop the above breaking vim syntax highlighting*