python module vs package - python modules - python packages - what is a python package

What Is a Python Package?

Packages are an essential building block in programming. Without packages, we’d spend lots of time writing code that’s already been written. Imagine having to write code from scratch every time you wanted to parse a file in a particular format. You’d never get anything done! That’s why we always want to use packages.

In this tutorial, we’ll walk you through the terminology of Python modules and packages, before showing you how to install and use packages in your Python code. We’ll then touch on how to create your own Python packages, and uncover some easter eggs. Let’s jump right in!

What Is a Python Package?

To understand Python packages, we’ll briefly look at scripts and modules. A “script” is something you execute in the shell to accomplish a defined task. To write a script, you’d type your code into your favorite text editor and save it with the .py extension. You can then use the python command in a terminal to execute your script. 

A module on the other hand is a Python program that you import, either in interactive mode or into your other programs. “Module” is really an umbrella term for reusable code.

A Python package usually consists of several modules. Physically, a package is a folder containing modules and maybe other folders that themselves may contain more folders and modules. Conceptually, it’s a namespace. This simply means that a package’s modules are bound together by a package name, by which they may be referenced.

Circling back to our earlier definition of a module as reusable, importable code, we note that every package is a module — but not every module is a package. A package folder usually contains one file named __init__.py that basically tells Python: “Hey, this directory is a package!” The init file may be empty, or it may contain code to be executed upon package initialization.

You’ve probably come across the term “library” as well. For Python, a library isn’t as clearly defined as a package or a module, but a good rule of thumb is that whenever a package has been published, it may be referred to as a library.

How to Use a Python Package

We’ve mentioned namespaces, publishing packages and importing modules. If any of these terms or concepts aren’t entirely clear to you, we’ve got you! In this section, we’ll cover everything you’ll need to really grasp the pipeline of using Python packages in your code. 

Importing a Python Package

We’ll import a package using the import statement:

Let’s assume that we haven’t yet installed any packages. Python comes with a big collection of pre-installed packages known as the Python Standard Library. It includes tools for a range of use cases, such as text processing and doing math. Let’s import the latter:

You might think of an import statement as a search trigger for a module. Searches are strictly organized: At first, Python looks for a module in the cache, then in the standard library and finally in a list of paths. This list may be accessed after importing sys (another standard library module).

The sys.path command returns all the directories in which Python will try to find a package. It may happen that you’ve downloaded a package but when you try importing it, you get an error:

In such cases, check whether your imported package has been placed in one of Python’s search paths. If it hasn’t, you can always expand your list of search paths:

At that point, the interpreter will have more than one more location to look for packages after receiving an import statement. 

Namespaces and Aliasing

When we had imported the math module, we initialized the math namespace. This means that we can now refer to functions and classes from the math module by way of “dot notation”:

Assume that we were only interested in our math module’s factorial function, and that we’re also tired of using dot notation. In that case, we can proceed as follows:

If you’d like to import multiple resources from the same source, you can simply comma-separate them in the import statement:

There is, however, always a small risk that your variables will clash with other variables in your namespace. What if one of the variables in your code was named log, too? It would overwrite the log function, causing bugs. To avoid that, it’s better to import the package as we did before. If you want to save typing time, you can alias your package to give it a shorter name:

Aliasing is a pretty common technique. Some packages have commonly used aliases: For instance, the numerical computation library NumPy is almost always imported as “np.”

Another option is to import all a module’s resources into your namespace:

However, this method poses serious risk since you usually don’t know all the names contained in a package, increasing the likelihood of your variables being overwritten. It’s for this reason that most seasoned Python programmers will discourage use of the wildcard * in imports. Also, as the Zen of Python states, “namespaces are one honking great idea!” 

How to Install a Python Package

How about packages that are not part of the standard library? The official repository for finding and downloading such third-party packages is the Python Package Index, usually referred to simply as PyPI. To install packages from PyPI, use the package installer pip:

pip can install Python packages from any source, not just PyPI. If you installed Python using Anaconda or Miniconda, you can also use the conda command to install Python packages.

While conda is very easy to use, it’s not as versatile as pip. So if you cannot install a package using conda, you can always try pip instead.

Reloading a Module

If you’re programming in interactive mode, and you change a module’s script, these changes won’t be imported, even if you issue another import statement. In such case, you’ll want to use the reload() function from the importlib library:

How to Create Your Own Python Package

Packaging your code for further use doesn’t necessarily mean you’ll want it published to PyPI. Maybe you just want to share it with a friend, or reuse it yourself. Whatever your aim, there are several files that you should include in your project. We’ve already mentioned the __init__.py file. 

Another important file is setup.py. Using the setuptools package, this file provides detailed information about your project and lists all dependencies — packages required by your code to run properly. 

Publishing to PyPI is beyond the scope of this introductory tutorial. But if you do have a package for distribution, your project should include two more files: a README.md written in Markdown, and a license. Check out the official Python Packaging User Guide (PyPUG) if you want to know more.

Some import Easter Eggs

Easter eggs are hidden goodies that make the developer’s life a bit sweeter. There are a few of them buried in the Python standard library. Try typing import this or import antigravity into your interactive Python console and see for yourself!

Learn More

As a Python programmer, you’ll need to know all about modules and packages. Check out our Introduction to Programming Nanodegree, where you’ll cover many more topics to advance your programming capabilities.

Start Learning