Estructura del proyecto y pyproject.toml
Organice un paquete
Estructura del proyecto y pyproject.toml es una lección gratuita de Python Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Python Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Python Academy incluye 4 lecciones en total.
Por qué empaquetar el código
Un script vive en su equipo; cualquier persona puede instalar un paquete mediante pip install. El empaquetado convierte una carpeta de código en una unidad distribuible, versionada y reutilizable.
El primer paso consiste en tener una estructura de proyecto limpia y un archivo de configuración.
La estructura src
La estructura recomendada coloca el código que se puede importar dentro de un directorio src/:
src/mypackage/__init__.pysrc/mypackage/core.pypyproject.tomlREADME.mdytests/
La estructura src evita que importe accidentalmente el código desde la raíz del proyecto en lugar de importar la copia instalada.
El archivo __init__.py
__init__.py marca un directorio como un paquete que se puede importar y se ejecuta la primera vez que se importa el paquete. También es el lugar donde se expone la API pública al importar nombres clave.
Incluso un archivo __init__.py vacío basta para crear un paquete.
package_dir = 'src/mypackage'
files = ['__init__.py', 'core.py', 'utils.py']
for f in files:
print(package_dir + '/' + f)
print('Importable as:', 'mypackage')Qué es pyproject.toml
pyproject.toml es el archivo de configuración único y estandarizado (PEP 518/621) para el empaquetado moderno de Python. Sustituye al antiguo setup.py en la mayoría de los proyectos y las herramientas de compilación lo leen.
Usa el formato TOML: secciones entre corchetes y líneas con la forma clave = valor.
La tabla build-system
La tabla [build-system] indica a las herramientas cómo compilar su paquete. Una opción habitual es:
requires = ['setuptools', 'wheel']build-backend = 'setuptools.build_meta'
Otros backends son Hatchling y Flit; la idea es la misma.
La tabla project
La tabla [project] contiene los metadatos: name, version, description, authors, readme, requires-python y dependencies. Esto es lo que los usuarios ven en PyPI.
Considérela como el documento de identidad de su paquete.
project = {
'name': 'mytool',
'version': '0.1.0',
'requires-python': '>=3.9',
'dependencies': ['requests>=2.0'],
}
for k, v in project.items():
print(k, '=', v)Reglas para los nombres
El nombre del paquete debe ser único en PyPI y sigue reglas de normalización: no distingue entre mayúsculas y minúsculas, y los guiones se consideran equivalentes a los guiones bajos. Compruebe la disponibilidad antes de elegir un nombre para evitar conflictos al cargarlo.
name = 'My_Cool.Tool'
normalized = name.lower().replace('_', '-').replace('.', '-')
print('PyPI normalized name:', normalized)Declarar dependencias
Indique las dependencias de ejecución en dependencies con restricciones de versión como 'requests>=2.28,<3'. Los extras opcionales se indican en [project.optional-dependencies] y se pueden instalar mediante pip install mytool[dev].
Mantenga las restricciones tan flexibles como sea seguro para que su paquete pueda coexistir con otros.
Puntos de entrada
Para distribuir una herramienta de línea de comandos, añada una entrada en [project.scripts], como mytool = 'mypackage.cli:main'. Después de instalarla, escribir mytool ejecuta esa función. Así es como las interfaces de línea de comandos como black o pytest exponen sus comandos.
Incluir archivos que no son código
Los archivos de datos (plantillas, JSON) no se incluyen automáticamente. Configure los datos del paquete en su backend de compilación para que los archivos se incluyan dentro del wheel. Olvidarlo es una causa habitual de errores en los que algo funciona localmente, pero falla al instalarlo.
Instalaciones editables para desarrollo
Durante el desarrollo, instale el paquete en modo editable mediante pip install -e .. Los cambios en el código fuente surten efecto inmediatamente sin necesidad de reinstalarlo. Esto depende de que pyproject.toml sea correcto, otra razón para configurarlo desde el principio.
Las instalaciones editables ofrecen el ciclo de retroalimentación más rápido mientras desarrolla un paquete.
Comprobación rápida
Compruebe sus conocimientos sobre la estructura de proyectos.
Recapitulación
Ha definido la estructura de un paquete:
- Use la estructura src, con
__init__.pypara marcar los paquetes pyproject.tomles la configuración estándar:[build-system]y[project]- Declare
name,version,requires-pythonydependencies - Añada puntos de entrada
[project.scripts]para las interfaces de línea de comandos y configure los datos del paquete
Preguntas frecuentes
¿La lección «Estructura del proyecto y pyproject.toml» es gratis?
Sí — el texto completo de «Estructura del proyecto y pyproject.toml» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Python Academy, actualiza a CoddyKit PRO. El curso de Python Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Estructura del proyecto y pyproject.toml»?
Organice un paquete Practicas Python Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar Python Academy?
No se requiere experiencia previa. Python Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.
¿Cuánto tiempo toma la lección «Estructura del proyecto y pyproject.toml»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de Python Academy?
Sí. Cada lección de Python Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Estructura del proyecto y pyproject.toml
- Compilación con build
- Versionado y metadatos
- Publicación con twine