Just like any other programming language, you’ll find it worthwhile to place some code in separate files. For example, you might create a math library that contains your favorite math functions. Rather than copy those functions everywhere, you place them in a separate module and then import that module as needed into an application. In order to make this setup work, you must know how to import modules and use them within the application. The following sections discuss modules and how you work with them in IronPython.
Considering Built-In and External Modules
IronPython uses the concept of built-in and external modules. A built-in module is one that you can access all the time from within the interpreter. For example, the str() function is part of a built-in module. All the code that the interpreter relies upon to perform basic tasks is part of a library of modules that comes with IronPython. In fact, you can see these modules in the Program FilesIronPython 2.6Lib directory of your installation.
An external module is one that you must load separately in order to use. When you create a file of functions you want to use within your application, you must load that module and then provide access to it from within your application. The following sections discuss both built-in and external modules. However, you should consider these sections as an overview because you’ll use modules throughout the book.
Working with the Built-In Modules
As previously mentioned, built-in modules are those that come with IronPython. There are actually two levels of built-in modules: those that are available immediately and those that you have to import first. This second group is part of IronPython, but you don’t always need them, so the interpreter asks that you import them before using them. The following sections discuss both levels of built-in modules.
Considering the Immediately Available Modules
When you start the IronPython interpreter, you get a few functions immediately. These functions are internal to the interpreter itself. To see these functions, you use the dir() function. If you type dir() by itself, you see the top-level modules shown in Figure 2-18.
The three names, __builtins__, __doc__, and __name__, probably don’t tell you very much. (Yes, those are double underscores before and after each module name.) However, all the functions you’ve used so far in the book appear in these three modules. Type dir(__builtins__) and press Enter. Suddenly, you begin seeing function names that you’ve used before, as shown in Figure 2-19. For example, you’ll find the dir() function in the list, as well as raw_input(). These functions help you create basic applications without importing anything else.
It turns out that dir() is an exceptionally helpful function. For example, if you want to discover the methods and attributes that the raw_input object supports, then you type dir(raw_input). Go ahead; give it a try right now.
You may have noticed that the __doc__ attribute keeps popping up in the lists that you display. The __doc__ attribute is also exceptionally important because it provides usage information about the object or function in question. For example, you might want to find out more about raw_input.__format__(), so you’d type print raw_input.__format__.__doc__ and press Enter — the interpreter would
display the help information shown in Figure 2-20. In this case, you see that __format__() requires an object that requires formatting and a string that tells how to format it.
Using sys.builtin_module_names
The modules loaded with the IronPython interpreter are enough to perform very basic tasks, such as those found so far in the book. However, most applications aren’t that simple — you need additional functionality to create something useful. One of the most commonly imported modules is sys. The sys module contains a wealth of extremely useful objects that you’ll need to build most complex applications. In order to use the sys module, you simply type import sys and press Enter. If you use the dir() function at this point, you’ll discover that you now have access to the sys module.
The sys module includes an interesting function, sys.builtin_module_names. You can use this particular function to obtain a list of all of the modules that are built into the interpreter. These are modules that load as part of the interpreter, instead of as separate files. Try it now and you’ll see output similar to that shown in Figure 2-21.
It’s important to note that these are module names and not object or function names. These modules appear as part of the executable, rather than as separate files. You’ll find them with the IronPython interpreter source code. The sys.builtin_module_names function is the only way to obtain this information.
Using External Modules with IronPython
Any application can use external modules. In fact, your IronPython application can have any number of external modules. You can use them as you would any other application. In order to use an external module, you simply import it into the main module. Let’s begin this example with a simple external module named MyStuff.py. Listing 2-3 shows the code for this module.
Listin g 2-3: Creating a simple external function
# Define a simple function that takes
# two arguments.
def SayHello(msg, name):
“Displays a hello message -> SayHello(message, user name)“
print msg, name
return
The SayHello() function is quite simple. All it does is print the message and name onscreen — nothing too complicated. However, it does serve as a useful example of how to work with external modules. Notice the string in the first line. The __doc__ attribute uses this information. After you import the module, you can type print MyStuff.SayHello.__doc__ and press Enter to see this message.
Before you can use SayHello(), you must import it. The main module, External.py, imports the external module as shown in Listing 2-4.
Listin g 2-4: Importing an external module and using it
# Import the file
import MyStuff
# Assign the function to a local variable.
SayHello = MyStuff.SayHello
# Perform the task.
SayHello(‘Hello’, ‘George’)
# Pause the display
raw_input(‘Press any key…’)
The example begins by importing MyStuff. Placing the external module in the same directory as the rest of the application is the best way to ensure the interpreter can find it. When you plan to use a particular function relatively often, you can assign it to a local variable, as shown in the example. This technique lets you call the function without using the module name, as would normally be required. The code calls SayHello() next. It then pauses so you can see the output in Visual Studio. Figure 2-22 shows the results.
