Organizing Python Projects Into Modules

Contenido del curso

Fundamentos de Clases y Objetos

Encapsulación y Comportamiento de Objetos

Implementar Protocolos con Métodos Especiales

Relaciones entre Clases y Polimorfismo

Diseño Avanzado y Patrones de Software

17
Loading JSON Data to Restore App State
11:43 min

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:007:58

Organizing Python Projects Into Modules

Curso de Python Orientado a Objetos

Clase 9 de 17

Clase 9 / 17

Comentarios (4)4 comentarios

Gabriel Obregón

Hace un año

🧩Organización modular de un proyecto en Python

🎯 Objetivo principal

Transformar el desorden del “código espagueti” en una estructura clara y modular. 🧠 Claves:

Separar responsabilidades.
Seguir la guía PEP 8.
Usar imports ordenados y útiles.

🚨 Problemas del código espagueti

❌ Todo en un solo archivo ().

❌ Dificultad para ubicar clases o funciones.

❌ Código duplicado o mal organizado.

❌ Mantenimiento lento y propenso a errores.

📉 Resultado: deuda técnica y una arquitectura confusa.

✅ Ventajas de modularizar

🌱 Claridad estructural.

⚙️ Mantenimiento más simple.

🔁 Reutilización de clases.

🔍 Búsqueda más rápida.

🧩 Código escalable y limpio.

🧱 Pilares de una buena modularización

🔹 Una responsabilidad por archivo.

🔹 Clases separadas del código ejecutable.

🔹 Imports precisos para conectar los módulos.

🔹 Nada de código que se ejecute dentro de los módulos.

🔹 Lógica principal centralizada en main.py.

🗂️ Estructura recomendada del proyecto

📘

→ Define Libro y LibroFisico.

→ Todo lo relacionado con los libros.

🏛️

→ Contiene la clase Biblioteca.

→ Gestiona préstamos y operaciones de biblioteca.

👩‍🎓

→ Define Estudiante, Profesor y el protocolo Solicitante.

→ Se encarga de los usuarios.

⚙️

→ Punto de entrada del sistema.

→ Crea objetos, conecta clases y ejecuta el flujo.

🔗 Cómo usar los imports

📍 Reglas clave:

Importa solo lo que necesites.
Agrupa varias clases del mismo módulo.
Coloca todos los imports al inicio del archivo.
Repetir imports está bien si se usan en varios lugares.
Usa nombres de archivo en plural si contienen varias clases.

Ejemplo (main.py):

from Usuarios import Estudiante, Profesor

from Libros import Libro, LibroFisico

from Biblioteca import Biblioteca

town_library = Biblioteca()

est1 = Estudiante("Ana")

prof1 = Profesor("Luis")

lib1 = Libro("Python 101")

lib2 = LibroFisico("Estructuras de Datos")

print(town_library.libros)

🧾 Orden de imports según PEP 8

📚 1. Biblioteca estándar: import os import sys

🌍 2. Librerías de terceros: import requests

🏗️ 3. Módulos propios del proyecto: from Usuarios import Estudiante, Profesor from Libros import Libro, LibroFisico from Biblioteca import Biblioteca

🔤 Dentro de cada grupo → orden alfabético.

⬜ Deja una línea en blanco entre grupos.

⚙️ Herramientas recomendadas

🧰 Ruff (en Visual Studio Code):

Organiza los imports automáticamente al guardar.
Ahorra tiempo y evita errores de formato.

💡 Tip adicional: Proyectos con archivos cortos y modulares ayudan a los modelos de lenguaje (LLMs) a analizar el código con menos costo y mejor contexto.

Samuel Alejandro Hurtado

Hace 10 meses

uv add --dev ruff

ruff check

para instalar ruff con uv

Samuel Steven Bernal Martínez

Hace un año

Recuerden que pueden instalar ruff con: uv pip install ruff

y luego ruff check, o también configurar en VsCode (eso lo enseñan en el curso anterior sobre pep8 y entornos virtuales)

Luis Martinez

Profesor

Hace un año

Sí, también basta con solo instalar la ext de vscode "ruff" que viene con el binario pre installado.

Sergio Daniel Flamenco

Hace 6 meses

🧑‍💻🫶

Recursos

Splitting Python code into modules turns a chaotic single file project into a clean, professional structure where each file has one responsibility. You will learn how to refactor a library project into separate modules, apply Python's import system, and follow PEP 8 conventions to keep your codebase maintainable and ready to scale.

Why should you split your Python project into modules?

When a project grows, keeping every class inside main.py creates what we call spaghetti code: logic piled up without any relationship to the file name. Think of it as stacking every book in a library on a single table. It works with five books. It collapses with five hundred.

In the original project, two files carried all the weight: a main.py mixing unrelated logic and a usuarios.py that even executed code on import. That violates a core principle: one file should do one thing. Around [00:48], the refactor begins by identifying this technical debt and planning a cleaner architecture.

What is a Python module? A module is a .py file that groups related code, like classes or functions, so it can be imported and reused from other files.

How do you separate classes into their own files?

The first move is creating a dedicated libros.py file and cutting every book related class out of main.py. The same logic applies to the Biblioteca class, which goes into a new biblioteca.py. The usuarios.py file is also cleaned up, removing any execution code so it only defines classes and protocols.

