Bool on Opensource internals

How CPython Implements bool in C

Jay Hubbert — Tue, 20 Oct 2026 09:00:00 +0000

Python’s bool is unusual: it is a real type, but there are exactly two instances, True and False, and they are also the integers 1 and 0. In CPython that is implemented in Objects/boolobject.c by making PyBool_Type a subclass of PyLong_Type and storing the two values as static _longobject structs. This article traces that implementation through the 3.15 source.

The type is a subclass of int

bool is not a separate representation. It reuses PyLongObject’s layout and inherits almost everything from int:

 c
 
 
// Objects/boolobject.c
PyTypeObject PyBool_Type = {
 PyVarObject_HEAD_INIT(&PyType_Type, 0)
 "bool",
 offsetof(struct _longobject, long_value.ob_digit), /* tp_basicsize */
 sizeof(digit), /* tp_itemsize */
 bool_dealloc, /* tp_dealloc */
 ...
 &bool_as_number, /* tp_as_number */
 ...
 &PyLong_Type, /* tp_base */
 ...
 bool_new, /* tp_new */
 .tp_vectorcall = bool_vectorcall,
};

Two details matter. First, tp_base is &PyLong_Type, so bool is a real subclass of int: isinstance(True, int) is true and all of int’s methods are inherited (see below). Second, tp_flags is just Py_TPFLAGS_DEFAULT – there is no Py_TPFLAGS_BASETYPE, so bool cannot be subclassed in Python:

 python
 
 
>>> class MyBool(bool): pass
TypeError: type 'bool' is not an acceptable base type

PyBool_Check is an exact type check, not a subclass check, which is why the bitwise overrides below can safely assume “this is exactly a bool”:

 c
 
 
// Include/boolobject.h
#define PyBool_Check(x) Py_IS_TYPE((x), &PyBool_Type)

The two singletons

True and False are not allocated at runtime. They are static C structs of type _longobject (the same struct int uses), initialized at compile time:

 c
 
 
// Objects/boolobject.c
struct _longobject _Py_FalseStruct = {
 PyObject_HEAD_INIT(&PyBool_Type)
 { .lv_tag = _PyLong_FALSE_TAG,
 { 0 }
 }
};

struct _longobject _Py_TrueStruct = {
 PyObject_HEAD_INIT(&PyBool_Type)
 { .lv_tag = _PyLong_TRUE_TAG,
 { 1 }
 }
};

The tags are defined in terms of the ordinary long tag machinery:

 c
 
 
// Include/internal/pycore_long.h
#define _PyLong_FALSE_TAG TAG_FROM_SIGN_AND_SIZE(0, 0)
#define _PyLong_TRUE_TAG TAG_FROM_SIGN_AND_SIZE(1, 1)

So False is “zero digits, zero value” and True is “one digit, value 1” – exactly the same encoding an int would use. That is why bool needs no special conversion to behave as an int: True + True == 2, True * 10 == 10, and int(True) is True.

The public macros resolve to these structs (or, in the limited API, to immortal constants):

 c
 
 
// Include/boolobject.h
#define Py_False _PyObject_CAST(&_Py_FalseStruct)
#define Py_True _PyObject_CAST(&_Py_TrueStruct)

Because they are statically allocated, they go through PyObject_HEAD_INIT, which marks them immortal (PEP 683). They also appear in the interpreter’s constant table (Py_CONSTANT_FALSE / Py_CONSTANT_TRUE), whose entries are all immortal. The bool_dealloc is a belt-and-braces guard in case a refcount ever reaches zero: it simply re-immortalizes the object instead of freeing it.

 c
 
 
// Objects/boolobject.c
static void
bool_dealloc(PyObject *boolean)
{
 _Py_SetImmortal(boolean);
}

PyBool_FromLong is the single factory. It never allocates; it just picks the right singleton:

 c
 
 
// Objects/boolobject.c
PyObject *PyBool_FromLong(long ok)
{
 return ok ? Py_True : Py_False;
}

tp_new: always a singleton

bool() (and bool(x)) is implemented by bool_new / bool_vectorcall. The rule is simple: unpack at most one argument, test its truthiness, and return Py_True or Py_False:

 c
 
 
// Objects/boolobject.c
static PyObject *
bool_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
 PyObject *x = Py_False;
 long ok;

 if (!_PyArg_NoKeywords("bool", kwds))
 return NULL;
 if (!PyArg_UnpackTuple(args, "bool", 0, 1, &x))
 return NULL;
 ok = PyObject_IsTrue(x);
 if (ok < 0)
 return NULL;
 return PyBool_FromLong(ok);
}

bool_vectorcall is the faster calling convention used for bool(x); it does the same thing, defaulting to False when called with no arguments. Note that type is accepted but never used to construct a new instance – there is no way to create a third bool, which is what makes True/False the only two instances the docstring promises.

