How many Python classes should I put in one file?

Python code is organized in files called "modules" and groups of related modules called "packages". The question of how many classes to put in one file is a common organizational concern that affects code maintainability and readability.

Understanding Python Modules

A module is a distinct unit that may have one or more closely-related classes. Modules need to be imported before they are read, used, maintained and extended if needed. So a module is a unit of reuse.

The rule is this: a module is the unit of reuse. Everything in Python libraries and other Python applications is either a module or a package of modules.

General Guidelines

There is no strict limit on how many classes one can put in a file or a module. However, here are some practical guidelines:

Single Responsibility Principle

Group related classes together in one module. For example, all classes related to user authentication can be in auth.py −

# auth.py
class User:
    def __init__(self, username, email):
        self.username = username
        self.email = email

class UserAuth:
    def login(self, user):
        return f"Logging in {user.username}"
    
    def logout(self, user):
        return f"Logging out {user.username}"

# Usage
user = User("john", "john@example.com")
auth = UserAuth()
print(auth.login(user))

Logging in john

Size Considerations

Keep modules manageable in size. A file with 500+ lines becomes harder to navigate. Consider splitting large modules −

# Instead of one large file, split into focused modules
# shapes.py
class Circle:
    def __init__(self, radius):
        self.radius = radius
    
    def area(self):
        return 3.14159 * self.radius ** 2

class Rectangle:
    def __init__(self, width, height):
        self.width = width
        self.height = height
    
    def area(self):
        return self.width * self.height

# Usage
circle = Circle(5)
rectangle = Rectangle(4, 6)
print(f"Circle area: {circle.area()}")
print(f"Rectangle area: {rectangle.area()}")

Circle area: 78.53975
Rectangle area: 24

Best Practices

Factors to Consider

The decision depends on several factors:

• Project size: Small projects can have multiple classes per file
• Class complexity: Large classes should be in separate files
• Team collaboration: Smaller files reduce merge conflicts
• Logical grouping: Related functionality should stay together

Conclusion

There's no strict limit on classes per file in Python. Organize classes based on logical relationships, keep files manageable in size, and prioritize code readability and maintainability over rigid rules.