Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/module.rst @ 78069:a8aa77458e12 3.2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add c_size_t and c_ssize_t to the ctypes summary table.
author Antoine Pitrou <solipsis@pitrou.net>
date Thu, 12 Jul 2012 20:31:50 +0200
parents 6e9aedf6ef24
children 7247d9f2fce9
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
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
32 .. c:function:: PyObject* PyModule_New(const char *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
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
44 .. c:function:: PyObject* PyModule_GetDict(PyObject *module)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 .. index:: single: __dict__ (module attribute)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
47
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 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
49 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
50 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
51 :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
52 manipulate a module's :attr:`__dict__`.
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
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
55 .. c:function:: char* PyModule_GetName(PyObject *module)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 .. index::
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 single: __name__ (module attribute)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 single: SystemError (built-in exception)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 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
62 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
63
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
64
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
65 .. c:function:: char* PyModule_GetFilename(PyObject *module)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
66
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
67 Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
64138
ee765a67c0b1 Issue #9425: Create PyModule_GetFilenameObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 52318
diff changeset
68 encoded to 'utf-8'.
ee765a67c0b1 Issue #9425: Create PyModule_GetFilenameObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 52318
diff changeset
69
ee765a67c0b1 Issue #9425: Create PyModule_GetFilenameObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 52318
diff changeset
70 .. deprecated:: 3.2
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
71 :c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
72 unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
64138
ee765a67c0b1 Issue #9425: Create PyModule_GetFilenameObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 52318
diff changeset
73
ee765a67c0b1 Issue #9425: Create PyModule_GetFilenameObject() function
Victor Stinner <victor.stinner@haypocalc.com>
parents: 52318
diff changeset
74
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
75 .. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
76
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 .. index::
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 single: __file__ (module attribute)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 single: SystemError (built-in exception)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
80
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 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
82 :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
83 unicode string, raise :exc:`SystemError` and return *NULL*; otherwise return
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
84 a reference to a :c:type:`PyUnicodeObject`.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
64140
a8d8de23cb77 Add versionadded tag to PyModule_GetFilenameObject() doc
Victor Stinner <victor.stinner@haypocalc.com>
parents: 64138
diff changeset
86 .. versionadded:: 3.2
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
88
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
89 .. c:function:: void* PyModule_GetState(PyObject *module)
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
90
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
91 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
92 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
93 :c:member:`PyModuleDef.m_size`.
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
94
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
95
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
96 .. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
97
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
98 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
99 created, or *NULL* if the module wasn't created with
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
100 :c:func:`PyModule_Create`.
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
101
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
102
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
103 Initializing C modules
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
104 ^^^^^^^^^^^^^^^^^^^^^^
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
105
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
106 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
107
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
108 .. c:function:: PyObject* PyModule_Create(PyModuleDef *module)
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
109
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
110 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
111 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
112 :const:`PYTHON_API_VERSION`.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
113
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
114
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
115 .. 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
116
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
117 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
118 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
119 of the running interpreter, a :exc:`RuntimeWarning` is emitted.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
120
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
121 .. note::
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
122
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
123 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
124 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
125
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
126
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
127 .. c:type:: PyModuleDef
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
128
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
129 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
130 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
131 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
132 module initialization function.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
133
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
134 .. c:member:: PyModuleDef_Base m_base
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
135
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
136 Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
137
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
138 .. c:member:: char* m_name
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
139
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
140 Name for the new module.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
141
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
142 .. c:member:: char* m_doc
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
143
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
144 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
145 :c:func:`PyDoc_STRVAR` is used.
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
146
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
147 .. c:member:: Py_ssize_t m_size
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
148
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
149 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
150 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
151 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
152 this to ``-1``.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
153
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
154 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
155 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
156 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
157 function has been called, if present.
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 .. c:member:: PyMethodDef* m_methods
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
160
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
161 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
162 :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
163
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
164 .. c:member:: inquiry m_reload
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
165
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
166 Currently unused, should be *NULL*.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
167
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
168 .. c:member:: traverseproc m_traverse
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
169
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
170 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
171 *NULL* if not needed.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
172
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
173 .. c:member:: inquiry m_clear
52318
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
174
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
175 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
176 *NULL* if not needed.
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:: freefunc m_free
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 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
181 not needed.
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
182
11d54c7e089b backport new c module docs
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
183
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
184 .. 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
185
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 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
187 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
188 *value*. Return ``-1`` on error, ``0`` on success.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
189
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
190
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
191 .. 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
192
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 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
194 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
195 success.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
196
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
197
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
198 .. 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
199
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 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
201 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
202 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
203
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
204
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
205 .. 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
206
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 44999
diff changeset
207 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
208 *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
209 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
210 Return ``-1`` on error, ``0`` on success.
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
211
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
212
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64140
diff changeset
213 .. 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
214
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44812
diff changeset
215 Add a string constant to *module*.