Understanding Modules and Packages in Python — SitePoint


On this article, we’ll have a look at a few of the ideas concerned when structuring our Python code utilizing modules and packages. We’ll discover ways to create our personal modules, how one can outline capabilities and lessons, and the way we will use them in different modules or packages. We’ll additionally have a look at how one can create packages, by organizing associated modules in a listing, and how one can import modules from packages. Lastly, we’ll discover a few of Python’s built-in modules and packages.

By the tip of this tutorial, we’ll have a stable understanding of how one can construction our code utilizing modules and packages, significantly enhancing our capability to put in writing maintainable, reusable, and readable code.

Desk of Contents
  1. Introducing Modules and Packages
  2. Working with Modules
  3. Introducing Packages
  4. The __all__ attribute
  5. The Python Commonplace Library and Well-liked Third-party Packages
  6. Packaging and Distribution
  7. Conclusion

Introducing Modules and Packages

A module in Python is a single file that accommodates Python code within the type of capabilities, executable statements, variables, and lessons. A module acts as a self-contained unit of code that may be imported and utilized in different packages or modules.

A bundle, then again, is a group of modules organized in a listing. Packages enable us to group a number of associated modules collectively beneath a typical namespace, making it simpler to arrange and construction our code base.

Breaking code down into modules and packages affords immense advantages:

  • Maintainability. Breaking down code into modules helps us make modifications within the impartial components of the general utility with out affecting the entire utility, because the modules are designed to solely take care of one a part of the appliance.

  • Reusability. This can be a key a part of software program improvement, the place we write code as soon as and we will use it in many alternative components of an utility as many occasions as we wish. This allows us to put in writing clear and dry code.

  • Collaboration. Modular code enhances and permits collaboration. Completely different groups can work on completely different components of the identical utility on the identical time with out interfering with one another’s work.

  • Readability. Breaking down code into modules and packages enhances code readability. We are able to simply inform what’s occurring in a file. We’d, for instance, have a file named databaseConnection.py: simply from the title we will inform that this file offers with database connections.

Working with Modules

Modules might be imported and utilized in different packages, modules, and packages. They’re very helpful in an utility, since they break down the appliance operate into smaller, manageable, and logical items.

As an illustration, say we wish to create an online utility: the appliance goes to want code for connecting to a database, code for creating database fashions, code that’s going to be executed when a person visits a sure route, and so forth.

We are able to put all of the code in a single file, however then the code in a short time turns into unmaintainable and unreadable. By utilizing modules, we will break down the code into items which are extra manageable. We’ll put all of the code wanted to connect with the database in a single file, code for database fashions is put in one other file, and code for the routes right into a module. Breaking the code down into these modules promotes group, reusability, and maintainability.

Making a easy module

It’s fairly easy to create a module in Python. Say now we have various associated capabilities, variables, and lessons: we might put them in a single module, and provides the module any title we wish, however it’s advisable to present our modules descriptive names — simply as with capabilities, variables, lessons.

To create a module in Python, open up an IDE or textual content editor, create a file, and provides it a descriptive title and a .py extension. For this instance, let’s name it pattern.py and enter within the following code:

sample_variable  = "This can be a string variable within the pattern.py module"

def say_hello(title):
  return f"Good day, {title}  welcome to this straightforward module."

def add(a, b):
  return f"The sum of {a} + {b} is = {a+b}"

print(add(2, 3))

The code above defines a module named pattern.py. It accommodates a variable named sample_variable whose worth is the string "This can be a string variable within the pattern.py module". This module additionally accommodates two operate definitions. When known as, the say_hello() operate takes in a reputation parameter, and it returns a welcome message if we go a reputation to it. The add() operate returns the sum of two numbers which were handed to it.

Whereas modules are meant for use in different components of this system or an utility, we will run them independently. To run this module, we have to have Python put in in our improvement surroundings. We are able to run it on the terminal utilizing the next command:

python pattern.py 

