from typing import Iterable

print(
    isinstance("", Iterable),
    isinstance((), Iterable),
    isinstance([], Iterable),
    isinstance({}, Iterable),
    isinstance(set(), Iterable),
)  # True True True True True

print(
    isinstance(0, Iterable),
    isinstance(0.0, Iterable),
)  # False False

class A:

    def __getitem__(self, item):
        return f"參數 item: {item}"

a = A()
# 內部定義了 __getitem__
# 首先可以讓實例對象像字典一樣訪問屬性
print(a["name"])  # 參數 item: name
print(a["satori"])  # 參數 item: satori

# 此外還可以像可迭代對象一樣被 for 循環
# 循環的時候會自動給 item 傳值：0 1 2 3 ...
# 如果內部出現了 StopIteration，循環結束
# 否則會一直循環下去，這里我們手動 break
for idx, val in enumerate(a):
    print(val)
    if idx == 5:
        break
"""
參數 item: 0
參數 item: 1
參數 item: 2
參數 item: 3
參數 item: 4
參數 item: 5
"""

from typing import Iterable
print(isinstance(a, Iterable))  # False

data = [1, 2, 3]
# 底層調用的其實是 list.__iter__(data)
# 或者說 PyList_Type.tp_iter(data)
it = data.__iter__()
print(it)
"""
<list_iterator object at 0x102c1cf10>
"""
print(str.__iter__(""))
"""
<str_iterator object at 0x100e623b0>
"""
print(tuple.__iter__(()))
"""
<tuple_iterator object at 0x100e623b0>
"""
# 不難發現，迭代器的種類有非常多
# 比如 list_iterator、str_iterator、tuple_iterator 等等

data = [1, 2, 3]
# 等價于 type(data).__iter__(data)
it = iter(data)

val = 0

def foo():
    global val
    val += 1
    return val

# iter 可以接收一個參數: iter(可迭代對象)
# iter 也可以接收兩個參數: iter(可調用對象, value)
for i in iter(foo, 5):
    print(i)
"""
1
2
3
4
"""

// Python/clinic/bltinmodule.c.h
static PyObject *
builtin_iter(PyObject *module, PyObject *const *args, Py_ssize_t nargs)
{
    PyObject *return_value = NULL;
    PyObject *object;
    PyObject *sentinel = NULL;
    // 內置函數 iter 接收 1 ~ 2 個參數
    if (!_PyArg_CheckPositional("iter", nargs, 1, 2)) {
        goto exit;
    }
    // 如果 nargs 小于 2，那么 args[0] 是可迭代對象
    // 如果 nargs 等于 2，那么 args[0] 是可調用對象
    object = args[0];
    if (nargs < 2) {
        goto skip_optional;
    }
    sentinel = args[1];
skip_optional:
    // 具體實現由 builtin_iter_impl 負責
    // 它會調用可迭代對象的 __iter__ 方法，返回迭代器
    return_value = builtin_iter_impl(module, object, sentinel);

exit:
    return return_value;
}

// Python/bltinmodule.c
static PyObject *
builtin_iter_impl(PyObject *module, PyObject *object, PyObject *sentinel)
{
    // 如果哨兵為空，說明只傳了一個參數，那么該參數應該是可迭代對象
    if (sentinel == NULL)
        // 調用 PyObject_GetIter 獲取對象的迭代器
        return PyObject_GetIter(object);
    // 如果哨兵不為空，那么第一個參數應該是可調用對象
    // 這里進行檢測，如果不是，拋出 TypeError
    if (!PyCallable_Check(object)) {
        PyErr_SetString(PyExc_TypeError,
                        "iter(object, sentinel): object must be callable");
        return NULL;
    }
    // 一會兒單獨解釋
    return PyCallIter_New(object, sentinel);
}

// Objects/abstract.c
PyObject *
PyObject_GetIter(PyObject *o)
{
    // 獲取可迭代對象的類型對象，比如 o 是列表，那么 t 就是 list
    PyTypeObject *t = Py_TYPE(o);
    // 我們說類型對象定義的操作，決定了實例對象的行為
    // 實例對象調用的那些方法都是定義在類型對象里面的
    // 還是那句話：obj.func() 等價于 type(obj).func(obj)
    getiterfunc f;
    
    // 所以這里是獲取類型對象的 tp_iter 字段
    // 也就是 Python 中的 __iter__
    f = t->tp_iter;
    // 如果 f 為 NULL，說明類型對象的內部沒有定義 __iter__ 
    // 像 str、tuple、list 等類型對象，它們的 tp_iter 字段都是不為 NULL 的
    if (f == NULL) {
        // 如果 tp_iter 為 NULL，那么解釋器會退而求其次
        // 檢測該類型對象中是否定義了 __getitem__
        // 如果定義了，那么直接調用 PySeqIter_New，創建 seqiterobject 對象
        // 下面的 PySequence_Check 函數負責檢測類型對象是否實現了 __getitem__
        // __getitem__ 對應 tp_as_sequence->sq_item
        if (PySequence_Check(o))
            return PySeqIter_New(o);
        // 走到這里說明該類型對象既沒有 __iter__、也沒有 __getitem__
        // 因此它的實例對象不具備可迭代的性質，于是拋出異常
        return type_error("'%.200s' object is not iterable", o);
    }
    else {
        // 否則說明定義了 __iter__，于是直接進行調用
        // Py_TYPE(o)->tp_iter(o) 返回對應的迭代器
        PyObject *res = (*f)(o);
        // 但如果返回值 res 不為 NULL、并且還不是迭代器
        // 證明 __iter__ 的返回值有問題，于是拋出異常
        if (res != NULL && !PyIter_Check(res)) {
            PyErr_Format(PyExc_TypeError,
                         "iter() returned non-iterator "
                         "of type '%.100s'",
                         Py_TYPE(res)->tp_name);
            Py_SETREF(res, NULL);
        }
        // 返回 res
        return res;
    }
}

