Crear una lista CSV de los archivos de una carpeta

01Crea tu primera lista con cuatro archivos

Crear una carpeta de salida no basta para considerar terminada esta tarea. El CSV debe contener exactamente una vez cada uno de los cuatro archivos originales, los tamaños indicados deben sumar 63 bytes y el contenido original debe permanecer sin cambios. Comprueba estas condiciones con los datos incluidos antes de pasar a tu propia carpeta de trabajo.

1. Busca example.py, README.txt y la carpeta sample_files dentro de la carpeta extraída.
2. Abre sample_files y comprueba readme.txt, empty.txt y las subcarpetas docs y reports. empty.txt está vacío intencionadamente.
3. Ejecuta una vez en la terminal el comando indicado a continuación. No muevas ni edites los archivos de entrada mientras se ejecuta.
4. Cuando aparezcan el mensaje de finalización y la ruta de salida, abre outputs/file_list.csv.

python example.py

02Entiende las rutas y las columnas

El código parte de la ubicación de example.py, no de la carpeta actual de la terminal. Solo recorre sample_files bajo BASE, por lo que puedes mover toda la carpeta del ejemplo siempre que mantengas su estructura interna. outputs está fuera de la carpeta recorrida para que el CSV resultante no pase a formar parte de la lista de entrada en una ejecución posterior.

relative_path utiliza barras inclinadas para facilitar la lectura entre distintos sistemas operativos. Los resultados se ordenan por esta ruta. No dependen del orden interno de recorrido de los archivos, lo que facilita comparar el orden de las filas para una misma entrada.

03Código completo utilizado en este ejemplo

collect_files recopila la información de los archivos y main escribe un CSV nuevo. El código no crea outputs hasta que se completan las comprobaciones de entrada. Si encuentra una carpeta que no puede leerse o un enlace, se detiene en lugar de guardar una lista parcial como si fuera un resultado correcto.

"""sample_files를 읽어 outputs/file_list.csv에 목록을 기록합니다. 원본은 변경하지 않습니다."""

import csv
import os
import sys
from datetime import datetime, timezone
from pathlib import Path

BASE = Path(__file__).resolve().parent
INPUT = BASE / "sample_files"
OUTPUT = BASE / "outputs"
FIELDS = ["relative_path", "extension", "size_bytes", "modified_utc"]


def is_link(path):
    # Windows 연결 디렉터리(junction)도 Python 3.12 이상에서는 거부합니다.
    return path.is_symlink() or getattr(path, "is_junction", lambda: False)()


def collect_files(folder):
    if is_link(folder) or not folder.is_dir():
        raise ValueError("sample_files는 실제 폴더여야 합니다.")
    rows = []

    def stop_on_error(error):
        raise error

    # 하위 폴더까지 읽되, 링크를 따라 다른 폴더로 나가지 않습니다.
    for root, dirs, files in os.walk(folder, followlinks=False, onerror=stop_on_error):
        root = Path(root)
        for name in dirs + files:
            if is_link(root / name):
                raise ValueError(f"링크는 처리하지 않습니다: {root / name}")
        for name in sorted(files):
            path = root / name
            if not path.is_file():
                raise ValueError(f"일반 파일이 아닙니다: {path}")
            stat = path.stat()
            rows.append({
                "relative_path": path.relative_to(folder).as_posix(),
                "extension": path.suffix.lower() or "(없음)",
                "size_bytes": stat.st_size,
                "modified_utc": datetime.fromtimestamp(
                    stat.st_mtime, timezone.utc
                ).isoformat(timespec="seconds"),
            })
    return sorted(rows, key=lambda row: row["relative_path"])


def main():
    if OUTPUT.exists() or OUTPUT.is_symlink():
        raise FileExistsError("outputs가 이미 있습니다. 기존 결과를 옮긴 뒤 실행하세요.")
    rows = collect_files(INPUT)  # 모두 읽은 뒤에만 출력 폴더를 만듭니다.
    OUTPUT.mkdir()
    target = OUTPUT / "file_list.csv"
    # x는 기존 파일을 덮어쓰지 않는 모드입니다. BOM은 한글 CSV 열기에 도움을 줍니다.
    with target.open("x", encoding="utf-8-sig", newline="") as stream:
        writer = csv.DictWriter(stream, fieldnames=FIELDS)
        writer.writeheader()
        writer.writerows(rows)
    print(f"완료: {len(rows)}개 파일, 합계 {sum(row['size_bytes'] for row in rows)}바이트")
    print(target)
    return 0


if __name__ == "__main__":
    try:
        raise SystemExit(main())
    except (OSError, ValueError) as error:
        print(f"중지: {error}", file=sys.stderr)
        raise SystemExit(2)

