Using Modules

Python itself comes with many highly useful built-in modules, which are ready for immediate use once Python is installed.

Let’s take the built-in sys module as an example to create a module named hello:

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

' a test module '

__author__ = 'Michael Liao'

import sys

def test():
    args = sys.argv
    if len(args)==1:
        print('Hello, world!')
    elif len(args)==2:
        print('Hello, %s!' % args[1])
    else:
        print('Too many arguments!')

if __name__=='__main__':
    test()

Lines 1 and 2 are standard comments:

• Line 1 allows the hello.py file to run directly on Unix/Linux/Mac systems.
• Line 2 indicates that the .py file itself uses the standard UTF-8 encoding.

Line 4 is a string serving as the documentation comment for the module. The first string in any module code is always treated as the module’s documentation comment.

Line 6 uses the __author__ variable to include the author’s name, so others can see your name when you publish the source code.

The above is the standard file template for a Python module. Of course, you could delete all of these comments and variables, but following standards is always a good practice.

The actual code begins after this section.

You may have noticed that the first step to use the sys module is to import it:

import sys

After importing the sys module, we have a variable sys that points to the module. Using this sys variable, we can access all the functionalities of the sys module.

The sys module has an argv variable, which stores all command-line arguments as a list. argv always has at least one element, because the first argument is always the name of the .py file. For example:

• Running python3 hello.py results in sys.argv being ['hello.py'].
• Running python3 hello.py Michael results in sys.argv being ['hello.py', 'Michael'].

Finally, note these two lines of code:

if __name__=='__main__':
    test()

When we run the hello module file from the command line, the Python interpreter sets a special variable __name__ to __main__. However, if the hello module is imported elsewhere, this if condition will fail. Therefore, this type of if check allows a module to execute additional code (most commonly for running tests) when it is run directly from the command line.

We can run hello.py from the command line to see the effect:

$ python3 hello.py
Hello, world!
$ python hello.py Michael
Hello, Michael!

If we start the Python interactive environment and then import the hello module:

$ python3
Python 3.4.3 (v3.4.3:9b73f1c3e601, Feb 23 2015, 02:52:03) 
[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import hello
>>>

No “Hello, world!” is printed during import because the test() function is not executed.

Only when we call hello.test() will “Hello, world!” be printed:

>>> hello.test()
Hello, world!

Scope

In a module, we may define many functions and variables. Some are intended for external use, while others are only for internal use within the module. In Python, this is achieved using the _ prefix:

• Normal function and variable names (e.g., abc, x123, PI) are public and can be directly referenced.
• Variables like __xxx__ are special variables—they can be directly referenced but have special purposes. For example, __author__ and __name__ are special variables, and the documentation comment of the hello module can be accessed via the special variable __doc__. We should avoid using this naming style for our own variables.
• Functions or variables like _xxx and __xxx are private and should not be directly referenced (e.g., _abc, __abc).

We say private functions/variables “should not” (rather than “cannot”) be directly referenced because Python does not have a mechanism to completely restrict access to private functions/variables. However, it is a programming convention to avoid referencing them directly.

If private functions/variables should not be referenced externally, what is their purpose? See the example below:

def _private_1(name):
    return 'Hello, %s' % name

def _private_2(name):
    return 'Hi, %s' % name

def greeting(name):
    if len(name) > 3:
        return _private_1(name)
    else:
        return _private_2(name)

We expose the greeting() function publicly in the module, while hiding the internal logic in private functions. This way, users of the greeting() function do not need to care about the details of the private internal functions. This is a very useful method of code encapsulation and abstraction:

All functions not required for external use are defined as private, and only functions that need to be referenced externally are defined as public.