Python boasts a rich set of built-in datatypes that you can use without importing any modules. Most of these, with the exception of the set that we introduce shortly, have syntax for including them within your code. To understand the examples in this book or to write Python yourself, you’re going to need to recognize them. Table 2.1 contains a guide to all the basic datatypes and their syntaxes.

'hello world'
"also hello world"
"""A triple quoted
multiline string"""
'''Another triple
quoted multiline string'''

u'A Unicode string'
u"Another Unicode string"
u"""Yet another Unicode
string."""

3
-3

9L
9999999999999999999999L

0.0
-3.1
2e100
2.765e-10

2 + 3j
8j

[]
[1, 2, 3, 4]
[1, "a", 3.0]

()
(1,)
(1, 2, 3, 4)

{}
{'key': 'value',
'key2': 'value2'}

set()
set([1, 2, 3, 4])

True
False

This table isn’t exhaustive. For example, it doesn’t include things like the slightly exotic frozenset or the built-in exceptions.

In addition to the information in the table, you need to know some additional things about these datatypes.

'hello	world
'

u'This is a Unicode string'

>>> string = 'Hello World'
>>> string.ToUpper()
Traceback (most recent call last):
AttributeError: 'str' object has no attribute 'ToUpper'

>>> import clr
>>> string.ToUpper()
'HELLO WORLD'

>>> import System
>>> System.String
<type 'str'>
>>> System.String is str
True

>>> 9/2
4
>>> 9/2.0
4.5

>>> a = [1, 2, 3, 4]
>>> a[0]
1
>>> a[-1]
4

>>> a = [0, 1, 2, 3]
>>> a[4]
Traceback (most recent call last):
IndexError: index out of range: 4
>>> a[-5]
Traceback (most recent call last):
IndexError: index out of range: -5

>>> a = [1, 2, 3, 4]
>>> a[0] = 'a'
>>> a
['a', 2, 3, 4]
>>> a[-1] = 'b'
>>> a
['a', 2, 3, 'b']

>>> del a[0]

>>> x = {'Key 1': 'Value number 1',
... 'Key 2': 'Value number 2'}
>>> x['Key 1']
'Value number 1'
>>> x['Key 2']
'Value number 2'

>>> x = {'Key 1': 'Value number 1',
... 'Key 2': 'Value number 2'}
>>> x['Key 3']
Traceback (most recent call last):
KeyError: 'Key 3'

>>> a = {}
>>> a[(0, 1)] = 'Get the point?'
>>> a
{(0, 1): 'Get the point?'}
>>> a[(0, 1)] = 'something else'
>>> a
{(0, 1): 'something else'}
>>> del a[(0, 1)]
>>> a
{}

>>> x = set([1, 2, 3, 4])
>>> 5 in x
False
>>> 2 in x
True

>>> 1 == 2
False
>>> 3 < 4
True

>>> x = {}
>>> if not x:
...   print 'Not this one'
...
Not this one
>>> y = [1]
>>> if y:
...    print 'This one'
...
This one

Although Python supports several different programming paradigms, it’s built on solid object-oriented principles. A natural consequence of this is that everything in Python is an object.

If you’ve programmed in C#, you’ll be used to the difference between value types and reference types. When you pass a value type, you’re passing the value (the data) itself. When you pass a reference type, you’re passing a reference to the object rather than the object itself. From this reference, you can access the properties of the object, call its methods, and so on.

With Python, there are only reference types. This rule is straightforward, but it does have some consequences that can be surprising for programmers new to Python.

Python draws an important distinction between objects and the names you use to refer to them. When you assign a value to a variable, you’re creating a name bound to an object. If you later assign a new value to the variable, you’re removing the reference to the original object and rebinding the name to a new object.

>>> a = 3    
>>> b = a      
>>> a = 6    
>>> b      
3

This is illustrated in figure 2.3.

Figure 2.3. Names bound to objects by assignment statements

The effect of , shown in , can confuse new programmers. The name b is bound to the object pointed to by the name a (which is an integer with the value of three ). New programmers might expect the line b = a to cause the variable b to have the same value as the variable a, so that when a is changed, b ought to change as well. Instead, when a = 6 is executed, the name a is rebound to point to a different object , whereas the name b remains bound to the original one .

