I was showing func off to a coworker the other day when a question came up ...
"This is pretty cool ... where can I get the Code/API documentation?"
The obvious answer is to look at the code ... but why not use
something like epydoc? In past projects it has been helpful and
generally improved the documentation in the code.
You can see what it looks like rendered for a module at
http://stevemilner.org/tmp/html/.
I'm also attaching a diff to show what it looks like in code (though
I'm being more verbose with self than need be ... as well as types
...)
On the good side we *should* have documentation of modules and epydoc
would document it in the code as well as generated html api
documentation.
On the bad side it does add more lines to the docstrings which could
be seen as adding too much to the noise to code ratio.
Also epydoc can be used without the extra @tags it's just less verbose
documentation.
Any objections, better ideas or questions about my sanity?
--
"An organisation that treats its programmers as morons will soon have
programmers that are willing and able to act like morons only."
-Bjarne Stroustrup
From 48a8ef60686736d51010e0291669bc992665feee Mon Sep 17 00:00:00 2001
From: Steve 'Ashcrow' Milner <stevem@xxxxxxxxxxxx>
Date: Tue, 22 Jan 2008 20:26:05 -0500
Subject: [PATCH] Added epydoc to network test.
---
func/minion/modules/networktest.py | 161 +++++++++++++++++++++++++++++++++++-
1 files changed, 158 insertions(+), 3 deletions(-)
diff --git a/func/minion/modules/networktest.py b/func/minion/modules/networktest.py
index 0e6fbb2..b8322b4 100644
--- a/func/minion/modules/networktest.py
+++ b/func/minion/modules/networktest.py
@@ -15,30 +15,148 @@ from codes import FuncException
import sub_process
class NetworkTest(func_module.FuncModule):
+ """
+ Various network related commands.
+ @ivar version: The version of the module.
+ @ivar api_version: The version of the API in use.
+ @ivar description: The description of this module.
+ """
version = "0.0.1"
api_version = "0.0.1"
description = "Defines various network testing tools."
def ping(self, *args):
+ """
+ Attempt to ping a host from a minion.
+
+ Code
+ ====
+ >>> client.networktest.ping('-c', '3', 'example.com')
+
+ Shell
+ =====
+ Assuming you have proper access::
+ $ func tachikoman call networktest ping redhat.com -c 2
+
+ @raise FuncException: Raised if a -c param is not passed in.
+
+ @param self: Internal NetworkTest object.
+ @type self: NetworkTest
+
+ @param args: All arguments to pass through to ping.
+ @type args: tuple
+
+ @return: Command output split by newlines.
+ @rtype: list
+ """
if '-c' not in args:
raise(FuncException("You must define a count with -c!"))
return self.__run_command('/bin/ping', self.__args_to_list(args))
def netstat(self, *args):
+ """
+ Run netstat on the minion.
+
+ Code
+ ====
+ >>> client.networktest.netstat()
+
+ Shell
+ =====
+ Assuming you have proper access::
+ $ func tachikoman call networktest netstat
+
+ @param self: Internal NetworkTest object.
+ @type self: NetworkTest
+
+ @param args: All arguments to pass through to netstat.
+ @type args: tuple
+
+ @return: Command output split by newlines.
+ @rtype: list
+ """
return self.__run_command('/bin/netstat',
self.__args_to_list(args))
def traceroute(self, *args):
- return self.__run_command('/bin/traceroute',
+ """
+ Run netstat on the traceroute.
+
+
+ Code
+ ====
+ >>> client.networktest.traceroute('example.com')
+
+ Shell
+ =====
+ Assuming you have proper access::
+ $ func tachikoman call networktest traceroute example.com
+
+ @param self: Internal NetworkTest object.
+ @type self: NetworkTest
+
+ @param args: All arguments to pass through to traceroute.
+ @type args: tuple
+
+ @return: Command output split by newlines.
+ @rtype: list
+ """
+ return self.__run_command('/bin/traceroute',
self.__args_to_list(args))
def dig(self, *args):
- return self.__run_command('/usr/bin/dig',
+ """
+ Run netstat on the minion.
+
+ Code
+ ====
+ >>> client.networktest.dig('example.com')
+
+ Shell
+ =====
+ Assuming you have proper access::
+ $ func tachikoman call networktest dig example.com
+
+ @param self: Internal NetworkTest object.
+ @type self: NetworkTest
+
+ @param args: All arguments to pass through to dig.
+ @type args: tuple
+
+ @return: Command output split by newlines.
+ @rtype: list
+ """
+ return self.__run_command('/usr/bin/dig',
self.__args_to_list(args))
def isportopen(self, host, port):
- # FIXME: the return api here needs some work... -akl
+ """
+ Check to see if a port is accessible from a minion.
+
+ Code
+ ====
+ >>> client.networktest.isportopen('localhost', '22')
+
+ Shell
+ =====
+ Assuming you have proper access::
+ $ func tachikoman call networktest isportopen localhost 22
+
+ @param self: Internal NetworkTest object.
+ @type self: NetworkTest
+
+ @param host: The host whose port you want to check.
+ @type host: str
+
+ @param port: The port to check.
+ @type port: str
+
+ @return: Return code follwed by message or a tuple of information.
+ @rtype: list
+
+ @todo: the return api here needs some work... -akl
+ """
import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
timeout = 3.0
@@ -56,9 +174,46 @@ class NetworkTest(func_module.FuncModule):
return [0, "connection to %s:%s succeeded" % (host, port)]
def __args_to_list(self, args):
+ """
+ Internal list maker.
+
+ Code
+ ====
+ >>> self.__args_to_list(('-c', '2', 'example.com'))
+ ['-c', '2', 'example.com']
+
+ @param self: Internal NetworkTest object.
+ @type self: NetworkTest
+
+ @param args: A tuple of arguments.
+ @type args: tuple
+
+ @return: List version of the tuple
+ @rtype: list
+ """
return [arg for arg in args]
def __run_command(self, command, opts=[]):
+ """
+ An easy way to run a command inside the module.
+
+ Code
+ ====
+ >>> self.__run_command('/bin/ls', ['/tmp/'])
+ [...]
+
+ @param self: Internal NetworkTest object.
+ @type self: NetworkTest
+
+ @param command: The full path to the command to run.
+ @type command: str
+
+ @param opts: Options to pass to the command.
+ @type opts: list
+
+ @return: The response of the command split by newlines.
+ @rtype: list
+ """
full_cmd = [command] + opts
cmd = sub_process.Popen(full_cmd, stdout=sub_process.PIPE)
return [line for line in cmd.communicate()[0].split('\n')]
--
1.5.3.7
_______________________________________________
Func-list mailing list
Func-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/func-list
