/Doc/c-api/module.rst

  1.. highlightlang:: c
  2
  3.. _moduleobjects:
  4
  5Module Objects
  6--------------
  7
  8.. index:: object: module
  9
 10There are only a few functions special to module objects.
 11
 12
 13.. cvar:: PyTypeObject PyModule_Type
 14
 15   .. index:: single: ModuleType (in module types)
 16
 17   This instance of :ctype:`PyTypeObject` represents the Python module type.  This
 18   is exposed to Python programs as ``types.ModuleType``.
 19
 20
 21.. cfunction:: int PyModule_Check(PyObject *p)
 22
 23   Return true if *p* is a module object, or a subtype of a module object.
 24
 25   .. versionchanged:: 2.2
 26      Allowed subtypes to be accepted.
 27
 28
 29.. cfunction:: int PyModule_CheckExact(PyObject *p)
 30
 31   Return true if *p* is a module object, but not a subtype of
 32   :cdata:`PyModule_Type`.
 33
 34   .. versionadded:: 2.2
 35
 36
 37.. cfunction:: PyObject* PyModule_New(const char *name)
 38
 39   .. index::
 40      single: __name__ (module attribute)
 41      single: __doc__ (module attribute)
 42      single: __file__ (module attribute)
 43
 44   Return a new module object with the :attr:`__name__` attribute set to *name*.
 45   Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in;
 46   the caller is responsible for providing a :attr:`__file__` attribute.
 47
 48
 49.. cfunction:: PyObject* PyModule_GetDict(PyObject *module)
 50
 51   .. index:: single: __dict__ (module attribute)
 52
 53   Return the dictionary object that implements *module*'s namespace; this object
 54   is the same as the :attr:`__dict__` attribute of the module object.  This
 55   function never fails.  It is recommended extensions use other
 56   :cfunc:`PyModule_\*` and :cfunc:`PyObject_\*` functions rather than directly
 57   manipulate a module's :attr:`__dict__`.
 58
 59
 60.. cfunction:: char* PyModule_GetName(PyObject *module)
 61
 62   .. index::
 63      single: __name__ (module attribute)
 64      single: SystemError (built-in exception)
 65
 66   Return *module*'s :attr:`__name__` value.  If the module does not provide one,
 67   or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
 68
 69
 70.. cfunction:: char* PyModule_GetFilename(PyObject *module)
 71
 72   .. index::
 73      single: __file__ (module attribute)
 74      single: SystemError (built-in exception)
 75
 76   Return the name of the file from which *module* was loaded using *module*'s
 77   :attr:`__file__` attribute.  If this is not defined, or if it is not a string,
 78   raise :exc:`SystemError` and return *NULL*.
 79
 80
 81.. cfunction:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
 82
 83   Add an object to *module* as *name*.  This is a convenience function which can
 84   be used from the module's initialization function.  This steals a reference to
 85   *value*.  Return ``-1`` on error, ``0`` on success.
 86
 87   .. versionadded:: 2.0
 88
 89
 90.. cfunction:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
 91
 92   Add an integer constant to *module* as *name*.  This convenience function can be
 93   used from the module's initialization function. Return ``-1`` on error, ``0`` on
 94   success.
 95
 96   .. versionadded:: 2.0
 97
 98
 99.. cfunction:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
100
101   Add a string constant to *module* as *name*.  This convenience function can be
102   used from the module's initialization function.  The string *value* must be
103   null-terminated.  Return ``-1`` on error, ``0`` on success.
104
105   .. versionadded:: 2.0
106
107.. cfunction:: int PyModule_AddIntMacro(PyObject *module, macro)
108
109   Add an int constant to *module*. The name and the value are taken from
110   *macro*. For example ``PyModule_AddConstant(module, AF_INET)`` adds the int
111   constant *AF_INET* with the value of *AF_INET* to *module*.
112   Return ``-1`` on error, ``0`` on success.
113
114   .. versionadded:: 2.6
115
116.. cfunction:: int PyModule_AddStringMacro(PyObject *module, macro)
117
118   Add a string constant to *module*.
119
120  .. versionadded:: 2.6
121