python: utilize uuid.UUID in logging

[elogind.git] / src / python-systemd / journal.py

diff --git a/src/python-systemd/journal.py b/src/python-systemd/journal.py
index 516ca1ab56a3982fa8110aa61205a83bc2c24df0..d610b4767bb8b53f5b2553263a13cdef7a36c17b 100644 (file)
--- a/src/python-systemd/journal.py
+++ b/src/python-systemd/journal.py
@@ -1,8 +1,10 @@
-#  -*- Mode: python; indent-tabs-mode: nil -*- */
+#  -*- Mode: python; coding:utf-8; indent-tabs-mode: nil -*- */
 #
 #  This file is part of systemd.
 #
-#  Copyright 2012 David Strauss
+#  Copyright 2012 David Strauss <david@davidstrauss.net>
+#  Copyright 2012 Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
+#  Copyright 2012 Marti Raudsepp <marti@juffo.org>
 #
 #  systemd is free software; you can redistribute it and/or modify it
 #  under the terms of the GNU Lesser General Public License as published by
@@ -33,24 +35,18 @@ def _make_line(field, value):
 def send(MESSAGE, MESSAGE_ID=None,
          CODE_FILE=None, CODE_LINE=None, CODE_FUNC=None,
          **kwargs):
-        r"""Send a message to journald.
+        r"""Send a message to the journal.
 
         >>> journal.send('Hello world')
         >>> journal.send('Hello, again, world', FIELD2='Greetings!')
         >>> journal.send('Binary message', BINARY=b'\xde\xad\xbe\xef')
 
         Value of the MESSAGE argument will be used for the MESSAGE=
-        field.
+        field. MESSAGE must be a string and will be sent as UTF-8 to
+        the journal.
 
         MESSAGE_ID can be given to uniquely identify the type of
-        message.
-
-        Other parts of the message can be specified as keyword
-        arguments.
-
-        Both MESSAGE and MESSAGE_ID, if present, must be strings, and
-        will be sent as UTF-8 to journal. Other arguments can be
-        bytes, in which case they will be sent as-is to journal.
+        message. It must be a string or a uuid.UUID object.
 
         CODE_LINE, CODE_FILE, and CODE_FUNC can be specified to
         identify the caller. Unless at least on of the three is given,
@@ -58,6 +54,11 @@ def send(MESSAGE, MESSAGE_ID=None,
         send(). CODE_FILE and CODE_FUNC must be strings, CODE_LINE
         must be an integer.
 
+        Additional fields for the journal entry can only be specified
+        as keyword arguments. The payload can be either a string or
+        bytes. A string will be sent as UTF-8, and bytes will be sent
+        as-is to the journal.
+
         Other useful fields include PRIORITY, SYSLOG_FACILITY,
         SYSLOG_IDENTIFIER, SYSLOG_PID.
         """
@@ -65,7 +66,8 @@ def send(MESSAGE, MESSAGE_ID=None,
         args = ['MESSAGE=' + MESSAGE]
 
         if MESSAGE_ID is not None:
-                args.append('MESSAGE_ID=' + MESSAGE_ID)
+                id = getattr(MESSAGE_ID, 'hex', MESSAGE_ID)
+                args.append('MESSAGE_ID=' + id)
 
         if CODE_LINE == CODE_FILE == CODE_FUNC == None:
                 CODE_FILE, CODE_LINE, CODE_FUNC = \
@@ -120,7 +122,7 @@ class JournalHandler(_logging.Handler):
         """Journal handler class for the Python logging framework.
 
         Please see the Python logging module documentation for an
-        overview: http://docs.python.org/library/logging.html
+        overview: http://docs.python.org/library/logging.html.
 
         To create a custom logger whose messages go only to journal:
 
@@ -136,8 +138,9 @@ class JournalHandler(_logging.Handler):
 
         To attach journal MESSAGE_ID, an extra field is supported:
 
-        >>> log.warn("Message with ID",
-        >>>     extra={'MESSAGE_ID': '22bb01335f724c959ac4799627d1cb61'})
+        >>> import uuid
+        >>> mid = uuid.UUID('0123456789ABCDEF0123456789ABCDEF')
+        >>> log.warn("Message with ID", extra={'MESSAGE_ID': mid})
 
         To redirect all logging messages to journal regardless of where
         they come from, attach it to the root logger: