Crear un inventario CSV de los archivos de una carpeta

01Crear el primer inventario con cuatro archivos

Que se haya creado una carpeta no basta para dar esta tarea por terminada. El CSV debe incluir cada uno de los cuatro archivos originales una sola vez, el total mostrado debe ser de 63 bytes y el contenido original debe permanecer intacto. Comprueba primero estas condiciones con los materiales incluidos y después amplía el trabajo a tus propias carpetas.

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

python example.py

02Entender 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 examina sample_files dentro de BASE, por lo que puedes mover toda la carpeta del ejemplo si mantienes la misma estructura relativa. outputs queda fuera del área examinada para que el CSV generado no vuelva a mezclarse con la lista de entrada.

relative_path usa barras inclinadas para facilitar la lectura entre sistemas operativos. Los resultados se ordenan por esa ruta. Al no depender del orden interno de exploración de archivos, es más fácil comparar el orden de las filas para una misma entrada.

03Código completo para ejecutar

collect_files recopila la información y main escribe el nuevo CSV. outputs no se crea hasta que termina la comprobación de la entrada. Si encuentra una carpeta ilegible o un enlace, el programa 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 la separación de columnas y las comillas del CSV. Se usa una cadena vacía para newline y se guarda con UTF-8 BOM. El archivo de salida se abre en modo x para no sobrescribirlo si ya se ha creado otro con el mismo nombre. En este ejemplo, antes se comprueba si existe la propia carpeta outputs.

04Comprobar las cuatro filas y el total

El total de la tabla es 15 + 0 + 17 + 31 = 63 bytes. La terminal también muestra el mensaje de finalización «완료: 4개 파일, 합계 63바이트». La primera línea del CSV contiene los nombres de columna, por lo que la hoja de cálculo muestra cinco filas si se incluye la cabecera. No olvides contar empty.txt.

05Comprobar el inventario y la conservación de los originales

1. Compara una a una las cuatro rutas del CSV con las ubicaciones reales en sample_files. Las carpetas docs y reports no aparecen como filas de datos.
2. Comprueba que el archivo vacío figure con 0 bytes y que las extensiones se distingan como .txt y .csv.
3. Abre sample_files/readme.txt y comprueba que siga apareciendo el texto original Sample inventory.
4. Ejecuta de nuevo el mismo comando. Debe detenerse con el mensaje «outputs가 이미 있습니다», que indica que la carpeta de salida ya existe, y conservar el primer resultado.

Las condiciones de rechazo también forman parte del diseño. No borres el código que impide generar la salida porque bloquee una nueva ejecución. Si necesitas conservar el resultado anterior, guarda outputs con otro nombre que incluya la fecha antes de volver a ejecutar, o extrae el ZIP en una carpeta nueva para empezar otra prueba.

06Aplicarlo a tu propia carpeta

No conectes toda tu carpeta de trabajo desde el principio. Coloca primero unos pocos archivos representativos en una copia de sample_files. Los nombres con caracteres coreanos o espacios se gestionan como objetos de ruta. No se admiten enlaces simbólicos ni directorios vinculados a otra ubicación, por lo que conviene usar una copia pequeña formada por archivos normales.

1. Conserva la entrada y los resultados del ejemplo anterior y crea una nueva carpeta de práctica.
2. Coloca en sample_files entre 5~10 archivos que puedas contar a mano. Añade también un nivel de subcarpetas.
3. Genera el inventario y comprueba que las rutas relativas apunten a las ubicaciones esperadas.
4. Aumenta el número de archivos sin cambiar las reglas que has comprobado. El tamaño del archivo puede diferir de la longitud de su contenido, así que mantén la unidad en bytes.

Si la carpeta de entrada está vacía, se genera un CSV solo con la cabecera y se muestra un recuento de 0 archivos. Esto es distinto de detenerse porque la carpeta no existe. Una carpeta vacía también puede ser un estado normal de trabajo; distingue ambos casos al interpretar los resultados.

07Resolver errores habituales

08Qué garantiza este inventario

El resultado recoge la información de los archivos observada durante la ejecución. No es una comprobación de duplicados por contenido ni una copia de seguridad recuperable. Dos documentos del mismo tamaño pueden tener contenidos distintos. Si necesitas comparar hashes, debes añadir ese objetivo y las columnas correspondientes por separado.

Este ejemplo introductorio no cubre cambios de nombre o contenido realizados por otros programas durante la exploración, retrasos de unidades de red ni la carga de muchísimos archivos en memoria a la vez. Si falla la escritura en disco durante la salida, puede quedar un outputs incompleto. 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

• Comprobados 4 archivos, incluidos los de carpetas anidadas, y un total de 63 bytes
• Una carpeta de entrada vacía genera solo la cabecera
• Rechazo de una carpeta de entrada inexistente y de outputs ya existente
• Comprobada la independencia de las rutas al ejecutar desde otra carpeta de trabajo
• Comprobado que el SHA-256 de los archivos de entrada no cambia tras 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 ↗ (Nueva pestaña)
• Documentación oficial de Python · Lectura y escritura con csv ↗ (Nueva pestaña)