From: Sven Trenkel <collectd@semidefinite.de>
Date: Sun, 3 Jan 2010 03:11:45 +0000 (+0100)
Subject: python: Documenting python3 changes.
X-Git-Tag: collectd-4.10.0~76^2
X-Git-Url: https://git.octo.it/?a=commitdiff_plain;h=dedba5c8fb05a1b00b66a8bbc9eab9e0affe551f;p=collectd.git

python: Documenting python3 changes.
---

diff --git a/src/collectd-python.pod b/src/collectd-python.pod
index 9b990b9b..d832cced 100644
--- a/src/collectd-python.pod
+++ b/src/collectd-python.pod
@@ -27,8 +27,7 @@ for collectd in Python. This is a lot more efficient than executing a
 Python-script every time you want to read a value with the C<exec plugin> (see
 L<collectd-exec(5)>) and provides a lot more functionality, too.
 
-Currently only I<Python 2> is supported and at least I<version 2.3> is
-required.
+At least python I<version 2.3> is required.
 
 =head1 CONFIGURATION
 
@@ -109,6 +108,29 @@ The I<name> identifies the callback.
 
 =back
 
+=head1 STRINGS
+
+There are a lot of places where strings are send from collectd to python and
+from python to collectd. How exactly this works depends on wheather byte or
+unicode strings or python2 or python3 are used.
+
+Python2 has I<str>, which is just bytes, and I<unicode>. Python3 has I<str>,
+which is a unicode object, and I<bytes>.
+
+When passing strings from python to collectd all of these object are supported
+in all places, however I<str> should be used if possible. These strings must
+not contain a NUL byte. Ignoring this will result in a I<TypeError> exception.
+If a byte string was used it will be used as is by collectd. If a unicode
+object was used it will be encoded using the default encoding (see above). If
+this is not possible python will raise a I<UnicodeEncodeError> exception.
+
+Wenn passing strings from collectd to python the behavior depends on the
+python version used. Python2 will always receive a I<str> object. Python3 will
+usually receive a I<str> object as well, however the original string will be
+decoded to unicode using the default encoding. If this fails because the
+string is not a valid sequence for this encoding a I<bytes> object will be
+returned instead.
+
 =head1 WRITING YOUR OWN PLUGINS
 
 Writing your own plugins is quite simple. collectd manages plugins by means of