barcode_qr_automation v1.0.0

name: barcode_qr_automation description: "Generate QR codes and linear barcodes in batches from a CSV manifest: choose payloads with discipline, pick QR or Code 128 or EAN-13 per row, set error correction, print size, quiet zones, and contrast before generating, then run a file and list verification pass. Use when a batch of tickets, labels, or inventory codes needs to be produced the same way every time." metadata: { "includeInPrompt": true }

Barcode and QR Automation

Purpose

Turn a list of payloads into a batch of machine-readable code images, one image per row, with the choices that affect scanning settled before anything is generated. The routine fixes the payload text, the code type, the QR error correction level, the physical print size, the quiet zone, and the contrast for each row, writes the batch from a CSV manifest, and then runs a verification pass over the files it produced. Settling size and contrast after generation is too late: a code stretched in layout or printed too small fails at the scanner, not at the generator.

Scope:

• Slug check verified 2026-10-20 against the 917-skill catalog: no slug in the catalog contains "qr" or "barcode", so there is no close cousin for this skill. It is the only skill in the set that generates machine-readable codes.
• file-renaming-automation renames files in place. This skill creates new image files; it renames nothing.
• spreadsheet-automation transforms workbooks. This skill reads one plain CSV manifest as input; it does not build, edit, or format a spreadsheet.
• This skill covers batch generation and a file level verification pass. It does not cover label printer drivers, print shop handoff, inventory systems, or point of sale setup.
• Verification note, 2026-10-20: codegen_batch.py below was run in a test venv with Python 3.12.3, segno 1.6.6, python-barcode 0.16.1, and Pillow 13.0.0, the versions the venv installed that day. segno 1.6.6 and python-barcode 0.16.1 were checked on PyPI and tested in that venv. Pillow on PyPI was 13.0.0 on 2026-10-20 and the venv installed 13.0.0; the system-wide Pillow on the drafting machine was 10.2.0 and was not the version the fixture run used. The fixture run returned rows_total: 3, generated: 3, generate_errors: 0, verified: 3, verify_errors: 0, verdict: PASS. EAN-13 behaviour was checked in a separate real run: EAN13 with the first 12 digits "400638133393" produced a full code of "4006381333931", and a 13-digit input ending in a wrong final digit was silently corrected to the same full code instead of raising an error. The qrcode package, version 8.2 on PyPI on 2026-10-20, was checked on PyPI only. It was not installed and not tested, and this skill does not rely on it. What was NOT verified: decode verification was not done. No decoder was used at any point. The verification pass checks file existence, Pillow opening, PNG format, nonzero size, and that generated.csv matches the manifest row order and payloads. A PASS does not prove a scanner can read a printed code.

Workflow

1. Write the payload for each code first, exactly as it should be encoded.

• The payload is the exact text the code carries. Write it in full, character for character, and treat any later edit to it as a new code that needs a new image.
• Plain text suits internal labels: a bin location, an asset tag, a shelf code. The scanner returns the text and the receiving system decides what it means.
• A URL suits codes a person scans with a phone, such as a ticket link or a product page. Use the full URL that should open, and check the link itself before encoding it. A code that encodes a dead link scans perfectly and still fails the job.
• Structured payloads, such as Wi-Fi or vCard formats, are named formats with named fields. Build them field by field from the format structure and check each field. Do not assemble one by joining loose text and hoping the receiving app parses it.

1. Apply payload discipline before any payload enters the manifest.

• Never encode secrets: no passwords, tokens, keys, recovery codes, or one-time codes. A printed code can be photographed, copied, and read by anyone who sees it.
• Never encode personal data that the label does not need in plain sight. Anyone with a phone can read a QR code, so the payload is public to everyone in sight of the label.
• Never encode raw payment data, such as a full card number. Payment codes belong to payment systems that define their own payload rules.
• Keep each payload to the job of that one label. Extra fields add size, shrink the modules at a fixed print size, and raise the chance of a failed scan.

1. Choose the code type for each row.

