5.5 Parsing arguments and building values
Keywords: api

#
5.5 Parsing arguments and building values

These functions are useful when creating your own extensions functions and methods. Additional information and examples are available in Extending and Embedding the Python Interpreter.

int `PyArg_ParseTuple`(PyObject *args, char *format, ...)
  Parse the parameters of a function that takes only positional parameters into local variables. Returns true on success; on failure, it returns false and raises the appropriate exception. See Extending and Embedding the Python Interpreter for more information.

int `PyArg_ParseTupleAndKeywords`(PyObject *args, PyObject *kw, char *format, char *keywords[], ...)
  Parse the parameters of a function that takes both positional and keyword parameters into local variables. Returns true on success; on failure, it returns false and raises the appropriate exception. See Extending and Embedding the Python Interpreter for more information.

int `PyArg_Parse`(PyObject *args, char *format, ...)
  Function used to deconstruct the argument lists of ``old-style'' functions -- these are functions which use the `METH_OLDARGS` parameter parsing method. This is not recommended for use in parameter parsing in new code, and most code in the standard interpreter has been modified to no longer use this for that purpose. It does remain a convenient way to decompose other tuples, however, and may continue to be used for that purpose.

int `PyArg_UnpackTuple`(PyObject *args, char *name, int min, int max, ...)
  A simpler form of parameter retrieval which does not use a format string to specify the types of the arguments. Functions which use this method to retrieve their parameters should be declared as `METH_VARARGS` in function or method tables. The tuple containing the actual parameters should be passed as args; it must actually be a tuple. The length of the tuple must be at least min and no more than max; min and max may be equal. Additional arguments must be passed to the function, each of which should be a pointer to a `PyObject*` variable; these will be filled in with the values from args; they will contain borrowed references. The variables which correspond to optional parameters not given by args will not be filled in; these should be initialized by the caller. This function returns true on success and false if args is not a tuple or contains the wrong number of elements; an exception will be set if there was a failure.

  This is an example of the use of this function, taken from the sources for the `_weakref` helper module for weak references:

        static PyObject *
        weakref_ref(PyObject *self, PyObject *args)
        {
            PyObject *object;
            PyObject *callback = NULL;
            PyObject *result = NULL;

            if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
                result = PyWeakref_NewRef(object, callback);
            }
            return result;
        }

  The call to `PyArg_UnpackTuple()` in this example is entirely equivalent to this call to `PyArg_ParseTuple()`:

        PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

  New in version 2.2.

PyObject* `Py_BuildValue`(char *format, ...)
  Return value: New reference.
  Create a new value based on a format string similar to those accepted by the `PyArg_Parse*()` family of functions and a sequence of values. Returns the value or `NULL` in the case of an error; an exception will be raised if `NULL` is returned. For more information on the format string and additional parameters, see Extending and Embedding the Python Interpreter.