Con este post pretendo explicar como crear un proyecto de Data Mining y preparar el entorno de proyecto, empleando Visual Studio Code como IDE, Git para control de versiones, y uv para gestión de dependencias. Para ello, te propongo un taller para seguir paso a paso.
1.- Herramientas
Para realizar el taller vas a necesitar las siguientes herramientas:
- Visual Studio Code: Es el entorno de desarrollo escogido, donde escribiremos el código y bastantes más cosas.
- Git: Para controlar las versiones del proyecto y poder volver a un estado anterior del mismo si metemos la pata.
- Uv: Para gestionar las dependencias. No voy a emplear el típico fichero requirements.txt, aunque también podemos emplearlo con uv. Personalmente me gusta más uv por su rapidez y sencillez.
Al finalizar, tendrás un proyecto que puede abrirse, ejecutarse y reconstruirse en otro equipo sin copiar el entorno virtual. El proyecto conservará sus dependencias en pyproject.toml y sus versiones exactas en uv.lock.
Instalación de Visual Studio Code
Descarga Visual Studio Code desde https://code.visualstudio.com/ e instálalo con las opciones predeterminadas. En Windows resulta útil activar la opción que añade el comando code al PATH.
Visual Studio Code será el punto de trabajo común: integra el editor, la terminal, la ejecución de Python, los notebooks y Git en una misma ventana.
Instalación de extensiones
Abre el panel Extensions con Ctrl+Shift+X e instala las extensiones siguientes:
- Python, identificador ms-python.python.
- Jupyter, identificador ms-toolsai.jupyter.
La extensión Python permite seleccionar intérpretes, ejecutar y depurar programas. Jupyter añade la edición y ejecución de notebooks; sin ella, los archivos .ipynb no disponen de celdas ni selector de kernel.
Ambas extensiones deben aparecer como instaladas y habilitadas en el espacio de trabajo.
Instalación de Git
Instala Git desde https://git-scm.com/downloads/.
Después, abre una terminal nueva en Visual Studio Code mediante Terminal > New Terminal y ejecuta:
git --version
Git registra la evolución del proyecto. Comprobar la versión confirma que la terminal puede localizarlo antes de inicializar o guardar cambios. La terminal debe mostrar un número de versión, por ejemplo:
git version 2.56.1.windows.1
Si Git solicita identidad al crear el primer commit, configúrala solo para este proyecto:
git config user.name "Nombre Apellidos"
git config user.email "correo@ejemplo.com"
Cada commit necesita una autoría. Al omitir la opción –global, estos datos se aplican únicamente al proyecto en curso y no modifican otros repositorios del equipo.
Instalación de uv
uv administrará la versión de Python, el entorno virtual, las dependencias y el archivo de bloqueo. Para instalarte la versión adecuada para tu equipo visita la página: https://docs.astral.sh/uv/getting-started/installation/
En Windows PowerShell se puede instalar con:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
En macOS o Linux, desde Terminal:
curl -LsSf https://astral.sh/uv/install.sh | sh
Una vez instalado, cierra y vuelve a abrir la terminal. Verifica la instalación:
uv --version
En este punto, si no te reconoce el comando uv, cierra visual Studio Code, vuelve a abrirlo y ejecuta de nuevo el comando anterior.
uv reúne varias tareas del entorno en una sola herramienta. Verificarlo ahora evita descubrir más tarde que el comando no está disponible o que la terminal conserva un PATH antiguo.
2.-Crear el proyecto
Una vez tenemos disponibles todas las herramientas que necesitamos, es el momento de crear el proyecto.
2.1.- Preparar Python
Instalar una versión concreta de Python evita diferencias entre equipos. El proyecto podrá indicar a uv qué intérprete debe usar aunque el sistema tenga otras versiones de Python. Por ejemplo, si queremos instalar la versión 3.13, haríamos:
uv python install 3.13
2.2.- Crear la carpeta
El proyecto va a vivir en una carpeta. Hay que tener muy claro donde lo ubicamos, da igual si creas la carpeta con el administrador de archivos y luego la abres en VS Code, o si lo haces desde el Terminal.
Si lo haces desde terminal, situate en el directorio donde quieras crear tu carpeta y ejecuta:
mkdir <nombre de la carpeta de tu proyecto>
mkdir crea una carpeta nueva, y luego con el comando cd nos movemos a esa carpeta que será la ubicación de trabajo:
cd <nombre de la carpeta de tu proyecto>
En el Terminal puedes ver como estás dentro del directorio que acabas de crear
2.3.-Generar la estructura del proyecto
Con uv vamos a generar la estructura del proyecto, para ello tecleamos en el Terminal el siguiente comando:
uv init
Con este comando, creamos la estructura y los metadatos del proyecto.
Y con el comando:
code .
abrimos exactamente la carpeta como espacio de trabajo en VS Code. Fijate que el comando incorpora un punto al final, separado del comando. Si code no se reconoce, abre la carpeta desde el menú File.
Cuando VS Code pregunte si confías en la carpeta, selecciona la opción de confianza solo si tú la has creado o conoces su procedencia. VS Code limita la ejecución automática de tareas y extensiones en carpetas no confiables. La confianza habilita todas las funciones necesarias para un proyecto propio.
2.4.-Revisar la estructura de proyecto
La estructura exacta puede variar ligeramente con la versión de uv, pero debe incluir estos elementos:
.
|-- .git/
|-- .gitignore
|-- .python-version
|-- README.md
|-- pyproject.toml
`-- src/
`-- taller_python/
`-- __init__.py
Los siguientes elementos cumplen con la siguiente función
- .git/: Guarda el historial local del proyecto.
- .gitignore: Indica qué archivos no deben entrar en Git.
- .python-version: Indica la versión de Python que debe utilizar uv.
- pyproject.toml: Describe el proyecto y declara sus dependencias directas.
Reconocer la función de cada archivo permite detectar errores de ubicación y evita editar a mano elementos que gestiona uv, como el archivo de bloqueo.
3.- El entorno
Con el proyecto creado, pasamos a configurar todo lo que se necesita del entorno.
3.1.- Instalar dependencias
Añade soporte de kernel para poder ejecutar notebooks con el mismo Python del proyecto:
uv add ipykernel
ipykernel conecta un notebook con el intérprete del entorno virtual. Así, las celdas usan las mismas dependencias que los programas del proyecto.
La primera orden de proyecto crea automáticamente la carpeta .venv, actualiza pyproject.toml y genera uv.lock. No instales paquetes manualmente dentro de .venv.
¿Qué consigue uv add? Además de instalar, registra la decisión en pyproject.toml y actualiza uv.lock. Esto hace que las dependencias no dependan de la memoria del desarrollador ni de instalaciones manuales.
3.2.- Comprobar el entorno
Para una primera comprobación del entorno de trabajo, podemos ejecutar los comandos siguientes en el Terminal:
uv run python --version
uv run python -c "import ipykernel; print('Dependencias correctas')"
uv tree
Debe aparecer Python 3.13, el mensaje Dependencias correctas y el árbol de paquetes sin errores. Estas tres comprobaciones validan aspectos distintos: la versión de Python, la importación de una dependencia y la resolución completa del conjunto de paquetes.
3.3.- Sincronizar el entorno
En ocasiones podemos necesitar reconstruir el entorno al completo, a partir de la información guardada. Para ello podemos utilizar el comando sync de uv:
uv sync
Este comando reconstruye el entorno a partir de pyproject.toml y uv.lock. No usa directamente requirements.txt.
Para migrar un proyecto antiguo, puede importarse con:
uv add -r requirements.txt.
Sincronizar obliga al entorno local a coincidir con la descripción del proyecto. Es la operación que se repetirá al recibir el proyecto en otro equipo.
4.- Git
Git es la herramienta que emplearemos para controlar las versiones de nuestro proyecto. Debes conocer como funciona esta herramienta, si tienes alguna duda puedes echar un vistazo rápido a este post.
4.1.- Revisar el fichero .gitignore
Abre .gitignore y verifica que, como mínimo, contiene:
.venv/
__pycache__/
*.py[cod]
.pytest_cache/
.ruff_cache/
.ipynb_checkpoints/
Estas carpetas y archivos se generan de forma automática, dependen del equipo o pueden reconstruirse. Excluirlos mantiene el repositorio pequeño y evita conflictos innecesarios.
Y comprueba que se cumplen las reglas. Por ejemplo, que Git ignora el entorno virtual y una carpeta de caché:
git check-ignore -v .venv
git check-ignore -v __pycache__
No basta con escribir las reglas: esta orden muestra qué línea de .gitignore coincide con cada ruta y permite comprobar el comportamiento antes del primer commit.
Guarda .gitignore, comprueba que estás en la raíz del proyecto y repite la orden.
4.2.- Guarda el punto de partida
Antes del primer commit, revisa exactamente qué archivos se van a guardar con el comando
git status
Este comando muestra los cambios sin preparar.
Para incorporarlos al área de preparación usamos el comando:
git add .
Con el punto incorporamos todos los ficheros y directorios a seguimiento. Todos los que no están en el fichero .gitignore
Si queremos incorporar a seguimiento unicamente un fichero o una carpeta, podemos sustituir el punto por el nombre del elemento en cuestión.
Tecleamos ahora de nuevo en el Terminal:
git status
Esta segunda vez permite revisar la selección antes de hacer un commit, y crear un punto permanente del historial.
Realizamos ahora el commit con un mensaje representativo para que luego podamos identificarlo facilmente
git commit -m "Configura el entorno inicial del proyecto"
Y con el comando log podemos ver el registro de este commit para confirmar su identificador y mensaje, facilitando volver a este estado o comparar cambios posteriores
git log --oneline
Si quieres todo el detalle, puedes hacer sencillamente:
git log
5.- Chuletas de comandos
Finalmente te dejo unas tablas con los comandos principales para git, uv y Terminal. De todos modos, si necesitas conocer los comandos de cada herramienta, normalmente puedes acceder a una lista de los mismos con el comando help. Por ejemplo:
git help
5.1.- Comandos de Git
| Comando | Uso |
|---|---|
| git –version | Comprueba que Git está disponible. |
| git status | Muestra los cambios y el área de preparación. |
| git add . | Prepara todos los cambios de la carpeta actual. |
| git commit -m «mensaje» | Guarda un punto del historial con una descripción. |
| git log –oneline -1 | Muestra el commit más reciente. |
| git check-ignore -v ruta | Explica qué regla hace que Git ignore una ruta. |
5.2.- Comandos de uv
| Comando | Uso |
|---|---|
| uv –version | Comprueba que uv está disponible. |
| uv python install 3.13 | Instala la versión de Python del taller. |
| uv init | Inicializa el proyecto en la carpeta actual. |
| uv add paquete | Añade una dependencia de ejecución. |
| uv add –dev paquete | Añade una herramienta de desarrollo. |
| uv remove paquete | Elimina una dependencia. |
| uv sync | Reconstruye y sincroniza el entorno. |
| uv run python archivo.py | Ejecuta un programa dentro del entorno. |
| uv tree | Muestra el árbol de dependencias. |
5.3.- Comandos de Terminal
| Comando | Uso |
|---|---|
| mkdir nombre | Crea una carpeta. |
| cd nombre | Entra en una carpeta. |
| cd .. | Sube a la carpeta superior. |
| pwd | Muestra la ruta de trabajo actual. |
| ls | Lista el contenido en macOS, Linux y PowerShell. |
| code . | Abre la carpeta actual en Visual Studio Code. |