• QR for payloads a phone needs to read, for URLs, and for any payload longer than a short identifier. QR codes carry text in two dimensions and include error correction, covered in step 4.
• Code 128 for internal IDs: SKU codes, asset numbers, bin labels, ticket references. It is a compact linear barcode for short identifiers that an in-house scanner reads, and it carries no retail meaning.
• EAN-13 only for real retail codes, where the number is an assigned retail product code and a point of sale will read it. Do not invent an EAN-13 number for an internal item; use Code 128 for internal items instead.
• Record the type per row in the manifest. A batch may mix types, as the fixture does, but each row carries exactly one type.

1. Handle the EAN-13 check digit the way the library handles it.

• Pass the first 12 digits and let the library compute the check digit. The verified behaviour: EAN13 given "400638133393" returned the full code "4006381333931".
• A 13-digit input with a wrong final digit was silently corrected to the same full code instead of raising an error. A wrong hand-typed check digit produces no warning, so never hand-fix one and never treat silence as proof the digit was right.
• Record the full code the library produced for every EAN-13 row, and use that recorded full code in stock or sales records. The 12 digits in the manifest and the 13 digits on the printed bars differ by that computed digit.

1. Set the QR error correction level per row.

• The four levels, in rising order of correction strength, are L, M, Q, and H. M is the default in the script when the manifest leaves the level blank.
• Higher correction holds more redundant data in the same code. It survives more damage, dirt, and partial covering, and it holds less payload at a given size because more of the code is redundancy.
• Lower correction holds more payload at a given size and survives less damage. Use it for clean, controlled settings where the code stays flat and protected.
• Raise the level when the label will be handled, wrapped, scuffed, or partly covered by design elements. Keep the level and the print size decided together: a high level and a long payload both push toward a larger print size.

1. Fix the physical print size and resolution before generating.

• Decide the printed size in millimetres first, from the label stock and the scanning distance. A code read at arm's length on a shelf edge needs more size than a code read at close range on a ticket.
• Work at 300 DPI for print. Convert with the formula: pixels = mm / 25.4 DPI. A 25 mm code at 300 DPI needs about 295 pixels across, and the generated image must meet or exceed that.
• Generate at or above the target pixel size. Do not stretch a small image up in layout, and do not shrink a layout element below the decided physical size to make a page fit.
• The script generates QR codes with segno at scale=10 and border=4, and barcodes through the python-barcode ImageWriter defaults. When a row needs a different pixel size, change the generation setting for that row and record it, rather than resizing the PNG afterwards.

1. Payloads carry no secrets, no personal data the label does not need, and no raw payment data. A printed code is readable by anyone who can see it, and the manifest is written as if that were true for every row.
2. The payload text is fixed before generation. Any change to a payload means a regenerated image and a rerun batch, never an image edited by hand.
3. EAN-13 is for real retail codes only, and its check digit comes from the library. Pass 12 digits, record the full code produced, and never hand-fix a check digit or trust a silent correction.
4. Physical size is decided before generation, at 300 DPI for print, using pixels = mm / 25.4 DPI. Images are generated at or above the needed pixel size and are never stretched in layout.
5. The quiet zone stays. QR codes keep border=4 modules of clear margin, linear barcodes keep clear space at both ends, and no design element enters that space.
6. Codes stay dark on a light, matte background. Inverted or recolored codes require a printed scan test that passed before they ship.
7. The manifest is the record of intent and generated.csv is the record of output. When the two disagree in row order or payloads, the batch has failed verification and does not ship until a clean rerun matches.
8. A PASS is a file level result only: files exist, open with Pillow, are PNG, have nonzero size, and match the manifest list. It is never reported as proof that the codes scan. Decode verification was not done by the script and is not claimed by this skill.
9. Use the script below for generation and verification. Save it as codegen_batch.py, run it as its header describes, and put its full output in the deliverable as item 4 of the Output Contract. Report numbers from its output, not from memory of the manifest.

Batch generation and verification (codegen_batch.py)