// Objects/listobject.c

// 列表迭代器的類型對象為 <class 'list_iterator'>
// 但這個類，解釋器并沒有暴露給我們，所以需要通過 type 獲取
// 然后它的 tp_basicsize 字段為 sizeof(_PyListIterObject)
// 這就說明列表迭代器在底層由 _PyListIterObject 結構體表示
PyTypeObject PyListIter_Type = {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
    "list_iterator",                            /* tp_name */
    sizeof(_PyListIterObject),                  /* tp_basicsize */
    0,                                          /* tp_itemsize */
    // ...
};

// Include/internal/pycore_list.h
typedef struct {
    PyObject_HEAD
    Py_ssize_t it_index;
    // 指向創建該迭代器的列表
    PyListObject *it_seq; 
} _PyListIterObject;

from ctypes import *

class PyObject(Structure):
    _fields_ = [
        ("ob_refcnt", c_ssize_t),
        ("ob_size", c_void_p)
    ]

class ListIterObject(PyObject):
    _fields_ = [
        ("it_index", c_ssize_t),
        ("it_seq", POINTER(PyObject))
    ]

it = iter([1, 2, 3])
it_obj = ListIterObject.from_address(id(it))

# it_seq 指向列表 [1, 2, 3]，it_index 初始為 0
print(it_obj.it_index)  # 0
# 進行迭代
next(it)
# 索引自增 1，此時 it_index 等于 1
print(it_obj.it_index)  # 1
# 再次迭代
next(it)
# 此時 it_index 等于 2
print(it_obj.it_index)  # 2
# 再次迭代
next(it)
# 此時 it_index 等于 3
print(it_obj.it_index)  # 3

// Python/clinic/bltinmodule.c.h
static PyObject *
builtin_next(PyObject *module, PyObject *const *args, Py_ssize_t nargs)
{
    PyObject *return_value = NULL;
    PyObject *iterator;
    PyObject *default_value = NULL;
    // 同樣接收 1 ~ 2 個參數
    // 因為調用 next 函數時，可以傳入一個默認值
    // 表示當迭代器沒有元素可以迭代的時候，會返回指定的默認值
    if (!_PyArg_CheckPositional("next", nargs, 1, 2)) {
        goto exit;
    }
    // 迭代器
    iterator = args[0];
    if (nargs < 2) {
        goto skip_optional;
    }
    // 默認值
    default_value = args[1];
skip_optional:
    return_value = builtin_next_impl(module, iterator, default_value);

exit:
    return return_value;
}

// Python/bltinmodule.c
static PyObject *
builtin_next_impl(PyObject *module, PyObject *iterator,
                  PyObject *default_value)
{
    PyObject *res;
    // 第一個參數必須是迭代器，否則拋出 TypeError
    if (!PyIter_Check(iterator)) {
        PyErr_Format(PyExc_TypeError,
            "'%.200s' object is not an iterator",
            Py_TYPE(iterator)->tp_name);
        return NULL;
    }
    // Py_TYPE(iterator) 表示獲取類型對象，也就是該迭代器的類型
    // 當然具體類型是哪一種并不確定，可能是列表迭代器、元組迭代器、字符串迭代器等等
    // 然后再獲取 tp_iternext 字段，相當于 __next__
    // 拿到函數指針之后，傳入迭代器進行調用
    res = (*Py_TYPE(iterator)->tp_iternext)(iterator);
    // 如果 res 不為 NULL, 那么證明迭代到值了, 直接返回
    if (res != NULL) {
        return res;
    } else if (default_value != NULL) {
        // 否則的話，說明沒有迭代到值（返回 NULL），那么這時候有兩種情況
        // 1）迭代器已耗盡，2）在迭代過程中出現異常
        // 那么判斷 default_value，如果不為 NULL，說明設置了默認值
        if (PyErr_Occurred()) {
            // 檢測異常是不是迭代完畢時（或者手動 raise）產生的 StopIteration 異常
            if(!PyErr_ExceptionMatches(PyExc_StopIteration))
                // 如果不是，說明程序的邏輯有問題，直接 return NULL，結束執行
                // 然后在 Python 里面我們會看到打印到 stderr 中的異常信息
                return NULL;
            // 如果異常是 StopIteration，證明迭代完畢了
            // 但我們設置了默認值，那么就應該返回默認值
            // 而不應該拋出 StopIteration，于是將異常回溯棧給清空
            PyErr_Clear();
        }
        // 增加 default_value 的引用計數，然后返回
        return Py_NewRef(default_value);
    } else if (PyErr_Occurred()) {
        // 走到這里說明 res == NULL，并且沒有指定默認值
        // 那么當發生異常時，將異常直接拋出
        return NULL;
    } else {
        // 都不是的話，直接拋出 StopIteration
        PyErr_SetNone(PyExc_StopIteration);
        return NULL;
    }
}

