gh-112068: C API: Add support of nullable arguments in PyArg_Parse (suffix)

Doc/c-api/arg.rst

@@ -113,14 +113,18 @@ There are three ways strings and buffers can be converted to C:
 ``z`` (:class:`str` or ``None``) [const char \*]
  Like ``s``, but the Python object may also be ``None``, in which case the C
  pointer is set to ``NULL``.
+ It is the same as ``s?`` with the C pointer was initialized to ``NULL``.
 
 ``z*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer]
  Like ``s*``, but the Python object may also be ``None``, in which case the
  ``buf`` member of the :c:type:`Py_buffer` structure is set to ``NULL``.
+ It is the same as ``s*?`` with the ``buf`` member of the :c:type:`Py_buffer`
+ structure was initialized to ``NULL``.
 
 ``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, :c:type:`Py_ssize_t`]
  Like ``s#``, but the Python object may also be ``None``, in which case the C
  pointer is set to ``NULL``.
+ It is the same as ``s#?`` with the C pointer was initialized to ``NULL``.
 
 ``y`` (read-only :term:`bytes-like object`) [const char \*]
  This format converts a bytes-like object to a C pointer to a
@@ -377,6 +381,17 @@ Other objects
  Non-tuple sequences are deprecated if *items* contains format units
  which store a borrowed buffer or a borrowed reference.
 
+``unit?`` (anything or ``None``) [*matching-variable(s)*]
+ ``?`` modifies the behavior of the preceding format unit.
+ The C variable(s) corresponding to that parameter should be initialized
+ to their default value --- when the argument is ``None``,
+ :c:func:`PyArg_ParseTuple` does not touch the contents of the corresponding
+ C variable(s).
+ If the argument is not ``None``, it is parsed according to the specified
+ format unit.
+
+ .. versionadded:: next
+
 A few other characters have a meaning in a format string. These may not occur
 inside nested parentheses. They are:
 

Doc/whatsnew/3.14.rst

@@ -1846,6 +1846,11 @@ New features
  file.
  (Contributed by Victor Stinner in :gh:`127350`.)
 
+* Add support of nullable arguments in :c:func:`PyArg_ParseTuple` and
+ similar functions.
+ Adding ``?`` after any format unit makes ``None`` be accepted as a value.
+ (Contributed by Serhiy Storchaka in :gh:`112068`.)
+
 * Add macros :c:func:`Py_PACK_VERSION` and :c:func:`Py_PACK_FULL_VERSION` for
  bit-packing Python version numbers.
  (Contributed by Petr Viktorin in :gh:`128629`.)

Lib/test/test_capi/test_getargs.py

@@ -1387,6 +1387,123 @@ def test_nested_sequence(self):
  "argument 1 must be sequence of length 1, not 0"):
  parse(([],),{}, '(' + f + ')', ['a'])
 
