Python Order Syntax (VS Code Extension)

Extensión para Visual Studio Code que reordena y formatea archivos de Python siguiendo una estructura jerárquica lógica, limpia y legible basada en las mejores prácticas de PEP 8 y el análisis sintáctico nativo mediante AST (Abstract Syntax Trees).

🚀 Características y Reglas de Ordenamiento

La extensión reorganiza cualquier archivo de código Python de arriba a abajo en el siguiente orden estricto:

1. Shebang y Encoding Cookie (ej. #!/usr/bin/env python3, # -*- coding: utf-8 -*-).
2. Docstring del Módulo (si existe al inicio del archivo).
3. Imports Agrupados y Ordenados Alfabéticamente (separados por 1 línea en blanco):
   • Standard Library (módulos nativos de Python: os, sys, json, typing, ast, etc.).
   • Third-party (paquetes externos: requests, numpy, fastapi, pydantic, etc.).
   • Locales / Relativos (from . import ..., from .local_module import ...).
4. Constantes Globales y Configuración (variables en MAYÚSCULAS o _MAYÚSCULAS).
5. Clases (separadas por 2 líneas según PEP 8) con sus miembros internos reorganizados:
   • Docstring de clase y variables/atributos de clase al inicio.
   • Constructores e inicializadores (__new__, __init__, __post_init__).
   • Métodos públicos (en orden alfabético o de definición).
   • Métodos privados y protegidos (aquellos que comienzan con _).
   • Métodos mágicos / dunder restantes (__str__, __repr__, etc.).
6. Funciones Aisladas / Helpers de nivel superior (separadas por 2 líneas en blanco).
7. Otros Statements Top-Level.
8. Bloque de Ejecución Principal (if __name__ == '__main__':).

Preservación Total: Todo el código se analiza con el módulo nativo ast de Python, manteniendo intactos todos los comentarios inline, comentarios de bloques, docstrings y la sintaxis del programa.

⌨️ Atajos y Formas de Uso

1. Paleta de Comandos

• Presiona Ctrl + Shift + P (o Cmd + Shift + P en macOS).
• Escribe y selecciona: Python: Order Code Logically.

2. Atajo de Teclado Rápido

• Windows / Linux: Ctrl + Alt + O
• macOS: Cmd + Alt + O (Solo activo cuando el editor tiene el foco en un archivo de Python).

3. Menú Contextual (Clic Derecho)

• Haz clic derecho en cualquier parte de un archivo .py y selecciona Python: Order Code Logically.

🛠️ Cómo Probar la Extensión Localmente en VS Code

Sigue estos sencillos pasos para probar la extensión en tu entorno local:

Paso 1: Abrir la carpeta del proyecto en VS Code

1. Abre VS Code.
2. Ve a File > Open Folder... y selecciona la carpeta del proyecto: d:\Plugins, Extensiones y Mods\Extensiones de Visual Studio Code\Python Order Syntax Logically

Paso 2: Instalar dependencias y compilar

Si abres una terminal integrada en la carpeta del proyecto (`Ctrl + ``):

npm install
npm run compile

Paso 3: Iniciar la extensión en modo depuración (Extension Development Host)

1. Presiona la tecla F5 (o ve a la pestaña Run and Debug en el panel izquierdo y haz clic en Run Extension).
2. Se abrirá una nueva ventana de VS Code titulada [Extension Development Host].
3. En esa nueva ventana, abre el archivo de prueba incluido: test_sample.py (o cualquier archivo .py que desees).
4. Presiona Ctrl + Alt + O o abre la paleta de comandos (Ctrl + Shift + P) y ejecuta Python: Order Code Logically.
5. ¡Verás cómo el archivo se reorganiza al instante de forma limpia y ordenada!

⚙️ Configuración Opcional

Puedes personalizar el comportamiento en tu settings.json de VS Code:

{
  // Ruta personalizada al intérprete de Python si no usas el estándar del PATH
  "pythonOrderSyntaxLogically.pythonPath": "",

  // Mostrar notificación de confirmación al reordenar
  "pythonOrderSyntaxLogically.showSuccessNotification": true
}

📁 Estructura del Proyecto

├── .vscode/
│   ├── launch.json              # Configuración para depurar con F5
│   └── tasks.json               # Tarea de compilación automática de TypeScript
├── python/
│   └── reorder_python.py        # Motor AST nativo de Python para reordenamiento
├── src/
│   └── extension.ts             # Código fuente TypeScript de la extensión
├── out/
│   └── extension.js             # Código compilado de la extensión
├── package.json                 # Manifiesto y comandos de la extensión de VS Code
├── tsconfig.json                # Configuración de compilador TypeScript
├── test_sample.py               # Archivo de prueba con código desordenado
└── README.md                    # Documentación y guía de uso