I propose to make the private _PyLong_FileDescriptor_Converter() function public and add it to the limited C API (version 3.13).

The function is used used by 4 stdlib C extensions: posix, fcntl, select and termios. Making the function public helps to build these extensions with the limited C API.

In the PyPI top 5,000 projects (at 2023-11-15), no project uses _PyLong_FileDescriptor_Converter(), but 25 projects use directly PyObject_AsFileDescriptor():

• Cython (3.0.5)
• M2Crypto (0.40.1)
• astropy (5.3.4)
• cassandra-driver (3.28.0)
• catboost (1.2.2)
• cffi (1.16.0)
• igraph (0.11.2)
• line_profiler (4.1.2)
• mod_wsgi (4.9.4)
• numpy (1.26.2)
• orjson (3.9.10)
• pycups (2.0.1)
• pydoop (2.0.0)
• pygame (2.5.2)
• pygraphviz (1.11)
• pysam (0.22.0)
• python-sat-0.1.8.dev10
• python-vlc (3.0.20123)
• pyuwsgi (2.0.23)
• pyxattr (0.8.1)
• scylla-driver (3.26.3)
• ssh-python (1.0.0)
• ssh2-python (1.0.0)
• uwsgi (2.0.23)
• yara-python (4.3.1)

To convert an object to a file descriptor, Argument Clinic generates code calling _PyLong_FileDescriptor_Converter().

This function is quite simple, it's a thin wrapper to the public PyObject_AsFileDescriptor() function:

int
_PyLong_FileDescriptor_Converter(PyObject *o, void *ptr)
{
    int fd = PyObject_AsFileDescriptor(o);
    if (fd == -1) {
        return 0;
    }
    *(int *)ptr = fd;
    return 1;
}

PyObject_AsFileDescriptor(obj) converts Python integer to a C int, or call obj.fileno() and converts the result to a C int, or raise a TypeError.

The API for converter callback is already exposed in PyArg_ParseTuple(): see O& format documentation: https://docs.python.org/dev/c-api/arg.html#other-objects

There is already PyUnicode_FSConverter() in the limited C API.

Linked PRs

• gh-116646: Add PyLong_FileDescriptor_Converter() function #116655
• gh-116646: Remove _PyLong_FileDescriptor_Converter() #116736
• gh-116646: Add limited C API support to AC fildes converter #116769
• gh-116646, AC: Add CConverter.use_converter() method #116793
• gh-116646, AC: Always use PyObject_AsFileDescriptor() in fildes #116806