Merge branch 'collectd-4.9' into collectd-4.10

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

diff --git a/src/collectd-python.pod b/src/collectd-python.pod
index cbfd267..267296c 100644 (file)
--- a/src/collectd-python.pod
+++ b/src/collectd-python.pod
@@ -37,8 +37,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
 
@@ -116,6 +115,15 @@ 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.
 
+If you really need to spawn new processes from python you can register an init
+callback and reset the action for SIGCHLD to the default behavior. Please note
+that this I<will> break the exec plugin. Do not even load the exec plugin if
+you intend to do this!
+
+There is an example script located in B<contrib/python/getsigchld.py>  to do
+this. If you import this from I<collectd.conf> SIGCHLD will be handled
+normally and spawning processes from python will work as intended.
+
 =back
 
 =item E<lt>B<Module> I<Name>E<gt> block
@@ -129,6 +137,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
@@ -219,6 +250,28 @@ collectd you're done.
 The following complex types are used to pass values between the Python plugin
 and collectd:
 
+=head2 Signed
+
+The Signed class is just a long. It has all its methods and behaves exactly
+like any other long object. It is used to indicate if an integer was or should
+be stored as a signed or unsigned integer object.
+
+ class Signed(long)
+
+This is a long by another name. Use it in meta data dicts
+to choose the way it is stored in the meta data.
+
+=head2 Unsigned
+
+The Unsigned class is just a long. It has all its methods and behaves exactly
+like any other long object. It is used to indicate if an integer was or should
+be stored as a signed or unsigned integer object.
+
+ class Unsigned(long)
+
+This is a long by another name. Use it in meta data dicts
+to choose the way it is stored in the meta data.
+
 =head2 Config
 
 The Config class is an object which keeps the information provided in the
@@ -382,6 +435,16 @@ If the sequence does not have the correct size upon dispatch a I<RuntimeError>
 exception will be raised. If the content of the sequence is not a number, a
 I<TypeError> exception will be raised.
 
+=item meta
+
+These are the meta data for this Value object.
+It has to be a dictionary of numbers, strings or bools. All keys must be
+strings. I<int> and <long> objects will be dispatched as signed integers unless
+they are between 2**63 and 2**64-1, which will result in a unsigned integer.
+You can force one of these storage classes by using the classes
+B<collectd.Signed> and B<collectd.Unsigned>. A meta object received by a write
+callback will always contain B<Signed> or B<Unsigned> objects.
+
 =back
 
 =head2 Notification
@@ -640,14 +703,8 @@ 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 behavior was
-changed.
-
-=item
-
 Not all aspects of the collectd API are accessible from python. This includes
-but is not limited to meta-data, filters and data sets.
+but is not limited to filters and data sets.
 
 =back