AIで作るテンプレート商品のZIP、空の見本フォルダが消える前に1件を検査する

請求書テンプレートをZIPで渡すとき、examplesフォルダだけが空なら一覧から消えます。購入者には、見本を入れる場所そのものが届きません。
AIにテンプレート本文や使い方を書かせると、納品物の骨組みも早く決まります。でも、空のフォルダはファイル名の一覧だけでは確認できません。そこで実在の商品ではなく、README.txtと合成したinvoice.xlsxを使い、空のexamples/を含むかを検査する小さな見本を作りました。
圧縮できたのに、フォルダがない
ZIPはファイルだけを持っていても作れます。この性質は、空のフォルダを別途登録しない梱包処理では困りものです。examples/に置く予定のファイルがまだ無いなら、パッケージ完成後のnamelist()にもその名前は現れません。
Pythonのzipfile.ZipFile.writestr()は、アーカイブへ名前とデータを書き込むメソッドです。この見本では、空フォルダにも末尾が/の名前を明示して書き込みます。商品用のフォルダ構成を、ファイルの有無とは別の条件として扱うためです。
ここで確認するのは、購入者の環境でフォルダがどう見えるかではありません。完成したZIPのメンバー一覧に、約束した空フォルダがあるかだけです。OSごとの展開結果や、実際の請求書ファイルの正しさまでは保証しません。
空フォルダなしを失敗にする
下のスクリプトは、missing-empty-dir.zipとfixed-empty-dir.zipを一時ディレクトリへ作ります。前者にはexamples/を書かず、後者にはarchive.writestr("examples/", b"")を加えます。
validate()がフォルダとして集めるのは、末尾が/のメンバーだけです。必要なexamples/が無ければ1を返します。通常の納品用スクリプトに組み込むなら、この終了コードをCIや梱包前のコマンドで受け取れます。
from __future__ import annotations
import sys
import zipfile
from pathlib import Path
def make_examples(root: Path) -> tuple[Path, Path]:
missing = root / "missing-empty-dir.zip"
fixed = root / "fixed-empty-dir.zip"
for path, include_empty_directory in ((missing, False), (fixed, True)):
with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as archive:
archive.writestr("README.txt", "テンプレートの使い方\n")
archive.writestr("invoice.xlsx", "synthetic workbook\n")
if include_empty_directory:
archive.writestr("examples/", b"")
return missing, fixed
def validate(path: Path) -> int:
required = {"examples/"}
with zipfile.ZipFile(path) as archive:
members = archive.namelist()
directories = {name for name in members if name.endswith("/")}
missing = sorted(required - directories)
print(f"{path.name}: members={members}")
if missing:
print(f"GATE=FAIL missing_directories={missing}")
return 1
print("GATE=PASS required_empty_directory=examples/")
return 0
if __name__ == "__main__":
root = Path(__file__).parent
missing, fixed = make_examples(root)
targets = [root / arg for arg in sys.argv[1:]] or [missing, fixed]
sys.exit(max(validate(path) for path in targets))
Python3.13.5で、空の一時ディレクトリから次を実行しました。
python3 check_empty_dirs.py missing-empty-dir.zip
python3 check_empty_dirs.py fixed-empty-dir.zip
echo "missing_exit=$? fixed_exit=$?"
ただし、上の3行を続けると最後の$?は2本目の結果だけになります。失敗と成功を別々に残すため、実行時は終了コードをそれぞれ変数へ退避しました。
missing-empty-dir.zip: members=['README.txt', 'invoice.xlsx']
GATE=FAIL missing_directories=['examples/']
missing_exit=1
fixed-empty-dir.zip: members=['README.txt', 'invoice.xlsx', 'examples/']
GATE=PASS required_empty_directory=examples/
fixed_exit=0
空フォルダがないZIPは、メンバーが2件だけでした。examples/を明示したZIPは3件になり、検査を通ります。失敗を終了コード1で返すようにしておけば、圧縮自体が成功しても次の工程へ進ませません。
納品の約束を、ファイルとフォルダに分ける
「見本はここへ入れてください」と案内する商品なら、空フォルダも納品物の一部です。一方で、実ファイルを必ず入れる設計なら、空フォルダを残す必要はありません。先にどちらなのかを商品ごとに決めます。
この見本では、空フォルダをファイル不足としては扱いません。テンプレートの本文、見本、利用案内は役割が違います。空の置き場を作るなら、必要な名前を配列へ明示し、ZIPの一覧で照合します。
ただし、末尾が/の名前を入れれば、すべてのZIP作成ツールと展開ツールで同じ表示になる、とまでは言えません。販売前には対象のOSで展開し、購入者向けの説明と並びを人の目でも確認します。この検査は、その前に「作ったつもりのフォルダ」を止めるための小さな関所です。


