PEP 7 – Style Guide for C Code

peps.python.org/pep-0007

Author:
Guido van Rossum <guido at python.org>, Barry Warsaw
<barry at python.org>
Status:
Active (Currently valid informational guidance, or an in-
use process)
Type:
Process (Normative PEP describing or proposing a
change to a Python community process, workflow or
governance)
Created:
05-Jul-2001
Post-History:

Table of Contents

Introduction
This document gives coding conventions for the C code comprising the C implementation
of Python. Please see the companion informational PEP describing style guidelines for
Python code.

Note, rules are there to be broken. Two good reasons to break a particular rule:

1. When applying the rule would make the code less readable, even for someone who
is used to reading code that follows the rules.
2. To be consistent with surrounding code that also breaks it (maybe for historic
reasons) – although this is also an opportunity to clean up someone else’s mess (in
true XP style).

C dialect
Python 3.11 and newer versions use C11 without optional features. The public C
API should be compatible with C++.

1/5
 Python 3.6 to 3.10 use C89 with several select C99 features:
Standard integer types in <stdint.h> and <inttypes.h>. We require the fixed
width integer types.
static inline functions
designated initializers (especially nice for type declarations)
intermingled declarations
booleans
C++-style line comments
Python versions before 3.6 used ANSI/ISO standard C (the 1989 version of the
standard). This meant (amongst many other things) that all declarations must be at
the top of a block (not necessarily at the top of function).
Don’t use compiler-specific extensions, such as those of GCC or MSVC (e.g. don’t
write multi-line strings without trailing backslashes).
All function declarations and definitions must use full prototypes (i.e. specify the
types of all arguments).
No compiler warnings with major compilers (gcc, VC++, a few others).
static inline functions should be preferred over macros in new code.

Code lay-out
Use 4-space indents and no tabs at all.
No line should be longer than 79 characters. If this and the previous rule together
don’t give you enough room to code, your code is too complicated – consider using
subroutines.
No line should end in whitespace. If you think you need significant trailing
whitespace, think again – somebody’s editor might delete it as a matter of routine.
Function definition style: function name in column 1, outermost curly braces in
column 1, blank line after local variable declarations.

static int
extra_ivars(PyTypeObject *type, PyTypeObject *base)
{
int t_size = PyType_BASICSIZE(type);
int b_size = PyType_BASICSIZE(base);

assert(t_size >= b_size); /* type smaller than base! */

...
return 1;
}

2/5
Code structure: one space between keywords like if, for and the following left
paren; no spaces inside the paren; braces are required everywhere, even where C
permits them to be omitted, but do not add them to code you are not otherwise
modifying. All new C code requires braces. Braces should be formatted as shown:

if (mro != NULL) {
...
}
else {
...
}

The return statement should not get redundant parentheses:

return(albatross); /* incorrect */

Instead:

return albatross; /* correct */

Function and macro call style: foo(a, b, c) – no space before the open paren, no
spaces inside the parens, no spaces before commas, one space after each comma.
Always put spaces around assignment, Boolean and comparison operators. In
expressions using a lot of operators, add spaces around the outermost (lowest-
priority) operators.
Breaking long lines: if you can, break after commas in the outermost argument list.
Always indent continuation lines appropriately, e.g.:

PyErr_Format(PyExc_TypeError,
"cannot create '%.100s' instances",
type->tp_name);

When you break a long expression at a binary operator, braces should be formatted
as shown:

if (type->tp_dictoffset != 0
&& base->tp_dictoffset == 0
&& type->tp_dictoffset == b_size
&& (size_t)t_size == b_size + sizeof(PyObject *))
{
return 0; /* "Forgive" adding a __dict__ only */
}

It’s OK to put operators at ends of lines, especially to be consistent with surrounding

code. (See PEP 8 for a longer discussion.)

Vertically align line continuation characters in multi-line macros.

3/5
 Macros intended to be used as a statement should use the do { ... } while (0)
macro idiom, without a final semicolon. Example:

#define ADD_INT_MACRO(MOD, INT) \

do { \
if (PyModule_AddIntConstant((MOD), (#INT), (INT)) < 0) { \
goto error; \
} \
} while (0)

// To be used like a statement with a semicolon:

ADD_INT_MACRO(m, SOME_CONSTANT);

#undef file local macros after use.

Put blank lines around functions, structure definitions, and major sections inside
functions.
Comments go before the code they describe.
All functions and global variables should be declared static unless they are to be
part of a published interface.
For external functions and variables, we always have a declaration in an
appropriate header file in the “Include” directory, which uses the PyAPI_FUNC()
macro and PyAPI_DATA() macro, like this:

PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);

PyAPI_DATA(PyTypeObject) PySuper_Type;

Naming conventions
Use a Py prefix for public functions; never for static functions. The Py_ prefix is
reserved for global service routines like Py_FatalError; specific groups of routines
(e.g. specific object type APIs) use a longer prefix, e.g. PyString_ for string
functions.
Public functions and variables use MixedCase with underscores, like this:
PyObject_GetAttr, Py_BuildValue, PyExc_TypeError.
Occasionally an “internal” function has to be visible to the loader; we use the _Py
prefix for this, e.g.: _PyObject_Dump.
Macros should have a MixedCase prefix and then use upper case, for example:
PyString_AS_STRING, Py_PRINT_RAW.
Macro parameters should use ALL_CAPS style, so they are easily distinguishable
from C variables and struct members.

Documentation Strings
Use the PyDoc_STR() or PyDoc_STRVAR() macro for docstrings to support building
Python without docstrings (./configure --without-doc-strings).

4/5
 The first line of each function docstring should be a “signature line” that gives a brief
synopsis of the arguments and return value. For example:

PyDoc_STRVAR(myfunction__doc__,
"myfunction(name, value) -> bool\n\n\
Determine whether name and value make a valid pair.");

Always include a blank line between the signature line and the text of the
description.

If the return value for the function is always None (because there is no meaningful
return value), do not include the indication of the return type.

When writing multi-line docstrings, be sure to always use backslash continuations,

as in the example above, or string literal concatenation:

PyDoc_STRVAR(myfunction__doc__,
"myfunction(name, value) -> bool\n\n"
"Determine whether name and value make a valid pair.");

Though some C compilers accept string literals without either:

/* BAD -- don't do this! */

PyDoc_STRVAR(myfunction__doc__,
"myfunction(name, value) -> bool\n\n
Determine whether name and value make a valid pair.");

not all do; the MSVC compiler is known to complain about this.

Copyright
This document has been placed in the public domain.

5/5