8
.. index:: object: module
11
.. c:var:: PyTypeObject PyModule_Type
13
.. index:: single: ModuleType (in module types)
15
This instance of :c:type:`PyTypeObject` represents the Python module type. This
16
is exposed to Python programs as ``types.ModuleType``.
19
.. c:function:: int PyModule_Check(PyObject *p)
21
Return true if *p* is a module object, or a subtype of a module object.
24
.. c:function:: int PyModule_CheckExact(PyObject *p)
26
Return true if *p* is a module object, but not a subtype of
27
:c:data:`PyModule_Type`.
30
.. c:function:: PyObject* PyModule_NewObject(PyObject *name)
33
single: __name__ (module attribute)
34
single: __doc__ (module attribute)
35
single: __file__ (module attribute)
36
single: __package__ (module attribute)
37
single: __loader__ (module attribute)
39
Return a new module object with the :attr:`__name__` attribute set to *name*.
40
The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
41
:attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
42
to ``None``); the caller is responsible for providing a :attr:`__file__`
47
.. versionchanged:: 3.4
48
:attr:`__package__` and :attr:`__loader__` are set to ``None``.
51
.. c:function:: PyObject* PyModule_New(const char *name)
53
Similar to :c:func:`PyImport_NewObject`, but the name is a UTF-8 encoded
54
string instead of a Unicode object.
57
.. c:function:: PyObject* PyModule_GetDict(PyObject *module)
59
.. index:: single: __dict__ (module attribute)
61
Return the dictionary object that implements *module*'s namespace; this object
62
is the same as the :attr:`~object.__dict__` attribute of the module object.
63
If *module* is not a module object (or a subtype of a module object),
64
:exc:`SystemError` is raised and *NULL* is returned.
66
It is recommended extensions use other :c:func:`PyModule_\*` and
67
:c:func:`PyObject_\*` functions rather than directly manipulate a module's
68
:attr:`~object.__dict__`.
71
.. c:function:: PyObject* PyModule_GetNameObject(PyObject *module)
74
single: __name__ (module attribute)
75
single: SystemError (built-in exception)
77
Return *module*'s :attr:`__name__` value. If the module does not provide one,
78
or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
83
.. c:function:: char* PyModule_GetName(PyObject *module)
85
Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
88
.. c:function:: void* PyModule_GetState(PyObject *module)
90
Return the "state" of the module, that is, a pointer to the block of memory
91
allocated at module creation time, or *NULL*. See
92
:c:member:`PyModuleDef.m_size`.
95
.. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
97
Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
98
created, or *NULL* if the module wasn't created from a definition.
101
.. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
104
single: __file__ (module attribute)
105
single: SystemError (built-in exception)
107
Return the name of the file from which *module* was loaded using *module*'s
108
:attr:`__file__` attribute. If this is not defined, or if it is not a
109
unicode string, raise :exc:`SystemError` and return *NULL*; otherwise return
110
a reference to a Unicode object.
112
.. versionadded:: 3.2
115
.. c:function:: char* PyModule_GetFilename(PyObject *module)
117
Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
121
:c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on
122
unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
125
.. _initializing-modules:
127
Initializing C modules
128
^^^^^^^^^^^^^^^^^^^^^^
130
Modules objects are usually created from extension modules (shared libraries
131
which export an initialization function), or compiled-in modules
132
(where the initialization function is added using :c:func:`PyImport_AppendInittab`).
133
See :ref:`building` or :ref:`extending-with-embedding` for details.
135
The initialization function can either pass a module definition instance
136
to :c:func:`PyModule_Create`, and return the resulting module object,
137
or request "multi-phase initialization" by returning the definition struct itself.
139
.. c:type:: PyModuleDef
141
The module definition struct, which holds all information needed to create
142
a module object. There is usually only one statically initialized variable
143
of this type for each module.
145
.. c:member:: PyModuleDef_Base m_base
147
Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
149
.. c:member:: char* m_name
151
Name for the new module.
153
.. c:member:: char* m_doc
155
Docstring for the module; usually a docstring variable created with
156
:c:func:`PyDoc_STRVAR` is used.
158
.. c:member:: Py_ssize_t m_size
160
Module state may be kept in a per-module memory area that can be
161
retrieved with :c:func:`PyModule_GetState`, rather than in static globals.
162
This makes modules safe for use in multiple sub-interpreters.
164
This memory area is allocated based on *m_size* on module creation,
165
and freed when the module object is deallocated, after the
166
:c:member:`m_free` function has been called, if present.
168
Setting ``m_size`` to ``-1`` means that the module does not support
169
sub-interpreters, because it has global state.
171
Setting it to a non-negative value means that the module can be
172
re-initialized and specifies the additional amount of memory it requires
173
for its state. Non-negative ``m_size`` is required for multi-phase
176
See :PEP:`3121` for more details.
178
.. c:member:: PyMethodDef* m_methods
180
A pointer to a table of module-level functions, described by
181
:c:type:`PyMethodDef` values. Can be *NULL* if no functions are present.
183
.. c:member:: PyModuleDef_Slot* m_slots
185
An array of slot definitions for multi-phase initialization, terminated by
186
a ``{0, NULL}`` entry.
187
When using single-phase initialization, *m_slots* must be *NULL*.
189
.. versionchanged:: 3.5
191
Prior to version 3.5, this member was always set to *NULL*,
194
.. c:member:: inquiry m_reload
196
.. c:member:: traverseproc m_traverse
198
A traversal function to call during GC traversal of the module object, or
199
*NULL* if not needed.
201
.. c:member:: inquiry m_clear
203
A clear function to call during GC clearing of the module object, or
204
*NULL* if not needed.
206
.. c:member:: freefunc m_free
208
A function to call during deallocation of the module object, or *NULL* if
211
Single-phase initialization
212
...........................
214
The module initialization function may create and return the module object
215
directly. This is referred to as "single-phase initialization", and uses one
216
of the following two module creation functions:
218
.. c:function:: PyObject* PyModule_Create(PyModuleDef *def)
220
Create a new module object, given the definition in *def*. This behaves
221
like :c:func:`PyModule_Create2` with *module_api_version* set to
222
:const:`PYTHON_API_VERSION`.
225
.. c:function:: PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)
227
Create a new module object, given the definition in *def*, assuming the
228
API version *module_api_version*. If that version does not match the version
229
of the running interpreter, a :exc:`RuntimeWarning` is emitted.
233
Most uses of this function should be using :c:func:`PyModule_Create`
234
instead; only use this if you are sure you need it.
236
Before it is returned from in the initialization function, the resulting module
237
object is typically populated using functions like :c:func:`PyModule_AddObject`.
239
.. _multi-phase-initialization:
241
Multi-phase initialization
242
..........................
244
An alternate way to specify extensions is to request "multi-phase initialization".
245
Extension modules created this way behave more like Python modules: the
246
initialization is split between the *creation phase*, when the module object
247
is created, and the *execution phase*, when it is populated.
248
The distinction is similar to the :py:meth:`__new__` and :py:meth:`__init__` methods
251
Unlike modules created using single-phase initialization, these modules are not
252
singletons: if the *sys.modules* entry is removed and the module is re-imported,
253
a new module object is created, and the old module is subject to normal garbage
254
collection -- as with Python modules.
255
By default, multiple modules created from the same definition should be
256
independent: changes to one should not affect the others.
257
This means that all state should be specific to the module object (using e.g.
258
using :c:func:`PyModule_GetState`), or its contents (such as the module's
259
:attr:`__dict__` or individual classes created with :c:func:`PyType_FromSpec`).
261
All modules created using multi-phase initialization are expected to support
262
:ref:`sub-interpreters <sub-interpreter-support>`. Making sure multiple modules
263
are independent is typically enough to achieve this.
265
To request multi-phase initialization, the initialization function
266
(PyInit_modulename) returns a :c:type:`PyModuleDef` instance with non-empty
267
:c:member:`~PyModuleDef.m_slots`. Before it is returned, the ``PyModuleDef``
268
instance must be initialized with the following function:
270
.. c:function:: PyObject* PyModuleDef_Init(PyModuleDef *def)
272
Ensures a module definition is a properly initialized Python object that
273
correctly reports its type and reference count.
275
Returns *def* cast to ``PyObject*``, or *NULL* if an error occurred.
277
.. versionadded:: 3.5
279
The *m_slots* member of the module definition must point to an array of
280
``PyModuleDef_Slot`` structures:
282
.. c:type:: PyModuleDef_Slot
284
.. c:member:: int slot
286
A slot ID, chosen from the available values explained below.
288
.. c:member:: void* value
290
Value of the slot, whose meaning depends on the slot ID.
292
.. versionadded:: 3.5
294
The *m_slots* array must be terminated by a slot with id 0.
296
The available slot types are:
298
.. c:var:: Py_mod_create
300
Specifies a function that is called to create the module object itself.
301
The *value* pointer of this slot must point to a function of the signature:
303
.. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
305
The function receives a :py:class:`~importlib.machinery.ModuleSpec`
306
instance, as defined in :PEP:`451`, and the module definition.
307
It should return a new module object, or set an error
310
This function should be kept minimal. In particular, it should not
311
call arbitrary Python code, as trying to import the same module again may
312
result in an infinite loop.
314
Multiple ``Py_mod_create`` slots may not be specified in one module
317
If ``Py_mod_create`` is not specified, the import machinery will create
318
a normal module object using :c:func:`PyModule_New`. The name is taken from
319
*spec*, not the definition, to allow extension modules to dynamically adjust
320
to their place in the module hierarchy and be imported under different
321
names through symlinks, all while sharing a single module definition.
323
There is no requirement for the returned object to be an instance of
324
:c:type:`PyModule_Type`. Any type can be used, as long as it supports
325
setting and getting import-related attributes.
326
However, only ``PyModule_Type`` instances may be returned if the
327
``PyModuleDef`` has non-*NULL* ``m_traverse``, ``m_clear``,
328
``m_free``; non-zero ``m_size``; or slots other than ``Py_mod_create``.
330
.. c:var:: Py_mod_exec
332
Specifies a function that is called to *execute* the module.
333
This is equivalent to executing the code of a Python module: typically,
334
this function adds classes and constants to the module.
335
The signature of the function is:
337
.. c:function:: int exec_module(PyObject* module)
339
If multiple ``Py_mod_exec`` slots are specified, they are processed in the
340
order they appear in the *m_slots* array.
342
See :PEP:`489` for more details on multi-phase initialization.
344
Low-level module creation functions
345
...................................
347
The following functions are called under the hood when using multi-phase
348
initialization. They can be used directly, for example when creating module
349
objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
350
``PyModule_ExecDef`` must be called to fully initialize a module.
352
.. c:function:: PyObject * PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
354
Create a new module object, given the definition in *module* and the
355
ModuleSpec *spec*. This behaves like :c:func:`PyModule_FromDefAndSpec2`
356
with *module_api_version* set to :const:`PYTHON_API_VERSION`.
358
.. versionadded:: 3.5
360
.. c:function:: PyObject * PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
362
Create a new module object, given the definition in *module* and the
363
ModuleSpec *spec*, assuming the API version *module_api_version*.
364
If that version does not match the version of the running interpreter,
365
a :exc:`RuntimeWarning` is emitted.
369
Most uses of this function should be using :c:func:`PyModule_FromDefAndSpec`
370
instead; only use this if you are sure you need it.
372
.. versionadded:: 3.5
374
.. c:function:: int PyModule_ExecDef(PyObject *module, PyModuleDef *def)
376
Process any execution slots (:c:data:`Py_mod_exec`) given in *def*.
378
.. versionadded:: 3.5
380
.. c:function:: int PyModule_SetDocString(PyObject *module, const char *docstring)
382
Set the docstring for *module* to *docstring*.
383
This function is called automatically when creating a module from
384
``PyModuleDef``, using either ``PyModule_Create`` or
385
``PyModule_FromDefAndSpec``.
387
.. versionadded:: 3.5
389
.. c:function:: int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
391
Add the functions from the *NULL* terminated *functions* array to *module*.
392
Refer to the :c:type:`PyMethodDef` documentation for details on individual
393
entries (due to the lack of a shared module namespace, module level
394
"functions" implemented in C typically receive the module as their first
395
parameter, making them similar to instance methods on Python classes).
396
This function is called automatically when creating a module from
397
``PyModuleDef``, using either ``PyModule_Create`` or
398
``PyModule_FromDefAndSpec``.
400
.. versionadded:: 3.5
405
The module initialization function (if using single phase initialization) or
406
a function called from a module execution slot (if using multi-phase
407
initialization), can use the following functions to help initialize the module
410
.. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
412
Add an object to *module* as *name*. This is a convenience function which can
413
be used from the module's initialization function. This steals a reference to
414
*value*. Return ``-1`` on error, ``0`` on success.
416
.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
418
Add an integer constant to *module* as *name*. This convenience function can be
419
used from the module's initialization function. Return ``-1`` on error, ``0`` on
423
.. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
425
Add a string constant to *module* as *name*. This convenience function can be
426
used from the module's initialization function. The string *value* must be
427
*NULL*-terminated. Return ``-1`` on error, ``0`` on success.
430
.. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)
432
Add an int constant to *module*. The name and the value are taken from
433
*macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int
434
constant *AF_INET* with the value of *AF_INET* to *module*.
435
Return ``-1`` on error, ``0`` on success.
438
.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
440
Add a string constant to *module*.
446
Single-phase initialization creates singleton modules that can be looked up
447
in the context of the current interpreter. This allows the module object to be
448
retrieved later with only a reference to the module definition.
450
These functions will not work on modules created using multi-phase initialization,
451
since multiple such modules can be created from a single definition.
453
.. c:function:: PyObject* PyState_FindModule(PyModuleDef *def)
455
Returns the module object that was created from *def* for the current interpreter.
456
This method requires that the module object has been attached to the interpreter state with
457
:c:func:`PyState_AddModule` beforehand. In case the corresponding module object is not
458
found or has not been attached to the interpreter state yet, it returns *NULL*.
460
.. c:function:: int PyState_AddModule(PyObject *module, PyModuleDef *def)
462
Attaches the module object passed to the function to the interpreter state. This allows
463
the module object to be accessible via :c:func:`PyState_FindModule`.
465
Only effective on modules created using single-phase initialization.
467
.. versionadded:: 3.3
469
.. c:function:: int PyState_RemoveModule(PyModuleDef *def)
471
Removes the module object created from *def* from the interpreter state.
473
.. versionadded:: 3.3
added
removed
python-3.5.2-docs-html/_sources/c-api/module.txt
