What is the purpose of Py_DECREF and PY_INCREF?

Question

I was going through the tutorial for defining 'new types' in python, https://docs.python.org/2/extending/newtypes.html, and I did not understand the purpose of using Py_DECREF in this piece of code.

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyString_FromString("");
        if (self->first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->last = PyString_FromString("");
        if (self->last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->number = 0;
    }

    return (PyObject *)self;
}

My understanding of reference counting is patchy and any help would be appreciated.

Answer 1

In this case, Py_DECREF would simply free the memory allocated with tp->alloc.

tp->alloc sets the ref count to 1. Py_DECREF decreases the ref count from 1 to 0; as it finds the ref count is 0, it calls the appropriate functions to free the memory (Noddy_dealloc in this case.)

If a python C api function returns NULL, something has gone wrong; usually an exception is set (saved in a global variable).

If the caller returns NULL again, the exception is chained, hence the 'return NULL'.