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 ]; then
    echo "✅ Script ejecutado exitosamente"
elif [ $EXIT_CODE -eq 1 ]; then
    echo "❌ Error en la aplicación"
else
    echo "🐍 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 python3
import sys

print(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 python3
import sys
import json
from datetime import datetime

def main():
    if len(sys.argv) < 2:
        print("Uso: python procesador_datos.py <archivo> [--json]")
        sys.exit(1)
    
    archivo = sys.argv[1]
    formato_json = "--json" in sys.argv
    
    resultado = {
        "archivo": archivo,
        "timestamp": str(datetime.now()),
        "lineas_procesadas": 100,
        "estado": "completado"
    }
    
    if formato_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! 🚀🐍☕