EAN-13 TOOLS · v0.1.0

Generation · Validation · ASCII · SVG · PNG · CLI · ISO/IEC 15420

Modular, professional and reusable. Zero dependencies in the core.

📚 INDEX

• ⚡ Tech Stack
• 🗂 Architecture
• 🎯 Features
• 📦 Installation
• 💻 Python API
• ⌨️ CLI
• ❗ Exceptions
• 🧪 Tests

---

⚡ Tech Stack

Module	Role	Deps
generator.py	EAN-13 check digit algorithm	—
validator.py	Full validation (length, chars, check digit)	—
ascii_renderer.py	ASCII barcode render using L/G/R tables	—
image_renderer.py	SVG export (built-in) and PNG (Pillow)	Pillow optional
cli.py	CLI installed as ean13 command	—
exceptions.py	Custom descriptive exception hierarchy	—

---

🗂 Architecture

ean13-tools/
│
├── ean13_tools/
│   ├── __init__.py          ← Public API of the package
│   ├── generator.py         ← Check digit calculation
│   ├── validator.py         ← ISO/IEC 15420 validation
│   ├── ascii_renderer.py    ← ASCII barcode (L, G, R tables)
│   ├── image_renderer.py    ← SVG built-in · PNG via Pillow
│   ├── cli.py               ← `ean13` terminal command
│   └── exceptions.py        ← Custom exception hierarchy
│
└── tests/
   └── test_ean13.py        ← 16 tests · pytest

---

🎯 Features

✔  Generate valid EAN-13 from a 12-digit prefix
✔  Validate complete EAN-13 (bool mode or raise mode)
✔  ASCII render in terminal using █ blocks
✔  Export to SVG with no external dependencies
✔  Export to PNG via Pillow (optional dependency)
✔  Installable CLI: `ean13` command available globally
✔  Descriptive exceptions with exact error messages
✔  16 automated tests with pytest

---

📦 Installation

Core — no external dependencies:

pip install ean13-tools

With PNG support (Pillow):

pip install "ean13-tools[image]"

Development mode (editable):

git clone https://github.com/ogclau/ean13tools
cd ean13-tools
pip install -e .

Verify installation:

ean13 --help

---

💻 Python API

Generate EAN-13

from ean13_tools import generate_ean13

code = generate_ean13("590123412345")
print(code)  # → 5901234123457

Validate

from ean13_tools import validate_ean13

validate_ean13("5901234123457")          # → True
validate_ean13("5901234123450")          # → False

# Strict mode — raises a descriptive exception
validate_ean13("5901234123450", raise_on_error=True)
# → InvalidCheckDigitError: expected 7, got 0

ASCII in terminal

from ean13_tools import render_ascii

print(render_ascii("5901234123457"))
# █ █   █ ██ █  ███ ██  ██  █  ██ ████ ...
# 5   9  0  1  2  3  4    1  2  3  4  5  7

Export SVG

from ean13_tools import render_svg

# As string
svg_str = render_svg("5901234123457")

# As file
render_svg("5901234123457", path="barcode.svg")

Export PNG (requires Pillow)

from ean13_tools import render_png

render_png("5901234123457", path="barcode.png")
render_png("5901234123457", path="barcode@2x.png", scale=4)

---

⌨️ CLI

Once installed, the ean13 command is available in any terminal:

# Generate EAN-13 from a 12-digit prefix
ean13 generate 590123412345
# → 5901234123457

# Validate (exit 0 = valid · exit 1 = invalid)
ean13 validate 5901234123457   # ✓  5901234123457  →  valid
ean13 validate 5901234123450   # ✗  5901234123450  →  INVALID

# ASCII barcode in terminal
ean13 ascii 5901234123457
ean13 ascii 5901234123457 --height 12

# Export SVG
ean13 svg 5901234123457 output.svg

# Export PNG
ean13 png 5901234123457 output.png

The CLI returns exit code 1 when a code is invalid, making it scriptable:

if ean13 validate "$CODE"; then echo "OK"; else echo "Invalid code"; fi

---

⚠️ Exceptions

All exceptions inherit from EAN13Error — catch them broadly or individually:

from ean13_tools import EAN13Error, InvalidCheckDigitError

try:
    validate_ean13("1234567890000", raise_on_error=True)
except InvalidCheckDigitError as e:
    print(e)   # Invalid check digit: expected 5, got 0
except EAN13Error as e:
    print(e)   # any other package error

Exception	When raised
EAN13Error	Base class — catches all package errors
InvalidPrefixLengthError	Prefix is not exactly 12 digits
InvalidLengthError	Code is not exactly 13 digits
InvalidCharactersError	Contains non-numeric characters
InvalidCheckDigitError	Check digit is incorrect

---

🧪 Tests

pip install pytest
pytest tests/ -v

# 16 passed in 0.04s ✓

Built with pure Python · ISO/IEC 15420 · Designed to be reused