Concepts / Organizing Code with Packages

Organizing Code with Packages

The file gives the code a name and provides a unit that another Python program can import.

  • Programming

From Program to Module

A Python program can be more than a file that runs on its own. Every Python program is also a module, which means its code can be organized in a file and made available for importing. The basic act of creating a module is simple: save Python code in a file whose name ends with .py.

Think of a module as Python code packaged in one source file. The file gives the code a name and provides a unit that another Python program can import. The module idea therefore connects two activities: saving code in a .py file and referring to that file by its module name in an import statement.

Python programhelpers.pysaved source filehelpersmodule namesaved asdrop .py
What contains what when Python code is saved as a reusable module?

Naming the Module

The filename determines the module name used in an import statement. Python removes the .py extension when the file is referred to as a module. For example, a file named helpers.py has the module name helpers, so the import statement uses helpers rather than helpers.py.

importkeywordhelpersmodule namehelpers.pysource filenameremove .pyuses
How does a filename such as helpers.py become the module name used in an import statement?
Worked example

Deriving an Import Name

A Python file is saved as mymodule.py. What module name should an importing program use?

  1. 1
    Start with the filename

    The saved file is named mymodule.py.

  2. 2
    Remove the extension

    The .py extension is dropped when the file is used in an import statement.

  3. 3
    Write the module name

    The resulting module name is mymodule.

Result

The importing program uses mymodule as the module name, not mymodule.py.

Saving a First Module

To create the simple module described in the lesson, save Python code in a file named mymodule.py. The saved file is now a module. Its module name is mymodule because Python handles the removal of the .py extension when the file is imported.

The important change is not a special conversion command. The file becomes a module when Python code is saved with the .py extension. The filename supplies the name that another program will use when it imports the module.

What do you think happens?

A file is named mymodule.py. Which name represents the module when it is imported?

  • mymodule.py

  • mymodule

  • .py

Reveal answer
Answer:

mymodule

The .py extension belongs to the filename. Python drops that extension when forming the module name used in an import statement.

Making the File Findable

Creating the module file is only half of the task. Python must also be able to find that file. A module must be in the same directory as the program that imports it, or in a directory listed in sys.path. If the file is placed outside those locations, Python cannot find it through the import.

Importing programrequests helpersSame directoryhelpers.py foundModule foundimport can succeedsys.path directoryhelpers.py foundModule not foundPython cannot find itOther directorynot in sys.pathsearchsearchyesyesfile placednot searched
How does Python find a module, and what changes when the .py file is outside the importing program's directory or the directories in sys.path?
Worked example

Checking Module Placement

An importing program needs a module named helpers. The file is helpers.py. Where can the file be placed so Python can find it?

  1. 1
    Check the filename

    helpers.py supplies the module name helpers.

  2. 2
    Check the importing program's directory

    The file can be placed in the same directory as the program that imports it.

  3. 3
    Check sys.path

    The file can instead be placed in a directory listed in sys.path.

  4. 4
    Reject an unlisted location

    A location that is neither the same directory nor a sys.path directory is not one of the specified places Python searches for the module.

Result

Place helpers.py beside the importing program or in a directory listed in sys.path.

Choosing Safe Filenames

A module filename should be a valid Python identifier apart from its .py extension. In practice, avoid spaces, hyphens, and other special characters in module filenames. Names that do not follow these rules can cause import errors.

Filename characteristicImporting consequence
Valid Python identifierSuitable as a module filename
Contains spacesCan cause import errors
Contains hyphensCan cause import errors
Contains other special charactersCan cause import errors

Module filenames should follow valid Python identifier rules.

Mistakes That Block Imports

  • Common mistake

    Writing the .py extension in the module name used for an import

    What it looks like

    Treating mymodule.py as the module name instead of mymodule

    Why it fails

    Python drops the .py extension when forming the module name used in an import statement.

    Do this instead

    Use the filename without .py as the module name.

  • Common mistake

    Placing the module where Python does not search

    What it looks like

    Saving helpers.py outside the importing program's directory and outside every directory in sys.path

    Why it fails

    Python must find the file in the same directory as the importing program or in a sys.path directory.

    Do this instead

    Move the module into the importing program's directory or into a directory listed in sys.path.

  • Common mistake

    Using spaces, hyphens, or special characters in the module filename

    What it looks like

    Choosing a filename that is not a valid Python identifier

    Why it fails

    Such filenames can cause import errors.

    Do this instead

    Use a filename that follows valid Python identifier rules.

Module Setup Practice

EASY

A file named report_tools.py is intended to be imported by a Python program. State the module name formed from the filename, identify two locations where the file can be placed for Python to find it, and name two filename features that should be avoided.

Hints
  • Remove the .py extension to determine the module name.
  • Use the two module-search locations described in this article.
  • Check whether the filename contains spaces, hyphens, or other special characters.
  1. 1
    Every Python program is also a module.
  2. 2
    Saving Python code in a .py file creates a module.
  3. 3
    The module name is the filename without the .py extension.
  4. 4
    Python can find a module in the importing program's directory or in a directory listed in sys.path.
  5. 5
    Module filenames should use valid Python identifiers and avoid spaces, hyphens, and special characters.

Key Takeaways

  • A Python source file saved with the .py extension is a module.
  • Python forms the module name by removing .py from the filename.
  • The module file must be in the same directory as the importing program or in a sys.path directory.
  • Valid Python identifiers are the safest module filenames; spaces, hyphens, and special characters can cause import errors.
  • Successful importing depends on both the module's name and its location.

Related Topics

Related concepts

More concepts starting with O