Converts between the measurement units used throughout print and design workflows. DPI and PPI functions are semantic aliases — numerically identical, provided for clarity in code that mixes screen and print contexts.

import pkgprint

pkgprint.mm_to_inches(25.4)     # 1.0
pkgprint.mm_to_inches(210)      # 8.267716535433072  (A4 width)
pkgprint.inches_to_mm(1)        # 25.4
pkgprint.mm_to_points(25.4)     # 72.0  (1 inch = 72 pt)

Converts between the colour models used in print (CMYK) and screen/web (RGB, hex) workflows. CMYK channels use the 0–100 scale (percentage); RGB channels use 0–255.

import pkgprint

pkgprint.cmyk_to_rgb(0, 100, 100, 0)    # (255, 0, 0)   — pure red
pkgprint.cmyk_to_rgb(0, 0, 0, 100)      # (0, 0, 0)     — process black
pkgprint.rgb_to_cmyk(255, 0, 0)         # (0.0, 100.0, 100.0, 0.0)
pkgprint.rgb_to_hex(255, 0, 0)          # '#FF0000'
pkgprint.hex_to_rgb('#FF0000')          # (255, 0, 0)

Looks up standard paper sizes (ISO A-series, B-series, US Letter/Legal/Tabloid, business cards) and common shipping box sizes. All dimensions are in millimetres. Lookups are case-insensitive.

import pkgprint

pkgprint.paper_size("A4")                 # (210, 297)
pkgprint.paper_size("Letter")             # (216, 279)
pkgprint.paper_size("Business Card US")   # (89, 51)
pkgprint.paper_size("Business Card ISO")  # (85, 55)
pkgprint.box_size("RSC Medium")           # (305, 229, 152)

pkgprint.list_paper_sizes()[:4]
# ['A0', 'A1', 'A2', 'A3']

Note on business card sizes: ISO/European business cards are 85×55 mm; US business cards are 89×51 mm (3.5"×2"). Both are available under distinct names.

Calculates the three key dimension sets in any print-ready file: the bleed size (artwork canvas with bleed added), the safe area (the zone guaranteed not to be trimmed), and the trim size (finished size recovered from a bled-up file).

import pkgprint

# US business card: 89×51 mm trim, 3 mm bleed → canvas size
pkgprint.add_bleed(89, 51)               # (95, 57)

# A4 with 5 mm bleed
pkgprint.add_bleed(210, 297, bleed_mm=5) # (220, 307)

# Safe text area inside A4 (5 mm margin from each edge)
pkgprint.safe_margin(210, 297)           # (200, 287)

# Recover trim size from a 95×57 mm bled-up business card
pkgprint.trim_size(95, 57)               # (89, 51)

Inspects an actual image file and reports whether it meets commercial print requirements. Requires Pillow (installed automatically with pip install pkgprint).

Each check returns a CheckResult with .passed, .actual, .expected, and .message. full_report() collects all three checks without raising on individual failures.

import pkgprint

report = pkgprint.full_report("artwork.tif", 210, 297)

print(report.summary)
# DPI check:        PASS — Effective DPI 304.8 ≥ 300 ...
# Colour mode:      FAIL — Colour mode is 'RGB' but 'CMYK' is required ...
# Dimensions check: PASS — Dimensions 210.0×297.0 mm match target ...
# Overall:          NOT PRINT-READY

report.passed          # False
report.dpi.passed      # True
report.color_mode.passed  # False
report.dimensions.actual  # (210.0, 297.0)

# Individual checks
result = pkgprint.check_dpi("artwork.tif", 210, 297, min_dpi=300)
result.passed    # True / False
result.actual    # effective DPI on the worst axis
result.message   # human-readable diagnostic

Result types: CheckResult(passed, actual, expected, message) and PrintReport(dpi, color_mode, dimensions, passed, summary).

Checks foreground/background colour pairs for legibility using the WCAG 2.1 contrast formulas — useful for packaging with text, label design, or any print piece with brand colour over a background.

WCAG thresholds: AA normal text = 4.5:1, AA large text = 3.0:1, AAA normal = 7.0:1, AAA large = 4.5:1.

import pkgprint

# Pure black on white: maximum contrast
pkgprint.contrast_ratio((0, 0, 0), (255, 255, 255))    # 21.0

# Mid-grey on white: fails AA normal text
result = pkgprint.check_wcag_compliance((140, 140, 140), (255, 255, 255))
result.passed          # False
result.ratio           # 3.36
result.required_ratio  # 4.5
result.message         # 'Contrast ratio 3.36:1 does NOT meet WCAG AA ...'

# Get an adjusted colour that passes
adjusted = pkgprint.suggest_darker_or_lighter(
    (140, 140, 140), (255, 255, 255), target_ratio=4.5
)
adjusted                                               # (118, 118, 118)
pkgprint.contrast_ratio(adjusted, (255, 255, 255))    # 4.54

Result type: ContrastResult(passed, ratio, required_ratio, level, text_size, message).

Calculates the flat sheet dimensions and named panel sizes for common box styles, so designers know how large their artwork canvas needs to be before structural work starts.

Planning formulas only. These are standard industry approximations. They do not account for material thickness, flute direction, or supplier-specific tuck geometry. Confirm with your structural engineer or printer's dieline template before production.

Supported styles in v0.2.0: "RSC" (Regular Slotted Container) and "Mailer" (tuck-end mailer). More styles planned — see Roadmap.

import pkgprint

# Flat canvas for a 300×200×150 mm RSC shipping box
pkgprint.rsc_flat_size(300, 200, 150)        # (1035.0, 350)
# flat_width  = 2×(300+200) + 35 mm glue flap = 1035 mm
# flat_height = 150 + 200 (top + bottom flaps each = W/2) = 350 mm

# Named panels for the same box
panels = pkgprint.panel_layout(300, 200, 150)
len(panels)       # 13  (4 body + 8 flaps + 1 glue flap)
panels[0]         # Panel(name='front', width_mm=300, height_mm=150)
panels[1]         # Panel(name='right side', width_mm=200, height_mm=150)

# Tuck mailer: 200×100×50 mm
pkgprint.mailer_flat_size(200, 100, 50)      # (635.0, 300.0)
pkgprint.panel_layout(200, 100, 50, style="Mailer")
# 7 panels: front, right side, back, left side,
#           top tuck flap, bottom tuck flap, glue flap

Result type: Panel(name, width_mm, height_mm).