+ def test_specific_type_errors(self):
+ parse = _testcapi.parse_tuple_and_keywords
+
+ def check(format, arg, expected, got='list'):
+ errmsg = f'must be{expected}, not{got}'
+ with self.assertRaisesRegex(TypeError, errmsg):
+ parse((arg,),{}, format, ['a'])
+
+ check('k', [], 'int')
+ check('k?', [], 'int or None')
+ check('K', [], 'int')
+ check('K?', [], 'int or None')
+ check('c', [], 'a byte string of length 1')
+ check('c?', [], 'a byte string of length 1 or None')
+ check('c', b'abc', 'a byte string of length 1',
+ 'a bytes object of length 3')
+ check('c?', b'abc', 'a byte string of length 1 or None',
+ 'a bytes object of length 3')
+ check('c', bytearray(b'abc'), 'a byte string of length 1',
+ 'a bytearray object of length 3')
+ check('c?', bytearray(b'abc'), 'a byte string of length 1 or None',
+ 'a bytearray object of length 3')
+ check('C', [], 'a unicode character')
+ check('C?', [], 'a unicode character or None')
+ check('C', 'abc', 'a unicode character',
+ 'a string of length 3')
+ check('C?', 'abc', 'a unicode character or None',
+ 'a string of length 3')
+ check('s', [], 'str')
+ check('s?', [], 'str or None')
+ check('z', [], 'str or None')
+ check('z?', [], 'str or None')
+ check('es', [], 'str')
+ check('es?', [], 'str or None')
+ check('es#', [], 'str')
+ check('es#?', [], 'str or None')
+ check('et', [], 'str, bytes or bytearray')
+ check('et?', [], 'str, bytes, bytearray or None')
+ check('et#', [], 'str, bytes or bytearray')
+ check('et#?', [], 'str, bytes, bytearray or None')
+ check('w*', [], 'read-write bytes-like object')
+ check('w*?', [], 'read-write bytes-like object or None')
+ check('S', [], 'bytes')
+ check('S?', [], 'bytes or None')
+ check('U', [], 'str')
+ check('U?', [], 'str or None')
+ check('Y', [], 'bytearray')
+ check('Y?', [], 'bytearray or None')
+ check('(OO)', 42, '2-item tuple', 'int')
+ check('(OO)?', 42, '2-item tuple or None', 'int')
+ check('(OO)', (1, 2, 3), 'tuple of length 2', '3')
+
+ def test_nullable(self):
+ parse = _testcapi.parse_tuple_and_keywords
+
+ def check(format, arg, allows_none=False):
+ # Because some format units (such as y*) require cleanup,
+ # we force the parsing code to perform the cleanup by adding
+ # an argument that always fails.
+ # By checking for an exception, we ensure that the parsing
+ # of the first argument was successful.
+ self.assertRaises(OverflowError, parse,
+ (arg, 256),{}, format + '?b', ['a', 'b'])
+ self.assertRaises(OverflowError, parse,
+ (None, 256),{}, format + '?b', ['a', 'b'])
+ self.assertRaises(OverflowError, parse,
+ (arg, 256),{}, format + 'b', ['a', 'b'])
+ self.assertRaises(OverflowError if allows_none else TypeError, parse,
+ (None, 256),{}, format + 'b', ['a', 'b'])
+
+ check('b', 42)
+ check('B', 42)
+ check('h', 42)
+ check('H', 42)
+ check('i', 42)
+ check('I', 42)
+ check('n', 42)
+ check('l', 42)
+ check('k', 42)
+ check('L', 42)
+ check('K', 42)
+ check('f', 2.5)
+ check('d', 2.5)
+ check('D', 2.5j)
+ check('c', b'a')
+ check('C', 'a')
+ check('p', True, allows_none=True)
+ check('y', b'buffer')
+ check('y*', b'buffer')
+ check('y#', b'buffer')
+ check('s', 'string')
+ check('s*', 'string')
+ check('s#', 'string')
+ check('z', 'string', allows_none=True)
+ check('z*', 'string', allows_none=True)
+ check('z#', 'string', allows_none=True)
+ check('w*', bytearray(b'buffer'))
+ check('U', 'string')
+ check('S', b'bytes')
+ check('Y', bytearray(b'bytearray'))
+ check('O', object, allows_none=True)
+
+ check('(OO)', (1, 2))
+ self.assertEqual(parse((((1, 2), 3),),{}, '((OO)?O)', ['a']), (1, 2, 3))
+ self.assertEqual(parse(((None, 3),),{}, '((OO)?O)', ['a']), (NULL, NULL, 3))
+ self.assertEqual(parse((((1, 2), 3),),{}, '((OO)O)', ['a']), (1, 2, 3))
+ self.assertRaises(TypeError, parse, ((None, 3),),{}, '((OO)O)', ['a'])
+
+ parse((None,),{}, 'es?', ['a'])
+ parse((None,),{}, 'es#?', ['a'])
+ parse((None,),{}, 'et?', ['a'])
+ parse((None,),{}, 'et#?', ['a'])
+ parse((None,),{}, 'O!?', ['a'])
+ parse((None,),{}, 'O&?', ['a'])
+
+ # TODO: More tests for es?, es#?, et?, et#?, O!, O&
+
  @unittest.skipIf(_testinternalcapi is None, 'needs _testinternalcapi')
  def test_gh_119213(self):
  rc, out, err = script_helper.assert_python_ok("-c", """if True:

Lib/test/test_mmap.py

@@ -732,7 +732,7 @@ def test_tagname(self):
  m2.close()
  m1.close()
 
- with self.assertRaisesRegex(TypeError, 'tagname'):
+ with self.assertRaisesRegex(TypeError, 'must be str or None'):
  mmap.mmap(-1, 8, tagname=1)
 
  @cpython_only

Misc/NEWS.d/next/C_API/2025-01-08-18-55-57.gh-issue-112068.ofI5Fl.rst

@@ -0,0 +1,3 @@
+Add support of nullable arguments in :c:func:`PyArg_Parse` and similar
+functions. Adding ``?`` after any format unit makes ``None`` be accepted as
+a value.

Modules/_ctypes/_ctypes.c

@@ -3848,9 +3848,7 @@ _validate_paramflags(ctypes_state *st, PyTypeObject *type, PyObject *paramflags)
  PyObject *name = Py_None;
  PyObject *defval;
  PyObject *typ;
- if (!PyArg_ParseTuple(item, "i|OO", &flag, &name, &defval) ||
- !(name == Py_None || PyUnicode_Check(name)))
-{
+ if (!PyArg_ParseTuple(item, "i|U?O", &flag, &name, &defval)){
  PyErr_SetString(PyExc_TypeError,
  "paramflags must be a sequence of (int [,string [,value]]) tuples");
  return 0;
@@ -3915,10 +3913,8 @@ PyCFuncPtr_FromDll(PyTypeObject *type, PyObject *args, PyObject *kwds)
  void *handle;
  PyObject *paramflags = NULL;
 
- if (!PyArg_ParseTuple(args, "O|O", &ftuple, &paramflags))
+ if (!PyArg_ParseTuple(args, "O|O?", &ftuple, &paramflags))
  return NULL;
- if (paramflags == Py_None)
- paramflags = NULL;
 
  ftuple = PySequence_Tuple(ftuple);
  if (!ftuple)
@@ -4050,10 +4046,8 @@ PyCFuncPtr_FromVtblIndex(PyTypeObject *type, PyObject *args, PyObject *kwds)
  GUID *iid = NULL;
  Py_ssize_t iid_len = 0;
 
- if (!PyArg_ParseTuple(args, "is|Oz#", &index, &name, &paramflags, &iid, &iid_len))
+ if (!PyArg_ParseTuple(args, "is|O?z#", &index, &name, &paramflags, &iid, &iid_len))
  return NULL;
- if (paramflags == Py_None)
- paramflags = NULL;
 
  ctypes_state *st = get_module_state_by_def(Py_TYPE(type));
  if (!_validate_paramflags(st, type, paramflags)){

Modules/_interpretersmodule.c

@@ -1252,14 +1252,11 @@ interp_get_config(PyObject *self, PyObject *args, PyObject *kwds)
  PyObject *idobj = NULL;
  int restricted = 0;
  if (!PyArg_ParseTupleAndKeywords(args, kwds,
- "O|$p:get_config", kwlist,
+ "O?|$p:get_config", kwlist,
  &idobj, &restricted))
 {
  return NULL;
  }
- if (idobj == Py_None){
- idobj = NULL;
- }
 
  int reqready = 0;
  PyInterpreterState *interp = \
@@ -1376,14 +1373,14 @@ capture_exception(PyObject *self, PyObject *args, PyObject *kwds)
  static char *kwlist[] ={"exc", NULL};
  PyObject *exc_arg = NULL;
  if (!PyArg_ParseTupleAndKeywords(args, kwds,
- "|O:capture_exception", kwlist,
+ "|O?:capture_exception", kwlist,
  &exc_arg))
 {
  return NULL;
  }
 
  PyObject *exc = exc_arg;
- if (exc == NULL || exc == Py_None){
+ if (exc == NULL){
  exc = PyErr_GetRaisedException();
  if (exc == NULL){
  Py_RETURN_NONE;

Modules/_json.c

@@ -1228,23 +1228,16 @@ encoder_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
  static char *kwlist[] ={"markers", "default", "encoder", "indent", "key_separator", "item_separator", "sort_keys", "skipkeys", "allow_nan", NULL};
 
  PyEncoderObject *s;
- PyObject *markers, *defaultfn, *encoder, *indent, *key_separator;
+ PyObject *markers = Py_None, *defaultfn, *encoder, *indent, *key_separator;
  PyObject *item_separator;
  int sort_keys, skipkeys, allow_nan;
 
- if (!PyArg_ParseTupleAndKeywords(args, kwds, "OOOOUUppp:make_encoder", kwlist,
- &markers, &defaultfn, &encoder, &indent,
+ if (!PyArg_ParseTupleAndKeywords(args, kwds, "O!?OOOUUppp:make_encoder", kwlist,
+ &PyDict_Type, &markers, &defaultfn, &encoder, &indent,
  &key_separator, &item_separator,
  &sort_keys, &skipkeys, &allow_nan))
  return NULL;
 
- if (markers != Py_None && !PyDict_Check(markers)){
- PyErr_Format(PyExc_TypeError,
- "make_encoder() argument 1 must be dict or None, "
- "not %.200s", Py_TYPE(markers)->tp_name);
- return NULL;
- }
-
  s = (PyEncoderObject *)type->tp_alloc(type, 0);
  if (s == NULL)
  return NULL;

Modules/_threadmodule.c

@@ -651,12 +651,12 @@ PyThreadHandleObject_join(PyObject *op, PyObject *args)
  PyThreadHandleObject *self = PyThreadHandleObject_CAST(op);
 
  PyObject *timeout_obj = NULL;
- if (!PyArg_ParseTuple(args, "|O:join", &timeout_obj)){
+ if (!PyArg_ParseTuple(args, "|O?:join", &timeout_obj)){
  return NULL;
  }
 
  PyTime_t timeout_ns = -1;
- if (timeout_obj != NULL && timeout_obj != Py_None){
+ if (timeout_obj != NULL){
  if (_PyTime_FromSecondsObject(&timeout_ns, timeout_obj,
  _PyTime_ROUND_TIMEOUT) < 0){
  return NULL;
@@ -1919,10 +1919,10 @@ thread_PyThread_start_joinable_thread(PyObject *module, PyObject *fargs,
  PyObject *func = NULL;
  int daemon = 1;
  thread_module_state *state = get_thread_state(module);
- PyObject *hobj = NULL;
+ PyObject *hobj = Py_None;
  if (!PyArg_ParseTupleAndKeywords(fargs, fkwargs,
- "O|Op:start_joinable_thread", keywords,
- &func, &hobj, &daemon)){
+ "O|O!?p:start_joinable_thread", keywords,
+ &func, state->thread_handle_type, &hobj, &daemon)){
  return NULL;
  }
 
@@ -1932,14 +1932,6 @@ thread_PyThread_start_joinable_thread(PyObject *module, PyObject *fargs,
  return NULL;
  }
 
- if (hobj == NULL){
- hobj = Py_None;
- }
- else if (hobj != Py_None && !Py_IS_TYPE(hobj, state->thread_handle_type)){
- PyErr_SetString(PyExc_TypeError, "'handle' must be a _ThreadHandle");
- return NULL;
- }
-
  if (PySys_Audit("_thread.start_joinable_thread", "OiO", func, daemon,
  hobj) < 0){
  return NULL;

Modules/mmapmodule.c

@@ -23,7 +23,6 @@
 #endif
 
 #include <Python.h>
-#include "pycore_abstract.h" // _Py_convert_optional_to_ssize_t()
 #include "pycore_bytesobject.h" // _PyBytes_Find()
 #include "pycore_fileutils.h" // _Py_stat_struct
 
@@ -516,7 +515,7 @@ mmap_read_method(PyObject *op, PyObject *args)
  mmap_object *self = mmap_object_CAST(op);
 
  CHECK_VALID(NULL);
- if (!PyArg_ParseTuple(args, "|O&:read", _Py_convert_optional_to_ssize_t, &num_bytes))
+ if (!PyArg_ParseTuple(args, "|n?:read", &num_bytes))
  return NULL;
  CHECK_VALID(NULL);
 
@@ -1710,7 +1709,7 @@ new_mmap_object(PyTypeObject *type, PyObject *args, PyObject *kwdict)
  DWORD off_lo; /* lower 32 bits of offset */
  DWORD size_hi; /* upper 32 bits of size */
  DWORD size_lo; /* lower 32 bits of size */
- PyObject *tagname = Py_None;
+ PyObject *tagname = NULL;
  DWORD dwErr = 0;
  int fileno;
  HANDLE fh = 0;
@@ -1720,7 +1719,7 @@ new_mmap_object(PyTypeObject *type, PyObject *args, PyObject *kwdict)
  "tagname",
  "access", "offset", NULL };
 
- if (!PyArg_ParseTupleAndKeywords(args, kwdict, "in|OiL", keywords,
+ if (!PyArg_ParseTupleAndKeywords(args, kwdict, "in|U?iL", keywords,
  &fileno, &map_size,
  &tagname, &access, &offset)){
  return NULL;
@@ -1853,13 +1852,7 @@ new_mmap_object(PyTypeObject *type, PyObject *args, PyObject *kwdict)
  m_obj->weakreflist = NULL;
  m_obj->exports = 0;
  /* set the tag name */
- if (!Py_IsNone(tagname)){
- if (!PyUnicode_Check(tagname)){
- Py_DECREF(m_obj);
- return PyErr_Format(PyExc_TypeError, "expected str or None for "
- "'tagname', not %.200s",
- Py_TYPE(tagname)->tp_name);
- }
+ if (tagname != NULL){
  m_obj->tagname = PyUnicode_AsWideCharString(tagname, NULL);
  if (m_obj->tagname == NULL){
  Py_DECREF(m_obj);