API reference¶

Encode data (unless it is already a QRMatrix) and render it.

dark / light customize ANSI mode's module colors (see cuere.render.render_matrix); they are only valid for mode="ansi".

Example:

from cuere import render

text = render("HELLO")                    # half-block QR as a str
colored = render("HELLO", mode="ansi")    # theme-proof SGR colors
wide = render("HELLO", mode="block", invert=True)

Render data and write it to out (default sys.stdout).

The fit check is width-only: wrapping destroys a code, but a code taller than the terminal merely scrolls and stays scannable, so height is not gated here (use fits for a height-aware predicate).

ANSI mode silently falls back to HALF when NO_COLOR is set or the stream is not a tty, unless force=True: raw SGR codes in logs or pipelines are worse than a theme-dependent code. dark / light customize ANSI mode's colors (only valid for mode="ansi"); when ANSI falls back, they are dropped with it so a no-color terminal gets plain glyphs.

Example:

from cuere import show

show("https://example.com")             # to sys.stdout
show("HELLO", mode="ansi", force=True)  # keep colors even when piped

Whether the rendered code fits the terminal in both dimensions.

Width is the hard constraint (wrapping destroys a scan); height is checked too because a code taller than the screen scrolls out of view. width and height default to the current terminal size.

Example:

from cuere import fits, show

if fits("https://example.com"):
    show("https://example.com")   # known to fit the current terminal

Render matrix as text; lines are equal-width, no trailing newline.

The quiet zone is rendered as part of the output (spaces / light modules) because a scanner needs it in the code's own background, not whatever the surrounding terminal happens to show.

dark / light customize the SGR colors of ANSI mode (dark modules and the light ground respectively); they default to the theme-proof black-on-white (palette 16 on 231). They are only valid for mode="ansi" — passing a color for half / block raises ColorError.

Example:

from cuere import QRMatrix, RenderMode, render_matrix

m = QRMatrix.encode("HELLO")
plain = render_matrix(m)  # default half-blocks
colored = render_matrix(m, mode=RenderMode.ANSI, dark="cyan")  # custom ANSI ink

Render matrix as a standalone SVG document, one module per unit.

Dark modules become a single <path> over a light background <rect>. viewBox is the module grid, so the path coordinates stay small integers; width/height scale it to scale pixels per module. shape-rendering="crispEdges" keeps module borders sharp (anti-aliasing blur hurts scanning). invert flips dark and light via matrix.inverted() — the same single code path the glyph renderers use.

Example:

from cuere import QRMatrix, render_svg

svg = render_svg(QRMatrix.encode("HELLO"), scale=8)
with open("hello.svg", "w", encoding="utf-8") as f:
    f.write(svg)

Terminal columns the rendered matrix occupies (ignoring SGR codes).

Example:

from cuere import QRMatrix, render_width, render_height

m = QRMatrix.encode("HELLO")
cols, rows = render_width(m), render_height(m)   # half-block footprint

Terminal rows the rendered matrix occupies.

Example:

from cuere import QRMatrix, RenderMode, render_height

rows = render_height(QRMatrix.encode("HELLO"), mode=RenderMode.BLOCK)

Encode data and render it to bytes in format.

mode selects the glyphs for the text format and is ignored by the image formats; scale is pixels-per-module for svg/png and is ignored by text. Encoding keywords (error/border/…) apply only when data is not already a QRMatrix.

Example:

from cuere import render_bytes

svg = render_bytes("HELLO", format="svg")   # UTF-8 bytes
png = render_bytes("HELLO", format="png")   # needs cuere[image]

Render data and write the bytes to dest.

dest is a filesystem path or an open binary stream. When format is omitted it is inferred from a path's suffix (.txt/.svg/.png); a stream needs an explicit format. Unknown formats and unguessable destinations raise UnknownFormatError.

Example:

from cuere import save

save("HELLO", "qr.png")              # format from the .png suffix
with open("qr.svg", "wb") as fh:
    save("HELLO", fh, format="svg")  # a stream needs an explicit format

Build a well-formed BIP-21 bitcoin: payment URI.

address is validated structurally (base58 or bech32/bech32m alphabet); amount is a BTC value (see _format_amount); label and message are free text and get percent-encoded. Parameters left as None are omitted; an explicit empty label/message is kept as an empty value. Invalid input raises WalletURIError.

The result is a plain str: pass it to optimize_uri (a bare address with no query shrinks to QR-alphanumeric) and then to render / show to draw the code.

Example:

from decimal import Decimal
from cuere import bitcoin_uri, optimize_uri, show