Run: python3 codegen_batch.py --make-fixture fixture_codes builds the worked fixture in a folder named fixture_codes, holding a manifest.csv file. Then run: python3 codegen_batch.py fixture_codes/manifest.csv fixture_codes/out to reproduce the output below. Run it on a real batch with python3 codegen_batch.py MANIFEST.csv OUT_DIR. Install the dependencies first in a venv: pip install segno==1.6.6 python-barcode==0.16.1 Pillow.

Expected output for the fixture run:

text
fixture_manifest: fixture_codes/manifest.csv rows=3
file: ticket-a1.png type=qr format=PNG size=370x370 bytes=500
file: bin-label-001.png type=qr format=PNG size=250x250 bytes=272
file: sku-8842.png type=code128 format=PNG size=324x280 bytes=4454
rows_total: 3
generated: 3
generate_errors: 0
verified: 3
verify_errors: 0
verdict: PASS

The fixture is built to show one of each common case in a small batch: two QR rows and one Code 128 row. The first QR row encodes a ticket URL at error correction level M and comes out at 370x370 pixels. The second QR row encodes the short plain text payload BIN-001 at level Q and comes out at 250x250 pixels. The Code 128 row encodes the internal identifier SKU-8842 and comes out at 324x280 pixels. All three rows generate and verify, which gives generated: 3, verified: 3, both error counts at 0, and a verdict of PASS. The fixture has no EAN-13 row; EAN-13 handling is covered by the verified library behaviour recorded in the Purpose section and in Workflow step 4.

codegen_batch.py (requires segno, python-barcode, and Pillow). Save this code as codegen_batch.py:

python
#!/usr/bin/env python3
"""Batch-generate QR codes and barcodes from a CSV manifest, then verify.

Usage:
  python3 codegen_batch.py --make-fixture DIR
  python3 codegen_batch.py MANIFEST.csv OUT_DIR

Manifest columns (header required):
  filename,payload,type,ec
  - filename: output file name inside OUT_DIR, PNG only, no subfolders
  - payload: the exact text the code encodes
  - type: qr, code128, or ean13
  - ec: QR error correction level L, M, Q, or H (blank means M);
        ignored for barcodes

Requires segno, python-barcode, and Pillow. Generation writes one PNG
per row and a generated.csv in OUT_DIR. The verification pass then
checks, for every manifest row, that the file exists, opens as an
image with Pillow, has a PNG format and nonzero size, and that the
generated.csv list matches the manifest payload list row for row.
It does NOT decode any code: no decoder is used, so a pass here does
not prove a scanner can read the printed code.

Exit code is 0 when every row generated and verified, 1 otherwise.
"""
import csv
import os
import sys

FIXTURE_ROWS = [
    {"filename": "ticket-a1.png", "payload": "https://example.com/tickets/A1", "type": "qr", "ec": "M"},
    {"filename": "bin-label-001.png", "payload": "BIN-001", "type": "qr", "ec": "Q"},
    {"filename": "sku-8842.png", "payload": "SKU-8842", "type": "code128", "ec": ""},
]


def fail(msg):
    print(f"error: {msg}")
    return 1