A more succinct way of saying this is that Python doesn’t really have variables. Python has objects and names that reference objects. Understanding this is central to understanding Python. If you already understand the difference between reference and value types, then this is probably pretty intuitive to you. If you don’t feel you understand it yet, don’t worry about it for now; it should become clearer as you use Python more.

Although Python doesn’t have the reference type/value type distinction, it does draw a distinction between mutable and immutable datatypes.

You’ve already seen that reassigning a name points it to a new object. Often you want to change or update the value a name points at; this might be incrementally building a string, adding members to a list, or updating a counter.

Some objects can be changed in place without having to create a new object. These are mutable objects. Others can’t be changed once they’ve been created. These are immutable objects.

As you might expect, the container types list and dict (dictionaries) are mutable. Adding new members doesn’t create a new object, but modifies the object in place. Tuples are immutable. Attempting to change or delete members, or add new ones, will raise an exception; but, tuples can contain mutable objects.

Strings and the number types are also immutable. Operations that change values don’t change the underlying object but create new ones.

>>> a = b = 'a string'
>>> a += ' which is getting bigger'
>>> a
'a string which is getting bigger'
>>> b
'a string'

Here the in-place operator += is merely syntactic sugar^[10] for a = a + 'which is getting bigger'. The name a is re-bound to a new string which is formed by adding 'a string' to 'which is getting bigger'. The name b remains bound to the string 'a string'.

The last two sections might seem confusing at first; but, once you’ve grasped this, you’ve understood a lot about Python. Here’s a simple test:

>>> a = []
>>> b = [a]
>>> a.append(1)

Can you predict what the object pointed to by the name b contains?^[11]

At last you’ve reached the end of the section devoted to the basic datatypes. It’s time to move from the mortar to the bricks. Functions and classes contain code, which uses the basic types. This code will be comprised of statements and expressions, so the first part of the section on basic constructs will cover these.

Python draws a distinction between statements and expressions. This wouldn’t be true in a purely functional programming language where everything is an expression.

Statements are actions such as printing, assigning a value, or raising an exception. A statement doesn’t return a value, so you can’t get away with the following:

>>> x = print 3
Traceback (most recent call last):
SyntaxError: unexpected token print (<stdin>, line 1)

Statements can’t be compounded together. You can do multiple assignments as a single statement.

>>> x = y = 10

Statements other than assignment use a Python keyword. These keywords are reserved words, and you can’t use them as variable names. You can see the full list of reserved keywords (not all of which form statements) at http://docs.python.org/ref/keywords.html.

Python follows the normal BODMAS^[12] precedence rules for operators in expressions. The best reference I could find on Python operators is from A Byte of Python by CH Swaroop at http://www.swaroopch.com/notes/Python_en:Operators_and_Expressions#Operator_Precedence.

Parentheses not only group parts of an expression together, but also allow you to break unwieldy expressions over multiple lines.

>>> (1 + 2 + 3 + 4 + 5 + 6 + 7 +
... 8 + 9 + 10)
55

Python uses keywords and syntax for its most basic elements that will be familiar to most programmers, and are easy to understand even if they aren’t familiar. The most fundamental of these are conditionals and loops.

Very often through the course of a program you’ll need it to take different actions depending on some condition—maybe finding the terminating condition of an algorithm, or responding to user input. The conditional statement in Python uses the if keyword.

Every statement that starts a new block of code must be terminated with a colon. Indented code following the if statement will only be executed if the condition evaluates to True. As soon as your code is dedented, execution continues normally. if allows you to provide multiple branches for different conditions; a final branch will be executed if none of the other conditions have been met. elif is used for multiple branches, and else for the final branch.

>>> x = -9
>>> if x == 0:
...    print 'x equals zero'
... elif x > 0:
...    print 'x is positive'
... else:
...    print 'x is negative'
...
'x is negative'

Another conditional in Python is while, which is also a loop. The while loop repeats a block of code until a condition is met, or until you explicitly break out of the loop.

>>> a = 0
>>> while a < 2:
...    print a
...    a += 1
...
0
1

If you want to terminate the loop early, you can use the break statement. With an optional else clause, you can tell whether a loop completed normally.

>>> a = 0
>>> while a < 6:
...   print a
...   if a >= 2:
...      break
... else:
...    print 'Loop terminated normally'
0
1
2

The second kind of loop in Python is the for loop. It’s used to iterate over a sequence (or any iterable), and allows you to perform an operation on every member.

>>> sequence = [1, 2, 3]
>>> for entry in sequence:
...    print entry
...
1
2
3

