Instance: add a set_logger method

Adds a way to link libVLC log system to a python logging.Logger object.

The logger and log callback is attached to the libVLC Instance object to avoid
the python garbage collector to destroy them too soon.

NOTE: as libVLC log messages are based on a printf + va_list format, we
need to use the standard C `vsnprintf` function with a max fixed size output.

Author: garfvl

generator/templates/header.py

@@ -489,6 +489,20 @@ class EventUnion(ctypes.Union):
         ('new_length',   ctypes.c_longlong),
     ]
 
+def loglevel_to_logging(level):
+    """Converts VLC log level to python logging Log level
+    """
+    if level == LogLevel.DEBUG:
+        return logging.DEBUG
+    elif level == LogLevel.ERROR:
+        return logging.ERROR
+    elif level == LogLevel.NOTICE:
+        return logging.INFO
+    elif level == LogLevel.WARNING:
+        return logging.WARNING
+    else:
+        return logging.INFO
+
 # Generated structs #
 # GENERATED_STRUCTS go here  # see generate.py
 # End of generated structs #

generator/templates/override.py

@@ -7,6 +7,13 @@ class Instance:
       - a list of strings as first parameters
       - the parameters given as the constructor parameters (must be strings)
     """
+
+    # logging related private fields
+    _vsnprintf = None
+    _max_log_message_size = 4096
+    _logger = None
+    _log_handler = None
+
     def __new__(cls, *args):
         if len(args) == 1:
             # Only 1 arg. It is either a C pointer, or an arg string,
@@ -142,6 +149,54 @@ def video_filter_list_get(self):
         """
         return module_description_list(libvlc_video_filter_list_get(self))
 
+    def set_logger(self, logger, max_log_message_size=4096):
+        """Links a logging.Logger object to the libVLC Instance
+
+        Along with the log level and message, each libVLC log will also include
+        The following extra info:
+        - vlc_module: the name of the VLC module (str).
+        - file: the VLC source filename (str).
+        - line: the VLC source file line number (int).
+        These variables can be used in the logger formatter.
+
+        @param logger: a logging.Logger object
+        @param max_log_message_size: defines the maximum size that will be
+               copied from VLC log messages. If you experience truncated log
+               messages, raise this number (default 4096).
+        """
+        # libVLC provides the log message through a printf format + va_list.
+        # Unfortunately, there is no simple way to use a
+        # printf format + va_list in Python outside of the use of a C format
+        # function.
+        # As there is no guarantee to have access to a C `vasprintf`, we use
+        # `vsnprintf` with a log message max size.
+        libc = find_libc()
+        if libc is None:
+            raise Exception("Cannot find a proper standard C library (needed to retrieve log messages)")
+        self._vsnprintf = libc.vsnprintf
+        self._max_log_message_size = max_log_message_size
+        self._logger = logger
+        # The log_handler is meant to be the "real" callback for libvlc_log_set().
+        @CallbackDecorators.LogCb
+        def log_handler(instance, log_level, ctx, fmt, va_list):
+            bufferString = ctypes.create_string_buffer(self._max_log_message_size)
+            self._vsnprintf(bufferString, self._max_log_message_size, fmt,
+                             ctypes.cast(va_list, ctypes.c_void_p))
+            msg = bufferString.value.decode('utf-8')
+            module, file, line = libvlc_log_get_context(ctx)
+            module = module.decode('utf-8')
+            file = file.decode('utf-8')
+            self._logger.log(loglevel_to_logging(LogLevel(log_level)),
+                             msg, extra={"vlc_module": module, "file": file, "line": line})
+        # We need to keep a reference to the log_handler function that persists
+        # after the end of the set_logger.
+        # If we do not do that, there is a (high) chance the python garbage
+        # collector will destroy the callback function and produce segfault in
+        # libVLC.
+        # To avoid that, link the log_handler lifetime to the Instance's one.
+        self._log_handler = log_handler
+        self.log_set(self._log_handler, None)
+
 class Media:
     """Create a new Media instance.