Build a Validated Seed-Tray CSV Report with Python’s Standard Library

PlantsSeed — Thu, 12 Nov 2026 06:45:19 +0000

Disclosure: This tutorial is published by the PlantsSeed brand account and was prepared with AI assistance. The dataset below is synthetic, not a customer dataset, a product trial, or evidence about growing performance. No hardware integration or professional developer experience is claimed.

A small, useful data problem

A propagation notebook often starts as a spreadsheet: a tray identifier, the number of seeds sown, and the number of seedlings counted on a particular date. Turning that notebook into a report sounds trivial until a blank cell becomes a zero, a repeated observation gets counted twice, or someone compares percentages with different denominators. These are ordinary software problems with a concrete domain attached. This tutorial builds a deliberately small command-line report with Python's standard library, so the complete transformation can be inspected without installing a framework.

The goal is to validate a CSV file, produce one final observed emergence percentage per tray, and calculate a correctly weighted overall percentage. It is not to recommend a germination temperature, diagnose plant disease, or compare commercial equipment. In particular, emergence means a visible seedling was counted. It does not prove that every unobserved seed failed to germinate. Keeping that distinction in the output prevents a neat-looking report from making a stronger biological claim than the data supports.

Define the contract before writing the loop

Use one row per tray for a single reporting date. The columns are tray_id, sown, and emerged. The identifier must be nonempty and unique. Both counts must be whole numbers, sown must be positive, and emerged must lie between zero and sown. A blank count is missing information and must be rejected. It should never silently become zero. This contract deliberately excludes time-series observations: if you record the same tray daily, select one reporting date before using this program.

Save the following example as trays.csv. These four fictional trays are designed to make the arithmetic easy to check manually. The names identify records only; they do not encode a species, treatment, or experimental group.

tray_id,sown,emerged
A,10,8
B,20,10
C,5,0
D,5,5

Tray A has eight observed seedlings out of ten seeds. Tray B has ten out of twenty. Tray C records an actual observed zero, which is different from a missing count. Tray D records five out of five. A useful first acceptance criterion is therefore that the program prints 80.0%, 50.0%, 0.0%, and 100.0% respectively, in the same order as the file. Preserving input order makes it easier to compare the output against a paper notebook.

Implement a strict reader and a pure calculation

Save this as report.py. It targets Python 3.9 or newer and uses only csv, pathlib, and sys. The functions separate reading, validation, summarisation, and presentation. That separation is modest but useful: the calculations can be tested without creating files, while the CSV reader can attach row numbers to malformed input.

import csv
import sys
from pathlib import Path

FIELDS = ["tray_id", "sown", "emerged"]


def read_trays(path):
    trays = []
    seen = set()
    with Path(path).open(newline="", encoding="utf-8-sig") as source:
        reader = csv.DictReader(source)
        if reader.fieldnames != FIELDS:
            raise ValueError("header must be: tray_id,sown,emerged")
        for line, row in enumerate(reader, start=2):
            if None in row or any(row.get(k) is None for k in FIELDS):
                raise ValueError(f"line {line}: wrong number of columns")
            tray = row["tray_id"].strip()
            if not tray or tray in seen:
                raise ValueError(f"line {line}: missing or duplicate tray_id")
            try:
                sown = int(row["sown"])
                emerged = int(row["emerged"])
            except (TypeError, ValueError):
                raise ValueError(f"line {line}: counts must be integers") from None
            if sown <= 0 or not 0 <= emerged <= sown:
                raise ValueError(f"line {line}: invalid count range")
            seen.add(tray)
            trays.append((tray, sown, emerged))
    if not trays:
        raise ValueError("file contains no tray records")
    return trays


def summarise(trays):
    sown = sum(row[1] for row in trays)
    emerged = sum(row[2] for row in trays)
    if sown <= 0:
        raise ValueError("total sown must be positive")
    return sown, emerged, 100 * emerged / sown


def main(argv):
    if len(argv) != 2:
        print("Usage: python3 report.py trays.csv", file=sys.stderr)
        return 2
    try:
        trays = read_trays(argv[1])
        sown, emerged, percent = summarise(trays)
    except (OSError, UnicodeError, csv.Error, ValueError) as error:
        print(f"Input error: {error}", file=sys.stderr)
        return 2
    for tray, count, observed in trays:
        print(f"{tray}: {observed}/{count} ({100 * observed / count:.1f}%)")
    print(f"Overall observed emergence: {emerged}/{sown} ({percent:.1f}%)")
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv))

