Shared types

Shared typing helpers for pyStrich encoders and renderers.

class BarcodeRenderOptions

Bases: TypedDict

Optional render-time tweaks for label-bearing 1D barcodes.

Currently used by pystrich.code128.Code128Encoder and pystrich.code39.Code39Encoder. All keys are optional; omitted keys fall back to library defaults.

show_label: bool

Whether to render the human-readable label underneath the bars. Defaults to True; set to False to suppress it.

ttf_font: str

Absolute path to a TrueType font file used for the label in PNG output. Defaults to a bundled bitmap font if unset. SVG and EPS output always render the label using the bundled Courier Prime glyph paths and ignore this option.

ttf_fontsize: int

Font size in points (PNG output only — SVG/EPS use the bundled Courier Prime glyph paths).

height: int

Total image height in pixels. Defaults to roughly a third of the image width for Code 128, and to 120 for Code 39.

label_border: int

Pixels of vertical space between the bars and the label.

bottom_border: int

Pixels of vertical space between the label and the bottom edge.

Matrix mark extraction shared by vector renderers (SVG, EPS, DXF).

class MatrixMark(x: int, y: int, width: int, height: int)

Bases: NamedTuple

A rectangular region of a matrix to be drawn as a single shape.

x: int

Alias for field number 0

y: int

Alias for field number 1

width: int

Alias for field number 2

height: int

Alias for field number 3

class MarkShape(*values)

Bases: Enum

How marked cells are grouped and drawn in vector output.

Each value selects a grouping (one MatrixMark per cell, or one per horizontal run) and – where the renderer supports it – the drawing primitive used per mark.

HORIZONTAL_RUNS = 1

Maximal horizontal runs of matched cells, drawn as filled rectangles.

SQUARE_CELLS = 2

One 1x1 region per matched cell, drawn as a filled rectangle.

CIRCULAR_CELLS = 3

One 1x1 region per matched cell, drawn as a filled circle inscribed in the cell.

iter_horizontal_runs(matrix: Sequence[Sequence[int | None]], *, mark_values_when: bool) → Iterator[MatrixMark]

Yield each maximal horizontal run of cells whose truthiness equals mark_values_when.

mark_values_when=True marks the dark (truthy) cells; False marks the light cells (0 or None). Each yielded mark has height=1.

iter_cells(matrix: Sequence[Sequence[int | None]], *, mark_values_when: bool) → Iterator[MatrixMark]

Yield a 1x1 mark for every cell whose truthiness equals mark_values_when.

iter_marks(matrix: Sequence[Sequence[int | None]], *, mark_values_when: bool, mark_shape: MarkShape) → Iterator[MatrixMark]

Yield MatrixMark regions for the chosen mark_shape.

class TextLabel(text: str, x: float, y: float, font_size: int, anchor: str = 'start')

Bases: NamedTuple

A run of text to render below the bars in vector output.

Coordinates are in pixels (= user units for SVG/EPS at default DPI), and y is the top edge of the text — matching the convention used by PIL.ImageDraw.text(xy, ...) for the corresponding raster path. anchor controls how x relates to the text run: "start" is the left edge, "middle" the centre, "end" the right edge.

text: str

Alias for field number 0

x: float

Alias for field number 1

y: float

Alias for field number 2

font_size: int

Alias for field number 3

anchor: str

Alias for field number 4

class BarLayout(heights: Sequence[int], bar_width: int, quiet_left: int = 0, quiet_right: int = 0, quiet_top: int = 0, quiet_bottom: int = 0, labels: Sequence[TextLabel] = ())

Bases: NamedTuple

Pixel-precise layout of a 1D barcode for any output format.

All values are in pixels (= user units for SVG/EPS at default DPI). heights[i] is the bar’s pixel height at column i (0 is a gap). Each column is bar_width pixels wide. The four quiet zones frame the symbol; quiet_left and quiet_top shift the bars, while quiet_right and quiet_bottom only enlarge the canvas. labels carries the human-readable text drawn beneath the bars by SVG/EPS renderers; the PNG path renders text via PIL directly and ignores this field.

heights: Sequence[int]

Alias for field number 0

bar_width: int

Alias for field number 1

quiet_left: int

Alias for field number 2

quiet_right: int

Alias for field number 3

quiet_top: int

Alias for field number 4

quiet_bottom: int

Alias for field number 5

labels: Sequence[TextLabel]

Alias for field number 6

iter_bar_marks(heights: Sequence[int], bar_width: int, *, quiet_left: int = 0, quiet_top: int = 0) → Iterator[MatrixMark]

Yield a MatrixMark per maximal run of equal positive heights.

Coordinates and dimensions are in pixels. heights[i] is the bar’s pixel height at column i (0 is a gap; positive values are bars sharing a top edge at y = quiet_top). Each column is bar_width pixels wide. Adjacent columns with the same positive height collapse into one mark.

Only quiet_left and quiet_top are accepted because they are the only offsets that affect mark coordinates; the right and bottom quiet zones are a renderer concern (canvas / viewBox sizing).