Truthiness

bool_new delegates truthiness to PyObject_IsTrue in Objects/object.c. That function has fast paths for the three singletons and otherwise consults the type’s nb_bool, then mapping length, then sequence length, defaulting to true:

 c
 
 
// Objects/object.c
PyObject_IsTrue(PyObject *v)
{
 Py_ssize_t res;
 if (v == Py_True)
 return 1;
 if (v == Py_False)
 return 0;
 if (v == Py_None)
 return 0;
 else if (Py_TYPE(v)->tp_as_number != NULL &&
 Py_TYPE(v)->tp_as_number->nb_bool != NULL)
 res = (*Py_TYPE(v)->tp_as_number->nb_bool)(v);
 else if (Py_TYPE(v)->tp_as_mapping != NULL &&
 Py_TYPE(v)->tp_as_mapping->mp_length != NULL)
 res = (*Py_TYPE(v)->tp_as_mapping->mp_length)(v);
 else if (Py_TYPE(v)->tp_as_sequence != NULL &&
 Py_TYPE(v)->tp_as_sequence->sq_length != NULL)
 res = (*Py_TYPE(v)->tp_as_sequence->sq_length)(v);
 else
 return 1;
 return (res > 0) ? 1 : Py_SAFE_DOWNCAST(res, Py_ssize_t, int);
}

This is also what if x:, not x, and the and/or operators use, so bool(x) and truthiness agree by construction. Note bool itself has nb_bool == 0 (left NULL so it is inherited from int); an int’s nb_bool is effectively “nonzero”, so bool(True) works through the Py_True fast path before ever reaching that.

bool as int

Because PyBool_Type is a subclass of PyLong_Type, almost all arithmetic is inherited. bool_as_number only fills in a handful of slots; the rest are copied from int by PyType_Ready (COPYNUM):

 c
 
 
// Objects/boolobject.c
static PyNumberMethods bool_as_number = {
 0, /* nb_add */ // inherited from int
 ...
 bool_invert, /* nb_invert */
 ...
 bool_and, /* nb_and */
 bool_xor, /* nb_xor */
 bool_or, /* nb_or */
 ...
};

So True + True == 2 (an int), True << 3 == 8, and so on, all use int’s implementations. Only the bitwise logical operators are overridden, and only so that &, |, ^ on two bools return a bool instead of an int:

 c
 
 
// Objects/boolobject.c
static PyObject *
bool_and(PyObject *a, PyObject *b)
{
 if (!PyBool_Check(a) || !PyBool_Check(b))
 return PyLong_Type.tp_as_number->nb_and(a, b);
 return PyBool_FromLong((a == Py_True) & (b == Py_True));
}

static PyObject *
bool_or(PyObject *a, PyObject *b)
{
 if (!PyBool_Check(a) || !PyBool_Check(b))
 return PyLong_Type.tp_as_number->nb_or(a, b);
 return PyBool_FromLong((a == Py_True) | (b == Py_True));
}

static PyObject *
bool_xor(PyObject *a, PyObject *b)
{
 if (!PyBool_Check(a) || !PyBool_Check(b))
 return PyLong_Type.tp_as_number->nb_xor(a, b);
 return PyBool_FromLong((a == Py_True) ^ (b == Py_True));
}

If either operand is not exactly a bool, the call falls through to int’s bitwise operation, which returns an int. ~ is special: it is deprecated on bool (it returns the underlying int’s bitwise inversion, e.g. ~True == -2) and emits a DeprecationWarning, and will be removed in 3.16.

bool_repr returns the interned identifiers, so repr(True) == "True":

 c
 
 
// Objects/boolobject.c
static PyObject *
bool_repr(PyObject *self)
{
 return self == Py_True ? &_Py_ID(True) : &_Py_ID(False);
}

Hashing and comparison are inherited from int: hash(True) == 1, True == 1 is True, and True is 1 is False – the usual identity-vs-equality distinction, since 1 is a separate (possibly cached) int object.

Memory layout summary

There is no separate allocation for bools. The two singletons are static _longobjects whose lv_tag and single digit are the values 0 and 1:

text

_Py_FalseStruct _Py_TrueStruct
+---------------------------+ +---------------------------+
| ob_refcnt (immortal) | | ob_refcnt (immortal) |
+---------------------------+ +---------------------------+
| *ob_type (&PyBool_Type) | | *ob_type (&PyBool_Type) |
+---------------------------+ +---------------------------+
| lv_tag (FALSE_TAG: 0) | | lv_tag (TRUE_TAG: 1<<3) |
+---------------------------+ +---------------------------+
| ob_digit[0] = 0 | | ob_digit[0] = 1 |
+---------------------------+ +---------------------------+

PyBool_Type.tp_basicsize is offsetof(struct _longobject, long_value.ob_digit) and tp_itemsize is sizeof(digit), identical to int, so even the memory layout is shared with PyLongObject.

Key takeaways

bool is a subclass of int (PyBool_Type.tp_base == &PyLong_Type) with no Py_TPFLAGS_BASETYPE, so it cannot be subclassed.
True and False are two immortal static _longobjects whose tags and digits are the integers 1 and 0; PyBool_FromLong only selects between them, so no bool is ever allocated.
bool(x) (bool_new/bool_vectorcall) tests truthiness via PyObject_IsTrue and returns a singleton.
Truthiness fast-paths True/False/None, then nb_bool, mapping length, sequence length, defaulting to true.
All arithmetic is inherited from int; only &, |, ^ (and a deprecated ~) are overridden so bool op bool returns bool.

How PostgreSQL Implements bool in C

Jay Hubbert — Sun, 04 Oct 2026 04:06:31 +0000

bool looks like the easiest type in PostgreSQL. One bit of meaning, one byte of storage, done. It is not. The value has two different text spellings depending on which code path you go through, the input parser accepts eight different words plus unique prefixes, the binary wire format is not the text format, and the aggregate machinery behind bool_and/bool_or is a small state machine with its own struct. All of it lives in src/backend/utils/adt/bool.c, a little over 400 lines.

This is based on reading the PostgreSQL source (version 20devel, commit e75fcc9867f).

The catalog entry

The type’s identity is one line in src/include/catalog/pg_type.dat:

 text
 
 
{ oid => '16', array_type_oid => '1000',
 descr => 'boolean, format \'t\'/\'f\'',
 typname => 'bool', typlen => '1', typbyval => 't', typcategory => 'B',
 typispreferred => 't', typinput => 'boolin', typoutput => 'boolout',
 typreceive => 'boolrecv', typsend => 'boolsend', typalign => 'c' },

Five of those fields matter here:

Field	Value	Meaning
`typlen`	1	one byte on disk
`typbyval`	`t`	passed by value, not by reference
`typalign`	`c`	`TYPALIGN_CHAR`: no alignment padding
`typcategory`	`B`	the Boolean category (sorts last in the built-in order)
`array_type_oid`	1000	`_bool` is generated automatically from this entry

typalign => 'c' is TYPALIGN_CHAR, documented in src/include/catalog/pg_type.h as “char alignment (ie no alignment needed)”. So a bool column never forces a padding byte before it. typstorage is not listed, so it takes the default 'p' (TYPSTORAGE_PLAIN): a bool is never TOASTed.

The C representation

In memory, a bool is a C99 bool (from <stdbool.h>, pulled in by src/include/c.h), which is one byte holding 0 or 1. But the function-call convention never hands you a bare bool. Every value crosses a function boundary as a Datum — a pointer-sized integer — and the conversion is a pair of trivial inline functions in src/include/postgres.h:

 c
 
 
static inline bool
DatumGetBool(Datum X)
{
	return (X != 0);
}

static inline Datum
BoolGetDatum(bool X)
{
	return (Datum) (X ? 1 : 0);
}

Notice the asymmetry in the doc comments: “any nonzero value will be considered true.” The representation is 8 bytes in memory but 1 byte on disk. PG_GETARG_BOOL(n) and PG_RETURN_BOOL(x) in src/include/fmgr.h are just these two functions.

Two text spellings

boolout is the type’s official output function, and it emits a single character:

 c
 
 
Datum
boolout(PG_FUNCTION_ARGS)
{
	bool		b = PG_GETARG_BOOL(0);
	char	 *result = (char *) palloc(2);

	result[0] = (b) ? 't' : 'f';
	result[1] = '\0';
	PG_RETURN_CSTRING(result);
}

That is why SELECT true; prints t and SELECT false; prints f — the type’s own output function is what a bare SELECT invokes. But the cast to text uses a different function, booltext, which follows the SQL standard instead:

 c
 
 
Datum
booltext(PG_FUNCTION_ARGS)
{
	bool		arg1 = PG_GETARG_BOOL(0);
	const char *str;

	if (arg1)
		str = "true";
	else
		str = "false";

	PG_RETURN_TEXT_P(cstring_to_text(str));
}

src/include/catalog/pg_cast.dat wires that function up for all three string targets:

 text
 
 
{ castsource => 'bool', casttarget => 'text', castfunc => 'text(bool)', ... }
{ castsource => 'bool', casttarget => 'varchar', castfunc => 'text(bool)', ... }
{ castsource => 'bool', casttarget => 'bpchar', castfunc => 'text(bool)', ... }

So true::text is true, and so is true::varchar and true::char(n). One value, two spellings, chosen by whether you go through boolout or through a cast to a string type.

The permissive input parser

boolin trims leading and trailing whitespace, then calls parse_bool_with_len. That function is a switch on the first character (src/backend/utils/adt/bool.c):

 c
 
 
