Merge branch 'collectd-4.9'

[collectd.git] / src / collectd-python.pod

diff --git a/src/collectd-python.pod b/src/collectd-python.pod
index 021a6c5..335f6a9 100644 (file)
--- 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
 
@@ -39,8 +38,8 @@ required.
 Loads the Python plugin I<Plugin>. Unlike most other LoadPlugin lines, this one
 should be a block containing the line "Globals true". This will cause collectd
 to export the name of all objects in the python interpreter for all plugins to
-see. If you don't do this or your platform does not support it, the embeded
-interpreter will start anywa but you won't be able to load certain python
+see. If you don't do this or your platform does not support it, the embedded
+interpreter will start anyway but you won't be able to load certain python
 modules, e.g. "time".
 
 =item B<Encoding> I<Name>
@@ -119,6 +118,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
@@ -211,7 +233,7 @@ and collectd:
 
 =head2 Config
 
-The Config class is an object which keeps the informations provided in the
+The Config class is an object which keeps the information provided in the
 configuration file. The sequence of children keeps one entry for each
 configuration option. Each such entry is another Config instance, which
 may nest further if nested blocks are used.
@@ -631,7 +653,7 @@ dispatched by the python plugin after upgrades.
 =item
 
 This plugin is not compatible with python3. Trying to compile it with python3
-will fail because of the ways string, unicode and bytearray bahavior was
+will fail because of the ways string, unicode and bytearray behavior was
 changed.
 
 =item