csv.DictWriter gestiona los delimitadores y las comillas del CSV. El archivo se guarda con newline establecido en una cadena vacía y con BOM UTF-8. El archivo de salida se abre en modo x, de modo que no sobrescribe un archivo que ya exista. Este ejemplo comprueba primero si la propia carpeta outputs ya existe.

04Comprueba las cuatro filas y el tamaño total

La tabla suma 15 + 0 + 17 + 31 = 63 bytes. La terminal también muestra “완료: 4개 파일, 합계 63바이트” (completado: cuatro archivos, sesenta y tres bytes en total). La primera línea del CSV contiene los nombres de las columnas, por lo que una hoja de cálculo muestra cinco filas contando el encabezado. No olvides contar empty.txt.

05Comprueba los originales además de la lista

1. Relaciona cada una de las cuatro rutas del CSV con su ubicación real en sample_files. Las propias carpetas docs y reports no se incluyen como filas de datos.
2. Comprueba que el archivo vacío se incluye con un tamaño de 0 bytes y que las extensiones son .txt y .csv.
3. Abre sample_files/readme.txt y comprueba que el texto original Sample inventory sigue presente.
4. Ejecuta de nuevo el mismo comando. Debe detenerse con “outputs가 이미 있습니다” (outputs ya existe), y el primer resultado debe permanecer intacto.

Las condiciones de fallo forman parte del diseño. No elimines el código de protección de salida solo porque impide una ejecución repetida. Para conservar los resultados anteriores, cambia el nombre de outputs por uno que incluya una fecha antes de volver a ejecutar, o extrae el ZIP en una carpeta nueva para iniciar una prueba nueva.

06Aplícalo a tu propia carpeta

No apuntes inicialmente el ejemplo a toda tu carpeta de trabajo. Coloca algunos archivos representativos en una copia de sample_files. Los objetos Path gestionan nombres de archivo que contienen caracteres coreanos o espacios. Los enlaces simbólicos y las uniones de directorios que apuntan a otras ubicaciones están fuera del alcance admitido, así que utiliza una copia pequeña que contenga archivos normales.

1. Conserva las entradas y los resultados del ejemplo existente y crea una carpeta de práctica nueva.
2. Coloca 5~10 archivos en sample_files para poder contarlos manualmente. Incluye también un nivel de subcarpetas.
3. Genera la lista y comprueba que las rutas relativas apunten a las ubicaciones esperadas.
4. Aumenta el número de archivos manteniendo sin cambios las reglas ya comprobadas. El tamaño de un archivo puede diferir de la longitud de su contenido, así que conserva la unidad en bytes.

Si la carpeta de entrada está vacía, el script crea un CSV que solo contiene el encabezado e informa de un recuento de archivos igual a 0. Esto es distinto de detenerse porque la carpeta no existe. Una carpeta vacía puede ser un estado de trabajo válido, así que distingue ambos casos al interpretar los resultados.

07Resuelve errores habituales

08Qué te indica esta lista y qué no

El resultado contiene información de los archivos observada durante la ejecución. No es una comprobación de contenido duplicado ni una copia de seguridad desde la que puedas restaurar archivos. Dos documentos con el mismo tamaño pueden tener contenidos diferentes. Si necesitas comparaciones mediante hash, defínelas como una tarea independiente y añade las columnas necesarias.

Este ejemplo para principiantes no cubre otros programas que cambien nombres o contenidos durante el recorrido, retrasos de unidades de red ni la recopilación en memoria de cantidades muy grandes de archivos. Un fallo de escritura en disco puede dejar una carpeta outputs incompleta, así que comprueba tanto el mensaje de finalización como el número de filas del resultado.

Registro de ejecución y verificación

2026-09-19 · Windows 11 · CPython 3.12.14 · Sin paquetes adicionales · Ejecutado en una copia temporal de la distribución

• Se confirmaron 4 archivos, incluidos archivos de carpetas anidadas, con un total de 63 bytes
• Una carpeta de entrada vacía produce un CSV que solo contiene el encabezado
• Se rechazan las carpetas de entrada inexistentes y una carpeta outputs ya existente
• Se confirmó la independencia del directorio de trabajo ejecutándolo desde otra carpeta
• Se confirmaron hashes SHA-256 idénticos para los archivos de entrada antes y después de la ejecución

Criterios de redacción y verificación de todo el sitio

Fuentes de referencia

Las explicaciones y los ejemplos son de elaboración propia. Puedes consultar los comportamientos y conceptos relacionados en las siguientes fuentes oficiales.

• Documentación oficial de Python · Rutas e información de archivos con pathlib ↗ (New tab)
• Documentación oficial de Python · Lectura y escritura de archivos CSV ↗ (New tab)