This tiny module is to make your comments in the source code a bit more useful, to be displayed as help messages. With the HelpMaker, once you finish writing/updating the comments, the help messages are ready. One more reason to work on your comments =)
Python, 118 lines
Download
Copy to clipboard1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 | """ HelpMaker: Builds help message from comments in the code.
"""
"""
There are two types of help messages:
the general help,
and the specific helps to corresponding functions/commands.
The general help message is the first comment in the .py file,
wrapped by the triple-double-quotes.
The general help describes what the .py file is about, or gives a brief
introduction of the module.
A specific help message is wrapped by the triple-double-quotes, and has only
one word (no space in between) in the first line of the comment.
A specific help explains/illustrates the usage of a function/command.
The specific helps are stored in an internal dictionary. The only-one-word
in the first line of comment serves as the key to the help message in the
internal dictionary.
"""
import sys
import re
class Phase:
HAVE_NOTHING = 0
HAVE_GENERAL_MSG = 1
HAVE_SPECIFIC_MSG = 2
class HelpMaker:
def __init__(self, filename):
""" construct function
construction function that takes the name of the .py file.
The function screens the entire file and gets ready to
display the comments as help messages.
"""
try:
with open(filename) as pyfile:
self._comment_head = re.compile(r"""^\s*\"{3}""")
self._key_word = re.compile(r"""^\s*\"{3}\s*\S{1,}\s*\Z""")
self._phase = Phase.HAVE_NOTHING
self._is_comment = False
self._general_help = ''
self._specific_help = dict()
self._tmp_key = ''
self._tmp_msg = ''
self._tmp_index = 0
for line in pyfile:
if self._phase is Phase.HAVE_NOTHING:
self._general_help_filter(line)
elif self._phase is Phase.HAVE_GENERAL_MSG:
self._specific_help_filter(line)
except IOError:
print('Could not find the file: %s'%filename)
""" available_help
Generate all the items with help messages
"""
def available_help(self):
return self._specific_help.keys()
def show_help(self, showitem = None):
""" show_help
Without any input this funtion shows general common help message.
When the showitem is given, the corresponding help message will be
displayed, if exists.
"""
if showitem is None:
print(self._general_help)
else:
try:
print(self._specific_help[showitem])
except KeyError:
print('No help on %s available'%showitem)
def _general_help_filter(self, line):
""" helper function that finds out the general help message
"""
if self._comment_head.search(line) is not None:
self._tmp_indent = line.find('"') + 3
self._is_comment = not self._is_comment
if self._is_comment is True:
self._general_help += line[self._tmp_indent:]
if self._general_help is not '' and self._is_comment is False:
self._phase = Phase.HAVE_GENERAL_MSG
def _specific_help_filter(self, line):
""" helper function that finds out the speific help message
"""
if self._key_word.search(line) is not None:
self._tmp_indent = line.find('"') + 3
self._tmp_key = line[self._tmp_indent:].strip()
self._is_comment = True
return
if self._is_comment is True:
if self._comment_head.search(line) is not None:
self._specific_help[self._tmp_key] = self._tmp_msg
self._tmp_msg = ''
self._is_comment = False
else:
self._tmp_msg += line[self._tmp_indent:]
if __name__ == '__main__':
hm = HelpMaker(sys.argv[0])
print('General help of HelpMaker:')
hm.show_help()
print("Functions with help message:")
for item in hm.available_help():
print(item)
print('')
print('Specific help of HelpMaker:show_help():')
hm.show_help('show_help')
print('Specific help of a nonexist function:')
hm.show_help('nonsense')
|
