Package: pordego
SummaryPordego provides a simple, pluggable command line tool for executing various static analyses such as
code complexity, dependency analysis, etc.. The goal is to provide a simple, configurable tool that CI software such as Bamboo can call as a step in the build process.The pordego package itself only contains the command line tool (also called “pordego”) and the configuration parser.
The actual analyses are performed by additional packages (see below for a list of known packages)“Pordego” means “gate” in Esperanto. The tool acts as a gate for the CI process and keeps crappy code out.InstallationThe easiest way to install is to run$pipinstallpordegoThis will install the command line tool, which does not do much on it’s own. You will want to install one or more plugins, such as:$pipinstallpordego-complexity$pipinstallpordego-dependencypordego will automatically detect installed pluginsUsageRun the analyses:$pordegorun<pathtoconfigfile>Show the installed plugins:$pordegoshowRun Configuration FileThe pordego tool accepts a single configuration file in yml format.
The configuration file has top level configuration parameters called “analysis” and “output” for configuring the analysis and output plugins respectivly.
The values of “analysis” and “output” are lists of plugin specific configuration. The results of all the confiugured analyses are passed to all the output plugins.The plugin specific configuration must contain a parameter called “plugin_name” which must match the name of one of the instlalled plugins of the section type.
Plugin configurations can optionally specify a parameter called “name” that is passed to the output instead of the plugin name.
This is useful for distinguishing analyses when the sam analysis plugin is run with multiple configurations.Plugins are exectued in the order they are specified in the file (excpet that analyses are always executed before output regardless of the position of the analysis and output configs), and the same plugin can be executed multiple times with different configurationExampleIn this example, one plugin called “myplugin” will be run twice with different configs. The output is sent to stdout. The plugin takes two parameters, one of which is a list.---analysis:-plugin_name:mypluginname:Check config 1myplugin_param_1:config valmyplugin_param_2:-list item 1-list item 2-plugin_name:mypluginname:Check config 2myplugin_param_1:some other valmyplugin_param_2:-list item 7output:-plugin_name:stdoutThe “myplugin” entry point (see below) will be passed a dictionary containing (note that the “plugin_name” parameter is stripped out):{"name":"Check config 1""myplugin_param_1":"config val","myplugin_param_2":["list item 1","list item 2"]}And then it will be executed again with{"name":"Check config 2""myplugin_param_1":"some other val","myplugin_param_2":["list item 7"]}It is also possible to include plugin configurations. For example, in the main config file:---analysis:-include:myplugin_config.ymlThe contents of myplugin_config.yml are:----plugin_name:mypluginname:Check config 1myplugin_param_1:config valmyplugin_param_2:-list item 1-list item 2Note that the included file only has a list of plugins, not the “analysis” tag.
It is possible to recursively include files in included files as well as to have plugin configurations and include statements in the same file.PluginsKnown Analysis PluginsPlugin NameMaintainerDescriptionPython Package NamecomplexityTim TreptowUses the Radon package to check code complexitypordego-complexitydependencyTim TreptowUses the snakefood package to test package dependenciespordego-dependencyKnown Output PluginsPlugin NameMaintainerDescriptionPython Package NamestdoutTim TreptowDumps results to stdoutpordego (builtin)junitTim TreptowDumps results to a junit filepordego (builtin)Analysis Plugin DevelopmentPordego uses package entry points to discover analysis plugins. Plugins packages must export an entrypont called “pordego.analysis”.Example:setup(...entry_points={"pordego.analysis":["myplugin = mypackage.mymodule:some_function"]},...)The function receives a dictionary containing the configuration for the plugin as specified in the file passed to pordegoReturning Errors and SucceessFor simplicty’s sake, the interaction between the pordego tool and the plugins is minimal. There are three states that a plugin can comminucate depending on what exceptions are raised.Don’t raise an exception- pordego assumes that the plugin has passedraise AssertionError- pordego assumes that the condition that the plugin is checking (e.g. code complexity) has failed. Pordego prints out the exception but not a stack trace.raise any other exception- pordego assumes that the plugin or configuration is in error so it prints out a stack trace to aid in debuggingOutput Plugin DevelopmentOutput plugins are specified with the “pordego.output” entry point. The entry point function must take two parameters.The first parameter is a list of plugin outputs.
Each list item is a tuple containing:the analysis name as specified by the “name” parameter in the analysis plugin config, or the plugin name if “name” does not exist.The second parameter is a string containing a failure message or None if the plugin did not fail.The third parameter is a tuple containing exception info (as returned by sys.exc_info()) if there was an error with the test, or None if there was no errorThe second parameter to the output plugin entry point is the plugin configuration as specified in the configuration file