Updated documentation of new callback data for CALLBACK_TOO_MANY_MATC…

…HES (VirusTotal#1519)

Co-authored-by: malvidin <[email protected]>

docs/capi.rst

@@ -254,10 +254,10 @@ CALLBACK_MSG_MODULE_IMPORTED. When this happens ``message_data`` points to a
 :c:type:`YR_OBJECT_STRUCTURE` structure. This structure contains all the
 information provided by the module about the currently scanned file.
 
-If during the scan a string hits the maximum number of matches your callback
-will be called once with the CALLBACK_MSG_TOO_MANY_MATCHES. When this happens,
-`message_data` is a `YR_STRING*` which points to the string which caused the
-warning. If your callback returns CALLBACK_CONTINUE the string will be disabled
+If during the scan a string hits the maximum number of matches, your callback
+will be called once with the ``CALLBACK_MSG_TOO_MANY_MATCHES``. When this happens,
+``message_data`` is a ``YR_STRING*`` which points to the string which caused the
+warning. If your callback returns ``CALLBACK_CONTINUE``, the string will be disabled
 and scanning will continue, otherwise scanning will be halted.
 
 Lastly, the callback function is also called with the

docs/yarapython.rst

@@ -277,6 +277,12 @@ Possible values for the type are::
 
   CALLBACK_TOO_MANY_MATCHES
 
+Contents of the callback message depend on the type of the callback.
+
+For ``CALLBACK_TOO_MANY_MATCHES``, the message is a named tuple containing
+3 items: ``namespace``, ``rule`` and ``string``. All contain string
+identifiers.
+
 Here is an example:
 
 .. code-block:: python
@@ -285,7 +291,7 @@ Here is an example:
 
   def warnings_callback(warning_type, message):
     if warning_type == yara.CALLBACK_TOO_MANY_MATCHES:
-        print(message)
+        print(f"namespace:'{message.namespace}' rule:'{message.rule}' string:'{message.string}'")
     return yara.CALLBACK_CONTINUE
 
   matches = rules.match('/foo/bar/my_file', warnings_callback=warnings_callback)