MareArts Computer Vision Study.

A | B means either: reading union type hints in Python

2026-08-24T06:02:11.039-07:00

Python · Type hints

def sensor_id(sensor: Sensor | int | None) -> int has three bars in one signature and looks like bit arithmetic. It is not arithmetic and it is not new syntax to memorise: each bar is the word or, and the whole annotation is one sentence — "a Sensor, or an int, or nothing".

Unions pile up in exactly one situation: a function that is polite about what callers hand it. A station can be identified by name or by number, a reading may be missing, an option may be left unset. Each politeness adds a member to the union, and the annotation grows to match. Reading one is a two-minute skill; the interesting part is what the notation does not promise, and that is where most of this post goes.

Everything below runs on CPython 3.10, and every output block is copied from a real run.

One bar, two types — the whole of the notation
The | None case — what used to be Optional
Nobody checks it at runtime — annotations are documentation
Narrowing a three-way union — the funnel pattern
The bar builds a real object — types.UnionType, and isinstance
Where you put the bar changes the meaning — list[int] | None vs list[int | None]
Older Python — from __future__ import annotations
Traps
Cheat sheet

1 · One bar, two types

The whole of the notation

A | B in an annotation means a value of type A, or a value of type B. That is the entire feature. It reads left to right, the order carries no meaning, and it chains: A | B | C is "any one of the three".

brightness.py

def brightness(level: int | float) -> str:
    return f"{level:.1f} lux"

print(brightness(3))
print(brightness(3.5))

$ python brightness.py

3.0 lux
3.5 lux

This spelling arrived in Python 3.10 (PEP 604). Before it, the same thing was written with a helper imported from typing, and you will still meet that spelling in any code that supports older interpreters:

Modern	Pre-3.10 equivalent
`int \| float`	`Union[int, float]`
`int \| None`	`Optional[int]`
`str \| int \| None`	`Optional[Union[str, int]]`
`dict[str, float] \| None`	`Optional[Dict[str, float]]`

They are not merely similar, they compare equal — the bar is a different way to spell the same object:

equivalence.py

from typing import Optional, Union

print(int | None == Optional[int])
print(int | str == Union[int, str])
print(str | None == None | str)      # order is not part of the meaning

$ python equivalence.py

True
True
True

Which explains why nobody writes the old form in new code, and why a linter will rewrite it for you. Ruff's UP rules do it as a fix:

old_style.py

from typing import Optional, Union


def humidity(sensor: Optional[int]) -> Union[float, str]:
    if sensor is None:
        return "no sensor"
    return 41.5

$ ruff check --select UP --target-version py310 --diff old_style.py

--- old_style.py
+++ old_style.py
@@ -1,7 +1,7 @@
 from typing import Optional, Union


-def humidity(sensor: Optional[int]) -> Union[float, str]:
+def humidity(sensor: int | None) -> float | str:
     if sensor is None:
         return "no sensor"
     return 41.5

Would fix 2 errors.

UP045 is the Optional one, UP007 the Union one. Both are auto-fixable, so a whole codebase converts in one command once every supported interpreter is 3.10 or newer.

2 · The `| None` case

"or nothing" is the common member

By far the most frequent union is X | None, because "this may be absent" is the most frequent extra case in any real signature. None here is standing in for its type, NoneType, which is why it can appear in a union at all:

nonetype.py

print(type(None))
print(int | None == int | type(None))

$ python nonetype.py

<class 'NoneType'>
True

Convention

Put None last. int | None and None | int are the same type, but the reader parses "an int, possibly absent" faster than "absent, or an int", and every style guide and auto-fixer produces the former.

A parameter with a None default should say so in the annotation. The default does not add the member for you:

wrong

def scale(factor: float = None):
    # claims float, accepts None
    ...

right

def scale(factor: float | None = None):
    # the annotation matches the default
    ...

The wrong version runs perfectly. It is a documentation bug: the annotation says the argument is always a float while the default proves otherwise, so a reader who trusts it will skip the None branch they needed to write. A type checker flags it; the interpreter never will.

3 · Nobody checks it at runtime

Annotations are documentation with syntax

This is the single most important fact about the notation, and the one that surprises people coming from a compiled language. Writing int | str does not make the interpreter reject a list. Nothing is validated on the way in, and nothing is validated on the way out.

unchecked.py

def label(value: int | str) -> str:
    return value.upper()

print(label("dry"))
print(label(7))

$ python unchecked.py

DRY
AttributeError: 'int' object has no attribute 'upper'

The annotation was honest — 7 really is an allowed argument — and the body was not. It called a string method on a value the signature promised might be an integer. The union is a claim about the caller; honouring it inside the body is the author's job, and that job is called narrowing.

Consequence

Every union member you add is a branch you owe the body. A three-member union with one code path through it is a bug waiting for the second-most-common input.

4 · Narrowing a three-way union

The funnel pattern

When a signature accepts several shapes, the usual body converts them to one shape as early as possible and then gets on with the actual work. The union is wide at the top of the function and narrow everywhere after.

  sensor: Sensor  |  int  |  None     three shapes in, one int out
            │         │       │
            │         │       │       isinstance(sensor, Sensor)
            ▼         │       │
       sensor.index   │       │
       (int | None)   │       │
            │         │       │
            └────┬────┘       │
                 │            │
                 ▼            ▼
                int          None     Sensor(None) lands here too
                 │            │
                 ▼            ▼
           return sensor   return 0

narrow.py

class Sensor:
    def __init__(self, index: int | None) -> None:
        self.index = index


def sensor_id(sensor: Sensor | int | None) -> int:
    if isinstance(sensor, Sensor):
        sensor = sensor.index      # Sensor | int | None  ->  int | None
    if sensor is None:
        return 0                   # int | None  ->  int
    return sensor


print(sensor_id(Sensor(4)))
print(sensor_id(9))
print(sensor_id(None))
print(sensor_id(Sensor(None)))

$ python narrow.py

Two lines removed two members. The first if replaces a Sensor with the integer inside it, so after that line the variable is int | None even though the parameter was declared wider. The second turns the remaining None into a value, so the return sensor at the bottom is an int and matches the return annotation. A type checker follows this reasoning statically and will complain if a branch is missing.

Read the fourth line of output

sensor_id(Sensor(None)) returns 0, the same as passing nothing at all. That is not a bug here, but it is a decision, and it is the kind of decision a wide union hides: an object whose interior field is empty collapses onto the same branch as a missing object. If those two cases should behave differently, the union has to be narrowed in a different order.

Ordering the checks is not narrowing by itself

isinstance and is None narrow. Falling off the end of a chain of ifs also narrows, by elimination, and is idiomatic — but only if the members really are exhausted:

elimination.py

def to_text(value: int | str) -> str:
    if isinstance(value, int):
        return f"#{value}"
    return value.strip()          # nothing left but str

print(to_text(7), to_text("  wet  ") + "|")

$ python elimination.py

#7 wet|

5 · The bar builds a real object

Not a special form the parser swallows

int | None is an ordinary expression evaluated at runtime. It produces an instance of types.UnionType, it has a readable repr, and it can be stored in a variable like any other value:

runtime_object.py

print(type(int | None))
print(int | None)

Celsius = float | int                    # a reusable alias
Reading = dict[str, float] | None
print(Celsius)
print(Reading)

$ python runtime_object.py

<class 'types.UnionType'>
int | None
float | int
dict[str, float] | None

Because it is a real object, duplicates collapse and nesting flattens, which is why you never see a union of unions:

flatten.py

print(int | str | int)
print((int | str) | float)
print(int | None | None)

$ python flatten.py

int | str
int | str | float
int | None

It works in `isinstance`

A genuine convenience of the new spelling: the resulting object is accepted as the second argument to isinstance and issubclass, which Union[...] never was. It behaves like the tuple form.

isinstance_union.py

print(isinstance(3, int | float))
print(isinstance("x", int | float))
print(isinstance([1], list | None))
print(isinstance([1], list[int] | None))    # parameterized -> rejected

$ python isinstance_union.py

True
False
True
TypeError: isinstance() argument 2 cannot contain a parameterized generic

The last line is the general rule about runtime checks, not a union quirk: nothing can test list[int] at runtime, because that would mean walking the list. Check list and trust the annotation for the element type.

Types only

The bar between two instances is still plain __or__, and most objects do not implement it. 3 | None raises TypeError: unsupported operand type(s) for |: 'int' and 'NoneType'. Unions are built from types, and a value that happens to be a type — a variable holding int — works exactly as well as the literal.

6 · Where you put the bar changes the meaning

Outside or inside the brackets

Two annotations one character apart in appearance, and entirely different in what they permit:

Annotation	Reads as	Accepts	Rejects
`list[int] \| None`	a list of ints, or no list at all	`[1, 2]`, `[]`, `None`	`[1, None]`
`list[int \| None]`	always a list, whose items may be missing	`[1, None]`, `[]`	`None`

The structure is visible at runtime — the outer construct is different in each case:

nesting.py

from typing import get_args, get_origin

print(get_origin(list[int] | None), get_args(list[int] | None))
print(get_origin(list[int | None]), get_args(list[int | None]))

$ python nesting.py

<class 'types.UnionType'> (list[int], <class 'NoneType'>)
<class 'list'> (int | None,)

For the first, the outermost thing is the union and the list is a member. For the second, the outermost thing is a list and the union is its element type. When a signature needs both — an optional list of optional readings — say so: list[float | None] | None. It is a mouthful, and that is a fair warning about the interface.

7 · Older Python

The `from future` escape

On 3.7 through 3.9 the bar between two types raises TypeError when evaluated. Since annotations are evaluated at function-definition time by default, that makes def f(x: int | None) a runtime error on those versions — not a warning, a crash on import.

from __future__ import annotations, at the top of the module, stops annotations from being evaluated at all. They are stored as strings and only ever inspected by tools:

future_import.py

from __future__ import annotations


def calibrate(offset: int | None) -> float | None:
    return None if offset is None else offset * 0.5


print(calibrate.__annotations__)
print(calibrate(4), calibrate(None))

$ python future_import.py

{'offset': 'int | None', 'return': 'float | None'}
2.0 None

The values are strings, quotes included. Nothing ever evaluated int | None, so the syntax is free on any version that has the future import.

Only annotations

The future import covers annotation positions and nothing else. An alias assignment (Celsius = float | int), a call to isinstance(x, int | None), or anything that resolves annotations at runtime — typing.get_type_hints, and the validation libraries built on it — still evaluates the expression and still fails below 3.10. Those places need Union and Optional until the floor moves.

8 · Traps

Four that survive the nicer syntax

A wide union is a cost, not a courtesy

str | int | Path | None is four branches for every caller and for the body. If one of the members is only there because a single caller was lazy, converting at that call site is usually cheaper than teaching every reader of the signature about a case that occurs once.

`or` is not the same as `is None`

The narrowing shortcut value or default collapses every falsy value, not just None, and an empty string is a legitimate member of str | None:

falsy.py

def site_name(name: str | None) -> str:
    return name or "unnamed"

def site_name_strict(name: str | None) -> str:
    return "unnamed" if name is None else name

print(repr(site_name("")), repr(site_name_strict("")))

$ python falsy.py

'unnamed' ''

The first discarded a caller's deliberate empty name. Same for 0 in int | None and [] in list[str] | None — the values most likely to matter are the falsy ones.

The return type is a union too

-> float | None is a promise that every caller must unwrap. It is the right annotation when absence is a real outcome, and the wrong one when the function could simply raise; returning None for failure pushes a branch onto everybody downstream, and the ones who forget it get an AttributeError far from the cause.

Mixing the spellings in one file

Optional[int] on one line and str | None on the next both work, and both mean what they say, but the reader now has to hold two vocabularies. Pick the modern one and let the auto-fixer convert the rest.

Wrapping up

Cheat sheet

You want	Write
Either of two types	`int \| str`
May be absent	`int \| None`, with `None` last
Absent by default	`def f(x: int \| None = None)` — annotation and default agree
A list, or nothing	`list[int] \| None`
A list with gaps in it	`list[int \| None]`
A name for a recurring union	`SensorRef = Sensor \| int \| None`
A runtime check against a union	`isinstance(x, int \| float)` — unparameterized members only
The syntax on 3.7–3.9	`from __future__ import annotations`, annotation positions only
To convert an old codebase	`ruff check --select UP007,UP045 --fix`

The short list

A | B is the word "or". Order carries no meaning, chaining is just more members, and X | None is what Optional[X] used to spell.
Nothing is enforced at runtime. The union constrains callers; the body still has to handle every member, and forgetting one fails later with an ordinary attribute error.
Narrow early. One isinstance and one is None at the top turn a three-member parameter into a single concrete type for the rest of the function.
It is a real object. types.UnionType, printable, assignable to an alias, and usable in isinstance — unlike the typing spelling.
Bracket placement is semantic. list[int] | None and list[int | None] accept disjoint sets of values.
Every member is a branch someone maintains. Three is usually a helpful interface; six is usually a missing conversion at one call site.

MareArts ANPR App: On-Device Plates, MMC Vehicle Info, Team Sync, Web and Desktop Viewers

2026-08-23T11:46:57.580-07:00

MareArts ANPR is a license-plate recognition app for iOS and Android, with a web viewer and a desktop viewer on the same account. Plates are read on the phone. Cloud MMC (make, model, colour, type, side, nation), team sync, rules, maps, and stats sit on marearts.com.

Get a license Open the web viewer

Scan (on-device and cloud)
MMC vehicle info
Detections, map, stats
Whitelist and blacklist
Team project
Web viewer
Desktop viewer
Webhook, regions, SDK

Scan — live box, crop, confidence

Detections — mosaicked plates plus MMC

Scan: on-device ANPR and cloud

Hold the phone at the lane. The app finds the plate, reads the characters, and stores time plus GPS. No extra camera box and no PC at the gate.

Single — one capture.
Continuous — keep scanning; a duplicate window (default 5 seconds) skips the same plate.
Cloud — send the frame for OCR plus MMC vehicle info in one step.

On-device mode keeps detection and OCR on the phone after the models are installed. Cloud mode is optional when you want vehicle identity with the plate.

Camera: 1080p, 720p recommended, or 480p. Preview 60 or 30 fps. Lower resolution is faster and uses less storage. Zoom 1× / 2×, flash, front or rear camera. Landscape scanning keeps boxes and controls upright.

Trial is 10 scans per day without login. A license on the product page removes that cap.

Detail — mosaicked plate, make, model, colour

Stats — daily activity, unique vehicles

MMC vehicle info (make, model, colour)

MMC here means MareArts cloud vehicle identity, not a third-party brand. For each detection the API can return:

Make and model (with confidence)
Colour (with a colour chip)
Type (car, SUV, van, …)
Side — front or rear
Nation — country of the plate

The phone list shows a short line such as “Volvo XC60 · black”. The detail card shows all six fields. Cloud scan writes MMC immediately; on-device scans pick it up on sync. The web viewer filters the same fields (make, model, colour, type).

MMC uses the MareArts cloud API and is included with the subscription. Daily vehicle-info usage is shown in Settings.

List — Volvo XC60 · black, and the rest

Card — make, model, colour, type, side, nation

Detections, map, and stats

List — grouped by day; All / Latest; swipe to set whitelist, blacklist, or unknown.
Detail — full frame, plate crop, confidence, first/last seen, GPS, history of that plate.
Map — pins and clusters, satellite or road, optional plate labels, search.
Stats — today / week / month / year / custom range; unique vehicles; filter by rule status.
CSV export — plate, time, GPS, confidences, rule note, plus MMC columns.

Map — clusters, plate labels, GPS

Whitelist and blacklist

Rules mark a plate as allowed (green) or blocked (red) on the next scan, with sound and vibration. Notes can sit on the detection card.

Search, letter groups, swipe to delete, CSV import and export.
Upload a large CSV on marearts.com, then pull the package on the phone (replace or merge).

Team project

One team leader creates a team and shares a password. Members join and contribute detections and rules. Cloud sync is two-way. Auto-sync can run when the app goes to the background.

Leader sees every member’s data on the web viewer and can switch member in the dashboard.
Desktop viewer for a leader can pull the same team detections.
Leave or break team returns a user to solo mode.

Typical use: several guards at a gate, one supervisor on the web viewer without standing at the lane.

Web viewer

After login, My ANPR Data is the browser console for the same account: detections, MMC filters, rule packages, team member switch, export. The phone captures; the browser reviews.

Web viewer — detections with MMC columns

Web viewer — filter by make, model, colour, type

Desktop viewer

MareArts ANPR Desktop is a free companion for Windows, macOS, and Linux. Same login. It is a read-only viewer: it downloads cloud data and does not edit or delete it. Capture and rule changes stay on the phone.

Detections with MMC and location
Map with clustering
Rules (view)
Statistics
Local image drop — run a still through the MareArts ANPR cloud API
One-click sync, optional auto-sync
Team leader: all members’ detections, same as the web viewer

Desktop viewer — detections and MMC on a large screen

Webhook, plate regions, SDK

Webhook — JSON to Discord, Slack, Zapier, Make, or your own URL (plate, time, GPS, confidences, bbox, rule, optional image).
Plate region — Universal, Europe+, Korea, North America, China.
Thresholds — detection and OCR 60–95% (90% recommended); max plates per frame 1–10.
Python ANPR SDK and Road Objects SDK — same license family; offline after activation. See the license page.

How to start

Install MareArts ANPR (search “marearts anpr” on the App Store or Google Play).
Open Scan and use the daily trial.
Subscribe on www.marearts.com/products/anpr. The serial key is emailed to the PayPal address and also appears after login.
Sign in under Settings. Sync fills the web viewer and the desktop viewer.

Serial keys are bound to the PayPal email and cannot be moved. Plans and SDK options stay on the product page.

Subscribe on marearts.com Download Desktop Viewer

API and ABI, and the line between them

2026-08-23T03:31:17.532-07:00

C · Python · Linking

Two acronyms one letter apart, describing promises made at two different moments. An API is what you agree to when you write the call. An ABI is what your compiled bytes agree to when they meet somebody else's compiled bytes — and unlike the API, breaking it usually produces no error at all.

The clearest way in is to put them side by side. Only the middle word differs: Programming or Binary.

Acronym	Level	A promise that sounds like
API Application Programming Interface	source code	"there is a function `resize(img, width, height)` and it returns an `int`"
ABI Application Binary Interface	machine code and memory	"`width` is at byte 0 and is 4 bytes; the first argument arrives in register `rdi`"

An API is a contract between a programmer and a library. An ABI is a contract between two piles of already-compiled machine code. That is why two languages can call each other at all: Python has no idea what a C header looks like, but if it lays the bytes out the way the ABI says and puts the arguments where the ABI says, the call works.

This post is in five parts. First the distinction and what an ABI actually specifies. Then the three pieces you can see and measure — struct layout, symbol names, argument registers — each with a program you can run. Then the same boundary crossed from Python, including two mistakes that produce wrong answers in total silence. Finally, what it takes to keep an ABI stable once other people depend on it.

Everything was compiled and run before publishing: gcc 11.4.0 on x86-64 Linux, CPython 3.10.12, GNU binutils 2.38. Every output block is copied from a real run.

Two contracts — the distinction, and why it costs you a rebuild
Struct layout — the part you can print out
Symbols and registers — what the linker sees, and where arguments go
Crossing from Python — where a mismatch stops being theoretical
Keeping an ABI — what breaks what, and how libraries survive it
Reference — tools, cheat sheet, and a one-screen summary

Part 1 · Two contracts

What each one promises

Take an ordinary header. It declares a struct and a function:

the API, as written

struct config {
    int    width;
    int    height;
    double scale;
};

int config_area(const struct config *c);

Everything visible there is API: the names, the types, the order of the parameters, the fact that the function takes a pointer rather than a value. If any of it changes, code that calls it stops compiling — loudly, with a file and a line number.

The ABI is everything the compiler decided underneath that text, and none of it appears in the header: that width begins at byte 0, that scale begins at byte 8 and not byte 12, that the whole struct occupies 16 bytes, that the pointer argument arrives in the register rdi, that the int comes back in eax, and that the symbol is spelled config_area rather than _Z11config_areaPK6config.

Those decisions are just as much a contract, and both sides are bound by them. The difference is what happens when one side changes its mind.

Recompile, relink, neither

The practical consequence of the distinction is what a change costs the people who use your library.

Change	API	ABI	What users must do
Fix a bug inside a function body	intact	intact	Nothing. Drop in the new `.so`.
Add a brand-new function	intact	intact	Nothing, unless they want the new one.
Rename a function	broken	broken	Edit their source, rebuild. The compiler tells them.
Reorder two struct fields	intact	broken	Rebuild — and nothing tells them.
Change a field from `int` to `long`	mostly intact	broken	Rebuild. Again, silently.

The last two rows are the whole reason this topic matters. A broken API is a compiler error; a broken ABI is a program that runs and gives you the wrong number. The rest of this post is mostly about making that second row concrete enough that you can spot it.

What an ABI decides

For a plain C interface on one machine, the list is short and worth memorising:

Struct layout — which byte each field starts at, and how big the whole thing is. Part 2.
Symbol naming — what the function is called in the object file. Part 3.
The calling convention — which register or stack slot each argument travels in, and who cleans up. Part 3.
Return values — which register the result comes back in, which depends on its type.

Sizes and alignments of the basic types sit underneath all four. C only guarantees relationships — that a long is at least as wide as an int — and the ABI picks the actual numbers, which is why long is 8 bytes on Linux and 4 bytes on 64-bit Windows.

Naming

The convention used throughout this post is the x86-64 System V ABI, which is what Linux and macOS use. Windows has a different one, as do 32-bit x86 and the various ARM targets. The concepts transfer exactly; the specific registers do not.

Part 2 · Struct layout

Where the fields actually land

You do not have to guess at any of this. offsetof and sizeof report what the compiler decided, and _Alignof reports the rule it was following.

layout.c — same fields, two orders

struct badly_ordered {
    char   tag;
    double value;
    int    id;
};

struct well_ordered {
    double value;
    int    id;
    char   tag;
};

#define SHOW(S, M)                                                       \
    printf("  %-6s offset %2zu   size %2zu   align %2zu\n", #M,          \
           offsetof(S, M), sizeof(((S *)0)->M), _Alignof(((S *)0)->M))

./layout

struct badly_ordered   sizeof = 24   align 8
  tag    offset  0   size  1   align  1
  value  offset  8   size  8   align  8
  id     offset 16   size  4   align  4

struct well_ordered    sizeof = 16   align 8
  value  offset  0   size  8   align  8
  id     offset  8   size  4   align  4
  tag    offset 12   size  1   align  1

field bytes actually used: 13
padding in badly_ordered : 11
padding in well_ordered  : 3

Alignment and padding

Two rules produce every number in that output.

Each field starts at a multiple of its own alignment. A double has alignment 8, so it may only begin at byte 0, 8, 16 and so on. In badly_ordered, tag occupies byte 0, and value cannot start at byte 1 — the compiler skips to byte 8 and leaves seven bytes of nothing behind.

The struct's own size is rounded up to its largest field alignment. That is what makes arrays work: if sizeof were not a multiple of 8, the second element of an array would put value on a misaligned address. In badly_ordered, id ends at byte 20 and the size rounds up to 24.

The two structs contain identical data — a double, an int and a char, 13 bytes of payload — and one is 50% larger than the other. Sorting fields from widest to narrowest, as well_ordered does, is a reliable way to get most of that back.

Note

Padding bytes have no defined value. This is why memcmp on two structs can report a difference when every field is equal, and why writing a struct straight to a file can leak whatever happened to be on the stack.

Reordering is an ABI change with no API change

Now put the two structs next to each other again and ask what a caller sees. Both have the same three fields with the same names and the same types. Any code that says c.value = 1.5 compiles unchanged against either one. The API is identical.

The bytes are not. Field value lives at offset 8 in one and offset 0 in the other. A library compiled against the first and a caller compiled against the second will agree on every name and disagree on every address — and no tool in the build will say a word, because each half is internally consistent.

Trap

sizeof matching is not evidence that two layouts agree. Two different orderings can easily produce the same total size — you will see exactly that in part 4, where a reordered struct is 16 bytes on both sides and still reads the wrong bytes.

Part 3 · Symbols and registers

Name mangling

A linker does not match calls to functions by reading your source. It matches strings. What string a function gets is part of the ABI, and C and C++ answer that question very differently.

mangling.cpp

int add(int a, int b) { return a + b; }

double add(double a, double b) { return a + b; }

namespace geometry {
int add(int a, int b) { return a + b; }
}  // namespace geometry

extern "C" int add_c(int a, int b) { return a + b; }

g++ -c mangling.cpp -o mangling.o && nm mangling.o

0000000000000018 T _Z3adddd
0000000000000000 T _Z3addii
0000000000000040 T _ZN8geometry3addEii
0000000000000058 T add_c

Three functions are all called add in the source and none of them is called add in the object file. C++ encodes the namespace and the parameter types into the symbol — that encoding is what makes overloading possible, since the linker needs a different string for each version. _Z3addii is add taking two ints; _Z3adddd is the double one.

nm -C undoes it, as does piping any symbol through c++filt:

nm -C mangling.o

0000000000000018 T add(double, double)
0000000000000000 T add(int, int)
0000000000000040 T geometry::add(int, int)
0000000000000058 T add_c

What `extern "C"` is for

The fourth symbol is the odd one out: add_c, spelled exactly as written. That is the entire effect of extern "C" — it tells a C++ compiler to use the C naming rule (the plain name) and the C calling rule for this function, so that anything outside C++ can find it.

It is not a performance hint and it does not change the function body. It is a promise about the string in the symbol table, which is why every library meant to be called from another language has a wall of it around its public header. And it is why C++ features that need mangling — overloads, templates, namespaces — cannot appear on such a boundary: there is only one add_c available, so there can only be one function of that name.

Look at the exported symbols of a C library and you get the flat list you would expect:

nm -D --defined-only libconfig.so

0000000000001119 T config_area
0000000000001174 T config_describe
00000000000011de T config_offset_scale
0000000000001137 T config_scaled_area
00000000000011cf T config_sizeof

That list, plus the layout of struct config, is the library's entire ABI surface. The T means the symbol is defined here and visible to others; U would mean undefined and needed from somewhere else.

The calling convention

The last piece is where arguments physically go. Three tiny functions and a disassembler answer it directly.

callconv.c

int sum4(int a, int b, int c, int d) { return a + b + c + d; }

double product2(double x, double y) { return x * y; }

int mixed(int a, double x, int b) { return a + b + (int)x; }

gcc -O1 -c callconv.c && objdump -d --no-show-raw-insn callconv.o

0000000000000000 <sum4>:
   0:	endbr64
   4:	add    %esi,%edi
   6:	add    %edx,%edi
   8:	lea    (%rdi,%rcx,1),%eax
   b:	ret

000000000000000c <product2>:
   c:	endbr64
  10:	mulsd  %xmm1,%xmm0
  14:	ret

0000000000000015 <mixed>:
  15:	endbr64
  19:	add    %esi,%edi
  1b:	cvttsd2si %xmm0,%eax
  1f:	add    %edi,%eax
  21:	ret

There is no prologue, no stack, no memory traffic at all. In sum4 the four arguments are already sitting in edi, esi, edx and ecx when the function begins, and the result is left in eax. That order is not something gcc invented; it is written down in the ABI, and every compiler targeting this platform obeys it.

Kind	Arguments 1–6	Beyond that	Return
Integers and pointers	`rdi rsi rdx rcx r8 r9`	pushed on the stack	`rax`
Floats and doubles	`xmm0` … `xmm7`	pushed on the stack	`xmm0`

product2 confirms the second row: mulsd %xmm1,%xmm0 multiplies the two arguments in place and the result is already in the return register.

The detail that surprises people

Look again at mixed(int a, double x, int b). The instruction is add %esi,%edi — so a is in edi and b is in esi, even though b is the third parameter.

The two register sequences are counted independently. Integers take rdi, rsi, … in order among themselves; floats take xmm0, xmm1, … in order among themselves. The double in the middle consumes xmm0 and does not consume an integer slot, so b gets the next integer register rather than the third one.

Why you care

Because it means you cannot work out where an argument goes by counting parameters. Any hand-written declaration that gets a parameter's type wrong — say, declaring a double parameter as int in an FFI binding — does not merely mistranslate that one value. It shifts every argument after it into the wrong register.

Part 4 · Crossing over from Python

The library

Everything so far has been observation. This part is where a mismatch actually costs you, and the most convenient way to build one is a C library and a Python client, because Python has no access to the header and has to be told the layout by hand.

libconfig.c

struct config {
    int    width;
    int    height;
    double scale;
};

int config_area(const struct config *c) {
    return c->width * c->height;
}

const char *config_describe(const struct config *c) {
    static char buf[64];
    snprintf(buf, sizeof buf, "%dx%d @ %.2fx", c->width, c->height, c->scale);
    return buf;
}

/* Self-description, so a caller can verify its mirror instead of trusting it. */
size_t config_sizeof(void) { return sizeof(struct config); }
size_t config_offset_scale(void) { return offsetof(struct config, scale); }

Those last two functions are worth a moment. They export nothing useful to a program — but they let a caller check its assumptions instead of hoping. A library that describes its own layout turns a silent class of bug into an assertion, for the price of two lines.

A mirror that matches

On the Python side, ctypes needs the layout restated. This declaration is a hand-copy of the C struct, and the whole exercise depends on it being right.

client.py

class Config(ctypes.Structure):
    _fields_ = [
        ("width", ctypes.c_int),
        ("height", ctypes.c_int),
        ("scale", ctypes.c_double),
    ]

lib.config_area.argtypes = [ctypes.POINTER(Config)]
lib.config_area.restype = ctypes.c_int

assert ctypes.sizeof(Config) == lib.config_sizeof()
assert Config.scale.offset == lib.config_offset_scale()

python3 client.py — part 1

== 1. matching mirror ==
sizeof        : python 16 | c 16
offset(scale) : python 8 | c 8
area          : 2073600
describe      : 1920x1080 @ 1.50x

Python computed offset 8 for scale by applying the same alignment rules the C compiler applied, independently, from the field types alone. That is not a coincidence — ctypes implements the platform ABI. It is also the reason the next section works the way it does.

A mirror that doesn't

Now the realistic accident: somebody writes the same three fields in a different order. Perhaps they copied from documentation that listed them alphabetically. Every name is right, every type is right.

client.py — the same fields, reordered

class ConfigWrong(ctypes.Structure):
    _fields_ = [
        ("scale", ctypes.c_double),
        ("width", ctypes.c_int),
        ("height", ctypes.c_int),
    ]

python3 client.py — part 2

== 2. reordered mirror ==
sizeof        : python 16 | c 16 -> agrees, and proves nothing
offset(scale) : python 0 | c 8 -> the actual disagreement
area          : 0
describe      : 0x1073217536 @ 0.00x
no exception, no warning, no crash

A 1920×1080 image now has an area of zero, and a height of 1073217536. Those numbers are not random: C read width from bytes 0–3, which in this layout hold the bottom half of the double 1.5, and that half is all zeros. It read height from bytes 4–7, the top half of the same double, which is 0x3FF80000 — the number printed.

Three things about that output deserve to be uncomfortable. There is no exception. There is no warning. And sizeof agrees perfectly on both sides, because reordering these particular fields happens to produce the same total. A size check would have passed this straight through; only the offset check catches it.

Trap

ctypes type-checks the Python side thoroughly and the C side not at all. It will refuse a ConfigWrong where you declared POINTER(Config) — but it has no way to know what the library thinks either of them looks like. Every guarantee stops at the boundary.

The `restype` trap

The other everyday mistake is forgetting to declare what comes back. ctypes assumes a C int unless told otherwise, and part 3 of the calling convention says an int comes back in rax while a double comes back in xmm0. Two different registers.

python3 client.py — part 3

== 3. missing restype ==
default (int) : 0
c_double      : 3110400.0
expected      : 3110400.0

The first call reads an integer register that the function never wrote to. It printed 0 here and it will print whatever is left over there on your machine; the point is only that it has nothing to do with the answer.

The same failure with a pointer return is worse. Left as the default int, a returned pointer is truncated to its low 32 bits, and dereferencing the result is a segmentation fault that appears to come from inside the C library. Setting argtypes and restype on every function you import is not ceremony — it is the only place the ABI gets written down on the Python side.

What the Python examples actually demonstrate

An FFI binding is a hand-copy of an ABI. Nothing checks it against the library, so it drifts the moment the library changes.
A matching sizeof proves very little. Compare offsets, field by field, or compare nothing.
Have the library describe itself. Two exported functions turned an invisible failure into an assert that fires on line one.

Part 5 · Keeping an ABI stable

What breaks which

Once other people ship binaries built against your library, every change falls into one of these boxes. The dangerous column is the one where the API survives and the ABI does not, because that is the change nobody notices.

Change to a public struct or function	API	ABI
Add a function	ok	ok
Change a function body	ok	ok
Rename a parameter in the header	ok	ok
Reorder struct fields	ok	broken
Insert a field in the middle	ok	broken
Widen a field, `int` → `long`	ok	broken
Add a field at the end	ok	broken if callers allocate it
Change a parameter's type	broken	broken
Remove or rename a function	broken	broken
Change a `#define` constant	behaviour changes	ok

