Python Module Introduction

1. Python Module.

Python has many useful built in modules, which can be used as soon as the installation is complete. We use the build-in sys module as an example to write a hello module as below.

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

' a hello test module '

__author__ = 'Richard Trump'

import sys

def say_hello():
    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__':
     say_hello()

Lines 1 and 2 are standard comments, line 1 comment allow the hello.py file to run directly on Unix/Linux/Mac, line 2 comment indicate that the .py file itself is encoded in standard utf-8 encoding. Line 4 is a string that represents the document annotation for the module. The first string of any module source code is treated as a document annotation of the module. Line 6 use the __author__ variable to write the author in it so that when you expose the source code to public, others can see your name. This is the standard file template for a Python module.

And then there’s the actual code part. As you may have noticed, the first step to using the sys module is to import the module import sys. After import the sys module, we have the variable sys pointing to the module, and with the variable sys, we can access all the functions of the sys module.

The sys module has an argv variable that stores all the arguments on the command line within a list. Argv has at least one element because the first parameter is always the name of the .py file, for example: Running python3 hello.py gives sys.argv with list ['hello.py']; Running python3 hello.py Richard give sys.argv value is ['hello.py', 'Richard'].

Finally, notice these two lines of code:

if __name__=='__main__':
      say_hello()

When we run the hello module file on the command line, the Python interpreter sets a special variable called __name__ to __main__. And if you import the hello module in another .py fiele, the if check will fail. So, the if check can allow a module to execute a few extra code through the command-line, and the most common code in the main function is to run test code.

We can run hello.py from the command line to see what happens.

$ python3 hello.py
Hello World!
$ python hello.py Richard
Hello, Richard!

If you start the Python interaction environment, then import the hello module.

$ python3
>>> import hello
>>

When import, ‘Hello Word’ is not printed! Because the say_hello() function is not executed. Only when you call hello.say_hello(), you can print out ‘Hello Word!’.

>>> hello.say_hello()
Hello World!

2. Python Module Variable Scope.

In a module, we may define many functions and variables, some functions and variables we want to use for others ( public ), some functions and variables we want to use only within the module ( private ). In Python, this is done with the _ prefix.

Normal function and variable names are public and can be referenced directly. Variables like __xxx__ are special variables that can be referenced directly, but have special meanings. For example, __author__ and __name__ is a special variables. The document annotations defined by the hello module can also be accessed with the special variable __doc__. We normally don’t use this kind of variable name for our own variables.

Functions or variables like _xxx and __xxx are not public ( there are private) and should not be referenced directly. Private functions or variables should not be referenced externally, so what’s the use of them? Please have a look at below example.

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

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

def say(name):
    if len(name) > 3:
        return _say_hello(name)
    else:
        return _say_hi(name)

We expose the say() function in the module and hide the internal logic in the private function. In this way, calling the say() function does not care about the details of the internal private function, which is a very useful method for code encapsulation and abstraction. Functions that are not referenced externally are all defined as private, and only those that are referenced externally are defined as public.