addr = "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"
uri = bitcoin_uri(addr, amount=Decimal("0.01"), label="Tip")
show(optimize_uri(uri))

Build a lightning: URI from a bech32 Lightning payload.

payload is a BOLT11 invoice (lnbc… / lntb… / …), an LNURL (lnurl1…), or a BOLT12 offer (lno1…) — any bech32 string whose human-readable part begins ln. It is validated structurally — a single-case run of ASCII alphanumerics beginning ln (the bech32 charset is a subset of that) — but its checksum is not verified, mirroring bitcoin_uri. An empty string, a mixed-case payload, or one carrying a : / @ / query character raises WalletURIError.

The result is a plain str. A lowercase payload composes with optimize_uri, which uppercases the URI to QR-alphanumeric mode for a smaller code (lightning: is SchemeCase.INSENSITIVE); pass the result to render / show to draw it.

Example:

from cuere import lightning_uri, optimize_uri, show

show(optimize_uri(lightning_uri("lnbc1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqf")))

Build an EIP-681 ethereum: native-payment URI.

address is the recipient, validated structurally as 0x + 40 hex digits with its case preserved (it carries the EIP-55 checksum when mixed-case). value is the amount in wei (1 ETH = 10**18 wei), a non-negative integer uint256; gas_price is likewise in wei and gas_limit is a gas-unit count. chain_id (EIP-155, e.g. 1 for mainnet) is emitted as @<chain_id>. Parameters left as None are omitted. Invalid input raises WalletURIError.

The result is a plain str to pass to render / show. Do not run it through optimize_uri: the EIP-55 checksum is case-significant, so uppercasing would corrupt the address (optimize_uri already refuses the ethereum: scheme for this reason).

Example:

from cuere import ethereum_uri, show

# 0.01 ETH = 10**16 wei, on Ethereum mainnet (chain_id=1)
show(ethereum_uri("0xfb6916095ca1df60bb79Ce92ce3ea74c37c5d359",
                  value=10**16, chain_id=1))

Build an EIP-681 ERC-20 transfer URI: ethereum:<token>/transfer?….

Encodes a call to the token's transfer(address,uint256) function. token is the ERC-20 contract address and to the recipient, both validated as 0x + 40 hex digits with case preserved. amount is a non-negative integer in the token's base units (its own decimals — which this library cannot know — so no scaling is applied); it is emitted as the uint256 argument. chain_id / gas_limit / gas_price behave as in ethereum_uri. Invalid input raises WalletURIError.

As with ethereum_uri, never pass the result to optimize_uri.

Example:

from cuere import erc20_transfer_uri, show

# transfer 1 USDC (6 decimals -> 1_000_000 base units) on mainnet
uri = erc20_transfer_uri(
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    to="0x8e23ee67d1332ad560396262c48ffbb01f93d052",
    amount=1_000_000,
    chain_id=1,
)
show(uri)

Uppercase a bech32-scheme URI when that provably shrinks its QR code.

Applied only when all of these hold: the scheme is case-insensitive (SchemeCase.INSENSITIVE — bitcoin: or lightning:), the URI is already entirely lowercase (so uppercasing cannot destroy significant case), and the uppercased form is fully QR-alphanumeric (so a query string or any other non-alphanumeric byte rules it out). Idempotent; returns the input unchanged in every other case — including case-significant (ethereum:, wc:) and unrecognized schemes.

Example:

from cuere import optimize_uri

optimize_uri("bitcoin:bc1q...")    # -> "BITCOIN:BC1Q..." (smaller QR)
optimize_uri("ethereum:0xAbC...")  # unchanged (case-significant)

Classify uri by how optimize_uri treats its scheme's case.

The scheme is the text before the first : (compared case-insensitively, per RFC 3986). A string with no : — hence no scheme — is SchemeCase.UNKNOWN. Only an SchemeCase.INSENSITIVE scheme is a candidate for optimization; see optimize_uri.

Example:

from cuere import scheme_case, SchemeCase

scheme_case("bitcoin:bc1q...") is SchemeCase.INSENSITIVE    # True
scheme_case("ethereum:0xAbC...") is SchemeCase.SIGNIFICANT  # True
scheme_case("mailto:a@b.com") is SchemeCase.UNKNOWN         # True

Whether data is non-empty and encodable in QR alphanumeric mode.

Example:

from cuere import is_qr_alphanumeric

is_qr_alphanumeric("BITCOIN:BC1Q...")   # True  — fits the compact mode
is_qr_alphanumeric("bitcoin:bc1q...")   # False — lowercase is byte mode