From: Brett Cannon <brett@python.org>
Date: Fri, 14 Jun 2013 23:19:57 +0000 (-0400)
Subject: Issue #17907: Document types.ModuleType's constructor and attributes,
X-Git-Tag: v3.4.0a1~502^2~1
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=2d7720418008582aefe3a031b78ef4e867e75d09;p=thirdparty%2FPython%2Fcpython.git

Issue #17907: Document types.ModuleType's constructor and attributes,
allowing for documenting imp.new_module() as deprecated.
---

diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst
index 890c171a15df..c6a07ca65580 100644
--- a/Doc/library/imp.rst
+++ b/Doc/library/imp.rst
@@ -112,6 +112,9 @@ This module provides an interface to the mechanisms used to implement the
    Return a new empty module object called *name*.  This object is *not* inserted
    in ``sys.modules``.
 
+   .. deprecated:: 3.4
+      Use :class:`types.ModuleType` instead.
+
 
 .. function:: reload(module)
 
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index 95132e8db453..c4f57e43af31 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -107,9 +107,35 @@ Standard names are defined for the following types:
    C".)
 
 
-.. data:: ModuleType
+.. class:: ModuleType(name, doc=None)
 
-   The type of modules.
+   The type of :term:`modules <module>`. Constructor takes the name of the
+   module to be created and optionally its :term:`docstring`.
+
+   .. attribute:: __doc__
+
+      The :term:`docstring` of the module. Defaults to ``None``.
+
+   .. attribute:: __loader__
+
+      The :term:`loader` which loaded the module. Defaults to ``None``.
+
+      .. versionchanged:: 3.4
+         Defaults to ``None``. Previously the attribute was optional.
+
+   .. attribute:: __name__
+
+      The name of the module.
+
+   .. attribute:: __package__
+
+      Which :term:`package` a module belongs to. If the module is top-level
+      (i.e. not a part of any specific package) then the attribute should be set
+      to ``''``, else it should be set to the name of the package (which can be
+      :attr:`__name__` if the module is a package itself). Defaults to ``None``.
+
+      .. versionchanged:: 3.4
+         Defaults to ``None``. Previously the attribute was optional.
 
 
 .. data:: TracebackType
diff --git a/Misc/NEWS b/Misc/NEWS
index f676dba49f15..3ebc4a8574d8 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -123,6 +123,9 @@ Core and Builtins
 Library
 -------
 
+- Issue #17907: Document imp.new_module() as deprecated in favour of
+  types.ModuleType.
+
 - Issue #18192: Introduce importlib.util.MAGIC_NUMBER and document as deprecated
   imp.get_magic().