cpython/Doc/c-api/module.rst

216 lines
7.1 KiB
ReStructuredText
Raw Normal View History

2008-01-20 05:30:57 -04:00
.. highlightlang:: c
.. _moduleobjects:
Module Objects
--------------
.. index:: object: module
There are only a few functions special to module objects.
.. c:var:: PyTypeObject PyModule_Type
2008-01-20 05:30:57 -04:00
.. index:: single: ModuleType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python module type. This
2008-01-20 05:30:57 -04:00
is exposed to Python programs as ``types.ModuleType``.
.. c:function:: int PyModule_Check(PyObject *p)
2008-01-20 05:30:57 -04:00
Return true if *p* is a module object, or a subtype of a module object.
.. c:function:: int PyModule_CheckExact(PyObject *p)
2008-01-20 05:30:57 -04:00
Return true if *p* is a module object, but not a subtype of
:c:data:`PyModule_Type`.
2008-01-20 05:30:57 -04:00
.. c:function:: PyObject* PyModule_New(const char *name)
2008-01-20 05:30:57 -04:00
.. index::
single: __name__ (module attribute)
single: __doc__ (module attribute)
single: __file__ (module attribute)
Return a new module object with the :attr:`__name__` attribute set to *name*.
Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in;
the caller is responsible for providing a :attr:`__file__` attribute.
.. c:function:: PyObject* PyModule_GetDict(PyObject *module)
2008-01-20 05:30:57 -04:00
.. index:: single: __dict__ (module attribute)
Return the dictionary object that implements *module*'s namespace; this object
is the same as the :attr:`__dict__` attribute of the module object. This
function never fails. It is recommended extensions use other
:c:func:`PyModule_\*` and :c:func:`PyObject_\*` functions rather than directly
2008-01-20 05:30:57 -04:00
manipulate a module's :attr:`__dict__`.
.. c:function:: char* PyModule_GetName(PyObject *module)
2008-01-20 05:30:57 -04:00
.. index::
single: __name__ (module attribute)
single: SystemError (built-in exception)
Return *module*'s :attr:`__name__` value. If the module does not provide one,
or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
.. c:function:: char* PyModule_GetFilename(PyObject *module)
2008-01-20 05:30:57 -04:00
Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
encoded to 'utf-8'.
.. deprecated:: 3.2
:c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on
unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
.. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
2008-01-20 05:30:57 -04:00
.. index::
single: __file__ (module attribute)
single: SystemError (built-in exception)
Return the name of the file from which *module* was loaded using *module*'s
:attr:`__file__` attribute. If this is not defined, or if it is not a
unicode string, raise :exc:`SystemError` and return *NULL*; otherwise return
a reference to a :c:type:`PyUnicodeObject`.
2008-01-20 05:30:57 -04:00
.. versionadded:: 3.2
2008-01-20 05:30:57 -04:00
.. c:function:: void* PyModule_GetState(PyObject *module)
Return the "state" of the module, that is, a pointer to the block of memory
allocated at module creation time, or *NULL*. See
:c:member:`PyModuleDef.m_size`.
.. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
created, or *NULL* if the module wasn't created with
:c:func:`PyModule_Create`.
Initializing C modules
^^^^^^^^^^^^^^^^^^^^^^
These functions are usually used in the module initialization function.
.. c:function:: PyObject* PyModule_Create(PyModuleDef *module)
Create a new module object, given the definition in *module*. This behaves
like :c:func:`PyModule_Create2` with *module_api_version* set to
:const:`PYTHON_API_VERSION`.
.. c:function:: PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version)
Create a new module object, given the definition in *module*, assuming the
API version *module_api_version*. If that version does not match the version
of the running interpreter, a :exc:`RuntimeWarning` is emitted.
.. note::
Most uses of this function should be using :c:func:`PyModule_Create`
instead; only use this if you are sure you need it.
.. c:type:: PyModuleDef
This struct holds all information that is needed to create a module object.
There is usually only one static variable of that type for each module, which
is statically initialized and then passed to :c:func:`PyModule_Create` in the
module initialization function.
.. c:member:: PyModuleDef_Base m_base
Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
.. c:member:: char* m_name
Name for the new module.
.. c:member:: char* m_doc
Docstring for the module; usually a docstring variable created with
:c:func:`PyDoc_STRVAR` is used.
.. c:member:: Py_ssize_t m_size
If the module object needs additional memory, this should be set to the
number of bytes to allocate; a pointer to the block of memory can be
retrieved with :c:func:`PyModule_GetState`. If no memory is needed, set
this to ``-1``.
This memory should be used, rather than static globals, to hold per-module
state, since it is then safe for use in multiple sub-interpreters. It is
freed when the module object is deallocated, after the :c:member:`m_free`
function has been called, if present.
.. c:member:: PyMethodDef* m_methods
A pointer to a table of module-level functions, described by
:c:type:`PyMethodDef` values. Can be *NULL* if no functions are present.
.. c:member:: inquiry m_reload
Currently unused, should be *NULL*.
.. c:member:: traverseproc m_traverse
A traversal function to call during GC traversal of the module object, or
*NULL* if not needed.
.. c:member:: inquiry m_clear
A clear function to call during GC clearing of the module object, or
*NULL* if not needed.
.. c:member:: freefunc m_free
A function to call during deallocation of the module object, or *NULL* if
not needed.
.. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
2008-01-20 05:30:57 -04:00
Add an object to *module* as *name*. This is a convenience function which can
be used from the module's initialization function. This steals a reference to
*value*. Return ``-1`` on error, ``0`` on success.
.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
2008-01-20 05:30:57 -04:00
Add an integer constant to *module* as *name*. This convenience function can be
used from the module's initialization function. Return ``-1`` on error, ``0`` on
success.
.. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
2008-01-20 05:30:57 -04:00
Add a string constant to *module* as *name*. This convenience function can be
used from the module's initialization function. The string *value* must be
null-terminated. Return ``-1`` on error, ``0`` on success.
Merged revisions 60176-60209 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60178 | georg.brandl | 2008-01-21 22:05:49 +0100 (Mon, 21 Jan 2008) | 2 lines #1715: include sub-extension modules in pydoc text output. ........ r60179 | georg.brandl | 2008-01-21 22:14:21 +0100 (Mon, 21 Jan 2008) | 2 lines Add a "const" to make gcc happy. ........ r60180 | georg.brandl | 2008-01-21 22:19:07 +0100 (Mon, 21 Jan 2008) | 2 lines Add the correct build dir when building with pydebug. ........ r60181 | georg.brandl | 2008-01-21 22:23:15 +0100 (Mon, 21 Jan 2008) | 3 lines Patch #1720595: add T_BOOL to the range of structmember types. Patch by Angelo Mottola, reviewed by MvL, tests by me. ........ r60182 | georg.brandl | 2008-01-21 22:28:32 +0100 (Mon, 21 Jan 2008) | 2 lines Reformat some ugly code. ........ r60187 | brett.cannon | 2008-01-22 00:50:16 +0100 (Tue, 22 Jan 2008) | 4 lines Make's MAKEFLAGS variable is set to a string containing the single-letter arguments to Make. This means there are no hyphens. Fix the '-s' check to silence distutils to now work. ........ r60188 | gregory.p.smith | 2008-01-22 01:19:41 +0100 (Tue, 22 Jan 2008) | 3 lines accepts and closes issue #1221598: adds an optional callback to ftplib.FTP storbinary() and storlines() methods. ........ r60189 | gregory.p.smith | 2008-01-22 02:12:02 +0100 (Tue, 22 Jan 2008) | 2 lines Replace spam.acquire() try: ... finally: spam.release() with "with spam:" ........ r60190 | gregory.p.smith | 2008-01-22 02:20:42 +0100 (Tue, 22 Jan 2008) | 4 lines - Fix Issue #1703448: A joined thread could show up in the threading.enumerate() list after the join() for a brief period until it actually exited. ........ r60193 | georg.brandl | 2008-01-22 08:53:31 +0100 (Tue, 22 Jan 2008) | 2 lines Fix \xhh specs, #1889. ........ r60198 | christian.heimes | 2008-01-22 16:01:25 +0100 (Tue, 22 Jan 2008) | 1 line Fixed a missing (X) in define ........ r60199 | christian.heimes | 2008-01-22 16:25:18 +0100 (Tue, 22 Jan 2008) | 2 lines Don't repeat yourself Added the macros PyModule_AddIntMacro and PyModule_AddStringMacro. They shorten PyModule_AddIntConstant(m, "AF_INET", AF_INET) to PyModule_AddIntMacro(m, AF_INET) ........ r60201 | raymond.hettinger | 2008-01-22 20:51:41 +0100 (Tue, 22 Jan 2008) | 1 line Document when to use izip_longest(). ........ r60202 | georg.brandl | 2008-01-22 20:56:03 +0100 (Tue, 22 Jan 2008) | 2 lines Fix for #1087741 patch. ........ r60203 | raymond.hettinger | 2008-01-22 21:18:53 +0100 (Tue, 22 Jan 2008) | 1 line Give zip() the same guarantee as izip() for left-to-right evaluation. ........ r60204 | raymond.hettinger | 2008-01-22 23:09:26 +0100 (Tue, 22 Jan 2008) | 1 line Improve variable name in sample code ........ r60205 | gregory.p.smith | 2008-01-23 00:15:34 +0100 (Wed, 23 Jan 2008) | 2 lines docstring and comment updates suggested by Giampaolo Rodola' ........ r60207 | raymond.hettinger | 2008-01-23 01:04:40 +0100 (Wed, 23 Jan 2008) | 1 line Let pprint() support sets and frozensets (suggested by David Mertz). ........ r60208 | guido.van.rossum | 2008-01-23 02:18:27 +0100 (Wed, 23 Jan 2008) | 4 lines I'm tired of these tests breaking at Google due to our large number of users and groups in LDAP/NIS. So I'm limiting the extra-heavy part of the tests to passwd/group files with at most 1000 entries. ........
2008-01-23 04:24:23 -04:00
.. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)
Merged revisions 60176-60209 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60178 | georg.brandl | 2008-01-21 22:05:49 +0100 (Mon, 21 Jan 2008) | 2 lines #1715: include sub-extension modules in pydoc text output. ........ r60179 | georg.brandl | 2008-01-21 22:14:21 +0100 (Mon, 21 Jan 2008) | 2 lines Add a "const" to make gcc happy. ........ r60180 | georg.brandl | 2008-01-21 22:19:07 +0100 (Mon, 21 Jan 2008) | 2 lines Add the correct build dir when building with pydebug. ........ r60181 | georg.brandl | 2008-01-21 22:23:15 +0100 (Mon, 21 Jan 2008) | 3 lines Patch #1720595: add T_BOOL to the range of structmember types. Patch by Angelo Mottola, reviewed by MvL, tests by me. ........ r60182 | georg.brandl | 2008-01-21 22:28:32 +0100 (Mon, 21 Jan 2008) | 2 lines Reformat some ugly code. ........ r60187 | brett.cannon | 2008-01-22 00:50:16 +0100 (Tue, 22 Jan 2008) | 4 lines Make's MAKEFLAGS variable is set to a string containing the single-letter arguments to Make. This means there are no hyphens. Fix the '-s' check to silence distutils to now work. ........ r60188 | gregory.p.smith | 2008-01-22 01:19:41 +0100 (Tue, 22 Jan 2008) | 3 lines accepts and closes issue #1221598: adds an optional callback to ftplib.FTP storbinary() and storlines() methods. ........ r60189 | gregory.p.smith | 2008-01-22 02:12:02 +0100 (Tue, 22 Jan 2008) | 2 lines Replace spam.acquire() try: ... finally: spam.release() with "with spam:" ........ r60190 | gregory.p.smith | 2008-01-22 02:20:42 +0100 (Tue, 22 Jan 2008) | 4 lines - Fix Issue #1703448: A joined thread could show up in the threading.enumerate() list after the join() for a brief period until it actually exited. ........ r60193 | georg.brandl | 2008-01-22 08:53:31 +0100 (Tue, 22 Jan 2008) | 2 lines Fix \xhh specs, #1889. ........ r60198 | christian.heimes | 2008-01-22 16:01:25 +0100 (Tue, 22 Jan 2008) | 1 line Fixed a missing (X) in define ........ r60199 | christian.heimes | 2008-01-22 16:25:18 +0100 (Tue, 22 Jan 2008) | 2 lines Don't repeat yourself Added the macros PyModule_AddIntMacro and PyModule_AddStringMacro. They shorten PyModule_AddIntConstant(m, "AF_INET", AF_INET) to PyModule_AddIntMacro(m, AF_INET) ........ r60201 | raymond.hettinger | 2008-01-22 20:51:41 +0100 (Tue, 22 Jan 2008) | 1 line Document when to use izip_longest(). ........ r60202 | georg.brandl | 2008-01-22 20:56:03 +0100 (Tue, 22 Jan 2008) | 2 lines Fix for #1087741 patch. ........ r60203 | raymond.hettinger | 2008-01-22 21:18:53 +0100 (Tue, 22 Jan 2008) | 1 line Give zip() the same guarantee as izip() for left-to-right evaluation. ........ r60204 | raymond.hettinger | 2008-01-22 23:09:26 +0100 (Tue, 22 Jan 2008) | 1 line Improve variable name in sample code ........ r60205 | gregory.p.smith | 2008-01-23 00:15:34 +0100 (Wed, 23 Jan 2008) | 2 lines docstring and comment updates suggested by Giampaolo Rodola' ........ r60207 | raymond.hettinger | 2008-01-23 01:04:40 +0100 (Wed, 23 Jan 2008) | 1 line Let pprint() support sets and frozensets (suggested by David Mertz). ........ r60208 | guido.van.rossum | 2008-01-23 02:18:27 +0100 (Wed, 23 Jan 2008) | 4 lines I'm tired of these tests breaking at Google due to our large number of users and groups in LDAP/NIS. So I'm limiting the extra-heavy part of the tests to passwd/group files with at most 1000 entries. ........
2008-01-23 04:24:23 -04:00
2009-01-03 17:18:54 -04:00
Add an int constant to *module*. The name and the value are taken from
*macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int
Merged revisions 60176-60209 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60178 | georg.brandl | 2008-01-21 22:05:49 +0100 (Mon, 21 Jan 2008) | 2 lines #1715: include sub-extension modules in pydoc text output. ........ r60179 | georg.brandl | 2008-01-21 22:14:21 +0100 (Mon, 21 Jan 2008) | 2 lines Add a "const" to make gcc happy. ........ r60180 | georg.brandl | 2008-01-21 22:19:07 +0100 (Mon, 21 Jan 2008) | 2 lines Add the correct build dir when building with pydebug. ........ r60181 | georg.brandl | 2008-01-21 22:23:15 +0100 (Mon, 21 Jan 2008) | 3 lines Patch #1720595: add T_BOOL to the range of structmember types. Patch by Angelo Mottola, reviewed by MvL, tests by me. ........ r60182 | georg.brandl | 2008-01-21 22:28:32 +0100 (Mon, 21 Jan 2008) | 2 lines Reformat some ugly code. ........ r60187 | brett.cannon | 2008-01-22 00:50:16 +0100 (Tue, 22 Jan 2008) | 4 lines Make's MAKEFLAGS variable is set to a string containing the single-letter arguments to Make. This means there are no hyphens. Fix the '-s' check to silence distutils to now work. ........ r60188 | gregory.p.smith | 2008-01-22 01:19:41 +0100 (Tue, 22 Jan 2008) | 3 lines accepts and closes issue #1221598: adds an optional callback to ftplib.FTP storbinary() and storlines() methods. ........ r60189 | gregory.p.smith | 2008-01-22 02:12:02 +0100 (Tue, 22 Jan 2008) | 2 lines Replace spam.acquire() try: ... finally: spam.release() with "with spam:" ........ r60190 | gregory.p.smith | 2008-01-22 02:20:42 +0100 (Tue, 22 Jan 2008) | 4 lines - Fix Issue #1703448: A joined thread could show up in the threading.enumerate() list after the join() for a brief period until it actually exited. ........ r60193 | georg.brandl | 2008-01-22 08:53:31 +0100 (Tue, 22 Jan 2008) | 2 lines Fix \xhh specs, #1889. ........ r60198 | christian.heimes | 2008-01-22 16:01:25 +0100 (Tue, 22 Jan 2008) | 1 line Fixed a missing (X) in define ........ r60199 | christian.heimes | 2008-01-22 16:25:18 +0100 (Tue, 22 Jan 2008) | 2 lines Don't repeat yourself Added the macros PyModule_AddIntMacro and PyModule_AddStringMacro. They shorten PyModule_AddIntConstant(m, "AF_INET", AF_INET) to PyModule_AddIntMacro(m, AF_INET) ........ r60201 | raymond.hettinger | 2008-01-22 20:51:41 +0100 (Tue, 22 Jan 2008) | 1 line Document when to use izip_longest(). ........ r60202 | georg.brandl | 2008-01-22 20:56:03 +0100 (Tue, 22 Jan 2008) | 2 lines Fix for #1087741 patch. ........ r60203 | raymond.hettinger | 2008-01-22 21:18:53 +0100 (Tue, 22 Jan 2008) | 1 line Give zip() the same guarantee as izip() for left-to-right evaluation. ........ r60204 | raymond.hettinger | 2008-01-22 23:09:26 +0100 (Tue, 22 Jan 2008) | 1 line Improve variable name in sample code ........ r60205 | gregory.p.smith | 2008-01-23 00:15:34 +0100 (Wed, 23 Jan 2008) | 2 lines docstring and comment updates suggested by Giampaolo Rodola' ........ r60207 | raymond.hettinger | 2008-01-23 01:04:40 +0100 (Wed, 23 Jan 2008) | 1 line Let pprint() support sets and frozensets (suggested by David Mertz). ........ r60208 | guido.van.rossum | 2008-01-23 02:18:27 +0100 (Wed, 23 Jan 2008) | 4 lines I'm tired of these tests breaking at Google due to our large number of users and groups in LDAP/NIS. So I'm limiting the extra-heavy part of the tests to passwd/group files with at most 1000 entries. ........
2008-01-23 04:24:23 -04:00
constant *AF_INET* with the value of *AF_INET* to *module*.
Return ``-1`` on error, ``0`` on success.
.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
Merged revisions 60176-60209 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60178 | georg.brandl | 2008-01-21 22:05:49 +0100 (Mon, 21 Jan 2008) | 2 lines #1715: include sub-extension modules in pydoc text output. ........ r60179 | georg.brandl | 2008-01-21 22:14:21 +0100 (Mon, 21 Jan 2008) | 2 lines Add a "const" to make gcc happy. ........ r60180 | georg.brandl | 2008-01-21 22:19:07 +0100 (Mon, 21 Jan 2008) | 2 lines Add the correct build dir when building with pydebug. ........ r60181 | georg.brandl | 2008-01-21 22:23:15 +0100 (Mon, 21 Jan 2008) | 3 lines Patch #1720595: add T_BOOL to the range of structmember types. Patch by Angelo Mottola, reviewed by MvL, tests by me. ........ r60182 | georg.brandl | 2008-01-21 22:28:32 +0100 (Mon, 21 Jan 2008) | 2 lines Reformat some ugly code. ........ r60187 | brett.cannon | 2008-01-22 00:50:16 +0100 (Tue, 22 Jan 2008) | 4 lines Make's MAKEFLAGS variable is set to a string containing the single-letter arguments to Make. This means there are no hyphens. Fix the '-s' check to silence distutils to now work. ........ r60188 | gregory.p.smith | 2008-01-22 01:19:41 +0100 (Tue, 22 Jan 2008) | 3 lines accepts and closes issue #1221598: adds an optional callback to ftplib.FTP storbinary() and storlines() methods. ........ r60189 | gregory.p.smith | 2008-01-22 02:12:02 +0100 (Tue, 22 Jan 2008) | 2 lines Replace spam.acquire() try: ... finally: spam.release() with "with spam:" ........ r60190 | gregory.p.smith | 2008-01-22 02:20:42 +0100 (Tue, 22 Jan 2008) | 4 lines - Fix Issue #1703448: A joined thread could show up in the threading.enumerate() list after the join() for a brief period until it actually exited. ........ r60193 | georg.brandl | 2008-01-22 08:53:31 +0100 (Tue, 22 Jan 2008) | 2 lines Fix \xhh specs, #1889. ........ r60198 | christian.heimes | 2008-01-22 16:01:25 +0100 (Tue, 22 Jan 2008) | 1 line Fixed a missing (X) in define ........ r60199 | christian.heimes | 2008-01-22 16:25:18 +0100 (Tue, 22 Jan 2008) | 2 lines Don't repeat yourself Added the macros PyModule_AddIntMacro and PyModule_AddStringMacro. They shorten PyModule_AddIntConstant(m, "AF_INET", AF_INET) to PyModule_AddIntMacro(m, AF_INET) ........ r60201 | raymond.hettinger | 2008-01-22 20:51:41 +0100 (Tue, 22 Jan 2008) | 1 line Document when to use izip_longest(). ........ r60202 | georg.brandl | 2008-01-22 20:56:03 +0100 (Tue, 22 Jan 2008) | 2 lines Fix for #1087741 patch. ........ r60203 | raymond.hettinger | 2008-01-22 21:18:53 +0100 (Tue, 22 Jan 2008) | 1 line Give zip() the same guarantee as izip() for left-to-right evaluation. ........ r60204 | raymond.hettinger | 2008-01-22 23:09:26 +0100 (Tue, 22 Jan 2008) | 1 line Improve variable name in sample code ........ r60205 | gregory.p.smith | 2008-01-23 00:15:34 +0100 (Wed, 23 Jan 2008) | 2 lines docstring and comment updates suggested by Giampaolo Rodola' ........ r60207 | raymond.hettinger | 2008-01-23 01:04:40 +0100 (Wed, 23 Jan 2008) | 1 line Let pprint() support sets and frozensets (suggested by David Mertz). ........ r60208 | guido.van.rossum | 2008-01-23 02:18:27 +0100 (Wed, 23 Jan 2008) | 4 lines I'm tired of these tests breaking at Google due to our large number of users and groups in LDAP/NIS. So I'm limiting the extra-heavy part of the tests to passwd/group files with at most 1000 entries. ........
2008-01-23 04:24:23 -04:00
Add a string constant to *module*.