Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/module.rst @ 79691:05c8928362ee

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge __next__ method link fixes with 3.3.
author Ezio Melotti <ezio.melotti@gmail.com>
date Fri, 12 Oct 2012 13:46:37 +0300
parents 55e8cba34b11
children 29d5bc1226f9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _moduleobjects:
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Module Objects
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 --------------
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. index:: object: module
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 There are only a few functions special to module objects.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
13 .. c:var:: PyTypeObject PyModule_Type
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
14
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 .. index:: single: ModuleType (in module types)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
17 This instance of :c:type:`PyTypeObject` represents the Python module type. This
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 is exposed to Python programs as ``types.ModuleType``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
20
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
21 .. c:function:: int PyModule_Check(PyObject *p)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 Return true if *p* is a module object, or a subtype of a module object.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
26 .. c:function:: int PyModule_CheckExact(PyObject *p)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 Return true if *p* is a module object, but not a subtype of
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
29 :c:data:`PyModule_Type`.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
31
68228
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 68111
diff changeset
32 .. c:function:: PyObject* PyModule_NewObject(PyObject *name)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
33
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 .. index::
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 single: __name__ (module attribute)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 single: __doc__ (module attribute)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 single: __file__ (module attribute)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 Return a new module object with the :attr:`__name__` attribute set to *name*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in;
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 the caller is responsible for providing a :attr:`__file__` attribute.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
68228
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 68111
diff changeset
43 .. versionadded:: 3.3
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 68111
diff changeset
44
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 68111
diff changeset
45
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 68111
diff changeset
46 .. c:function:: PyObject* PyModule_New(const char *name)
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 68111
diff changeset
47
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 68111
diff changeset
48 Similar to :c:func:`PyImport_NewObject`, but the name is an UTF-8 encoded
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 68111
diff changeset
49 string instead of a Unicode object.
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 68111
diff changeset
50
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
52 .. c:function:: PyObject* PyModule_GetDict(PyObject *module)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
53
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
54 .. index:: single: __dict__ (module attribute)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
55
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 Return the dictionary object that implements *module*'s namespace; this object
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 is the same as the :attr:`__dict__` attribute of the module object. This
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 function never fails. It is recommended extensions use other
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
59 :c:func:`PyModule_\*` and :c:func:`PyObject_\*` functions rather than directly
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 manipulate a module's :attr:`__dict__`.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
62
68111
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
63 .. c:function:: PyObject* PyModule_GetNameObject(PyObject *module)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
64
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 .. index::
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 single: __name__ (module attribute)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 single: SystemError (built-in exception)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 Return *module*'s :attr:`__name__` value. If the module does not provide one,
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
68111
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
72 .. versionadded:: 3.3
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
74
68111
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
75 .. c:function:: char* PyModule_GetName(PyObject *module)
64138
ee765a67c0b1 Issue #9425: Create PyModule_GetFilenameObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 52318
diff changeset
76
68111
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
77 Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
78 ``'utf-8'``.
64138
ee765a67c0b1 Issue #9425: Create PyModule_GetFilenameObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 52318
diff changeset
79
ee765a67c0b1 Issue #9425: Create PyModule_GetFilenameObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 52318
diff changeset
80
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
81 .. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 .. index::
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 single: __file__ (module attribute)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 single: SystemError (built-in exception)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 Return the name of the file from which *module* was loaded using *module*'s
64138
ee765a67c0b1 Issue #9425: Create PyModule_GetFilenameObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 52318
diff changeset
88 :attr:`__file__` attribute. If this is not defined, or if it is not a
ee765a67c0b1 Issue #9425: Create PyModule_GetFilenameObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 52318
diff changeset
89 unicode string, raise :exc:`SystemError` and return *NULL*; otherwise return
72785
fe65c75c9f9d Update C API docs for PEP 393.
Georg Brandl <georg@python.org>
parents: 69716
diff changeset
90 a reference to a Unicode object.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
91
64140
a8d8de23cb77 Add versionadded tag to PyModule_GetFilenameObject() doc
Victor Stinner <victor.stinner@haypocalc.com>
parents: 64138
diff changeset
92 .. versionadded:: 3.2
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
94
68111
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
95 .. c:function:: char* PyModule_GetFilename(PyObject *module)
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
96
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
97 Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
98 encoded to 'utf-8'.
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
99
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
100 .. deprecated:: 3.2
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
101 :c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
102 unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
103
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 65137
diff changeset
104
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
105 .. c:function:: void* PyModule_GetState(PyObject *module)
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
106
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
107 Return the "state" of the module, that is, a pointer to the block of memory
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
108 allocated at module creation time, or *NULL*. See
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
109 :c:member:`PyModuleDef.m_size`.
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
110
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
111
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
112 .. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
113
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
114 Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
115 created, or *NULL* if the module wasn't created with
77564
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
116 :c:func:`PyModule_Create`.i
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
117
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
118 .. c:function:: PyObject* PyState_FindModule(PyModuleDef *def)
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
119
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
120 Returns the module object that was created from *def* for the current interpreter.
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
121 This method requires that the module object has been attached to the interpreter state with
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
122 :c:func:`PyState_AddModule` beforehand. In case the corresponding module object is not
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
123 found or has not been attached to the interpreter state yet, it returns NULL.
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
124
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
125 .. c:function:: int PyState_AddModule(PyModuleDef *def, PyObject *module)
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
126
77564
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
127 Attaches the module object passed to the function to the interpreter state. This allows
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
128 the module object to be accessible via
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
129 :c:func:`PyState_FindModule`.
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
130
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
131 .. versionadded:: 3.3
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
132
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
133 .. c:function:: int PyState_RemoveModule(PyModuleDef *def, PyObject *module)
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
134
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
135 Removes the module object created from *def* from the interpreter state.
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
136
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
Martin v. Löwis <martin@v.loewis.de>
parents: 72785
diff changeset
137 .. versionadded:: 3.3
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
138
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
139 Initializing C modules
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
140 ^^^^^^^^^^^^^^^^^^^^^^
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
141
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
142 These functions are usually used in the module initialization function.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
143
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
144 .. c:function:: PyObject* PyModule_Create(PyModuleDef *module)
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
145
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
146 Create a new module object, given the definition in *module*. This behaves
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
147 like :c:func:`PyModule_Create2` with *module_api_version* set to
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
148 :const:`PYTHON_API_VERSION`.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
149
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
150
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
151 .. c:function:: PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version)
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
152
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
153 Create a new module object, given the definition in *module*, assuming the
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
154 API version *module_api_version*. If that version does not match the version
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
155 of the running interpreter, a :exc:`RuntimeWarning` is emitted.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
156
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
157 .. note::
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
158
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
159 Most uses of this function should be using :c:func:`PyModule_Create`
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
160 instead; only use this if you are sure you need it.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
161
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
162
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
163 .. c:type:: PyModuleDef
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
164
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
165 This struct holds all information that is needed to create a module object.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
166 There is usually only one static variable of that type for each module, which
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
167 is statically initialized and then passed to :c:func:`PyModule_Create` in the
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
168 module initialization function.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
169
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
170 .. c:member:: PyModuleDef_Base m_base
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
171
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
172 Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
173
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
174 .. c:member:: char* m_name
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
175
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
176 Name for the new module.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
177
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
178 .. c:member:: char* m_doc
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
179
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
180 Docstring for the module; usually a docstring variable created with
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
181 :c:func:`PyDoc_STRVAR` is used.
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
182
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
183 .. c:member:: Py_ssize_t m_size
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
184
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
185 If the module object needs additional memory, this should be set to the
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
186 number of bytes to allocate; a pointer to the block of memory can be
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
187 retrieved with :c:func:`PyModule_GetState`. If no memory is needed, set
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
188 this to ``-1``.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
189
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
190 This memory should be used, rather than static globals, to hold per-module
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
191 state, since it is then safe for use in multiple sub-interpreters. It is
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
192 freed when the module object is deallocated, after the :c:member:`m_free`
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
193 function has been called, if present.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
194
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
195 .. c:member:: PyMethodDef* m_methods
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
196
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
197 A pointer to a table of module-level functions, described by
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
198 :c:type:`PyMethodDef` values. Can be *NULL* if no functions are present.
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
199
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
200 .. c:member:: inquiry m_reload
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
201
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
202 Currently unused, should be *NULL*.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
203
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
204 .. c:member:: traverseproc m_traverse
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
205
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
206 A traversal function to call during GC traversal of the module object, or
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
207 *NULL* if not needed.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
208
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
209 .. c:member:: inquiry m_clear
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
210
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
211 A clear function to call during GC clearing of the module object, or
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
212 *NULL* if not needed.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
213
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
214 .. c:member:: freefunc m_free
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
215
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
216 A function to call during deallocation of the module object, or *NULL* if
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
217 not needed.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
218
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
219
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
220 .. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
221
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 Add an object to *module* as *name*. This is a convenience function which can
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
223 be used from the module's initialization function. This steals a reference to
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
224 *value*. Return ``-1`` on error, ``0`` on success.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
225
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
226
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
227 .. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
228
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
229 Add an integer constant to *module* as *name*. This convenience function can be
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 used from the module's initialization function. Return ``-1`` on error, ``0`` on
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 success.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
232
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
233
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
234 .. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
235
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
236 Add a string constant to *module* as *name*. This convenience function can be
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
237 used from the module's initialization function. The string *value* must be
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
238 null-terminated. Return ``-1`` on error, ``0`` on success.
44885
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
239
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
240
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
241 .. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)
44885
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
242
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 44999
diff changeset
243 Add an int constant to *module*. The name and the value are taken from
69713
b3e7ffe6d727 fix function name in example (closes #11966)
Benjamin Peterson <benjamin@python.org>
parents: 52318
diff changeset
244 *macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int
44885
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
245 constant *AF_INET* with the value of *AF_INET* to *module*.
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
246 Return ``-1`` on error, ``0`` on success.
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
247
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
248
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
249 .. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
44885
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
250
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
251 Add a string constant to *module*.