static int
list_resize(PyListObject *self, Py_ssize_t newsize)
{

    PyObject **items;
    size_t new_allocated, num_allocated_bytes;
    Py_ssize_t allocated = self->allocated;

    /* Bypass realloc() when a previous overallocation is large enough
       to accommodate the newsize.  If the newsize falls lower than half
       the allocated size, then proceed with the realloc() to shrink the list.
    */

    // 扩容、缩容机制调用realloc()函数
    // allocated = 容量
    // newsize代表已存在的数据项个数 + 1

    // 当前列表容量 > 已有数据项个数+1 and 已有数据项个数 >=  当前列表容量的一半
    if (allocated >= newsize && newsize >= (allocated >> 1)) {
    
        assert(self->ob_item != NULL || newsize == 0);
        // 则直接添加数据项，不进行扩容
        // 并新增数据项个数 Py_ssize_t ob_size + 1
        Py_SET_SIZE(self, newsize);
        return 0;
    }

    /* This over-allocates proportional to the list size, making room
     * for additional growth.  The over-allocation is mild, but is
     * enough to give linear-time amortized behavior over a long
     * sequence of appends() in the presence of a poorly-performing
     * system realloc().
     * Add padding to make the allocated size multiple of 4.
     * The growth pattern is:  0, 4, 8, 16, 24, 32, 40, 52, 64, 76, ...
     * Note: new_allocated won't overflow because the largest possible value
     *       is PY_SSIZE_T_MAX * (9 / 8) + 6 which always fits in a size_t.
     */
    new_allocated = ((size_t)newsize + (newsize >> 3) + 6) & ~(size_t)3;
    /* Do not overallocate if the new size is closer to overallocated size
     * than to the old size.
     */

    // 如果数据项个数 + 1 < 当前列表容量的一半，则进行缩容，删除空的列表槽位
    // 当前列表容量 <  已有数据项个数+1，则先进行扩容后再添加数据项
    // 下面这句话是获取新的容量值
    if (newsize - Py_SIZE(self) > (Py_ssize_t)(new_allocated - newsize))
        new_allocated = ((size_t)newsize + 3) & ~(size_t)3;

    // 全是空的
    if (newsize == 0)
        new_allocated = 0;

    num_allocated_bytes = new_allocated * sizeof(PyObject *);

    // 基于realloc()进行扩容或者缩容，内部会包含数据项的位置调整
    items = (PyObject **)PyMem_Realloc(self->ob_item, num_allocated_bytes);
    if (items == NULL) {
        PyErr_NoMemory();
        return -1;
    }
    // 重新设置列表的 ob_item、obsize、allocated
    self->ob_item = items;
    Py_SET_SIZE(self, newsize);
    self->allocated = new_allocated;
    return 0;
}

插入元素

static int
ins1(PyListObject *self, Py_ssize_t where, PyObject *v)
{
    // 获取数据项个数
    Py_ssize_t i, n = Py_SIZE(self);
    PyObject **items;
    
    // 插入数据项确保不是NULL
    if (v == NULL) {
        PyErr_BadInternalCall();
        return -1;
    }

    assert((size_t)n + 1 < PY_SSIZE_T_MAX);
    
    // 重新计算容量是否可容纳新数据项的加入，从而进行扩容或缩容
    if (list_resize(self, n+1) < 0)
        return -1;
    
    // 如果where小于0，代表通过倒序索引进行插入
    if (where < 0) {
        where += n;
        if (where < 0)
            where = 0;
    }
   
   // 如果where大于列表的大小（已占据容量），则where = 已占据容量
   // 即插入到最后的一个位置
    if (where > n)
        where = n;
    
    // 拿到列表中所有数据项的引用
    items = self->ob_item;
    
    // 让插入位置之后的所有数据项开始向后挪动1个位置，腾出位置来插入新的数据项
    for (i = n; --i >= where; )
        // i + 1指的是数据项指针地址，每次 - 1
        items[i+1] = items[i];
    
    // 新增数据项的引用计数 + 1
    Py_INCREF(v);
    
    // 新的数据项索引位置和值做绑定
    items[where] = v;
    return 0;
}

