Label Module

The label module provides classes for creating text and image labels.

Label classes for Brother P-touch label printers.

class ptouch.label.Label(image, tape)[source]

Bases: object

A label to be printed on a specific tape.

image

The image to print.

Type:: PIL.Image.Image

tape

The tape this label is designed for.

Type:: Tape

__init__(image, tape)[source]

Initialize a label.

Parameters:

image (Image) – The image to print.
tape (type[Tape] | Tape) – The tape class (e.g., Tape36mm) or instance.

prepare(height, resolution_dpi=180)[source]

Prepare the label for printing.

Called by the printer before printing. Override in subclasses that need deferred rendering (e.g., TextLabel).

Parameters:

height (int) – Print height in pixels (tape_config.print_pins).
resolution_dpi (int) – Printer resolution in DPI for mm to pixel conversion.

Return type:

None

class ptouch.label.TextLabel(text, tape, font, font_size=None, align=None, min_width_mm=None, fixed_width_mm=None, auto_size=True)[source]

Bases: Label

A label containing rendered text.

The image is rendered automatically when printed, using the correct height for the printer/tape combination.

class Align(*values)[source]

Bases: Flag

Text alignment options. Combine with | operator, e.g. Align.LEFT | Align.TOP.

LEFT = 1

HCENTER = 2

RIGHT = 4

TOP = 8

VCENTER = 16

BOTTOM = 32

CENTER = 18

__init__(text, tape, font, font_size=None, align=None, min_width_mm=None, fixed_width_mm=None, auto_size=True)[source]

Initialize a text label.

Parameters:

text (str) – Text to render.
tape (type[Tape] | Tape) – The tape class (e.g., Tape36mm) or instance.
font (str | FreeTypeFont) – Path to TrueType font file, or a pre-loaded ImageFont object.
font_size (int | None) – Font size in pixels. Only used when auto_size=False.
align (Align | None) – Text alignment. Combine horizontal (LEFT, HCENTER, RIGHT) and vertical (TOP, VCENTER, BOTTOM) with |, e.g. Align.LEFT | Align.TOP. Use Align.CENTER for both horizontally and vertically centered.
min_width_mm (float | None) – Minimum label width in millimeters. If specified, the label will be padded to at least this width. Ignored when fixed_width_mm is set.
fixed_width_mm (float | None) – Fixed label width in millimeters. If specified, the label is locked to exactly this width and the font is scaled down so the text fits within it (it does not expand the label to the text size).
auto_size (bool) – If True, automatically size the font to 80% of the print height. If False, use font_size (for path strings) or the ImageFont’s built-in size.

property image: Image: Get the rendered image.

prepare(height, resolution_dpi=180)[source]

Render the text to an image.

Parameters:

height (int) – Image height in pixels (tape_config.print_pins).
resolution_dpi (int) – Printer resolution in DPI for mm to pixel conversion.

Return type:

None

class ptouch.label.Align(*values)

Bases: Flag

Text alignment options. Combine with | operator, e.g. Align.LEFT | Align.TOP.

LEFT = 1

HCENTER = 2

RIGHT = 4

TOP = 8

VCENTER = 16

BOTTOM = 32

CENTER = 18

Label Types

Label

Base class for image-based labels. Use this when you have a pre-rendered image.

Key attributes:

image - PIL Image object
tape - Tape type (e.g., Tape36mm)

TextLabel

Specialized label class for text rendering with automatic sizing and alignment.

Key attributes:

text - Text to print
tape - Tape type
font - ImageFont object or path to TTF file
align - Alignment flags (e.g., TextLabel.Align.CENTER)
auto_size - Whether to auto-size font to tape height (default: True)
width_mm - Fixed label width in mm (default: None for auto-width)

Alignment Options

Text alignment can be combined using the | operator:

Horizontal Alignment

Align.LEFT - Align text to left edge
Align.HCENTER - Center text horizontally
Align.RIGHT - Align text to right edge

Vertical Alignment

Align.TOP - Align text to top edge
Align.VCENTER - Center text vertically
Align.BOTTOM - Align text to bottom edge

Combined Alignment

Align.CENTER - Center both horizontally and vertically (HCENTER | VCENTER)

Example Usage

Image Label

from PIL import Image
from ptouch import Label, Tape36mm

image = Image.open("logo.png")
label = Label(image, Tape36mm)
printer.print(label)

Text Label with Auto-Sizing

from ptouch import TextLabel, Tape36mm
from PIL import ImageFont

font = ImageFont.load_default()
label = TextLabel(
    "Hello World",
    Tape36mm,
    font=font,
    align=TextLabel.Align.CENTER
)

Text Label with Fixed Size

font = ImageFont.truetype("/path/to/font.ttf", 48)
label = TextLabel(
    "Fixed Size",
    Tape36mm,
    font=font,
    auto_size=False,  # Use font's built-in size
    align=TextLabel.Align.LEFT | TextLabel.Align.TOP
)

Text Label with Fixed Width

label = TextLabel(
    "Short",
    Tape36mm,
    font=font,
    width_mm=50.0  # Create 50mm wide label
)

Custom Alignment

# Top-left alignment
label = TextLabel(
    "Top Left",
    Tape36mm,
    font=font,
    align=TextLabel.Align.LEFT | TextLabel.Align.TOP
)

# Bottom-right alignment
label = TextLabel(
    "Bottom Right",
    Tape36mm,
    font=font,
    align=TextLabel.Align.RIGHT | TextLabel.Align.BOTTOM
)

# Centered (shorthand)
label = TextLabel(
    "Centered",
    Tape36mm,
    font=font,
    align=TextLabel.Align.CENTER
)