"Add a field at the end" is the interesting one. If callers only ever receive a pointer your library allocated, growing the struct is harmless — they never compute its size. If callers declare one on their own stack, they will allocate the old, smaller size, and your library will write past the end of it.

How libraries stay compatible

Hide the struct entirely

The strongest option: callers never see the fields, only a pointer to something they cannot inspect.

opaque handle

/* in the public header */
typedef struct config config_t;        /* declared, never defined */

config_t *config_create(void);
void      config_set_scale(config_t *c, double scale);
int       config_area(const config_t *c);
void      config_destroy(config_t *c);

The layout is now a private implementation detail — it can change in any release, because no caller ever computed an offset into it. The cost is a function call per field and an allocator round trip. This is how most C libraries with long support windows do it.

Put the size in the struct

When callers must allocate, have them declare how big their version is, and check.

versioned struct

struct config {
    size_t struct_size;    /* caller sets this to sizeof(struct config) */
    int    width;
    int    height;
    double scale;
    /* new fields may only be appended below */
};

int config_area(const struct config *c) {
    if (c->struct_size < offsetof(struct config, scale)) return -1;
    ...
}

The library can now tell an old caller from a new one at runtime and read only the fields that caller actually has. The rule is absolute, though: fields may only ever be appended, and existing ones may never move or change width.

Reserve space up front

A cruder version of the same idea — char reserved[32]; at the end of the struct, spent later on new fields without changing the size. It works, it is ugly, and it is everywhere.

Version the symbol, not the struct

When a function genuinely has to change shape, keep the old one and add a new name: config_area stays, config_area2 appears. Old binaries keep finding the old symbol. The C standard library has done this for decades, which is why symbols with version suffixes turn up in nm output on any mature library.

soname, and how the loader picks a file

Shared libraries carry a name inside them, and it is that name — not the filename — that gets recorded in every program linked against them.

building with a soname

gcc -shared -fPIC -Wl,-soname,libconfig.so.1 -o libconfig.so.1.0.0 libconfig.c
readelf -d libconfig.so.1.0.0 | head -6

readelf -d libconfig.so.1.0.0

Dynamic section at offset 0x2e10 contains 25 entries:
  Tag        Type                         Name/Value
 0x0000000000000001 (NEEDED)             Shared library: [libc.so.6]
 0x000000000000000e (SONAME)             Library soname: [libconfig.so.1]
 0x000000000000000c (INIT)               0x1000

The convention that falls out of this is the familiar three-level filename. The file is libconfig.so.1.0.0; the soname is libconfig.so.1, and that is what programs record; the bare libconfig.so is a symlink that only the linker uses at build time.

The middle number is the promise. Bump the patch level for a bug fix, bump the minor for added functions, and bump the soname to .so.2 when the ABI breaks. Because the soname is part of the filename, version 1 and version 2 can sit in the same directory and old programs keep loading the one they were built against. That is the whole mechanism by which a Linux system runs binaries compiled years apart.

Part 6 · Reference

Tools worth knowing

`nm -D --defined-only lib.so`	Exported symbols — the callable ABI surface
`nm -C`, `c++filt`	Demangle C++ symbol names
`readelf -d lib.so`	soname and the list of libraries it needs
`readelf -Ws lib.so`	Full symbol table with sizes and visibility
`objdump -d --no-show-raw-insn f.o`	Disassembly — see the calling convention directly
`ldd ./program`	Which libraries actually get loaded, and from where
`gcc -fdump-lang-raw`, `pahole`	Struct layout and padding, reported by the toolchain
`offsetof`, `_Alignof`, `_Static_assert`	Assert the layout from inside the program itself

Cheat sheet

The distinction

API	Source-level contract. Broken → compiler error, with a line number.
ABI	Binary-level contract. Broken → wrong answers, usually with no message at all.

x86-64 System V, in four lines

Integer / pointer arguments	`rdi rsi rdx rcx r8 r9`, then the stack
Float / double arguments	`xmm0`–`xmm7`, counted separately
Return value	`rax`, or `xmm0` for floating point
Struct field offsets	Each field aligned to its own width; total rounded up to the largest

Writing an FFI binding

Set `argtypes` and `restype`	On every single function. The defaults are wrong for pointers and doubles.
Assert `sizeof` and offsets	Sizes can match while layouts differ.
Export a self-description	Two functions returning `sizeof` and an `offsetof` pay for themselves.
Prefer opaque pointers	A layout nobody can see is a layout nobody can get wrong.

Wrapping up

What to take away

The mnemonic in the first table is worth keeping — Programming versus Binary, one contract for people writing code and one for code that has already been written. But the reason to care is narrower than that.

The short list

An API break is loud; an ABI break is silent. The compiler is on your side for one of them and completely absent for the other.
Field order is part of your public interface. It does not look like it in the header, and swapping two lines is a breaking change.
Every hand-written binding is a copy of a layout, so make it checkable. Export sizeof and a couple of offsets, assert them at import time, and the entire category of bug in part 4 turns into a failed assertion.

The stability techniques in part 5 only matter once someone else ships a binary against your code. Until then the ABI is a private matter and you can rearrange whatever you like. The day that stops being true is the day the opaque pointer starts looking cheap.

Appendix · The complete programs

Building and running

Five short files produced every output on this page. They are reproduced in full below, so copying the snippets into one directory is enough to reproduce all of it.

build and run everything

gcc -std=c11 -Wall -Wextra -o layout layout.c && ./layout

gcc -std=c11 -Wall -Wextra -shared -fPIC -o libconfig.so libconfig.c
python3 client.py

g++ -c mangling.cpp -o mangling.o && nm mangling.o && nm -C mangling.o

gcc -O1 -c callconv.c -o callconv.o
objdump -d --no-show-raw-insn callconv.o

gcc -shared -fPIC -Wl,-soname,libconfig.so.1 -o libconfig.so.1.0.0 libconfig.c
readelf -d libconfig.so.1.0.0 | head -6

Verified on gcc 11.4.0 and GNU binutils 2.38 (Ubuntu 22.04, x86-64) with CPython 3.10.12. The one value that is not reproducible is the integer read in part 3 of client.py, which is whatever the return register happened to contain.

layout.c 43 lines

layout.c

#include <stddef.h>
#include <stdio.h>

/* Same three fields, same API, two different binary layouts. */

struct badly_ordered {
    char   tag;
    double value;
    int    id;
};

struct well_ordered {
    double value;
    int    id;
    char   tag;
};

#define SHOW(S, M)                                                       \
    printf("  %-6s offset %2zu   size %2zu   align %2zu\n", #M,          \
           offsetof(S, M), sizeof(((S *)0)->M), _Alignof(((S *)0)->M))

int main(void) {
    size_t payload = sizeof(double) + sizeof(int) + sizeof(char);

    printf("struct badly_ordered   sizeof = %2zu   align %zu\n",
           sizeof(struct badly_ordered), _Alignof(struct badly_ordered));
    SHOW(struct badly_ordered, tag);
    SHOW(struct badly_ordered, value);
    SHOW(struct badly_ordered, id);

    printf("\nstruct well_ordered    sizeof = %2zu   align %zu\n",
           sizeof(struct well_ordered), _Alignof(struct well_ordered));
    SHOW(struct well_ordered, value);
    SHOW(struct well_ordered, id);
    SHOW(struct well_ordered, tag);

    printf("\nfield bytes actually used: %zu\n", payload);
    printf("padding in badly_ordered : %zu\n",
           sizeof(struct badly_ordered) - payload);
    printf("padding in well_ordered  : %zu\n",
           sizeof(struct well_ordered) - payload);
    return 0;
}

callconv.c 9 lines

callconv.c

/* Where do arguments actually go? Build and look:
     gcc -O1 -c callconv.c -o callconv.o
     objdump -d --no-show-raw-insn callconv.o */

int sum4(int a, int b, int c, int d) { return a + b + c + d; }

double product2(double x, double y) { return x * y; }

int mixed(int a, double x, int b) { return a + b + (int)x; }

mangling.cpp 12 lines

mangling.cpp

/* What a linker actually sees. Build with:
     g++ -c mangling.cpp -o mangling.o && nm mangling.o */

int add(int a, int b) { return a + b; }

double add(double a, double b) { return a + b; }

namespace geometry {
int add(int a, int b) { return a + b; }
}  // namespace geometry

extern "C" int add_c(int a, int b) { return a + b; }

libconfig.c 29 lines

libconfig.c

#include <stddef.h>
#include <stdio.h>

/* Everything a caller in another language has to agree with lives here:
   the layout of struct config, and the exported symbols below. */

struct config {
    int    width;
    int    height;
    double scale;
};

int config_area(const struct config *c) {
    return c->width * c->height;
}

double config_scaled_area(const struct config *c) {
    return c->width * c->height * c->scale;
}

const char *config_describe(const struct config *c) {
    static char buf[64];
    snprintf(buf, sizeof buf, "%dx%d @ %.2fx", c->width, c->height, c->scale);
    return buf;
}

/* Self-description, so a caller can verify its mirror instead of trusting it. */
size_t config_sizeof(void) { return sizeof(struct config); }
size_t config_offset_scale(void) { return offsetof(struct config, scale); }

client.py 76 lines

client.py

"""Three ways to talk to libconfig.so: one right, two wrong."""

import ctypes

lib = ctypes.CDLL("./libconfig.so")
lib.config_sizeof.restype = ctypes.c_size_t
lib.config_offset_scale.restype = ctypes.c_size_t

# ---- 1. a mirror that matches the C struct -------------------------------

class Config(ctypes.Structure):
    _fields_ = [
        ("width", ctypes.c_int),
        ("height", ctypes.c_int),
        ("scale", ctypes.c_double),
    ]

lib.config_area.argtypes = [ctypes.POINTER(Config)]
lib.config_area.restype = ctypes.c_int
lib.config_describe.argtypes = [ctypes.POINTER(Config)]
lib.config_describe.restype = ctypes.c_char_p

print("== 1. matching mirror ==")
print("sizeof        : python", ctypes.sizeof(Config), "| c", lib.config_sizeof())
print("offset(scale) : python", Config.scale.offset, "| c", lib.config_offset_scale())
assert ctypes.sizeof(Config) == lib.config_sizeof()
assert Config.scale.offset == lib.config_offset_scale()

cfg = Config(width=1920, height=1080, scale=1.5)
print("area          :", lib.config_area(ctypes.byref(cfg)))
print("describe      :", lib.config_describe(ctypes.byref(cfg)).decode())

# ---- 2. the same fields, declared in a different order -------------------
# A second handle, as if a different program had written its own mirror.

class ConfigWrong(ctypes.Structure):
    _fields_ = [
        ("scale", ctypes.c_double),
        ("width", ctypes.c_int),
        ("height", ctypes.c_int),
    ]

other = ctypes.CDLL("./libconfig.so")
other.config_area.argtypes = [ctypes.POINTER(ConfigWrong)]
other.config_area.restype = ctypes.c_int
other.config_describe.argtypes = [ctypes.POINTER(ConfigWrong)]
other.config_describe.restype = ctypes.c_char_p
other.config_offset_scale.restype = ctypes.c_size_t

print("\n== 2. reordered mirror ==")
print("sizeof        : python", ctypes.sizeof(ConfigWrong), "| c", lib.config_sizeof(),
      "-> agrees, and proves nothing")
print("offset(scale) : python", ConfigWrong.scale.offset, "| c",
      other.config_offset_scale(), "-> the actual disagreement")

bad = ConfigWrong(scale=1.5, width=1920, height=1080)
print("area          :", other.config_area(ctypes.byref(bad)))
print("describe      :", other.config_describe(ctypes.byref(bad)).decode())
print("no exception, no warning, no crash")

# ---- 3. a function called without declaring its return type --------------

print("\n== 3. missing restype ==")
lib.config_scaled_area.argtypes = [ctypes.POINTER(Config)]
print("default (int) :", lib.config_scaled_area(ctypes.byref(cfg)))

lib.config_scaled_area.restype = ctypes.c_double
print("c_double      :", lib.config_scaled_area(ctypes.byref(cfg)))
print("expected      :", 1920 * 1080 * 1.5)

The X-macro, from #define to runtime reflection

2026-08-23T00:33:31.770-07:00

C · Preprocessor

C forgets the name of every field the moment it finishes compiling. The X-macro is how a C programmer gets those names back — by writing the list once and replaying it as an enum, a string table, a descriptor table, and a set of registration calls that run before main.

Almost everyone meets #define as a way to name the number 100 and then never thinks about it again. That is a shame, because the preprocessor is the only part of C that can write C for you, and there is one pattern in particular that turns it from a curiosity into something load-bearing.

The problem it solves is dull enough that it hides in plain sight: one piece of knowledge, written down in two places. An enum and the array of names that goes with it. A struct and the code that serialises it. A config table and the parser that reads it. Each pair is fine on the day it is written and wrong three months later, when someone edits one half.

This is written as a path. Part 1 is the mechanics — what a macro actually does, and how a list grows a hole in it. Part 2 builds the useful thing: a runtime table describing a struct, with offsets the compiler computes. Part 3 makes that table reachable, first from elsewhere in the program and then from Python. Part 4 is the part people learn the hard way.

Everything here was compiled and run before publishing — gcc 11.4.0 on x86-64, CPython 3.10 — and every output block is copied from a real run, including the error message.

The preprocessor — what is really happening before the compiler starts
Describing a struct — the payoff: a table the compiler fills in
Making it reachable — from a table nobody can find to one everybody can
Practice — traps, tooling, and knowing when to stop
Appendix — the three programs in full, and how to build them

Part 1 · The preprocessor

A macro is text, not a value

Most people meet #define as a way to name a constant, and stop there.

the half everyone knows

#define MAX_USERS 100

The other half is that a macro can take parameters, and that what it does is substitute text before the compiler ever sees the file.

the other half

#define SQUARE(x) ((x) * (x))

int n = SQUARE(3 + 1);      /* becomes ((3 + 1) * (3 + 1)), so 16 */

Nothing is evaluated. No types are checked. There is no function call, no scope, no x anywhere at runtime. The preprocessor pastes characters and moves on, and the compiler then reads the result as if you had typed it yourself.

Hold on to that sentence, because every clever thing below is just careful pasting. The parentheses around (x) in that snippet are the classic example of why: without them, SQUARE(3 + 1) pastes into 3 + 1 * 3 + 1, which is 7.

Mental model

A macro is not a function that runs early. It is a find-and-replace rule that runs on your source text. When an expansion surprises you, the answer is always visible in the pasted text — see debugging expansions.

Two lists that must agree

Say you have three colours. You need an enum for the code, and names for logging.

the obvious way

enum color { COLOR_RED, COLOR_GREEN, COLOR_BLUE, COLOR_COUNT };

static const char *color_names[] = { "RED", "GREEN", "BLUE" };

This is fine. It stays fine right up until someone adds COLOR_YELLOW to the enum and does not touch the array. Now color_names[COLOR_YELLOW] reads past the end of the array, and nothing warns you — as far as the compiler is concerned these are two unrelated declarations that happen to sit next to each other. Keeping them in sync is a rule that lives only in someone's memory.

The same shape shows up everywhere once you start looking for it: an enum and the switch over it, a struct and its serialiser, a set of command-line flags and the help text. Two lists, one fact, and a silent failure when they disagree.

The X-macro: give the list a parameter

The idea is to write the list exactly once, but leave a hole where the action goes.

the list

#define COLOR_LIST(X) \
    X(RED)            \
    X(GREEN)          \
    X(BLUE)

COLOR_LIST is not a value and cannot be used on its own. It is a list that does not yet know what to do with its items — X is the hole. By convention that parameter is named X, which is the whole reason the pattern is called an X-macro; any name works.

Now define what a single item should become, and hand it in.

two actions, one list

#define AS_ENUM(name)   COLOR_##name,
#define AS_STRING(name) #name,

enum color { COLOR_LIST(AS_ENUM) COLOR_COUNT };

static const char *color_names[] = { COLOR_LIST(AS_STRING) };

COLOR_LIST(AS_ENUM) pastes into COLOR_RED, COLOR_GREEN, COLOR_BLUE, and COLOR_LIST(AS_STRING) pastes into "RED", "GREEN", "BLUE",. Two completely different pieces of code out of one list, and the trailing comma is harmless in both because COLOR_COUNT follows the first and C allows a trailing comma in an initialiser.

Add X(YELLOW) to the list and both the enum and the name array grow. The synchronisation bug is not fixed by discipline here; it has been made impossible to write.

./demo

colors: 3
  0 = RED
  1 = GREEN
  2 = BLUE

Note

Notice where the comma lives: inside AS_ENUM and AS_STRING, not in COLOR_LIST. The list carries no punctuation at all, because different actions want different separators — an enum wants commas, a sequence of statements wants none.

The two operators: `#` and `##`

Those action macros used two operators that exist nowhere else in C.

Operator	Name	Given `name` = `RED`
`#name`	stringify	produces the string literal `"RED"`
`A##B`	token paste	`COLOR_##name` produces the single token `COLOR_RED`

The property that makes # worth the trouble is that the string comes from the actual token you wrote. You cannot end up with a name string that disagrees with the identifier beside it, because they are literally the same characters. Every hand-written "id" next to a field called id is a copy waiting to go stale; #M is not a copy.

## is what lets one list generate distinct identifiers — COLOR_RED, sensor_reading_fields, FIELD_IDX_timestamp. It has one sharp edge, which we will hit in the section on unique names: ## suppresses macro expansion of its own operands.

Part 2 · Describing a struct

What C throws away

Colours are a warm-up. Here is the use that actually earns the pattern its place.

C discards field names at compile time. After the compiler is done, a struct is a size and a set of byte offsets; the word timestamp exists in the debug info, if you asked for it, and nowhere else. So the moment something outside the compiler needs to know that "byte 16 of this struct is a double called timestamp" — a serialiser, a logger, a test harness, another language — somebody has to write that down.

Writing it down by hand is the two-lists problem again, with worse consequences, because now the second list contains numbers.

demo.c — the struct

struct sensor_reading {
    int    id;
    int    sample_count;
    float  temperature;
    double timestamp;
    char  *label;
};

demo.c — what we want to produce

typedef enum { FIELD_INT, FIELD_FLOAT, FIELD_DOUBLE, FIELD_PTR } field_type;

typedef struct {
    const char *name;
    field_type  type;
    unsigned    offset;
    unsigned    size;
} field_desc;

Building the field table

Same shape as before: write the list once, with a hole. Each item now carries three pieces of information instead of one — the struct it belongs to, the member, and a type tag.

demo.c — the list

#define SENSOR_FIELDS(X)                               \
    X(struct sensor_reading, id, FIELD_INT)            \
    X(struct sensor_reading, sample_count, FIELD_INT)  \
    X(struct sensor_reading, temperature, FIELD_FLOAT) \
    X(struct sensor_reading, timestamp, FIELD_DOUBLE)  \
    X(struct sensor_reading, label, FIELD_PTR)

demo.c — one action, one table

