Python Packages (and Modules!) Explained

butteredwaffles
Sep 4, 2018 · 4 min read

If you’ve ever opened a text file and written Python code in it, you’ve created a module! A module is a file with a .py extension that can be imported into other modules, run by itself, or both.

You may have seen if __name__ == '__main__' in a few Python modules. __name__ is usually the variable holding the name of the module itself (so if you had a module called music.py, __name__ would hold music.) However, if you’re running the module directly through thepython command or some other means, __name__ will be __main__ instead. So when you see that if statement, it means that that block of code will only run if this module is being run directly (i.e. not imported.)

What are packages and how do I use them?

Packages are collections of modules that you create and use.

You can import modules in the directory you run the program in directly, but if you want to import modules from other directories, you have to let Python know that the directory you’re importing from is a Python package. To do that, you put a file called __init__.py in that directory. Take this example straight from the Python3 docs:

sound/                          Top-level package
__init__.py Initialize the sound package
formats/ Subpackage for file format conversions
__init__.py
wavread.py
wavwrite.py
aiffread.py
aiffwrite.py
auread.py
auwrite.py
...
effects/ Subpackage for sound effects
__init__.py
echo.py
surround.py
reverse.py
...
filters/ Subpackage for filters
__init__.py
equalizer.py
vocoder.py
karaoke.py
...

Let’s say you wanted to use the equalizer module in your separate program (i.e. one not in this directory). You would do this:

import sound.filters.equalizer as equalizer

Since sound is the root package, that would be the first section of the import statement. filters is the package containing the equalizer module, so that’s the next section. equalizer is what we’re actually trying to import, so that’s the last section! Import statements use . as a way to show the directory tree. (Imports also conventionally go at the top of a file!)

The as statement isn’t necessarily needed, but if you didn’t change it, you would have to type out sound.filters.equalizer every time you wanted to use a method from equalizer.py! Using as, we only have to type equalizer. As an alternative, you could also do it this way:

from sound.filters import equalizer

This would also achieve the same effect as the as statement. The from statement is used to only get specific parts of modules and packages. Let’s say you only wanted one variable from the equalizer module — the frequency. You could do this:

from sound.filters.equalizer import frequency

Now, Python will only import that single variable from equalizer.

You don’t have to just import one item, either. If the module is in the same package (or if the variable/function is in the same module, depending on how you’re importing) then you can chain them using commas.

from sound.filters import equalizer, vocoder

If you wanted to import *everything* from a module, you could use an asterisk.

from sound.filters.equalizer import *

This is against PEP convention, though. They prefer you to be verbose with what you’re importing.

To import everything from a package, though, the package author has to do something a bit more special. Remember __init__.py? The file that causes Python to recognize the package? Inside that, you have to set a variable called __all__ containing all the modules in the package, like this:

__all__ = ['equalizer', 'vocoder', 'karaoke']

That way, import * will import those three modules.

Tidbits of Relative Import-ance

You can also import modules relatively. Let’s say you’re in the echo module and you want to call something from equalizer. That import statement would look like this.

from ..filters import equalizer

. seperates folders, as we learned earlier, so that’s the same thing as going effects -> sound -> filters.

Getting External Packages

There’s several websites to get useful packages that you need — with the largest being PyPi. To install packages from PyPi, you run the pip command included in your Python installation. As an example, let’s say you wanted to install the requests library. You would find the link — which in this case is https://pypi.org/project/requests/.

At the top, it tells you how to install it.

pip install requests

If you’re on Linux and not in a virtual environment, you’ll have to run it with sudo (although I recommend having a virtualenv). Now, you can just import requests! It’s that easy. Go take this knowledge and make your new programs sectioned and organized!

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade