← Back to branch summary

~ubuntu-branches/ubuntu/trusty/python3.4/trusty-proposed

« back to all changes in this revision

Viewing changes to Doc/c-api/module.rst

  • Committer: Package Import Robot
  • Author(s): Matthias Klose
  • Date: 2013-11-25 09:44:27 UTC
  • Revision ID: package-import@ubuntu.com-20131125094427-lzxj8ap5w01lmo7f
Tags: upstream-3.4~b1
Import upstream version 3.4~b1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/c-api/module.rst
 
1
.. highlightlang:: c
 
2
 
 
3
.. _moduleobjects:
 
4
 
 
5
Module Objects
 
6
--------------
 
7
 
 
8
.. index:: object: module
 
9
 
 
10
There are only a few functions special to module objects.
 
11
 
 
12
 
 
13
.. c:var:: PyTypeObject PyModule_Type
 
14
 
 
15
   .. index:: single: ModuleType (in module types)
 
16
 
 
17
   This instance of :c:type:`PyTypeObject` represents the Python module type.  This
 
18
   is exposed to Python programs as ``types.ModuleType``.
 
19
 
 
20
 
 
21
.. c:function:: int PyModule_Check(PyObject *p)
 
22
 
 
23
   Return true if *p* is a module object, or a subtype of a module object.
 
24
 
 
25
 
 
26
.. c:function:: int PyModule_CheckExact(PyObject *p)
 
27
 
 
28
   Return true if *p* is a module object, but not a subtype of
 
29
   :c:data:`PyModule_Type`.
 
30
 
 
31
 
 
32
.. c:function:: PyObject* PyModule_NewObject(PyObject *name)
 
33
 
 
34
   .. index::
 
35
      single: __name__ (module attribute)
 
36
      single: __doc__ (module attribute)
 
37
      single: __file__ (module attribute)
 
38
      single: __package__ (module attribute)
 
39
      single: __loader__ (module attribute)
 
40
 
 
41
   Return a new module object with the :attr:`__name__` attribute set to *name*.
 
42
   The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
 
43
   :attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
 
44
   to ``None``); the caller is responsible for providing a :attr:`__file__`
 
45
   attribute.
 
46
 
 
47
   .. versionadded:: 3.3
 
48
 
 
49
   .. versionchanged:: 3.4
 
50
      :attr:`__package__` and :attr:`__loader__` are set to ``None``.
 
51
 
 
52
 
 
53
.. c:function:: PyObject* PyModule_New(const char *name)
 
54
 
 
55
   Similar to :c:func:`PyImport_NewObject`, but the name is an UTF-8 encoded
 
56
   string instead of a Unicode object.
 
57
 
 
58
 
 
59
.. c:function:: PyObject* PyModule_GetDict(PyObject *module)
 
60
 
 
61
   .. index:: single: __dict__ (module attribute)
 
62
 
 
63
   Return the dictionary object that implements *module*'s namespace; this object
 
64
   is the same as the :attr:`__dict__` attribute of the module object.  This
 
65
   function never fails.  It is recommended extensions use other
 
66
   :c:func:`PyModule_\*` and :c:func:`PyObject_\*` functions rather than directly
 
67
   manipulate a module's :attr:`__dict__`.
 
68
 
 
69
 
 
70
.. c:function:: PyObject* PyModule_GetNameObject(PyObject *module)
 
71
 
 
72
   .. index::
 
73
      single: __name__ (module attribute)
 
74
      single: SystemError (built-in exception)
 
75
 
 
76
   Return *module*'s :attr:`__name__` value.  If the module does not provide one,
 
77
   or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
 
78
 
 
79
   .. versionadded:: 3.3
 
80
 
 
81
 
 
82
.. c:function:: char* PyModule_GetName(PyObject *module)
 
83
 
 
84
   Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
 
85
   ``'utf-8'``.
 
86
 
 
87
 
 
88
.. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
 
89
 
 
90
   .. index::
 
91
      single: __file__ (module attribute)
 
92
      single: SystemError (built-in exception)
 
93
 
 
94
   Return the name of the file from which *module* was loaded using *module*'s
 
95
   :attr:`__file__` attribute.  If this is not defined, or if it is not a
 
96
   unicode string, raise :exc:`SystemError` and return *NULL*; otherwise return
 
97
   a reference to a Unicode object.
 
98
 
 
99
   .. versionadded:: 3.2
 
100
 
 
101
 
 
102
.. c:function:: char* PyModule_GetFilename(PyObject *module)
 
103
 
 
104
   Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
 
105
   encoded to 'utf-8'.
 
106
 
 
107
   .. deprecated:: 3.2
 
108
      :c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on
 
109
      unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
 
110
 
 
111
 
 
112
.. c:function:: void* PyModule_GetState(PyObject *module)
 
113
 
 
114
   Return the "state" of the module, that is, a pointer to the block of memory
 
115
   allocated at module creation time, or *NULL*.  See
 
116
   :c:member:`PyModuleDef.m_size`.
 
117
 
 
118
 
 
119
.. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
 
120
 
 
121
   Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
 
122
   created, or *NULL* if the module wasn't created with
 
123
   :c:func:`PyModule_Create`.i
 
124
 
 
125
.. c:function:: PyObject* PyState_FindModule(PyModuleDef *def)
 
126
 
 
127
   Returns the module object that was created from *def* for the current interpreter.
 
128
   This method requires that the module object has been attached to the interpreter state with
 
