Skip to content

Latest commit

 

History

History
385 lines (324 loc) · 19.4 KB

README.md

File metadata and controls

385 lines (324 loc) · 19.4 KB
FilesPy Logo

FilesPy

Organizador, Renombrador por Lotes e Inspector Inteligente de Archivos

Una herramienta de escritorio moderna, ultrarrápida y segura construida con Python y Flet (Flutter Engine) con diseño en modo oscuro y acentos en #f40048.

Latest Release Python Version Flet GUI Cross Platform License

Explorar Funciones • Descargar Binarios • Instalación Local • Guía de Uso • Arquitectura


Tip

Seguridad ante todo: Ninguna operación modifica archivos físicos en disco sin tu confirmación previa. FilesPy detecta colisiones de nombre en tiempo real y permite revertir cualquier lote con un solo clic mediante su motor de transacciones atómicas.


📑 Tabla de Contenidos


✨ Descripción General

FilesPy es una solución de escritorio concebida para poner orden en el caos de archivos. Diseñada meticulosamente con un enfoque visual moderno en modo oscuro, ofrece la fluidez del motor Flutter a través de Flet junto con la potencia y flexibilidad de Python 3.

Resuelve de forma eficiente tres de las tareas más comunes y propensas a errores en cualquier sistema operativo:

  1. Renombrar cientos de archivos aplicando reglas complejas (regex, numeración, capitalización).
  2. Organizar estructuras caóticas clasificándolas por formato, categorías temáticas o fechas.
  3. Identificar y depurar archivos duplicados mediante huellas hash SHA-256 sin importar su nombre.

⚡ Características Principales

🏷️ 1. Renombrado por Lotes Potente

  • Búsqueda y Reemplazo: Coincidencia directa o patrones avanzados mediante Regex (con distinción opcional de mayúsculas).
  • Prefijos y Sufijos: Añade metadatos o etiquetas al inicio o final preservando la extensión original.
  • Numeración Secuencial: Genera correlativos automáticos (ej. _001, _002) con selector de inicio y dígitos de relleno.
  • Normalización de Formato: Alterna entre minusculas, MAYÚSCULAS, Título, snake_case y kebab-case.
  • Control de Extensiones: Mantén, estandariza o modifica extensiones en masa.

📂 2. Organización Inteligente en Carpetas

  • Por Extensión: Clasifica automáticamente en subdirectorios temáticos (PDF/, JPG/, DOCX/).
  • Por Categorías Dinámicas: Agrupa por tipo de contenido (Documentos, Imágenes, Audio, Video, Código, Comprimidos), completamente personalizable.
  • Cronología por Fechas: Estructura carpetas por Año y Mes (YYYY/MM) leyendo metadatos reales de modificación en disco.
  • Recursivo o Plano: Procesa únicamente la carpeta actual o incluye subcarpetas con un clic.

🛡️ 3. Previsualización y Prevención de Colisiones

  • Grid Reactivo en Vivo: Compara el nombre original, nuevo nombre propuesto, ruta de destino y tamaño en tiempo real.
  • Detección Activa de Conflictos: Identifica y bloquea la operación si dos archivos tendrían el mismo nombre o si ya existe uno en el destino.
  • Control Granular: Activa o desactiva elementos individualmente o selecciona todos mediante un interruptor maestro.

🔍 4. Inspector Multimedia (Pillow + Texto)

  • Miniaturas Fluidas: Previsualización rápida de imágenes (PNG, JPG, WEBP, GIF, BMP, SVG).
  • Lector de Código y Texto: Muestra extractos de archivos planos, scripts y documentos sin abrir aplicaciones externas.
  • Ficha Técnica: Visualiza peso exacto formateado (KB, MB, GB), fecha y ruta absoluta.

🧬 5. Detección Criptográfica (SHA-256)

  • Análisis en 2 Fases: Filtrado rápido por tamaño exacto en bytes seguido del cálculo SHA-256 en bloques de 64 KB para máximo rendimiento.
  • Independiente del Nombre: Detecta archivos con contenido idéntico aunque tengan nombres completamente distintos.
  • Aislamiento Seguro: Mueve duplicados redundantemente a un directorio especial (_Duplicados) para revisión segura.

⏪ 6. Sistema de Deshacer Atómico (Undo)

  • Transacciones Reversibles: Cada lote aplicado genera un registro transaccional exacto en memoria y registro persistente.
  • Rollback en 1 Clic: Reviértelo todo inmediatamente; los archivos regresan a sus nombres y ubicaciones previas de forma segura.

🎯 7. Organización Manual y Nombrado Híbrido

  • Recorrido Asistido: Revisa archivo por archivo con previsualización visual y decide su destino al instante.
  • Carpetas al Vuelo: Crea y selecciona carpetas personalizadas (Facturas, Clientes, etc.) con el botón + Agregar Carpeta.
  • Nombrado Híbrido: Escribe un nombre a medida o pulsa ⚡ Auto-nombrar para aplicar las reglas activas.
  • Auto-avance Veloz: Pasa automáticamente al siguiente elemento al asignar destino para un flujo de trabajo ultra ágil.