This brings two practical wins:

Finding code is trivial. If you need the Libro class, you open libros.py and you are done.
Files become shorter, which matters when you feed context to an LLM. At [02:14], the instructor points out that passing eight lines instead of twenty directly reduces token costs when generating code with AI assistants.

A small but powerful convention: name your files in plural (libros.py, usuarios.py) when they hold multiple related classes. It signals that the file groups several definitions of the same domain.

What goes inside main.py after the refactor?

After moving classes out, main.py stops being a dumping ground and becomes the entry point. Its only job is to import the pieces and orchestrate them: create the library, instantiate students and professors, build the books, and connect everything together.

That separation of concerns is the heart of modular design. Each file defines. main.py connects.

How does the Python import system connect your modules?

Once classes live in different files, Python needs explicit imports to find them. The syntax from usuarios import Estudiante tells the interpreter where to look. When you need more than one class from the same module, you chain them with commas:

python from usuarios import Estudiante, Profesor, SolicitanteProtocol from libros import Libro, LibroFisico from biblioteca import Biblioteca

Repeating imports across files is fine and expected. Each module declares what it actually uses, so usuarios.py and libros.py can both import from typing without conflict.

Where should imports go in a Python file? At the top of the file, grouped in three blocks separated by a blank line: standard library first, third party packages second, your own application modules last. Inside each block, order them alphabetically.

This ordering follows PEP 8, the official Python style guide. Tools like Ruff automate it: every time you save, imports get sorted and unused ones are removed. In the demo, the Libro import disappeared on its own once it was no longer referenced.

What is the difference between a module and a package?

A module is a single .py file. A package is a folder containing multiple modules, usually with an __init__.py to mark it as importable. The library project uses modules. As it grows, grouping usuarios.py, libros.py, and biblioteca.py under a package would be the next step.

How do you verify the refactor works?

With the structure in place, main.py reads top to bottom like a script: create the Biblioteca, create the users, create the books, attach the books to the library, and print the result. Running python main.py from the terminal confirms everything still works, this time with clear responsibilities per file.

A few takeaways worth keeping close:

One file, one responsibility. Classes in their own modules, execution in main.py.
Plural file names for modules holding several related classes.
Imports at the top, sorted by PEP 8, ideally automated with Ruff.
main.py as the entry point that wires everything together.

The next step is making this modular code more robust with exception handling, so the upcoming loan system can deal with real world errors without breaking. If you have refactored a messy project recently, share what your before and after looked like in the comments.

Resumen

Why should you split your Python project into modules?

What is a Python module? A module is a .py file that groups related code, like classes or functions, so it can be imported and reused from other files.

How do you separate classes into their own files?

This brings two practical wins:

Finding code is trivial. If you need the Libro class, you open libros.py and you are done.
Files become shorter, which matters when you feed context to an LLM. At [02:14], the instructor points out that passing eight lines instead of twenty directly reduces token costs when generating code with AI assistants.

What goes inside main.py after the refactor?

That separation of concerns is the heart of modular design. Each file defines. main.py connects.

How does the Python import system connect your modules?

python from usuarios import Estudiante, Profesor, SolicitanteProtocol from libros import Libro, LibroFisico from biblioteca import Biblioteca

Repeating imports across files is fine and expected. Each module declares what it actually uses, so usuarios.py and libros.py can both import from typing without conflict.

Where should imports go in a Python file? At the top of the file, grouped in three blocks separated by a blank line: standard library first, third party packages second, your own application modules last. Inside each block, order them alphabetically.

What is the difference between a module and a package?

How do you verify the refactor works?

A few takeaways worth keeping close:

One file, one responsibility. Classes in their own modules, execution in main.py.
Plural file names for modules holding several related classes.
Imports at the top, sorted by PEP 8, ideally automated with Ruff.
main.py as the entry point that wires everything together.

Fundamentos de Clases y Objetos

OOP in Python: Modeling Real World Systems

Classes and Objects in Python Explained

Instance Methods That Make Python Objects Act

Private Attributes and Data Integrity in Python

Encapsulación y Comportamiento de Objetos

Herencia en Python para evitar duplicación de código

Simple Inheritance With Python Classes

Python Protocol for Flexible Polymorphism

Implementar Protocolos con Métodos Especiales

Composition Over Inheritance in Python

Organizing Python Projects Into Modules

Custom Exceptions That Make Python Errors Clear

Sistema de préstamos con identificación de usuarios en Python

Relaciones entre Clases y Polimorfismo

Book Search and Lending Flow in Python OOP

Clases abstractas en Python con ABC y @abstractmethod

Decoradores property en Python para atributos con validación

Decoradores @staticmethod y @classmethod en Python

Serialización de objetos Python a JSON para persistencia de datos

Diseño Avanzado y Patrones de Software

Loading JSON Data to Restore App State

Organizing Python Projects Into Modules

Progreso del curso

Fundamentos de Clases y Objetos

Encapsulación y Comportamiento de Objetos

Implementar Protocolos con Métodos Especiales

Relaciones entre Clases y Polimorfismo

Diseño Avanzado y Patrones de Software

Recursos

Recursos