Merge commit 'trenkel/st/python'

Conflicts:

	src/python.c

diff --combined src/collectd-python.pod
index 021a6c5,d832cce..8742104
--- 1/src/collectd-python.pod
--- 2/src/collectd-python.pod
+++ b/src/collectd-python.pod
@@@ -27,8 -27,7 +27,7 @@@ for collectd in Python. This is a lot m
  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
  
@@@ -86,7 -85,7 +85,7 @@@ collectd script as well as from a norma
  B<1.> collectd will try to import the B<readline> module to give you a decent
  way of entering your commands. The daemonized collectd won't do that.
  
 -=item 
 +=item
  
  B<2.> collectd will block I<SIGINT>. Pressing I<Ctrl+C> will usually cause
  collectd to shut down. This would be problematic in an interactive session,
@@@ -96,16 -95,6 +95,16 @@@ exception either
  
  To quit collectd send I<EOF> (press I<Ctrl+D> at the beginning of a new line).
  
 +=item
 +
 +B<3.> collectd handles I<SIGCHLD>. This means that python won't be able to
 +determine the return code of spawned processes with system(), popen() and
 +subprocess. This will result in python not using external programs like less
 +to display help texts. You can override this behavior with the B<PAGER>
 +environment variable, e.g. I<export PAGER=less> before starting collectd.
 +Depending on your version of python this might or might not result in an
 +B<OSError> exception which can be ignored.
 +
  =back
  
  =item E<lt>B<Module> I<Name>E<gt> block
@@@ -119,6 -108,29 +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
@@@ -227,17 -239,17 +249,17 @@@ It has no methods beyond the bare minim
  Data descriptors defined here:
  
  =over 4
 - 
 +
  =item parent
  
  This represents the parent of this node. On the root node
  of the config tree it will be None.
 - 
 +
  =item key
  
  This is the keyword of this item, i.e. the first word of any given line in the
  config file. It will always be a string.
 - 
 +
  =item values
  
  This is a tuple (which might be empty) of all value, i.e. words following the
@@@ -245,7 -257,7 +267,7 @@@ keyword in any given line in the confi
  
  Every item in this tuple will be either a string or a float or a boolean,
  depending on the contents of the configuration file.
 - 
 +
  =item children
  
  This is a tuple of child nodes. For most nodes this will be empty. If this node
@@@ -329,7 -341,7 +351,7 @@@ Methods defined here
  =over 4
  
  =item B<dispatch>([type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.
 -    
 +
  Dispatch this instance to the collectd process. The object has members for each
  of the possible arguments for this method. For a detailed explanation of these
  parameters see the member of the same same.
@@@ -357,7 -369,7 +379,7 @@@ The interval is the timespan in second
  source. This value has to be a positive integer, so you can't submit more than
  one value per second. If this member is set to a non-positive value, the
  default value as specified in the config file will be used (default: 10).
 -    
 +
  If you submit values more often than the specified interval, the average will
  be used. If you submit less values, your graphs will have gaps.
  
@@@ -405,11 -417,11 +427,11 @@@ Methods defined here
  =over 4
  
  =item B<dispatch>([type][, values][, plugin_instance][, type_instance][, plugin][, host][, time][, interval]) -> None.  Dispatch a value list.
 -    
 +
  Dispatch this instance to the collectd process. The object has members for each
  of the possible arguments for this method. For a detailed explanation of these
  parameters see the member of the same same.
 -    
 +
  If you do not submit a parameter the value saved in its member will be
  submitted. If you do provide a parameter it will be used instead, without
  altering the member.