Pymux es un multiplexor de terminales escrito en Python, similar a tmux, que permite a los usuarios crear y gestionar múltiples sesiones, ventanas y paneles dentro de una única ventana terminal. Esta guía ayudará a los desarrolladores a comprender cómo contribuir al proyecto Pymux, incluyendo la preparación del entorno, análisis de módulos principales, métodos de desarrollo de extensiones y el proceso de contribución.

1. Preparación del Entorno de Desarrollo

1.1 Clonar el Repositorio

Primero, clona el repositorio del proyecto Pymux localmente:

git clone https://gitcode.com/gh_mirrors/py/pymux
cd pymux

1.2 Instalar Dependencias

Pymux utiliza Python para su desarrollo y requiere instalar dependencias específicas. Aunque el proyecto no incluye un archivo requirements.txt explícito, se pueden inferir las dependencias principales como prompt_toolkit entre otras librerías de interfaz de terminal. Se recomienda usar un entorno virtual para el desarrollo:

python -m venv venv
source venv/bin/activate  # Linux/Mac
# o en Windows
venv\Scripts\activate
pip install prompt_toolkit

1.3 Ejecutar Pruebas

Pymux proporciona scripts de ejemplo que pueden ejecutarse para probar la funcionalidad:

python -m pymux.entry_points.run_pymux

2. Análisis de la Estructura del Proyecto

La estructura de código de Pymux es clara y se divide principalmente en los siguientes módulos:

• pymux/commands/: Contiene toda la lógica de procesamiento de comandos, como gestión de ventanas y operaciones de paneles
• pymux/client/: Código relacionado con el cliente, que maneja la comunicación con el servidor
• pymux/key_bindings.py: Configuración de atajos de teclado, definiendo operaciones de acceso rápido
• pymux/layout.py: Gestión de diseños, controlando la disposición de ventanas y paneles
• pymux/server.py: Código del servidor, manejando conexiones de múltiples clientes

Nota: Pymux soporta conexiones de múltiples clientes, como se muestra en la imagen que ilustra varias sesiones de terminal conectadas simultáneamente al mismo servidor Pymux

3. Métodos de Desarrollo de Extensiones

3.1 Agregar Nuevos Comandos

Pymux utiliza un patrón de decoradores para definir comandos. En pymux/commands/commands.py, se puede ver el decorador @comando utilizado para registrar nuevos comandos:

def comando(nombre, opciones=''):
    """Decorador para todos los comandos."""
    def decorador(func):
        def contenedor_comando(pymux, argumentos):
            # Analizar parámetros
            opciones_recibidas = docopt.docopt(
                'Uso:\n    %s %s' % (nombre, opciones),
                argumentos,
                ayuda=False)
            # Llamar a la función de procesamiento
            func(pymux, opciones_recibidas)
            # Refrescar la interfaz
            pymux.invalidar()
        COMANDOS_A_MANEJADORES[nombre] = contenedor_comando
        return contenedor_comando
    return decorador

Para agregar un nuevo comando, simplemente se crea una función que utilice el decorador @comando. Por ejemplo, agregar un comando simple "hola":

@comando('hola', '[-n NOMBRE]')
def comando_hola(pymux, args):
    nombre = args.get('--nombre', 'Mundo')
    pymux.mostrar_mensaje(f"¡Hola, {nombre}!")

3.2 Personalizar Atajos de Teclado

Pymux permite agregar atajos de teclado personalizados mediante el método agregar_enlace_personalizado. En pymux/key_bindings.py se puede encontrar la implementación relevante:

def agregar_enlace_personalizado(self, nombre_tecla, comando, argumentos, necesita_prefijo=False):
    # Lógica de implementación

Por ejemplo, agregar un atajo de teclado Ctrl+a h para activar el comando "hola":

pymux.atajos_teclado.agregar_enlace_personalizado(
    nombre_tecla='h',
    comando='hola',
    argumentos=['--nombre', 'Pymux'],
    necesita_prefijo=True
)

3.3 Modificar la Gestión de Diseños

La gestión de diseños se implementa en pymux/layout.py. Pymux soporta múltiples métodos de disposición, como división horizontal y vertical. Se puede extender la funcionalidad de diseño modificando la clase Diseño o agregando nuevas clases de diseño.

Nota: La interfaz de modo copia de Pymux, que demuestra su flexible capacidad de gestión de diseños

4. Proceso de Contribución de Código

4.1 Enviar Issue

Antes de contribuir código, se recomienda enviar un Issue describiendo el problema a resolver o la función a agregar, discutiendo su viabilidad con los mantenedores del proyecto.

4.2 Escribir Código

Se debe seguir el estilo y estructura de código existentes del proyecto, asegurando que el nuevo código tenga comentarios adecuados. Los archivos principales incluyen:

• Implementación de comandos: pymux/commands/commands.py
• Atajos de teclado: pymux/key_bindings.py
• Gestión de diseños: pymux/layout.py

4.3 Probar Código

Asegurarse de que la nueva funcionalidad tenga pruebas correspondientes, que pueden ejecutarse mediante scripts de ejemplo:

python examples/prueba_color_real.py

4.4 Enviar Pull Request

Envía tus modificaciones al repositorio de GitHub y crea un Pull Request para su revisión por parte de los mantenedores del proyecto.

5. Técnicas Avanzadas de Extensión

5.1 Implementar Temas de Color Personalizados

Pymux soporta visualización en color verdadero, y se pueden personalizar los temas de color modificando pymux/estilo.py. Por ejemplo, modificar los colores del menú:

Nota: La interfaz de menú de color verdadero de Pymux, mostrando su rico soporte de colores

5.2 Agregar Nuevos Tipos de Cliente

Pymux soporta múltiples tipos de clientes, y en el directorio pymux/client/ se pueden encontrar implemantaciones de clientes para diferentes plataformas. Se pueden agregar nuevos tipos de cliente heredando de la clase ClienteBase.

5.3 Extender el Sistema de Configuración

El sistema de configuración de Pymux se implementa en pymux/opciones.py, y se pueden agregar nuevas opciones de configuración para mejorar la personalización del software.