⚙️ 8. Configuración Dinámica Persistente

  • Modal de Preferencias: Añade nuevas extensiones y categorías (ej. Modelado 3D con .blend, .obj).
  • Lista Negra de Omitidos: Ignora archivos del sistema o dependencias (.DS_Store, node_modules, Thumbs.db).
  • Almacenamiento Local: Ajustes guardados automáticamente en settings.json con opción de restablecer valores de fábrica.

📥 Instaladores y Descargas

FilesPy cuenta con paquetes autocontenidos para los principales sistemas operativos, listos para usar sin necesidad de instalar Python ni librerías adicionales:

Sistema Operativo Paquete / Formato Arquitectura Descripción Enlace
Windows FilesPy-Windows-Setup.exe
o versión portable .zip
x64 Asistente de instalación Inno Setup con accesos directos al Menú Inicio y Escritorio. Descargar
macOS FilesPy-macOS.dmg
o .zip portable
Universal / x64 / arm64 Imagen de disco .dmg con ventana de instalación arrastrar-y-soltar a /Applications. Descargar
Linux FilesPy-Linux-x64.tar.gz x64 Paquete portable con lanzador install.sh y acceso de escritorio .desktop. Descargar

Note

Accede al historial completo de versiones y notas de versión en GitHub Releases.


🚀 Inicio Rápido

Si prefieres ejecutar FilesPy directamente desde el código fuente o contribuir al proyecto:

Requisitos Previos

  • Python 3.10+ instalado en tu sistema.
  • Gestor de paquetes pip y soporte para entornos virtuales (venv).

Instalación Paso a Paso

1. Clonar el Repositorio

git clone https://github.com/Mad065/FilesPy.git
cd FilesPy

2. Crear y Activar el Entorno Virtual

<!-- slide -->
##### En macOS / Linux
```bash
python3 -m venv .venv
source .venv/bin/activate
```
<!-- slide -->
##### En Windows (PowerShell / CMD)
```cmd
python -m venv .venv
.venv\Scripts\activate
```

3. Instalar Dependencias

pip install -r requirements.txt

4. Lanzar la Aplicación

python main.py

📖 Guía de Uso

El flujo de trabajo en FilesPy está pensado para ser visual, rápido e intuitivo:

[ 1. Explorar Carpeta ] ──▶ [ 2. Configurar Reglas ] ──▶ [ 3. Verificar en Vivo ] ──▶ [ 4. Aplicar Cambios ]
                                                                                               │
                                                                                    (¿Necesitas volver atrás?)
                                                                                               ▼
                                                                                     [ 5. Botón Deshacer ]
  1. 📁 Cargar Directorio: Haz clic en Explorar... y selecciona la carpeta a procesar. Activa la casilla Subcarpetas si deseas escanear recursivamente.
  2. ⚙️ Seleccionar Modo de Operación:
    • Pestaña Renombrar: Configura prefijos, sufijos, reemplazo de caracteres, numeración o formato de mayúsculas/minúsculas.
    • Pestaña Organizar: Elige si deseas ordenar por extensión, categoría o fecha (año/mes).
    • Pestaña Duplicados: Ejecuta el escaneo por hash SHA-256 para detectar copias redundantes y aislarlas.
  3. 👀 Comprobación Visual: Revisa la tabla central interactiva. Las filas se colorean dinámicamente:
    • 🟢 Verde: Operación lista y válida sin conflictos.
    • 🔴 Rojo: Alerta de colisión (el archivo ya existe en destino o dos archivos recibirían el mismo nombre).
  4. 🖼️ Inspección de Detalles: Toca cualquier archivo en la tabla para ver su miniatura (en imágenes) o extracto de texto en el panel lateral derecho.
  5. 🚀 Aplicar Operaciones: Pulsa en Aplicar Cambios para ejecutar las acciones en el disco de forma segura.
  6. ↩️ Reversión Inmediata: ¿Cambio inesperado o error involuntario? Presiona el botón Deshacer y todos los archivos volverán exactamente a su estado y ubicación anterior.

🏗️ Arquitectura del Sistema

FilesPy sigue una arquitectura desacoplada y reactiva en tres capas bien diferenciadas:

flowchart TD
    subgraph UI["💻 Capa de Presentación (Flet / Flutter Engine)"]
        FB["FolderBar\nRuta y Filtros"]
        Tabs["Paneles Principales\n(Renombrar | Organizar | Duplicados)"]
        PT["PreviewTable\nGrid Reactivo de Comparación"]
        IP["FileInspector\nMiniaturas (Pillow) y Metadatos"]
        AB["ActionBar\nBotones de Aplicar y Deshacer"]
        SD["Settings & Review Dialogs\nModales Interactivos"]
    end

    subgraph Core["🧠 Capa de Negocio (Core Engines)"]
        CFG["ConfigManager\nsettings.json y Categorías"]
        SCN["DirectoryScanner\nDescubrimiento y Filtros"]
        REN["RenamerEngine\nRegex, Prefijos, Formato"]
        ORG["OrganizerEngine\nExtensión, Fecha, Tipo"]
        CON["ConflictDetector\nValidación y Colisiones"]
        DUP["DuplicateFinder\nHashes Criptográficos SHA-256"]
        UND["UndoManager\nTransacciones Atómicas y Rollback"]
    end

    subgraph FS["💾 Almacenamiento Local"]
        Disk["Sistema de Archivos en Disco"]
    end

    FB --> SCN
    Tabs --> REN & ORG & DUP
    SCN --> Core
    REN & ORG --> CON
    CON --> PT
    PT --> IP
    AB --> UND
    UND --> Disk
    CFG -.-> Tabs
    SD -.-> CFG
Loading

📁 Estructura del Proyecto

FilesPy/
├── main.py                      # Punto de entrada de la aplicación
├── requirements.txt             # Dependencias del proyecto (flet, pillow)
├── settings.json                # Configuración persistente del usuario
├── .gitignore                   # Exclusiones de Git
├── README.md                    # Documentación principal
├── assets/                      # Recursos visuales y gráficos
│   └── icons/                   # Iconos vectoriales y ejecutables (.ico, .icns, .png)
├── core/                        # Módulos de lógica de negocio y motores
│   ├── config_manager.py        # Gestión y persistencia de configuración JSON
│   ├── conflicts.py             # Detección de colisiones y validación de rutas
│   ├── duplicates.py            # Localización de duplicados por hash SHA-256
│   ├── models.py                # Modelos de datos (dataclasses tipados)
│   ├── organizer.py             # Clasificación por extensión, categoría o fecha
│   ├── renamer.py               # Motor de transformaciones de nombres
│   ├── scanner.py               # Explorador de directorios con filtros
│   └── undo.py                  # Pila de transacciones y operaciones reversibles
├── ui/                          # Capa visual moderna (Flet)
│   ├── app.py                   # Ventana principal y pipeline reactivo
│   ├── theme.py                 # Constantes de diseño, paleta y formateadores
│   └── components/              # Componentes visuales desacoplados
│       ├── action_bar.py        # Barra de botones de acción (Aplicar, Deshacer)
│       ├── duplicate_panel.py   # Panel de análisis y aislamiento de duplicados
│       ├── folder_bar.py        # Barra de ruta, subcarpetas y configuración
│       ├── inspector_panel.py   # Panel lateral de miniaturas y metadatos
│       ├── manual_organize_dialog.py # Diálogo de clasificación y nombrado híbrido
│       ├── organize_panel.py    # Formulario de modos de organización
│       ├── preview_table.py     # Tabla interactiva con verificación visual
│       ├── rename_panel.py      # Formulario de reglas de renombrado
│       ├── settings_dialog.py   # Modal de edición de categorías y preferencias
│       └── step_review_dialog.py# Revisión paso a paso interactiva
├── packaging/                   # Empaquetado multiplataforma
│   ├── FilesPy.spec             # Especificación PyInstaller
│   ├── FilesPy.desktop          # Lanzador para entornos de escritorio Linux
│   ├── inno_setup.iss           # Script de instalación para Windows (Inno Setup)
│   └── icon_generator.py        # Generador de iconos .ico / .icns / .png
└── scripts/                     # Scripts de compilación automatizada
    ├── build_macos.sh           # Generador de .app y .dmg para macOS
    ├── build_windows.bat        # Generador de .exe y Setup para Windows
    └── build_linux.sh           # Generador de .tar.gz y .desktop para Linux

🛠️ Compilación Local de Instaladores

Si deseas compilar los binarios e instaladores de forma manual en tu máquina:

# 🍏 En macOS:
chmod +x scripts/build_macos.sh && ./scripts/build_macos.sh
# Salida: dist/FilesPy.app, installer_output/FilesPy-macOS.dmg y .zip

# 🪟 En Windows:
scripts\build_windows.bat
# Salida: dist\FilesPy\FilesPy.exe, installer_output\FilesPy-Windows-Setup.exe y .zip

# 🐧 En Linux:
chmod +x scripts/build_linux.sh && ./scripts/build_linux.sh
# Salida: installer_output/FilesPy-Linux-x64.tar.gz con script install.sh

🔄 CI/CD Automatizado

FilesPy cuenta con un pipeline de integración y despliegue continuo mediante GitHub Actions (.github/workflows/build-installers.yml):

  • 🏷️ Disparo Automático: Se activa ante cualquier nueva etiqueta de versión (v*) o mediante ejecución manual (workflow_dispatch).
  • ⚡ Compilación Concurrente: Construye los instaladores simultáneamente en runners nativos de Windows, macOS y Linux.
  • 📦 Publicación en Releases: Empaqueta los binarios e instaladores y los adjunta automáticamente a la sección de lanzamientos de GitHub.

📄 Licencia

Este proyecto está distribuido bajo la licencia MIT. Para más detalles, consulta el archivo LICENSE.

Desarrollado con ❤️ para simplificar la gestión masiva de archivos.
⬆ Volver al inicio