cpython-lru_cache-weakref: Doc/c-api/module.rst annotate

annotate Doc/c-api/module.rst @ 87690:66c1c9f32567 default tip

Add use_weakref option to functools.lru_cache The use_weakref option makes lru_cache create weak references to the function arguments when creating the cache key, which prevents them from staying in the memory forever even after all other references to them are gone. This is a proof of concept for http://bugs.python.org/issue19859

author	Radomir Dopieralski <devel@sheep.art.pl>
date	Tue, 03 Dec 2013 16:02:48 +0100
parents	d43435e82e21
children

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)
83607 e39a8f8ceb9f #17115,17116: Have modules initialize the __package__ and __loader__ Brett Cannon <brett@python.org> parents: 82504 diff changeset	38 single: __package__ (module attribute)
e39a8f8ceb9f #17115,17116: Have modules initialize the __package__ and __loader__ Brett Cannon <brett@python.org> parents: 82504 diff changeset	39 single: __loader__ (module attribute)
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	40
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	41 Return a new module object with the :attr:`__name__` attribute set to name.
83607 e39a8f8ceb9f #17115,17116: Have modules initialize the __package__ and __loader__ Brett Cannon <brett@python.org> parents: 82504 diff changeset	42 The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
e39a8f8ceb9f #17115,17116: Have modules initialize the __package__ and __loader__ Brett Cannon <brett@python.org> parents: 82504 diff changeset	43 :attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
e39a8f8ceb9f #17115,17116: Have modules initialize the __package__ and __loader__ Brett Cannon <brett@python.org> parents: 82504 diff changeset	44 to ``None``); the caller is responsible for providing a :attr:`__file__`
e39a8f8ceb9f #17115,17116: Have modules initialize the __package__ and __loader__ Brett Cannon <brett@python.org> parents: 82504 diff changeset	45 attribute.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	46
68228 50b38e4b0231 Issue #3080: Add PyModule_NewObject() function Victor Stinner <victor.stinner@haypocalc.com> parents: 68111 diff changeset	47 .. versionadded:: 3.3
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function Victor Stinner <victor.stinner@haypocalc.com> parents: 68111 diff changeset	48
83607 e39a8f8ceb9f #17115,17116: Have modules initialize the __package__ and __loader__ Brett Cannon <brett@python.org> parents: 82504 diff changeset	49 .. versionchanged:: 3.4
e39a8f8ceb9f #17115,17116: Have modules initialize the __package__ and __loader__ Brett Cannon <brett@python.org> parents: 82504 diff changeset	50 :attr:`__package__` and :attr:`__loader__` are set to ``None``.
e39a8f8ceb9f #17115,17116: Have modules initialize the __package__ and __loader__ Brett Cannon <brett@python.org> parents: 82504 diff changeset	51
68228 50b38e4b0231 Issue #3080: Add PyModule_NewObject() function Victor Stinner <victor.stinner@haypocalc.com> parents: 68111 diff changeset	52
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function Victor Stinner <victor.stinner@haypocalc.com> parents: 68111 diff changeset	53 .. 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	54
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function Victor Stinner <victor.stinner@haypocalc.com> parents: 68111 diff changeset	55 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	56 string instead of a Unicode object.
50b38e4b0231 Issue #3080: Add PyModule_NewObject() function Victor Stinner <victor.stinner@haypocalc.com> parents: 68111 diff changeset	57
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	58
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	59 .. c:function:: PyObject* PyModule_GetDict(PyObject *module)
44812 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 .. index:: single: __dict__ (module attribute)
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	62
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	63 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	64 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	65 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	66 :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	67 manipulate a module's :attr:`__dict__`.
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
68111 f2edaf62d823 Issue #3080: Add PyModule_GetNameObject() Victor Stinner <victor.stinner@haypocalc.com> parents: 65137 diff changeset	70 .. c:function:: PyObject* PyModule_GetNameObject(PyObject *module)
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	71
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	72 .. index::
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	73 single: __name__ (module attribute)
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	74 single: SystemError (built-in exception)
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	75
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	76 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	77 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	78
68111 f2edaf62d823 Issue #3080: Add PyModule_GetNameObject() Victor Stinner <victor.stinner@haypocalc.com> parents: 65137 diff changeset	79 .. versionadded:: 3.3
44812 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
68111 f2edaf62d823 Issue #3080: Add PyModule_GetNameObject() Victor Stinner <victor.stinner@haypocalc.com> parents: 65137 diff changeset	82 .. 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	83
68111 f2edaf62d823 Issue #3080: Add PyModule_GetNameObject() Victor Stinner <victor.stinner@haypocalc.com> parents: 65137 diff changeset	84 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	85 ``'utf-8'``.
64138 ee765a67c0b1 Issue #9425: Create PyModule_GetFilenameObject() function Victor Stinner <victor.stinner@haypocalc.com> parents: 52318 diff changeset	86
ee765a67c0b1 Issue #9425: Create PyModule_GetFilenameObject() function Victor Stinner <victor.stinner@haypocalc.com> parents: 52318 diff changeset	87
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	88 .. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	89
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	90 .. index::
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	91 single: __file__ (module attribute)
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	92 single: SystemError (built-in exception)
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 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	95 :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	96 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	97 a reference to a Unicode object.
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	98
64140 a8d8de23cb77 Add versionadded tag to PyModule_GetFilenameObject() doc Victor Stinner <victor.stinner@haypocalc.com> parents: 64138 diff changeset	99 .. versionadded:: 3.2
44812 1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	100
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	101
68111 f2edaf62d823 Issue #3080: Add PyModule_GetNameObject() Victor Stinner <victor.stinner@haypocalc.com> parents: 65137 diff changeset	102 .. c:function:: char* PyModule_GetFilename(PyObject *module)
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 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	105 encoded to 'utf-8'.
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject() Victor Stinner <victor.stinner@haypocalc.com> parents: 65137 diff changeset	106
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject() Victor Stinner <victor.stinner@haypocalc.com> parents: 65137 diff changeset	107 .. deprecated:: 3.2
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject() Victor Stinner <victor.stinner@haypocalc.com> parents: 65137 diff changeset	108 :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	109 unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject() Victor Stinner <victor.stinner@haypocalc.com> parents: 65137 diff changeset	110
f2edaf62d823 Issue #3080: Add PyModule_GetNameObject() Victor Stinner <victor.stinner@haypocalc.com> parents: 65137 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:: void* PyModule_GetState(PyObject *module)
52318 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 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	115 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	116 :c:member:`PyModuleDef.m_size`.
52318 11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	117
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	118
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	119 .. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
52318 11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	120
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	121 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	122 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	123 :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	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:: 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	126
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule. Martin v. Löwis <martin@v.loewis.de> parents: 72785 diff changeset	127 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	128 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	129 :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	130 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	131
82504 29d5bc1226f9 #17363: fix arguments in PyState_AddModule and PyState_RemoveModule docs. Ezio Melotti <ezio.melotti@gmail.com> parents: 77564 diff changeset	132 .. c:function:: int PyState_AddModule(PyObject module, PyModuleDef def)
52318 11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	133
77564 55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule. Martin v. Löwis <martin@v.loewis.de> parents: 72785 diff changeset	134 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	135 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	136 :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	137
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule. Martin v. Löwis <martin@v.loewis.de> parents: 72785 diff changeset	138 .. versionadded:: 3.3
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule. Martin v. Löwis <martin@v.loewis.de> parents: 72785 diff changeset	139
82504 29d5bc1226f9 #17363: fix arguments in PyState_AddModule and PyState_RemoveModule docs. Ezio Melotti <ezio.melotti@gmail.com> parents: 77564 diff changeset	140 .. c:function:: int PyState_RemoveModule(PyModuleDef *def)
77564 55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule. Martin v. Löwis <martin@v.loewis.de> parents: 72785 diff changeset	141
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule. Martin v. Löwis <martin@v.loewis.de> parents: 72785 diff changeset	142 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	143
55e8cba34b11 Issue #15042: Add PyState_AddModule and PyState_RemoveModule. Martin v. Löwis <martin@v.loewis.de> parents: 72785 diff changeset	144 .. versionadded:: 3.3
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 Initializing C modules
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	147 ^^^^^^^^^^^^^^^^^^^^^^
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 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	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_Create(PyModuleDef *module)
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. This behaves
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	154 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	155 :const:`PYTHON_API_VERSION`.
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
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	158 .. 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	159
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	160 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	161 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	162 of the running interpreter, a :exc:`RuntimeWarning` is emitted.
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	163
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	164 .. note::
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	165
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	166 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	167 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	168
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:type:: PyModuleDef
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 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	173 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	174 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	175 module initialization function.
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	176
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	177 .. c:member:: PyModuleDef_Base m_base
52318 11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	178
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	179 Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	180
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	181 .. c:member:: char* m_name
52318 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 Name for the new module.
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	184
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	185 .. c:member:: char* m_doc
52318 11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	186
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	187 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	188 :c:func:`PyDoc_STRVAR` is used.
52318 11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	189
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	190 .. c:member:: Py_ssize_t m_size
52318 11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	191
85061 698fd628b001 Issue #18668: Properly document setting m_size in PyModuleDef Eli Bendersky <eliben@gmail.com> parents: 82504 diff changeset	192 Some modules allow re-initialization (calling their ``PyInit_*`` function
698fd628b001 Issue #18668: Properly document setting m_size in PyModuleDef Eli Bendersky <eliben@gmail.com> parents: 82504 diff changeset	193 more than once). These modules should keep their state in a per-module
698fd628b001 Issue #18668: Properly document setting m_size in PyModuleDef Eli Bendersky <eliben@gmail.com> parents: 82504 diff changeset	194 memory area that can be retrieved with :c:func:`PyModule_GetState`.
52318 11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	195
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	196 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	197 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	198 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	199 function has been called, if present.
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	200
85079 f55ba27776d4 Issue #18668: Further clarify m_size setting for non-negative values Eli Bendersky <eliben@gmail.com> parents: 85061 diff changeset	201 Setting ``m_size`` to ``-1`` means that the module can not be
f55ba27776d4 Issue #18668: Further clarify m_size setting for non-negative values Eli Bendersky <eliben@gmail.com> parents: 85061 diff changeset	202 re-initialized because it has global state. Setting it to a non-negative
f55ba27776d4 Issue #18668: Further clarify m_size setting for non-negative values Eli Bendersky <eliben@gmail.com> parents: 85061 diff changeset	203 value means that the module can be re-initialized and specifies the
f55ba27776d4 Issue #18668: Further clarify m_size setting for non-negative values Eli Bendersky <eliben@gmail.com> parents: 85061 diff changeset	204 additional amount of memory it requires for its state.
85061 698fd628b001 Issue #18668: Properly document setting m_size in PyModuleDef Eli Bendersky <eliben@gmail.com> parents: 82504 diff changeset	205
698fd628b001 Issue #18668: Properly document setting m_size in PyModuleDef Eli Bendersky <eliben@gmail.com> parents: 82504 diff changeset	206 See :PEP:`3121` for more details.
698fd628b001 Issue #18668: Properly document setting m_size in PyModuleDef Eli Bendersky <eliben@gmail.com> parents: 82504 diff changeset	207
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	208 .. c:member:: PyMethodDef* m_methods
52318 11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	209
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	210 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	211 :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	212
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	213 .. c:member:: inquiry m_reload
52318 11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	214
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	215 Currently unused, should be NULL.
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	216
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	217 .. c:member:: traverseproc m_traverse
52318 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 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	220 NULL if not needed.
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	221
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	222 .. c:member:: inquiry m_clear
52318 11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	223
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	224 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	225 NULL if not needed.
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	226
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	227 .. c:member:: freefunc m_free
52318 11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	228
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	229 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	230 not needed.
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	231
11d54c7e089b backport new c module docs Benjamin Peterson <benjamin@python.org> parents: 50563 diff changeset	232
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	233 .. 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	234
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	235 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	236 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	237 value. Return ``-1`` on error, ``0`` on success.
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	238
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	239
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	240 .. 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	241
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	242 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	243 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	244 success.
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	245
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	246
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	247 .. 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	248
1e8b9e7c34ce Split C API docs in Py3k branch. Georg Brandl <georg@python.org> parents: diff changeset	249 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	250 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	251 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	252
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44812 diff changeset	253
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	254 .. 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	255
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 44999 diff changeset	256 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	257 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	258 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	259 Return ``-1`` on error, ``0`` on success.
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44812 diff changeset	260
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44812 diff changeset	261
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64140 diff changeset	262 .. 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	263
fefaa0e66fdd Merged revisions 60176-60209 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44812 diff changeset	264 Add a string constant to module.

Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/module.rst @ 87690:66c1c9f32567 default tip