diff options
Diffstat (limited to 'Doc/c-api')
| -rw-r--r-- | Doc/c-api/arg.rst | 5 | ||||
| -rw-r--r-- | Doc/c-api/structures.rst | 61 |
2 files changed, 64 insertions, 2 deletions
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 1b2ab8f843..96068d988a 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -53,8 +53,9 @@ variable(s) whose address should be passed. string may contain embedded null bytes. Unicode objects pass back a pointer to the default encoded string version of the object if such a conversion is possible. All other read-buffer compatible objects pass back a reference to - the raw internal data representation. Since this format doesn't allow writable buffer compatible objects like byte - arrays, ``s*`` is to be preferred. + the raw internal data representation. Since this format doesn't allow + writable buffer compatible objects like byte arrays, ``s*`` is to be + preferred. The type of the length argument (int or :ctype:`Py_ssize_t`) is controlled by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before including diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 04fe8f44d5..fdbd806cb9 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -198,3 +198,64 @@ definition with the same method name. object and will co-exist with the slot. This is helpful because calls to PyCFunctions are optimized more than wrapper object calls. + +.. ctype:: PyMemberDef + + Structure which describes an attribute of a type which corresponds to a C + struct member. Its fields are: + + +------------------+-------------+-------------------------------+ + | Field | C Type | Meaning | + +==================+=============+===============================+ + | :attr:`name` | char \* | name of the member | + +------------------+-------------+-------------------------------+ + | :attr:`type` | int | the type of the member in the | + | | | C struct | + +------------------+-------------+-------------------------------+ + | :attr:`offset` | Py_ssize_t | the offset in bytes that the | + | | | member is located on the | + | | | type's object struct | + +------------------+-------------+-------------------------------+ + | :attr:`flags` | int | flag bits indicating if the | + | | | field should be read-only or | + | | | writable | + +------------------+-------------+-------------------------------+ + | :attr:`doc` | char \* | points to the contents of the | + | | | docstring | + +------------------+-------------+-------------------------------+ + + :attr:`type` can be one of many ``T_`` macros corresponding to various C + types. When the member is accessed in Python, it will be converted to the + equivalent Python type. + + =============== ================== + Macro name C type + =============== ================== + T_SHORT short + T_INT int + T_LONG long + T_FLOAT float + T_DOUBLE double + T_STRING char \* + T_OBJECT PyObject \* + T_OBJECT_EX PyObject \* + T_CHAR char + T_BYTE char + T_UNBYTE unsigned char + T_UINT unsigned int + T_USHORT unsigned short + T_ULONG unsigned long + T_BOOL char + T_LONGLONG long long + T_ULONGLONG unsigned long long + T_PYSSIZET Py_ssize_t + =============== ================== + + :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX` differ in that + :cmacro:`T_OBJECT` returns ``None`` if the member is *NULL* and + :cmacro:`T_OBJECT_EX` raises an :exc:`AttributeError`. + + :attr:`flags` can be 0 for write and read access or :cmacro:`READONLY` for + read-only access. Using :cmacro:`T_STRING` for :attr:`type` implies + :cmacro:`READONLY`. Only :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX` + members can be deleted. (They are set to *NULL*). |