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.

quiet_width_multiplier: int

Width of the quiet zone on each side, in narrow-bar widths. Defaults to 10, the minimum required by both symbologies.

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

class SymbolMarks(marks: tuple[MatrixMark, ...], width: int, height: int)

Bases: NamedTuple

A rendered symbol as dark rectangles in a unit grid.

marks are the dark regions as (x, y, width, height) rectangles, with a top-left origin and y pointing down (matching the matrix, PIL and SVG). width and height are the full extent of the grid the marks live in – the same canvas every other output format draws, so quiet zones, finder pattern and (for 1D) the bearer bar and the space reserved for the human-readable label are all included – and a consumer can fit [0, width] x [0, height] into any target box at any scale. The label glyphs themselves are never marks. For 2D symbols one unit is one module; for 1D symbols the x unit is one narrow bar and the y unit is one pixel of the bar layout.

marks: tuple[tuple[int, int, int, int], ...]

Alias for field number 0

width: int

Alias for field number 1

height: int

Alias for field number 2

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[tuple[int, int, int, int]]

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[tuple[int, int, int, int]]

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[tuple[int, int, int, int]]

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] = (), bearer_width: int = 0)

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, rendered identically by the PNG, SVG and EPS paths. bearer_width, when positive, draws a bearer bar of that pixel thickness bordering the bars (as used by ITF-14); it must be folded into the quiet zones, with the label placed in the bottom quiet zone outside the frame.

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

bearer_width: int

Alias for field number 7

property width: int

Total canvas width in pixels.

property height: int

Total canvas height in pixels.

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

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).

iter_bearer_marks(layout: BarLayout) → Iterator[tuple[int, int, int, int]]

Yield the four rectangles of a full-frame bearer bar.

Nothing is yielded when layout.bearer_width is zero. The frame borders the bars only – the top and bottom rules abut the bars, and the label (in the bottom quiet zone) sits outside the frame. quiet_top holds the top rule, so the bearer thickness must be folded into the quiet zones.

iter_barcode_marks(layout: BarLayout) → Iterator[tuple[int, int, int, int]]

Yield every dark mark of a 1D barcode: its bars, then its bearer bar.

The single entry point the PNG, SVG and EPS paths render from, composing the raw iter_bar_marks() primitive with iter_bearer_marks().

User-friendly composition of GS1 Application Identifier payloads.

Pair GS1Fixed and GS1Variable instances with the matching gs1() classmethod on pystrich.code128.Code128Data or pystrich.datamatrix.DataMatrixData to emit a GS1-128 or GS1 Data Matrix payload without managing FNC1 separators by hand.

The library does not ship an Application Identifier registry: callers tell us whether each field is fixed- or variable-length by choosing the wrapper class. FNC1 separators are inserted after variable-length fields that are not the final element of the payload, and once at the very start of the message.

Added in version 0.15.

class GS1Fixed(application_identifier: str, value: str)

Bases: _GS1Field

A fixed-length GS1 Application Identifier field.

The reader knows the data length from the Application Identifier alone, so no FNC1 separator is needed after the field. Use for Application Identifiers such as (01) GTIN-14, (17) expiry date, or (11) production date.

Parameters:

• application_identifier – The 2-4 digit Application Identifier.

• value – The data string. Must be non-empty printable ASCII.

class GS1Variable(application_identifier: str, value: str)

Bases: _GS1Field

A variable-length GS1 Application Identifier field.

The reader cannot determine where the data ends from the Application Identifier alone, so an FNC1 separator follows unless this is the last field of the payload. Use for Application Identifiers such as (10) batch, (21) serial number, or (240) additional product identification.

Parameters:

• application_identifier – The 2-4 digit Application Identifier.

• value – The data string. Must be non-empty printable ASCII.