ar-book-labels

English | 简体中文

Generate printable Accelerated Reader book labels from an Excel spreadsheet. Labels include book title, author, AR level (with standard color coding), points, and quiz number — formatted for sticker-style printing and sticking on books.

Table of Contents

• Features
• Installation
• Quick Start
• CLI Usage
  • Options
  • Examples
• Label Size Presets
• Page Size Presets
• Configuration File
• Input Format (Excel & CSV)
• AR Level Color Chart
• Custom Color Scheme
• Development
• License

Features

• Flexible label sizing: 4 built-in presets (50x30, 70x37, 63x38, 99x38) or custom dimensions via --label-size
• Multiple page sizes: 7 presets (A4, A5, A3, Letter, Legal, B5, B4) or custom dimensions via --page-size
• Auto grid layout: Columns, rows, and centering are computed automatically from label size
• Manual grid override: Specify exact columns × rows with --grid (e.g. 4x9)
• Customizable spacing: Column gap (--col-gap), row gap (--row-gap), and page margin (--margin)
• CSV & Excel input: Read book data from .csv or .xlsx files (auto-detected by extension)
• Standard AR color coding: 12 color ranges from yellow (0.1–1.5) to brown (6.6+)
• Custom color scheme: Override AR colors with --colors
• Black-and-white mode: --bw for ink-saving printing
• Cutting-guide border: --with-border adds a thin printable border for manual cutting
• Typography control: Custom font family (--font) and border radius (--radius)
• YAML/JSON config: Reusable configuration files via --config
• Config generation: --generate-config creates an example config file to get started quickly
• Smart text truncation: Titles wrap to 2 lines with ellipsis; authors on 1 line
• Author-first layout: Author name appears above title for easy shelf sorting
• Print-ready HTML: @page CSS for direct printing; screen preview via --scale
• Template included: Reference Excel template with sample data and column documentation

Installation

pip install ar-book-labels

For YAML config file support:

pip install ar-book-labels[yaml]

Or install from source:

git clone https://github.com/TonyBlur/ar-book-labels.git
cd ar-book-labels
pip install -e .

Quick Start