Or we will use the next command:

python3 pattern.py

This can return the next output:

This can be a string variable in the pattern.py module
Good day, kabaki welcome to this straightforward module.
The sum of 2 + 3 is = 5

For one-off module utilization, we will run it as a standalone, however most modules are made for use in different modules or different components of a Python program. So to make use of variables, capabilities, and lessons from one module in one other module now we have to import the module. There are other ways of importing modules, so let’s have a look at them.

Utilizing the import assertion

We are able to use the import assertion to make the contents of 1 module accessible to be used in one other module. Think about our pattern.py from above: to make use of its contents in one other module, we simply import it:

import pattern

print(pattern.add(2, 3))

The code above exhibits how one can import the capabilities from the pattern.py module, making them accessible to be used within the another_module.py. Notice that, after we import a module, we don’t embody the .py extension; Python robotically is aware of we’re importing a module.

Utilizing the from key phrase

We are able to additionally use the from key phrase to import particular capabilities or variables. Say a module has a lot of capabilities and variables outlined in it and we don’t wish to use all of them. We are able to specify the capabilities or variables we wish to use, utilizing the from key phrase:

from pattern import add

print(add(10, 4))

The code above exhibits that we’ve particularly imported the add() operate from the pattern module.

One other advantage of utilizing the from key phrase is that we’ll run the imported operate with out namespacing it or prefixing it with the title of its guardian module. As an alternative, we’ll use the operate like we’ve outlined it within the file the place we’re utilizing it. This results in extra concise and readable code.

Utilizing as

We are able to use as to supply an alias or an alternate title for the module.

At occasions, we might outline module names which are fairly lengthy or unreadable. Python gives a manner of giving the module imports an alternate or alias, which we will use to discuss with them within the modules we’re importing them into. To do that, we’ll use the as key phrase:

import pattern as sp

outcome = sp.add(5, 5)

This code exhibits an import of the pattern module, the place the module is being given an alternate title sp. So utilizing sp is simply the identical as calling pattern. Subsequently, utilizing the alias, now we have entry to the variables and capabilities, in the identical manner we might if we have been utilizing the unique title.

Utilizing these three strategies, we’re in a position to make use of the variables or capabilities from one module in one other module, enhancing the readability of our utility the place we don’t must put the code in a single file.

Whereas naming our modules, it’s good follow to make use of lowercase letters and separate phrases with underscores. As an illustration, if now we have a module for dealing with database connections, we would title it database_connection.py. To keep away from naming conflicts, attempt to decide on descriptive and distinctive names for modules. If a module title may trigger a reputation conflict with a Python built-in key phrase or module from a third-party library, think about using a special title or including a prefix that’s related to the challenge. Additionally, keep in mind that names are case-sensitive in Python, so make sure that to make use of the right module title when importing.

Total, utilizing modules lets us create and arrange our code in a readable and maintainable manner. And that is very helpful — whether or not we’re engaged on a small script or a big utility. Later, we’ll have a look at some widespread Python commonplace library modules.

Introducing Packages

A bundle in Python is a manner of organizing associated modules right into a listing. This gives a greater manner of organizing code, enabling us to group modules that serve a typical function or are a part of the identical element.

Packages are notably helpful when structuring bigger tasks or libraries. As an illustration, contemplate the case of an online utility the place now we have code for various database fashions, views, and utilities.

It might make a number of sense if we created a fashions bundle with completely different modules for the completely different fashions in an utility. Say our internet app is a running a blog utility: potential fashions might be a customers mannequin and a posts mannequin; we might then create a module for person administration, and a module for posts administration, after which put them within the fashions bundle.

It’s necessary to reiterate at this level that modules are particular person information containing Python code: they assist put associated capabilities, lessons, and variables inside a single file. In distinction, packages are directories that comprise a number of modules or subpackages. They supply the next degree of group for our code, by grouping associated modules and enabling us to create extra structured and maintainable tasks.