int
PyList_Insert(PyObject *op, Py_ssize_t where, PyObject *newitem)
{
    // 传入列表的引用， 插入的位置，还有新的数据项引用，并且验证列表和数据项
    if (!PyList_Check(op)) {
        PyErr_BadInternalCall();
        return -1;
    }
    // 进行插入
    return ins1((PyListObject *)op, where, newitem);
}

static PyObject *
list_pop_impl(PyListObject *self, Py_ssize_t index)
// 传入列表的引用，列表的弹出数据项索引位置

{
    PyObject *v;
    int status;

    // 如果是一个空列表，则抛出异常
    if (Py_SIZE(self) == 0) {
        /* Special-case most common failure cause */
        PyErr_SetString(PyExc_IndexError, "pop from empty list");
        return NULL;
    }
    if (index < 0)
        index += Py_SIZE(self);
        
    // 如果索引值不存在，则抛出异常
    if (!valid_index(index, Py_SIZE(self))) {
        PyErr_SetString(PyExc_IndexError, "pop index out of range");
        return NULL;
    }
    
    // 找到准备弹出的数据项位置
    v = self->ob_item[index];
    
    // 如果弹出的数据项是列表中的最后一个
    if (index == Py_SIZE(self) - 1) {
        // list_resize()内部只会做size - 1，而不会回收内存进行缩容
        status = list_resize(self, Py_SIZE(self) - 1);
        if (status >= 0)
            return v; /* and v now owns the reference the list had */
        else
            return NULL;
    }
    // 增加一次引用计数器
    Py_INCREF(v);
    
    // 如果弹出的数据项不是列表中的最后一个，则需要进行位置调整
    status = list_ass_slice(self, index, index+1, (PyObject *)NULL);
    if (status < 0) {
        Py_DECREF(v);
        return NULL;
    }
    
    // 返回被弹出的数据项
    return v;
}

static int
_list_clear(PyListObject *a)
{
    Py_ssize_t i;
    PyObject **item = a->ob_item;
    if (item != NULL) {
        /* Because XDECREF can recursively invoke operations on
           this list, we make it empty first. */
        i = Py_SIZE(a);
        // 重新设置大小为0
        Py_SET_SIZE(a, 0);
        // 将列表中插槽引用的对象全部设置为None
        a->ob_item = NULL;
        // 重新设置容量为0
        a->allocated = 0;
        // 循环列表中的数据项，令所有数据项的引用计数-1
        while (--i >= 0) {
            Py_XDECREF(item[i]);
        }
        PyMem_Free(item);
    }
    /* Never fails; the return value can be ignored.
       Note that there is no guarantee that the list is actually empty
       at this point, because XDECREF may have populated it again! */
    return 0;
}

static void
list_dealloc(PyListObject *op)
{
    Py_ssize_t i;
    
    // 内部会判断这个列表是否还有其他标识符引用，如果为0则代表没有其他标识符引用
    // 可以通过内部GC机制将该列表所占据的内存空间进行释放
    PyObject_GC_UnTrack(op);
    Py_TRASHCAN_BEGIN(op, list_dealloc)
    if (op->ob_item != NULL) {
        /* Do it backwards, for Christian Tismer.
           There's a simple test case where somehow this reduces
           thrashing when a *very* large list is created and
           immediately deleted. */
           
        // 获取列表中已有数据项的个数（即大小）
        i = Py_SIZE(op);
        // 循环列表中的数据项，令所有数据项的引用计数-1
        while (--i >= 0) {
            Py_XDECREF(op->ob_item[i]);
        }
        PyMem_Free(op->ob_item);
    }
    struct _Py_list_state *state = get_list_state();
    
    
#ifdef Py_DEBUG
    // list_dealloc() must not be called after _PyList_Fini()
    assert(state->numfree != -1);
#endif

    // 判断free_list中的已缓存列表个数是否大于80，这里是没满
    // 在free_list中添加空列表的引用即可
    if (state->numfree < PyList_MAXFREELIST && PyList_CheckExact(op)) {
        state->free_list[state->numfree++] = op;
    }
    else {
        // 如果free_list的大小已达到容量限制
        // 则直接在内存中销毁列表的结构体对象
        Py_TYPE(op)->tp_free((PyObject *)op);
    }
    Py_TRASHCAN_END
}