plugins/python/example_*.py: document returning error string

plugins/python/example_group_plugin.py

@@ -19,6 +19,12 @@ class SudoGroupPlugin(sudo.Plugin):
         sudo.RC.ERROR               -1
         sudo.RC.USAGE_ERROR         -2
 
+    If the plugin encounters an error, instead of just returning sudo.RC.ERROR
+    result code it can also add a message describing the problem.
+    This can be done by raising the special exception:
+        raise sudo.PluginError("Message")
+    This added message will be used by the audit plugins.
+
     If the function returns "None" (for example does not call return), it will
     be considered sudo.RC.OK. If an exception other than sudo.PluginError is
     raised, its backtrace will be shown to the user and the plugin function

plugins/python/example_io_plugin.py

@@ -29,6 +29,12 @@ class SudoIOPlugin(sudo.Plugin):
         sudo.RC.ERROR               -1
         sudo.RC.USAGE_ERROR         -2
 
+    If the plugin encounters an error, instead of just returning sudo.RC.ERROR
+    result code it can also add a message describing the problem.
+    This can be done by raising the special exception:
+        raise sudo.PluginError("Message")
+    This added message will be used by the audit plugins.
+
     If the function returns "None" (for example does not call return), it will
     be considered sudo.RC.OK. If an exception other than sudo.PluginError is
     raised, its backtrace will be shown to the user and the plugin function

plugins/python/example_policy_plugin.py

@@ -12,10 +12,6 @@ from typing import Tuple
 VERSION = 1.0
 
 
-class SudoPluginError(Exception):
-    pass
-
-
 class SudoPolicyPlugin(sudo.Plugin):
     """Example sudo policy plugin
 
@@ -34,6 +30,12 @@ class SudoPolicyPlugin(sudo.Plugin):
         sudo.RC.ERROR               -1
         sudo.RC.USAGE_ERROR         -2
 
+    If the plugin encounters an error, instead of just returning sudo.RC.ERROR
+    result code it can also add a message describing the problem.
+    This can be done by raising the special exception:
+        raise sudo.PluginError("Message")
+    This added message will be used by the audit plugins.
+
     If the function returns "None" (for example does not call return), it will
     be considered sudo.RC.OK. If an exception other than sudo.PluginError is
     raised, its backtrace will be shown to the user and the plugin function
@@ -57,7 +59,7 @@ class SudoPolicyPlugin(sudo.Plugin):
         in the sudo manual ("man sudo").
         """
         if not version.startswith("1."):
-            raise sudo.SudoException(
+            raise sudo.PluginError(
                 "This plugin plugin is not compatible with python plugin"
                 "API version {}".format(version))
 
@@ -71,18 +73,16 @@ class SudoPolicyPlugin(sudo.Plugin):
             sudo.log_error("You are not allowed to run this command!")
             return sudo.RC.REJECT
 
+            raise sudo.PluginError("You are not allowed to run this command!")
+
         # The environment the command will be executed with (we allow any here)
         user_env_out = sudo.options_from_dict(self.user_env) + env_add
 
-        try:
+        command_info_out = sudo.options_from_dict({
-            command_info_out = sudo.options_from_dict({
+            "command": self._find_on_path(cmd),  # Absolute path of command
-                "command": self._find_on_path(cmd),  # Absolute path of command
+            "runas_uid": self._runas_uid(),      # The user id
-                "runas_uid": self._runas_uid(),      # The user id
+            "runas_gid": self._runas_gid(),      # The group id
-                "runas_gid": self._runas_gid(),      # The group id
+        })
-            })
-        except SudoPluginError as error:
-            sudo.log_error(str(error))
-            return sudo.RC.ERROR
 
         return (sudo.RC.ACCEPT, command_info_out, argv, user_env_out)
 
@@ -156,7 +156,8 @@ class SudoPolicyPlugin(sudo.Plugin):
         try:
             return pwd.getpwnam(runas_user)
         except KeyError:
-            raise SudoPluginError("Could not find user '{}'".format(runas_user))
+            raise sudo.PluginError("Could not find user "
+                                   "'{}'".format(runas_user))
 
     def _runas_uid(self):
         return self._runas_pwd().pw_uid
@@ -169,5 +170,5 @@ class SudoPolicyPlugin(sudo.Plugin):
         try:
             return grp.getgrnam(runas_group).gr_gid
         except KeyError:
-            raise SudoPluginError(
+            raise sudo.PluginError(
                 "Could not find group '{}'".format(runas_group))

plugins/python/regress/testdata/check_example_io_plugin_fails_with_python_backtrace.stdout

@@ -1,7 +1,7 @@
 Example sudo python plugin will log to /some/not/writable/directory/sudo.log
 Traceback:
-  File "SRC_DIR/example_io_plugin.py", line 61, in __init__
+  File "SRC_DIR/example_io_plugin.py", line 67, in __init__
     self._open_log_file(path.join(log_path, "sudo.log"))
-  File "SRC_DIR/example_io_plugin.py", line 134, in _open_log_file
+  File "SRC_DIR/example_io_plugin.py", line 140, in _open_log_file
     self._log_file = open(log_path, "a")