Although it’s theoretically possible to write a program using only the constructs we’ve examined so far, it would be an extremely ugly program. To reuse blocks of code (and write well-structured, modular programs), you need functions and classes.

Functions allow you to break code down into smaller units and make programs more readable. Functions take values as arguments and return values, but they may also be used for their side effects, such as writing to the filesystem or a database.

Like other aspects of Python, the syntax for functions is straightforward. It’s shown in figure 2.4.

Figure 2.4. Function definition, body, and return

A function is created using the def keyword, followed by the function name and an argument list (which can be empty if the function receives no arguments). Because they introduce a new block of code, function definitions are terminated with a colon.

The function body is the indented block which follows the def. If the interpreter hits a return statement, then it leaves the function and returns the specified value (or None if no value is supplied). If the interpreter reaches the end of the function body without hitting a return statement at all, then None is also returned.

If the function needs to receive arguments, then a comma-separated list of names is placed between the parentheses that follow the function name. When the function is called, a value must be supplied for every name in the argument list.

Python also allows you to define function arguments that have a default value. If the argument isn’t supplied when the function is called, the default value is used instead. This is done by assigning a value to the argument inside the function definition.

>>> def PrintArgs(arg1, arg2=3):
...    print arg1, arg2
...
>>> PrintArgs(3)
3 3
>>> PrintArgs(3, 2)
3 2

As you can see, when you don’t pass in an explicit second value, arg2 takes on the default value specified in the function definition. If you do pass in a second value, it’s used instead of the default one. Arguments with default values are known as keyword arguments. Note that you can also pass in keyword arguments by position; this is shown in the last line of the following example.

>>> def ShowingOffKeywords(a=None, b=None):
...    if a is not None:
...       print 'a =', a
...    if b is not None:
...       print 'b =', b
...
>>> ShowingOffKeywords(a=3)
a = 3
>>> ShowingOffKeywords(b='a string')
b = a string
>>> ShowingOffKeywords(2.0, 3)
a = 2.0
b = 3

If used sparingly, keyword arguments can greatly improve an API by removing the need to pass in values that rarely differ from the defaults. If you overuse them, you can create a complex API that no one will remember how to use. Keyword arguments also provide a convenient mechanism for configuring .NET classes—the ultimate goal of this tutorial.

Functions are great for simple and self-contained operations where the overhead of writing a class isn’t needed. Many simple operations end up being needed in program after program. Instead of having to re-implement your own functions over and over again, Python has a selection of built-in functions.

There are many operations that you need to perform often or that can be awkward to do cleanly. For a lot of these, Python provides built-in functions that are always available. Unlike the reserved keywords, you can create names (variables or functions) that shadow these names. Needless to say, shadowing built-ins is bad practice.

Table 2.2 shows some of the most useful built-in functions, along with a brief explanation.

Many of these functions have optional arguments or alternative usage patterns. For details, refer to the Python documentation, which provides a list of all the built-in functions at http://docs.python.org/lib/built-in-funcs.html.

It’s worth familiarizing yourself with these functions. We use a few of them through the book, and they can be extremely useful.

This list of built-in functions includes the type objects of the datatypes we’ve already looked at. These create new objects of their type. For example, int takes numbers or strings as input and returns a new integer.

>>> int(3.2)
3
>>> int('3')
3

The other constructors do a similar job, creating new objects from input you provide.

Functions are the bread and butter of procedural and functional programming. In recent years,^[13] a paradigm called object-oriented programming has arisen, building on the principles of procedural programming. Object-oriented programming allows you to combine data with functions (called methods) for working on the data. The basic element in object-oriented programming is a programming construct called the class, which we turn to now.

At the start of this chapter, we looked at the built-in datatypes. These are relatively simple objects, such as strings or integers, which represent a value. As well as their value, most^[14] of the built-in types also have methods associated with them.

You use these methods for performing common operations; they’re a bit like the built-in functions. For example, strings have methods to return a copy of themselves in lowercase or to remove whitespace from the start and end. The key thing is that the built-in types only have methods that are relevant to their type. Numbers don’t have a lower or a strip method.

The selection of available methods is determined by the type of the object and its class. You can define your own classes to create new kinds of objects.^[15]

New classes are not only for representing data but also for structuring programs and providing a framework. Well-written classes will make your program easier to understand; but, more importantly, they’re a thing of beauty and elegance!

