Defina regras de nomes de arquivos para a equipe e verifique-os com Python

01Escreva a convenção de nomes antes de escrever o verificador

Este exemplo usa o formato YYYYMMDD_project_document_vNN.ext. A date tem oito dígitos e deve ser uma data real do calendário. project e document usam letras minúsculas ou dígitos, opcionalmente separados por hífens. A version é v seguida de exatamente dois dígitos. As allowed extensions são pdf, docx, xlsx, csv e txt.

YYYYMMDD_project_document_vNN.ext

Example:
20260920_alpha_test-plan_v01.pdf

• Use a data de trabalho relevante do arquivo como YYYYMMDD.
• Use project e document tokens em minúsculas.
• Use underscores apenas entre as quatro partes principais do filename.
• Use v01, v02 e assim por diante para versions em vez de final, latest, new ou revised.
• Mantenha a file extension original e restrinja-a a uma lista acordada.

02Crie uma pasta sintética com nomes válidos e inválidos

Os filenames a seguir são sintéticos e foram criados especificamente para este artigo. Salve o script de preparação como create_file_naming_demo.py. Ele cria oito arquivos vazios; quatro seguem a regra e quatro a violam deliberadamente.

from pathlib import Path

SOURCE = Path("outputs") / "file_naming_demo"
FILENAMES = [
    "20260920_alpha_test-plan_v01.pdf",
    "20260920_alpha_results_v02.csv",
    "20260921_beta_meeting-notes_v03.txt",
    "20261001_beta_budget_v01.xlsx",
    "2026-09-20_alpha_notes_v01.txt",
    "20260920_Alpha_notes_v01.txt",
    "20260920_alpha_notes_final.txt",
    "20260230_beta_results_v01.csv",
]

SOURCE.parent.mkdir(parents=True, exist_ok=True)
SOURCE.mkdir()  # Stop if the synthetic source already exists.

for filename in FILENAMES:
    target = SOURCE / filename
    with target.open("xb"):
        pass

Espera-se que os primeiros quatro names passem. O quinto usa uma hyphenated date em vez de YYYYMMDD. O sexto contém um uppercase project token. O sétimo usa final em vez de vNN. O oitavo tem a forma correta, mas contém a data impossível 2026-02-30.

03Classifique manualmente os oito nomes

Portanto, os totais esperados são 8 files checked, 4 passes e 4 failures. Três failures são structural, e um tem filename estruturalmente válido, mas uma calendar date inválida.

04Verifique filenames sem renomeá-los

Salve o script a seguir como check_file_names.py. Ele lê apenas filenames e grava um relatório CSV em uma output folder separada. Ele não renomeia, move, edita nem exclui nenhum source file.

import csv
import re
from datetime import datetime
from pathlib import Path

SOURCE = Path("outputs") / "file_naming_demo"
OUTPUT_DIR = Path("outputs") / "file_naming_result"
REPORT = OUTPUT_DIR / "file_naming_report.csv"
ALLOWED_EXTENSIONS = {"pdf", "docx", "xlsx", "csv", "txt"}

NAME_PATTERN = re.compile(
    r"^(?P<date>[0-9]{8})_"
    r"(?P<project>[a-z0-9]+(?:-[a-z0-9]+)*)_"
    r"(?P<document>[a-z0-9]+(?:-[a-z0-9]+)*)_"
    r"(?P<version>v[0-9]{2})\."
    r"(?P<extension>[a-z0-9]+)$"
)


def check_filename(filename: str) -> tuple[str, str]:
    match = NAME_PATTERN.fullmatch(filename)
    if match is None:
        return "FAIL", "STRUCTURE_ERROR"

    extension = match.group("extension")
    if extension not in ALLOWED_EXTENSIONS:
        return "FAIL", "UNSUPPORTED_EXTENSION"

    try:
        datetime.strptime(match.group("date"), "%Y%m%d")
    except ValueError:
        return "FAIL", "INVALID_DATE"

    return "PASS", ""


