Lines Matching +full:is +full:- +full:module
5 Module Objects
6 --------------
8 .. index:: pair: object; module
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``.
21 Return true if *p* is a module object, or a subtype of a module object.
27 Return true if *p* is a module object, but not a subtype of
34 single: __name__ (module attribute)
35 single: __doc__ (module attribute)
36 single: __file__ (module attribute)
37 single: __package__ (module attribute)
38 single: __loader__ (module attribute)
40 Return a new module object with the :attr:`__name__` attribute set to *name*.
41 The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
43 to ``None``); the caller is responsible for providing a :attr:`__file__`
54 Similar to :c:func:`PyModule_NewObject`, but the name is a UTF-8 encoded
58 .. c:function:: PyObject* PyModule_GetDict(PyObject *module)
60 .. index:: single: __dict__ (module attribute)
62 Return the dictionary object that implements *module*'s namespace; this object
63 is the same as the :attr:`~object.__dict__` attribute of the module object.
64 If *module* is not a module object (or a subtype of a module object),
65 :exc:`SystemError` is raised and ``NULL`` is returned.
67 It is recommended extensions use other ``PyModule_*`` and
68 ``PyObject_*`` functions rather than directly manipulate a module's
72 .. c:function:: PyObject* PyModule_GetNameObject(PyObject *module)
75 single: __name__ (module attribute)
76 single: SystemError (built-in exception)
78 Return *module*'s :attr:`__name__` value. If the module does not provide one,
79 or if it is not a string, :exc:`SystemError` is raised and ``NULL`` is returned.
84 .. c:function:: const char* PyModule_GetName(PyObject *module)
87 ``'utf-8'``.
89 .. c:function:: void* PyModule_GetState(PyObject *module)
91 Return the "state" of the module, that is, a pointer to the block of memory
92 allocated at module creation time, or ``NULL``. See
96 .. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
98 Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
99 created, or ``NULL`` if the module wasn't created from a definition.
102 .. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
105 single: __file__ (module attribute)
106 single: SystemError (built-in exception)
108 Return the name of the file from which *module* was loaded using *module*'s
109 :attr:`__file__` attribute. If this is not defined, or if it is not a
116 .. c:function:: const char* PyModule_GetFilename(PyObject *module)
119 encoded to 'utf-8'.
126 .. _initializing-modules:
132 which export an initialization function), or compiled-in modules
133 (where the initialization function is added using :c:func:`PyImport_AppendInittab`).
134 See :ref:`building` or :ref:`extending-with-embedding` for details.
136 The initialization function can either pass a module definition instance
137 to :c:func:`PyModule_Create`, and return the resulting module object,
138 or request "multi-phase initialization" by returning the definition struct itself.
142 The module definition struct, which holds all information needed to create
143 a module object. There is usually only one statically initialized variable
144 of this type for each module.
152 Name for the new module.
156 Docstring for the module; usually a docstring variable created with
157 :c:macro:`PyDoc_STRVAR` is used.
161 Module state may be kept in a per-module memory area that can be
163 This makes modules safe for use in multiple sub-interpreters.
165 This memory area is allocated based on *m_size* on module creation,
166 and freed when the module object is deallocated, after the
169 Setting ``m_size`` to ``-1`` means that the module does not support
170 sub-interpreters, because it has global state.
172 Setting it to a non-negative value means that the module can be
173 re-initialized and specifies the additional amount of memory it requires
174 for its state. Non-negative ``m_size`` is required for multi-phase
181 A pointer to a table of module-level functions, described by
186 An array of slot definitions for multi-phase initialization, terminated by
188 When using single-phase initialization, *m_slots* must be ``NULL``.
199 A traversal function to call during GC traversal of the module object, or
202 This function is not called if the module state was requested but is not
203 allocated yet. This is the case immediately after the module is created
204 and before the module is executed (:c:data:`Py_mod_exec` function). More
205 precisely, this function is not called if :c:member:`m_size` is greater
206 than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
207 is ``NULL``.
210 No longer called before the module state is allocated.
214 A clear function to call during GC clearing of the module object, or
217 This function is not called if the module state was requested but is not
218 allocated yet. This is the case immediately after the module is created
219 and before the module is executed (:c:data:`Py_mod_exec` function). More
220 precisely, this function is not called if :c:member:`m_size` is greater
221 than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
222 is ``NULL``.
224 Like :c:member:`PyTypeObject.tp_clear`, this function is not *always*
225 called before a module is deallocated. For example, when reference
226 counting is enough to determine that an object is no longer used,
227 the cyclic garbage collector is not involved and
228 :c:member:`~PyModuleDef.m_free` is called directly.
231 No longer called before the module state is allocated.
235 A function to call during deallocation of the module object, or ``NULL``
238 This function is not called if the module state was requested but is not
239 allocated yet. This is the case immediately after the module is created
240 and before the module is executed (:c:data:`Py_mod_exec` function). More
241 precisely, this function is not called if :c:member:`m_size` is greater
242 than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
243 is ``NULL``.
246 No longer called before the module state is allocated.
248 Single-phase initialization
251 The module initialization function may create and return the module object
252 directly. This is referred to as "single-phase initialization", and uses one
253 of the following two module creation functions:
257 Create a new module object, given the definition in *def*. This behaves
264 Create a new module object, given the definition in *def*, assuming the
266 of the running interpreter, a :exc:`RuntimeWarning` is emitted.
273 Before it is returned from in the initialization function, the resulting module
274 object is typically populated using functions like :c:func:`PyModule_AddObjectRef`.
276 .. _multi-phase-initialization:
278 Multi-phase initialization
281 An alternate way to specify extensions is to request "multi-phase initialization".
283 initialization is split between the *creation phase*, when the module object
284 is created, and the *execution phase*, when it is populated.
285 The distinction is similar to the :py:meth:`__new__` and :py:meth:`__init__` methods
288 Unlike modules created using single-phase initialization, these modules are not
289 singletons: if the *sys.modules* entry is removed and the module is re-imported,
290 a new module object is created, and the old module is subject to normal garbage
291 collection -- as with Python modules.
294 This means that all state should be specific to the module object (using e.g.
295 using :c:func:`PyModule_GetState`), or its contents (such as the module's
298 All modules created using multi-phase initialization are expected to support
299 :ref:`sub-interpreters <sub-interpreter-support>`. Making sure multiple modules
300 are independent is typically enough to achieve this.
302 To request multi-phase initialization, the initialization function
303 (PyInit_modulename) returns a :c:type:`PyModuleDef` instance with non-empty
304 :c:member:`~PyModuleDef.m_slots`. Before it is returned, the ``PyModuleDef``
309 Ensures a module definition is a properly initialized Python object that
316 The *m_slots* member of the module definition must point to an array of
337 Specifies a function that is called to create the module object itself.
343 instance, as defined in :PEP:`451`, and the module definition.
344 It should return a new module object, or set an error
348 call arbitrary Python code, as trying to import the same module again may
351 Multiple ``Py_mod_create`` slots may not be specified in one module
354 If ``Py_mod_create`` is not specified, the import machinery will create
355 a normal module object using :c:func:`PyModule_New`. The name is taken from
357 to their place in the module hierarchy and be imported under different
358 names through symlinks, all while sharing a single module definition.
360 There is no requirement for the returned object to be an instance of
362 setting and getting import-related attributes.
364 ``PyModuleDef`` has non-``NULL`` ``m_traverse``, ``m_clear``,
365 ``m_free``; non-zero ``m_size``; or slots other than ``Py_mod_create``.
369 Specifies a function that is called to *execute* the module.
370 This is equivalent to executing the code of a Python module: typically,
371 this function adds classes and constants to the module.
372 The signature of the function is:
374 .. c:function:: int exec_module(PyObject* module)
379 See :PEP:`489` for more details on multi-phase initialization.
381 Low-level module creation functions
384 The following functions are called under the hood when using multi-phase
385 initialization. They can be used directly, for example when creating module
387 ``PyModule_ExecDef`` must be called to fully initialize a module.
391 Create a new module object, given the definition in *def* and the
399 Create a new module object, given the definition in *def* and the
402 a :exc:`RuntimeWarning` is emitted.
411 .. c:function:: int PyModule_ExecDef(PyObject *module, PyModuleDef *def)
417 .. c:function:: int PyModule_SetDocString(PyObject *module, const char *docstring)
419 Set the docstring for *module* to *docstring*.
420 This function is called automatically when creating a module from
426 .. c:function:: int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
428 Add the functions from the ``NULL`` terminated *functions* array to *module*.
430 entries (due to the lack of a shared module namespace, module level
431 "functions" implemented in C typically receive the module as their first
433 This function is called automatically when creating a module from
442 The module initialization function (if using single phase initialization) or
443 a function called from a module execution slot (if using multi-phase
444 initialization), can use the following functions to help initialize the module
447 .. c:function:: int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)
449 Add an object to *module* as *name*. This is a convenience function which
450 can be used from the module's initialization function.
452 On success, return ``0``. On error, raise an exception and return ``-1``.
454 Return ``NULL`` if *value* is ``NULL``. It must be called with an exception
460 add_spam(PyObject *module, int value)
464 return -1;
466 int res = PyModule_AddObjectRef(module, "spam", obj);
471 The example can also be written without checking explicitly if *obj* is
475 add_spam(PyObject *module, int value)
478 int res = PyModule_AddObjectRef(module, "spam", obj);
489 .. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
494 The new :c:func:`PyModule_AddObjectRef` function is recommended, since it is
509 add_spam(PyObject *module, int value)
513 return -1;
515 if (PyModule_AddObject(module, "spam", obj) < 0) {
517 return -1;
520 // Py_DECREF(obj) is not needed here
524 The example can also be written without checking explicitly if *obj* is
528 add_spam(PyObject *module, int value)
531 if (PyModule_AddObject(module, "spam", obj) < 0) {
533 return -1;
536 // Py_DECREF(obj) is not needed here
544 .. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
546 Add an integer constant to *module* as *name*. This convenience function can be
547 used from the module's initialization function. Return ``-1`` on error, ``0`` on
551 .. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *valu…
553 Add a string constant to *module* as *name*. This convenience function can be
554 used from the module's initialization function. The string *value* must be
555 ``NULL``-terminated. Return ``-1`` on error, ``0`` on success.
558 .. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)
560 Add an int constant to *module*. The name and the value are taken from
561 *macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int
562 constant *AF_INET* with the value of *AF_INET* to *module*.
563 Return ``-1`` on error, ``0`` on success.
566 .. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
568 Add a string constant to *module*.
570 .. c:function:: int PyModule_AddType(PyObject *module, PyTypeObject *type)
572 Add a type object to *module*.
573 The type object is finalized by calling internally :c:func:`PyType_Ready`.
574 The name of the type object is taken from the last component of
576 Return ``-1`` on error, ``0`` on success.
581 Module lookup
584 Single-phase initialization creates singleton modules that can be looked up
585 in the context of the current interpreter. This allows the module object to be
586 retrieved later with only a reference to the module definition.
588 These functions will not work on modules created using multi-phase initialization,
593 Returns the module object that was created from *def* for the current interpreter.
594 This method requires that the module object has been attached to the interpreter state with
595 :c:func:`PyState_AddModule` beforehand. In case the corresponding module object is not
598 .. c:function:: int PyState_AddModule(PyObject *module, PyModuleDef *def)
600 Attaches the module object passed to the function to the interpreter state. This allows
601 the module object to be accessible via :c:func:`PyState_FindModule`.
603 Only effective on modules created using single-phase initialization.
605 Python calls ``PyState_AddModule`` automatically after importing a module,
606 so it is unnecessary (but harmless) to call it from module initialization
607 code. An explicit call is needed only if the module's own init code
609 The function is mainly intended for implementing alternative import
615 Return 0 on success or -1 on failure.
621 Removes the module object created from *def* from the interpreter state.
622 Return 0 on success or -1 on failure.