validation.gtin

def validate_gtin(value: str) -> GtinCheck

@dataclass(frozen=True)
class GtinCheck:
    """The result of checking a GTIN. Every string is null when valid is false; reason is null when it is true."""

    valid: bool
    #: the digits only, at the length given
    normalised: Optional[str]
    #: ean-8, upc-a, ean-13 or gtin-14, from the length
    kind: Optional[str]
    #: left-padded with zeros to 14 digits, the form to compare and store
    gtin14: Optional[str]
    #: empty, bad-character, bad-length, all-zero or bad-check-digit
    reason: Optional[str]

from fune.validation.gtin import validate_gtin  # validation.gtin@^1

from typing import List

from .validation_gs1_check_digit import is_gs1_check_digit_valid  ← from validation.gs1-check-digit ^1.0.0 · built alongside by fune
from .validation_gtin_types import GtinCheck

#: The four GTIN lengths, and what each is called.
_KINDS = {8: "ean-8", 12: "upc-a", 13: "ean-13", 14: "gtin-14"}


def _invalid(reason: str) -> GtinCheck:
    return GtinCheck(valid=False, normalised=None, kind=None, gtin14=None, reason=reason)


def validate_gtin(value: str) -> GtinCheck:
    """Check an EAN-8, UPC-A, EAN-13 or GTIN-14 against the GS1 mod-10 check digit.

    A pass means the number was typed correctly, not that GS1 issued it.
    Validators answer rather than raise: a malformed value is the answer "no".
    """
    if not isinstance(value, str):
        return _invalid("empty")

    # Barcodes are printed in groups, so spaces and hyphens are ignored anywhere.
    chars: List[str] = [ch for ch in value if ch != " " and ch != "-"]
    if not chars:
        return _invalid("empty")
    # Compare against ASCII explicitly: str.isdigit() accepts Arabic-Indic and
    # superscript digits, which the other two languages would reject.
    if any(ch < "0" or ch > "9" for ch in chars):
        return _invalid("bad-character")
    digits = "".join(chars)
    kind = _KINDS.get(len(digits))
    if kind is None:
        return _invalid("bad-length")
    # Zero everywhere satisfies the arithmetic and has never been allocated.
    if all(ch == "0" for ch in digits):
        return _invalid("all-zero")

    # The GS1 mod-10 check, weighted from the right, which is what makes one
    # rule serve all four lengths (EAN-13's first digit gets 1, EAN-8's and
    # UPC-A's get 3).
    if not is_gs1_check_digit_valid(digits):
        return _invalid("bad-check-digit")

    return GtinCheck(valid=True, normalised=digits, kind=kind, gtin14=digits.rjust(14, "0"), reason=None)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add validation.gtin

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./validation.gtin-1.1.0-python.fune, or fetch it from a terminal with fune pull validation.gtin@1.1.0:python.

The whole function, every language, is one file too: validation.gtin-1.1.0.fune, 15,693 bytes, sha256 34abcea03c11dbc84715b68a15149e3b346a65ea45084ac80d49792f3adec583. It installs into a project of any language.

# fune: before validation.gtin

# fune: after validation.gtin

# fune: replace validation.gs1-check-digit in validation.gtin

# fune: step validation.gtin after <n|label>

More from the author

Weighting from the right is the detail home-grown validators get wrong. EAN-13 weights its first digit 1, but EAN-8 and UPC-A weight their first digit 3, so code that always starts at the left with 1 accepts only EAN-13 and GTIN-14.

A PASSING NUMBER IS WELL FORMED, NOT ALLOCATED. The check catches every single mistyped digit and most adjacent transpositions. It cannot say whether GS1 has issued the number or what product it is on; only GS1's registry (Verified by GS1) can.

RESULT: `valid`, then on success the digits (`normalised`), the `kind` implied by the length, and `gtin14`, the number left-padded with zeros to 14 digits. GS1 defines every GTIN as a 14-digit number with leading zeros, so `gtin14` is the form to store and compare: the UPC-A 036000291452 and the EAN-13 0036000291452 are the same item. `kind` is read from the length as given; an EAN-13 beginning with 0 is not re-labelled as a UPC-A.

ACCEPTED INPUT: ASCII digits, with ASCII spaces and hyphens ignored anywhere, because barcodes are printed in groups ("5 012345 678900"). Anything else makes the value invalid.

| reason | meaning | |-------------------|----------------------------------------------------------| | `empty` | nothing but spaces and hyphens, or not a string at all | | `bad-character` | something other than a digit, space or hyphen | | `bad-length` | not 8, 12, 13 or 14 digits | | `all-zero` | every digit is 0: satisfies the arithmetic, never issued | | `bad-check-digit` | the last digit does not match |

The checks run in that order and the first failure is the reason. Validators answer rather than throw.

Out of scope: GS1 prefix meaning (country of the member organisation, 978/979 Bookland, 02/20-29 restricted in-store numbers), GTIN-12 zero-suppressed UPC-E, and add-on codes. For ISBNs use validation.isbn, which also checks the prefix.

Source: GS1 General Specifications, section 7.9 "Check digit calculation" (https://www.gs1.org/services/how-calculate-check-digit-manually).

Files