Quick answer: A Python module is an importable namespace, usually a .py file, that groups functions, classes, constants, and implementation details. A class defines a type and can create instances with their own state and behavior. Use a module to organize related code across an import boundary; use a class when several objects share operations but need separate state, lifecycle, or invariants.
A Python module is a .py file that groups reusable code under one importable namespace. A Python class defines a new object type with attributes and methods.
The main references are Python’s module tutorial, the class tutorial, and the import system reference.
Use a module to organize functions, constants, and related helpers. Use a class when you need many objects that share behavior but each carry their own state.
The two tools often work together. A module can contain one or more classes, and other modules can import those classes.
The decision is mostly about responsibility. If the code is only grouped for reuse, a module is enough. If the code needs objects with separate state and behavior, a class is often the better fit.
Avoid creating classes only to hold unrelated helper functions. That style adds ceremony without improving the design.
Prefer the smallest clear structure.
What A Module Does
A module gives names a home and makes them importable from another file.
PI = 3.14159
def circle_area(radius):
return PI * radius * radius
print(circle_area(3))
If this code lives in geometry.py, another file can import geometry and call geometry.circle_area(3).
A module is loaded once per interpreter process and then reused from Python’s module cache.
Because imports run top-level code, keep module startup light. Put expensive work inside functions or guarded entry points instead of doing it during import.
What A Class Does
A class defines a type of object. Each instance can hold its own state.
class User:
def __init__(self, name):
self.name = name
def greeting(self):
return f"Hello, {self.name}"
ada = User("Ada")
print(ada.greeting())
The class describes the behavior. The instance ada carries the specific name.
Create a class when several related values and operations belong together as one concept.
Classes are especially useful when many instances should behave the same way while carrying different data, such as users, products, requests, jobs, or parsed records.
Import A Class From A Module
A module can export a class just like it exports a function.
from dataclasses import dataclass
@dataclass
class Product:
name: str
price: float
item = Product("Book", 12.50)
print(item.name, item.price)
In a real project, this class might live in models.py, while application code imports it where needed.
Keep import paths simple. If a class belongs to a domain concept, put it in a module name that reflects that concept.
For small projects, a single module can hold a few related classes. For larger projects, split modules by purpose so imports stay understandable.
Use A Module For Stateless Helpers
When behavior does not need per-object state, a plain function in a module is often better than a class.
def slugify(text):
return text.lower().replace(" ", "-")
print(slugify("Python Class Guide"))
This helper has no object state. Wrapping it in a class would add structure without adding value.
Modules are a good home for utility functions, parsing helpers, constants, and small pure transformations.
Module functions are also easy to test because the input and output are explicit. If a helper does not need object state, a function keeps the call straightforward.
Use A Class For Shared Behavior And State
A class is useful when each object needs its own data plus methods that operate on that data.
class Counter:
def __init__(self):
self.count = 0
def add(self):
self.count += 1
return self.count
counter = Counter()
print(counter.add())
print(counter.add())
Each Counter() instance gets its own count. That is the kind of state a class handles well.
If there will only ever be one global state holder, consider whether a module-level function or configuration object would be simpler.
When state changes over time, a class can make ownership clearer. Each instance owns its own attributes, so tests can create fresh instances without resetting module-level state.
Choose The Simpler Tool
Start with a module and functions when the code only needs organization. Move to a class when the design needs multiple instances, methods, and object state.
def total_price(items):
return sum(item["price"] for item in items)
items = [
{"name": "Book", "price": 12.50},
{"name": "Pen", "price": 2.00},
]
print(total_price(items))
This function works well because the data is simple and the operation is direct.
The practical rule is: modules organize code for import, classes define object types, and good Python code often uses both without forcing every helper into a class.
Refactor toward a class when related functions keep passing the same data bundle around. Keep a module-level function when the operation is independent and easy to describe with inputs and output.
Put Related Functions In A Module
A module is a file-level namespace. Importing it gives callers a stable qualified name, which prevents unrelated helper functions from colliding and makes ownership visible in the call site.
# geometry.py
def area(width, height):
return width * height
# application.py
import geometry
print(geometry.area(3, 4))
Use A Class For Per-Object State
A class is appropriate when each instance needs its own data while sharing methods. The instance argument connects the method to the state that belongs to that object.
class Counter:
def __init__(self, start=0):
self.value = start
def increment(self):
self.value += 1
return self.value
first = Counter()
second = Counter(10)
print(first.increment(), second.increment())
A Module Can Define Classes
These boundaries are complementary, not competing. A module can export a class and supporting functions, while the class instances carry runtime state. Keep public names small and document the intended import path.
# inventory.py
class Item:
def __init__(self, name):
self.name = name
def make_item(name):
return Item(name)
# caller
from inventory import Item, make_item
print(Item("book").name)
print(make_item("pen").name)
Choose The Boundary From Ownership
Use a module for stateless utilities or a cohesive implementation namespace. Use a class when invariants must be maintained across operations or when multiple independent objects exist. Avoid a class that only wraps one unrelated function.
class Score:
def __init__(self):
self._value = 0
def add(self, points):
if points < 0:
raise ValueError("points must not be negative")
self._value += points
@property
def value(self):
return self._value
score = Score()
score.add(5)
print(score.value)
Python’s official modules tutorial and classes tutorial describe importable namespaces, class definitions, and instances. Related references include importing classes, nested classes, and collection modules.
For related organization patterns, compare importing classes, nested classes, and collection modules when deciding where state and behavior belong.
Frequently Asked Questions
What is the difference between a Python class and module?
A module organizes names in an importable file, while a class bundles behavior and data into a type whose instances hold state.
Can a module contain a class?
Yes. A module commonly defines and exports one or more classes, functions, and constants.
When should I use a class?
Use a class when multiple objects share behavior and each object needs its own state or lifecycle.
When should I use a module?
Use a module to group related functions, constants, classes, and importable implementation details.
Nice !