1. Get the template (optional — if you don't have an Excel file yet):

ar-book-labels --template

This copies ar_template.xlsx to your current directory. Fill it with your book data.

2. Generate labels:

ar-book-labels books.xlsx -o labels.html

3. Open labels.html in a browser to preview, then print (Ctrl/Cmd+P).

   Print tip: In the browser print dialog, choose "Actual size" (or "No margins" / "None" for margins) to prevent the browser from auto-adding page margins that shift label positions. The HTML already declares @page { margin: 0 }; adding browser margins on top causes misalignment.

CLI Usage

ar-book-labels <excel> [options]

Options

Input & Output

Column Mapping

Layout

Appearance

Configuration

Examples

# Basic usage (default 50x30mm labels)
ar-book-labels my_books.xlsx

# CSV input (auto-detected by extension)
ar-book-labels my_books.csv -o labels.html

# Generate an example config file
ar-book-labels --generate-config my_config.yaml
ar-book-labels --generate-config my_config.json

# Custom output path and sheet name
ar-book-labels my_books.xlsx -o output/labels.html -s "Book Data"

# Larger labels (70x37mm, 21 per page)
ar-book-labels my_books.xlsx --label-size 70x37

# Avery 5160 compatible labels
ar-book-labels my_books.xlsx --label-size 63x38

# Custom dimensions with wider gaps
ar-book-labels my_books.xlsx --label-size 60x40 --col-gap 3 --row-gap 2

# Letter paper (US)
ar-book-labels my_books.xlsx --page-size Letter

# A5 paper with manual 2×5 grid
ar-book-labels my_books.xlsx --page-size A5 --grid 2x5

# Manual grid layout (4 columns × 9 rows)
ar-book-labels my_books.xlsx --grid 4x9

# Custom page size (WxH in mm)
ar-book-labels my_books.xlsx --page-size 150x200

# Tighter margins (10mm)
ar-book-labels my_books.xlsx --margin 10

# Custom font (e.g. for Chinese titles)
ar-book-labels my_books.xlsx --font "Noto Sans SC, sans-serif"

# Square corners
ar-book-labels my_books.xlsx --radius 0

# Custom color scheme
ar-book-labels my_books.xlsx --colors "0.1-2.0:#FFD700,2.1-4.0:#2E8B57,4.1-6.0:#DC143C,6.1-99:#8B4513"

# Black-and-white mode with border
ar-book-labels my_books.xlsx --bw --with-border

# Use a config file
ar-book-labels my_books.xlsx --config ar-book-labels.yaml

# Copy the template for reference
ar-book-labels --template

Label Size Presets

Custom sizes are also supported: --label-size WxH where W and H are in millimeters.

When using a custom or preset size, the grid (columns, rows) is calculated automatically and labels are centered horizontally on the page.

Page Size Presets

Custom page sizes are also supported: --page-size WxH where W and H are in millimeters.

When the label grid doesn't fit the chosen page size (e.g. too-wide labels on a small page), the tool reports a clear error with suggestions for fixing it.

Configuration File

For reusable settings, create a YAML or JSON config file:

# ar-book-labels.yaml
label_size: "50x30"
page_size: "A4"        # A4, A5, A3, Letter, Legal, B5, B4, or WxH
# grid: "4x9"          # Manual grid override (COLSxROWS)
col_gap: 2
row_gap: 0
margin: 13.5
font: "'Segoe UI', system-ui, sans-serif"
radius: 4
bw: false
with_border: false
# colors: "0.1-1.5:#FFD700,1.6-2.0:#2E8B57,..."

ar-book-labels my_books.xlsx --config ar-book-labels.yaml

Priority: CLI arguments > config file > defaults.

An example config file is available at ar_labels_config.example.yaml.

YAML support requires the optional pyyaml dependency:

pip install ar-book-labels[yaml]

JSON config files work without any extra dependencies.

Input Format (Excel & CSV)

The tool accepts both Excel (.xlsx) and CSV (.csv) files. The format is auto-detected from the file extension.

The spreadsheet must contain these columns (default names shown; use --col-* options to map custom names):

Rows with missing required fields are skipped with a warning printed to stderr.

Use ar-book-labels --template to get a pre-formatted template with sample data.

AR Level Color Chart

Custom Color Scheme

Override the default AR color scheme with --colors:

ar-book-labels my_books.xlsx --colors "0.1-2.0:#FFD700,2.1-4.0:#2E8B57,4.1-6.0:#DC143C,6.1-99:#8B4513"

Format: min-max:#HEX,min-max:#HEX,...

• Each range is min-max:#HEX (level range → color)
• Ranges are separated by commas
• Ranges should cover the full level spectrum (0.1–99)
• In black-and-white mode (--bw), custom colors are ignored

Development

Setup

git clone https://github.com/TonyBlur/ar-book-labels.git
cd ar-book-labels
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[yaml,dev]"

Project Structure

ar-book-labels/
  ar_book_labels/
    __init__.py        # Package metadata and public API
    layout.py          # Layout dataclass + grid computation
    config.py          # Config loading (YAML/JSON) + merging
    generator.py       # Core label generation logic
    cli.py             # CLI entry point (argparse)
    __main__.py        # python -m ar_book_labels support
    templates/
      ar_template.xlsx # Reference Excel template
  tests/
    test_layout.py     # Layout computation tests
    test_config.py     # Config loading tests
    test_generator.py  # Generator tests
  ar_labels_config.example.yaml  # Example config file
  pyproject.toml       # Build configuration (setuptools)
  LICENSE              # MIT License
  README.md            # This file (English)
  README.zh.md         # 中文文档

Running Tests

python -m pytest tests/ -v

Building & Publishing

pip install build twine
python -m build
twine check dist/*
twine upload dist/*

Automated Publishing (GitHub Actions)

This project uses a GitHub Actions workflow to automatically publish to PyPI when a new release is created:

1. Bump the version in pyproject.toml
2. Create a new release on GitHub (via the web UI or gh release create)
3. The publish.yml workflow will automatically build the package and publish it to PyPI using trusted publishing (OIDC — no API token needed)

Prerequisites: Configure a Trusted Publisher on PyPI for the ar-book-labels project, linking it to the TonyBlur/ar-book-labels repository and the pypi environment.

Code Style

• Python 3.8+
• Minimal external dependencies (openpyxl required, pyyaml optional)
• Keep the generator logic self-contained and testable

License

MIT — see LICENSE for details.