Java Python Executor 🐍➡️☕

Una aplicación Java-Maven que permite ejecutar scripts Python, con soporte completo para entornos virtuales, gestión de dependencias y una interfaz de línea de comandos intuitiva.

📋 Tabla de Contenidos

• Características
• Requisitos
• Instalación
• Uso Básico
• Ejemplos
• Gestión de Entornos Virtuales
• Opciones de Línea de Comandos
• Códigos de Salida
• Estructura del Proyecto
• Solución de Problemas

✨ Características

• ✅ Ejecución de scripts Python desde Java
• 🐍 Soporte para entornos virtuales (venv)
• 📦 Gestión automática de dependencias Python
• 🔧 Interfaz CLI intuitiva con ayuda integrada
• 🔄 Múltiples argumentos para scripts Python
• 📁 Validación automática de archivos y permisos
• ⚡ Configuración persistente de entornos

🛠️ Requisitos

Software necesario:

• Java 11 o superior
• Python 3 o superior
• Maven 3.6+ (solo para compilación)

Verificación:

# Verificar Java
java -version
# Verificar Python
python --version
# o
python3 --version
# Verificar Maven (para desarrollo)
mvn -version

📦 Instalación

1. Compilar desde fuente:

# Clonar el proyecto via HTTPS
git clone https://github.com/alexdevzz/java-python-executor.git
# o via SSH
git clone git@github.com:alexdevzz/java-python-executor.git
# Compilar con Maven
mvn clean package
# El JAR se creará en: target/java-python-executor.jar

2. Verificar instalación:

java -jar java-python-executor.jar --help

🚀 Uso Básico

Sintaxis general:

java -jar java-python-executor.jar [OPCIONES] script.py [ARGUMENTOS_PYTHON...]

Ejecutar script simple:

java -jar java-python-executor.jar mi_script.py

Ejecutar script con argumentos:

java -jar java-python-executor.jar mi_script.py arg1 arg2 arg3

Ejecutar script usando entorno virtual:

java -jar java-python-executor.jar mi_script.py arg1 --venv /ruta/venv

📖 Ejemplos

Ejemplo 1: Script de horóscopo

# Sin entorno virtual
java -jar java-python-executor.jar horoscope.py aries
# Con entorno virtual
java -jar java-python-executor.jar horoscope.py taurus --venv C:\venvs\horoscope_venv

Ejemplo 2: Análisis de datos

# Crear entorno con dependencias
java -jar java-python-executor.jar --create-env data-science --python 3 --install numpy pandas matplotlib
# Ejecutar análisis
java -jar java-python-executor.jar analizar_datos.py dataset.csv --venv venvs/data-science

Ejemplo 3: API web

# Crear entorno para API
java -jar java-python-executor.jar --create-env fastapi-env \
--install fastapi uvicorn
# Ejecutar servidor
java -jar java-python-executor.jar api_server.py \
--venv venvs/fastapi-env --host 0.0.0.0 --port 8080

🐍 Gestión de Entornos Virtuales

Listar entornos configurados:

java -jar java-python-executor.jar --list-envs

Salida ejemplo:

📋 ENTORNOS VIRTUALES CONFIGURADOS
Nombre Ruta Estado
----------------------------------------------------------------------
data-science ./venvs/data-science ✅ VÁLIDO
web-dev ./venvs/web-dev ✅ VÁLIDO
ml-env ./venvs/ml-env ❌ NO VÁLIDO

Crear nuevo entorno:

# Versión básica
java -jar java-python-executor.jar --create-env mi-entorno
# Con versión específica de Python
java -jar java-python-executor.jar --create-env proyecto37 --python 3.7
# Con paquetes preinstalados
java -jar java-python-executor.jar --create-env data-tools --install numpy pandas scikit-learn jupyter
# Ruta personalizada
java -jar java-python-executor.jar --create-env custom-location --venv /opt/entornos/mi-proyecto

Validar entorno:

Los entornos se validan automáticamente al:

1. Listarlos (muestra estado ✅/❌)
2. Ejecutar scripts (verifica Python ejecutable)
3. Usar --venv (comprueba estructura de venv)

⚙️ Opciones de Línea de Comandos

Opciones principales:

Opción	Forma larga	Descripción
-h	--help	Muestra ayuda detallada
-v RUTA	--venv RUTA	Usar entorno virtual en RUTA
-l	--list-envs	Listar entornos virtuales configurados
-c NOMBRE	--create-env NOMBRE	Crear nuevo entorno virtual

Opciones para creación de entornos:

Opción	Descripción	Ejemplo
--python VERSION	Versión de Python	--python 3.9
--install PKG...	Paquetes a instalar	--install numpy pandas

Separador de argumentos:

Usa -- para separar argumentos de Java de los de Python:

