Using Modules ​

Python itself has many very useful built-in modules that can be used immediately after installation.

Let's take the built-in sys module as an example to write a hello module:

#!/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()

The first and second lines are standard comments. The first line allows the hello.py file to run directly on Unix/Linux/Mac, and the second line indicates that the .py file uses standard UTF-8 encoding.

The fourth line is a string that serves as the module's documentation comment; any string that appears as the first statement in a module is considered the module's documentation comment.

The sixth line uses the __author__ variable to include the author's name, allowing others to recognize you when you share your source code.

This is the standard file template for a Python module. Of course, you could delete everything and write just the functional code, but following the standard is certainly a good practice.

Now, let's get to the actual code part.

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

import sys

After importing the sys module, we now have a variable sys that points to the module, allowing us to access all the functionalities of the sys module using this variable.

The sys module has a variable argv that stores all command-line parameters in a list. argv always has at least one element because the first parameter is always the name of the .py file. For example:

• Running python3 hello.py will yield sys.argv as ['hello.py'].
• Running python3 hello.py Michael will yield sys.argv as ['hello.py', 'Michael'].

Finally, take note of 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__. If the hello module is imported from elsewhere, this if condition will fail, meaning that this test allows the module to execute additional code when run from the command line, which is commonly used for running tests.

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

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

If we start the Python interactive environment and 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
>>>

When importing, "Hello, world!" is not printed because the test() function is not executed.

Only when we call hello.test() will it print "Hello, world!":

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

Scope ​

In a module, we may define many functions and variables, but some functions and variables we want to be accessible to others, while some we want to keep private to the module. In Python, this is achieved using the _ prefix.

Normal function and variable names are public and can be referenced directly, such as: abc, x123, PI, etc.

Variables like __xxx__ are special variables that can be referenced directly but have special purposes. For example, __author__ and __name__ are special variables, and the module's documentation comment defined in the hello module can be accessed using the special variable __doc__. Generally, we should avoid using such variable names for our own variables.

Variables or functions that start with _xxx or __xxx are considered private and should not be referenced directly, such as _abc or __abc.

The reason we say private functions and variables "should not" be referenced directly rather than "cannot" be referenced is that Python does not provide a way to completely restrict access to private functions or variables. However, from a programming convention standpoint, private functions or variables should not be referenced.

What is the purpose of private functions or variables if they should not be referenced? Here is an example:

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)

In this module, we expose the greeting() function while hiding the internal logic using private functions. This way, when calling greeting(), the caller does not need to be concerned with the details of the private functions, which is a very useful method for code encapsulation and abstraction. Specifically, all functions that do not need to be referenced externally are defined as private, while only the functions that need to be referenced externally are defined as public.