Methods are attributes of objects that you call like functions—they can take arguments and return values. All object attributes are accessed using the dot syntax.

The following example uses the string method startswith. This method takes an argument and returns True if the string starts with the argument you supplied.

>>> string = 'Hello world'
>>> string.startswith('Hello')
True

Not all attributes are methods. Attributes can also be values, properties, or any other object. The normal way to access attributes though, whatever they may be, is with the dot syntax.

So how do you create your own classes? The answer is the class statement. We talk about classes being declared. A typical line that commences a class declaration is shown in figure 2.5.

Figure 2.5. A class declaration

Between the parentheses following the class name is a list of classes that your class inherits from. If your class inherits from another class, then it automatically gains the attributes and methods of that class. If you need several classes that do similar things, then you may be able to put the common parts into a single class and then have your other classes inherit from it. Classes that you inherit from are called base classes. Classes can have more than one base class—Python supports multiple inheritance—but this can be a recipe for confusion; it’s usually best avoided if possible.

class OldStyleClass:

Indented inside the class statement are your methods and any class attributes. To write methods, you need to know about two things first: self and __init__.

Every method you write needs to take an extra argument. The individual objects created from classes are called instances. Individual strings are instances of the str or unicode class. For the code inside your methods to access the instance it belongs to, it needs a reference to the instance. This is passed in as the first argument to methods; the Python convention is to call this argument self. self is the equivalent of this in C#, except that you need to explicitly declare it in the method signature.

You also need to know that constructor methods are declared in Python with the name __init__. __init__ is entirely optional; you don’t need to write a constructor if your class doesn’t require one.

When you create a new instance by calling the class, the constructor is called and the new instance returned.

>>> class MyObject(object):
...    def __init__(self, value):
...       self.value = value
...
>>> myObject = MyObject(10)
>>> print myObject.value
10

When the instance is created, __init__ is called with a reference to the new instance (self) and the argument passed in. __init__ then sets the value attribute on the instance to 10.

Classes can have attributes too; this is useful because class attributes are shared between all instances.

>>> class SimpleObject(object):
...    classAttribute = object()
...
>>> instance1 = SimpleObject()
>>> instance2 = SimpleObject()
>>> instance1.classAttribute is instance2.classAttribute
True

Note that in this example a constructor isn’t defined, so you inherit the default one from object, which does nothing.

Python doesn’t have true private or protected attributes. By convention, any method or attribute name that starts with a single or a double underscore isn’t part of the public API. Exceptions are the magic methods, whose names start and end with double underscores. You don’t often call these directly anyway, except perhaps in subclasses calling up to their parent classes. Attribute or method names that have a leading double underscore are treated specially by the interpreter. The names are mangled^[17] to make it harder to access them from outside the class. From inside the class, the names can be used normally; from outside, they can only be accessed via the mangled name.

We’ve now covered the basic constructs in Python, the mortar and the bricks of the language. Functions and classes are the most essential building components of any Python program. By now, you should be starting to get an overview of Python and how it works; for example, methods are really just special cases of functions. One consequence of this is that you can replace methods on classes with alternative functions at runtime, something useful for testing. The more of an overview you have, the easier it is to understand the details of what’s going on.

The goal of this chapter is to allow you to create an IronPython program that takes full advantage of the .NET platform. Many aspects of the .NET framework are similar to Python, such as the basic class structure with methods and attributes. To create Python programs, you need to understand the objects and patterns you’ll encounter from a Python point of view. You also need to know enough Python to be able to create applications. Before we can dive into .NET, you need a few more raw materials; think of these as the timbers, ties, and plastics of the house that is the Python language. In the next section, we look at a few further aspects of Python necessary to our construction work.

Exceptions indicate that some kind of error has happened. They can be raised by the operating system when you try something like accessing a file that doesn’t exist, or by the Python runtime when you do something daft like adding strings to numbers.

You can also raise exceptions yourself, to indicate that an error condition has been reached.

If you don’t handle exceptions, then your program will literally stop with a crash. Catching exceptions in Python is done with the try: ... except: block.

>>> 'a string' + 3
Traceback (most recent call last):
TypeError: Cannot convert int(3) to String
>>> try:
...   'a string' + 3
... except:
...   pass
...

When used like this, the except clause catches all exceptions. This is bad practice; you should only catch the specific types of exceptions that you’re expecting. Catching and silencing exceptions you aren’t expecting can allow bugs in your code to pass unnoticed, and cause problems that are very difficult to debug.

