
Module Objects
**************

There are only a few functions special to module objects.

PyTypeObject PyModule_Type

   This instance of ``PyTypeObject`` represents the Python module
   type.  This is exposed to Python programs as ``types.ModuleType``.

int PyModule_Check(PyObject *p)

   Return true if *p* is a module object, or a subtype of a module
   object.

int PyModule_CheckExact(PyObject *p)

   Return true if *p* is a module object, but not a subtype of
   ``PyModule_Type``.

PyObject* PyModule_NewObject(PyObject *name)

   Return a new module object with the ``__name__`` attribute set to
   *name*. Only the module's ``__doc__`` and ``__name__`` attributes
   are filled in; the caller is responsible for providing a
   ``__file__`` attribute.

   New in version 3.3.

PyObject* PyModule_New(const char *name)
    Return value: New reference.

   Similar to ``PyImport_NewObject()``, but the name is an UTF-8
   encoded string instead of a Unicode object.

PyObject* PyModule_GetDict(PyObject *module)
    Return value: Borrowed reference.

   Return the dictionary object that implements *module*'s namespace;
   this object is the same as the ``__dict__`` attribute of the module
   object.  This function never fails.  It is recommended extensions
   use other ``PyModule_*()`` and ``PyObject_*()`` functions rather
   than directly manipulate a module's ``__dict__``.

PyObject* PyModule_GetNameObject(PyObject *module)

   Return *module*'s ``__name__`` value.  If the module does not
   provide one, or if it is not a string, ``SystemError`` is raised
   and *NULL* is returned.

   New in version 3.3.

char* PyModule_GetName(PyObject *module)

   Similar to ``PyModule_GetNameObject()`` but return the name encoded
   to ``'utf-8'``.

PyObject* PyModule_GetFilenameObject(PyObject *module)

   Return the name of the file from which *module* was loaded using
   *module*'s ``__file__`` attribute.  If this is not defined, or if
   it is not a unicode string, raise ``SystemError`` and return
   *NULL*; otherwise return a reference to a Unicode object.

   New in version 3.2.

char* PyModule_GetFilename(PyObject *module)

   Similar to ``PyModule_GetFilenameObject()`` but return the filename
   encoded to 'utf-8'.

   Deprecated since version 3.2: ``PyModule_GetFilename()`` raises
   ``UnicodeEncodeError`` on unencodable filenames, use
   ``PyModule_GetFilenameObject()`` instead.

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
   ``PyModuleDef.m_size``.

PyModuleDef* PyModule_GetDef(PyObject *module)

   Return a pointer to the ``PyModuleDef`` struct from which the
   module was created, or *NULL* if the module wasn't created with
   ``PyModule_Create()``.i

PyObject* PyState_FindModule(PyModuleDef *def)

   Returns the module object that was created from *def* for the
   current interpreter. This method requires that the module object
   has been attached to the interpreter state with
   ``PyState_AddModule()`` beforehand. In case the corresponding
   module object is not found or has not been attached to the
   interpreter state yet, it returns NULL.

int PyState_AddModule(PyModuleDef *def, PyObject *module)

   Attaches the module object passed to the function to the
   interpreter state. This allows the module object to be accessible
   via ``PyState_FindModule()``.

   New in version 3.3.

int PyState_RemoveModule(PyModuleDef *def, PyObject *module)

   Removes the module object created from *def* from the interpreter
   state.

   New in version 3.3.


Initializing C modules
======================

These functions are usually used in the module initialization
function.

PyObject* PyModule_Create(PyModuleDef *module)

   Create a new module object, given the definition in *module*.  This
   behaves like ``PyModule_Create2()`` with *module_api_version* set
   to ``PYTHON_API_VERSION``.

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
   ``RuntimeWarning`` is emitted.

   Note: Most uses of this function should be using ``PyModule_Create()``
     instead; only use this if you are sure you need it.

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
   ``PyModule_Create()`` in the module initialization function.

   PyModuleDef_Base m_base

      Always initialize this member to ``PyModuleDef_HEAD_INIT``.

   char* m_name

      Name for the new module.

   char* m_doc

      Docstring for the module; usually a docstring variable created
      with ``PyDoc_STRVAR()`` is used.

   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 ``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 ``m_free`` function has been called, if
      present.

   PyMethodDef* m_methods

      A pointer to a table of module-level functions, described by
      ``PyMethodDef`` values.  Can be *NULL* if no functions are
      present.

   inquiry m_reload

      Currently unused, should be *NULL*.

   traverseproc m_traverse

      A traversal function to call during GC traversal of the module
      object, or *NULL* if not needed.

   inquiry m_clear

      A clear function to call during GC clearing of the module
      object, or *NULL* if not needed.

   freefunc m_free

      A function to call during deallocation of the module object, or
      *NULL* if not needed.

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)

   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.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

   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.

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)

   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.

int PyModule_AddIntMacro(PyObject *module, macro)

   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 constant *AF_INET* with the value of *AF_INET* to
   *module*. Return ``-1`` on error, ``0`` on success.

int PyModule_AddStringMacro(PyObject *module, macro)

   Add a string constant to *module*.