Constructing and managing packages

Whereas packages arrange associated code modules in a single listing, simply placing the modules in a listing doesn’t make it a bundle. For Python to determine a listing as a bundle or a subpackage, the listing should comprise a particular file named __init__.py.

This file notifies Python that the listing containing it needs to be handled as a bundle or a subpackage. This file might be empty, and more often than not it’s, however it could actually additionally comprise initialization code, and it performs an important position in Python’s bundle construction and import mechanisms. So utilizing __init__.py tells Python that we’re deliberately making a bundle, thereby serving to it differentiate between a bundle and an abnormal listing.

Packages can have a hierarchical construction, which means we will create subpackages inside our packages to additional arrange our code. This allows finer and extra managed separation of elements and performance. Think about the next instance:

├── __init__.py
├── module1.py
└── subpackage/
  ├── __init__.py
  ├── submodule1.py
  └── submodule2.py

This diagram exhibits my_package is the primary bundle, and subpackage is a subpackage inside it. Each directories have an __init__.py file. Utilizing this sort of construction helps us arrange our code right into a significant hierarchy.

Creating packages and subpackages

To create a bundle, we first create a listing that’s going to comprise our modules. Then we create an __init__.py file. Then we create our modules in it, together with any subpackages.

Say we’re constructing a calculator utility: let’s create a bundle for numerous calculations, so create a listing in our terminal or our IDE and title it calculator.

Within the listing, create the __init__.py file, then create some modules. Let’s create three modules, add.py, subtract.py, and multiply.py. Ultimately, we’ll have a listing construction just like this:

├── __init__.py
├── add.py
├── subtract.py
└── multiply.py

Let’s put some samples in these information. Open the add.py module and put within the following code:

def add(a, b):
  Provides two numbers and returns the outcome.

  :param a: First quantity.
  :param b: Second quantity.
  :return: Sum of a and b.
  return a + b

This creates a module for addition, separating it from different calculations. Let’s create yet one more module for subtraction. Open the subtract.py file and put the next code in it:

def subtract(a, b):
  Subtracts two numbers and returns the outcome.

  :param a: First quantity.
  :param b: Second quantity.
  :return: Distinction of a and b.
  return a - b

So in our utility, if we want to benefit from the calculator modules, we’ll simply import the bundle. There are other ways to import from a bundle, so let’s have a look at them within the subsequent part.

Importing from packages

To import modules from packages or subpackages, there are two foremost methods. We are able to both use a relative import or an absolute import.

Absolute imports

Absolute imports are used to immediately import modules or subpackages from the top-level bundle, the place we specify the total path to the module or bundle we wish to import.

Right here’s an instance of importing the add module from the calculator bundle:

from calculator.add import add

outcome = add(5, 9)


The above instance exhibits an exterior module — calculate.py — that imports the add() operate from the add module utilizing an absolute import by specifying absolutely the path to the operate.

Relative imports

Relative imports are used to import modules or packages relative to the present module’s place within the bundle hierarchy. Relative imports are specified utilizing dots (.) to point the extent of relative positioning.

As a way to reveal relative imports, let’s create a subpackage within the calculator bundle, name the subpackage multiply, then transfer the multiply.py module into that subpackage, in order that we’ll have an up to date bundle construction like this:

├── __init__.py
├── add.py
├── subtract.py
└── multiply/
  ├── __init__.py
  └── multiply.py

With this setup, we will now use relative imports to entry the multiply module from different modules inside the calculator bundle or its subpackages. As an illustration, if we had a module contained in the calculator bundle that should import the multiply module, we might use the code beneath:

from .multiply import multiply 

outcome = multiply(5, 9)

Total, relative imports are notably helpful for imports inside a bundle and subpackage construction.

The __all__ attribute

There are occasions after we might use all modules from a bundle or subpackages, or all capabilities and variables from a module, so typing out all names turns into fairly cumbersome. So we wish a method to specify that we’re importing capabilities and variables {that a} module has to supply or all modules that bundle affords.

