Criar uma lista CSV dos arquivos de uma pasta

01Crie sua primeira lista com quatro arquivos

Criar uma pasta de saída não é suficiente para considerar esta tarefa concluída. O CSV deve conter cada um dos quatro arquivos originais exatamente uma vez, os tamanhos listados devem somar 63 bytes e o conteúdo original deve permanecer inalterado. Verifique essas condições com os dados incluídos antes de passar para sua própria pasta de trabalho.

1. Localize example.py, README.txt e a pasta sample_files dentro da pasta extraída.
2. Abra sample_files e verifique readme.txt, empty.txt e as subpastas docs e reports. empty.txt está intencionalmente vazio.
3. Execute uma vez no terminal o comando abaixo. Não mova nem edite os arquivos de entrada durante a execução.
4. Quando a mensagem de conclusão e o caminho de saída aparecerem, abra outputs/file_list.csv.

python example.py

02Entenda os caminhos e as colunas

O código parte da localização de example.py, e não da pasta atual do terminal. Ele percorre apenas sample_files dentro de BASE, portanto você pode mover toda a pasta do exemplo desde que mantenha sua estrutura interna. outputs fica fora da pasta percorrida para que o CSV resultante não entre na lista de entrada em uma execução posterior.

relative_path usa barras normais para facilitar a leitura entre diferentes sistemas operacionais. Os resultados são ordenados por esse caminho. Eles não dependem da ordem interna de percurso dos arquivos, o que facilita comparar a ordem das linhas para a mesma entrada.

03Código completo usado neste exemplo

collect_files reúne as informações dos arquivos, e main grava um novo CSV. O código não cria outputs até que as verificações de entrada sejam concluídas. Se encontrar uma pasta ilegível ou um link, ele interrompe a execução em vez de salvar uma lista parcial como se fosse um resultado bem-sucedido.

"""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 cuida dos delimitadores e das aspas do CSV. O arquivo é salvo com newline definido como uma string vazia e com BOM UTF-8. O arquivo de saída é aberto no modo x, portanto não sobrescreve um arquivo que já exista. Este exemplo verifica primeiro se a própria pasta outputs já existe.

04Verifique as quatro linhas e o tamanho total

A tabela totaliza 15 + 0 + 17 + 31 = 63 bytes. O terminal também exibe “완료: 4개 파일, 합계 63바이트” (concluído: quatro arquivos, total de sessenta e três bytes). A primeira linha do CSV contém os nomes das colunas, portanto uma planilha mostra cinco linhas incluindo o cabeçalho. Não se esqueça de contar empty.txt.

05Verifique os originais, além da lista

1. Compare cada um dos quatro caminhos do CSV com sua localização real em sample_files. As próprias pastas docs e reports não são incluídas como linhas de dados.
2. Verifique se o arquivo vazio está incluído com tamanho de 0 bytes e se as extensões são .txt e .csv.
3. Abra sample_files/readme.txt e confirme que o texto original Sample inventory ainda está presente.
4. Execute o mesmo comando novamente. Ele deve parar com “outputs가 이미 있습니다” (outputs já existe), e o primeiro resultado deve permanecer intacto.

As condições de falha fazem parte do projeto. Não remova o código de proteção da saída apenas porque ele bloqueia uma nova execução. Para manter os resultados anteriores, renomeie outputs para um nome que contenha uma data antes de executar novamente, ou extraia o ZIP em uma pasta nova para iniciar outro teste.

06Aplique à sua própria pasta

Não aponte o exemplo para toda a sua pasta de trabalho logo de início. Coloque alguns arquivos representativos em uma cópia de sample_files. Objetos Path lidam com nomes de arquivo que contêm caracteres coreanos ou espaços. Links simbólicos e junções de diretório que apontam para outros locais estão fora do escopo suportado, então use uma pequena cópia contendo arquivos comuns.

1. Mantenha as entradas e os resultados do exemplo existente e crie uma nova pasta de prática.
2. Coloque 5~10 arquivos em sample_files para que seja possível contá-los manualmente. Inclua também um nível de subpastas.
3. Gere a lista e verifique se os caminhos relativos apontam para os locais esperados.
4. Aumente o número de arquivos mantendo inalteradas as regras já verificadas. O tamanho do arquivo pode ser diferente do comprimento do conteúdo, portanto mantenha a unidade em bytes.

Se a pasta de entrada estiver vazia, o script cria um CSV apenas com o cabeçalho e informa uma contagem de arquivos igual a 0. Isso é diferente de interromper a execução porque a pasta não existe. Uma pasta vazia pode ser um estado de trabalho válido, portanto diferencie os dois casos ao interpretar os resultados.

07Resolva erros comuns

08O que esta lista informa e o que não informa

O resultado contém informações dos arquivos observadas durante a execução. Ele não é uma verificação de conteúdo duplicado nem um backup que possa ser restaurado. Dois documentos com o mesmo tamanho podem ter conteúdos diferentes. Se você precisar de comparações por hash, defina isso como uma tarefa separada e adicione as colunas necessárias.

Este exemplo para iniciantes não cobre outros programas alterando nomes ou conteúdos durante a varredura, atrasos em unidades de rede ou a coleta de quantidades muito grandes de arquivos na memória. Uma falha de gravação em disco pode deixar uma pasta outputs incompleta, portanto verifique tanto a mensagem de conclusão quanto o número de linhas do resultado.

Registro de execução e verificação

2026-09-19 · Windows 11 · CPython 3.12.14 · Sem pacotes adicionais · Executado em uma cópia temporária da distribuição

• Confirmados 4 arquivos, incluindo arquivos em pastas aninhadas, totalizando 63 bytes
• Uma pasta de entrada vazia produz um CSV apenas com o cabeçalho
• Pastas de entrada ausentes e uma pasta outputs já existente são rejeitadas
• Confirmada a independência do diretório de trabalho executando a partir de outra pasta
• Confirmados hashes SHA-256 idênticos dos arquivos de entrada antes e depois da execução

Princípios de redação e verificação de todo o site

Fontes de referência

As explicações e os exemplos são de elaboração própria. Os comportamentos e conceitos relacionados podem ser consultados nas fontes oficiais abaixo.

• Documentação oficial do Python · Caminhos e informações de arquivos com pathlib ↗ (New tab)
• Documentação oficial do Python · Leitura e gravação de arquivos CSV ↗ (New tab)