Document guidelines for when to use dynamically typed APIs

[erlend-aasland]

We need to agree on guidelines for when to use and when to not use dynamically typed APIs.

See capi-workgroup/problems#31 (The C API is weakly typed)

In capi-workgroup/problems#31 (comment), @markshannon suggests:

PyObject *obj, PyDictObject *dict;
PyObject_GetItem(obj);   // 👍 
PyDict_GetItem(dict);   // 👍 
PyObject_GetItem((PyObject *)dict); // Pointlessly inefficient
PyDict_GetItem((PyDictObject *)obj); // Unsafe

[vstinner]

I suppose that a guideline should be decided in capi-workgroup/problems#31 first.

[erlend-aasland]

I suppose that a guideline should be decided in capi-workgroup/problems#31 first.

Definitely!