11.2 Module Template

The file pyp_template.py is a skeleton that can be used to get started writing a custom module. The first thing you should do is save a copy of pyp_template.py with your working module name; we will use the filename pyp_jbc.py for the following example. You should also fill-in the module header so that it contains your name, e-mail address, etc. The version number of your module does not have to match that of the main PyPedal distribution, and is only used as an aid to the programmer.

###############################################################################
# NAME: pyp_jbc.py
# VERSION: 1.0.0 (16NOVEMBER2005)
# AUTHOR: John B. Cole, PhD (jcole@aipl.arsusda.gov)
# LICENSE: LGPL
###############################################################################
# FUNCTIONS:
#     get_color_32()
#     color_pedigree()
#     draw_colored_pedigree()
###############################################################################

The imports section of the template includes import statements for all of the standard PyPedal modules. There's no harm in including all of them in your module, but it's good practice to include only the modules you need. You should always include the logging module because it's needed for communicating with the log file. For pyp_jbc I am including only the pyp_graphics, pyp_network, and pyp_utils modules.

##
# pyp_jbc provides tools for enhanced pedigree drawing.
##
import logging
from PyPedal import pyp_graphics
from PyPedal import pyp_network
from PyPedal import pyp_utils

There is a very sketchy function prototype included in the template. It is probably enough for you to get started if you have a little experience programming in Python. If you don't have any experience programming in Python you should be able to get up-and-running with a little trial-and-error and some study of PyPedal source. You should always write a comment block similar to that attached to yourFunctionName() for each of your functions. This comment block is recognized by PythonDoc, a tool for automatically generating program documentation. Parameters are the inputs that you send to a function, return is a description of the function's output, and defreturn is the type of output that is returned, such as a list, dictionary, integer, or tuple.

##
# yourFunctionName() <description of what function does>
# @param <parameter_name> <parameter description>
# @return <description of returned value(s)
# @defreturn <type of returned data, e.g., 'dictionary' or 'list'>
def yourFunctionName(pedobj):
    try:
        # Do something here
        logging.info('pyp_template/yourFunctionName() did something.')
        # return a value/dictionary/etc.
    except:
        logging.error('pyp_template/yourFunctionName() encountered a problem.')
        return 0

See About this document... for information on suggesting changes.