Packages - Crib Sheet

There may be times when you need to extend Python's capabilities beyond what is included in the standard library. This is where modules and packages come in.

Modules

In Python, a module is a file containing Python definitions and statements. The file name is the module name with the suffix .py. Modules can be used to organize related code, reuse code across different projects, and provide a way to share code with others.

To use a module in your code, you must first import it using the import statement. Here's an example:

import math 
print(math.pi)

In this example, the math module is imported using the import statement, and the value of the constant pi is printed using the print() function.

You can also import specific names from a module using the from...import statement. Here's an example:

from math import pi 
print(pi)

In this example, the pi constant is imported from the math module using the from...import statement, and the value is printed using the print() function.

Packages

A package is a collection of modules that are organized into a directory hierarchy. Packages provide a way to organize related modules, and can be used to create reusable libraries of code.

To create a package, you must first create a directory with a special file called __init__.py in it. The __init__.py file is executed when the package is imported, and can be used to define package-level variables and functions.

Here's an example of a simple package structure:

mypackage/ 
    __init__.py 
    module1.py 
    module2.py

In this example, the mypackage directory contains the __init__.py, module1.py, and module2.py files. The __init__.py file can be used to define package-level variables and functions, while the module1.py and module2.py files contain module-level definitions.

To use a module in a package, you must first import the package using the import statement. Here's an example:

import mypackage.module1 

mypackage.module1.my_function()

In this example, the mypackage package is imported using the import statement, and the my_function() function in the module1.py file is called using the . operator.

You can also import a module from a package using the from...import statement. Here's an example:

from mypackage import module1 
module1.my_function()

In this example, the my_function() function in the module1.py file is imported using the from...import statement, and the function is called using the . operator.

Passing Arguments to Programs

Python programs can be designed to accept command-line arguments using the sys.argv list. The sys.argv list contains the command-line arguments passed to the program, with the first argument being the name of the program itself.

Here's an example of a Python program that accepts command-line arguments:

import sys 
if len(sys.argv) > 1: 
    print("Hello, " + sys.argv[1] + "!") 
else: 
    print("Hello, world!")

In this example, the program checks if there is at least one command-line argument, and if so, prints a personalized greeting to the first argument. If no argument is provided, the program prints a generic greeting.

To run this program with a command-line argument, you would use the following command:

python hello.py John

This would output:

Hello, John!

If no command-line argument is provided, running the program with the following command would output the generic greeting:

python hello.py

Package Structure

When organizing modules and packages in a project, it is important to follow a consistent structure. This makes it easier to navigate and maintain the code, and makes it easier for others to understand how the code is organized.

Here is a common package structure for a Python project:

myproject/ 
    __init__.py 
    main.py 
    utils/ 
        __init__.py 
        file1.py 
        file2.py 
    tests/ 
        __init__.py
        test_file1.py 
        test_file2.py

In this example, the myproject directory contains the __init__.py file and the main.py file.

The utils directory contains the __init__.py file and the file1.py and file2.py modules, which contain utility functions that can be used throughout the project. The tests directory contains the __init__.py file and the test_file1.py and test_file2.py modules, which contain unit tests for the file1.py and file2.py modules.

The __init__.py files are used to define package-level variables and functions, and to ensure that the directories are recognized as packages by Python.

The main.py file is the entry point of the program, and can import and use functions and classes from the other modules and packages in the project.

The utils directory contains modules that provide utility functions that can be used throughout the project. These functions can be imported using the from utils import file1 syntax.

The tests directory contains modules that provide unit tests for the other modules and packages in the project. These tests can be run using a testing framework such as unittest.

When designing a Python project, it is important to follow a consistent package structure, and to use command-line arguments to make the program more flexible and easier to use. By following these best practices, you can create high-quality Python projects that are easy to maintain and share with others.