BookBarcode

BookBarcode generates deterministic ISBN-13/EAN-13 barcodes for books. It creates editable SVG files and print-ready PDF files, and checks each artifact before writing it.

• PDF is the recommended final format for printing. It uses true process black: C:0 M:0 Y:0 K:100.
• SVG is useful for vector editing and preview. It includes CMYK intent metadata, although colour handling ultimately depends on the SVG application.

The package has no runtime third-party dependencies and supports Python 3.9+.

Example generated from the ISBN used in the International ISBN Agency's Users' Manual.

Choose an entrypoint

I want to...	Start with
Generate a barcode from a terminal	Human CLI
Use BookBarcode from Python	Python API
Call BookBarcode from an agent	JSON agent interface

Quick start

Install the current release from PyPI:

python3 -m pip install "bookbarcode==0.4.1"

Generate both formats with a valid ISBN-13:

bookbarcode 9789295055124 \
  --display "ISBN 978-92-95055-12-4"

This creates and verifies these files in the current directory:

book-barcode.svg
book-barcode.pdf

The command refuses to replace an existing file unless you add --overwrite. It writes a temporary sibling, verifies it, then atomically installs it at the target path.

For an editable development installation, clone the repository first:

git clone https://github.com/Aues12/BookBarcode.git
cd BookBarcode
python3 -m pip install -e .

You can also run the command from this repository without installing it:

python3 -m bookbarcode.cli 9789295055124 \
  --display "ISBN 978-92-95055-12-4"

Common tasks

Create a print-ready PDF at a chosen path:

bookbarcode 9789295055124 \
  --format pdf \
  --output output/book-barcode

Use the smallest bundled layout when space is constrained:

bookbarcode 9789295055124 \
  --preset minimum \
  --output output/small-book-barcode

Use assigned ISBN hyphenation in the visible heading:

bookbarcode 9780306406157 \
  --display "ISBN 978-0-306-40615-7" \
  --output output/book-barcode

Without --display, BookBarcode uses a readable 3-3-3-3-1 fallback. This is not an assertion about official ISBN registrant ranges; provide the assigned hyphenation when it matters.

Layout and output

Preset	Dimensions	Best for
normal (default)	35 × 19 mm	Typical book barcodes
minimum	26 × 14 mm	Space-constrained covers

By default, BookBarcode writes both SVG and PDF. Use --format svg or --format pdf to select one. --output sets the base path, so --output output/barcode produces output/barcode.svg and/or output/barcode.pdf; the directory must already exist.

Custom total dimensions, data-bar height, and either shared or independent side margins are available. The detailed commands and the full option reference are in the English user guide. Their mandatory formulas, dependencies, and constraints are defined by the measurement dependency DAG.

Python API

Generate content without writing files:

from bookbarcode import Barcode

barcode = Barcode("9789295055124")
svg_text = barcode.to_svg()
pdf_bytes = barcode.to_pdf()

Write verified artifacts explicitly:

from bookbarcode import Barcode, BarcodeLayout

layout = BarcodeLayout(
    width_mm=38,
    height_mm=20,
    side_margin_mm=3.8,
    bar_height_mm=12.5,
)
barcode = Barcode(
    "9789295055124",
    display_text="ISBN 978-92-95055-12-4",
    layout=layout,
)
barcode.write_svg("book-barcode.svg")
barcode.write_pdf("book-barcode.pdf")

One module (X) is the narrowest EAN-13 bar/space unit. Custom margins are accepted only when they preserve quiet zones of at least 11X on the left and 7X on the right.

For explicit intent/resolution separation, use the typed measurement pipeline:

from bookbarcode import LayoutSpec, build_barcode_geometry, resolve_layout

spec = LayoutSpec.from_preset("normal", side_margin_mm=3.5)
resolved = resolve_layout(spec)
geometry = build_barcode_geometry(
    "9789295055124",
    "ISBN 978-92-95055-12-4",
    resolved,
)

resolved contains no optional measurements. geometry contains the complete title, bar, and human-readable digit positions consumed by both renderers.

Agent-tools JSON interface

Agent tools can use BookBarcode as a tool by sending a JSON request envelope to isbn_barcode.py over standard input. The adapter translates that request to the same package API used by Python and the CLI; it does not implement barcode rules independently.

printf '%s' '{
  "operation": "write_barcode",
  "params": {
    "isbn": "9789295055124",
    "output_base": "/tmp/book-barcode",
    "layout": {"preset": "normal"}
  }
}' | python3 isbn_barcode.py

Supported operations are generate_svg, write_svg, write_pdf, write_barcode, verify_svg, and verify_pdf. Agents and runtimes should read the tool usage procedure; SKILL.yaml is the canonical local machine-readable manifest.

Documentation

• Changelog — release history and notable changes by version.
• English user guide — installation, complete CLI reference, custom layouts, printing guidance, common errors, and examples.
• Türkçe kullanım kılavuzu
• Agent tool usage procedure
• Canonical measurement dependency DAG
• KDY size and colour reference notes
• KDY ölçü ve renk referans notları

Quality and printing

BookBarcode verifies serialized SVG and PDF dimensions, barcode modules, guard bars, readable ISBN digits, physical geometry, and colour intent. PDF checks parse the content stream rather than trusting the renderer's input geometry. For production, keep quiet zones clear, do not scale the barcode non-proportionally or rasterize it, and scan a printed sample after printer preflight.

Run the test suite from the repository root:

python3 -m unittest discover -s tests -v

BookBarcode is released under the MIT License.