java -jar app.jar script.py --venv myenv -- --verbose --output=resultado.json
# ↑ args Java ↑ ↑ args Python ↑

📊 Códigos de Salida

La aplicación retorna códigos de salida estándar:

Código	Significado
0	✅ Éxito - Script ejecutado correctamente
1	❌ Error - Error general de la aplicación

Interpretar resultados:

# Ejecutar y capturar código de salida
java -jar java-python-executor.jar script.py
EXIT_CODE=$?if [ $EXIT_CODE-eq 0 ];thenecho"✅ Script ejecutado exitosamente"elif [ $EXIT_CODE-eq 1 ];thenecho"❌ Error en la aplicación"elseecho"🐍 Error en script Python (código: $EXIT_CODE)"fi

📁 Estructura del Proyecto

java-python-executor/
├── src/main/java/com/alexdevzz/pythonrunner/
│ ├── cli/
│ │ └── CommandLineArgs.java # Parser de argumentos CLI
│ ├── core/
│ │ ├── PythonRunner.java # Ejecutor principal
│ │ ├── VirtualEnvManager.java # Gestionador de entornos virtuales
│ │ ├── PythonService.java # Servicio con lógica de negocio
│ │ └── ExecutionResult.java # Resultados de ejecución
│ └── Main.java # Punto de entrada
├── target/
│ └── java-python-executor.jar # JAR ejecutable
├── python-envs.properties # Configuración de entornos (auto)
├── venvs/ # Entornos virtuales (auto)
├── README.md # Documentación (este archivo)
└── pom.xml # Configuración Maven

Archivos generados automáticamente:

• python-envs.properties: Se crea al primer uso, almacena configuraciones de entornos virtuales creados
• venvs/: Directorio para entornos virtuales creados
• Logs: La salida se muestra en consola, errores en stderr

🔧 Solución de Problemas

Problemas comunes y soluciones:

1. "Python no encontrado"

# Verificar instalación
python --version
# Especificar Python 3 explícitamente# Editar PythonRunner.java línea: command.add("python3");

2. "Entorno virtual no válido"

# Verificar estructura del venv
ls -la /ruta/venv/
# Debe contener: bin/python o Scripts/python.exe# Crear nuevo entorno si está corrupto
java -jar app.jar --create-env nuevo-venv

3. "Permiso denegado"

# Dar permisos de ejecución al script
chmod +x script.py
# Verificar permisos del directorio
ls -ld /ruta/script.py

4. "Error al instalar paquetes"

# Actualizar pip primero
java -jar app.jar --create-env test --install pip --upgrade
# Instalar paquetes por separado
java -jar app.jar --create-env test --install numpy
java -jar app.jar --create-env test --install pandas

5. "Memoria insuficiente"

# Aumentar memoria Java
java -Xmx2g -jar java-python-executor.jar script.py

Modo debug (para desarrollo):

# Ver información detallada
java -Ddebug=true -jar java-python-executor.jar script.py
# Log verbose
java -Dverbose=true -jar java-python-executor.jar script.py

📝 Scripts Python de Ejemplo

ejemplo_simple.py:

#!/usr/bin/env python3importsysprint(f"¡Hola desde Python {sys.version}!")
print(f"Argumentos recibidos: {sys.argv[1:]}")
print("Script ejecutado exitosamente")
sys.exit(0)

procesador_datos.py:

#!/usr/bin/env python3importsysimportjsonfromdatetimeimportdatetimedefmain():
iflen(sys.argv) <2:
print("Uso: python procesador_datos.py <archivo> [--json]")
sys.exit(1)
archivo=sys.argv[1]
formato_json="--json"insys.argvresultado= {
"archivo": archivo,
"timestamp": str(datetime.now()),
"lineas_procesadas": 100,
"estado": "completado"
}
ifformato_json:
print(json.dumps(resultado, indent=2))
else:
print(f"Procesado: {archivo}")
print(f"Líneas: {resultado['lineas_procesadas']}")
print(f"Hora: {resultado['timestamp']}")
sys.exit(0)
if__name__=="__main__":
main()

🤝 Contribuir

1. Reportar issues: Describe el problema con detalles
2. Sugerir features: Explica el caso de uso
3. Pull requests: Sigue el estilo de código existente
4. Documentación: Mejora este README si encuentras errores

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver archivo LICENSE para más detalles.

🙏 Agradecimientos

• Equipo Java por el ecosistema robusto
• Comunidad Python por los entornos virtuales
• Maven por la gestión de dependencias
• Contribuidores que mejoran la herramienta

---

¿Preguntas o problemas?

• Revisa la sección Solución de Problemas
• Ejecuta java -jar java-python-executor.jar --help
• Crea un issue en el repositorio

¡Feliz ejecución de scripts Python desde Java! 🚀🐍☕