To arrange what might be imported when a person desires to import all choices from a module or a bundle, Python has the __all__ attribute, which is a particular attribute that’s utilized in modules or packages to regulate what will get imported when a person makes use of the from module import * assertion. This attribute permits us to specify a listing of names that will likely be thought-about “public” and will likely be imported when the wildcard (*) import is used.

Utilizing the __all__ attribute in modules

In a module, we will outline the __all__ attribute to explicitly specify which names needs to be imported when the from module import * assertion is used. This helps forestall unintended imports of inside names, offering a transparent manner of exhibiting the capabilities that may be imported publicly and people which are meant to be used solely within the module.

Right here’s an instance:

__all__ = ['public_function', 'public_variable']

def public_function():
  return "This can be a public operate."

def _internal_function():
  return "That is an inside operate."

public_variable = "This can be a public variable."
_internal_variable = "That is an inside variable."

The code above defines a module named my_module.py, and with the __all__ attribute being set, solely the public_function and the public_variable will likely be imported when the from my_module import * is used. The operate and variable names beginning with an underscore gained’t be imported.

It’s necessary to notice a number of issues. If we all know absolutely the paths to the capabilities beginning with an underscore, we will nonetheless import them to our code. Nonetheless, that goes in opposition to the conference of encapsulation, because the underscore (_) denotes them as non-public members of the module and signifies that they shouldn’t be used outdoors the module. So it’s good follow to comply with Python programming conventions even when Python doesn’t implement strict encapsulation.

Utilizing the __all__ attribute in packages

The __all__ attribute will also be utilized in __init__.py information inside a bundle or subpackage to regulate the default habits of wildcard imports for submodules or subpackages. This will help be sure that solely particular modules are imported when utilizing wildcard imports on packages:

__all__ = ['submodule1', 'subpackage']

from . import submodule1
from . import subpackage

This instance exhibits an __init__.py file specifying that solely submodule1 and subpackage1 will likely be imported when utilizing from my_package import *. Different submodules or subpackages gained’t be imported by default.

As within the case of modules, we will nonetheless import the opposite modules not specified within the __all__ attribute listing if we all know their absolute paths. So the __all__ attribute acts as a conference relatively than as a strict rule. It’s meant to speak what can be utilized publicly from a module or a bundle. It’s, nonetheless, advisable that express imports (import module_name) be used as an alternative of wildcard imports (from module_name import *).

The Python Commonplace Library and Well-liked Third-party Packages

The Python Commonplace Library is a group of modules and packages that come included with the Python interpreter set up. These modules present a variety of functionalities — from working with information sorts and performing file operations to dealing with community communication and implementing numerous algorithms.

A number of the generally used modules within the Python commonplace library embody:

  • os: offers us an API for interacting with the host working system
  • math: gives a variety of mathematical capabilities and constants (helpful when performing numerous mathematical operations in our code)
  • datetime: permits us to work with dates and time in our code
  • json: permits us to deal with JSON information in our code
  • argparse: permits us to create command line interfaces
  • csv: permits us to learn and write CSV information

The usual library accommodates much more modules than these few examples, every with its personal space of utility, implementing the advantages of breaking code down into modules. To be taught extra concerning the modules on provide, go to the official Python documentation.

The Python Bundle Index and third-party packages

The Python Bundle Index (PyPI) is a repository of third-party Python packages that reach the performance of the Python Commonplace Library. These packages cowl a variety of domains and supply options to varied programming challenges. These packages are created by the open-source group. We are able to additionally create our personal bundle and publish it with the repository.

To handle third-party packages, Python makes use of a instrument known as pip (Python Bundle Installer). pip permits us to simply set up, improve, and handle packages from PyPI.

We are able to set up any third-party library utilizing pip:

pip set up package_name

As an illustration, to put in the Django bundle (which is used for internet improvement) we will run this:

pip set up django