def main() -> None:
    if not SOURCE.is_dir():
        raise FileNotFoundError(f"Source folder not found: {SOURCE}")
    if OUTPUT_DIR.exists():
        raise FileExistsError(f"Output folder already exists: {OUTPUT_DIR}")

    files = sorted(path for path in SOURCE.iterdir() if path.is_file())
    results = []

    for path in files:
        status, issue = check_filename(path.name)
        results.append({
            "filename": path.name,
            "status": status,
            "issue": issue,
        })

    OUTPUT_DIR.parent.mkdir(parents=True, exist_ok=True)
    OUTPUT_DIR.mkdir()
    with REPORT.open("x", encoding="utf-8", newline="") as stream:
        writer = csv.DictWriter(
            stream,
            fieldnames=["filename", "status", "issue"],
        )
        writer.writeheader()
        writer.writerows(results)

    passed = sum(row["status"] == "PASS" for row in results)
    failed = len(results) - passed
    print(f"Files checked: {len(results)}.")
    print(f"Passed: {passed}; failed: {failed}.")
    print(f"Report: {REPORT.as_posix()}")


if __name__ == "__main__":
    main()

python check_file_names.py

05Compare o relatório esperado

O report deve conter uma linha para cada source file. Como os filenames são ordenados alfabeticamente antes da verificação, a output order segue os sorted names em vez da lista do setup script.

A saída esperada do console abaixo foi derivada manualmente a partir dos synthetic filenames e do checker. Não é um execution log capturado.

Files checked: 8.
Passed: 4; failed: 4.
Report: outputs/file_naming_result/file_naming_report.csv

06Revise os failures antes de alterar filenames

• Confirme que todos os quatro valid names planejados recebem PASS.
• Confirme que 20260230_beta_results_v01.csv é rejeitado mesmo que seu text shape corresponda à regex.
• Decida quem tem permissão para renomear shared files antes de corrigir qualquer coisa.
• Verifique links, scripts, CAD references, document references ou shared-drive shortcuts que possam depender dos filenames existentes.
• Execute o checker novamente sem alterar OUTPUT_DIR. Ele deve parar com FileExistsError em vez de substituir o report anterior.

07Mantenha as regras de nomes úteis, sem complicá-las demais

Uma filename convention não substitui proper version control, document management ou metadata. Um file chamado v03 não prova que seu content é mais recente do que v02, que foi aprovado pela pessoa correta ou que está vinculado ao project correto.

O exemplo verifica apenas files diretamente dentro de uma pasta. Ele não faz recursive scan de subfolders, não impõe uniqueness entre vários shared drives, não verifica file contents nem confirma se o project token corresponde a um project real.

Quando uma equipe muda sua convention, registre a effective date e decida se old files serão mantidos como estão ou renomeados. Uma rule prática deve ser estável o suficiente para ser lembrada pelas pessoas e rígida o suficiente para que automated checks produzam resultados úteis.

Registro de execução e verificação

2026-09-20 · exemplo verificado manualmente · alvo: Python 3.12 · biblioteca padrão: csv, datetime, pathlib, re · sem execução

• Foram classificados manualmente 8 synthetic filenames como 4 valid e 4 invalid.
• Foram identificadas três structural failures: hyphenated date, uppercase project token e final version label.
• Foi confirmado por raciocínio de calendário que 2026-02-30 é inválida, mesmo que 20260230 corresponda à forma de oito dígitos.
• Foram derivados manualmente os totais esperados de 4 PASS, 4 FAIL, 3 STRUCTURE_ERROR e 1 INVALID_DATE.
• O script foi inspecionado quanto a full filename matching, allowed-extension checking, calendar-date validation, output collision protection e ausência de operações rename ou delete.
• A saída esperada do console foi derivada manualmente.

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 3.12 · re ↗ (New tab)
• Documentação oficial do Python 3.12 · datetime ↗ (New tab)
• Documentação oficial do Python 3.12 · pathlib ↗ (New tab)
• Documentação oficial do Python 3.12 · csv ↗ (New tab)