diff options
Diffstat (limited to 'Doc/c-api/module.rst')
| -rw-r--r-- | Doc/c-api/module.rst | 88 |
1 files changed, 44 insertions, 44 deletions
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index 9e1af09..1a64947 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -10,26 +10,26 @@ Module Objects There are only a few functions special to module objects. -.. cvar:: PyTypeObject PyModule_Type +.. c:var:: PyTypeObject PyModule_Type .. index:: single: ModuleType (in module types) - This instance of :ctype:`PyTypeObject` represents the Python module type. This + This instance of :c:type:`PyTypeObject` represents the Python module type. This is exposed to Python programs as ``types.ModuleType``. -.. cfunction:: int PyModule_Check(PyObject *p) +.. c:function:: int PyModule_Check(PyObject *p) Return true if *p* is a module object, or a subtype of a module object. -.. cfunction:: int PyModule_CheckExact(PyObject *p) +.. c:function:: int PyModule_CheckExact(PyObject *p) Return true if *p* is a module object, but not a subtype of - :cdata:`PyModule_Type`. + :c:data:`PyModule_Type`. -.. cfunction:: PyObject* PyModule_New(const char *name) +.. c:function:: PyObject* PyModule_New(const char *name) .. index:: single: __name__ (module attribute) @@ -41,18 +41,18 @@ There are only a few functions special to module objects. the caller is responsible for providing a :attr:`__file__` attribute. -.. cfunction:: PyObject* PyModule_GetDict(PyObject *module) +.. c:function:: PyObject* PyModule_GetDict(PyObject *module) .. index:: single: __dict__ (module attribute) Return the dictionary object that implements *module*'s namespace; this object is the same as the :attr:`__dict__` attribute of the module object. This function never fails. It is recommended extensions use other - :cfunc:`PyModule_\*` and :cfunc:`PyObject_\*` functions rather than directly + :c:func:`PyModule_\*` and :c:func:`PyObject_\*` functions rather than directly manipulate a module's :attr:`__dict__`. -.. cfunction:: char* PyModule_GetName(PyObject *module) +.. c:function:: char* PyModule_GetName(PyObject *module) .. index:: single: __name__ (module attribute) @@ -62,17 +62,17 @@ There are only a few functions special to module objects. or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned. -.. cfunction:: char* PyModule_GetFilename(PyObject *module) +.. c:function:: char* PyModule_GetFilename(PyObject *module) - Similar to :cfunc:`PyModule_GetFilenameObject` but return the filename + Similar to :c:func:`PyModule_GetFilenameObject` but return the filename encoded to 'utf-8'. .. deprecated:: 3.2 - :cfunc:`PyModule_GetFilename` raises :ctype:`UnicodeEncodeError` on - unencodable filenames, use :cfunc:`PyModule_GetFilenameObject` instead. + :c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on + unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead. -.. cfunction:: PyObject* PyModule_GetFilenameObject(PyObject *module) +.. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module) .. index:: single: __file__ (module attribute) @@ -81,23 +81,23 @@ There are only a few functions special to module objects. Return the name of the file from which *module* was loaded using *module*'s :attr:`__file__` attribute. If this is not defined, or if it is not a unicode string, raise :exc:`SystemError` and return *NULL*; otherwise return - a reference to a :ctype:`PyUnicodeObject`. + a reference to a :c:type:`PyUnicodeObject`. .. versionadded:: 3.2 -.. cfunction:: void* PyModule_GetState(PyObject *module) +.. c:function:: void* PyModule_GetState(PyObject *module) Return the "state" of the module, that is, a pointer to the block of memory allocated at module creation time, or *NULL*. See - :cmember:`PyModuleDef.m_size`. + :c:member:`PyModuleDef.m_size`. -.. cfunction:: PyModuleDef* PyModule_GetDef(PyObject *module) +.. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module) - Return a pointer to the :ctype:`PyModuleDef` struct from which the module was + Return a pointer to the :c:type:`PyModuleDef` struct from which the module was created, or *NULL* if the module wasn't created with - :cfunc:`PyModule_Create`. + :c:func:`PyModule_Create`. Initializing C modules @@ -105,14 +105,14 @@ Initializing C modules These functions are usually used in the module initialization function. -.. cfunction:: PyObject* PyModule_Create(PyModuleDef *module) +.. c:function:: PyObject* PyModule_Create(PyModuleDef *module) Create a new module object, given the definition in *module*. This behaves - like :cfunc:`PyModule_Create2` with *module_api_version* set to + like :c:func:`PyModule_Create2` with *module_api_version* set to :const:`PYTHON_API_VERSION`. -.. cfunction:: PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version) +.. c:function:: PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version) Create a new module object, given the definition in *module*, assuming the API version *module_api_version*. If that version does not match the version @@ -120,89 +120,89 @@ These functions are usually used in the module initialization function. .. note:: - Most uses of this function should be using :cfunc:`PyModule_Create` + Most uses of this function should be using :c:func:`PyModule_Create` instead; only use this if you are sure you need it. -.. ctype:: PyModuleDef +.. c:type:: PyModuleDef This struct holds all information that is needed to create a module object. There is usually only one static variable of that type for each module, which - is statically initialized and then passed to :cfunc:`PyModule_Create` in the + is statically initialized and then passed to :c:func:`PyModule_Create` in the module initialization function. - .. cmember:: PyModuleDef_Base m_base + .. c:member:: PyModuleDef_Base m_base Always initialize this member to :const:`PyModuleDef_HEAD_INIT`. - .. cmember:: char* m_name + .. c:member:: char* m_name Name for the new module. - .. cmember:: char* m_doc + .. c:member:: char* m_doc Docstring for the module; usually a docstring variable created with - :cfunc:`PyDoc_STRVAR` is used. + :c:func:`PyDoc_STRVAR` is used. - .. cmember:: Py_ssize_t m_size + .. c:member:: Py_ssize_t m_size If the module object needs additional memory, this should be set to the number of bytes to allocate; a pointer to the block of memory can be - retrieved with :cfunc:`PyModule_GetState`. If no memory is needed, set + retrieved with :c:func:`PyModule_GetState`. If no memory is needed, set this to ``-1``. This memory should be used, rather than static globals, to hold per-module state, since it is then safe for use in multiple sub-interpreters. It is - freed when the module object is deallocated, after the :cmember:`m_free` + freed when the module object is deallocated, after the :c:member:`m_free` function has been called, if present. - .. cmember:: PyMethodDef* m_methods + .. c:member:: PyMethodDef* m_methods A pointer to a table of module-level functions, described by - :ctype:`PyMethodDef` values. Can be *NULL* if no functions are present. + :c:type:`PyMethodDef` values. Can be *NULL* if no functions are present. - .. cmember:: inquiry m_reload + .. c:member:: inquiry m_reload Currently unused, should be *NULL*. - .. cmember:: traverseproc m_traverse + .. c:member:: traverseproc m_traverse A traversal function to call during GC traversal of the module object, or *NULL* if not needed. - .. cmember:: inquiry m_clear + .. c:member:: inquiry m_clear A clear function to call during GC clearing of the module object, or *NULL* if not needed. - .. cmember:: freefunc m_free + .. c:member:: freefunc m_free A function to call during deallocation of the module object, or *NULL* if not needed. -.. cfunction:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value) +.. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value) Add an object to *module* as *name*. This is a convenience function which can be used from the module's initialization function. This steals a reference to *value*. Return ``-1`` on error, ``0`` on success. -.. cfunction:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value) +.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value) Add an integer constant to *module* as *name*. This convenience function can be used from the module's initialization function. Return ``-1`` on error, ``0`` on success. -.. cfunction:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value) +.. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value) Add a string constant to *module* as *name*. This convenience function can be used from the module's initialization function. The string *value* must be null-terminated. Return ``-1`` on error, ``0`` on success. -.. cfunction:: int PyModule_AddIntMacro(PyObject *module, macro) +.. c:function:: int PyModule_AddIntMacro(PyObject *module, macro) Add an int constant to *module*. The name and the value are taken from *macro*. For example ``PyModule_AddConstant(module, AF_INET)`` adds the int @@ -210,6 +210,6 @@ These functions are usually used in the module initialization function. Return ``-1`` on error, ``0`` on success. -.. cfunction:: int PyModule_AddStringMacro(PyObject *module, macro) +.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro) Add a string constant to *module*. |