A system profiler/auditor written in Python that supports custom plugins and a custom profiler. Custom plugins can superscede builtin plugins to allow for a great deal of flexibility. Plugins follow naming conventions for ease of use.
Copyright 2011 Mark LaPerriere
Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
An example of running pyHai with all the default parameters and using the builtin auditing plugins.:
>>> from pyhai import pyhai
>>> pyhai.audit()
This will run all the builtin auditing plugins and return a dictionary object with detailed information about the local system. The dictionary keys are the lowercase names of the plugin files (minus the ‘.py’ file name extension) and the contents are the results of the plugin’s run.
An example of running pyHai with a single additional plugin path. The builtin plugins will be run before the “custom” plugins found in the path supplied.:
>>> from pyhai import pyhai
>>> pyhai.audit('/path/to/my/plugins')
This will return the dictionary of results of the auditing run including builtin plugins and the custom plugins found in the path provided.
An example of running pyHai with a number of additional plugin paths.:
>>> from pyhai import pyhai
>>> pyhai.audit(['/path/to/my/plugins', '/path/to/some/other/plugins'])
This will return the dictionary of results of the auditing run including builtin plugins and all custom plugins.
Important
When using custom plugins, if you name your plugin the same as one of the builtin plugins, your plugin will superscede the builtin plugin. This allows users to provide their own plugins, but could cause confusion if it is unexcpected. For instance, if you write a plugin called ‘environment’, the builtin plugin - environment - will not run and your plugin will be run instead.
An example of running pyHai with a single custom plugin directory and without running the builtin plugins.:
>>> from pyhai import pyhai
>>> pyhai.audit('/path/to/my/plugins', enable_default_plugins=False)
Important
If you don’t supply custom plugin path(s) and try to disable builtin plugins, an exception is raised - nothing to do.
This section describes how to create your own auditing plugins and using a custom profiler.
Plugin files must use all lowercase letters and seperate words with underscores.:
super_cool_widget.py
Plugin class names use CamelCase letters and reflect the plugin file name.:
class SuperCoolWidget(AuditorPlugin):
pass
Plugin classes have a single required method: run. This method will be called as part of the default run.
We’ll use the builtin “environment” plugin as an example. You can check out the source code in the builtin plugins for additional reference. Example Custom Plugin:
# file: environment.py
# import the auditing plugin base class
from pyhai import AuditorPlugin
# name your plugin the same as your file name.
class EnvironmentPlugin(AuditorPlugin):
# provide a run method
def run(self, *args, **kwargs):
return dict(os.environ)
There are two hooks provided in the auditing base class. If you provide them in your custom auditing class, pyHai will execute them as such.
The before method will be called before the run method is called. The results of the before method will passed along to the run method as a keyword argument: before_results.
The after method will be called after the run method is called. The results of the run are available in the plugin class by calling self._get_results().
Simply import the profiler base class and extend it. There are two methods that need to be supplied by the custom profile class: profile, and system. The profile method needs to return a dictionary with some basic information about the system running pyHai to help auditing plugins make desicions about how to audit.:
from pyhai.profilers.base import ProfilerBase
class DefaultProfiler(ProfilerBase):
def profile(self):
# return a simple dictionary with basic information about the local system
# this dictionary will be provided to all auditing plugins
pass
def system(self):
# return a string representing the type of system pyHai is running on
# for example the default profiler returns the results of a call to the system method of the builtin
# python module platform
pass