In Python, you can specify which types of exceptions you want to catch after the except. You specify either a single exception type or a tuple of exceptions. You can also chain multiple except clauses to provide different blocks of code to handle different types of exceptions. You can also provide a block of code to be executed only if no exceptions occur, by ending your except clauses with an optional else clause.^[18]

>>> try:
...    do_something()
... except (OSError, IOError):
...    print 'Looks like the path was invalid'
... except TypeError:
...    print 'Why did this happen'
... else:
...    print 'It all worked out fine'
...

Sometimes you need to keep hold of the exception instance to check attributes or the message. The string representation of exception instances is the error message. You can bind the exception to a name within the except clause; this can be useful for logging.

>>> try:
...     'a string' + 3
... except TypeError, e:
...    print e
...
Cannot convert int(3) to String

In some circumstances you may wish to catch the error and then re-raise it. If you use the raise statement on its own, it re-raises the last exception that occurred.

For a slightly different use case, try: ... except: has a companion—the try: ... finally: block. You use finally rather than except when you need to guarantee that some code runs, whether or not the preceding block was successful. For example, you might want to use finally when closing a database connection or an open file. If an exception is raised, the finally block is executed, and then the exception is re-raised.

The next example illustrates the finally block, and also the other side of catching exceptions—raising exceptions.

>>> try:
...    raise Exception("Something went wrong")
... finally:
...    print 'This will be executed'
...    print 'whether an exception is raised'
...    print 'or not'
...
This will be executed
whether an exception is raised
or not
Traceback (most recent call last):
Exception: Something went wrong

The raise statement raises exceptions. There are several different variations of raise, but the only one you really need to know is the form used in the example.

raise ExceptionType(arguments)

The base exception class in Python is Exception.

That finishes it off for exceptions, at least for the moment. We’ve already talked at length about how Python can take advantage of programming styles like functional programming. Understanding the scoping rules is important for any programming, but it’s particularly vital to functional programming.

Scoping rules are the way that a language looks up names that you use within a program. Python uses lexical scoping.^[20] Your code can access names defined in any enclosing scopes, as well as all global values.

But first, we probably need to explain what a scope is. Let’s look at global and local scopes.

>>> x = 3            
>>> def function1():
...    print x       
...
>>> def function2():
...    x = 6         
...    print x
...
>>> function1()
3
>>> function2()
6

This code segment defines the name x. Because it isn’t inside a function or method body, x is defined in the global scope . function1 uses the name x , which isn’t defined inside it. When Python encounters the name and can’t find it locally, it looks it up in the global scope.

Inside function2 the name x is also defined locally . When you call function2 and the Python interpreter encounters the name x, the first place it looks is the local scope. The local name x shadows the global variable.

Things get interesting when you introduce another scope. If a function has a function defined inside it, the outer function is said to enclose the inner function. When the inner function uses a name, the name is first looked for in the scope of the inner function, its local scope. If it isn’t found, then Python will check the enclosing scope. This applies to as many levels of nesting as you want; the outer scopes will be searched all the way up to the global scope. If the name isn’t found anywhere, then a NameError exception is raised.

When you call outerFunction, it defines the function innerFunction. This function exists in the local scope of outerFunction. (Try calling innerFunction from the global scope.) outerFunction calls innerFunction; this prints the values x and y. Neither of these is local to innerFunction. x is defined inside outerFunction, shadowing the global x. y is only defined in the global scope.

When you call a function, the names inside it are looked up from the enclosing scope where the function was defined, not from where it’s used. Your outer functions can return a reference to an inner function that can then be used far from where it was created. It will still use names from the scope(s) that enclosed it when it was defined. To illustrate this, let’s use a classic example and create an adder function.

>>> def makeAdder(value):
...    def newAdder(newValue):     
...       return value + newValue    
...    return newAdder
...
>>> adder = makeAdder(7)      
>>> adder(3)
10
>>> adder(-4)
3

You pass in a value to the makeAdder function, and it returns a newAdder function that adds numbers to the original value that you passed in . When you call makeAdder with an argument , the argument is bound to the name value, which is local to the scope of makeAdder. You can reuse makeAdder to create as many adder functions as you like. Every time you call it a new scope is created.