Listed here are examples of some in style third-party packages:

  • NumPy: a strong library for numerical computing in Python. It gives help for giant, multi-dimensional arrays and matrices, together with quite a lot of mathematical capabilities to function on these arrays.

  • Pandas: a library for information manipulation and evaluation. It gives information constructions like DataFrames for effectively dealing with and analyzing tabular information.

  • Matplotlib: a widely-used library for creating static, animated, and interactive visualizations in Python. It affords a MATLAB-like interface for plotting numerous varieties of graphs and charts.

  • SciPy: constructed on high of NumPy, SciPy gives extra capabilities for optimization, integration, linear algebra, sign processing, and extra.

  • Django: a high-level internet framework for constructing internet purposes. It follows the Mannequin-View-Controller (MVC) structure and affords options for dealing with databases, URLs, templates, and extra.

  • Flask: one other internet framework, Flask is extra light-weight and minimal in comparison with Django. It’s excellent for constructing smaller internet purposes or APIs.

  • Requests: a bundle for making HTTP requests and dealing with responses. It simplifies working with internet APIs and fetching information from the Web.

The packages listed above are only a few examples of the huge ecosystem of third-party packages accessible on PyPI. Packages like these can save us a number of effort and time.

Packaging and Distribution

Packaging and distributing our Python tasks permits others to simply set up and use our code. That is particularly necessary after we wish to share our libraries or purposes with a wider viewers. Right here’s a quick overview of how one can bundle and distribute our Python tasks.

setuptools for packaging

setuptools is a bundle that gives constructing and packaging capabilities for our Python tasks. It simplifies the method of making distribution packages, together with supply distributions (sdist) and binary distributions (bdist). To make use of setuptools, we usually create a setup.py script in our challenge’s root listing.

Right here’s a easy instance of a setup.py script:

from setuptools import setup, find_packages

      "console_scripts": [
          "my_script = my_project.my_module:main",

Within the script above, we specify the challenge’s title, model, packages, dependencies, and any entry factors utilizing the setup() operate.

twine for publishing

As soon as our challenge is correctly packaged utilizing setuptools, we will use twine to add our bundle to PyPI for distribution. twine is a instrument that helps us securely add packages to PyPI.

To make use of twine, we have to set up it:

pip set up twine

We then go to our challenge’s root listing and use the next command to add our bundle:

twine add dist/*

Remember that distributing packages on PyPI requires creating an account and following sure pointers. It’s advisable that we learn the official PyPI documentation for detailed directions on packaging and distribution.

A number of the pointers:

  • Versioning. Correctly model packages to point modifications and updates. This helps customers perceive what’s new and ensures compatibility.

  • Documentation. Embrace clear documentation for the code, describing how one can set up and use our bundle. Use instruments like Sphinx to generate documentation.

  • Licensing. Clearly specify the license beneath which the bundle is distributed to make sure customers perceive how they will use it.

  • Testing. Implement testing to make sure the bundle capabilities as anticipated. Instruments like pytest might be useful for writing and working assessments.

By correctly packaging and distributing our Python tasks, we make it simpler for others to entry and use our code, contributing to a extra collaborative and open-source improvement surroundings.


On this tutorial, we’ve explored the ideas of modules and packages in Python and their significance in writing well-organized, maintainable, and reusable code.

Modules are particular person information containing Python code that encapsulate capabilities, lessons, and variables. They promote code group inside a single script and facilitate code reuse throughout a number of scripts.

Packages take the idea of modularity to the following degree by permitting us to arrange associated modules into listing hierarchies. This hierarchical construction enhances code group in bigger tasks and fosters a transparent separation of issues.

As we proceed our Python journey, mastering the artwork of modular programming with modules and packages will undoubtedly contribute to us turning into more adept and environment friendly builders. By leveraging these ideas, we’ll be higher outfitted to deal with advanced tasks and collaborate successfully with different builders.


Please enter your comment!
Please enter your name here