Basic Jython programming principles

This topic describes some basic Jython language and programming principles, giving you a brief introduction to some concepts used in JLI-script-that-uses-an-external-library-to-execute-a-BLCLI-command.

• Importing native or custom modules
• How suites work
• Documenting Jython Code

Importing native or custom modules

Maintaining all code in a single file is often impractical, especially for large projects. Additionally, you might want to create code modules or classes that you can share with other applications. The Jython import command loads these external code modules into the current script.

On import, an external file is compiled and processed, executing any code that is not in a function. You need to put your import statements on the first lines of a script. Import statements take the following form:

The first import statement imports the bladelogic.cli module, naming the imported object blcli. The second import statement does not import the entire bladelogic.cli module. Instead, it imports only the CLI class from within the bladelogic.cli module. If an external module contains more than one class, function, variable or other such Jython object, the from <module> import <object> statement does not load the entire module, but rather only the specific named external object.

Using the second import statement, you can now access (instantiate) the CLI class directly as a global variable within the script.

Import search path

When an import line tries to import a Jython module, it searches a specific search path. The default Jython import search path is the current directory (.). When you set up your Jython environment (see Installing-and-configuring-Jython), you edited the python.path variable in the Jython registry file to add a value to the default search path — that added value being a path to the location of the BMC Server Automation Jython modules.

The sys module makes the import search path available as a variable of type list by using sys.path. You can add extra values to this path via the Jython append command: sys.path.append('/new/path').

Obviously, the directory containing the bladelogic/cli directories must exist within the sys.path variable for import into a JLI script. If this directory does not exist within the sys.path, copy the directories and files to the directory declared as python.path in the Jython registry file.

How suites work

Anyone accustomed to other high-level programming or scripting languages such as C/C++, Java, or PERL may find Jython's lack of function and class delimiters somewhat disconcerting. Rather than the normal curly brackets used to indicate the beginning and end of a function or class, or an if or for statement, Jython breaks its control structures into suites which consist of a series of lines with similar levels of indentation. For example:

The first suite in this example defines a function named toggle that takes an argument y. Notice the indented if, elif ("else if"), and else control structures. The statements within the toggle function indent one level, and the statements within each control structure indent yet another level. The final line in the function, the return statement, lies outside of the if…else control structure and, therefore, has the same level (1) of indentation.

Each of the if statements in the toggle function has one line within its suite. The if(x==1) statement demonstrates a multi-line suite with no other indentations, unlike the multi-line, multi-suite toggle function shown above it.

Notice the colon ":" at the end of the first line of the if suite and toggle function definition. This colon indicates the beginning of a suite. The Jython interpreter throws an error during compilation if it finds the next line not indented one more than the beginning of the suite. Notice the lack of a syntactical indication of the end of a suite. A suite ends when the compiler finds a line of the same indentation level as the beginning line of the suite.

Although you might find the concept of a suite somewhat non-intuitive, over time you may discover that the suite methodology employed by Jython remains logical and produces more readable code.

Documenting Jython Code

Jython allows for both single line code documentation and multiple line code documentation:

• Single-line documentation has no restrictions. You can place your comments wherever you want by simply prefixing the comment with a # character. The # character comments out all text to the right of it. This lets you temporarily remove the execution of a line of code or make a note that explains the purpose of a particular line of code.

• Multiple-line documentation, aside from its obvious benefits, offers a special functionality as well. Multiple-line documentation, when used as the initial lines of a function, class, or module, becomes available at runtime as <functionName>._doc_.
  
  Use triple quotation marks to denote multiple-line documentation. You can use multiple-line documentation anywhere, with one restriction. Multiple-line documentation must retain the same level of indentation as the suite it documents. For example:

  function foo(bar):
   """This function prints the value of bar.
    This is a test."""
    print bar
  

  When you import a library with the function foo shown in the previous example, you can access the documentation via <module name>.foo._doc_.