Several parts of Python show the influence of functional programming. One favorite of mine is the list comprehension, which is a particularly elegant construct. List comprehensions also get used a lot in Python, so it would be impossible to have a tutorial that doesn’t mention them.

List comprehensions allow you to express several lines of code in a single readable line. This is a concept borrowed from the language Haskell, that allows you to combine a for loop and an optional filter in a single construct. If you’re brave, you can combine several loops into a single list comprehension, but this tends to be a bit taxing on the brain.

List comprehensions are so named because they create lists. Consider the following simple segment of code:

>>> result = []
>>> input = [1, 2, 3, 4, 5]
>>> for value in input:
...    result.append(value * 3)
...
>>> result
[3, 6, 9, 12, 15]

This constructs a list (called result) from all the members of input, multiplying each value by three.

This segment of code can be written in a much more concise way using a list comprehension.

>>> input = [1, 2, 3, 4, 5]
>>> result = [value * 3 for value in input]
>>> result
[3, 6, 9, 12, 15]

The expression value * 3 is calculated for each member of input, and the result list is built. The two forms of this code, using a loop and using a list comprehension, are functionally identical.

List comprehensions also allow you to include filters. Suppose you only wanted to use the values from the input that are greater than two; you can put this condition into the body of the list comprehension.

>>> input = [1, 2, 3, 4, 5]
>>> result = [value * 3 for value in input if value > 2]
>>> result
[9, 12, 15]

A list comprehension is itself an expression, and so you can use one anywhere an expression can be used.

We haven’t covered every possible variant of Python syntax, but you should have learned enough to give you a good grounding to be able to start exploring. The final sections in this chapter are about organizing programs into libraries called modules and packages. The mechanisms for working with modules and packages are useful for organizing your own programs, but they’re also the same mechanisms by which you access the .NET libraries.

The last thing you want when programming is to have all your code contained in a single monolithic file. This makes it almost impossible to find anything. Ideally, you want to break your program down into small files containing only closely related classes or functionality. In Python, these are called modules.

The import statement has several different forms.

import module[21]
from module import name1, name2
from module import name as anotherName
from module import *

Importing a module executes the code it contains and creates a module object. The names you’ve specified are then available from where you imported them.

If you use the first form, you receive a reference to the module object. Needless to say, these are first-class objects that you can pass around and access attributes on (including setting and deleting attributes). If a module defines a class SomeClass, then you can access it using module.SomeClass.

If you need access to only a few objects from the module, you can use the second form. It imports only the names you’ve specified from the module.

If a name you wish to import would clash with a name in your current namespace, you can use the third form. This imports the object you specify, but binds it to an alternative name.

The fourth form is the closest to the C# using directive. It imports all the names (except ones that start with an underscore) from the module into your namespace. In Python, this is generally frowned on. You may import names that clash with other names you’re using without realizing it; when reading your code, it’s not possible to see where names are defined.

Python allows you to group related modules together as a package. The structure of a Python package, with subpackages, is shown in figure 2.6.

Figure 2.6. The structure of a Python package on the filesystem

A package is a directory on the Python search path. Importing anything from the package will execute __init__.py and insert the resulting module into sys.modules under the package name. You can use __init__.py to customize what importing the package does, but it’s also common to leave it as an empty file and expose the package functionality via the modules in the package.

You import a module from a package using dot syntax.

import package.module
from package import module

Packages themselves may contain packages; these are subpackages. To access subpackages, you just need to use a few more dots.

import package.subpackage.module
from package.subpackage import module

Python also contains several built-in modules. You still need to import these to have access to them, but no code is executed when you do the import. We mention these because one of them is very important to understanding imports. This is the sys module.^[22]

When you import a module, the first thing that Python does is look inside sys.modules to see if the module has already been imported. sys.modules is a dictionary, keyed by module name, containing the module objects. If the module is already in sys.modules, then it will be fetched from there rather than re-executed. Importing a module (or name) from different places will always give you a reference to the same object.

If the module hasn’t been imported yet, Python searches its path to look for a file named module.py.^[23] If it finds a Python file corresponding to the import, Python executes the file and creates the module object. If the module isn’t found, then an ImportError is raised.

The list of paths that Python searches is stored in sys.path. This is a list of strings that always includes the directory of the main script that’s running. You can add (or remove) paths from this list if you want.

Some Python files can be used both as libraries, to be imported from, and as scripts that provide functionality when they’re executed directly. For example, consider a library that provides routines for converting files from one format to another. Programs may wish to import these functions and classes for use within an application, but the library itself might be capable of acting as a command-line utility for converting files.