data = [1, 2, 3]
it = iter(data)
# 然后迭代，等價于 next(it)
print(type(it).__next__(it))  # 1
print(type(it).__next__(it))  # 2
print(type(it).__next__(it))  # 3
# 但是 next 可以指定默認值
# 如果不指定默認值，或者還是 type(it).__next__(it)
# 那么就會報錯，拋出 StopIteration
print(next(it, 666))  # 666

// Objects/listobject.c
static PyObject *
listiter_next(_PyListIterObject *it)
{
    // 迭代器只是對可迭代對象的一層封裝
    // 如果是列表的迭代器，那么內部的 it_seq 字段便指向列表
    PyListObject *seq;
    PyObject *item;

    assert(it != NULL);
    // 如果 it->it_seq 等于 NULL，說明迭代器已經迭代完畢了
    // 從這里也能看出迭代器不能二次循環迭代
    seq = it->it_seq;
    if (seq == NULL)
        return NULL;
    assert(PyList_Check(seq));
    // 如果 it->it_index 小于列表的長度
    if (it->it_index < PyList_GET_SIZE(seq)) {
        // 那么獲取元素
        item = PyList_GET_ITEM(seq, it->it_index);
        // it_index 自增 1
        ++it->it_index;
        // 增加元素的引用計數，并返回
        return Py_NewRef(item);
    }
    // 否則說明 it_index 已經達到了列表的長度
    // 再迭代就索引越界了，而對于迭代器來說
    // 當 it_index 等于列表長度時，就證明所有元素都迭代完畢了
    it->it_seq = NULL;  // 將 it_seq 設置為 NULL
    Py_DECREF(seq);
    return NULL;
}

// Python/bltinmodule.c
static PyObject *
builtin_iter_impl(PyObject *module, PyObject *object, PyObject *sentinel)
{
    if (sentinel == NULL)
        return PyObject_GetIter(object);
    if (!PyCallable_Check(object)) {
        PyErr_SetString(PyExc_TypeError,
                        "iter(object, sentinel): object must be callable");
        return NULL;
    }
    // 如果 sentinel 不等于 NULL，會調用 PyCallIter_New
    return PyCallIter_New(object, sentinel);
}


// Objects/iterobject.c
typedef struct {
    PyObject_HEAD
    PyObject *it_callable; 
    PyObject *it_sentinel; 
} calliterobject;

PyObject *
PyCallIter_New(PyObject *callable, PyObject *sentinel)
{
    // iter(callable, value) 會返回一個 <class 'callable_iterator'> 實例
    // 在底層由 calliterobject 結構體實現
    calliterobject *it;
    // 為 calliterobject 實例申請內存
    it = PyObject_GC_New(calliterobject, &PyCallIter_Type);
    if (it == NULL)
        return NULL;
    // 初始化字段
    it->it_callable = Py_NewRef(callable);
    it->it_sentinel = Py_NewRef(sentinel);
    _PyObject_GC_TRACK(it);
    return (PyObject *)it;
}

// 再來看看迭代過程
static PyObject *
calliter_iternext(calliterobject *it)
{
    PyObject *result;
    // 如果 it_callable 字段為空，說明迭代結束，不能再次迭代
    if (it->it_callable == NULL) {
        return NULL;
    }
    // 調用 it_callable，拿到返回值 result
    result = _PyObject_CallNoArgs(it->it_callable);
    if (result != NULL && it->it_sentinel != NULL){
        int ok;
        // 如果 result 和哨兵相等，那么 ok == 1，否則 ok == 0
        ok = PyObject_RichCompareBool(it->it_sentinel, result, Py_EQ);
        // 如果 ok == 0，說明兩者不相等，那么返回 result
        if (ok == 0) {
            return result; 
        }
        // 如果返回值和哨兵相等，那么迭代結束
        // 減少引用計數，并將 it_callable 和 it_sentinel 字段設置為 NULL
        if (ok > 0) {
            Py_CLEAR(it->it_callable);
            Py_CLEAR(it->it_sentinel);
        }
    }
    else if (PyErr_ExceptionMatches(PyExc_StopIteration)) {
        // 如果函數拋出了 StopIteration 異常，同樣視為迭代結束
        PyErr_Clear();
        Py_CLEAR(it->it_callable);
        Py_CLEAR(it->it_sentinel);
    }
    Py_XDECREF(result);
    return NULL;
}