From bef7a29e126f4469c734d125c26fbbd13454bd13 Mon Sep 17 00:00:00 2001 From: Jarrod Johnson Date: Tue, 18 Jun 2013 10:00:21 -0400 Subject: [PATCH] Flesh out documentation --- conf.py | 4 +-- index.rst | 5 ++++ ipmi_command.py | 68 +++++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 73 insertions(+), 4 deletions(-) diff --git a/conf.py b/conf.py index 685c6fb7..6855f847 100644 --- a/conf.py +++ b/conf.py @@ -16,7 +16,7 @@ import sys, os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.abspath('.')) # -- General configuration ----------------------------------------------------- @@ -25,7 +25,7 @@ import sys, os # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.pngmath', 'sphinx.ext.viewcode'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.pngmath'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/index.rst b/index.rst index 602e06b9..b0dda3e9 100644 --- a/index.rst +++ b/index.rst @@ -11,6 +11,11 @@ Contents: .. toctree:: :maxdepth: 2 +.. automodule:: ipmi_command + +.. autoclass:: ipmi_command + :members: + Indices and tables ================== diff --git a/ipmi_command.py b/ipmi_command.py index b4c22f7e..a96033a6 100644 --- a/ipmi_command.py +++ b/ipmi_command.py @@ -1,3 +1,7 @@ +# Copyright 2013 IBM Corp. +""" +@author: Jarrod Johnson +""" from ipmi_session import ipmi_session, call_with_optional_args def _raiseorcall(callback,response,args=None): if callback is None: @@ -33,10 +37,30 @@ power_states = { "boot": -1, #not a valid direct boot state, but here for convenience of 'in' statement } -class ipmi_command: +class ipmi_command(object): + """ + Send IPMI commands to BMCs. + + Args: + * bmc (str): hostname or ip address of the BMC + * userid (str): username to use to connec + * password (str): password to connect to the BMC + * kg (str): Optional parameter to use if BMC has a particular Kg configured + """ def __init__(self,bmc,userid,password,kg=None): + """ + Establish a new IPMI session. + """ + #TODO: accept tuples and lists of each parameter for mass operations without pushing the async complexities up the stack self.ipmi_session=ipmi_session(bmc=bmc,userid=userid,password=password,kg=kg) def get_bootdev(self,callback=None,callback_args=None): + """ + Get current boot device override information. + + Args: + * callback (function): optional callback if async behavior desired + * callback_args (tuple): optional arguments to callback + """ self.commandcallback=callback self.commandcallbackargs=callback_args self.ipmi_session.raw_command(netfn=0,command=9,data=(5,0,0),callback=self._got_bootdev) @@ -106,7 +130,20 @@ class ipmi_command: - def set_bootdev(self,bootdev,callback=None,callback_args=None,persist=None,uefiboot=None): + def set_bootdev(self,bootdev,callback=None,callback_args=None,persist=False,uefiboot=False): + """ + Set boot device to use on next reboot + + Args: + * bootdev (str): One of 'pxe', 'hd', 'dvd', 'setup', 'default' + * callback (function): Optional callback for async operation + * callback_args (tuple): Optional arguments for callback (probably needless if callback is an instance method of an object) + * persist (bool): If set, system firmware may persist the boot device request across multiple resets + * uefiboot (bool): If set, request explicitly UEFI style boot. + Example: + ipmicmd.set_bootdev("pxe") + """ + self.commandcallback=callback self.commandcallbackargs=callback_args if bootdev not in boot_devices: @@ -140,6 +177,19 @@ class ipmi_command: self.ipmi_session.raw_command(netfn=0,command=8,data=data,callback=self.commandcallback,callback_args=self.commandcallbackargs) def raw_command(self,netfn,command,data=(),callback=None,callback_args=None): + """ + Send raw ipmi information to BMC + + Args: + * netfn (int): Net function number + * command (int): Command + * data (tuple): Tuple of data bytes to submit + * callback (function): Optional callback for asynchronous mode. + * callback_args (tuple): Optional arguments should callback be in use *and* require more data + + Example: + ipmicmd.raw_command(netfn=0,command=4,data=(5)) + """ response=self.ipmi_session.raw_command(netfn=0,command=1,callback=callback,callback_args=callback_args) if response: #this means there was no callback if 'error' in response: @@ -166,6 +216,20 @@ class ipmi_command: call_with_optional_args(self.commandcallback,self.lastresponse,self.commandcallbackargs) def get_power(self,callback=None,callback_args=None): + """ + Get current power state of the BMC device + + Args: + * callback (function): optional callback to request asynchronous behavior + * callback_args (tuple): optional arguments for callback + + Returns: + If no callback provided, a dict with 'powerstate' member. + Otherwise, returns true and the dict is passed as an argument to the provided callback. + + Example: + ipmicmd.get_power() + """ self.commandcallback=callback self.commandcallbackargs=callback_args self.ipmi_session.raw_command(netfn=0,command=1,callback=self._got_power)