def generate(manifest_path, out_dir):
    try:
        import segno
        from barcode import Code128, EAN13
        from barcode.writer import ImageWriter
        from PIL import Image
    except ImportError as exc:
        return fail(f"missing dependency: {exc.name}. Install segno, python-barcode, and Pillow in a venv first.")
    if not os.path.isfile(manifest_path):
        return fail(f"manifest not found: {manifest_path}")
    with open(manifest_path, newline="", encoding="utf-8") as fh:
        rows = list(csv.DictReader(fh))
    os.makedirs(out_dir, exist_ok=True)
    generated = []
    errors = 0
    for i, row in enumerate(rows, start=1):
        name = (row.get("filename") or "").strip()
        payload = row.get("payload") or ""
        kind = (row.get("type") or "").strip().lower()
        ec = (row.get("ec") or "").strip().upper() or "M"
        if not name or os.path.basename(name) != name or not name.endswith(".png"):
            print(f"row {i}: BAD_FILENAME {name!r}")
            errors += 1
            continue
        if not payload:
            print(f"row {i}: EMPTY_PAYLOAD filename={name}")
            errors += 1
            continue
        path = os.path.join(out_dir, name)
        try:
            if kind == "qr":
                if ec not in ("L", "M", "Q", "H"):
                    raise ValueError(f"bad ec level {ec!r}")
                qr = segno.make(payload, error=ec.lower())
                qr.save(path, scale=10, border=4)
            elif kind == "code128":
                Code128(payload, writer=ImageWriter()).save(os.path.splitext(path)[0])
            elif kind == "ean13":
                digits = payload.strip()
                if not digits.isdigit() or len(digits) not in (12, 13):
                    raise ValueError("ean13 payload must be 12 or 13 digits")
                EAN13(digits, writer=ImageWriter()).save(os.path.splitext(path)[0])
            else:
                raise ValueError(f"unknown type {kind!r}")
        except Exception as exc:
            print(f"row {i}: GENERATE_FAIL filename={name} reason={exc}")
            errors += 1
            continue
        generated.append({"filename": name, "payload": payload, "type": kind, "ec": ec if kind == "qr" else ""})
    gen_csv = os.path.join(out_dir, "generated.csv")
    with open(gen_csv, "w", newline="", encoding="utf-8") as fh:
        writer = csv.DictWriter(fh, fieldnames=["filename", "payload", "type", "ec"])
        writer.writeheader()
        writer.writerows(generated)
    # Verification pass: files exist, open as images, list matches.
    verified = 0
    verify_errors = 0
    manifest_payloads = [(r.get("filename") or "").strip() for r in rows]
    generated_names = [g["filename"] for g in generated]
    if generated_names != manifest_payloads:
        print(f"verify: LIST_MISMATCH manifest={len(manifest_payloads)} generated={len(generated_names)}")
        verify_errors += 1
    for g in generated:
        path = os.path.join(out_dir, g["filename"])
        if not os.path.isfile(path):
            print(f"verify: MISSING {g['filename']}")
            verify_errors += 1
            continue
        try:
            with Image.open(path) as im:
                im.load()
                fmt, size = im.format, im.size
        except Exception as exc:
            print(f"verify: UNREADABLE {g['filename']} reason={exc}")
            verify_errors += 1
            continue
        if fmt != "PNG" or size[0] <= 0 or size[1] <= 0:
            print(f"verify: BAD_IMAGE {g['filename']} format={fmt} size={size}")
            verify_errors += 1
            continue
        print(f"file: {g['filename']} type={g['type']} format={fmt} size={size[0]}x{size[1]} bytes={os.path.getsize(path)}")
        verified += 1
    print(f"rows_total: {len(rows)}")
    print(f"generated: {len(generated)}")
    print(f"generate_errors: {errors}")
    print(f"verified: {verified}")
    print(f"verify_errors: {verify_errors}")
    print(f"verdict: {'PASS' if errors == 0 and verify_errors == 0 and verified == len(rows) else 'FAIL'}")
    return 0 if errors == 0 and verify_errors == 0 and verified == len(rows) else 1


def make_fixture(base):
    os.makedirs(base, exist_ok=True)
    path = os.path.join(base, "manifest.csv")
    with open(path, "w", newline="", encoding="utf-8") as fh:
        writer = csv.DictWriter(fh, fieldnames=["filename", "payload", "type", "ec"])
        writer.writeheader()
        writer.writerows(FIXTURE_ROWS)
    print(f"fixture_manifest: {path} rows={len(FIXTURE_ROWS)}")
    return 0


def main():
    args = sys.argv[1:]
    if len(args) == 2 and args[0] == "--make-fixture":
        return make_fixture(args[1])
    if len(args) != 2:
        print("usage: codegen_batch.py MANIFEST.csv OUT_DIR")
        print("       codegen_batch.py --make-fixture DIR")
        return 2
    return generate(args[0], args[1])


if __name__ == "__main__":
    raise SystemExit(main())