The utf-8-sig encoding accepts ordinary UTF-8 and strips a leading byte-order mark sometimes introduced by spreadsheet exports. Opening with newline="" lets the csv module handle line endings. The exact header check catches accidental renaming and reordered columns rather than guessing what the author intended. This is a choice, not a universal best practice: for a public import service you might support documented aliases, but a small local tool benefits from one unambiguous format.

The reader also rejects both extra and missing columns. DictReader represents those cases differently, which is why the condition checks for a None key as well as None values. A duplicated identifier is rejected instead of aggregated. Aggregation could hide a repeated export row or combine observations from different dates. If duplicate identifiers are legitimate in your workflow, extend the schema with a date or batch identifier and define a composite key explicitly.

Run it and inspect the expected output

From the directory containing both files, run python3 report.py trays.csv. The expected final line is Overall observed emergence: 23/40 (57.5%). This is the most important number to check by hand: eight plus ten plus zero plus five equals twenty-three, and the four denominators sum to forty. The overall calculation divides the sum of the numerators by the sum of the denominators.

Do not take the simple mean of the four tray percentages. That would give 57.5% in this particular example by coincidence, which makes this dataset alone insufficient to detect the bug. Add a second test containing one tray with one seed and one observed seedling, plus another with ninety-nine seeds and zero observed seedlings. The correct pooled result is 1/100, or 1.0%. An unweighted mean incorrectly gives 50.0%. Choosing an asymmetric test is more informative than simply adding more realistic-looking rows.

Test failure paths as part of the feature

A report is only trustworthy if bad input produces a clear failure. Copy trays.csv to a temporary file and remove the emerged value from one row. The command should return status 2 and explain that counts must be integers. Next, change a count so emerged exceeds sown. It should reject the invalid range. Repeat an identifier and verify that the duplicate is caught. Try a header-only file as well: no records is an error, not a report claiming zero percent emergence.

For a minimal automated arithmetic check, create test_report.py beside report.py:

import unittest
from report import summarise


class SummaryTests(unittest.TestCase):
    def test_weighted_percentage(self):
        total, observed, percent = summarise([
            ("small", 1, 1), ("large", 99, 0)
        ])
        self.assertEqual((total, observed), (100, 1))
        self.assertAlmostEqual(percent, 1.0)

    def test_zero_observations_are_valid(self):
        self.assertEqual(summarise([("tray", 12, 0)]), (12, 0, 0.0))


if __name__ == "__main__":
    unittest.main()

Run python3 -m unittest -v. These tests target two meaningful errors: incorrect weighting and incorrectly treating an observed zero as missing. They do not establish that the reader handles every malformed file. For a maintained tool, add temporary-file tests for duplicate identifiers, missing columns, unexpected columns, and noninteger counts. Keep each test named after a behaviour, so a failure explains what guarantee was lost rather than merely which internal line changed.

Know what the numbers cannot tell you

A pooled percentage describes the records supplied to the program. It does not adjust for sowing dates, seed age, species, tray position, watering, light, or different counting intervals. A tray counted on day three is not directly comparable to one counted on day fourteen. Before comparing batches, record the observation date and days since sowing, then define the comparison window. Retain the raw observations so a later correction can be traced back to its source.

Rounding belongs at presentation time. The program retains the calculation as a floating-point value and formats it to one decimal place only when printing. Do not feed rounded tray percentages back into an overall calculation. For these small integer counts, binary floating-point is adequate for display; if an application later requires exact decimal accounting, choose a representation based on that requirement rather than adding complexity automatically.

Extend carefully rather than collecting everything

A sensible next version could add an observation_date column and export a summary CSV. Validate dates with datetime.date.fromisoformat and document whether a row is a daily observation or a final snapshot. If you add temperature readings, include units and sensor placement; an ambient reading is not automatically the compost temperature. Resist presenting correlations as evidence that a product caused an improvement. Establishing causation needs an appropriate experiment, not just another chart.

This example comes from the record-keeping context of PlantsSeed, but the implementation is independent of any shop or device. It makes no network requests, collects no personal details, and needs no commercial service. Keep customer names and email addresses out of a growing log unless there is a separate, legitimate reason to process them. If the tool later becomes a web upload form, add file-size limits, authentication where appropriate, and a clear retention policy before accepting other people's files.

The useful deliverable is a transparent transformation: a documented input contract, explicit rejection of impossible records, a weighted calculation, and a result that can be checked with a calculator. Those habits transfer to inventory counts, classroom observations, and many other small datasets. Consult the Python documentation for csv.DictReader and unittest when extending the program, and treat horticultural interpretation as a separate question from whether the software arithmetic is correct.

DEV Community: PlantsSeed