#define AS_FIELD_DESC(S, M, T) \
    { #M, (T), (unsigned)offsetof(S, M), (unsigned)sizeof(((S *)0)->M) },

static const field_desc sensor_layout[] = { SENSOR_FIELDS(AS_FIELD_DESC) };

Two things in that action macro are worth stopping on.

offsetof(S, M) is a standard macro from <stddef.h>, and the crucial word is standard: the compiler computes the byte offset. You never type a number, so the table cannot drift from the real layout when a field is inserted, when the order changes, or when padding rules differ between targets.

sizeof(((S *)0)->M) is the idiom for "the size of member M of type S" when you have no instance to point at. It looks like a null dereference and is not one: sizeof does not evaluate its operand, it only inspects the operand's type, so nothing is ever read from address zero. C11 also offers sizeof(((S){0}).M) if the cast makes you uncomfortable.

Here is what the preprocessor genuinely emits for the first entry, lifted out of gcc -E -P demo.c:

gcc -E -P demo.c — after pasting

{"id", (FIELD_INT), (unsigned)__builtin_offsetof (struct sensor_reading, id),
 (unsigned)sizeof(((struct sensor_reading *)0)->id)},

…and what the compiler folds that into, before anything runs:

constant-folded

{"id", 0, 0, 4}

There is no runtime cost to any of this. The table is a static array of constants in .rodata, exactly as if it had been typed out by hand — the difference is only in who typed it.

The padding you would have got wrong

The full table, printed at runtime:

./demo

sizeof(struct sensor_reading) = 32
field count = 5
name           type  offset  size
id             0     0       4
sample_count   0     4       4
temperature    1     8       4
timestamp      2     16      8
label          3     24      8

Look at temperature: it starts at byte 8 and is 4 bytes long, so it ends at 12. But timestamp starts at 16, not 12. The compiler inserted four bytes of padding so the double lands on an 8-byte boundary. The five field sizes add up to 28; the struct is 32.

A hand-written table would have said 12, and every read through it would have been off by four bytes from that field onward — the kind of bug that produces plausible-looking garbage rather than a crash. offsetof did not get it wrong, and cannot.

ABI

These numbers are for the x86-64 System V ABI. On a different target the offsets and the total size may differ. That is an argument for offsetof rather than a caveat about it: the same source produces the right table on each target.

The same list, a different output

The list is now a reusable asset, and this is where the pattern starts paying compound interest. A different action over the same list gives you named indices into the table:

demo.c

#define AS_INDEX(S, M, T) FIELD_IDX_##M,

enum { SENSOR_FIELDS(AS_INDEX) SENSOR_FIELD_COUNT };

./demo

FIELD_IDX_timestamp = 3

Note that AS_INDEX ignores two of its three parameters. That is normal and fine — the list is a fixed shape, and each action takes what it needs. Adding one field to the struct and one line to the list now updates the descriptor table, the index enum, and the count, in one edit.

Other actions people write over the same list, without changing it: a switch that converts a field name string back to an index, a printf-style dumper with the right format specifier per type tag, a JSON writer, a comparison function, a fuzzer that fills each field with the right kind of noise.

Renaming a field breaks the build — on purpose

This is the property that makes the syntax worth tolerating, and it is easy to miss because nothing visibly happens on a good day.

Rename id to reading_id in the struct and forget the list. The build stops:

gcc -std=c11 -Wall -Wextra -o demo demo.c

error: ‘struct sensor_reading’ has no member named ‘id’
   50 |     {#M, (T), (unsigned)offsetof(S, M), (unsigned)sizeof(((S *)0)->M)},
      |                         ^~~~~~~~
   43 |     X(struct sensor_reading, id, FIELD_INT)
      |     ^ in expansion of macro ‘AS_FIELD_DESC’

Compare that with the hand-written table, where the string "id" would go on cheerfully naming a field that no longer exists, and the offset next to it would now describe a different field entirely. A stale hand-written mirror is silent; a stale X-macro list is a compile error. The entire pattern can be justified on that one sentence.

Reading the error

The compiler points at line 50 — inside AS_FIELD_DESC, which is not where your mistake is — and then adds an "in expansion of macro" note pointing at line 43, which is. Always read down to the note.

Part 3 · Making it reachable

Registering yourself before `main`

A table is only useful if something can find it. The usual arrangement is a small registry that types add themselves to:

reflect.c — the registry API

void layout_register(const char *type_name, const field_desc *fields,
                     size_t count, size_t struct_size);

const field_desc *layout_lookup(const char *type_name, size_t *count_out);

You could call layout_register from main. But then every new type means editing main, and a central list of every type in the program is exactly the drift problem from part 1, moved up one level. Better to have the call happen by itself:

reflect.c — one line adds a type

#define REGISTER_LAYOUT(NAME, STRUCT, FIELDS)                               \
    static const field_desc NAME##_fields[] = { FIELDS(AS_FIELD_DESC) };    \
    __attribute__((constructor)) static void NAME##_register_layout(void) { \
        layout_register(#NAME, NAME##_fields,                               \
                        sizeof(NAME##_fields) / sizeof(NAME##_fields[0]),   \
                        sizeof(STRUCT));                                    \
    }

REGISTER_LAYOUT(sensor_reading, struct sensor_reading, SENSOR_FIELDS)

That one invocation generates three things at once: a static table built from the field list, a function that hands it to the registry, and the annotation that makes the function run on its own. #NAME supplies the lookup key, and sizeof(arr)/sizeof(arr[0]) supplies the count without anyone counting.

__attribute__((constructor)) marks a function to run before main — or, in a shared library, at load time. It is a GCC and Clang extension rather than ISO C; MSVC has its own mechanism via .CRT$XCU, and the portable fallback is an explicit init() that you do have to remember to call. In C++ the same effect falls out of a global object's constructor, which is why you see the trick spelled as a dummy static Registrar r{} there.

Why this shape keeps showing up

The knowledge sits next to the thing it describes. The field list lives beside the struct, not in a registry file three directories away.
Adding a type is a local edit. No shared file to touch, so no merge conflict when two people add a type in the same week.
Nothing can be half-added. The table, the registration and the name all come from one macro invocation, so there is no state where one exists without the others.

Unique names when the macro is used twice

NAME##_fields works because the caller supplies a distinct NAME. Sometimes a macro has to be usable twice in one file with nothing to distinguish the uses — two registrations of the same struct under different keys, say. The standard-ish trick is __COUNTER__, which expands to 0, 1, 2, … each time it is read.

the two-step dance

#define UNIQUE_IMPL2(ctr) static int tmp_var_##ctr;
#define UNIQUE_IMPL(ctr)  UNIQUE_IMPL2(ctr)
#define MAKE_UNIQUE()     UNIQUE_IMPL(__COUNTER__)

Trap

The middle layer is not decoration. ## suppresses expansion of its operands, so without UNIQUE_IMPL you get a variable literally named tmp_var___COUNTER__ — and a redefinition error on the second use. The extra indirection forces __COUNTER__ to expand to a number before it reaches the paste.

__COUNTER__ is supported by GCC, Clang and MSVC but is not in the standard. __LINE__ is the portable substitute and is fine whenever one use per line is an acceptable restriction.

Reading the table from another language

Once the table lives in a shared library behind a plain C function, anything with an FFI can read it. Python's ctypes is in the standard library, so this needs no dependencies:

read_layout.py

class FieldDesc(ctypes.Structure):
    _fields_ = [("name", ctypes.c_char_p), ("type", ctypes.c_int),
                ("offset", ctypes.c_uint), ("size", ctypes.c_uint)]

lib = ctypes.CDLL("./libreflect.so")
lib.layout_lookup.restype = ctypes.POINTER(FieldDesc)

count = ctypes.c_size_t(0)
table = lib.layout_lookup(b"sensor_reading", ctypes.byref(count))

The FieldDesc declaration on the Python side does have to match the C one by hand — that is the one mirror you cannot escape. But it is a single four-field descriptor type that changes approximately never, and it buys you the description of every other struct in the program.

Building the mirror at runtime

Because the table carries names, type tags and offsets, the caller can construct a matching structure definition while the program runs, instead of hand-writing one per struct:

read_layout.py

TAGS = {0: ctypes.c_int, 1: ctypes.c_float, 2: ctypes.c_double, 3: ctypes.c_void_p}

fields = [(table[i].name.decode(), TAGS[table[i].type]) for i in range(count.value)]
Mirror = type("SensorReading", (ctypes.Structure,), {"_fields_": fields})

python3 read_layout.py

id             tag=0 offset=0   size=4
sample_count   tag=0 offset=4   size=4
temperature    tag=1 offset=8   size=4
timestamp      tag=2 offset=16  size=8
label          tag=3 offset=24  size=8

built mirror : SensorReading
python sizeof: 32
c sizeof     : 32
mirror.timestamp offset: 16

The two sizeof values agreeing is the check that matters, and it is worth asserting rather than eyeballing. If they differ, the description is wrong somewhere and every subsequent read through the mirror lands on the wrong bytes — silently, with plausible values.

This is the whole payoff, and it is worth stating plainly: the struct is defined once, in C, and everybody else asks it what it looks like. No generated bindings to regenerate, no Python file to update when a field moves, no version skew between a library and the script reading it — because the description ships inside the library.

Part 4 · Practice

Pitfalls

The trailing backslash must be the last character on the line

One trailing space after it and the continuation silently ends, taking the rest of your list with it. Some compilers warn; do not count on it. This is the single most common way to lose an hour to this pattern, and it is invisible in a diff.

Put the punctuation in the action, not the list

Different actions need different separators. Keep the list free of commas and semicolons so it can serve an enum, an initialiser and a sequence of statements without special cases.

Order matters when position matters

If consumers index the table by position, the list must follow the struct's declaration order. Nothing enforces this — the build still succeeds, and only the offset column looks odd. If you can, index by name instead.

Macros do not recurse

A list cannot include itself, directly or through another macro. Nested lists work only in a strict hierarchy. If you find yourself wanting recursion, you have outgrown the pattern.

Keep the list next to the thing it describes

A field list in a different file from the struct can drift in the one way the pattern exists to prevent: somebody adds a field, never sees the list, and the table is quietly incomplete. Note that this failure is not caught by the compiler — the rename check only fires for fields the list mentions.

The one gap

An X-macro list catches renamed and deleted fields. It does not catch added ones. If completeness matters, add a static assertion that the field sizes plus known padding equal sizeof the struct, or simply assert the struct size and let the build break when it changes.

Debugging with the preprocessor, not by staring

Nearly every X-macro bug becomes obvious the moment you look at the pasted text. Do not reason about it; print it.

see what the compiler sees

gcc -E -P demo.c                      # preprocess only, strip line markers
gcc -E -P demo.c | clang-format       # ...and make it readable
gcc -E -P demo.c | sed -n '/sensor_layout/,/;/p'

-E stops after preprocessing and -P drops the #line markers that otherwise dominate the output. Everything the compiler will see is in there, including the expansion you were sure was correct.

When not to reach for it

When the list has exactly one consumer

If you only need the enum, write the enum. The pattern costs readability up front and repays it per consumer; it breaks even at two and clearly pays at three.

When the list is large, or comes from somewhere else

Past a few dozen entries, or when the real source of truth is a schema file, a protobuf definition or a database, generate a .c file from a script. Generated code can be read, diffed and stepped through in a debugger; a wall of backslash continuations cannot.

When you want type dispatch, not list replay

C11's _Generic selects an expression based on a type. It solves a different problem and reads far better for that one.

When the language has real reflection

This entire pattern is a workaround for C discarding names. In a language that keeps them, use what the language gives you.

Cheat sheet

Preprocessor operators and predefined macros

`#x`	Stringify the argument as written
`a##b`	Paste two tokens into one; suppresses expansion of both operands
`__COUNTER__`	0, 1, 2, … per read — needs a two-step macro to paste with
`__LINE__`, `__FILE__`	Portable alternatives; one use per line
`__VA_ARGS__`	Variadic macro arguments, for actions of varying arity

Layout introspection

`offsetof(S, M)`	Byte offset of a member, from `<stddef.h>`
`sizeof(((S *)0)->M)`	Size of a member with no instance; operand is not evaluated
`sizeof(a) / sizeof(a[0])`	Element count of a real array — not of a pointer
`_Static_assert(c, "msg")`	Compile-time check; useful for pinning struct size

Running code before `main`

`__attribute__((constructor))`	GCC and Clang; also runs at `dlopen` time
Global object constructor	C++; the same effect, portably
`.CRT$XCU` section	MSVC equivalent
Explicit `init()`	Portable fallback, at the cost of a central call site

Commands

`gcc -E -P f.c`	Show the pasted text the compiler will read
`gcc -Wall -Wextra`	Catches trailing-comma and unused-macro-argument mistakes
`pahole ./a.out`	Print struct layout and padding, independently of your table

Wrapping up

What actually matters here

The X-macro has a reputation for being a clever trick, which undersells it. It is a way of making a class of bug unrepresentable, and the syntax is the price.

The short list

The list with a hole is the whole idea. LIST(X) plus an action macro; everything else in this document is a choice of action.
Let the compiler compute the numbers. offsetof and sizeof mean the table cannot disagree with the struct, on any target, ever.
A stale hand-written mirror is silent; a stale list is a compile error. That trade — a little syntax now for a loud failure later — is the reason to use it.

The registry and the FFI reader in part 3 are a step further than most code needs, but they are the natural end of the road: once the description exists as data, the interesting question stops being "how do I keep these in sync" and becomes "who else would like to read this". Usually the answer is more people than you expected.

Appendix · The complete programs

Building and running

Everything above came from three short files, reproduced in full below so this page stands on its own — copy the three snippets into a directory and the commands work as written.

build and run everything

gcc -std=c11 -Wall -Wextra -o demo demo.c && ./demo

gcc -std=c11 -Wall -Wextra -shared -fPIC -o libreflect.so reflect.c
python3 read_layout.py

gcc -E -P demo.c | head -40        # see what the preprocessor produced

Verified on gcc 11.4.0 (Ubuntu 22.04, x86-64) and CPython 3.10.12. Every output block on this page is copied from a real run, including the compiler error in the rename section, which was produced by renaming id to reading_id in a copy of demo.c.

demo.c 74 lines

The warm-up and the field table, in one standalone program. Nothing outside the C standard library.

demo.c

#include <stddef.h>
#include <stdio.h>

/* ---------- Warm-up: one list, two outputs ---------- */

#define COLOR_LIST(X) \
    X(RED)            \
    X(GREEN)          \
    X(BLUE)

#define AS_ENUM(name)   COLOR_##name,
#define AS_STRING(name) #name,

enum color { COLOR_LIST(AS_ENUM) COLOR_COUNT };

static const char *color_names[] = {COLOR_LIST(AS_STRING)};

/* ---------- Main: a runtime field table ---------- */

struct sensor_reading {
    int    id;
    int    sample_count;
    float  temperature;
    double timestamp;
    char  *label;
};

typedef enum {
    FIELD_INT = 0,
    FIELD_FLOAT = 1,
    FIELD_DOUBLE = 2,
    FIELD_PTR = 3
} field_type;

typedef struct {
    const char *name;
    field_type  type;
    unsigned    offset;
    unsigned    size;
} field_desc;

#define SENSOR_FIELDS(X)                              \
    X(struct sensor_reading, id, FIELD_INT)           \
    X(struct sensor_reading, sample_count, FIELD_INT) \
    X(struct sensor_reading, temperature, FIELD_FLOAT)\
    X(struct sensor_reading, timestamp, FIELD_DOUBLE) \
    X(struct sensor_reading, label, FIELD_PTR)

#define AS_FIELD_DESC(S, M, T) \
    {#M, (T), (unsigned)offsetof(S, M), (unsigned)sizeof(((S *)0)->M)},

static const field_desc sensor_layout[] = {SENSOR_FIELDS(AS_FIELD_DESC)};

#define AS_INDEX(S, M, T) FIELD_IDX_##M,

enum { SENSOR_FIELDS(AS_INDEX) SENSOR_FIELD_COUNT };

int main(void) {
    printf("colors: %d\n", (int)COLOR_COUNT);
    for (int i = 0; i < COLOR_COUNT; i++)
        printf("  %d = %s\n", i, color_names[i]);

    printf("\nsizeof(struct sensor_reading) = %zu\n",
           sizeof(struct sensor_reading));
    printf("field count = %d\n", (int)SENSOR_FIELD_COUNT);
    printf("%-14s %-5s %-7s %s\n", "name", "type", "offset", "size");
    for (size_t i = 0; i < sizeof(sensor_layout) / sizeof(sensor_layout[0]); i++)
        printf("%-14s %-5d %-7u %u\n", sensor_layout[i].name,
               (int)sensor_layout[i].type, sensor_layout[i].offset,
               sensor_layout[i].size);

    printf("\nFIELD_IDX_timestamp = %d\n", (int)FIELD_IDX_timestamp);
    return 0;
}

reflect.c 83 lines

The registry plus a type that puts itself in it. Built as a shared library; it has no main, and the only thing that runs is the constructor.

reflect.c

#include <stddef.h>
#include <string.h>

typedef struct {
    const char *name;
    int         type;
    unsigned    offset;
    unsigned    size;
} field_desc;

typedef struct {
    const char       *type_name;
    const field_desc *fields;
    size_t            count;
    size_t            struct_size;
} type_layout;

/* A tiny fixed-capacity registry. */
static type_layout g_registry[16];
static size_t      g_registry_count;

void layout_register(const char *type_name, const field_desc *fields, size_t count,
                     size_t struct_size) {
    if (g_registry_count >= 16) return;
    g_registry[g_registry_count].type_name = type_name;
    g_registry[g_registry_count].fields = fields;
    g_registry[g_registry_count].count = count;
    g_registry[g_registry_count].struct_size = struct_size;
    g_registry_count++;
}

const field_desc *layout_lookup(const char *type_name, size_t *out_count) {
    for (size_t i = 0; i < g_registry_count; i++) {
        if (strcmp(type_name, g_registry[i].type_name) == 0) {
            if (out_count) *out_count = g_registry[i].count;
            return g_registry[i].fields;
        }
    }
    if (out_count) *out_count = 0;
    return NULL;
}

size_t layout_sizeof(const char *type_name) {
    for (size_t i = 0; i < g_registry_count; i++)
        if (strcmp(type_name, g_registry[i].type_name) == 0)
            return g_registry[i].struct_size;
    return 0;
}

/* ---- a type that registers itself ---- */

struct sensor_reading {
    int    id;
    int    sample_count;
    float  temperature;
    double timestamp;
    char  *label;
};

#define FIELD_INT 0
#define FIELD_FLOAT 1
#define FIELD_DOUBLE 2
#define FIELD_PTR 3

#define SENSOR_FIELDS(X)                               \
    X(struct sensor_reading, id, FIELD_INT)            \
    X(struct sensor_reading, sample_count, FIELD_INT)  \
    X(struct sensor_reading, temperature, FIELD_FLOAT) \
    X(struct sensor_reading, timestamp, FIELD_DOUBLE)  \
    X(struct sensor_reading, label, FIELD_PTR)

#define AS_FIELD_DESC(S, M, T) \
    {#M, (T), (unsigned)offsetof(S, M), (unsigned)sizeof(((S *)0)->M)},

#define REGISTER_LAYOUT(NAME, STRUCT, FIELDS)                                 \
    static const field_desc NAME##_fields[] = {FIELDS(AS_FIELD_DESC)};        \
    __attribute__((constructor)) static void NAME##_register_layout(void) {   \
        layout_register(#NAME, NAME##_fields,                                 \
                        sizeof(NAME##_fields) / sizeof(NAME##_fields[0]),     \
                        sizeof(STRUCT));                                      \
    }

REGISTER_LAYOUT(sensor_reading, struct sensor_reading, SENSOR_FIELDS)

Note

field_desc is declared identically in both C files rather than shared through a header, so that each one can be read on its own. In a real program it would live in a header, and layout_register would be declared there too.

read_layout.py 37 lines

The other side of the wall: no C compiler involved, no generated bindings, just the library and the standard library.

read_layout.py

import ctypes


class FieldDesc(ctypes.Structure):
    _fields_ = [
        ("name", ctypes.c_char_p),
        ("type", ctypes.c_int),
        ("offset", ctypes.c_uint),
        ("size", ctypes.c_uint),
    ]


lib = ctypes.CDLL("./libreflect.so")

lib.layout_lookup.argtypes = [ctypes.c_char_p, ctypes.POINTER(ctypes.c_size_t)]
lib.layout_lookup.restype = ctypes.POINTER(FieldDesc)
lib.layout_sizeof.argtypes = [ctypes.c_char_p]
lib.layout_sizeof.restype = ctypes.c_size_t

TAGS = {0: ctypes.c_int, 1: ctypes.c_float, 2: ctypes.c_double, 3: ctypes.c_void_p}

count = ctypes.c_size_t(0)
table = lib.layout_lookup(b"sensor_reading", ctypes.byref(count))

fields = []
for i in range(count.value):
    f = table[i]
    print(f"{f.name.decode():14} tag={f.type} offset={f.offset:<3} size={f.size}")
    fields.append((f.name.decode(), TAGS[f.type]))

Mirror = type("SensorReading", (ctypes.Structure,), {"_fields_": fields})

print()
print("built mirror :", Mirror.__name__)
print("python sizeof:", ctypes.sizeof(Mirror))
print("c sizeof     :", lib.layout_sizeof(b"sensor_reading"))
print("mirror.timestamp offset:", Mirror.timestamp.offset)

Setting argtypes and restype is not optional decoration. Without them ctypes assumes every argument and the return value are int, which on x86-64 truncates pointers to 32 bits and produces a segfault that looks like it came from the C side.

The list that remembers: mutable default arguments in Python

2026-07-29T00:11:03.409-07:00

Python · Language

def append_to(item, target=[]) looks like it starts from an empty list every time. It does not. One list is created when the def statement runs, and every call for the rest of the program's life shares it.

This is the most famous gotcha in Python, and it is famous for a reason: the code is short, the intent is obvious, and it is wrong. There is no error, no warning at runtime, and the symptom depends on what earlier callers happened to do — which makes it genuinely hard to track down when you meet it in a real codebase rather than in a blog post.

It is also a two-minute fix once you know the rule. Every output below is copied from a real run on CPython 3.10.

The bug — three calls, one list
Why it happens — the default lives on the function object
The shape you actually hit — two carts, one basket
The fix — the None sentinel
Variations and near-misses — or [], sentinel objects, dataclasses
What is safe, what is not
Letting a linter catch it — B006 vs B008
Cheat sheet

Part 1 · The bug

Three calls, one list

append.py

def append_to(item, target=[]):
    target.append(item)
    return target

print(append_to(1))
print(append_to(2))
print(append_to(3))

$ python append.py

[1]
[1, 2]        ← expected [2]
[1, 2, 3]     ← expected [3]

The first call behaves. The second reveals that target was not empty when the call started. The list is accumulating across calls, because it is the same list each time.

Part 2 · Why it happens

The default lives on the function object

A default argument expression is evaluated once, when the def statement executes — not on each call. The resulting object is stored on the function and handed to every call that omits the argument. So [] is not an instruction to make a fresh list; it is one list, made once.

def append_to(item, target=[]):
                           ~~
                           evaluated once, at def time —
                           the resulting list is stored on the function

   call 1 ──┐
   call 2 ──┼──▶ that one list ──▶ [1] ─▶ [1, 2] ─▶ [1, 2, 3]
   call 3 ──┘    (never replaced, never reset)

You do not have to take this on faith. The list is reachable through __defaults__:

show_default.py

def append_to(item, target=[]):
    target.append(item)
    return target

print(append_to.__defaults__)
append_to(1)
print(append_to.__defaults__)
append_to(2)
print(append_to.__defaults__)

$ python show_default.py

([],)
([1],)        ← the list attached to the function has changed
([1, 2],)

That is the whole story. The default is a piece of state hanging off the function, and target.append(item) mutates it. Nothing resets it between calls, because nothing was ever going to.

Note what is not the problem

Rebinding is fine. def f(n=0): n += 1 cannot leak, because n += 1 on an integer creates a new object and points the local name at it — the stored default is untouched. The bug needs mutation of the default object, which is why only mutable types are affected.

Part 3 · The shape you actually hit

Two carts, one basket

Nobody writes append_to in production. What people do write is a constructor with an empty collection as its default — and then the shared object is shared between instances:

cart.py

class Cart:
    def __init__(self, items=[]):
        self.items = items

a = Cart()
b = Cart()
a.items.append("apple")

print(b.items)
print(a.items is b.items)
print(Cart.__init__.__defaults__)

$ python cart.py

['apple']              ← a different cart, with someone else's apple in it
True                   ← it was the same list all along
(['apple'],)           ← and it is living on Cart.__init__

Two independent objects, one shared basket. Worse, the default is attached to the class, so the contamination outlives both instances and reaches every Cart() created later in the process.

Why it is hard to debug

The reproduction condition is "what did some earlier caller put in there", which is not visible from the failing line, is not in the traceback, and often depends on test ordering. A unit test that constructs one Cart passes. The suite fails only when another test ran first — and then passes again when you run it alone to investigate.

Passing the argument explicitly sidesteps it, which is part of why the bug hides so well: the code path that everyone tests is usually the one that supplies a value.

explicit argument, no sharing

c = Cart(items=[])       # a genuinely new list
c.items.append("pear")
print(c.items, a.items)  # ['pear'] ['apple']

Part 4 · The fix

The `None` sentinel

Make the default an immutable marker, and build the real object inside the body. The construction then happens per call, which is what you wanted in the first place.

broken

def append_to(item, target=[]):
    target.append(item)
    return target


class Cart:
    def __init__(self, items=[]):
        self.items = items

correct

def append_to(item, target=None):
    if target is None:
        target = []
    target.append(item)
    return target

class Cart:
    def __init__(self, items=None):
        self.items = [] if items is None else items

the fixed version

append_to(1) → [1]
append_to(2) → [2]
append_to(3) → [3]
append_to.__defaults__ → (None,)      ← nothing to accumulate into

None is a singleton and immutable, so storing it on the function is harmless. The important part is the is None check: it is what turns "one object, made once" into "a new object per call".

Type it honestly

If the codebase is annotated, the parameter now genuinely accepts None, and the annotation should say so:

annotated

def append_to(item: int, target: list[int] | None = None) -> list[int]:
    if target is None:
        target = []
    target.append(item)
    return target

On Python 3.9 and earlier, write Optional[List[int]] from typing, or add from __future__ import annotations to use the | syntax anyway.

Part 5 · Variations and near-misses

Three things worth knowing

`or []` is shorter and subtly different

target = target or [] is a common abbreviation. It fixes the sharing, but it also replaces any falsy argument the caller passed — including an empty list they expected you to fill:

or_trap.py

def with_or(item, target=None):
    target = target or []          # empty list from the caller gets discarded
    target.append(item)
    return target

def with_is_none(item, target=None):
    target = [] if target is None else target
    target.append(item)
    return target

mine = []
with_or("x", mine)
print("or      →", mine)

mine = []
with_is_none("x", mine)
print("is None →", mine)

$ python or_trap.py

or      → []            ← the caller's list was never touched
is None → ['x']

The or version quietly appended to a throwaway list and the caller's stayed empty. Same class of confusion for 0, "" and False. Prefer is None: it tests for exactly the thing you meant.

When `None` is itself a valid value

Sometimes None is meaningful data and you still need to distinguish "not supplied". Use a private sentinel object:

sentinel object

_MISSING = object()

def fetch(key, default=_MISSING):
    if default is _MISSING:
        raise KeyError(key)     # no default supplied
    return default              # default supplied — possibly None

print(fetch("k", None))         # None
fetch("k")                      # KeyError: 'k'

This is how dict.pop and friends behave, and why they can tell those two cases apart.

Dataclasses refuse to let you do it

@dataclass knows about this bug and raises at class-creation time rather than letting you ship it:

bad_dc.py

from dataclasses import dataclass

@dataclass
class Bad:
    items: list = []

$ python bad_dc.py

ValueError: mutable default <class 'list'> for field items is not allowed: use default_factory

Note that this fires at import, before any instance exists — the decorator inspects the defaults while building the class. The sanctioned form is a factory, called once per instance:

good_dc.py

from dataclasses import dataclass, field

@dataclass
class Good:
    items: list = field(default_factory=list)

g1, g2 = Good(), Good()
g1.items.append("apple")
print(g1.items, g2.items, g1.items is g2.items)

$ python good_dc.py

['apple'] [] False

default_factory is the "call it per invocation" idea made explicit — the same thing the None check does by hand.

When the sharing is deliberate

A mutable default occasionally is the point — a memo dict that must persist across calls. It works, but it hides a piece of global state in a signature where no reader expects it. Use a module-level variable or functools.cache instead; both announce themselves.

Part 6 · What is safe, what is not

A quick classification

The rule follows directly from the mechanism: the stored object is only a hazard if something can mutate it.

Default	Safe?	Because
`None`, `0`, `""`, `True`	yes	Immutable; cannot be changed in place
`()`, `frozenset()`	yes	Immutable containers
A module-level constant	usually	Safe if genuinely immutable — a shared `CONFIG` dict is not
`[]`, `{}`, `set()`	no	One object, mutated in place by every caller
A custom class instance	no	One instance shared across calls
`datetime.now()`	no	Not mutation — it freezes at import time

That last row is a different bug wearing the same clothes, and it is worth seeing on its own:

frozen at import, not "now"

import time
from datetime import datetime

def stamped(when=datetime.now()):
    return when

t1 = stamped()
time.sleep(0.05)
t2 = stamped()
print(t1 == t2)          # True — both are the moment the module was imported

A long-running service will hand out the same timestamp for days. The test suite will not notice, because it imports and calls within the same instant.

Part 7 · Letting a linter catch it

B006 and B008

You should never be finding this by reading. flake8-bugbear — bundled into Ruff as the B rules — catches both variants:

Rule	Catches	Example
`B006` mutable-argument-default	A mutable literal or constructor as a default — the bug in this post	`def f(x=[])`
`B008` function-call-in-default-argument	Any function call in a default, evaluated once at import	`def f(t=datetime.now())`

pyproject.toml

[tool.ruff.lint]
extend-select = ["B"]      # all of flake8-bugbear, B006 and B008 included

$ ruff check --select B006,B008 --output-format concise .

app.py:4:28: B006 Do not use mutable data structures for argument defaults
app.py:9:21: B006 Do not use mutable data structures for argument defaults
app.py:13:18: B008 Do not perform function call `datetime.now` in argument defaults;
              instead, perform the call within the function, or read the default from
              a module-level singleton variable
app.py:18:30: B006 Do not use mutable data structures for argument defaults
Found 4 errors.

The two rules get conflated

target=[] is B006, not B008. The advice "perform the call within the function" belongs to B008's message — apt for datetime.now(), but a list literal is not a call. The remedy happens to be the same shape in both cases: move the work inside the body.

B008 has real exceptions

Some frameworks give a call in the default an actual meaning — FastAPI's Depends() is the standard example. Ruff's extend-immutable-calls exists for these; list the specific callable rather than disabling the rule.

Wrapping up

Cheat sheet

Instead of	Write
`def f(x=[])`	`def f(x=None)` then `if x is None: x = []`
`def f(x={})`	`def f(x=None)` then `x = {} if x is None else x`
`def f(t=datetime.now())`	`def f(t=None)` then `t = t or datetime.now()`
`x = x or []`	`x = [] if x is None else x` — unless discarding falsy input is intended
`items: list = []` in a dataclass	`items: list = field(default_factory=list)`
A memo dict in the signature	A module-level variable, or `functools.cache`

The short list

Defaults are evaluated once, at def time. The object is stored on the function and reused forever; [] means one list, not a fresh one per call.
You can watch it happen in f.__defaults__ — the list grows in place.
The damage scales in constructors. A default items=[] in __init__ is shared by every instance the process ever creates.
Default to None and build inside the body. Test with is None, not or, so a caller's empty list is still theirs.
Enable B in Ruff. B006 and B008 find every instance in seconds, and neither bug ever announces itself at runtime.

The loop variable that changed: late binding and default arguments in Python

2026-07-28T08:12:44.403-07:00

Python · Language

You define a function inside a loop, collect the functions, call them later — and every single one returns the last value. The usual fix is a strange-looking line where the same name appears twice. Here is what is actually going on, and why the fix works.

This bug has a particular texture. The code reads correctly, each function looks like it captured its own value, and nothing raises. You only find out when the results are all identical — and if the loop happens to have one iteration during development, you never find out at all.

The explanation is one sentence long: a closure captures the variable, not the value. Everything else in this post is unpacking what that means and what to do about it.

Every snippet was run on CPython 3.10 before publishing, and the output shown is copied from those runs.

The bug — three functions, one value
Why it happens — variables, cells, and Python's missing block scope
Anatomy of the fix — reading def f(x: T = x) as three parts
Defaults are evaluated once — the rule that makes the fix work
The same rule, as a trap — mutable default arguments
Other ways to capture — partial, factories, and which to prefer
Where it bites — threads, callbacks, handlers, tasks
What the type hint does — and when it is evaluated
Scoping rules, briefly — LEGB, nonlocal, comprehensions
Letting a linter catch it — B023 and B008
Cheat sheet

Part 1 · The bug

Three functions, one value

Build a list of functions in a loop. Each one returns the loop variable.

late.py

fns = []
for i in range(3):
    def show():
        return i
    fns.append(show)

print([f() for f in fns])

$ python late.py

[2, 2, 2]

Not [0, 1, 2]. All three functions return 2, the value i had when the loop finished. The functions were created at three different times, but they were never looking at three different values — they were all looking at the same i.

Why it survives review

Nothing about the code is unusual, and the failure is silent. It also depends on when you call: if you call show() inside the loop it returns the right thing, because i still holds that value at that moment. Deferring the call is what exposes it.

Part 2 · Why it happens

Variables, cells, and the missing block scope

A closure is a function plus a reference to the enclosing scope's variables. Not copies of their values — references to the variables themselves. Python stores each captured variable in a cell, and every closure over that variable shares the one cell.

You can look at the cell directly:

the cell is shared and mutable

def make():
    n = 0
    def inc():
        nonlocal n
        n += 1
        return n
    return inc

c = make()
print(c(), c(), c())              # 1 2 3
print(c.__closure__[0].cell_contents)   # 3

The three calls returned different numbers because they all read and wrote the same cell. That is the whole point of a closure — and it is exactly what goes wrong in the loop, because the loop variable is also just a variable in the enclosing scope.

There is a second ingredient. In most C-like languages, for (int i = ...) creates a new i scoped to the loop body. Python has no block scope: if, for and while do not create scopes. Only modules, functions and classes do. So there is exactly one i, it belongs to the enclosing function, and it outlives the loop:

the loop variable leaks

for i in range(3):
    pass
print(i)          # 2 — still in scope, still holding the last value

Put the two facts together and the behaviour is inevitable:

The loop rebinds one variable three times.
All three closures reference that one variable.
Calling them afterwards reads it once the loop has finished, so all three see the final value.

"Late binding" names the timing

The name lookup happens when the function runs, not when it is defined. That is the general rule for every free variable in Python, and it is usually what you want — it is why you can define a function that calls a helper declared later in the file.

Part 3 · Anatomy of the fix

Reading `def f(x: T = x)` as three parts

The fix is to bind the value into the function's own signature. In a typed codebase it ends up looking like this, which is where the confusion starts:

the idiom

def invoke(kernel: Kernel = kernel) -> None:
    ...

Three independent things are packed into kernel: Kernel = kernel:

def invoke(kernel: Kernel = kernel) -> None:
           ~~~~~~~~~~~~~~ ~~~~~~~~
           │     │        │
           │     │        └─ default value: the OUTER variable,
           │     │           evaluated now, at def time
           │     └─ type hint: the Kernel class
           └─ parameter name: a NEW local, created per call

The name appears twice because two different things happen to share a spelling. They live in different scopes and are resolved at different times:

	Left `kernel`	Right `kernel`
What it is	A parameter being declared	An expression being evaluated
Which scope	Local to `invoke`	The enclosing scope — the loop variable
When	On every call to `invoke`	Once, when the `def` statement runs
Effect	Shadows the outer name inside the body	Snapshots the current value

That last row is the mechanism. Because the right-hand side is evaluated while the loop is on that iteration, the value is captured then and stored on the function object. And because the left-hand side introduces a local with the same name, the body reads the captured parameter instead of the outer variable — the closure is gone.

fixed.py

fns = []
for i in range(3):
    def show(i=i):     # left i = new parameter; right i = this iteration's value
        return i
    fns.append(show)

print([f() for f in fns])

$ python fixed.py

[0, 1, 2]

You can see the snapshot on the function object. Rebinding the outer name afterwards changes nothing:

the value is stored, not looked up

x = 10
def f(a=x):
    return a

x = 999
print(f.__defaults__, f(), x)

output

(10,) 10 999

It changes the public signature

show(i=i) is an honest fix but not a free one: show now accepts an argument, and a caller can override the captured value. For an internal callback that is harmless. For a function you hand to someone else, prefer a factory (below) so the capture is not part of the API.

Part 4 · Defaults are evaluated once

The rule underneath

Default argument expressions are evaluated once, when the def statement executes — not on each call. This single rule explains both the fix above and the trap below.

Prove it with a default that announces itself:

once.py

def stamp(value=print("  (default evaluated)")):
    return value

print("  function defined, not called yet")
stamp()
stamp()

$ python once.py

  (default evaluated)
  function defined, not called yet

The message appears before "function defined", and appears only once despite two calls. The default was computed while Python was building the function object, and the result was stored on it.

So def show(i=i) is not a clever trick, it is the ordinary rule applied deliberately: you are asking for an expression to be evaluated now and remembered.

Part 5 · The same rule, as a trap

Mutable default arguments

Evaluated once means the default object is created once and reused by every call. If it is mutable, every call shares it — and the sharing persists for the lifetime of the function.

mutable.py

def append_bad(item, bucket=[]):
    bucket.append(item)
    return bucket

print(append_bad("a"))
print(append_bad("b"))
print(append_bad.__defaults__)

$ python mutable.py

['a']
['a', 'b']
(['a', 'b'],)

The second call did not start from an empty list. The [] in the signature is one list object, created once, now permanently attached to the function — you can see it grow inside __defaults__.

The fix is the None sentinel. Take the default as None and build the real thing inside:

avoid

def f(bucket=[]):
    bucket.append(1)
    return bucket

def g(cache={}):
    ...

def h(when=datetime.now()):
    ...       # frozen at import time!

prefer

def f(bucket=None):
    if bucket is None:
        bucket = []
    bucket.append(1)
    return bucket

def g(cache=None):
    cache = {} if cache is None else cache

def h(when=None):
    when = when or datetime.now()

The subtlest version of this bug

def h(when=datetime.now()) looks like "default to now". It means "default to the moment this module was imported". A long-running process will hand out the same timestamp for days, and the test suite will pass because it imports and calls within the same second.

When sharing is the point

A mutable default is occasionally deliberate — a memo dictionary that must persist across calls. It works, but it is invisible to the reader. Prefer an explicit module-level variable or functools.cache, both of which say what they mean.

Part 6 · Other ways to capture

partial, factories, and which to prefer

A factory function

Give the value a scope of its own by passing it as a parameter to an outer function. The inner closure then captures that parameter, and each call to the factory creates a fresh one.

factory

def make_show(value):
    def show():
        return value       # captures the parameter, not the loop variable
    return show

fns = [make_show(i) for i in range(3)]
print([f() for f in fns])          # [0, 1, 2]

This is the version to reach for in library code: the signature of show stays clean, and the capture is explicit rather than a signature side effect.

`functools.partial`

partial

from functools import partial

def show(value):
    return value

fns = [partial(show, i) for i in range(3)]
print([f() for f in fns])          # [0, 1, 2]

partial binds arguments immediately and stores them on the resulting object, so there is no closure to go stale. It is the cleanest option when the function already exists and takes the value as a parameter.

Comparison

Technique	Good	Cost	Use when
`def f(x=x)`	One token; no restructuring	Adds a parameter callers can override	Local callbacks, quick lambdas
Factory function	Signature stays clean; intent explicit	An extra function	Library code, anything exported
`partial`	No new scope; composes well	Function must accept the value	The callable already exists
Bind to an instance attribute	Natural when state is already an object	A class	Several values travel together

Part 7 · Where it bites

Anything that defers the call

The pattern is always the same: a callable is created in a loop and invoked later. Threads make it vivid because the fix and the bug differ by six characters.

threads.py

import threading

results = []
threads = [
    threading.Thread(target=lambda: results.append(name))
    for name in ("a", "b", "c")
]
for t in threads: t.start()
for t in threads: t.join()
print("buggy:", sorted(results))

results = []
threads = [
    threading.Thread(target=lambda name=name: results.append(name))
    for name in ("a", "b", "c")
]
for t in threads: t.start()
for t in threads: t.join()
print("fixed:", sorted(results))

$ python threads.py

buggy: ['c', 'c', 'c']
fixed: ['a', 'b', 'c']

The same shape shows up in:

Event handlers. Buttons built in a loop that all act on the last item.
Async tasks. asyncio.create_task over a coroutine closing on a loop variable.
Handler dictionaries. {name: lambda: dispatch(name) for name in names} — the dict comprehension has its own scope, but the lambdas still close over its variable.
Retry and timing wrappers. A benchmark harness that builds one thunk per case and runs them afterwards ends up measuring the last case repeatedly.
Deferred logging. log.debug(lambda: f"{item}") style lazy messages.

The measurement version is the nastiest

When the deferred callables are benchmarks, nothing crashes and every number looks plausible — you simply publish the same case's timing under several names. There is no error to notice, only a conclusion that is wrong.

Part 8 · What the type hint does

The middle part, and when it runs

In kernel: Kernel = kernel, the annotation is the only part with no effect on behaviour. Python does not check it, coerce with it, or consult it when binding arguments. It is metadata for readers and for tools such as mypy or pyright.

But it is an expression, and by default it is evaluated at definition time:

annotations are evaluated eagerly

def side_effect():
    print("  (annotation evaluated)")
    return int

def g(a: side_effect() = 1):
    return a

print(g.__annotations__)

output

  (annotation evaluated)
{'a': <class 'int'>}

Add from __future__ import annotations and they are kept as strings instead, never evaluated unless something asks for them:

output with the future import

{'a': 'side_effect()'}          # note: no "(annotation evaluated)" line
(1,)                            # __defaults__ — still evaluated eagerly

Two things worth carrying away. First, deferring annotations lets you reference a class before it is defined, which is why the future import is common in typed code. Second, it changes nothing about defaults — those are always evaluated immediately, which is exactly what the capture idiom relies on.

Hints do not narrow the capture

Writing kernel: Kernel = kernel rather than kernel=kernel documents the parameter and gives a type checker something to verify. The value that gets captured, and when, is identical either way.

Part 9 · Scoping rules, briefly

LEGB, nonlocal, and comprehensions

Python resolves a name by searching four scopes in order:

Scope	Is
Local	Names assigned in the current function
Enclosing	Locals of any lexically enclosing function — this is where closures read from
Global	Module level
Built-in	`len`, `print`, and friends

Assigning to a name makes it local for the whole function, which is why reading it before the assignment raises rather than falling through to an outer scope. To assign to an outer name instead, declare the intent:

nonlocal vs global

count = 0

def outer():
    total = 0
    def bump():
        nonlocal total     # assign to outer()'s local
        global count       # assign to the module-level name
        total += 1
        count += 1
    bump(); bump()
    return total

print(outer(), count)      # 2 2

Comprehensions are the one construct that looks like a loop but is not: each has its own scope, so its variable does not leak. That is a small blessing and a common source of surprise:

comprehension scope

squares = [j * j for j in range(3)]
print(squares)             # [0, 1, 4]
print(j)                   # NameError: name 'j' is not defined

But it does not save you

The comprehension's variable is scoped, yet a lambda created inside still closes over it and still reads it late. [lambda: j for j in range(3)] gives three functions that all return 2. Scoping the variable is not the same as snapshotting it.

Part 10 · Letting a linter catch it

B023 and B008

You should not have to spot this by eye. flake8-bugbear and Ruff both ship the checks; enable them once and the class of bug stops reaching review.

Rule	Catches
`B023` function-uses-loop-variable	A function defined in a loop that references the loop variable — the bug in part 1
`B006` mutable-argument-default	`def f(x=[])` and friends — the trap in part 5
`B008` function-call-in-default-argument	`def f(when=datetime.now())` — a call evaluated once at import

pyproject.toml

[tool.ruff.lint]
extend-select = ["B"]      # all of flake8-bugbear, including B006/B008/B023

what it looks like

$ ruff check --select B023,B006,B008 --output-format concise .
b008.py:3:12: B008 Do not perform function call `datetime.now` in argument defaults;
              instead, perform the call within the function, or read the default from
              a module-level singleton variable
late.py:4:16: B023 Function definition does not bind loop variable `i`
mutable.py:1:29: B006 Do not use mutable data structures for argument defaults
Found 3 errors.

B008 has legitimate exceptions

Some frameworks make a call in the default meaningful — FastAPI's Depends() is the usual example. Ruff has extend-immutable-calls for exactly this; add the specific callable rather than switching the rule off.

Wrapping up

Cheat sheet

Expression	Evaluated	Consequence
Function body	On every call	Free variables are read late
Default argument	Once, at `def`	Snapshots values; shares mutables
Annotation	Once, at `def` — or never, with the future import	No runtime effect either way
Decorator	Once, at `def`	Wrapping happens at definition time

The short list

A closure captures the variable, not the value. If a function outlives the loop that made it, it will see the loop's final state.
def f(x=x) works because defaults are evaluated once, at definition. Left is a new local, right is the outer variable read right now. Same word, different things.
That same rule is the mutable-default trap. One [], created once, shared by every call. Use None and build inside.
Turn on bugbear (B) in Ruff. B023, B006 and B008 cover all three failure modes above, and none of them announce themselves at runtime.

pytest, from your first test to your own plugin

2026-07-28T07:01:40.443-07:00

Python · Testing

Most pytest tutorials stop right after assert 1 + 1 == 2, which is roughly where the interesting part begins. This one keeps going — through fixtures, parametrization and the configuration that makes a suite pleasant to live with, and out the other side into hooks and plugins.

There is a moment in most Python projects where the test suite stops helping. It takes four minutes to run, three tests fail intermittently, and nobody remembers what conftest.py is for. The tool is rarely the problem — pytest has an answer for each of those, and the answers are small.

So this is written as a path rather than a reference. Part 1 gets you productive with nothing but functions and assert. Parts 2 and 3 cover fixtures and parametrization, which is where pytest stops being "unittest with less typing" and starts being a different tool. Part 4 is the boring, high-leverage material: layout, configuration, mocking, CI. Part 5 opens the hood.

Every runnable snippet here was executed against pytest 9.1.1 before publishing, and the terminal output is copied from real runs. Anything version-sensitive is flagged inline.

Basics — why pytest, then the mechanics you use every day
Fixtures — the feature that makes pytest a different tool
Parametrizing — one function, many independently reported cases
Practical — the unglamorous, high-leverage material
Advanced — under the hood, and how to extend it
Reference — what to avoid, and a one-screen summary

Part 1 · Basics

Why pytest

Python ships with unittest, a port of Java's JUnit. It works, but it makes you inherit from a base class, remember a different assert method for every comparison, and wrap setup logic in setUp methods that run for every test whether you need them or not.

pytest replaces all of that with plain functions and the plain assert keyword.

unittest

import unittest

class TestMath(unittest.TestCase):
    def setUp(self):
        self.values = [1, 2, 3]

    def test_sum(self):
        self.assertEqual(sum(self.values), 6)

    def test_membership(self):
        self.assertIn(2, self.values)
        self.assertNotIn(9, self.values)

pytest

import pytest

@pytest.fixture
def values():
    return [1, 2, 3]

def test_sum(values):
    assert sum(values) == 6

def test_membership(values):
    assert 2 in values
    assert 9 not in values

The pytest version has no class, no inheritance, and no assertion vocabulary to memorise. It is also strictly more capable: values is a fixture, and unlike setUp it only runs for tests that actually ask for it.

pytest also runs unittest test cases as-is, so adopting it never requires a big-bang migration.

Your first test

install

python -m pip install pytest

Create two files side by side.

slugify.py

import re

def slugify(title: str) -> str:
    """Turn a human title into a URL-safe slug."""
    cleaned = re.sub(r"[^\w\s-]", "", title.lower())
    return re.sub(r"[\s_]+", "-", cleaned).strip("-")

test_slugify.py

from slugify import slugify

def test_lowercases_and_joins_words():
    assert slugify("Hello World") == "hello-world"

def test_strips_punctuation():
    assert slugify("What's new?!") == "whats-new"

def test_collapses_whitespace():
    assert slugify("too    many   spaces") == "too-many-spaces"

$ pytest -q

...                                                            [100%]
3 passed in 0.01s

Three dots, three passing tests. There is no registration step, no test suite object, no if __name__ == "__main__". pytest found the file, found the functions, and ran them.

Run it from the right place

pytest inserts the test file's directory (technically its rootdir for that file) into sys.path, which is why from slugify import slugify works here. For real projects use the layout in Project layout instead of relying on this.

How tests are found

Discovery is convention-driven. pytest walks the directories you give it (or the current one) and collects:

Level	Default rule	Config key
Files	`test_.py` or `_test.py`	`python_files`
Classes	`Test*`, and it must not define `__init__`	`python_classes`
Functions	`test*`, at module level or inside a collected class	`python_functions`

Ask pytest what it would run without running anything. This is the single most useful command when a test "isn't running":

dry run

pytest --collect-only -q

Common trap

A test class with an __init__ method is silently skipped — pytest cannot instantiate it, so it warns and moves on. If a whole class mysteriously vanishes, that is almost always why.

The assert statement

pytest rewrites the bytecode of your test modules at import time so that a failing assert reports the value of every subexpression. You get JUnit-grade diagnostics from the plain keyword.

test_report.py

def build_report():
    return {"rows": 41, "status": "ok", "tags": ["a", "b"]}

def test_report_shape():
    report = build_report()
    assert report == {"rows": 42, "status": "ok", "tags": ["a", "c"]}

$ pytest -q

    def test_report_shape():
        report = build_report()
>       assert report == {"rows": 42, "status": "ok", "tags": ["a", "c"]}
E       AssertionError: assert {'rows': 41, ...': ['a', 'b']} == {'rows': 42, ...': ['a', 'c']}
E
E         Omitting 1 identical items, use -vv to show
E         Differing items:
E         {'rows': 41} != {'rows': 42}
E         {'tags': ['a', 'b']} != {'tags': ['a', 'c']}
E         Use -v to get more diff

test_report.py:6: AssertionError
1 failed in 0.02s

pytest knows how to diff dicts, lists, sets, strings and dataclasses. Add -vv when the diff is truncated — it disables the shortening.

Add a message only when it adds information

assert x == y, "x should equal y" is noise; the rewriting already showed you that. A good message supplies context the values cannot: assert resp.ok, f"upstream said {resp.text}".

Exceptions and warnings

Use pytest.raises as a context manager. The test fails if the block does not raise.

test_errors.py

import pytest

def withdraw(balance, amount):
    if amount <= 0:
        raise ValueError(f"amount must be positive, got {amount}")
    if amount > balance:
        raise ValueError("insufficient funds")
    return balance - amount

def test_rejects_negative_amount():
    with pytest.raises(ValueError):
        withdraw(100, -5)

def test_error_message_names_the_amount():
    # match= is a regex applied with re.search against str(exception)
    with pytest.raises(ValueError, match=r"must be positive, got -5"):
        withdraw(100, -5)

def test_inspect_the_exception_object():
    with pytest.raises(ValueError) as excinfo:
        withdraw(100, 500)
    assert "insufficient" in str(excinfo.value)
    assert excinfo.type is ValueError

Assert after the block, not inside it

Code placed after the raising line inside a with pytest.raises(...) block never executes. Anything you want to check about the exception goes after the block using excinfo.value.

Warnings have a mirror-image API:

warnings

import warnings, pytest

def legacy_api():
    warnings.warn("use new_api() instead", DeprecationWarning, stacklevel=2)
    return 42

def test_warns():
    with pytest.warns(DeprecationWarning, match="new_api"):
        assert legacy_api() == 42

Comparing floats

0.1 + 0.2 == 0.3 is False in binary floating point. pytest.approx wraps a value with a tolerance and works on scalars, sequences, dicts and numpy arrays.

approx

from pytest import approx

def test_scalar():
    assert 0.1 + 0.2 == approx(0.3)

def test_explicit_tolerance():
    assert 4.7 == approx(4.7005, abs=1e-3)     # absolute
    assert 1_000_100 == approx(1_000_000, rel=1e-3)  # relative

def test_containers():
    assert [0.1 + 0.2, 1 / 3] == approx([0.3, 0.33333333])
    assert {"loss": 0.1 + 0.2} == approx({"loss": 0.3})

The default is a relative tolerance of 1e-6 with a small absolute floor, which is the right default for most numeric code. Say what you mean when precision actually matters.

Running and selecting tests

Command	What it does
`pytest`	Everything under the current directory
`pytest tests/unit`	One directory
`pytest tests/test_api.py`	One file
`pytest tests/test_api.py::test_login`	One test — this is a node id
`pytest "tests/test_api.py::test_login[admin]"`	One parametrized case
`pytest -k "login and not slow"`	Substring/boolean match on names
`pytest -m integration`	Match a marker
`pytest -x`	Stop at the first failure
`pytest --maxfail=3`	Stop after three failures
`pytest -q` / `-v` / `-vv`	Quieter / one line per test / no truncated diffs
`pytest -rA`	Summary lines for every outcome, including passes
`pytest -s`	Don't capture stdout (see your `print` calls live)
`pytest --lf`	Only the tests that failed last run
`pytest --ff`	Everything, but last run's failures first
`pytest --sw`	Stepwise: stop at a failure, resume there next time

Node ids are copy-pasteable. When a test fails, the id in the output is exactly the argument you need to re-run just that case.

Part 2 · Fixtures

Fixture basics

A fixture is a function that produces something a test needs. Tests request fixtures by naming them as parameters, and pytest supplies them. That is the entire mental model — it is dependency injection with a decorator.

request by name

import pytest

@pytest.fixture
def inventory():
    return {"apple": 3, "pear": 0}

def test_has_apples(inventory):        # ← the parameter name is the fixture name
    assert inventory["apple"] == 3

def test_pears_are_out_of_stock(inventory):
    assert inventory["pear"] == 0

Each test gets a fresh inventory by default, so one test mutating the dict cannot affect another. That isolation is the reason fixtures beat module-level constants.

Fixtures can request other fixtures, forming a graph that pytest resolves for you:

composition

@pytest.fixture
def config():
    return {"currency": "EUR", "vat": 0.21}

@pytest.fixture
def cart(config):                       # fixtures compose
    return {"config": config, "items": []}

def test_cart_uses_config(cart):
    assert cart["config"]["vat"] == 0.21

Setup and teardown

Replace return with yield and everything after the yield becomes teardown. It runs even if the test fails, because pytest wraps it in a finalizer.

yield fixture

import sqlite3
import pytest

@pytest.fixture
def db():
    conn = sqlite3.connect(":memory:")
    conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
    yield conn                          # ← the test runs here
    conn.close()                        # ← always runs afterwards

def test_insert_and_read_back(db):
    db.execute("INSERT INTO users (name) VALUES (?)", ("ada",))
    assert db.execute("SELECT name FROM users").fetchone() == ("ada",)

Setup failures are errors, not failures

If the code before yield raises, pytest reports the test as an error rather than a failure, and the test body never runs. That distinction in the summary line tells you instantly whether your production code or your scaffolding broke.

Scopes

Expensive setup should not repeat per test. scope controls how long one instance is cached and shared.

Scope	Created once per	Typical use
`function` default	Test	Anything mutable
`class`	Test class	Shared object for a group of methods
`module`	File	A parsed file, a compiled artifact
`package`	Directory	Rare; a shared subsystem
`session`	Whole run	Docker container, server process, big download

session scope

@pytest.fixture(scope="session")
def http_server():
    proc = start_server()               # slow: do it once for the whole run
    yield proc
    proc.terminate()

@pytest.fixture
def client(http_server):                # cheap per-test wrapper over the shared server
    return Client(http_server.url)

The scope rule you will hit eventually

A fixture may only depend on fixtures of equal or wider scope. A session fixture requesting a function fixture is an error, because the narrow one would be destroyed while the wide one still holds it.

And never let a widely scoped fixture hand out something mutable. One test appending to a session-scoped list poisons every later test, producing failures that depend on run order.

conftest.py

Fixtures defined in conftest.py are visible to every test in that directory and below, with no import needed. Nested conftest.py files stack, and the closest definition wins.

tree

tests/
├── conftest.py            # fixtures for everything below
├── unit/
│   └── test_parser.py
└── integration/
    ├── conftest.py        # extra fixtures, only for integration tests
    └── test_api.py

tests/conftest.py

import pytest

@pytest.fixture(scope="session")
def sample_data():
    return {"users": ["ada", "grace"], "version": 3}

@pytest.fixture
def frozen_clock(monkeypatch):
    """Pin time.time() so timestamp assertions are deterministic."""
    import time
    monkeypatch.setattr(time, "time", lambda: 1_700_000_000.0)
    return 1_700_000_000.0

conftest.py is more than a fixture bucket

It is also where hooks, custom CLI options and plugin registration live. pytest imports it automatically — it must never be imported by hand, and it needs no __init__.py.

Where does a fixture come from? Ask:

list available fixtures

pytest --fixtures            # every fixture visible here, with docstrings
pytest --fixtures-per-test tests/test_api.py::test_login

Built-in fixtures

These ship with pytest. Reach for them before writing your own.

`tmp_path` — a real, empty directory per test

tmp_path

def test_writes_a_csv(tmp_path):
    target = tmp_path / "out.csv"       # tmp_path is a pathlib.Path
    target.write_text("id,name\n1,ada\n")

    assert target.exists()
    assert target.read_text().splitlines()[0] == "id,name"

pytest keeps the last few runs' directories on disk for post-mortem inspection and cleans up older ones. Use tmp_path_factory for a directory shared across a session.

`monkeypatch` — scoped, auto-undone patching

monkeypatch

def test_reads_token_from_environment(monkeypatch):
    monkeypatch.setenv("API_TOKEN", "secret")
    monkeypatch.delenv("HTTP_PROXY", raising=False)
    assert load_config().token == "secret"

def test_patch_an_attribute(monkeypatch):
    monkeypatch.setattr("myapp.net.fetch", lambda url: {"ok": True})
    assert myapp.summarize("http://x") == "ok"

def test_run_from_another_directory(monkeypatch, tmp_path):
    monkeypatch.chdir(tmp_path)         # undone automatically
    assert Path.cwd() == tmp_path

Every change is reverted when the test ends, including failures. That is the whole point: hand-rolled os.environ[...] = ... leaks into subsequent tests.

`capsys` and `caplog` — captured output

capsys / caplog

import logging

def test_prints_a_banner(capsys):
    print("READY")
    captured = capsys.readouterr()      # consumes the buffer
    assert captured.out == "READY\n"
    assert captured.err == ""

def test_logs_a_warning(caplog):
    with caplog.at_level(logging.WARNING):
        logging.getLogger("app").warning("disk almost full")
    assert "disk almost full" in caplog.text
    assert caplog.records[0].levelno == logging.WARNING

Use capfd instead of capsys when the output comes from a subprocess or a C extension.

`request` — introspection

request

@pytest.fixture
def workspace(request, tmp_path):
    """Name the directory after the test that asked for it."""
    d = tmp_path / request.node.name
    d.mkdir()
    return d

Factory fixtures

When a test needs several of a thing, or needs to choose parameters, return a function instead of a value. Track what you create so teardown stays correct.

factory-as-fixture

import pytest

@pytest.fixture
def make_user(db):
    created = []

    def _make(name, admin=False):
        cur = db.execute(
            "INSERT INTO users (name, admin) VALUES (?, ?)", (name, admin)
        )
        created.append(cur.lastrowid)
        return {"id": cur.lastrowid, "name": name, "admin": admin}

    yield _make

    for user_id in created:             # clean up exactly what this test made
        db.execute("DELETE FROM users WHERE id = ?", (user_id,))

def test_admins_can_see_everyone(make_user):
    admin = make_user("ada", admin=True)
    make_user("grace")
    make_user("alan")
    assert len(visible_users(admin)) == 3

Part 3 · Parametrizing

parametrize

One test function, many cases. Each case is a separate test: it gets its own node id, its own pass/fail, and one failing case does not hide the others.

basic

import pytest

@pytest.mark.parametrize(
    ("title", "expected"),
    [
        ("Hello World", "hello-world"),
        ("What's new?!", "whats-new"),
        ("  padded  ", "padded"),
        ("", ""),
    ],
)
def test_slugify(title, expected):
    assert slugify(title) == expected

$ pytest -v

test_slug.py::test_slugify[Hello World-hello-world] PASSED
test_slug.py::test_slugify[What's new?!-whats-new]   PASSED
test_slug.py::test_slugify[  padded  -padded]        PASSED
test_slug.py::test_slugify[-]                        PASSED

Stacking decorators produces the cartesian product:

3 × 2 = 6 tests

@pytest.mark.parametrize("codec", ["gzip", "zstd", "none"])
@pytest.mark.parametrize("size", [0, 1_000_000])
def test_roundtrip(codec, size):
    payload = b"x" * size
    assert decompress(compress(payload, codec), codec) == payload

Combinatorics grow fast

Stacking is convenient and dangerous. Three stacked decorators of five values each is 125 tests. Prefer an explicit list of meaningful tuples once the product stops being all-interesting.

Readable IDs

Auto-generated ids come from the values, which is unreadable for objects and awkward for long strings. Name your cases — the id is what you will read in CI output and paste on the command line.

ids=

@pytest.mark.parametrize(
    ("payload", "expected"),
    [
        ({"v": 1}, True),
        ({"v": 1, "extra": None}, True),
        ({}, False),
    ],
    ids=["minimal", "with-nulls", "empty"],
)
def test_validate(payload, expected):
    assert validate(payload) is expected

A dict keeps the name and the data in one place, which stops them drifting apart:

dict-driven cases

CASES = {
    "empty-input":     ("",        []),
    "single-token":    ("a",       ["a"]),
    "trailing-comma":  ("a,b,",    ["a", "b"]),
    "quoted-comma":    ('"a,b",c', ["a,b", "c"]),
}

@pytest.mark.parametrize(
    ("raw", "expected"), list(CASES.values()), ids=list(CASES.keys())
)
def test_parse_csv_line(raw, expected):
    assert parse_csv_line(raw) == expected

Per-case marks

pytest.param attaches a mark or an id to a single case, so one known-broken input does not force you to skip the whole function.

pytest.param

@pytest.mark.parametrize(
    ("raw", "expected"),
    [
        ("2024-01-01", date(2024, 1, 1)),
        pytest.param("01/01/2024", date(2024, 1, 1), id="us-format"),
        pytest.param(
            "2024-W01-1", date(2024, 1, 1),
            marks=pytest.mark.xfail(reason="ISO week dates not supported yet"),
        ),
        pytest.param(
            "yesterday", date(2024, 1, 1),
            marks=pytest.mark.skipif(sys.platform == "win32", reason="needs GNU date"),
        ),
    ],
)
def test_parse_date(raw, expected):
    assert parse_date(raw) == expected

Parametrized fixtures

Put params on the fixture and every test using it runs once per value. This is how you sweep a whole suite across backends without touching a single test body.

fixture params

@pytest.fixture(params=["sqlite", "postgres"], ids=["sqlite", "pg"])
def store(request):
    backend = request.param             # ← the current value
    s = open_store(backend)
    yield s
    s.close()

# both of these now run twice, once per backend
def test_put_then_get(store):
    store.put("k", "v")
    assert store.get("k") == "v"

def test_missing_key_returns_none(store):
    assert store.get("nope") is None

Indirect parametrization

indirect=True routes the parameter through a fixture rather than into the test. Use it when the value needs setup before the test can see it.

indirect

@pytest.fixture
def user(request):
    role = request.param                # comes from parametrize, not from the test
    return create_user(role=role)

@pytest.mark.parametrize("user", ["admin", "viewer"], indirect=True)
def test_dashboard_access(user):
    assert user.can_open_dashboard() is (user.role == "admin")

Mix direct and indirect by naming which arguments are indirect:

partial indirect

@pytest.mark.parametrize(
    ("user", "expected"),
    [("admin", True), ("viewer", False)],
    indirect=["user"],                  # only `user` goes through the fixture
)
def test_dashboard_access(user, expected):
    assert user.can_open_dashboard() is expected

Part 4 · Practical

Project layout

The src layout is the one that avoids import surprises: your package is not importable from the repository root, so tests are forced to import the installed package — the same thing your users get.

recommended

myproject/
├── pyproject.toml
├── src/
│   └── myproject/
│       ├── __init__.py
│       └── core.py
└── tests/
    ├── conftest.py
    ├── unit/
    │   └── test_core.py
    └── integration/
        └── test_end_to_end.py

install once, then test

python -m pip install -e ".[dev]"
pytest

Do not put __init__.py in tests/

Without it, test modules are imported as top-level modules — which means two files named test_utils.py in different directories will collide. Either give them distinct names, or add __init__.py files and accept package semantics. The distinct-names route is simpler.

Configuration

One config block removes a lot of repeated typing and makes local runs match CI. pyproject.toml is the modern home; pytest.ini and setup.cfg still work.

pyproject.toml

[tool.pytest.ini_options]
minversion = "8.0"
testpaths = ["tests"]
addopts = [
    "-ra",                 # summary for all non-passing outcomes
    "--strict-markers",    # unknown @pytest.mark.* becomes an error
    "--strict-config",     # typos in this very section become an error
    "--import-mode=importlib",
]
markers = [
    "slow: takes more than a second",
    "integration: needs external services",
]
filterwarnings = [
    "error",                                   # warnings fail the suite ...
    "ignore::DeprecationWarning:third_party.*" # ... except from code you don't own
]

Option	Why you want it
`--strict-markers`	A typo like `@pytest.mark.slwo` silently does nothing otherwise
`filterwarnings = ["error"]`	Catches deprecations while they are cheap to fix
`testpaths`	Bare `pytest` stops walking `.venv`, `build`, docs
`--import-mode=importlib`	Modern import semantics; avoids `sys.path` surgery

Markers, skip and xfail

Markers are labels. You attach them to tests and select on them later.

marking

import pytest

@pytest.mark.slow
def test_full_reindex():
    ...

@pytest.mark.integration
class TestPaymentGateway:          # applies to every method in the class
    def test_charge(self): ...
    def test_refund(self): ...

pytestmark = pytest.mark.integration   # module-level: applies to the whole file

selecting

pytest -m slow                  # only slow
pytest -m "not slow"            # everything else
pytest -m "integration and not slow"

skip vs xfail

Construct	Meaning	When
`@pytest.mark.skip(reason=…)`	Never run it	Temporarily irrelevant
`@pytest.mark.skipif(cond, reason=…)`	Run only if the condition is false	Platform / version / optional dependency
`pytest.skip(reason)`	Skip from inside the test	Decision needs runtime information
`pytest.importorskip("numpy")`	Skip if the import fails	Optional dependency
`@pytest.mark.xfail(reason=…)`	Run it; a failure is expected	Known bug, with a test that proves it

the useful forms

import sys, pytest

@pytest.mark.skipif(sys.version_info < (3, 12), reason="uses PEP 695 syntax")
def test_new_generics(): ...

def test_needs_a_gpu():
    if not gpu_present():
        pytest.skip("no GPU on this runner")
    ...

pandas = pytest.importorskip("pandas", minversion="2.0")

@pytest.mark.xfail(strict=True, reason="bug #482: rounds half-down")
def test_rounds_half_up():
    assert round_half_up(0.5) == 1

Prefer xfail(strict=True) over skip for known bugs

A strict xfail that starts passing becomes a failure. That is the feature: the day someone fixes the bug, the suite tells you to delete the marker. A skipped test just rots.

Mocking

Two tools, two jobs. monkeypatch replaces an attribute for the duration of a test. unittest.mock additionally records how the replacement was used.

monkeypatch: substitute behaviour

def test_retries_on_timeout(monkeypatch):
    calls = []

    def flaky_get(url):
        calls.append(url)
        if len(calls) < 3:
            raise TimeoutError
        return {"status": "ok"}

    monkeypatch.setattr("myapp.client.get", flaky_get)
    assert fetch_with_retry("http://x")["status"] == "ok"
    assert len(calls) == 3

mock: assert on the interaction

from unittest.mock import patch, MagicMock

def test_sends_exactly_one_email():
    with patch("myapp.mailer.send") as send:
        send.return_value = MagicMock(status=202)
        register_user("ada@example.com")

    send.assert_called_once_with(
        to="ada@example.com", template="welcome"
    )

Patch where it is looked up

If myapp/service.py does from myapp.mailer import send, then patching "myapp.mailer.send" has no effect — service already holds its own reference. Patch "myapp.service.send", the name in the module using it.

Mocking is a smell in proportion to its depth

Mocking a network boundary is good. Mocking five internal collaborators means the test now asserts your implementation's shape rather than its behaviour, and it will break on every refactor while catching no bugs. Consider a fake object or a real in-memory implementation instead.

Output and logging

pytest captures stdout, stderr and logging, then prints them only for failing tests. That is why your print statements seem to vanish on success.

Flag	Effect
`-s`	Disable capture entirely — output streams live
`--capture=no`	Same as `-s`
`--log-cli-level=DEBUG`	Stream log records to the terminal as they happen
`--show-capture=no`	Hide captured output even on failures

Coverage

pytest-cov

python -m pip install pytest-cov

pytest --cov=myproject --cov-report=term-missing
pytest --cov=myproject --cov-report=html      # then open htmlcov/index.html
pytest --cov=myproject --cov-fail-under=85    # gate in CI

Coverage measures execution, not verification

A test that calls a function and asserts nothing still counts as full coverage of it. Treat the number as a way to find untested code, never as evidence that tested code is correct. Branch coverage (--cov-branch) is a strictly better signal than line coverage.

Speed

find and fix slowness

pytest --durations=10          # the 10 slowest tests, with setup/teardown split out

python -m pip install pytest-xdist
pytest -n auto                 # one worker per CPU
pytest -n 4 --dist loadfile    # keep each file on a single worker

Parallelism exposes hidden coupling: tests that only pass in a particular order will start failing. That is a bug being surfaced, not a bug being introduced.

Debugging a failure

the loop

pytest -x -q                   # 1. stop at the first failure
pytest --lf -x                 # 2. iterate on just that one
pytest --lf -x --pdb           # 3. drop into a debugger at the failure point
pytest --lf -x -vv --tb=long   # 4. full diffs and full traceback
pytest -q                      # 5. confirm the whole suite is green again

Flag	Traceback style
`--tb=long`	Every frame, fully expanded default
`--tb=short`	One line per frame — best for CI logs
`--tb=line`	One line per failure
`--tb=no`	Names only

breakpoint() works inside tests as long as capture is off (-s), and --pdb opens a debugger at the moment of failure with the whole frame still alive — usually faster than guessing where to put the breakpoint.

CI recipe

GitHub Actions

name: tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
      - run: python -m pip install -e ".[dev]"
      - run: pytest -ra --tb=short --durations=10 --cov --cov-report=xml -n auto

fail-fast: false matters: without it, one failing Python version cancels the others and hides whether the problem is version-specific.

Part 5 · Advanced

Hooks

pytest is a plugin system with a test runner attached. Every phase — collection, setup, running, reporting — publishes hooks, and conftest.py is a plugin that is loaded automatically. Implement a hook by defining a function with the right name.

conftest.py — auto-mark by location

def pytest_collection_modifyitems(config, items):
    """Everything under tests/integration/ gets @pytest.mark.integration."""
    import pytest
    for item in items:
        if "/integration/" in str(item.path):
            item.add_marker(pytest.mark.integration)

conftest.py — expose the outcome to fixtures

import pytest

@pytest.hookimpl(hookwrapper=True)
def pytest_runtest_makereport(item, call):
    outcome = yield
    report = outcome.get_result()
    # stash "rep_setup" / "rep_call" / "rep_teardown" on the test item
    setattr(item, f"rep_{report.when}", report)

@pytest.fixture
def browser(request):
    driver = start_browser()
    yield driver
    if getattr(request.node, "rep_call", None) and request.node.rep_call.failed:
        driver.save_screenshot(f"/tmp/{request.node.name}.png")
    driver.quit()

That pattern — capture an artifact only when the test failed — is the standard answer for browser screenshots, server logs and database dumps.

Hook	Fires
`pytest_addoption`	Once at startup, to register CLI flags
`pytest_configure`	After config is read; register markers here
`pytest_collection_modifyitems`	After collection — reorder, filter, mark
`pytest_generate_tests`	Per test function, to generate parameters
`pytest_runtest_setup`	Before each test
`pytest_runtest_makereport`	After each phase, with the result
`pytest_sessionfinish`	Once, at the very end

Custom CLI options

conftest.py

import pytest

def pytest_addoption(parser):
    parser.addoption(
        "--runslow", action="store_true", default=False,
        help="run tests marked slow",
    )
    parser.addoption(
        "--env", action="store", default="staging",
        choices=("staging", "prod"), help="target environment",
    )

def pytest_configure(config):
    config.addinivalue_line("markers", "slow: takes more than a second")

def pytest_collection_modifyitems(config, items):
    if config.getoption("--runslow"):
        return
    skip = pytest.mark.skip(reason="needs --runslow")
    for item in items:
        if "slow" in item.keywords:
            item.add_marker(skip)

@pytest.fixture(scope="session")
def env(request):
    return request.config.getoption("--env")

usage

pytest                      # slow tests are skipped
pytest --runslow            # everything
pytest --env prod

pytest_generate_tests

When the set of cases is only known at runtime — read from a directory, a manifest, a database — generate them in this hook. Each generated case is still a first-class test.

golden files as test cases

# conftest.py
from pathlib import Path

CASES = Path(__file__).parent / "cases"

def pytest_generate_tests(metafunc):
    if "case_file" in metafunc.fixturenames:
        files = sorted(CASES.glob("*.input"))
        metafunc.parametrize(
            "case_file", files, ids=[f.stem for f in files]
        )

# test_render.py
def test_render_matches_golden(case_file):
    expected = case_file.with_suffix(".expected").read_text()
    assert render(case_file.read_text()) == expected

Dropping a new pair of files into cases/ adds a test. No code change, and the id is the file name so failures point straight at the data.

Writing a plugin

A plugin is a module of hooks and fixtures. Once it lives in a package with the pytest11 entry point, installing the package is enough — no imports, no conftest.py.

pytest_timer/plugin.py

import time
import pytest

@pytest.fixture
def timer():
    """Yield an object whose .elapsed is the time spent inside the block."""
    class _Timer:
        start = time.perf_counter()
        @property
        def elapsed(self):
            return time.perf_counter() - self.start
    return _Timer()

def pytest_addoption(parser):
    parser.addoption("--warn-slower-than", type=float, default=None)

@pytest.hookimpl(hookwrapper=True)
def pytest_runtest_call(item):
    started = time.perf_counter()
    yield
    limit = item.config.getoption("--warn-slower-than")
    took = time.perf_counter() - started
    if limit is not None and took > limit:
        item.warn(pytest.PytestWarning(f"{item.name} took {took:.2f}s"))

pyproject.toml

[project.entry-points.pytest11]
timer = "pytest_timer.plugin"

Test your plugin with pytest's own pytester fixture, which runs a nested pytest session in a temporary directory:

pytester

pytest_plugins = ["pytester"]

def test_warns_about_slow_tests(pytester):
    pytester.makepyfile("""
        import time
        def test_slow():
            time.sleep(0.05)
    """)
    result = pytester.runpytest("--warn-slower-than=0.01")
    result.assert_outcomes(passed=1, warnings=1)

Custom assertion helpers

Shared assertion functions clutter tracebacks with frames nobody cares about. Set __tracebackhide__ and the failure points at the caller instead.

__tracebackhide__

import pytest

def assert_valid_invoice(invoice):
    __tracebackhide__ = True            # hide this frame in the report
    if invoice.total < 0:
        pytest.fail(f"negative total: {invoice.total}")
    if invoice.lines and invoice.total != sum(l.amount for l in invoice.lines):
        pytest.fail(
            f"total {invoice.total} != sum of lines "
            f"{sum(l.amount for l in invoice.lines)}"
        )

def test_generated_invoice(order):
    assert_valid_invoice(build_invoice(order))   # ← failure is reported here

To keep pytest's value-introspection inside a helper module, register it for rewriting before it is imported:

conftest.py

import pytest
pytest.register_assert_rewrite("mypackage.testing.helpers")

Why plain `assert` works

Python's assert throws away everything but the boolean. pytest installs an import hook that rewrites the AST of test modules before they are compiled, replacing each assert with code that stores intermediate values and builds an explanation on failure.

conceptually

# what you write
assert compute(x) == expected

# roughly what gets compiled
@py_left  = compute(x)
@py_right = expected
if not (@py_left == @py_right):
    raise AssertionError(explain("==", @py_left, @py_right))

Three consequences worth knowing:

Rewriting applies to test modules, conftest.py, and modules you explicitly register. A plain library module keeps bare AssertionErrors with no detail.
Running Python with -O strips assert statements entirely, so never run a suite optimised.
Stale __pycache__ from a non-pytest run can shadow rewritten bytecode; pytest --cache-clear or deleting the caches fixes the "my assertions lost their detail" mystery.

Async tests

pytest cannot await a coroutine on its own — an async def test without a plugin is skipped with a warning, which looks like a pass in a hurry. Install one of the two plugins.

pytest-asyncio

# pyproject.toml
# [tool.pytest.ini_options]
# asyncio_mode = "auto"        # no per-test marker needed

import asyncio, pytest

@pytest.fixture
async def client():
    c = await open_client()
    yield c
    await c.aclose()

async def test_fetches_concurrently(client):
    a, b = await asyncio.gather(client.get("/a"), client.get("/b"))
    assert a.status == b.status == 200

anyio is the alternative when you need the same tests to run on both asyncio and trio.

Property-based testing

Instead of listing examples, describe the shape of valid input and assert a property that must hold for all of them. Hypothesis generates cases, and on failure shrinks them to the smallest reproducer.

hypothesis

from hypothesis import given, strategies as st

@given(st.text())
def test_slugify_is_idempotent(s):
    once = slugify(s)
    assert slugify(once) == once

@given(st.lists(st.integers()))
def test_sort_is_a_permutation(xs):
    out = my_sort(xs)
    assert len(out) == len(xs)
    assert sorted(out) == sorted(xs)
    assert all(a <= b for a, b in zip(out, out[1:]))

It composes with pytest normally — @given functions are collected like any other test. Good properties are round-trips (decode(encode(x)) == x), invariants (length, ordering) and equivalence to a slow reference implementation.

Don't mix @given with function-scoped fixtures

Hypothesis calls the test body many times, but a function-scoped fixture is created once for the whole thing. Shared mutable state leaks between generated examples. Build what you need inside the test, or use a factory fixture.

Flaky tests and isolation

A flaky test is worse than no test: it trains people to re-run CI instead of reading it. The usual causes are few, and each has a direct fix.

Cause	Fix
Shared mutable state across tests	Narrow the fixture scope; return copies
Order dependence	`pytest -p no:randomly` to confirm, then fix the coupling
Real clock / real timezone	Freeze time (`monkeypatch`, `freezegun`, `time-machine`)
Unseeded randomness	Seed it, and log the seed
`sleep()`-based waiting	Poll for the condition with a timeout
Dict/set iteration order assumptions	Compare sets, or sort before comparing
Leftover files or env vars	`tmp_path` and `monkeypatch`, never manual mutation

prove isolation

python -m pip install pytest-randomly
pytest                       # shuffles order every run, prints the seed
pytest -p no:randomly        # reproduce the deterministic order
pytest -p randomly --randomly-seed=12345   # reproduce a specific shuffle

Retry plugins are anaesthetic, not treatment

pytest-rerunfailures can keep a pipeline moving, but a test that passes on the second attempt is telling you something real about your system. Retry only at genuinely non-deterministic boundaries (a live network), and never on unit tests.

Reference

Anti-patterns

Logic in the test

A test with branching needs its own tests. Split it into parametrized cases so each path is visible in the report.

avoid

def test_prices():
    for currency in ("EUR", "USD"):
        if currency == "EUR":
            assert fmt(1, currency) == "1,00 €"
        else:
            assert fmt(1, currency) == "$1.00"

prefer

@pytest.mark.parametrize(
    ("currency", "expected"),
    [("EUR", "1,00 €"), ("USD", "$1.00")],
)
def test_prices(currency, expected):
    assert fmt(1, currency) == expected

Asserting the implementation

mock.assert_called_once_with(...) on an internal helper locks in today's call graph. Rename the helper and the test fails while the behaviour is unchanged. Assert on the observable result instead.

One test, many concerns

When a 40-line test fails you learn "something in registration is broken". Several focused tests tell you which part, and the names double as documentation.

Depending on execution order

A test that only passes after another one ran is not a test, it is half of one. Each test must set up everything it needs.

Sleeping

avoid

start_worker()
time.sleep(2)          # slow AND flaky
assert job_done()

prefer

def wait_until(pred, timeout=5, interval=0.05):
    __tracebackhide__ = True
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        if pred():
            return
        time.sleep(interval)
    pytest.fail(f"condition not met in {timeout}s")

start_worker()
wait_until(job_done)

Cheat sheet

Command line

`pytest path::test_name`	Run one test
`-k "expr"` / `-m "expr"`	Select by name / by marker
`-x` / `--maxfail=N`	Stop early
`--lf` / `--ff` / `--sw`	Last-failed / failures-first / stepwise
`-q` / `-v` / `-vv` / `-ra`	Verbosity and outcome summary
`-s`	Show output live
`--pdb`	Debugger at the failure
`--tb=short`	Compact tracebacks
`--collect-only`	List tests without running
`--fixtures`	List available fixtures
`--durations=10`	Slowest tests
`-n auto`	Parallel (xdist)
`-W error`	Turn warnings into failures

API

`pytest.fixture(scope=, params=, autouse=, ids=)`	Define a fixture
`pytest.mark.parametrize(argnames, argvalues, ids=, indirect=)`	Generate cases
`pytest.param(*values, id=, marks=)`	One case with metadata
`pytest.raises(Exc, match=)`	Expect an exception
`pytest.warns(W, match=)`	Expect a warning
`pytest.approx(value, rel=, abs=)`	Float comparison
`pytest.skip(reason)` / `pytest.fail(msg)`	Skip / fail imperatively
`pytest.importorskip(name, minversion=)`	Optional dependency
`pytest.register_assert_rewrite(module)`	Rewrite asserts in a helper module

Built-in fixtures

`tmp_path`, `tmp_path_factory`	Temporary directories
`monkeypatch`	Patch attributes, env vars, cwd — auto-undone
`capsys`, `capfd`	Captured stdout/stderr (Python level / fd level)
`caplog`	Captured log records
`request`	Test metadata, `request.param`, config access
`pytester`	Run a nested pytest — for testing plugins
`recwarn`	Record all warnings raised

Wrapping up

What actually moves the needle

Reading a tool's full feature list rarely changes how anyone works. If you adopt three things from this post, make them these.

The short list

Turn on --strict-markers and filterwarnings = ["error"]. Two lines of config that convert a class of silent failures into loud ones, today, in an existing project.
Replace your ad-hoc setup with fixtures, and keep them function-scoped until proven slow. Almost every order-dependent flake traces back to state shared more widely than it needed to be.
Reach for parametrize the moment a test grows a loop or an if. Each case gets its own name and its own verdict, which is the difference between "billing is broken" and "billing is broken for zero-quantity line items".

The advanced material matters less often, but it is worth knowing it exists. The day you find yourself copying the same conftest.py into a fourth repository, that is the signal to turn it into a plugin — and by then the entry point is a two-line change.

Understanding Python variable type hints (Dict, dict, and mypy)

2026-07-13T01:17:52.686-07:00

When you read Python code, sooner or later you hit a line like this:

data: Dict[str, int] = {}

The : Dict[str, int] part looks strange the first time. In this post we'll figure out exactly what that one line means — and whether a "type hint" is actually enforced — using tiny runnable examples.

1. One line, three things at once

That single line is really three pieces glued together.

data  :  Dict[str, int]  =  {}
 │            │              │
name       type hint       actual
            (a note)        value

Piece	Meaning
`data`	the variable name
`: Dict[str, int]`	a type hint — "keys are str, values are int". Just a note for humans/editors
`= {}`	the actual value = an empty dict

At runtime it is exactly the same as:

data = {}   # drop the hint and this is all that's left

2. `= {}` is just a dict

A dict is a "key → value" store. It has nothing to do with type hints — it's a basic built-in type that has always existed.

data = {}                 # empty dict
data["gemm"]   = "A"      # key (str) -> value
data["conv2d"] = "B"
print(data)               # {'gemm': 'A', 'conv2d': 'B'}
print(data["gemm"])       # A
print(list(data))         # ['gemm', 'conv2d']

3. `: Dict[str, int]` is a "type hint"

Dict[str, int] is a note saying "a dict whose keys are strings and values are integers". Python does not enforce that note when it runs.

from typing import Dict

ages: Dict[str, int] = {}   # at runtime this is just ages = {}
ages["alice"] = 30
ages["bob"]   = 25
print(ages)                 # {'alice': 30, 'bob': 25}

4. Is it really not enforced? — break it on purpose

Violating the hint does not raise an error. Let's prove it.

from typing import Dict

ages: Dict[str, int] = {}   # promise: "str keys, int values"
ages["alice"] = 30          # keeps the promise
ages["oops"]  = "not-int"   # value is a string -> breaks it
ages[123]     = 99          # key is an int      -> breaks it
print(ages)

Output:

{'alice': 30, 'oops': 'not-int', 123: 99}

Key point: a type hint is not enforced. The Python interpreter simply ignores it at runtime, so breaking it still runs fine.

5. So why write hints at all?

If they're not enforced, why bother? Because they're a "quality tool", not a rule.

Humans — reading the code, you instantly see "this is a str→int dict".
Editors (IDEs) — autocomplete, and a red squiggle when you misuse it.
Static checkers (mypy) — run mypy file.py separately and it catches violations before you run the code.

A hint is "a promise + documentation", not a check. To actually catch violations, run a tool like mypy yourself — the interpreter won't.

6. `Dict` vs `dict` — and when did this syntax appear?

The dict itself is old; the type-hint syntax is the newer part.

Syntax	Import needed?	Introduced
`Dict[str, int]` (capital)	`from typing import Dict`	Python 3.5 (2015)
`dict[str, int]` (lowercase)	none (built-in)	Python 3.9 (2020)
`dict` (plain)	none	always

Annotating a variable with x: int = 0 has been possible since Python 3.6 (2016). Both forms mean the same thing, so new code usually prefers the lowercase dict[...].

scores: dict[str, float] = {}   # 3.9+ : lowercase, no import

Summary

name: Type = value == name = value + (a type note)
= {} is just an empty dict (old, ordinary syntax)
: Dict[str, int] is a hint that is not enforced — breaking it still runs
hints are documentation for humans / editors / mypy; the checking is done by mypy, separately

AMD GPU Programming Primer — Threads, Waves, Tiles & Vector Loads

2026-05-06T10:02:00.000-07:00

AMD GPU Programming Primer

Threads · Waves · Memory · Tile Distribution · Vector Loads · MFMA

1. The execution hierarchy: grid → workgroup → wave → thread

A GPU kernel launch is a hierarchy of work units. Bigger units contain smaller ones.

AMD term	NVIDIA term	What it is
Grid	Grid	The whole kernel launch — covers the entire problem.
Workgroup	Block / threadblock	A group of threads on one Compute Unit (CU). Shares LDS (shared memory). Can synchronize via `__syncthreads()`.
Wavefront (wave)	Warp	64 threads (AMD CDNA) executing the same instruction simultaneously (SIMT).
Thread (work-item)	Thread	One lane in a wave. Has its own thread ID and register state.

GRID (kernel launch — covers the whole problem)

Workgroup 0 (256 threads)

Wave 0 (T0..T63)

Wave 1 (T64..T127)

Wave 2 (T128..T191)

Wave 3 (T192..T255)

Workgroup 1 (256 threads)

Wave 0..3 (64 threads each)

Workgroup N−1

Wave 0..3

Key: 64 threads in a wave always execute the same instruction in lock-step. That is the essence of SIMT (Single Instruction Multiple Threads).

2. Lane vs thread

"Lane" and "thread" are two views of the same physical execution slot.

Lane = a hardware ALU slot inside a SIMD unit. There are exactly 64 lanes per SIMD on AMD CDNA.
Thread = the software view of one lane. Has its own thread ID and private registers.

One lane runs one thread at a time. They are 1:1 within an executing wave.

1 wave (= 64 threads) running on 1 SIMD:

   Lane 0  ↔  Thread 0    (running my_function with tid=0)
   Lane 1  ↔  Thread 1    (running my_function with tid=1)
   Lane 2  ↔  Thread 2
    ...
   Lane 63 ↔  Thread 63

All 64 lanes execute the same instruction at the same cycle.

3. Hardware: GPU → CU → SIMD → lane

Below the software hierarchy is the physical hardware:

GPU contains many CUs (Compute Units). Example: MI300X has 304 CUs.
CU contains 4 SIMD units. The 4 SIMDs in a CU operate in parallel.
SIMD contains 64 lanes (ALUs) and a register file that can hold up to 8 resident waves.

GPU
├─ CU 0
│   ├─ SIMD 0  (64 lanes, ≤ 8 resident waves)
│   ├─ SIMD 1  (64 lanes, ≤ 8 resident waves)
│   ├─ SIMD 2  (64 lanes, ≤ 8 resident waves)
│   ├─ SIMD 3  (64 lanes, ≤ 8 resident waves)
│   └─ LDS (shared memory, 64 KB)
├─ CU 1
├─ ...
└─ CU 303      ← total 304 CUs on MI300X

SIMD ≠ instant execution. A SIMD holds up to 8 waves in its register file but executes only one wave per cycle. With multiple waves resident, when one wave waits for memory, the SIMD switches to another. This is latency hiding.

4. Registers, VGPRs & occupancy

Register types

Type	Size	Scope	Notes
VGPR (vector GPR)	32-bit (4 B)	Private per lane	Up to 256 per lane per wave. Each lane sees its own VGPR.
SGPR (scalar GPR)	32-bit (4 B)	Shared by 64 lanes	Used for scalar values like loop counters, addresses.
AGPR (accumulator GPR)	32-bit (4 B)	Private per lane	CDNA-only. Used as MFMA accumulators.

How much register memory does one lane have?

1 lane × 256 VGPRs × 4 bytes = 1 KB per lane
1 wave (64 lanes) × 1 KB = 64 KB total register file used by one wave

Occupancy

Occupancy = number of waves resident on a SIMD (1 to 8). Higher occupancy enables better latency hiding.

If a wave uses 256 VGPRs/lane → only 1 wave fits in SIMD → occupancy 1
If a wave uses 128 VGPRs/lane → 2 waves fit                → occupancy 2
If a wave uses  32 VGPRs/lane → 8 waves fit                → occupancy 8 (max)

More resident waves = SIMD can switch when one wave stalls on memory.

Trade-off: using more VGPRs per thread means each thread can hold more data, but fewer waves can be resident, reducing latency hiding.

5. Memory hierarchy: registers → LDS → cache → HBM

GPU memory has multiple levels, similar to CPU cache hierarchy:

Level	Size (per CU / total)	Latency (cycles)	Managed by	CPU analogue
Registers (VGPR/SGPR)	~256 KB / CU	~1	Compiler	CPU registers
LDS (shared memory)	64 KB / CU	~10–30	Software (explicit loads/stores)	Scratchpad / fast SRAM
L1 cache	16 KB / CU	~30	Hardware (transparent)	L1 cache
L2 cache	~16 MB total	~150	Hardware	L2 cache
Infinity / L3	~256 MB	~300	Hardware	L3 cache
HBM (global memory)	192 GB	~500–1000	HW + software	DRAM

Key insight: registers are basically free (~1 cycle), HBM is very expensive (~500+ cycles). Performance comes from staging data through LDS and registers, and from hiding HBM latency with high occupancy.

6. Kernel launch `<<< grid, block >>>`

HIP/CUDA kernel launch syntax:

add_kernel<<< grid, block >>>(A, B, C, N);

Parameter	Meaning	Example
`block` (a.k.a. blockSize)	Threads per workgroup	256 → 4 waves per workgroup
`grid`	Number of workgroups	4 → 4 workgroups total
(implicit)	Wave count = blockSize / 64	256 / 64 = 4 waves per workgroup

You don't pick the wave count directly — it is derived from blockSize. The hardware always groups threads into waves of 64 on CDNA.

add_kernel<<< grid=4, block=256 >>>(...)

Total threads = 4 × 256 = 1024
Total waves   = 1024 / 64 = 16
Total workgroups = 4

Each workgroup → one CU
Each wave → one SIMD inside that CU

7. Vector loads & the 16-byte rule

A single load instruction can pull up to 16 bytes into a thread's registers. This is the hardware limit on AMD CDNA.

The number of elements per load (called vec size) depends on the data type:

Data type	Size (B)	vec=1	vec=2	vec=4	vec=8	vec=16
fp16 / bf16	2	2 B	4 B	8 B	16 B (max)	—
fp32	4	4 B	8 B	16 B (max)	—	—
int8	1	1 B	2 B	4 B	8 B	16 B (max)

Rule: vec × sizeof(dtype) ≤ 16 byte. Larger vec means fewer load instructions to move the same amount of data — faster.

Example GPU instructions

fp16, vec=1 (2 B):
   global_load_ushort  v0,    v[1:2]    ; load 2 bytes (1 fp16)
fp16, vec=4 (8 B):
   global_load_dwordx2 v[0:1], v[2:3]   ; load 8 bytes (4 fp16)
fp16, vec=8 (16 B):
   global_load_dwordx4 v[0:3], v[4:5]   ; load 16 bytes (8 fp16) - MAX
fp32, vec=4 (16 B):
   global_load_dwordx4 v[0:3], v[4:5]   ; load 16 bytes (4 fp32) - MAX

8. Walking through a simple kernel

__global__ void add_kernel(float* A, float* B, float* C, int N) {
    int tid = blockIdx.x * blockDim.x + threadIdx.x;  // global thread ID
    if (tid < N) {
        float a = A[tid];        // load (HBM → register)
        float b = B[tid];        // load (HBM → register)
        float c = a + b;         // ALU (register-to-register, ~1 cycle)
        C[tid] = c;              // store (register → HBM)
    }
}

add_kernel<<< 4, 256 >>>(A, B, C, 1024);

What happens per cycle (assuming occupancy 1, the worst case):

cycle:  1     2..99    100   101..199   200    201
        ----  ------   ----  --------   ----   -----
inst:   load   wait    load    wait     add    store
        A     (idle)   B      (idle)
                                                  ↓
                                          ALU only busy 2 cycles out of 200.

Instructions in this kernel: 4. Actual cycles: ~200. The reason: each HBM load takes ~100 cycles to complete, even though issuing it takes 1 cycle. With occupancy 1, the SIMD has nothing else to do but wait.

If occupancy were 4, the SIMD would switch to other waves during the wait, keeping the ALU busy on every cycle. This is why high occupancy matters.

9. MFMA: cooperative matrix multiply

MFMA (Matrix Fused Multiply-Add) instructions are wave-cooperative: all 64 lanes work together to compute a small matrix multiply (e.g., 16×16).

v_mfma_f32_16x16x16_f16   acc, a_frag, b_frag, c_frag

  64 lanes cooperatively compute D = A × B + C
  where A is 16×16 fp16, B is 16×16 fp16, D is 16×16 fp32

  Each lane holds a small piece of A, B, and accumulates a small piece of D.
  The hardware exchanges data between lanes during execution.

  Latency: ~8–32 cycles (NOT 1 cycle), but throughput is enormous:
    16×16×16 = 4,096 multiply-adds per instruction per wave

Important: MFMA is a wave-level instruction. It cannot be split across waves — one wave executes one MFMA. To compute a larger matrix multiply, multiple waves issue multiple MFMAs (covering different tiles).

CDNA vs RDNA

CDNA (data-center: gfx90a, gfx942, gfx950): MFMA available.
RDNA (consumer: gfx11, gfx12): no MFMA. Has WMMA (Wave Matrix Multiply-Accumulate) instead with similar idea.

10. Tiles & how a wave fills a tile (X0, Y0, X1, Y1)

What is a tile?

A tile is a 2D chunk of a matrix that one workgroup (or one wave) processes. GPU kernels divide a big problem into many small tiles.

Big matrix (e.g., 1024 × 1024)
divided into tiles of 64 × 64:

       X →
       ┌────────────────────────┐
   Y   │ t0  t1  t2  ...  t15   │
   ↓   │ t16 t17 ...            │   16 × 16 = 256 tiles
       │ ...                    │   each handled by one workgroup
       │ t240 ...          t255 │
       └────────────────────────┘

How does a 64-thread wave fill a 64×64 tile?

One 64×64 tile = 4,096 elements. One wave = 64 threads. Each thread is responsible for 4096/64 = 64 elements.

Those 64 elements per thread are split between two axes:

Symbol	Meaning
X1 (= vec)	Number of elements one thread loads in one instruction (X direction).
X0	Number of threads placed along the X axis.
Y0	Number of threads placed along the Y axis.
Y1	Number of times each thread iterates along the Y axis.

Constraints:

X0 × Y0     = 64           ← total threads (wave size)
X0 × X1     = XPerTile     ← X axis fully covered
Y0 × Y1     = YPerTile     ← Y axis fully covered (with iteration)
X1 × sizeof ≤ 16 byte      ← hardware load limit

Why the X axis can use vec loads

Memory is 1D, but we view it as 2D (row-major):

memory:  [a][b][c][d] [e][f][g][h] [i][j][k][l] [m][n][o][p]
         ─────────── ─────────── ─────────── ───────────
            row 0       row 1       row 2       row 3

X direction: addresses +1 (contiguous)  → one instruction can load 4/8/16 bytes
Y direction: addresses +width (strided) → needs separate instructions per row

Worked example: 64×64 tile, fp16, vec=4

X1 = 4 (vec)
X0 = XPerTile / X1 = 64 / 4 = 16
Y0 = wave / X0     = 64 / 16 = 4
Y1 = YPerTile / Y0 = 64 / 4  = 16

Per thread:    X1 × Y1 = 4 × 16 = 64 elements
Per wave:      64 threads × 64 elements = 4,096 elements ✓
Load count:    16 (per thread) → 1024 total vec loads → 4,096 elements

                X axis (16 threads × 4 vec = 64 cols)
              ┌─────────────────────────────────────┐
   row 0..3   │ T0  T1  T2  T3  T4  T5 ... T14 T15  │   ← Y0=0, Y1=0..3
   row 4..7   │ T0  T1  T2  T3  ...                 │   ← Y0=0, Y1=4..7
   ...                                                  Y1 iterates 16 times
   row 16..   │ T16 T17 ...                         │   ← Y0=1
   row 32..   │ T32 T33 ...                         │   ← Y0=2
   row 48..63 │ T48 T49 ... T63                     │   ← Y0=3
              └─────────────────────────────────────┘

Choosing vec size

vec	X0	Y0	Y1	Loads / thread	Quality
1	64	1	64	64	worst (no vec)
2	32	2	32	32	poor
4	16	4	16	16	good
8	8	8	8	8	best (fp16 max)

Larger vec → fewer load instructions → faster, up to the 16-byte hardware limit.

11. Tile distribution patterns: thread / warp / block raked

The same tile can be distributed across threads in several ways. The choice depends on the algorithm, the data layout, and the matrix instruction (MFMA) shape.

Pattern	Who covers one tile	Wave layout inside tile
`thread_raked`	1 wave (64 threads)	n/a (single wave)
`warp_raked`	Multiple waves cooperate	1D stack (waves stripe along one axis)
`block_raked`	All waves of the workgroup	2D grid (waves arranged in a grid)

warp_raked — 1D wave layout (4 waves stacked along Y)

                X axis (XPerTile)
              ┌─────────────────────────────────┐
              │          Wave 0                 │   each wave covers full X width
              ├─────────────────────────────────┤
              │          Wave 1                 │   1/4 of Y
              ├─────────────────────────────────┤
              │          Wave 2                 │
              ├─────────────────────────────────┤
              │          Wave 3                 │
              └─────────────────────────────────┘

block_raked — 2D wave layout (4 waves in 2×2 grid)

                X axis
              ┌───────────────┬─────────────┐
              │  Wave 0       │  Wave 1     │
              │ (X 0..63)     │ (X 64..127) │
              ├───────────────┼─────────────┤
              │  Wave 2       │  Wave 3     │
              │ (X 0..63)     │ (X 64..127) │
              └───────────────┴─────────────┘

	warp_raked (1D)	block_raked (2D)
Wave layout	1 axis (Y)	2 axes (X × Y)
Sub-tile per wave	XPerTile × (YPerTile/N)	(XPerTile/M) × (YPerTile/M)
X coverage by one wave	full	partial

The choice of pattern affects memory access patterns, MFMA fragment alignment, and register tile shapes. Each is best suited to different scenarios.

12. Cheat sheet

Concept	Definition
Grid	The whole kernel launch.
Workgroup (block)	Group of threads on one CU. Shares LDS.
Wave (warp)	64 threads (CDNA) executing in lockstep (SIMT).
Thread (work-item)	One software unit; runs on one lane.
Lane	One hardware ALU slot in a SIMD. 64 per SIMD.
SIMD	Hardware execution unit. 4 per CU. Can hold up to 8 resident waves.
CU	Compute Unit. Contains 4 SIMDs and 64 KB LDS. ~304 per MI300X.
VGPR	Vector register, private per lane. 32-bit. Up to 256 per lane.
SGPR	Scalar register, shared by all 64 lanes in a wave.
AGPR	Accumulator register (CDNA), used for MFMA output.
LDS	Local Data Share = software-managed shared memory. 64 KB per CU.
HBM	Global memory. Large but slow (~500+ cycle latency).
Occupancy	Number of resident waves on a SIMD (1–8). Higher = better latency hiding.
Latency hiding	SIMD switches to another resident wave while one waits on memory.
SIMT	Single Instruction Multiple Threads. All 64 lanes run the same instruction.
MFMA	Matrix Fused Multiply-Add. Wave-cooperative matrix multiply (CDNA).
WMMA	RDNA equivalent of MFMA.
Tile	2D chunk of a matrix processed by one workgroup.
XPerTile / YPerTile	Tile dimensions in elements (algorithm-defined).
vec / X1	Elements per thread per load. Constrained by 16-byte limit.
X0, Y0	Number of threads placed along X / Y axes.
Y1	Y-axis iteration count per thread.
Coalescing	Adjacent threads accessing adjacent memory → one wide HBM transaction.
Kernel launch	`kernel<<< grid, block >>>(...)` — grid = workgroups, block = threads/wg.
tile_distribution_pattern	How threads/waves are distributed across one tile (thread/warp/block raked).

Key takeaways

Threads run in waves of 64; one instruction = one wave-step.
Memory is the slow part. High occupancy hides memory latency.
Vector loads (up to 16 B) reduce instruction count dramatically.
Tile dimensions are chosen by the algorithm; thread layout is derived from them.
MFMA is wave-cooperative — cannot be split across waves.

How to Access Korean-Only Websites from Overseas Using AWS EC2 (Seoul Region VPN)

2026-05-03T02:14:00.000-07:00

How to Access Korean-Only Websites from Overseas Using AWS EC2 (Seoul Region VPN)

Some Korean websites (government, financial, public institutions) block access from foreign IP addresses. This guide shows you how to create a quick VPN tunnel through AWS EC2 in Seoul to get a Korean IP address.

What you need: AWS account, AWS CLI installed, Terminal (macOS/Linux)

Step 1: Verify AWS CLI

Make sure AWS CLI is installed and configured:

aws --version
aws sts get-caller-identity --region ap-northeast-2

If you see your Account ID, you're good to go.

Step 2: Create a Key Pair

aws ec2 create-key-pair \
  --key-name kr-proxy-key \
  --region ap-northeast-2 \
  --query 'KeyMaterial' \
  --output text > ~/Desktop/kr-proxy-key.pem

chmod 400 ~/Desktop/kr-proxy-key.pem

Step 3: Create a Security Group

# Create security group
aws ec2 create-security-group \
  --group-name kr-proxy-sg \
  --description "SSH proxy for Korean IP access" \
  --region ap-northeast-2

# Allow SSH inbound (replace sg-xxxxx with your Group ID from above)
aws ec2 authorize-security-group-ingress \
  --group-id sg-xxxxx \
  --protocol tcp \
  --port 22 \
  --cidr 0.0.0.0/0 \
  --region ap-northeast-2

Step 4: Find the Latest AMI

aws ec2 describe-images \
  --owners amazon \
  --filters "Name=name,Values=al2023-ami-2023*-x86_64" "Name=state,Values=available" \
  --query 'Images | sort_by(@, &CreationDate) | [-1].ImageId' \
  --output text \
  --region ap-northeast-2

Note the AMI ID (e.g. ami-09a64de684ce1ac0e).

Step 5: Launch EC2 Instance

aws ec2 run-instances \
  --image-id ami-09a64de684ce1ac0e \
  --instance-type t2.micro \
  --key-name kr-proxy-key \
  --security-group-ids sg-xxxxx \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=kr-proxy}]' \
  --region ap-northeast-2 \
  --query 'Instances[0].InstanceId' \
  --output text

Note the Instance ID (e.g. i-0df42e446381ecc9a).

t2.micro is free-tier eligible (750 hours/month for 12 months).

Step 6: Get Public IP

Wait about 30 seconds, then:

aws ec2 describe-instances \
  --instance-ids i-xxxxx \
  --region ap-northeast-2 \
  --query 'Reservations[0].Instances[0].[State.Name, PublicIpAddress]' \
  --output text

You should see something like: running 13.125.x.x

Step 7: Open SSH SOCKS5 Tunnel

ssh -D 1080 -N -f \
  -o StrictHostKeyChecking=no \
  -i ~/Desktop/kr-proxy-key.pem \
  ec2-user@13.125.x.x

-D 1080 — Creates a SOCKS5 proxy on local port 1080
-N — No remote command (tunnel only)
-f — Run in background

Step 8: Verify Korean IP

curl --socks5-hostname localhost:1080 https://ifconfig.me

If it returns your EC2's Korean IP (e.g. 13.125.x.x), it's working!

Step 9: Configure Browser Proxy

Option A: macOS System Settings

Open System Settings → Network → Wi-Fi
Click Details... → Proxies
Enable SOCKS Proxy
Server: localhost / Port: 1080
Click OK

Option B: Terminal (macOS)

sudo networksetup -setsocksfirewallproxy "Wi-Fi" localhost 1080
sudo networksetup -setsocksfirewallproxystate "Wi-Fi" on

Option C: curl only

curl --socks5-hostname localhost:1080 https://www.target-website.kr

Now open your browser and access the Korean website!

Clean Up (Important!)

When you're done, clean up everything to avoid charges:

1. Close the SSH Tunnel

pkill -f "ssh -D 1080"

2. Turn Off Browser Proxy

macOS GUI: System Settings → Network → Wi-Fi → Details → Proxies → SOCKS Proxy OFF

Terminal:

sudo networksetup -setsocksfirewallproxystate "Wi-Fi" off

# Verify
networksetup -getsocksfirewallproxy "Wi-Fi"
# Should show: Enabled: No

3. Terminate EC2 Instance

aws ec2 terminate-instances \
  --instance-ids i-xxxxx \
  --region ap-northeast-2

4. Delete Security Group

Wait about 30 seconds after termination, then:

aws ec2 delete-security-group \
  --group-id sg-xxxxx \
  --region ap-northeast-2

5. Delete Key Pair

aws ec2 delete-key-pair \
  --key-name kr-proxy-key \
  --region ap-northeast-2

rm ~/Desktop/kr-proxy-key.pem

Cost Summary

Item	Cost
t2.micro (free tier)	Free (750 hrs/month, 12 months)
t2.micro (after free tier)	~$0.0116/hr (~$8.5/month)
Data transfer	Free up to 100GB/month

Tip: If you want to keep the instance for later, Stop it instead of terminating. You only pay for EBS storage (~$0.10/GB/month) while stopped.

Quick Reference: Reconnect Later

If you stopped (not terminated) the instance:

# Start the instance
aws ec2 start-instances --instance-ids i-xxxxx --region ap-northeast-2

# Wait ~30 seconds, get new public IP
aws ec2 describe-instances \
  --instance-ids i-xxxxx \
  --region ap-northeast-2 \
  --query 'Reservations[0].Instances[0].PublicIpAddress' \
  --output text

# Open tunnel
ssh -D 1080 -N -f -i ~/Desktop/kr-proxy-key.pem ec2-user@NEW-IP

# Set proxy
sudo networksetup -setsocksfirewallproxy "Wi-Fi" localhost 1080
sudo networksetup -setsocksfirewallproxystate "Wi-Fi" on

How to Apply for a D-U-N-S Number

2026-03-08T03:31:00.000-07:00

Contents

What is a D-U-N-S Number?
Prerequisites — Documents to Prepare
Go to the D&B Application Portal
Select Your Request Type
Search for an Existing D-U-N-S
Fill Out the Application Form
Attach Supporting Documents
Add Notes & Submit
What Happens Next?
Troubleshooting: Common Rejection Reasons
Using Your D-U-N-S for Apple Developer Enrollment

1. What is a D-U-N-S Number?

A D-U-N-S Number (Data Universal Numbering System) is a unique 9-digit business identifier issued by Dun & Bradstreet (D&B). It is used globally to identify and verify businesses for purposes such as:

Enrolling in the Apple Developer Program as an organization
Applying for government contracts and grants
Establishing business credit profiles
Vendor and supplier registration

💡 Apple requires a D-U-N-S Number to verify your organization's legal identity before issuing an Apple Developer team account. Individual accounts do not need one.

2. Prerequisites — Documents to Prepare

Before starting the application, gather the following information and documents:

Item	Description
Business Name	Full legal name exactly as registered
Registration Number	Tax ID or company registration number
Business Address	Full address including postal code and country
Phone Number	International format: `+[country code][number]`
CEO / Owner Info	Full legal name and title (e.g., Owner, CEO)
Website	Company website URL (if available)
Date Founded	Official business establishment date
Employee Count	Total headcount including yourself
Registration Certificate	English version — PDF format preferred

⚠️ Non-English documents must be translated. Check your country's official tax authority or business registration portal — many offer an official English-language certificate export option directly.

3. Go to the D&B Application Portal

Navigate to the appropriate portal based on your use case:

Apple Developer Program

👉 https://support.dnb.com/?CUST=APPLEDEV

Use this URL if you are applying specifically to enroll in the Apple Developer Program as an organization.

General D-U-N-S Application

👉 https://www.dnb.com/duns-number/get-a-duns.html

Use this for general business registration, government contracts, or other purposes.

4. Select Your Request Type

On the Apple Developer D&B portal, you will be asked two questions:

Step 4a

Under "What are you?" → select Developer Program

Step 4b

Under "What do you need?" → select Create New DUNS

5. Search for an Existing D-U-N-S

The portal checks whether your business already has a D-U-N-S number before creating a new one.

Step 5a

Enter your business name and full address in the search fields.

Step 5b

Click "Lookup by Name / Address".

Step 5c — Expected Result

For new businesses: you will see "No Match found" — this is completely normal and expected.

Step 5d

Click "click here to submit a request to create a new D-U-N-S" to open the full application form.

✅ If a match is found, your business already has a D-U-N-S. You can claim or update it instead of creating a new one — contact D&B support directly.

6. Fill Out the Application Form

Complete all fields in the Create D-U-N-S Number form. All fields must exactly match your official registration documents.

Field	What to Enter
Full Legal Business Name	Exact name as on registration documents
Business Registration Number	Your tax ID / company ID number
Company Phone	International format (e.g., `+358501234567`)
Street Address	Full street address
City	City name
State / Province	State or province (if applicable)
Postal Code	ZIP / postal code
Country	Your country
Business Structure	e.g., Sole Proprietorship, LLC, Corporation
CEO / Owner Name	Full legal name
CEO / Owner Title	e.g., Owner, CEO, Director
Website	Company website URL
Home-Based Business	Yes / No
Number of Employees	Total headcount (including yourself)
Date Founded	Official establishment date (MM/DD/YYYY)

⚠️ Exact match required. The business name, address, and registration number must match your official documents precisely. Even minor differences (abbreviations, punctuation) can cause rejection.

Click "Next" to advance to the document attachment page.

7. Attach Supporting Documents

Upload a document to verify your business registration. This is required — submissions without a document attachment are typically rejected.

Accepted Documents

✅ English Business Registration Certificate (strongly preferred)

✅ Official government-issued business license

✅ Any official document showing your business name, registration number, and address

📄 PDF format is recommended. File size is typically not an issue, but keep it under 5MB to be safe. Make sure the document is clearly legible and all key information is visible.

8. Add Notes & Submit

There is usually a free-text Additional Details / Notes field. Always fill this in — it helps the D&B reviewer understand your submission and can speed up approval.

Example — First-time application

Sample note text

This is a new D-U-N-S number request for [Your Business Name], a sole proprietorship registered in [Country] since [Year]. Business is engaged in [industry, e.g. software development]. English Business Registration Certificate is attached.

Example — Resubmission after rejection

Sample note text

Resubmitting after previous rejection (Case #XXXXXXXX) which was closed due to missing English Business Registration Certificate. The English certificate is now attached. Business registration number: [Your Number]. Business started: [Date].

After reviewing all information, click Submit.

💾 Save your case number immediately after submission — you will need it to track your application status or to reference in any resubmission.

9. What Happens Next?

After submission, D&B will review your request. Here is the typical timeline:

Immediately	On-screen confirmation + case number displayed. Check your email for a confirmation from D&B (check spam).
1–2 business days	D&B reviews your submitted information and documents.
3–5 business days	D-U-N-S Number issued and emailed to you.
Up to 30 days	In some cases D&B may request additional documentation.

📬 D&B will send your D-U-N-S Number by email. Once received, the number is also searchable via the D&B portal. Apple recommends waiting 24–48 hours after receiving your number before using it for developer enrollment.

10. Troubleshooting: Common Rejection Reasons

Issue	Solution
Missing English document	Obtain an official English translation of your registration certificate and resubmit
Business name mismatch	Ensure the name on the form exactly matches your official documents (character for character)
Address not recognized	Use the exact address format from your registration documents
Duplicate D-U-N-S found	Contact D&B to claim or update the existing record instead of creating a new one
Case closed, no response	Resubmit the form and reference the previous case number in the notes field
Document unreadable	Re-export or rescan the document as a clear, high-resolution PDF

11. Using Your D-U-N-S for Apple Developer Enrollment

Once you have your D-U-N-S Number:

Step 1

Go to https://developer.apple.com/enroll/

Step 2

Select "Enroll as an Organization" (not Individual).

Step 3

Enter your D-U-N-S Number when prompted. Apple will verify it against D&B's database.

Step 4

Allow 24–48 hours after receiving your D-U-N-S before enrolling — the number needs time to propagate in D&B's system.

✅ The Apple verification process typically takes a few days after enrollment. Apple may call your registered business phone number to verify your identity as the organization's legal representative.

Final Checklist

Prepared English business registration certificate (PDF)
Navigated to the D&B portal (APPLEDEV or general)
Selected correct request type (Developer Program → Create New DUNS)
Searched for existing D-U-N-S — confirmed no match
Filled out all form fields matching official documents exactly
Uploaded supporting document (English certificate)
Added descriptive notes in the Additional Details field
Submitted the form and saved the case number
Waiting for D&B email confirmation (3–5 business days)

Resources

Last updated: March 2026 · For general informational purposes

Main image by Syawish Rehman on Unsplash

🚙🚙 AUTOMATIC NUMBER PLATE RECOGNITION (ANPR, LPR, ALPR) solution

2026-01-09T13:51:00.032-08:00

Step-by-Step: Building MIOpen and hipDNN with Ninja

2026-01-09T05:12:00.000-08:00

Step-by-Step: Building MIOpen and hipDNN with Ninja

Step 1: Navigate to the monorepo

git clone https://github.com/ROCm/rocm-libraries.git

>cd rocm-libraries

Step 2: Create a build directory

Step 3: Configure with CMake using Ninja

What this does:

-GNinja - Use Ninja build system (faster than Make)

-DCMAKE_BUILD_TYPE=Release - Optimized build

-DCMAKE_INSTALL_PREFIX=/opt/rocm - Install location

-DCMAKE_PREFIX_PATH=/opt/rocm - Where to find ROCm dependencies

-DROCM_LIBS_ENABLE_COMPONENTS="miopen;hipdnn" - Build only these two projects + their dependencies

Step 4: Build both projects

Or if you want to limit parallel jobs (e.g., for memory constraints):

Step 5: Run tests (optional)

Step 6: Install (optional)

Alternative: Build with specific options

If you need more control, you can add these flags:

Useful Ninja Commands

Expected Build Time

Configuration (CMake): ~30 seconds to 2 minutes

MIOpen build: ~20-40 minutes (first time)

hipDNN build: ~5-10 minutes

Total: ~30-50 minutes on MI250X system

What Gets Built

After successful build, you'll have:

If You Encounter Issues

Missing dependencies error:

Out of memory during build:

See what would be built:

AWS SAM Troubleshooting - Fixing pip/runtime and AWS CLI Issues

2025-12-31T11:24:00.000-08:00

🔧 AWS SAM Troubleshooting - Fixing pip/runtime and AWS CLI Issues

If you're deploying AWS Lambda functions with SAM (Serverless Application Model), you may have encountered frustrating build errors. This guide explains the two most common issues and how to fix them permanently.

Note: This guide uses generic examples (<YOUR_STACK_NAME>) and is safe to share publicly.

🚨 The Two Common Problems

Problem A — `sam build` fails with pip/runtime error

You may see this error:

Error: PythonPipBuilder:ResolveDependencies - Failed to find a Python runtime containing pip on the PATH.

What this means: SAM is trying to build for a specific Lambda runtime (like python3.11), but your shell has:

python from one location (e.g., conda environment)
pip from another location (e.g., ~/.local/bin or /usr/bin)

SAM requires a matching pair - the pip must belong to the same Python interpreter that matches your Lambda runtime version.

Problem B — AWS CLI crashes with botocore conflicts

You may see errors like:

KeyError: 'opsworkscm'
ModuleNotFoundError: No module named 'dateutil'

What this means: Your system AWS CLI (/usr/bin/aws) is accidentally importing incompatible botocore or boto3 packages from ~/.local/lib/python..., causing version conflicts.

🔍 Quick Diagnosis (5 Commands)

Run these from your SAM project directory to diagnose the issue:

# 1. What Python runtime does your template.yaml require?
grep "Runtime: python" template.yaml

# 2. What python are you using?
which python
python -V

# 3. What pip are you using?
which pip
pip -V

# 4. Does pip belong to this python?
python -m pip -V

🚩 Red flag: If pip -V and python -m pip -V show different paths or Python versions, your PATH is contaminated.

✅ The Fix: Dedicated Environment + Clean PATH

The solution is to create an isolated environment that matches your Lambda runtime and force clean PATH ordering.

Step 1: Create an environment matching your Lambda runtime

If your template.yaml specifies Runtime: python3.11, create a Python 3.11 environment:

# Using conda (recommended)
conda create -n aws-sam-py311 python=3.11 pip -y
conda activate aws-sam-py311

# Or using venv
python3.11 -m venv ~/.virtualenvs/aws-sam-py311
source ~/.virtualenvs/aws-sam-py311/bin/activate

Step 2: Install SAM CLI and AWS CLI inside the environment

# Upgrade pip first
python -m pip install --upgrade pip

# Install SAM CLI
python -m pip install aws-sam-cli

# Optional: Install AWS CLI v2 (avoids system aws/botocore conflicts)
# Using conda-forge:
conda install -c conda-forge awscli -y

# Or using pip:
python -m pip install awscli

Step 3: Disable user-site imports and fix PATH ordering

This is the critical step that prevents ~/.local contamination:

# Disable user site-packages (~/.local)
export PYTHONNOUSERSITE=1

# Force clean PATH (conda/venv bin first, then system)
export PATH="$CONDA_PREFIX/bin:/usr/bin:/bin"

# Or for venv:
# export PATH="$VIRTUAL_ENV/bin:/usr/bin:/bin"

# Clear shell hash table
hash -r

Step 4: Verify the fix

# All should point to your environment
which python
which pip
which sam
which aws

# Verify versions match
python -V      # Should be 3.11.x
pip -V         # Should show python 3.11
sam --version  # Should work without errors
aws --version  # Should work without errors

Step 5: Build and deploy

sam build --cached --parallel
sam deploy --no-confirm-changeset --stack-name <YOUR_STACK_NAME> --region <YOUR_AWS_REGION>

🐳 Alternative: Container Build (Docker)

If you have Docker installed, you can avoid all Python toolchain issues by building in a container:

sam build --use-container
sam deploy --no-confirm-changeset --stack-name <YOUR_STACK_NAME> --region <YOUR_AWS_REGION>

Pros:

✅ No need to match local Python version
✅ Builds in environment identical to Lambda
✅ Most reproducible approach

Cons:

❌ Slower than native builds
❌ Requires Docker installed and running

⚡ Quick Fix for Broken AWS CLI (Emergency)

If you need to use system AWS CLI right now and it's broken:

# Force it to ignore user-site packages
PYTHONNOUSERSITE=1 /usr/bin/aws --version
PYTHONNOUSERSITE=1 /usr/bin/aws sts get-caller-identity
PYTHONNOUSERSITE=1 /usr/bin/aws s3 ls

But the proper fix is: Install AWS CLI inside your dedicated environment (see Step 2 above).

🤔 Why Lambda is python3.11 but my machine uses python3.12?

This is a common source of confusion. They are different things:

Component	What It Is	Where It's Defined
Lambda Runtime	Python version AWS runs in production	`template.yaml` → `Runtime: python3.11`
Your Local Python	Python version for development/training/scripts	Your system default or conda environment

Key point: When SAM builds your Lambda functions, it must build dependencies compatible with the Lambda runtime, even if your system default is Python 3.12.

Example from template.yaml:

AnprDeviceLicenseValidateFunction:
  Type: AWS::Serverless::Function
  Properties:
    CodeUri: anpr_device_license_validate/
    Handler: app.lambda_handler
    Runtime: python3.11          # ← Lambda uses 3.11
    Architectures:
      - x86_64

So you have three options:

Match local environment to Lambda (recommended) - Create python3.11 env for SAM work
Use container build - Let Docker handle it with sam build --use-container
Upgrade Lambda runtime - Change template.yaml to python3.12 (requires testing)

📋 Complete Example: Deploy Script

Here's a complete bash script that implements all the fixes:

#!/usr/bin/env bash
set -euo pipefail

# Activate conda environment (matches Lambda runtime)
source ~/anaconda3/etc/profile.d/conda.sh
conda activate aws-sam-py311

# Critical: Clean PATH and disable user-site
export PYTHONNOUSERSITE=1
export PATH="$CONDA_PREFIX/bin:/usr/bin:/bin"
hash -r

echo "Environment ready:"
echo "  Python: $(python -V)"
echo "  SAM: $(sam --version | head -1)"
echo "  AWS: $(aws --version)"

# Build and deploy
sam build --cached --parallel
sam deploy --no-confirm-changeset

🎯 Troubleshooting Checklist

Issue	Check	Fix
sam build fails	`which pip` vs `python -m pip -V`	Create dedicated env, fix PATH
aws command crashes	`echo $PYTHONNOUSERSITE`	Set `PYTHONNOUSERSITE=1`
Wrong Python version	`python -V` vs Lambda runtime	Create env matching Lambda
Multiple pip versions	`which -a pip`	Fix PATH ordering
Conda conflicts	`conda env list`	Create separate env for SAM

🔒 Security Best Practices

⚠️ When sharing code publicly:

❌ Never publish template.yaml with secrets (API keys, tokens, webhook URLs)
✅ Use AWS Secrets Manager or SSM Parameter Store for secrets
✅ Redact from logs:
- AWS account IDs
- API Gateway URLs
- Stack names and ARNs
- Any access keys/tokens

💡 Pro Tips

1. Create a deployment script

Instead of remembering all these environment variables, create a deploy.sh script:

#!/usr/bin/env bash
set -euo pipefail

# Activate environment
source ~/anaconda3/etc/profile.d/conda.sh
conda activate aws-sam-py311

# Clean environment
export PYTHONNOUSERSITE=1
export PATH="$CONDA_PREFIX/bin:/usr/bin:/bin"
hash -r

# Build and deploy
sam build --cached --parallel
sam deploy --no-confirm-changeset

echo "✅ Deployment complete!"

Make it executable: chmod +x deploy.sh

2. Use SAM build cache for faster builds

# First build (slow)
sam build

# Subsequent builds (much faster!)
sam build --cached --parallel

3. Test locally before deploying

# Invoke function locally
sam local invoke MyFunction --event events/test.json

# Start local API
sam local start-api

4. Skip changeset confirmation in CI/CD

# Manual deployment - shows changes
sam deploy

# CI/CD deployment - no prompts
sam deploy --no-confirm-changeset

📊 Before vs After

❌ Before (Broken)

$ sam build
Error: Failed to find Python runtime containing pip

$ aws --version
KeyError: 'opsworkscm'

$ which pip
/home/user/.local/bin/pip  # Wrong location!

$ pip -V
pip 24.0 (python 3.12)     # Wrong version!

✅ After (Fixed)

$ conda activate aws-sam-py311
$ export PYTHONNOUSERSITE=1
$ export PATH="$CONDA_PREFIX/bin:/usr/bin:/bin"

$ sam build
Build Succeeded ✨

$ aws --version
aws-cli/2.32.26 Python/3.11.14

$ which pip
/home/user/anaconda3/envs/aws-sam-py311/bin/pip  # Correct!

$ pip -V
pip 25.3 (python 3.11)     # Matches Lambda runtime!

🎓 Summary

The root cause of most SAM build failures is PATH contamination - your shell mixes Python versions and pip locations from different sources (~/.local, /usr/bin, conda environments).

The complete fix:

✅ Create dedicated environment matching Lambda runtime (python3.11)
✅ Install SAM CLI and AWS CLI inside that environment
✅ Set PYTHONNOUSERSITE=1 to disable user-site packages
✅ Fix PATH ordering: export PATH="$CONDA_PREFIX/bin:/usr/bin:/bin"
✅ Run hash -r to clear shell cache

After this, sam build and aws commands will work reliably! 🚀

🔗 Additional Resources

Tags: AWS, SAM, Lambda, Python, DevOps, Deployment, Troubleshooting, ServerlessFramework, CICD, CloudComputing

MareArts ANPR V14 Models - Complete Performance Guide & Benchmarks

2025-12-30T14:02:12.778-08:00

⚡ MareArts ANPR V14 Models - Performance, Metrics & How to Choose

Choosing the right ANPR model is crucial for your application. Too heavy? Slow performance. Too light? Lower accuracy. In this comprehensive guide, we'll break down all MareArts ANPR V14 models with real benchmarks to help you make the perfect choice.

🎯 Two-Stage Pipeline Architecture

MareArts ANPR uses a two-stage pipeline:

Detector - Finds license plates in images (Where is the plate?)
OCR - Reads text from detected plates (What does it say?)

You can mix and match models from each stage to optimize for your specific needs!

📊 Detector Models - Find License Plates

Model Sizes Explained

Size	Parameters	Speed	Accuracy	Best For
pico	Smallest	Fast	Good (96-98%)	Mobile, Edge devices
micro	Small	Very Fast	Excellent (97-99%)	🏆 Best overall
small	Medium	Fastest	Excellent (98-99%)	High-speed applications
medium	Large	Fast	Excellent (98-99%)	Balanced
large	Largest	Moderate	Highest (99%+)	Maximum accuracy

Resolution Options

320p models (320×320) - 2× faster, 96-98% detection
640p models (640×640) - Highest accuracy, 98-99% detection

Precision Options

FP32 - Fastest on GPU (2× faster than FP16), standard size
FP16 - 50% smaller file size, same accuracy, slower inference

Complete Detector Performance Table

Model Name	Detection Rate	Speed (GPU)	Size	Recommendation
micro_320p_fp32	97.13%	128 FPS (7.8ms)	83 MB	🏆 Best overall
micro_320p_fp16	97.13%	56 FPS (17.9ms)	42 MB	🏆 Best mobile
small_320p_fp32	98.00%	142 FPS (7.0ms)	114 MB	⚡ Fastest
medium_320p_fp32	98.06%	136 FPS (7.4ms)	153 MB	High detection
large_320p_fp32	98.40%	131 FPS (7.6ms)	164 MB	Strong performance
pico_320p_fp32	96.02%	129 FPS (7.8ms)	75 MB	📱 Smallest + fast
pico_640p_fp32	98.54%	66 FPS (15.2ms)	75 MB	Balanced
small_640p_fp32	99.15%	70 FPS (14.3ms)	114 MB	High detection
medium_640p_fp32	99.21%	66 FPS (15.1ms)	153 MB	Very high
large_640p_fp32	99.31%	60 FPS (16.7ms)	164 MB	🎯 Highest accuracy

Key Findings:

✅ 320p models: 2× faster than 640p (96-98% accuracy)
✅ 640p models: Highest accuracy (98-99%) for difficult cases
✅ FP16 models: 50% smaller, same accuracy, ~50% slower
✅ Recommended: micro_320p_fp32 (best speed/accuracy balance)

📖 OCR Models - Read License Plate Text

Two Key Metrics

Exact Match - Entire plate number is 100% correct
Character Accuracy - Percentage of individual characters correct

Example: Actual plate: "ABC-1234"

OCR reads "ABC-1234" → ✅ Exact Match = Yes, Char Accuracy = 100%
OCR reads "ABC-1235" → ❌ Exact Match = No, Char Accuracy = 87.5% (7/8 correct)

Complete OCR Performance by Region

🌍 Universal (univ) - All Regions

Model	Exact Match	Char Accuracy	FPS	Size
pico_fp32	97.48%	98.87%	264	20 MB
micro_fp32	97.54%	98.86%	260	71 MB
small_fp32	97.51%	98.85%	291	112 MB
medium_fp32	97.57%	98.89%	245	164 MB
large_fp32	97.75%	98.91%	253	179 MB

🇰🇷 Korean (kr) - Best Overall Accuracy

Model	Exact Match	Char Accuracy	FPS
pico_fp32	98.99%	99.77%	272
micro_fp32	99.21%	99.80%	250
small_fp32	99.19%	99.80%	295
medium_fp32	99.21%	99.80%	267
large_fp32	99.27%	99.82%	265

🇪🇺 Europe+ (eup) - EU + Additional Countries

Model	Exact Match	Char Accuracy	FPS
pico_fp32	94.98%	97.39%	280
micro_fp32	95.07%	97.46%	266
small_fp32	94.98%	97.43%	304
medium_fp32	95.03%	97.46%	278
large_fp32	95.32%	97.54%	260

🇺🇸 North America (na) - USA, Canada, Mexico

Model	Exact Match	Char Accuracy	FPS
pico_fp32	71.21%	88.43%	268
micro_fp32	71.21%	87.67%	269
small_fp32	69.70%	88.27%	311
medium_fp32	63.64%	87.24%	284
large_fp32	69.70%	86.25%	271

🇨🇳 China (cn)

Model	Exact Match	Char Accuracy	FPS
pico_fp32	96.24%	98.82%	268
micro_fp32	96.30%	98.74%	265
small_fp32	96.36%	98.88%	301
medium_fp32	96.36%	98.89%	276
large_fp32	96.49%	98.87%	262

OCR Model Averages (All Regions)

Model	Avg Exact Match	Avg Char Accuracy	Avg FPS	Size
small_fp32	91.54%	96.64%	300 FPS	112 MB
pico_fp32	91.78%	96.65%	270 FPS	20 MB
micro_fp32	91.86%	96.50%	262 FPS	71 MB
medium_fp32	90.36%	96.45%	270 FPS	164 MB
large_fp32	91.70%	96.27%	262 FPS	179 MB

🌍 Regional Vocabulary Support

Region	Code	Coverage	Character Sets
Universal	`univ`	All regions (default)	All character sets
Korea	`kr`	South Korea	Hangul + Latin + Digits
Europe+	`eup`	EU + UK, Switzerland, Norway	Latin + Cyrillic + Special
North America	`na`	USA, Canada, Mexico	Latin + Digits
China	`cn`	China	Chinese + Latin + Digits

Pro Tip: Always use specific regions for best accuracy. Only use univ when the region is unknown!

🎯 How to Choose the Right Models

Use Case 1: Parking Management

Requirements: Good accuracy, real-time performance, cost-effective

# Recommended Configuration
detector = ma_anpr_detector_v14(
    "micro_320p_fp32",  # 97% detection, 128 FPS
    user, key, sig,
    backend="cuda",
    conf_thres=0.25
)

ocr = ma_anpr_ocr_v14(
    "small_fp32",       # 95%+ exact match, 300 FPS
    "eup",              # Specific region
    user, key, sig
)

Why: Excellent balance of speed and accuracy. Handles 90%+ of plates easily.

Use Case 2: Security Checkpoint (Critical)

Requirements: Maximum accuracy, can't miss plates

# Recommended Configuration
detector = ma_anpr_detector_v14(
    "large_640p_fp32",  # 99.31% detection (highest!)
    user, key, sig,
    backend="cuda",
    conf_thres=0.20     # Lower threshold for more detections
)

ocr = ma_anpr_ocr_v14(
    "large_fp32",       # 95%+ exact match, best accuracy
    "kr",               # Specific region for your area
    user, key, sig
)

Why: Maximum detection and recognition accuracy. No compromises.

Use Case 3: Traffic Monitoring (High Volume)

Requirements: Maximum speed, process many cameras

# Recommended Configuration
detector = ma_anpr_detector_v14(
    "small_320p_fp32",  # 98% detection, 142 FPS (fastest!)
    user, key, sig,
    backend="cuda",
    conf_thres=0.25
)

ocr = ma_anpr_ocr_v14(
    "small_fp32",       # 300 FPS (fastest OCR!)
    "univ",             # Universal for mixed traffic
    user, key, sig
)

Why: Fastest processing for high-volume applications. Can handle multiple streams.

Use Case 4: Mobile/Edge Device

Requirements: Small size, low power, on-device processing

# Recommended Configuration
detector = ma_anpr_detector_v14(
    "micro_320p_fp16",  # 97% detection, 42 MB (50% smaller!)
    user, key, sig,
    backend="cpu",      # CPU for mobile
    conf_thres=0.25
)

ocr = ma_anpr_ocr_v14(
    "pico_fp32",        # 20 MB, 270 FPS
    "kr",               # Specific region
    user, key, sig
)

Why: Smallest models, excellent for mobile/edge. Total size: 62 MB.

Use Case 5: Law Enforcement (Difficult Conditions)

Requirements: Works in poor lighting, angles, damaged plates

# Recommended Configuration
detector = ma_anpr_detector_v14(
    "medium_640p_fp32", # 99.21% detection
    user, key, sig,
    backend="cuda",
    conf_thres=0.15     # Very low threshold for difficult cases
)

ocr = ma_anpr_ocr_v14(
    "large_fp32",       # Best OCR accuracy
    "na",               # Specific region
    user, key, sig
)

Why: Handles difficult conditions better. Lower threshold catches more plates.

📈 Performance Comparison Chart

Detector Models: Speed vs Accuracy

Category	Fastest	Balanced	Most Accurate
320p	small_320p_fp32 142 FPS, 98.00%	micro_320p_fp32 128 FPS, 97.13%	large_320p_fp32 131 FPS, 98.40%
640p	small_640p_fp32 70 FPS, 99.15%	medium_640p_fp32 66 FPS, 99.21%	large_640p_fp32 60 FPS, 99.31%
Mobile	pico_320p_fp16 50+ FPS, 37 MB	micro_320p_fp16 56 FPS, 42 MB	small_320p_fp16 70+ FPS, 57 MB

OCR Models: Speed vs Accuracy

Priority	Smallest	Fastest	Most Accurate
Choice	pico_fp32 20 MB, 270 FPS 91.78% exact	small_fp32 112 MB, 300 FPS 91.54% exact	large_fp32 179 MB, 262 FPS 91.70% exact

💡 Performance Tips

1. GPU Acceleration is Essential

# CPU: ~1-2 FPS (slow!)
detector = ma_anpr_detector_v14(..., backend="cpu")

# CUDA (NVIDIA GPU): ~100+ FPS (fast!)
detector = ma_anpr_detector_v14(..., backend="cuda")

# DirectML (Windows GPU): ~50+ FPS
detector = ma_anpr_detector_v14(..., backend="directml")

Result: GPU is 50-100× faster than CPU!

2. Use Batch Processing

# Slow: Process one by one
for img in images:
    text, conf = ocr.predict(img)

# Fast: Process in batch (3-5× faster!)
results = ocr.predict(images)  # Pass list

3. Choose Resolution Wisely

320p: Good quality images, controlled environment → Use 320p (2× faster)
640p: Poor lighting, far distance, damaged plates → Use 640p (higher accuracy)

4. Tune Confidence Thresholds

# High precision (fewer false positives)
detector = ma_anpr_detector_v14(..., conf_thres=0.50)

# Balanced (recommended)
detector = ma_anpr_detector_v14(..., conf_thres=0.25)

# High recall (catch more plates, more false positives)
detector = ma_anpr_detector_v14(..., conf_thres=0.15)

5. Use Specific Regions

# ❌ Less accurate (universal)
ocr = ma_anpr_ocr_v14("small_fp32", "univ", ...)  # ~92% exact match

# ✅ More accurate (specific region)
ocr = ma_anpr_ocr_v14("small_fp32", "kr", ...)    # ~99% exact match!

🚀 Quick Decision Guide

Your Priority	Detector	OCR
Best Overall	micro_320p_fp32	small_fp32
Fastest	small_320p_fp32	small_fp32
Most Accurate	large_640p_fp32	large_fp32
Smallest	pico_320p_fp16	pico_fp32
Mobile	micro_320p_fp16	pico_fp32
Balanced	medium_320p_fp32	medium_fp32

📊 Benchmark Environment

GPU: NVIDIA RTX 3060 (CUDA 11.8)
CPU: Intel Core i7
Dataset: Real-world license plate images
Test Size: 1000+ images per region
Updated: December 2025

🎓 Key Takeaways

✅ Two-stage pipeline: Detector → OCR
✅ Mix and match models for your needs
✅ 320p models: 2× faster, excellent for most uses
✅ 640p models: Highest accuracy for difficult cases
✅ GPU acceleration: 50-100× faster than CPU
✅ Specific regions: Much better accuracy than universal
✅ Batch processing: 3-5× faster for multiple images
✅ Best overall: micro_320p_fp32 + small_fp32

💻 Example Configuration

from marearts_anpr import ma_anpr_detector_v14, ma_anpr_ocr_v14
from marearts_anpr import marearts_anpr_from_image_file

# Initialize models (one time)
detector = ma_anpr_detector_v14(
    "micro_320p_fp32",      # 97% detection, 128 FPS
    user_name, serial_key, signature,
    backend="cuda",          # GPU acceleration
    conf_thres=0.25          # Balanced threshold
)

ocr = ma_anpr_ocr_v14(
    "small_fp32",            # 95%+ accuracy, 300 FPS
    "eup",                   # Specific region for best accuracy
    user_name, serial_key, signature
)

# Process image
result = marearts_anpr_from_image_file(detector, ocr, "plate.jpg")
print(result)

# Output:
# {
#   "results": [
#     {
#       "ocr": "AB-123-CD",
#       "ocr_conf": 98.5,
#       "ltrb": [120, 230, 380, 290],
#       "ltrb_conf": 95
#     }
#   ],
#   "ltrb_proc_sec": 0.008,  # Detection time
#   "ocr_proc_sec": 0.003     # OCR time
# }

🔗 Resources

📊 Full Benchmarks: See detailed results in GitHub docs
📚 Model Guide: Complete model documentation
🧪 Try Free: ma-anpr test-api image.jpg
🛒 Get License: MareArts ANPR

🎯 Conclusion

MareArts ANPR V14 offers 11 detector models and 5 OCR models, giving you 55+ possible combinations! The right choice depends on your specific requirements:

Speed-critical? → small_320p_fp32 + small_fp32
Accuracy-critical? → large_640p_fp32 + large_fp32
Balanced? → micro_320p_fp32 + small_fp32 (recommended!)
Mobile? → micro_320p_fp16 + pico_fp32

Start with the recommended configuration and tune based on your results. Happy optimizing! ⚡🚗

Labels: ANPR, MachineLearning, ComputerVision, Performance, Benchmarks, Models, Metrics, DeepLearning, Optimization, GPU

MareArts ANPR Mobile App - Professional License Plate Recognition in Your Pocket

2025-12-30T14:00:00.000-08:00

📱 Introducing MareArts ANPR Mobile App - AI-Powered License Plate Recognition

We're excited to announce the MareArts ANPR Mobile App - bringing professional-grade license plate recognition to iOS! Experience the power of on-device AI for parking management, security checkpoints, and vehicle tracking, all in your pocket.

🎁 One License, Everything Included!

No additional license required! When you purchase a MareArts ANPR license, you get:

✅ Python SDK (unlimited desktop/server usage)
✅ iOS Mobile App (unlimited mobile usage)
✅ Road Objects Detection
✅ All future updates

One license = Use everywhere!

📲 Download Now

iOS: Download on App Store

Android: Coming Soon! 🚀

Search "marearts anpr" in the App Store

🎉 Free Trial Available!

✅ 100 scans per day - FREE forever!
✅ No credit card required
✅ No registration needed
✅ Try before you buy
✅ Login for unlimited scans (with license)

✨ Key Features

🔒 100% Privacy First

On-Device AI Processing - All recognition happens on your iPhone
No Cloud Upload - Your data stays on your device
No Analytics Tracking - We don't track your usage
Local Storage - Complete privacy and security

⚡ Lightning Fast

Real-time Detection - Instant plate recognition
Continuous Scanning - Auto-capture mode for busy entrances
Optimized for iOS - Smooth 60 FPS camera
No Internet Needed - Works completely offline

🌍 Multi-Region Support

🌍 Universal - All regions (default)
🇪🇺 Europe+ - EU, UK, Switzerland, Norway
🇰🇷 Korea - South Korea (한국)
🇺🇸 North America - USA, Canada, Mexico
🇨🇳 China - China (中国)

🧭 Five Powerful Tabs

1. 📷 Scan Page - Fast Recognition

Camera Modes:

Single Capture (⭕) - Take one photo at a time
Continuous Mode (🔄) - Auto-scan continuously
Cloud Mode (☁️) - Use cloud API for processing
Swipe left/right - Quick switch between modes

Smart Controls:

🔦 Flash toggle for low light
🔍 1x-5x zoom (pinch or tap)
📷 Front/back camera switch
✅ Tap to focus anywhere

Live Feedback:

Green/Red boxes show detected plates
Real-time plate number display
Confidence percentage shown
Whitelist/Blacklist status indicator

2. 🕐 Detections Page - Complete History

Three View Modes:

📋 List View

All captured plates chronologically
Grouped by: Today, Yesterday, This Week, etc.
Swipe left-to-right - Quick status change menu
Color badges: Green (whitelist), Red (blacklist), Orange (unknown)
Shows: Plate number, time, location, thumbnail

📸 Full Preview

Large plate image
Edit plate number (tap ✏️)
Detection + OCR confidence
GPS location & address
Quick actions: Copy, Delete, Add to Whitelist/Blacklist

🗺️ Map View

See all plates on interactive map
Smart clustering for nearby detections
Satellite/Road view toggle
Show all plate numbers as labels
Search by plate number
Tap markers for details

3. ✅ Rules Page - Whitelist & Blacklist

Smart Access Control:

Whitelist (Green) - Approved vehicles, success sound
Blacklist (Red) - Blocked vehicles, alert sound
Search in Real-time - Filter plates instantly
Partial matching: "ABC" finds "ABC-123"
Tab counters show totals
Swipe left to delete
+ button to add new plates

Use Cases:

🏢 Parking: Whitelist residents, blacklist violators
🔐 Security: Whitelist staff, blacklist banned vehicles
🚚 Delivery: Track known vehicles

4. 📊 Stats Page - Analytics & Insights

Overview Cards:

Total Scans (all-time)
Today's count
This Week / Month / Year

Top 10 Vehicles:

Most frequently detected plates
Tap to see all scans for that vehicle

Time Period Selector:

Today - Hourly breakdown
This Week - Monday to today
This Month - Current month
Year - Full year with year selector
Custom Range - Pick any dates

Status Filter:

View All, Whitelist only, Blacklist only, or Unknown

5. ⚙️ Settings Page - Fine-Tune Everything

Account:

Login with email + signature → Infinite scans!
Free trial: 100 scans/day (no login)
Shows expiry date

Notifications:

🔊 Sound alerts (success/alert/unknown)
📳 Vibration patterns (different for whitelist/blacklist)

Detection Settings:

Sync Thresholds - Link detection + OCR together
Detection Threshold (60-95%) - Minimum confidence
OCR Threshold (60-95%) - Text recognition confidence
Max Detections (1-10) - Plates per scan
Ignore Duplicates (0-60s) - Prevent repeated saves
Plate Region - Select specific region for accuracy

Storage:

Save images toggle
Clear history
Data retention: 7-365 days or Never

Location:

Enable GPS for map view
Shows address with detections

🎯 Real-World Use Cases

🏢 Parking Management

1. Add residents to Whitelist
2. Scan vehicles at entrance
3. Green = Allowed, Red = Blocked
4. Review violations in history
5. View statistics monthly

🔐 Security Checkpoint

1. Add approved vehicles to Whitelist
2. Add banned vehicles to Blacklist
3. Use Continuous Mode at gate
4. Audio/vibration alerts instantly
5. GPS tracking of all entries

🚗 Vehicle Tracking

1. Scan vehicles continuously
2. View complete history
3. Use Map to see locations
4. Export data for reports
5. Track Top 10 frequent visitors

🚚 Delivery Management

1. Track delivery vehicle arrivals
2. Time-stamped records
3. GPS location logging
4. Statistics for optimization
5. Whitelist known carriers

💡 Pro Tips for Best Results

✅ Best Practices:

Distance: 2-3 meters from vehicle
Angle: Perpendicular to plate (90 degrees)
Lighting: Good outdoor light (daytime best)
Focus: Tap plate area to focus before scanning
Stability: Hold steady while capturing

❌ Avoid:

Too far away (>5 meters)
Extreme angles
Low light conditions
Motion blur (moving vehicle)
Dirty or damaged plates

⚙️ Settings Recommendations:

Use Case	Detection	OCR	Max Plates	Region
High Accuracy (Parking/Security)	90%	90%	1	Specific
High Recall (Traffic Monitoring)	70%	70%	5	Universal
Balanced (General Use)	80%	80%	2	Specific

🔄 Latest Update (v1.5.16)

What's New:

✨ Year selector in Stats page
📅 Custom date range picker
🔍 Search in Rules page (real-time filtering)
👆 Swipe navigation between modes
🎨 UI improvements
🐛 Bug fixes and performance enhancements

🆚 Free vs Paid License

Feature	Free Trial	Paid License
Daily Scans	100/day	Unlimited ∞
All Features	✅	✅
5 Regions	✅	✅
Whitelist/Blacklist	✅	✅
History & Stats	✅	✅
Map View	✅	✅
Python SDK	❌	✅
Commercial Use	❌	✅
Support	Community	Priority

🌟 Why Choose MareArts ANPR Mobile App?

✅ Professional Grade - Same AI as enterprise SDK
✅ 100% Privacy - All processing on-device
✅ Lightning Fast - Real-time recognition
✅ Free Trial - 100 scans/day forever
✅ Multi-Region - Works worldwide
✅ Complete Solution - Whitelist, history, map, stats
✅ One License - Mobile + SDK included
✅ Regular Updates - New features monthly

📊 Technical Specs

Platform: iOS 14.0+ (Android coming soon)
AI Engine: On-device CoreML
Processing Time: ~0.1s per frame
Accuracy: 95%+ (optimal conditions)
Storage: ~200MB (with models)
Internet: Not required (offline capable)
Camera: All iOS cameras supported

🚀 Get Started in 3 Steps

# Step 1: Download from App Store
Search "marearts anpr" → Install

# Step 2: Open app and start scanning
Tap Scan → Point at license plate → Capture!

# Step 3 (Optional): Login for unlimited
Settings → Login → Enter email + signature → ∞ scans!

💼 Perfect For:

🏢 Parking Lot Managers - Automate access control
🔐 Security Guards - Quick vehicle verification
🏠 Residential Communities - Resident/visitor tracking
🏗️ Construction Sites - Authorized vehicle entry
🏨 Hotels - Valet parking management
🚚 Logistics - Delivery vehicle tracking
👮 Law Enforcement - Field plate scanning
🎓 Universities - Campus parking control

📞 Support & Resources

📧 Email: hello@marearts.com
🌐 Website: https://www.marearts.com
🛒 Buy License: ANPR Solution
📚 Full Guide: APP_GUIDE.md
🐛 Report Issues: GitHub Issues

🎁 Special Offer

Buy one license, get everything:

✅ Python SDK (desktop/server)

✅ iOS Mobile App (unlimited scans)

✅ Road Objects Detection

✅ All future updates

✅ Priority support

One payment, lifetime access!

💬 What Users Are Saying

"Perfect for our parking lot! 100 free scans/day is enough for testing, and the paid version is unlimited." - Parking Manager

"Finally, professional ANPR on mobile! On-device processing means no privacy concerns." - Security Director

"The whitelist/blacklist feature saves us so much time at our security gate." - Facility Manager

"Map view is genius! We can see exactly where each vehicle was spotted." - Operations Manager

🎯 Start Today!

📲 Download: Search "marearts anpr" on App Store
📷 Try Free: 100 scans/day, no credit card
🚀 Upgrade: Login for unlimited scans
💼 Deploy: Use in production with confidence

Professional license plate recognition is now in your pocket! 📱🚗

FREE ANPR/ALPR/LPR API - Try Before You Buy (1000 Requests/Day)

2025-12-30T13:57:00.000-08:00

🎁 FREE License Plate Recognition API - No Credit Card Required!

Want to try ANPR (Automatic Number Plate Recognition) / ALPR (Automatic License Plate Recognition) / LPR (License Plate Recognition) without buying a license? We offer a completely FREE test API with 1000 requests per day!

✨ What You Get (FREE!)

✅ 1000 requests/day - Perfect for testing and evaluation
✅ No credit card required
✅ No registration needed
✅ 5 regions supported: Korea, Europe, USA/Canada, China, Universal
✅ Multiple models to test (pico to large)
✅ Works instantly - just install and run!

🚀 Quick Start (30 Seconds)

# Install
pip install marearts-anpr

# Test immediately (NO CONFIG NEEDED!)
ma-anpr test-api your-plate.jpg --region eup

# That's it! 🎉

🌍 Supported Regions

Region Code	Coverage	Example
`kr`	South Korea	123가4567
`eup`	Europe (EU standards)	AB-123-CD
`na`	USA, Canada, Mexico	ABC-1234
`cn`	China	京A·12345
`univ`	Universal (all)	Any format

💻 Usage Examples

Command Line (Easiest!)

# European plates
ma-anpr test-api eu-plate.jpg --region eup

# Korean plates
ma-anpr test-api kr-plate.jpg --region kr

# US plates
ma-anpr test-api us-plate.jpg --region na

# Chinese plates
ma-anpr test-api cn-plate.jpg --region cn

# Unknown region? Use universal
ma-anpr test-api unknown-plate.jpg --region univ

Python Script

#!/usr/bin/env python3
import subprocess

def test_free_anpr(image_path, region='eup'):
    """Test free ANPR API - no credentials needed!"""
    
    cmd = f'ma-anpr test-api "{image_path}" --region {region}'
    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
    
    if result.returncode == 0:
        print(result.stdout)
        return True
    else:
        print(f"Error: {result.stderr}")
        return False

# Test European plate
test_free_anpr("plate.jpg", "eup")

# Test Korean plate
test_free_anpr("plate2.jpg", "kr")

Test Multiple Regions

# Test same image with different regions
for region in eup kr na cn univ; do
    echo "Testing $region..."
    ma-anpr test-api plate.jpg --region $region
done

🎯 Advanced Options

Try Different Models

# List all available models
ma-anpr test-api --list-models

# Try different detector models
ma-anpr test-api plate.jpg --region eup --detector small_640p_fp32
ma-anpr test-api plate.jpg --region eup --detector medium_640p_fp32
ma-anpr test-api plate.jpg --region eup --detector large_640p_fp32

# Try different OCR models
ma-anpr test-api plate.jpg --region eup --ocr small_fp32
ma-anpr test-api plate.jpg --region eup --ocr medium_fp32
ma-anpr test-api plate.jpg --region eup --ocr large_fp32

Batch Testing

# Test all images in a folder
for img in ./plates/*.jpg; do
    echo "Processing $img..."
    ma-anpr test-api "$img" --region eup
done

📊 Sample Output

{
  "results": [
    {
      "ocr": "AB-123-CD",
      "ocr_conf": 98.5,
      "ltrb": [120, 230, 380, 290],
      "ltrb_conf": 95
    }
  ],
  "ltrb_proc_sec": 0.15,
  "ocr_proc_sec": 0.03,
  "status": "success"
}

🆓 FREE vs PAID Comparison

Feature	FREE Test API	Paid License
Requests/Day	1000	Unlimited
Speed	~0.5s (cloud)	~0.02s (local GPU)
Internet Required	Yes	No (offline OK)
Configuration	None	One-time setup
Regions	All 5	All 5
Models	All	All
Price	$0	Contact sales

🎓 Use Cases for Free API

✅ Evaluation: Try before buying a license
✅ Prototyping: Build POC applications
✅ Testing: Test accuracy on your specific plates
✅ Education: Learn ANPR/ALPR/LPR technology
✅ Small Projects: Personal projects under 1000/day
✅ Region Testing: Find which region works best
✅ Model Comparison: Compare different model sizes

📈 When to Upgrade to Paid License?

Consider upgrading when you need:

🚀 Unlimited requests (no daily limit)
⚡ 10-100x faster processing (local GPU)
🔒 Offline operation (no internet needed)
🏢 Commercial deployment
📹 Real-time video processing
🎯 High-volume applications (>1000/day)

💡 Pro Tips

# 1. Use specific regions for best accuracy
ma-anpr test-api plate.jpg --region eup  # ✅ Better
ma-anpr test-api plate.jpg --region univ # ⚠️ OK but less accurate

# 2. Test different models to find best speed/accuracy balance
ma-anpr test-api plate.jpg --region eup --detector small_640p_fp32   # Faster
ma-anpr test-api plate.jpg --region eup --detector large_640p_fp32   # More accurate

# 3. Check remaining quota
ma-anpr test-api --check-quota

# 4. Get help
ma-anpr test-api --help

# 5. See all options
ma-anpr test-api --list-models

🔍 Troubleshooting

Rate limit exceeded?

# Wait until midnight UTC (resets daily)
# OR upgrade to paid license for unlimited requests

No plates detected?

# Try different detector models
ma-anpr test-api plate.jpg --region eup --detector large_640p_fp32

# Try universal region
ma-anpr test-api plate.jpg --region univ

Wrong text recognized?

# Make sure you're using correct region!
ma-anpr test-api plate.jpg --region kr   # For Korean plates
ma-anpr test-api plate.jpg --region eup  # For European plates

# Try larger OCR model
ma-anpr test-api plate.jpg --region eup --ocr large_fp32

📖 Complete Example Script

#!/usr/bin/env python3
"""
Free ANPR Test Script
Test license plate recognition with different regions and models
"""
import subprocess
import json

def test_anpr_free(image_path, region='eup', detector='medium_640p_fp32', ocr='medium_fp32'):
    """Test free ANPR API"""
    
    cmd = [
        'ma-anpr', 'test-api', image_path,
        '--region', region,
        '--detector', detector,
        '--ocr', ocr
    ]
    
    result = subprocess.run(cmd, capture_output=True, text=True)
    
    if result.returncode == 0:
        try:
            data = json.loads(result.stdout)
            return data
        except:
            return result.stdout
    else:
        return {"error": result.stderr}

# Test European plate with different models
image = "eu-plate.jpg"

print("Testing different detector models...")
for detector in ['small_640p_fp32', 'medium_640p_fp32', 'large_640p_fp32']:
    result = test_anpr_free(image, 'eup', detector)
    print(f"{detector}: {result}")

print("\nTesting different regions...")
for region in ['eup', 'kr', 'na', 'univ']:
    result = test_anpr_free(image, region)
    print(f"{region}: {result}")

🎯 Real-World Example

# Parking lot monitoring (Europe)
ma-anpr test-api parking-cam.jpg --region eup

# Toll booth (USA)
ma-anpr test-api toll-booth.jpg --region na

# Security gate (Korea)
ma-anpr test-api security-cam.jpg --region kr

# Traffic enforcement (China)
ma-anpr test-api traffic.jpg --region cn

# Multi-national (airport parking)
ma-anpr test-api airport.jpg --region univ

🌟 Why Choose MareArts ANPR?

✅ FREE tier available - Try before you buy!
✅ State-of-the-art AI - Latest deep learning models
✅ Multi-region support - Works worldwide
✅ Fast processing - ~0.02s with GPU
✅ Easy integration - Python, HTTP API, CLI
✅ Regular updates - New models and features
✅ Commercial ready - Production-grade quality

🚀 Get Started Now!

# Install (takes 10 seconds)
pip install marearts-anpr

# Test (takes 20 seconds)
ma-anpr test-api your-plate.jpg --region eup

# Celebrate! 🎉
# You just recognized your first license plate!

📞 Need More?

🌐 Website: https://www.marearts.com
🛒 Purchase: https://www.marearts.com/products/anpr
📚 Documentation: Full examples included with package
💬 Support: Technical support with paid license

💬 What People Are Saying

"Finally, an ANPR API I can test without entering my credit card!" - Developer

"1000 requests/day is perfect for my small parking lot project." - Small Business Owner

"Tested all 5 regions before buying. Confident in my purchase!" - System Integrator

🎁 Summary

MareArts ANPR offers a completely FREE test API with 1000 requests per day. No credit card, no registration, no strings attached. Just install and start recognizing license plates!

✅ Install: pip install marearts-anpr
✅ Test: ma-anpr test-api plate.jpg --region eup
✅ Evaluate: Try all regions and models
✅ Upgrade: When ready for unlimited use

Start your ANPR/ALPR/LPR journey today - completely FREE! 🚗📸

MareArts ANPR V14 - Advanced Manual Processing & Performance Tuning

2025-12-30T13:55:00.759-08:00

⚡ MareArts ANPR V14 - Advanced Manual Processing

Ready to take control? In this advanced guide, I'll show you how to manually process detections, measure performance, and optimize for your specific use case.

🎯 Why Manual Processing?

Full control over detection pipeline
Custom filtering and post-processing
Performance measurement and optimization
Integration with existing computer vision pipelines
Custom confidence thresholds per stage

🔧 Manual Detection & OCR Pipeline

from marearts_anpr import ma_anpr_detector_v14, ma_anpr_ocr_v14
import cv2
from PIL import Image
import time

# Initialize models
detector = ma_anpr_detector_v14(
    "medium_640p_fp32",
    user_name, serial_key, signature,
    backend="cpu",
    conf_thres=0.25,
    iou_thres=0.5
)

ocr = ma_anpr_ocr_v14("medium_fp32", "eup", user_name, serial_key, signature)

# Load image
img = cv2.imread("plate.jpg")

# Step 1: Detect license plates
start = time.time()
detections = detector.detector(img)
detection_time = time.time() - start

print(f"Detection time: {detection_time:.4f}s")
print(f"Found {len(detections)} plate(s)")

# Step 2: Process each detection
results = []
ocr_time = 0

for i, box_info in enumerate(detections):
    # Get bounding box
    bbox = box_info['bbox']  # [x1, y1, x2, y2]
    score = box_info['score']  # Detection confidence
    
    # Crop plate region
    x1, y1, x2, y2 = int(bbox[0]), int(bbox[1]), int(bbox[2]), int(bbox[3])
    crop = img[y1:y2, x1:x2]
    
    if crop.size == 0:
        continue
    
    # Convert to PIL for OCR
    pil_img = Image.fromarray(crop)
    if pil_img.mode != "RGB":
        pil_img = pil_img.convert("RGB")
    
    # Run OCR
    start = time.time()
    text, confidence = ocr.predict(pil_img)
    elapsed = time.time() - start
    ocr_time += elapsed
    
    print(f"Plate {i+1}: {text} ({confidence}%) - {elapsed:.4f}s")
    
    results.append({
        "ocr": text,
        "ocr_conf": confidence,
        "bbox": [x1, y1, x2, y2],
        "det_conf": int(score * 100)
    })

print(f"\nTotal time: {detection_time + ocr_time:.4f}s")

📊 Detection Object Structure

# detector.detector(img) returns list of dictionaries:
[
    {
        'bbox': [x1, y1, x2, y2],  # Bounding box coordinates
        'score': 0.95,              # Detection confidence (0-1)
        'class': 'license_plate'    # Object class
    },
    ...
]

# ocr.predict(pil_image) returns tuple:
("ABC1234", 98.5)  # (text, confidence_percentage)

🚀 Backend Performance Comparison

backends = ["cpu", "cuda"]  # Add "directml" on Windows

for backend_name in backends:
    try:
        print(f"\n🔧 Testing {backend_name}...")
        
        # Initialize with specific backend
        test_detector = ma_anpr_detector_v14(
            "medium_640p_fp32",
            user_name, serial_key, signature,
            backend=backend_name,
            conf_thres=0.25
        )
        
        # Measure performance
        start = time.time()
        detections = test_detector.detector(img)
        elapsed = time.time() - start
        
        print(f"Detected {len(detections)} plates in {elapsed:.4f}s")
        print(f"Speed: {1/elapsed:.1f} FPS")
        
    except Exception as e:
        print(f"⚠️ {backend_name} not available: {e}")

⚙️ Performance Results (Typical)

Backend	Detection	OCR	Total	FPS
CPU (i7)	~0.15s	~0.03s	~0.18s	~5.5
CUDA (RTX 3060)	~0.008s	~0.002s	~0.01s	~100

Result: GPU acceleration = 18x faster! 🚀

🎛️ Custom Filtering

# Filter detections by confidence
min_detection_conf = 0.50
min_ocr_conf = 80.0

filtered_results = []

for box_info in detections:
    if box_info['score'] < min_detection_conf:
        continue  # Skip low confidence detections
    
    # Process with OCR...
    text, conf = ocr.predict(plate_crop)
    
    if conf < min_ocr_conf:
        continue  # Skip low confidence OCR
    
    filtered_results.append({
        "text": text,
        "confidence": conf,
        "bbox": bbox
    })

print(f"After filtering: {len(filtered_results)} high-confidence plates")

🎨 Custom Visualization

import cv2

# Draw boxes and text on image
for result in results:
    x1, y1, x2, y2 = result['bbox']
    text = result['ocr']
    conf = result['ocr_conf']
    
    # Draw rectangle
    cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2)
    
    # Draw text
    label = f"{text} ({conf}%)"
    cv2.putText(img, label, (x1, y1-10), 
                cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 2)

cv2.imwrite("result.jpg", img)

📹 Video Processing Pipeline

import cv2

# Open video
cap = cv2.VideoCapture("traffic.mp4")

frame_count = 0
plate_history = {}

while cap.isOpened():
    ret, frame = cap.read()
    if not ret:
        break
    
    frame_count += 1
    
    # Process every N frames (skip frames for speed)
    if frame_count % 5 != 0:
        continue
    
    # Detect plates
    detections = detector.detector(frame)
    
    for det in detections:
        bbox = det['bbox']
        x1, y1, x2, y2 = int(bbox[0]), int(bbox[1]), int(bbox[2]), int(bbox[3])
        crop = frame[y1:y2, x1:x2]
        
        if crop.size == 0:
            continue
        
        # OCR
        pil_crop = Image.fromarray(cv2.cvtColor(crop, cv2.COLOR_BGR2RGB))
        text, conf = ocr.predict(pil_crop)
        
        # Track plates (simple tracking by position)
        plate_id = f"{x1//50}_{y1//50}"
        
        if plate_id not in plate_history:
            plate_history[plate_id] = []
        plate_history[plate_id].append(text)
        
        # Draw
        cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2)
        cv2.putText(frame, text, (x1, y1-10), 
                    cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 2)
    
    cv2.imshow('ANPR', frame)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

# Print detected plates
print("\nDetected plates:")
for plate_id, texts in plate_history.items():
    # Most common text for this plate
    most_common = max(set(texts), key=texts.count)
    print(f"  {most_common} (seen {len(texts)} times)")

💾 Batch Processing from Directory

import os
from pathlib import Path

image_dir = Path("./images")
results_all = {}

for img_path in image_dir.glob("*.jpg"):
    print(f"Processing {img_path.name}...")
    
    img = cv2.imread(str(img_path))
    detections = detector.detector(img)
    
    plates = []
    for det in detections:
        bbox = det['bbox']
        x1, y1, x2, y2 = int(bbox[0]), int(bbox[1]), int(bbox[2]), int(bbox[3])
        crop = img[y1:y2, x1:x2]
        
        if crop.size > 0:
            pil_crop = Image.fromarray(cv2.cvtColor(crop, cv2.COLOR_BGR2RGB))
            text, conf = ocr.predict(pil_crop)
            plates.append({"text": text, "conf": conf})
    
    results_all[img_path.name] = plates

# Save results
import json
with open("results.json", "w") as f:
    json.dump(results_all, f, indent=2)

print(f"\nProcessed {len(results_all)} images")

🎓 Advanced Tips

GPU Memory: Use cuda backend for 10-100x speedup
Confidence Tuning: Lower conf_thres to 0.15-0.20 for difficult images
IOU Threshold: Increase iou_thres to reduce duplicate detections
Batch Processing: Process multiple crops at once with ocr.predict([img1, img2, ...])
Frame Skipping: Process every Nth frame in videos for speed
Multi-threading: Run detector and OCR in separate threads

🔍 Troubleshooting

No detections?

Lower conf_thres to 0.15
Try larger model (large_640p_fp32)
Check image quality and resolution

Wrong OCR results?

Verify correct region (kr, eup, na, cn)
Try larger OCR model (large_fp32)
Check plate crop quality

Slow performance?

Use GPU backend (cuda or directml)
Use smaller models (small_640p_fp32, small_fp32)
Skip video frames
Batch process multiple images

💡 Conclusion

Manual processing gives you complete control over the ANPR pipeline. Use it for:

✅ Custom filtering and validation
✅ Performance optimization
✅ Video stream processing
✅ Integration with existing CV pipelines
✅ Advanced visualization and tracking

Happy optimizing! ⚡🚗

MareArts ANPR V14 - Easy 3-Method Integration (File, OpenCV, PIL)

2025-12-30T13:54:14.772-08:00

🚀 MareArts ANPR V14 - Getting Started in 3 Easy Ways

Welcome to MareArts ANPR V14! Today I'll show you how to process license plates using three different methods: from files, OpenCV, or PIL. Plus, the new multi-region switching feature that saves memory.

📦 Quick Setup

pip install marearts-anpr
ma-anpr config  # Enter your credentials

🎯 Basic Usage - Three Input Methods

from marearts_anpr import ma_anpr_detector_v14, ma_anpr_ocr_v14
from marearts_anpr import marearts_anpr_from_image_file, marearts_anpr_from_cv2, marearts_anpr_from_pil
import cv2
from PIL import Image

# Initialize detector and OCR (once)
detector = ma_anpr_detector_v14(
    "medium_640p_fp32",
    user_name, serial_key, signature,
    backend="cpu",
    conf_thres=0.25
)

ocr = ma_anpr_ocr_v14("medium_fp32", "eup", user_name, serial_key, signature)

# Method 1: From file (easiest!)
result = marearts_anpr_from_image_file(detector, ocr, "plate.jpg")
print(result)

# Method 2: From OpenCV
img = cv2.imread("plate.jpg")
result = marearts_anpr_from_cv2(detector, ocr, img)
print(result)

# Method 3: From PIL
pil_img = Image.open("plate.jpg")
result = marearts_anpr_from_pil(detector, ocr, pil_img)
print(result)

🌍 NEW: Dynamic Region Switching (Saves 180MB!)

Previously, you needed separate OCR instances for each region. Now use set_region():

# Initialize once with any region
ocr = ma_anpr_ocr_v14("medium_fp32", "eup", user_name, serial_key, signature)

# Switch regions instantly!
ocr.set_region('eup')   # European plates
result = marearts_anpr_from_image_file(detector, ocr, "eu-plate.jpg")

ocr.set_region('kr')    # Korean plates  
result = marearts_anpr_from_image_file(detector, ocr, "kr-plate.jpg")

ocr.set_region('na')    # North American plates
result = marearts_anpr_from_image_file(detector, ocr, "us-plate.jpg")

ocr.set_region('cn')    # Chinese plates
ocr.set_region('univ')  # Universal

Memory savings: Single instance vs multiple = ~180MB saved per additional region!

📊 Available Regions

kr - Korean plates (123가4567)
eup - European plates (EU standards)
na - North American plates (USA, Canada, Mexico)
cn - Chinese plates (京A·12345)
univ - Universal (all regions, slightly lower accuracy)

🎨 Batch Processing

# Detect plates from multiple images
img1 = cv2.imread("plate1.jpg")
img2 = cv2.imread("plate2.jpg")

detections1 = detector.detector(img1)
detections2 = detector.detector(img2)

# Collect plate crops
plates = []
for det in detections1:
    bbox = det['bbox']
    crop = img1[int(bbox[1]):int(bbox[3]), int(bbox[0]):int(bbox[2])]
    plates.append(Image.fromarray(cv2.cvtColor(crop, cv2.COLOR_BGR2RGB)))

for det in detections2:
    bbox = det['bbox']
    crop = img2[int(bbox[1]):int(bbox[3]), int(bbox[0]):int(bbox[2])]
    plates.append(Image.fromarray(cv2.cvtColor(crop, cv2.COLOR_BGR2RGB)))

# Process all plates at once!
results = ocr.predict(plates)  # Pass list of images

for i, (text, conf) in enumerate(results):
    print(f"Plate {i+1}: {text} ({conf}%)")

🔧 Model Options

Detector models:

pico_640p_fp32 - Smallest, fastest
micro_640p_fp32
small_640p_fp32
medium_640p_fp32 - Recommended balance
large_640p_fp32 - Most accurate

OCR models:

pico_fp32 - Fastest
micro_fp32
small_fp32
medium_fp32 - Recommended
large_fp32 - Best accuracy

Backends:

cpu - Works everywhere
cuda - NVIDIA GPU (10-100x faster!)
directml - Windows GPU

📝 Complete Example

from marearts_anpr import ma_anpr_detector_v14, ma_anpr_ocr_v14
from marearts_anpr import marearts_anpr_from_image_file
import os

# Load credentials
user_name = os.getenv('MAREARTS_ANPR_USERNAME')
serial_key = os.getenv('MAREARTS_ANPR_SERIAL_KEY')
signature = os.getenv('MAREARTS_ANPR_SIGNATURE')

# Initialize models
detector = ma_anpr_detector_v14(
    "medium_640p_fp32",
    user_name, serial_key, signature,
    backend="cpu",
    conf_thres=0.25,
    iou_thres=0.5
)

ocr = ma_anpr_ocr_v14("medium_fp32", "eup", user_name, serial_key, signature)

# Process European plate
print("Processing European plate...")
result = marearts_anpr_from_image_file(detector, ocr, "eu-plate.jpg")
print(result)

# Switch to Korean region
ocr.set_region('kr')
print("\nProcessing Korean plate...")
result = marearts_anpr_from_image_file(detector, ocr, "kr-plate.jpg")
print(result)

💡 Key Takeaways

✅ Three input methods: file, OpenCV, PIL
✅ Dynamic region switching saves memory
✅ Batch processing for efficiency
✅ Multiple model sizes for different needs
✅ GPU acceleration available

🔗 Try It Free!

No license yet? Try the free API (1000 requests/day):

ma-anpr test-api your-plate.jpg --region eup

Happy coding! 🚗📸

Labels:

MareArts ANPR HTTP Server Integration - Load Once, Process Fast

2025-12-30T13:43:00.000-08:00

🚀 MareArts ANPR HTTP Server - Easy Integration for Any Platform

One of the biggest challenges in ANPR (Automatic Number Plate Recognition) integration is the model loading time. Loading deep learning models can take 20+ seconds, which is impractical if you reload them for every image. Today, I'm sharing our solution: a lightweight HTTP server that loads models once and processes images from memory.

📊 The Problem: Model Loading Overhead

Model loading: ~22 seconds (one time)
Image processing: ~0.03 seconds per image
Traditional approach: Load models for EVERY image = slow!
Server approach: Load models ONCE, process thousands of images = fast!

✨ The Solution: Simple HTTP Server

Our simple_server.py creates a FastAPI server that:

Loads ANPR models once at startup
Accepts images through 3 different methods (file upload, raw bytes, base64)
Processes images directly from memory (no disk I/O)
Perfect for integration with C#, Visual Studio, or any HTTP client

🔧 Server Implementation

Here's the core server code:

#!/usr/bin/env python3
from fastapi import FastAPI, File, UploadFile, Request
from fastapi.responses import JSONResponse
from marearts_anpr import ma_anpr_detector_v14, ma_anpr_ocr_v14, marearts_anpr_from_cv2
import cv2
import numpy as np

# ============================================================================
# LOAD MODELS (Once at startup)
# ============================================================================

detector = ma_anpr_detector_v14(
    "medium_640p_fp32", USER, KEY, SIG,
    backend="cpu",  # or "cuda" for GPU
    conf_thres=0.20
)

ocr = ma_anpr_ocr_v14("small_fp32", "eup", USER, KEY, SIG, backend="cpu")

# ============================================================================
# CREATE SERVER
# ============================================================================

app = FastAPI(title="MareArts ANPR Server")

@app.post("/detect")
async def detect_plate_file(image: UploadFile = File(...)):
    """Method 1: Upload image file (multipart/form-data)"""
    image_bytes = await image.read()
    return process_image_bytes(image_bytes)

@app.post("/detect/binary")
async def detect_plate_binary(request: Request):
    """Method 2: Send raw image bytes"""
    image_bytes = await request.body()
    return process_image_bytes(image_bytes)

@app.post("/detect/base64")
async def detect_plate_base64(data: Base64Image):
    """Method 3: Send base64 encoded image"""
    image_bytes = base64.b64decode(data.image)
    return process_image_bytes(image_bytes)

def process_image_bytes(image_bytes):
    """Process image from bytes"""
    nparr = np.frombuffer(image_bytes, np.uint8)
    img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
    result = marearts_anpr_from_cv2(detector, ocr, img)
    return result

💻 Client Examples

Python Client (test_server.py)

import requests

def test_server(image_path, server_url="http://localhost:8000"):
    # Health check
    response = requests.get(f"{server_url}/health")
    print(response.json())
    
    # Detect plates
    with open(image_path, 'rb') as f:
        files = {'image': f}
        response = requests.post(f"{server_url}/detect", files=files)
    
    result = response.json()
    if result.get('results'):
        print(f"✅ Detected {len(result['results'])} plate(s):")
        for plate in result['results']:
            print(f"  • {plate['ocr']} ({plate['ocr_conf']}%)")

cURL Command Line

# Method 1: File upload
curl -X POST http://localhost:8000/detect -F "image=@plate.jpg"

# Method 2: Binary data
curl -X POST http://localhost:8000/detect/binary --data-binary "@plate.jpg"

# Health check
curl http://localhost:8000/health

C# / Visual Studio Integration

using System.Net.Http;

// Example 1: Send raw bytes
var client = new HttpClient();
var content = new ByteArrayContent(imageBytes);
content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
var response = await client.PostAsync("http://localhost:8000/detect/binary", content);

// Example 2: Send base64 JSON
var base64Image = Convert.ToBase64String(imageBytes);
var json = JsonSerializer.Serialize(new { image = base64Image });
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("http://localhost:8000/detect/base64", content);

🎯 Usage Guide

Step 1: Install dependencies

pip install marearts-anpr fastapi uvicorn python-multipart
ma-anpr config  # Configure your credentials

Step 2: Start the server (Terminal 1)

python simple_server.py
# Models load once (~22s), then server waits for requests

Step 3: Send images (Terminal 2 or your application)

python test_server.py your_image.jpg

🌟 Key Benefits

Load Once, Use Forever: Models load at startup, not per request
Memory Processing: No disk I/O, process images from RAM
Multiple Input Methods: File upload, raw bytes, or base64
Cross-Platform: Works with Python, C#, JavaScript, or any HTTP client
Production Ready: Built on FastAPI with async support
Easy Integration: RESTful API with JSON responses

📈 Performance Comparison

Approach	First Image	Subsequent Images
Traditional (load per image)	~22 seconds	~22 seconds each
HTTP Server (load once)	~22 seconds	~0.03 seconds each

Result: 700x faster for subsequent images! 🚀

🔗 Available Endpoints

POST /detect - Upload file (multipart/form-data)
POST /detect/binary - Send raw bytes (application/octet-stream)
POST /detect/base64 - Send base64 JSON
GET / - Server info
GET /health - Health check

🎓 When to Use This

✅ Integrating ANPR into C# / Visual Studio projects
✅ Building web applications with ANPR
✅ Processing multiple images efficiently
✅ Microservice architecture
✅ Real-time video processing

📦 Complete Example Package

All code is available in our SDK:

simple_server.py - HTTP server (202 lines)
test_server.py - Python client test (52 lines)
README.md - Complete documentation

Install: pip install marearts-anpr

🔐 Configuration

The server uses environment variables for credentials:

# Configure once
ma-anpr config

# Credentials are stored in ~/.marearts/.marearts_env
# Server automatically loads from environment variables

💡 Conclusion

This HTTP server approach makes ANPR integration incredibly simple. Whether you're building a C# desktop application, a web service, or a microservice architecture, you can now integrate license plate recognition with just a few HTTP calls. No need to worry about Python integration complexity - just send HTTP requests!

The key insight: separate model loading from image processing. Load once, process thousands of times.

Happy coding! 🚗📸

Shows difference between functions, concepts, and constexpr variables

2025-12-16T01:46:00.000-08:00

// study.marearts.com: When to use () and when not to in C++
// Shows difference between functions, concepts, and constexpr variables

#include <iostream>
#include <concepts>

// ==========================================
// CASE 1: FUNCTION - NEEDS ()
// ==========================================

// Regular function
bool isPositiveFunction(int x) {
    return x > 0;
}

// constexpr function
constexpr bool isPositiveConstexpr(int x) {
    return x > 0;
}

// consteval function (C++20)
template <typename T>
consteval bool IsIntegerFunction() {
    return std::is_integral_v<T>;
}

void example1() {
    std::cout << "\n=== CASE 1: FUNCTIONS - MUST USE () === study.marearts.com" << std::endl;
    
    // Functions NEED ()
    if (isPositiveFunction(5)) {  // ← () required
        std::cout << "✓ 5 is positive (function call)" << std::endl;
    }
    
    if constexpr (IsIntegerFunction<int>()) {  // ← () required
        std::cout << "✓ int is integer (consteval function call)" << std::endl;
    }
    
    // ❌ This would be ERROR:
    // if (isPositiveFunction) { }  // ERROR: can't use function without calling it
}

// ==========================================
// CASE 2: CONCEPT - NO ()
// ==========================================

// Concept (C++20)
template <typename T>
concept IsInteger = std::is_integral_v<T>;

void example2() {
    std::cout << "\n=== CASE 2: CONCEPTS - NO () === study.marearts.com" << std::endl;
    
    // Concepts don't use ()
    if constexpr (IsInteger<int>) {  // ← NO () - it's a concept, not function
        std::cout << "✓ int is integer (concept check)" << std::endl;
    }
    
    // ❌ This would be ERROR:
    // if constexpr (IsInteger<int>()) { }  // ERROR: concept is not a function
}

// ==========================================
// CASE 3: CONSTEXPR VARIABLE - NO ()
// ==========================================

// constexpr variable
template <typename T>
constexpr bool is_integer_variable = std::is_integral_v<T>;

void example3() {
    std::cout << "\n=== CASE 3: CONSTEXPR VARIABLES - NO () === study.marearts.com" << std::endl;
    
    // constexpr variables don't use ()
    if constexpr (is_integer_variable<int>) {  // ← NO () - it's a variable, not function
        std::cout << "✓ int is integer (constexpr variable)" << std::endl;
    }
    
    // ❌ This would be ERROR:
    // if constexpr (is_integer_variable<int>()) { }  // ERROR: variable is not callable
}

// ==========================================
// COMPARISON IN SAME CONTEXT
// ==========================================

// All three doing the same thing, different ways:
template <typename T>
consteval bool IsPositiveFunction() { return sizeof(T) > 0; }  // Function

template <typename T>
concept IsPositiveConcept = sizeof(T) > 0;  // Concept

template <typename T>
constexpr bool is_positive_variable = sizeof(T) > 0;  // Variable

void example4() {
    std::cout << "\n=== COMPARISON: FUNCTION vs CONCEPT vs VARIABLE === study.marearts.com" << std::endl;
    
    // Function needs ()
    if constexpr (IsPositiveFunction<int>()) {  // ← () YES
        std::cout << "✓ Function: use ()" << std::endl;
    }
    
    // Concept doesn't use ()
    if constexpr (IsPositiveConcept<int>) {  // ← () NO
        std::cout << "✓ Concept: no ()" << std::endl;
    }
    
    // Variable doesn't use ()
    if constexpr (is_positive_variable<int>) {  // ← () NO
        std::cout << "✓ Variable: no ()" << std::endl;
    }
}

// ==========================================
// DISPATCHER PATTERN EXAMPLE
// ==========================================

// Like CK Builder dispatcher!

// Old way: consteval functions (need ())
template <typename T>
consteval bool IsSpecialAlgorithmFunction() { return sizeof(T) > 4; }

// New way: concepts (no ())
template <typename T>
concept IsSpecialAlgorithmConcept = sizeof(T) > 4;

template <typename T>
void dispatch_old_way() {
    if constexpr (IsSpecialAlgorithmFunction<T>()) {  // ← () YES (function)
        std::cout << "Old dispatcher: Special algorithm (function)" << std::endl;
    }
    else {
        std::cout << "Old dispatcher: Normal algorithm" << std::endl;
    }
}

template <typename T>
void dispatch_new_way() {
    if constexpr (IsSpecialAlgorithmConcept<T>) {  // ← () NO (concept)
        std::cout << "New dispatcher: Special algorithm (concept)" << std::endl;
    }
    else {
        std::cout << "New dispatcher: Normal algorithm" << std::endl;
    }
}

void example5() {
    std::cout << "\n=== DISPATCHER PATTERN (Like CK Builder) ===" << std::endl;
    
    dispatch_old_way<long>();   // Old way with functions
    dispatch_new_way<long>();   // New way with concepts
}

// ==========================================
// MAIN
// ==========================================

int main() {
    std::cout << "=== When to Use () in C++ === study.marearts.com" << std::endl;
    
    example1();  // Functions
    example2();  // Concepts
    example3();  // Variables
    example4();  // Comparison
    example5();  // Dispatcher pattern
    
    std::cout << "\n=== SUMMARY ===" << std::endl;
    std::cout << "FUNCTION:   Use ()  → IsXXX<T>()" << std::endl;
    std::cout << "CONCEPT:    No ()   → IsXXX<T>" << std::endl;
    std::cout << "VARIABLE:   No ()   → is_xxx<T>" << std::endl;
    
    return 0;
}

/*
TO COMPILE:
g++ -std=c++20 when_to_use_parentheses.cpp -o when_to_use_parentheses
./when_to_use_parentheses

OUTPUT:
Functions need ()
Concepts don't need ()
Variables don't need ()
*/

Compile-Time vs Runtime

Feature	When Evaluated	Use Case
concept	✅ Compile-time ONLY	Type constraints
constexpr	⚠️ Compile OR runtime	Flexible
consteval	✅ Compile-time ONLY	Force compile-time

1. Concept - Always Compile Time ✅

template <typename T>

concept IsInteger = std::is_integral_v<T>;

// Checked at COMPILE TIME:

if constexpr (IsInteger<int>) { // ← Compiler checks this

// This code exists in binary

}

else {

// This code REMOVED from binary

}

Compiler decides which branch to include in the compiled program.

2. constexpr - Can Be Either

Compiler decides based on context!

3. consteval - MUST Be Compile Time ✅

C++20, consteval and comma operator example code

2025-12-15T05:51:00.000-08:00

// (study.marearts.com): Compile-time Validation Pattern with consteval + static_assert
// C++20 required for consteval

#include <iostream>

// ==========================================
// EXAMPLE 1: Simple consteval function
// ==========================================

// consteval = MUST run at compile time (C++20 feature)
consteval int add(int a, int b) {
    return a + b;
}

void example1() {
    // This is evaluated at COMPILE TIME!
    constexpr int result = add(5, 3);  // Compiler computes: 5 + 3 = 8
    std::cout << "(study.marearts.com) Example 1 : 5 + 3 = " << result << std::endl;
}

// ==========================================
// EXAMPLE 2: Comma operator
// ==========================================

void printMessage() {
    std::cout << "Message printed!" << std::endl;
    // Returns nothing (void)
}

void example2() {
    // Comma operator: (A, B) evaluates A, then returns B
    int x = (printMessage(), 42);
    //       ↓                ↓
    //   Calls function    Returns 42
    
    std::cout << "(study.marearts.com) Example 2: x = " << x << std::endl;  // x = 42
}

// ==========================================
// EXAMPLE 3: consteval with static_assert (VALIDATION!)
// ==========================================

// Validation function - checks if number is positive
template <int N>
consteval void ValidatePositive() {
    static_assert(N > 0, "ERROR: Number must be positive!");
    // If N <= 0, compilation FAILS here with error message
    // If N > 0, function completes
}

// Example struct that validates its template parameter
template <int Number>
struct PositiveNumber {
    // This line forces validation at compile time!
    // If Number is negative, compilation fails
    static constexpr auto kValidation = (ValidatePositive<Number>(), 0);
    //                                   ↓                           ↓
    //                           Run checks (compile time)      Return 0
    
    int value = Number;
    
    void print() {
        std::cout << "Positive number: " << value << std::endl;
    }
};

void example3() {
    std::cout << "\n(study.marearts.com) Example 3: Compile-time validation" << std::endl;
    
    // ✅ This COMPILES (5 > 0)
    PositiveNumber<5> good;
    good.print();
    
    // ❌ This would FAIL to compile (uncomment to see error!)
    // PositiveNumber<-3> bad;  
    // Error: static assertion failed: ERROR: Number must be positive!
    
    std::cout << "✓ Validation passed at compile time!" << std::endl;
}

// ==========================================
// EXAMPLE 4: Real-world pattern (like our code!)
// ==========================================

enum class OperationType {
    PASS_THROUGH,
    ADD_ONE,
    MULTIPLY_TWO
};

// Configuration struct (like our ConvSignature)
template <OperationType Op>
struct Config {
    static constexpr OperationType operation = Op;
};

// Validation: Only allow PASS_THROUGH
template <auto Cfg>
consteval void ValidateConfig() {
    static_assert(Cfg.operation == OperationType::PASS_THROUGH,
                  "ERROR: Simple implementation only supports PASS_THROUGH!");
}

// Simple implementation (like our ReferenceForwardFactory)
template <auto CONFIG>
struct SimpleProcessor {
    // Validate at compile time!
    static constexpr auto kValidation = (ValidateConfig<CONFIG>(), 0);
    
    void process(int x) {
        std::cout << "Processing " << x << " (PassThrough only)" << std::endl;
    }
};

void example4() {
    std::cout << "\nExample 4: Real-world validation pattern" << std::endl;
    
    // ✅ This COMPILES (uses PASS_THROUGH)
    constexpr Config<OperationType::PASS_THROUGH> good_config;
    SimpleProcessor<good_config> processor;
    processor.process(42);
    
    // ❌ This would FAIL to compile (uncomment to see error!)
    // constexpr Config<OperationType::ADD_ONE> bad_config;
    // SimpleProcessor<bad_config> bad_processor;
    // Error: static assertion failed: Simple implementation only supports PASS_THROUGH!
    
    std::cout << "✓ Config validation passed!" << std::endl;
}

// ==========================================
// MAIN
// ==========================================

int main() {
    std::cout << "=== Compile-Time Validation Study ===" << std::endl;
    
    example1();  // consteval basics
    example2();  // comma operator
    example3();  // consteval + static_assert
    example4();  // real-world pattern
    
    std::cout << "\n✓ All examples passed!" << std::endl;
    return 0;
}

KEY CONCEPTS:

1. consteval (C++20):
   - Function MUST execute at compile time
   - Cannot be called at runtime

2. static_assert (C++11):
   - Checks condition at compile time
   - If false, compilation FAILS with error message

3. Comma operator:
   - (A, B) executes A, then returns B
   - Used to "call void function" in member initialization

4. The Pattern:
   static constexpr auto kValidation = (ValidateFunction<>(), 0);
   - Forces compile-time validation
   - Returns 0 if validation passes
   - Compilation fails if validation fails

TO COMPILE:
g++ -std=c++20 compile_time_validation.cpp -o compile_time_validation
./compile_time_validation

=== Compile-Time Validation Study ===
Example 1: 5 + 3 = 8
Message printed!
Example 2: x = 42

Example 3: Compile-time validation
Positive number: 5
✓ Validation passed at compile time!

Example 4: Real-world validation pattern
Processing 42 (PassThrough only)
✓ Config validation passed!

✓ All examples passed!

Summary: C++ Version Requirements

Feature	C++ Version	What It Does
consteval	C++20	Function MUST run at compile time
static_assert	C++11	Compile-time assertion check
constexpr	C++11	CAN run at compile time
Comma operator	C++98	(A, B) returns B

Our pattern needs: C++20 (for consteval)

Quick Reference

✅ Good Case (Passes):

❌ Bad Case (Fails):

To Experiment

Try uncommenting line 75 in the study file:

Then compile:

You'll see the compile error!

Why Can't We Use Functions in "requires"? #04_why_not_both.cpp

2025-12-12T06:24:00.000-08:00

// Example 4: Why Can't We Use Functions in "requires"?
// This shows the difference between concepts and constexpr functions

#include <iostream>
#include <concepts>

// ==========================================
// Define types
// ==========================================

struct Dog {
    const char* name = "MareArts.com";
};

struct Cat {
    const char* name = "Whiskers";
};

// ==========================================
// METHOD 1: Using CONCEPT (works in requires)
// ==========================================

template <typename T>
concept HasName = requires(T t) {
    { t.name } -> std::convertible_to<const char*>;
};

template <typename T>
    requires HasName<T>  // ✅ Works! Concept in requires clause
void printNameWithConcept(T animal) {
    std::cout << "Name: " << animal.name << "\n";
}

// ==========================================
// METHOD 2: Using CONSTEXPR FUNCTION (doesn't work in requires!)
// ==========================================

template <typename T>
consteval bool hasNameFunction() {
    return requires(T t) {
        { t.name } -> std::convertible_to<const char*>;
    };
}

// ❌ This won't compile!
// template <typename T>
//     requires hasNameFunction<T>()  // ❌ ERROR: Can't use function in requires!
// void printNameWithFunction(T animal) {
//     std::cout << "Name: " << animal.name << "\n";
// }

// ==========================================
// METHOD 3: Using CONSTEXPR FUNCTION with "if constexpr" (works!)
// ==========================================

template <typename T>
void printNameIfConstexpr(T animal) {
    // ✅ Works! Function in "if constexpr"
    if constexpr (hasNameFunction<T>()) {
        std::cout << "Name: " << animal.name << "\n";
    }
    else {
        std::cout << "No name!\n";
    }
}

// ==========================================
// WHY THE DIFFERENCE?
// ==========================================

/*
"requires" clause:
    - Part of template declaration
    - Needs a CONCEPT (compile-time constraint)
    - Determines if template can even exist
    - Syntax: template <...> requires CONCEPT<T>

"if constexpr":
    - Inside function body
    - Can use ANY compile-time expression
    - Chooses which code branch to keep
    - Syntax: if constexpr (EXPRESSION)
*/

// ==========================================
// Main
// ==========================================

int main() {
    Dog dog;
    Cat cat;
    
    std::cout << "=== Using Concept in 'requires' ===\n";
    printNameWithConcept(dog);
    printNameWithConcept(cat);
    
    std::cout << "\n=== Using Function in 'if constexpr' ===\n";
    printNameIfConstexpr(dog);
    printNameIfConstexpr(cat);
    
    return 0;
}

/*
SUMMARY - Where Can You Use What?

┌──────────────────────────┬──────────────┬──────────────────┐
│                          │  "requires"  │  "if constexpr"  │
├──────────────────────────┼──────────────┼──────────────────┤
│ Concept                  │      ✅      │        ✅        │
│ Constexpr Function       │      ❌      │        ✅        │
│ Any compile-time expr    │      ❌      │        ✅        │
└──────────────────────────┴──────────────┴──────────────────┘

This is why:
- Factories use concepts in "requires" (IsReferenceAlgorithm concept)
- Dispatcher uses constexpr functions in "if constexpr" (IsReferenceAlgorithm())

After refactoring:
- We removed the concept (not needed anymore)
- Kept the constexpr function (used in dispatcher)
- Removed algorithm checks from factory "requires" clauses
*/

### 4. Why Not Both? (04_why_not_both.cpp)
**What it teaches:** Why we can't mix them up

```
┌──────────────────────────┬──────────────┬──────────────────┐
│                          │  "requires"  │  "if constexpr"  │
├──────────────────────────┼──────────────┼──────────────────┤
│ Concept                  │      ✅      │        ✅        │
│ Constexpr Function       │      ❌      │        ✅        │
└──────────────────────────┴──────────────┴──────────────────┘
```

**Key Point:** Constexpr functions DON'T work in `requires` clauses!

Now #1~#4 series is done.

g++ -std=c++20 01_concept_basics.cpp -o 01_concepts
g++ -std=c++20 02_constexpr_functions.cpp -o 02_constexpr
g++ -std=c++20 03_dispatcher_pattern.cpp -o 03_dispatcher
g++ -std=c++20 04_why_not_both.cpp -o 04_why

recap!

## Key Takeaways 🎯

1. **Concepts** check if types have certain features
   - Used in `requires` clauses
   - Like: `requires HasName<T>`

2. **Constexpr functions** run at compile time
   - Used in `if constexpr` statements
   - Like: `if constexpr (isDog<T>())`

3. **Dispatcher pattern** separates concerns:
   - **Dispatcher** checks algorithm type (using `if constexpr` + constexpr functions)
   - **Factory** checks direction only (using `requires` + concepts)

4. **You can't mix them:**
   - Constexpr functions DON'T work in `requires` clauses
   - That's why we removed the algorithm check from factory `requires` clauses!

Thank you!

study.marearts.com

Dispatcher Pattern Example #03_dispatcher_pattern.cpp

2025-12-12T06:06:00.000-08:00

// Example 3: The Dispatcher Pattern (Like CK Convolution!)
// This is exactly how the convolution dispatcher works!

#include <iostream>
#include <concepts>

// ==========================================
// Step 1: Define algorithm types
// ==========================================

enum class AlgorithmType {
    SIMPLE,
    FAST,
    PARALLEL
};

// Simple algorithm
struct SimpleAlgorithm {
    static constexpr AlgorithmType type = AlgorithmType::SIMPLE;
};

// Fast algorithm
struct FastAlgorithm {
    static constexpr AlgorithmType type = AlgorithmType::FAST;
    int optimization_level = 3;
};

// Parallel algorithm
struct ParallelAlgorithm {
    static constexpr AlgorithmType type = AlgorithmType::PARALLEL;
    int num_threads = 8;
};

// ==========================================
// Step 2: Algorithm detection functions (like IsReferenceAlgorithm!)
// ==========================================

// Check if algorithm is Simple
template <typename T>
consteval bool IsSimpleAlgorithm() {
    return std::is_same_v<T, SimpleAlgorithm>;
}

// Check if algorithm is Fast
template <typename T>
consteval bool IsFastAlgorithm() {
    return std::is_same_v<T, FastAlgorithm>;
}

// Check if algorithm is Parallel
template <typename T>
consteval bool IsParallelAlgorithm() {
    return std::is_same_v<T, ParallelAlgorithm>;
}

// ==========================================
// Step 3: Factories (only check direction, not algorithm!)
// ==========================================

enum class Direction {
    FORWARD,
    BACKWARD
};

// Factory for Simple Algorithm
template <Direction DIR, typename Algorithm>
    requires (DIR == Direction::FORWARD)  // ← Only check direction!
struct SimpleFactory {
    static void process() {
        std::cout << "SimpleFactory: Processing with basic algorithm\n";
    }
};

// Factory for Fast Algorithm
template <Direction DIR, typename Algorithm>
    requires (DIR == Direction::FORWARD)  // ← Only check direction!
struct FastFactory {
    static void process() {
        std::cout << "FastFactory: Processing with optimized algorithm\n";
    }
};

// Factory for Parallel Algorithm
template <Direction DIR, typename Algorithm>
    requires (DIR == Direction::FORWARD)  // ← Only check direction!
struct ParallelFactory {
    static void process() {
        std::cout << "ParallelFactory: Processing with parallel algorithm\n";
    }
};

// ==========================================
// Step 4: DISPATCHER - Routes to correct factory
// ==========================================

template <Direction DIR, typename Algorithm>
void dispatch() {
    std::cout << "\n=== DISPATCHER START (MareArts.com)===\n";
    
    // Check direction first
    if constexpr (DIR == Direction::FORWARD) {
        std::cout << "Direction: FORWARD\n";
        
        // Check algorithm type (like the conv dispatcher!)
        if constexpr (IsSimpleAlgorithm<Algorithm>()) {  // ← Check algorithm here!
            std::cout << "Algorithm: SIMPLE\n";
            SimpleFactory<DIR, Algorithm>::process();
        }
        else if constexpr (IsFastAlgorithm<Algorithm>()) {  // ← Check algorithm here!
            std::cout << "Algorithm: FAST\n";
            FastFactory<DIR, Algorithm>::process();
        }
        else if constexpr (IsParallelAlgorithm<Algorithm>()) {  // ← Check algorithm here!
            std::cout << "Algorithm: PARALLEL\n";
            ParallelFactory<DIR, Algorithm>::process();
        }
        else {
            // Force compile error for unknown algorithms
            []<bool flag = false>() { static_assert(flag, "Unknown algorithm!"); }();
        }
    }
    else {
        std::cout << "Direction: BACKWARD\n";
        std::cout << "Not implemented yet!\n";
    }
    
    std::cout << "=== DISPATCHER END ===\n\n";
}

// ==========================================
// Main - Try different algorithms!
// ==========================================

int main() {
    std::cout << "=== Dispatcher Pattern Example ===\n";
    std::cout << "This is exactly how CK convolution dispatcher works!\n";
    
    // Try Simple algorithm
    dispatch<Direction::FORWARD, SimpleAlgorithm>();
    
    // Try Fast algorithm
    dispatch<Direction::FORWARD, FastAlgorithm>();
    
    // Try Parallel algorithm
    dispatch<Direction::FORWARD, ParallelAlgorithm>();
    
    return 0;
}

/*
DISPATCHER PATTERN SUMMARY:

┌─────────────────────────────────────────┐
│          USER CODE                      │
│  dispatch<FORWARD, SimpleAlgorithm>()   │
└─────────────────────────────────────────┘
                 ↓
┌─────────────────────────────────────────┐
│          DISPATCHER                     │
│  ✅ Check direction (if constexpr)      │
│  ✅ Check algorithm (if constexpr)      │
│     - IsSimpleAlgorithm()               │
│     - IsFastAlgorithm()                 │
│     - IsParallelAlgorithm()             │
│  ✅ Route to correct factory            │
└─────────────────────────────────────────┘
                 ↓
┌─────────────────────────────────────────┐
│          FACTORY                        │
│  requires (DIR == FORWARD)              │
│  ❌ NO algorithm check!                 │
│  ✅ Just build the thing                │
└─────────────────────────────────────────┘

KEY POINTS:
1. Dispatcher uses consteval functions with "if constexpr"
2. Factories use concepts with "requires"
3. Algorithm checking happens in dispatcher, not factory
4. This is EXACTLY the CK convolution pattern!
*/

### 3. Dispatcher Pattern (03_dispatcher_pattern.cpp) ⭐ MOST IMPORTANT
**What it teaches:** Exactly how CK convolution works!

```cpp
// Detection functions (like IsReferenceAlgorithm!)
template <typename T>
consteval bool IsSimpleAlgorithm() {
    return std::is_same_v<T, SimpleAlgorithm>;
}

// Dispatcher - checks algorithm and routes
template <Direction DIR, typename Algorithm>
void dispatch() {
    if constexpr (DIR == Direction::FORWARD) {
        // Check algorithm type here!
        if constexpr (IsSimpleAlgorithm<Algorithm>()) {
            SimpleFactory<DIR, Algorithm>::process();
        }
        else if constexpr (IsFastAlgorithm<Algorithm>()) {
            FastFactory<DIR, Algorithm>::process();
        }
    }
}

// Factory - only checks direction!
template <Direction DIR, typename Algorithm>
    requires (DIR == Direction::FORWARD)  // Only check direction
struct SimpleFactory {
    // NO algorithm check here!
};
```

**Output:**
```
=== DISPATCHER START ===
Direction: FORWARD
Algorithm: SIMPLE
SimpleFactory: Processing with basic algorithm
=== DISPATCHER END ===
```

**Key Point:** This is EXACTLY the CK pattern!

Study.marearts.com!!!

c++ constexpr #02_constexpr_functions.cpp

2025-12-12T05:57:00.000-08:00

// Example 2: Understanding constexpr/consteval Functions
// These functions run at COMPILE TIME and return results the compiler can use

#include <iostream>

// ==========================================
// CONSTEXPR: Function evaluated at compile time
// ==========================================

// Regular function - runs at runtime
bool isDogRuntime(const char* type) {
    return type[0] == 'D';  // Check if starts with 'D'
}

// Constexpr function - can run at compile time!
constexpr bool isDogCompileTime(const char* type) {
    return type[0] == 'D';
}

// Consteval (C++20) - MUST run at compile time
consteval bool isDogMustCompileTime(const char* type) {
    return type[0] == 'D';
}

// ==========================================
// Animal types
// ==========================================

struct Dog {
    static constexpr const char* type = "marearts.com Dog";
};

struct Cat {
    static constexpr const char* type = "marearts.com Cat";
};

struct Bird {
    static constexpr const char* type = "marearts.com Bird";
};

// ==========================================
// Using constexpr functions with "if constexpr"
// ==========================================

template <typename T>
void describeAnimal() {
    // if constexpr - evaluated at COMPILE TIME
    if constexpr (isDogCompileTime(T::type)) {
        std::cout << "This is a DOG - has 4 legs, barks\n";
    }
    else if constexpr (T::type[0] == 'C') {  // Can use any compile-time expression
        std::cout << "This is a CAT - has 4 legs, meows\n";
    }
    else {
        std::cout << "This is a BIRD - has 2 legs, flies\n";
    }
}

// ==========================================
// Difference: regular if vs if constexpr
// ==========================================

template <typename T>
void regularIf() {
    // Regular if - runs at RUNTIME, all branches must be valid
    if (isDogRuntime(T::type)) {
        std::cout << "Runtime check: Dog\n";
    }
}

template <typename T>
void constexprIf() {
    // if constexpr - evaluated at COMPILE TIME, only chosen branch exists
    if constexpr (isDogCompileTime(T::type)) {
        std::cout << "Compile-time check: Dog\n";
    }
}

// ==========================================
// Main
// ==========================================

int main() {
    std::cout << "=== Using constexpr functions with 'if constexpr' ===\n\n";
    
    describeAnimal<Dog>();
    describeAnimal<Cat>();
    describeAnimal<Bird>();
    
    std::cout << "\n=== Difference between regular if and if constexpr ===\n\n";
    
    regularIf<Dog>();
    constexprIf<Dog>();
    
    // With constexpr, the check happens at COMPILE TIME!
    // The compiler removes the unused branches - they don't even exist in final code!
    
    return 0;
}

/*
KEY POINTS:
1. constexpr/consteval functions run at COMPILE TIME
2. "if constexpr" uses compile-time checks
3. Only the chosen branch exists in final code (very efficient!)
4. Can't use constexpr functions in "requires" clauses - they need concepts
5. But CAN use constexpr functions in "if constexpr" - that's the dispatcher pattern!
*/

------------------------------------------------------------

How to build

> g++ -std=c++20 02_constexpr_functions.cpp -o 02_constexpr_functions

>./02_constexpr

=== Using constexpr functions with 'if constexpr' ===

This is a DOG - has 4 legs, barks

This is a CAT - has 4 legs, meows

This is a BIRD - has 2 legs, flies

=== Difference between regular if and if constexpr ===

Runtime check: Dog

Compile-time check: Dog

------------------------------------------------------------------------------------------------------------------------

### 2. Constexpr Functions (02_constexpr_functions.cpp)
**What it teaches:** Functions that run at compile time

```cpp
// Constexpr function - evaluated at compile time
constexpr bool isDog(const char* type) {
    return type[0] == 'D';
}

// Use in if constexpr
template <typename T>
void describe() {
    if constexpr (isDog(T::type)) {  // ✅ Function works here!
        std::cout << "It's a dog!";
    }
}
```

OK then what is different constexpr and consteval and anything else?

1. constexpr (C++11)

Can run at compile time OR runtime, depending on context:

02_constexpr_functions.cppLines 15-18

Flexible: The compiler decides when to evaluate it.

2. consteval (C++20)

MUST run at compile time - stricter than constexpr:

02_constexpr_functions.cppLines 20-23

Strict: Compile error if it can't be evaluated at compile time.

3. constinit (C++20)

Ensures variables are initialized at compile time (doesn't apply to functions):

Bonus: if constexpr (C++17)

Not a function specifier, but a compile-time conditional statement:

02_constexpr_functions.cppLines 47-57

    // if constexpr - evaluated at COMPILE TIME
    if constexpr (isDogCompileTime(T::type)) {
        std::cout << "This is a DOG - has 4 legs, barks\n";
    }
    else if constexpr (T::type[0] == 'C') {  // Can use any compile-time expression
        std::cout << "This is a CAT - has 4 legs, meows\n";
    }
    else {
        std::cout << "This is a BIRD - has 2 legs, flies\n";
    }

Quick Comparison

Keyword	When Evaluated	Use Case
constexpr	Compile time OR runtime	Functions/variables that CAN be constant
consteval	Compile time ONLY	Functions that MUST be constant
constinit	Initialization at compile time	Variables with compile-time initialization
if constexpr	Compile time	Conditional compilation branches

So the answer is: three main keywords (constexpr, consteval, constinit), plus if constexpr for compile-time conditionals! 🎯

ok, one thing to clear

Both are equivalent:

The only requirement for if constexpr is that the condition must be a compile-time constant expression - it doesn't matter whether it comes from a function call or is written inline! 🎯

What is meaning constexpr is flexible??

constexpr - Flexible (Can do both)

02_constexpr_functions.cppLines 15-18

This same function can be used in BOTH ways:

✅ Use 1: Compile-time evaluation

✅ Use 2: Runtime evaluation

consteval - NOT Flexible (Compile time only)

02_constexpr_functions.cppLines 20-23

This can ONLY be used at compile time:

Summary

Feature	constexpr (Flexible)	consteval (Strict)
Compile-time use	✅ Yes	✅ Yes
Runtime use	✅ Yes	❌ No (compile error)
Flexibility	Can adapt to context	Must be compile-time only

"Flexible" = The compiler decides when to evaluate it based on context! 🎯

One more thing to clear!! what happened in runtime exactly?

When you call a constexpr function with runtime values, it simply executes as a regular function during program execution.

Here's what happens:

// Example with constexpr function
constexpr bool isDogCompileTime(const char* type) {
    return type[0] == 'D';  // Check first character
}
// Scenario 1: COMPILE TIME (value known at compile)
if constexpr (isDogCompileTime("Dog")) {  
    // ↑ Compiler evaluates: "Dog"[0] == 'D' → true
    // Decision made BEFORE program runs
}
// Scenario 2: RUNTIME (value unknown until program runs)
const char* runtimeString = getUserInput();  // User types something
bool result = isDogCompileTime(runtimeString);  
    // ↑ Program executes this code WHILE running
    // Checks runtimeString[0] == 'D' at runtime
    // Just like a normal function!

Think of constexpr like this:

Visual Timeline:

Compile Time (if arguments are constants):

Runtime (if arguments are not constants):

So yes, constexpr with runtime values = normal function execution! 🎯

That's it.

Thank you!

Study.marearts.com!!!

MareArts Computer Vision Study.

A | B means either: reading union type hints in Python

Contents

1 · One bar, two types

The whole of the notation

2 · The | None case

"or nothing" is the common member

3 · Nobody checks it at runtime

Annotations are documentation with syntax

4 · Narrowing a three-way union

The funnel pattern

Ordering the checks is not narrowing by itself

5 · The bar builds a real object

Not a special form the parser swallows

It works in isinstance

6 · Where you put the bar changes the meaning

Outside or inside the brackets

7 · Older Python

The from __future__ escape

8 · Traps

Four that survive the nicer syntax

A wide union is a cost, not a courtesy

or is not the same as is None

The return type is a union too

Mixing the spellings in one file

Wrapping up

Cheat sheet

The short list

Further reading

MareArts ANPR App: On-Device Plates, MMC Vehicle Info, Team Sync, Web and Desktop Viewers

Scan: on-device ANPR and cloud

MMC vehicle info (make, model, colour)

Detections, map, and stats

Whitelist and blacklist

Team project

Web viewer

Desktop viewer

Webhook, plate regions, SDK

How to start

API and ABI, and the line between them

Contents

Part 1 · Two contracts

What each one promises

Recompile, relink, neither

What an ABI decides

Part 2 · Struct layout

Where the fields actually land

Alignment and padding

Reordering is an ABI change with no API change

Part 3 · Symbols and registers

Name mangling

What extern "C" is for

The calling convention

The detail that surprises people

Part 4 · Crossing over from Python

The library

A mirror that matches

A mirror that doesn't

The restype trap

What the Python examples actually demonstrate

Part 5 · Keeping an ABI stable

What breaks which

How libraries stay compatible

Hide the struct entirely

Put the size in the struct

Reserve space up front

Version the symbol, not the struct

soname, and how the loader picks a file

Part 6 · Reference

Tools worth knowing

Cheat sheet

The distinction

x86-64 System V, in four lines

Writing an FFI binding

Wrapping up

What to take away

The short list

Further reading

Appendix · The complete programs

Building and running

2 · The `| None` case

It works in `isinstance`

The `from future` escape

`or` is not the same as `is None`

What `extern "C"` is for

The `restype` trap

The two operators: `#` and `##`

Registering yourself before `main`

Running code before `main`

The `None` sentinel

`or []` is shorter and subtly different

When `None` is itself a valid value