In short Python Modules are just files with Python code. Python modules refer to files with the ‘.py’ extension that contain:
- Python statements
- Python classes
- Python definitions (functions)
- Data in any form acceptable to python, eg(lists, dicts, objects, arrays)
Usually, modules would be grouped in packages that can be installed in your local development environment, after which you can import functions from those packages and use them within your code.
However, you can also create your own python modules (you can create your own packages, but we’ll stick to the basics of modules for now).
Clean, reusable code. It’s what every developer aspires to.
To this end, we have reusable functions that are written to:
- accept parameters,
| also called arguments (*args) and/or keyword arguments (**kwargs) |
- handle the data within those parameters,
- and return said data.
What if we wanted to take it a step further? If we wanted to, not only write clean reusable code but also organize and store our code in clearer, structured modules?
This also comes into play when using design patterns, writing and organizing data classes, etc.
This is where modules come in – Not only can we have code that can be used and reused within a project, we can create modules that can be used in any project. In this post, we’re going to talk specifically about Python Modules.
- What are python modules?
- How can we use them?
- How do we install them?
- How can we import them?
In the world of web development, certain terminology can be confusing.
If you’ve recently begun learning python you might ask “what is the difference between an app, and a module?”.
An ‘app’ can be just one ‘module’ within a larger app. However, while you can have multiple python modules within one app, you cannot have apps within a module. This could be confusing, especially if early on in your coding journey, you’ve begun learning Python and working with, say Django.
- We create our main project, in this case, it’s a site for a local photographer so we’ll call it photography_philosophy
- we create the main app and let’s say we create an app specifically to handle the logic for the initial landing page (home)
- and an app to handle the logic for site Users (users)
- Our project folder structure looks like this,
We add the apps to the INSTALLED_APPS config var (environment variable) in settings.py but we have a typo. The app folder is called ‘users’, but we’ve put ‘user’ into our settings.
We get a | ModuleNotFoundError | when trying to run the project.
“But it’s an app, not a module? The command to start it is literally, startapp?”
This is an example of how the terms ‘app’ and ‘module’ can sometimes be used interchangeably and might cause confusion.
Creating a basic python module
At its most basic, this is as simple as creating a file, giving it the ‘.py’ extension, and adding a few lines of code.
- I’ll create a file: app.py and in this file, I’ll write a small function that takes in a single parameter (argument, or *args) and prints the value of that parameter to the terminal.
- Then I’ll call the function and pass in a familiar string, the foundation on which all coding tutorials are built, the ever-present ‘Hello World!’.
There we have it. We’ve written our first python module! We’ll go further into this later in the article.
How to Install Modules in Python
You’ll need the Python package manager (pip)
Python has a package manager called pip which is used to install packages, either system-wide or within a specific environment. Hold on, “I thought we were installing modules?” you may be thinking.
Well, in essence, we are, but here’s where understanding certain terminology comes into play.
What is a package vs what is a module?
Think of a package as a group of related files (modules) and associated functions/classes that are within those modules that work together to form a complete package.
If you’ve worked with NodeJS or React, you may have used one of the following, npx or npm (node package manager). We can start to see how, across coding languages, across frameworks, certain patterns start to emerge, as regards coding concepts and even some naming conventions (packages/apps/modules …etc).
Back to python however and the syntax for installing a Python module using pip is as follows:
pip install module-name
If you’re working with Gitpod the syntax is almost identical, you just need to specify the version
pip3 install module-name
For this to work, you must have pip installed, and the installation process differs according to your system. The following would be to install pip system-wide.
Installing pip on Windows
Ensure that you have at least Python 3.4 or newer installed. Python versions beyond 3.4 ship with pip by default, so it should already be installed. The following examples and commands should be run from the terminal.
If you’re running these commands outside your IDE | Integrated Development Environment | run from a Git Bash or PowerShell terminal on Windows, or a Bash terminal on macOS and Linux).
You can check which version of python you have installed by running this command:
However, if pip is not available, just run this command:
py -3 -m ensurepip
Installing pip on macOS
First, open a Bash terminal and download the get-pip.py installation file with curl:
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
And then run the script to install pip:
Installing pip on Linux
First, open a Bash terminal and download the package using this command:
And install it with the following command:
sudo python get-pip.py
If you’re using one of either Debian or Ubuntu you might be able to use the systems package manager with one of the following commands:
sudo apt install python-pip
sudo apt install python3-pip
Have you noticed something? The file we’re downloading and then running is a python module, get-pip.py – but more than that, it’s a module that then installs the entire pip package and any associated modules.
From here most of the time it’s simply a case of referring to the documentation for the latest stable release of whichever package you are looking to install.
How to Import Modules in Python
Importing code from one module to another
While the syntax may vary, depending on:
- the project setup
- exactly what you are importing, etc
the underlying concept remains the same. Think of it as asking someone to fetch something specific from a specific location. In a real-life situation a person might ask someone, “hey would you please bring me the car keys, they are on my desk, thanks”.
In pythonic form were one to ask Python to hand them their car keys:
from desk import car_keys
Let’s assume the desk is located in a separate room, the home office, for example, we could use dot notation to specify the desk within the home office:
from home_office.desk import car_keys
Alternatively, we could import the entire desk from home_office, and then access the car_keys:
from home_office import desk my_car_keys = desk.car_keys
Once a module has been imported, we can consider it to be a class, whose variables (keys, objects, functions) can be accessed.
Let’s look at how this could be applied in a coding situation.
For this, I’m going to use an example of importing directly from Python, and also some examples using a combination of built-in packages/modules from Django, as well as local user-created modules.
Importing built-in modules directly from Python.
Python comes with its own built-in modules, methods, and functions. To dive further into this, check out the Python Standard Library. For this example, we’ll use Python’s built-in datetime. This assumes you have Python installed on your system.
To import directly from python is as simple as:
For how to use the specific python module we use google, or whichever is your preferred search engine.
Once you’ve imported the module we can use it:
import datetime today = datetime.datetime.now() print(today)
If you’re wondering why I’ve used datetime.datetime, that’s because the overall package is called datetime, and the main class of the package is also called datetime, the specific function I’m finally accessing is now() which will give me the current time. To delve into the datetime module further click here.
Importing in Django.
In this example:
- I’m using dot notation to import a specific module, render, from a Django module called shortcuts
- I’m then returning this module from my index() function, and passing in the request and a template as arguments (*args)
- The render method (function) is a built-in Django module that expects one required argument, request, and can take in multiple arguments (*args) and specific keyword arguments (**kwargs)
- You can take a look at the source code here. As per the Django documentation it: Combines a given template with a given context dictionary and returns an HttpResponse object with that rendered text.
The render module can also take in a context object – This is extremely useful because we can pass any data we want to a template via this context object using | ‘key’: value | pairs. Here’s how it looks in the code:
In the above example,
- I’m defining a variable on line 7, welcome_text, assigning it a string value.
- On line 10 I define a context object, called context, and within that object, I declare a ‘key’: this key I’ve called ‘welcome_text’ and I assign it that same variable welcome_text I defined on line 7.
Essentially I’m telling Django. This key ‘welcome_text’ in this context object, has the value of the variable welcome_text on line 7.
- I’m also now storing the route to the template in a variable called template on line 9
- Both context and template are keyword arguments (**kwargs) that the render() method expects
And now the magic. On the actual template file, index.html, I can access that context object and any ‘key’ within to display the value stored at that ‘key’:
Remember the key was ‘welcome_text’:
And the result when I run the project (I’ve added some basic styling using bootstrap):
And there we have it. We imported a module from Django and used it to render data (in this case a string) to a template. This method can be used to pass other forms of data to a template as well.
Let’s get back to Python Modules and how to work with them.
Importing various types of data.
So far we’ve only talked about importing modules and functions, but you can also import data models, classes, lists, and dicts. In Django, you can import Forms from one module into another. Essentially, if you can define it, you can import it from one module into another. I’ll show one brief example:
The example below is from a project using Django as its framework, the module here is a forms.py module and the class is defining a form.
- Notice the first import on line 1, importing forms from django
- Now look at line 6, I’m passing that forms module into my UserProfileImageForm class, and via dot notation importing a specific module/method from within the forms module: ModelForm.
Below is a separate module, this one is called views.py:
- I’m importing that UserProfileImageForm class on line 6.
- I’m using from .forms because I’m importing from a local module located in the same directory, and the dot . instructs Django to import from the forms.py module within this specific directory.
How to write your own Modules in Python
Let’s write a couple of basic Python modules and import from one module into the other. We’ll take our first example app.py – In it, we had a very basic function and we’re going to move that function into an entirely different module.
We’re going to:
- Create a file called print.py
- Cut the function (only the function) definition from app.py and paste it into our new print.py file.
- Import that same function from print.py back into app.py
Let’s look at our file structure. We now have 2 modules – note they are both on the same level in the same root directory
And here are the contents of our two modules:
We run our main module with the command:
Specify the python version if working in Gitpod:
And the result
Congratulations. You’ve just created 2 python modules and imported a function from one to the other.
This is a very basic example, and in the course of being a developer there will surely come times where you may encounter tricky issues, but the underlying concept remains the same.
“Hold on! In the Django example, we used from .forms but in the above example, we used from print? Why didn’t you have to pre-face from print with a full stop as in the previous Django example from .forms?”
I didn’t have to use from .print import, because this is an example with only one root folder and only those 2 modules, print.py, and app.py.
- I didn’t have to specify “use the corresponding module directly within this folder” using a full stop: from .forms because that was already implied
- There’s only one folder, and only 2 files, print.py, and app.py. Because of this, the command: import print doesn’t need to be more specific than that.
A Django project would most likely be far more complex, with multiple apps, and modules, and specifying from .module import directly tells the main Django app, “import directly from within this app, from within this folder”.
Defining a module that already exists.
One thing to be aware of is to make sure you’re not re-defining a module that already exists. Here are a couple of examples: math and datetime. Both of these are already defined pre-built Python modules.
Be aware that defining your own can cause issues. If you run into such a situation, simply re-name your module making sure to update any instances where you are importing this module to reflect your changes to the module name.
Importing from other modules can also be done using dot notation.
For example, if I know the exact function I want to access, I could import the entire module and simply use the function I want as seen below:
While this is possible, it might not always be the best idea due to potentially importing a lot of code that you may not need. Assuming that the print module has multiple functions, if you only need the one function, only import that one function from that module (as in our first example,
from print import printValue)
You can also import modules as x where x would be the variable of your choosing. In this case, whatever you set the name as it will hold any functions/code from within the module that you imported.
Here’s an example:
The same can be done for individual functions:
The result of which will be the same. I run the app.py module and the string ‘Hello World!’, is printed to the terminal:
Excellent! I hope you’ve enjoyed this introduction to Python modules. If you want to go further in-depth and read more about how to create your own packages, here’s a link to the docs: Python Packages.
John Traas, Code Institute Graduate
How can you use Python?
If you are interested in getting keyed up with Python, you can learn with our Full Stack Diploma. To find out more, schedule a call with an education advisor through the form at the bottom of this page. Alternatively, to find out more about Python, click here.