by Simon Bluck

A file containing Python code is called a module. The file name is the module name with the suffix .py appended. A module may be: a top-level program (one you invoke directly from the command line),his is called the main module); or a useful set of Python definitions to be imported into another module. Or both, i.e. a top-level program containing useful definitions that you may want to import into another program.

See the docs.python.org tutorial on modules.

• Python comes with a library of standard modules.
• The built-in function dir() can be used to find out which names a module defines.
• By convention, the top-level function of a program is called main:

def main ():
 ...  # Elipses are allowed in python and they effectively do nothing here.

And you need to explicitly call main:

main ()

Standard code to call function main if you think you may ever import this module:

if __name__ == "__main__": main() # Only call main if module run from cmd line

Useful variables are automatically defined for you in any module:

__name__      module name

List of command line arguments:

sys.argv

(Note that argv[0] is the script name or path.)

When you run a python script, python analyses and executes each statement as it is encountered. Note that execution of a function definition merely causes python to remember that definition; the function isn’t invoked at that time. If the function definition includes default values for any parameters, those are evaluated and remembered at the point of execution of the function definition.

Doc strings

The first string in a module, function, class or method is implicitly assigned to a local variable:

    __doc__

Use help(module) to print the doc strings (or help(__name__) from within a module).

Importing a module

    import fibo  # Makes all defns in module fib accessible as e.g fibo.fib1

More sophisticated versions of import:

    from fibo import fib1, fib2  # Import just defns fib1 and fib2 from module fibo

    from fibo import *           # Import all defns from fibo (generally frowned upon)

How Python finds a module

Python checks if fibs is a built-in and uses that if it is; otherwise it checks the directory of the top level script (or current directory if no file was specified); else the directories listed in the shell PYTHONPATH environment variable.

Module layout and boilerplate

• The import statements are best placed first in a module. At least, the first Python statements.

• This is the Python first line, useful on Linux:

  #! /usr/bin/python

It allows you to run your program without first calling the python program. (Check that /usr/bin/python is in fact a symbolic link to python3, using ls -ld /usr/bin/python.)

• Comments begin with # and must be at the end of a line.

• Indentation is required, and is by convention four spaces.

• Boilerplate main module:

#! /usr/bin/python

"""<module doc string>
"""

import ...

  global definitions

def main ()
  ...

 if __name__ == "__main__":  main()

Comments

Comments should supply useful information not immediately obvious from the code. Don’t write comments like:

a = pi * r * r # Multiply pi by r squared and store in a

(unless, you’re writing an explanation to absolute beginners.)

But do write:

a = pi * r * r # Calc area

But better of course would be to choose your variable names carefully:

area = pi * radius * radius

(which is best not commented)

But it’s often a compromise. If you’re writing lots of code manipulating area and radius then:

a = pi * r * r

without a comment is actually best.

It’s good to provide a comment for each and every name you introduce. Go back over the code when it’s nearing completion and do that, renaming if required to better reflect the true meaning. Often you unearth issues when you figure out accurate names.

Each module should have a header comment that ideally fully describes what the module is about.

NEXT -> Part Four: Approaching Coding