Python Forum

Each file is a module, and modules import other modules to use the names they define. Modules provide an easy way to organize components into a system by serving as self-contained packages of variables known as namespaces.

A module is a set of functions, types, classes, ... put together in a common namespace.
A library is a set of modules which makes sense to be together and that can be used in a program or another library.
A package is a unit of distribution that can contain a library or an executable or both. It's a way to share your code with the community.

import  
 let's a client (importer) fetch a module as a whole

import tester

from   
 allows clients to fetch particular names from a module

from tester import Klass

allows clients to fetch a module from a different directory. (see Relative Imports on Modules Part 3)

from .. import tester #import the module tester from parent directory

as
allows an imported name to be given a different name in your script

from tester import Klass as Kl
import tester as test

reload   
Provides a way to reload a module's code without stopping Python
Python2.x (reload is a built-in)

reload(modulename)

Python3.x (reload has been moved to the imp module)

from imp import reload
reload(modulename)

importing subpackages

import os
import tkinter
import tkinter.ttk

Subpackages are not necessarily available in the package's namespace and you may need to import them separately (this allows to import only what you really need). Note that submodules may exist in a module that is not a package. An example is os.path. You can import os and use os.path.expanduser() for example without importing explicitly os.path. Another example is tkinter and ttk. ttk is a subpackage of tkinter and needs to be imported in addition to tkinter.

How it works:
The rest of part 1 can be tedious. If you don't want to hear the mumbo jumbo, scroll down and click the link for part 2.

Modules import without the suffix .py. Imported modules performs a 3-step process the first time it is imported:

1)Find the modules file
Python first looks at the home directory that the file is located in:

directoryname/
    a.py
    b.py

Using the previous example, in b.py if you wanted to import the module a.py, in b.py you would have the following syntax:

import a

If a program is located entirely in a single directory, all of it's imports will work automatically with no path configuration required. Because this directory is searched first, its files will also override modules of the same name in directories elsewhere on the path.

Python then searches your PYTHONPATH directories:
PYTHONPATH is a list of user-defined and platform-specific names of directories that contain python code files. You can add all the directories from which you wish and python will extend the modules search path to inlcude all the directories in your PYTHONPATH lists. This setting is only important when you are importing files across directory boundaries.

import sys
sys.path.append("/path/to/your/directory") 

Python then searches your standard library directories:
These are always searched and do not need to be added to your PYTHONPATH

Python then searches for directories in your .pth files:
This is a file you create that allows you to add directories to the module search path by listing them, one per line, in a text file whose names ends with .pth. 

You can always inspect the modules search path

import sys
print(sys.path)

sys.path is the merging of the home directory of the top-level file (or an empty string to designate the current working directory), any PYTHONPATH directories, the contents of any .pth files path you created, and the standard library directories. 

Some changes last only the duration of the script, but PYTHONPATH and .pth files allow for more permanent ways to modify the path. 

2) Compile it to byte code (if needed)
After finding the the source code file that matches the import statement, Python next compiles it to byte code if necessary.  Python checks the file timestamps and if the byte code file is older than the source file (ie, if you changed the source), automatically regenerates the byte code when the program is run. If on the other hand, it finds a .pyc byte code file that is not older than the corresponding  .py source file, it skips thie source-to-byte code compile step. IF python finds only a byte code file on the search path and no source, it loads the byte code directly (meaning you can ship your a program as jsut byte code files and avoid sending source). The compile step is bypassed if possible to speed program startup. 

Only imported files leave behind a .pyc file

3) Run the modules code to build the objects it defines
The final step is is it executes the byte code of the module. All statements in the file are executed in trun, from top to bottom, and anyassignments made to names during this step generate attributes of the resulting module object.

Because this step actually runs the file's code, if any top-level code in a module does real work, you will see the results at import time. Because of this, any given module is imported only once per process by default. If you need to import a file again after it it has been loaded, you have to force the issue with imp.reload.

3rd party software
3rd party software use distutils from the standard library to install themselves. So no path configuration is required to use thier code. These typically come with a setup.py file

Basic structure example using linux terminal
I did this all on the terminal so you can actually see what i write to the file. For quick rundown: mkdir creates a directory, touch creates a file, cat prints off the file content, ls lists the current directory content, echo "some_string" >> filename writes some_string to the file filename. 

this is an example all on the terminal:

metulburr@arch ~ $ mkdir example
metulburr@arch ~ $ cd example
metulburr@arch ~/example $ touch main.py
metulburr@arch ~/example $ ls
main.py
metulburr@arch ~/example $ echo "from subfolder import module" >> main.py
metulburr@arch ~/example $ echo "print('running main')" >> main.py
metulburr@arch ~/example $ cat main.py 
from subfolder import module
print('running main')
metulburr@arch ~/example $ mkdir subfolder
metulburr@arch ~/example $ ls
main.py  subfolder
metulburr@arch ~/example $ touch subfolder/__init__.py
metulburr@arch ~/example $ touch subfolder/module.py
metulburr@arch ~/example $ echo "print('running module')" >> subfolder/module.py
metulburr@arch ~/example $ cat subfolder/module.py 
print('running module')
metulburr@arch ~/example $ python3 main.py 
running module
running main
metulburr@arch ~/example $ python2 main.py
running module
running main
metulburr@arch ~/example $ 

and here is what each line is doing:

create directory example in ~/
cd directory into example
create a new file called main.py
list files in directory (ls)
write to the file on first line in main.py "from subfolder import module"
write to the file on second line in main.py "print('running main')"
print the content of what is in main.py (cat)
make directory subfolder
list files and directories in current directory "example"
create a new file in  subfolder called __init__.py
create a new file in subfolder called module.py
write to the file on first line in the subfolder directory to file module.py
print the content of what is in subfolder/module.py
execute main.py via (python main.py) in the directory example
(code can be python2.x or 3.x)

the structure:

• /home/username/example:
  • main.py
    
  • subfolder
    • __init__.py
      
    • module.py
      

go to Modules part 2