In this case, the code needs to know whether it’s running as the main script or has been imported from somewhere else. You can do this by checking the value of the variable __name__. This is normally set to the current module name unless the script is running as the main script, in which case its name will be __main__.^[24]

def main():
   # code to execute functionality
   # when run as a script
if __name__ == '__main__':
   main()

This segment of code will only call the function main if run as the main script and not if imported.

When you re-import a module, you get a new reference to the already-created module object. This can be a pain when you’re actively developing a module and want to play with it from the interactive interpreter. If you want to force the interpreter to use the latest version, you can use the reload function and then re-import it.

Calling reload doesn’t rebind names that point to objects from the old module. You have to do this yourself after reloading—hence, the need to import again.

Another useful feature of modules shared with several types of objects is the docstring.

If you cast your mind back to the end of the first chapter, you’ll recall the useful builtin function help. This is for working with the interactive interpreter; it prints some useful information about an object to the console. For Python modules, functions, classes, and methods, it will include any docstring that you’ve defined. So what is this esoteric creature, the docstring?

A docstring is a string written inline with an object and that isn’t assigned a name. This is then available to the help function, and lives attached to the object as the __doc__ attribute. The following segment illustrates this a bit more clearly, using a function as an example:

>>> def adder(val1, val2):
...   "This function takes two values and adds them together."
...   return val1 + val2
...
>>> help(adder)
Help on function adder in module __main__

 | adder(val1, val2)
 |    This function takes two values and adds them together.
>>> adder.__doc__
'This function takes two values and adds them together.'
>>>

If you want docstrings that contain multiple lines, you can use triple-quoted strings.

Docstrings aren’t just useful for interactive help; they’re guides for anyone reading your source code and are also used by automatic documentation tools^[25] for creating API documentation from source code.

At last, you know enough to create large and well-structured IronPython programs, as long as you don’t need to access much .NET functionality. Before you rush off to try this, we’d like to save you some time. CPython comes with a large standard library of packages and modules for common programming tasks. Before you start coding, it’s well worth checking to see if at least part of your task is already written for you. The next section talks about the standard library, introduces you to a few of the more commonly used modules, and explains how to use the library with IronPython.

Python comes with batteries included. This statement refers to the standard library that accompanies CPython. Many of the modules it provides are pure-Python modules, but some of them are extension modules written in C.

Unfortunately, extension modules written in C won’t work directly in IronPython. Other modules, even in the standard library, rely on implementation details or undocumented features of Python. Some of these incompatibilities between Python and IronPython have already been fixed, but some are very difficult cases.

That’s the bad news. The good news is that a large proportion of the standard library works fine. The IronPython team, along with the Python community, has put a lot of effort into ensuring that as much of the standard library as possible works with IronPython; in some cases, alternatives to C extension modules have been created. Existing code that uses the standard library stands a better chance of working, and these modules are available to use within your code.

The first step in using the standard library is obtaining it. The IronPython 2 msi installer comes with the Python 2.5 standard library, and makes it automatically available for import.^[28]

An alternative way of getting hold of the standard library is downloading and installing CPython. Go to www.python.org/download/ and download the latest version of Python 2.5.^[29]

On Windows, the default install location is C:Python25. The standard library itself will be located in C:Python25Lib.

You then need to expose the library to IronPython. There are three convenient ways of doing this. The first is best for use on a single machine, the second for distributing applications, and the third for quick one-off experimentation.

You can manually add the standard directory library at the interactive interpreter with the following steps:

>>> import sys
>>> sys.path.append(r'C:Python25Lib')

Notice that you use a raw string to add the path; otherwise, the backslashes will be interpreted as escape characters.

There are many modules and packages in the Python standard library. We’ve listed some of the commonly used ones in table 2.3. Some of these modules, such as re and cStringIO, are implemented in C for CPython. Many of them^[30] have been implemented by the IronPython team as built-in modules (written in C#) so that these modules are available to IronPython. You can find a list of all of them at http://docs.python.org/modindex.html.

Python isn’t a big language, nor is it difficult to learn, but we’ve still covered a lot of material in this chapter. The best way of getting it ingrained, of course, is to use it. In the next chapter, you’ll be putting what you’ve learned here to practical use; you’ll also learn about the .NET framework, which comes with its own standard library.