python / python/cpython

Clarify which "identifiers" in the C API are macros

Open
#93,733 19 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

docs topic-C-API
Dominant language
Python
Stars
77.2k
Forks
36k
Avg merge
1d 9h
Merged PRs (30d)
558

Description

Documentation

The "Python/C API Reference Manual" is an excellent resource but could be even better
if C macros were marked as such.

For a programmer that writes directly in C it doesn't matter which identifiers are real C functions
and which are C macros. However, when Python is used through libpython only the
C functions are available. This is the case for languages embedding Python through ffilib.

As an example: Consider the C macro PyImport_ImportModuleEx and the C function PyImport_ImportModuleLevel. They are documented in a way that makes it impossible
to guess that one is a C macro.

PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)

PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

A look in "Python.c" (or friends import.h here) will reveal that PyImport_ImportModuleEx is a C macro.
But it would be a quality of life-improvement, if a simple "C Macro" were added below the
signature of C macros.

This "C macro" annotation could have the same style as the "Return value is a new reference" annotation.
(maybe with a different color).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Python/C API Reference Manual and compare the documented PyImport_ImportModuleEx and PyImport_ImportModuleLevel entries. Inspect import.h to confirm the macro distinction, then identify how the existing return-value annotations are produced. Done means C macros in the API documentation are visibly marked without mislabeling C functions.

Written by the indexing model from the issue text.

Assessment

Tech stack
c, python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.