bool
parse_bool_with_len(const char *value, size_t len, bool *result)
{
	/* Check the most-used possibilities first. */
	switch (*value)
	{
		case 't':
		case 'T':
			if (pg_strncasecmp(value, "true", len) == 0)
			{
				if (result)
					*result = true;
				return true;
			}
			break;
		...
		case 'o':
		case 'O':
			/* 'o' is not unique enough */
			if (pg_strncasecmp(value, "on", (len > 2 ? len : 2)) == 0)
			...

The comment above the function claims it accepts “unique prefixes thereof” — and the implementation really does, because pg_strncasecmp only compares len characters. 't', 'tr', 'tru', and 'true' all parse as true; the same for f/fa/fal/fals/false, y/ye/yes, and n/no. The one exception is o, which the code calls out as “not unique enough”: it clamps the comparison length to at least 2, so 'o' alone is rejected while 'on' and 'of' are accepted.

The full set of accepted inputs is true, false, yes, no, on, off, 1, 0, each case-insensitive and optionally prefixed (except o, which needs two characters).

Binary format

boolrecv and boolsend handle the binary protocol (COPY ... WITH (FORMAT binary)). They do not reuse the text representation:

 c
 
 
Datum
boolrecv(PG_FUNCTION_ARGS)
{
	StringInfo	buf = (StringInfo) PG_GETARG_POINTER(0);
	int			ext;

	ext = pq_getmsgbyte(buf);
	PG_RETURN_BOOL(ext != 0);
}

Datum
boolsend(PG_FUNCTION_ARGS)
{
	bool		arg1 = PG_GETARG_BOOL(0);
	StringInfoData buf;

	pq_begintypsend(&buf);
	pq_sendbyte(&buf, arg1 ? 1 : 0);
	PG_RETURN_BYTEA_P(pq_endtypsend(&buf));
}

One byte on the wire, 0 or 1 on the way out, and any nonzero byte counts as true on the way in. That is the same “any nonzero is true” rule as DatumGetBool, which is what lets a boolean survive a round trip even if a client sends 0x02.

Hashing, comparison, and aggregates

Equality is trivial (arg1 == arg2), and hashing widens the byte to an int32 and reuses the integer hash:

 c
 
 
Datum
hashbool(PG_FUNCTION_ARGS)
{
	return hash_uint32((int32) PG_GETARG_BOOL(0));
}

The btree comparison is a plain subtraction (src/backend/access/nbtree/nbtcompare.c):

 c
 
 
Datum
btboolcmp(PG_FUNCTION_ARGS)
{
	bool		a = PG_GETARG_BOOL(0);
	bool		b = PG_GETARG_BOOL(1);

	PG_RETURN_INT32((int32) a - (int32) b);
}

For int4 and wider, btint4cmp cannot subtract (it could overflow) and switches to > / <. For one-byte bools the subtraction is safe.

bool_and and bool_or are where the interesting struct appears. They are aggregates, so they need per-group state. BoolAggState keeps two counters:

 c
 
 
typedef struct BoolAggState
{
	int64		aggcount;		/* number of non-null values aggregated */
	int64		aggtrue;		/* number of values aggregated that are true */
} BoolAggState;

The transition function bool_accum increments both counters, skipping NULLs, and bool_alltrue / bool_anytrue answer from the counters at the end. That is why bool_and of an all-NULL group returns NULL rather than an arbitrary default. The whole thing is one more example of the general PostgreSQL aggregate pattern: a state struct, a transition function, an inverse (bool_accum_inv, for moving-aggregate mode), and a final function.

Look at it yourself

 sql
 
 
SELECT 't'::bool, 'tru'::bool, 'o'::bool; -- t, t, ERROR
SELECT true::text, true::varchar; -- true, true
SELECT true; -- t
SELECT bool_and(x) FROM (VALUES (true),(false)) v(x); -- false
SELECT bool_and(x) FROM (VALUES (NULL),(NULL)) v(x); -- NULL

The parser’s prefix behavior is easy to confirm:

 sql
 
 
SELECT 'ye'::bool, 'n'::bool, 'off'::bool, 'of'::bool;
-- t, f, f, f

And the catalog entry is visible directly:

 sql
 
 
SELECT typname, typlen, typbyval, typalign, typcategory
FROM pg_type WHERE oid = 16;
-- bool, 1, t, c, B

What it all means

A bool is one byte of storage and eight bytes of in-memory Datum, with typbyval meaning no pointer chasing.
typalign => 'c' means it never forces padding, so a bool column can sit at any byte offset in a tuple.
boolout says t/f; booltext says true/false. Which one you see depends on the cast.
The input parser accepts case-insensitive prefixes of eight words (true/false/yes/no/on/off/1/0), with o as the only minimum-two-character special case.
The binary protocol uses one byte and treats any nonzero value as true.