129
   :c:func:`PyState_AddModule` beforehand. In case the corresponding module object is not
 
130
   found or has not been attached to the interpreter state yet, it returns NULL.
 
131
 
 
132
.. c:function:: int PyState_AddModule(PyObject *module, PyModuleDef *def)
 
133
 
 
134
   Attaches the module object passed to the function to the interpreter state. This allows
 
135
   the module object to be accessible via
 
136
   :c:func:`PyState_FindModule`.
 
137
 
 
138
   .. versionadded:: 3.3
 
139
 
 
140
.. c:function:: int PyState_RemoveModule(PyModuleDef *def)
 
141
 
 
142
   Removes the module object created from *def* from the interpreter state.
 
143
 
 
144
   .. versionadded:: 3.3
 
145
 
 
146
Initializing C modules
 
147
^^^^^^^^^^^^^^^^^^^^^^
 
148
 
 
149
These functions are usually used in the module initialization function.
 
150
 
 
151
.. c:function:: PyObject* PyModule_Create(PyModuleDef *module)
 
152
 
 
153
   Create a new module object, given the definition in *module*.  This behaves
 
154
   like :c:func:`PyModule_Create2` with *module_api_version* set to
 
155
   :const:`PYTHON_API_VERSION`.
 
156
 
 
157
 
 
158
.. c:function:: PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version)
 
159
 
 
160
   Create a new module object, given the definition in *module*, assuming the
 
161
   API version *module_api_version*.  If that version does not match the version
 
162
   of the running interpreter, a :exc:`RuntimeWarning` is emitted.
 
163
 
 
164
   .. note::
 
165
 
 
166
      Most uses of this function should be using :c:func:`PyModule_Create`
 
167
      instead; only use this if you are sure you need it.
 
168
 
 
169
 
 
170
.. c:type:: PyModuleDef
 
171
 
 
172
   This struct holds all information that is needed to create a module object.
 
173
   There is usually only one static variable of that type for each module, which
 
174
   is statically initialized and then passed to :c:func:`PyModule_Create` in the
 
175
   module initialization function.
 
176
 
 
177
   .. c:member:: PyModuleDef_Base m_base
 
178
 
 
179
      Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
 
180
 
 
181
   .. c:member:: char* m_name
 
182
 
 
183
      Name for the new module.
 
184
 
 
185
   .. c:member:: char* m_doc
 
186
 
 
187
      Docstring for the module; usually a docstring variable created with
 
188
      :c:func:`PyDoc_STRVAR` is used.
 
189
 
 
190
   .. c:member:: Py_ssize_t m_size
 
191
 
 
192
      Some modules allow re-initialization (calling their ``PyInit_*`` function
 
193
      more than once). These modules should keep their state in a per-module
 
194
      memory area that can be retrieved with :c:func:`PyModule_GetState`.
 
195
 
 
196
      This memory should be used, rather than static globals, to hold per-module
 
197
      state, since it is then safe for use in multiple sub-interpreters.  It is
 
198
      freed when the module object is deallocated, after the :c:member:`m_free`
 
199
      function has been called, if present.
 
200
 
 
201
      Setting ``m_size`` to ``-1`` means that the module can not be
 
202
      re-initialized because it has global state. Setting it to a non-negative
 
203
      value means that the module can be re-initialized and specifies the
 
204
      additional amount of memory it requires for its state.
 
205
 
 
206
      See :PEP:`3121` for more details.
 
207
 
 
208
   .. c:member:: PyMethodDef* m_methods
 
209
 
 
210
      A pointer to a table of module-level functions, described by
 
211
      :c:type:`PyMethodDef` values.  Can be *NULL* if no functions are present.
 
212
 
 
213
   .. c:member:: inquiry m_reload
 
214
 
 
215
      Currently unused, should be *NULL*.
 
216
 
 
217
   .. c:member:: traverseproc m_traverse
 
218
 
 
219
      A traversal function to call during GC traversal of the module object, or
 
220
      *NULL* if not needed.
 
221
 
 
222
   .. c:member:: inquiry m_clear
 
223
 
 
224
      A clear function to call during GC clearing of the module object, or
 
225
      *NULL* if not needed.
 
226
 
 
227
   .. c:member:: freefunc m_free
 
228
 
 
229
      A function to call during deallocation of the module object, or *NULL* if
 
230
      not needed.
 
231
 
 
232
 
 
233
.. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
 
234
 
 
235
   Add an object to *module* as *name*.  This is a convenience function which can
 
236
   be used from the module's initialization function.  This steals a reference to
 
237
   *value*.  Return ``-1`` on error, ``0`` on success.
 
238
 
 
239
 
 
240
.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
 
241
 
 
242
   Add an integer constant to *module* as *name*.  This convenience function can be
 
243
   used from the module's initialization function. Return ``-1`` on error, ``0`` on
 
244
   success.
 
245
 
 
246
 
 
247
.. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
 
248
 
 
249
   Add a string constant to *module* as *name*.  This convenience function can be
 
250
   used from the module's initialization function.  The string *value* must be
 
251
   null-terminated.  Return ``-1`` on error, ``0`` on success.
 
252
 
 
253
 
 
254
.. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)
 
255
 
 
256
   Add an int constant to *module*. The name and the value are taken from
 
257
   *macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int
 
258
   constant *AF_INET* with the value of *AF_INET* to *module*.
 
259
   Return ``-1`` on error, ``0`` on success.
 
260
 
 
261
 
 
262
.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
 
263
 
 
264
   Add a string constant to *module*.