Clean up shutil.disk_usage.

- Move a test from call time to define time
- Add the function name to __all__
- Improve docstring and docs

A few lines are now duplicated (named tuple definition and docstring)
but I think the end result reads better.

Doc/library/shutil.rst

@@ -175,8 +175,9 @@ Directory and files operations
 
 .. function:: disk_usage(path)
 
-   Return disk usage statistics about the given path as a namedtuple including
-   total, used and free space expressed in bytes.
+   Return disk usage statistics about the given path as a :term:`named tuple`
+   with the attributes *total*, *used* and *free*, which are the amount of
+   total, used and free space, in bytes.
 
    .. versionadded:: 3.3
 

Lib/shutil.py

@@ -12,7 +12,6 @@ import fnmatch
 import collections
 import errno
 import tarfile
-from collections import namedtuple
 
 try:
     import bz2
@@ -36,6 +35,7 @@ __all__ = ["copyfileobj", "copyfile", "copymode", "copystat", "copy", "copy2",
            "register_archive_format", "unregister_archive_format",
            "get_unpack_formats", "register_unpack_format",
            "unregister_unpack_format", "unpack_archive"]
+           # disk_usage is added later, if available on the platform
 
 class Error(EnvironmentError):
     pass
@@ -756,20 +756,36 @@ def unpack_archive(filename, extract_dir=None, format=None):
         kwargs = dict(_UNPACK_FORMATS[format][2])
         func(filename, extract_dir, **kwargs)
 
-if hasattr(os, "statvfs") or os.name == 'nt':
-    _ntuple_diskusage = namedtuple('usage', 'total used free')
+
+if hasattr(os, 'statvfs'):
+
+    __all__.append('disk_usage')
+    _ntuple_diskusage = collections.namedtuple('usage', 'total used free')
 
     def disk_usage(path):
-        """Return disk usage statistics about the given path as a namedtuple
-        including total, used and free space expressed in bytes.
+        """Return disk usage statistics about the given path.
+
+        Returned valus is a named tuple with attributes 'total', 'used' and
+        'free', which are the amount of total, used and free space, in bytes.
         """
-        if hasattr(os, "statvfs"):
         st = os.statvfs(path)
-            free = (st.f_bavail * st.f_frsize)
-            total = (st.f_blocks * st.f_frsize)
+        free = st.f_bavail * st.f_frsize
+        total = st.f_blocks * st.f_frsize
         used = (st.f_blocks - st.f_bfree) * st.f_frsize
-        else:
+        return _ntuple_diskusage(total, used, free)
+
+elif os.name == 'nt':
+
     import nt
+    __all__.append('disk_usage')
+    _ntuple_diskusage = collections.namedtuple('usage', 'total used free')
+
+    def disk_usage(path):
+        """Return disk usage statistics about the given path.
+
+        Returned valus is a named tuple with attributes 'total', 'used' and
+        'free', which are the amount of total, used and free space, in bytes.
+        """
         total, free = nt._getdiskusage(path)
         used = total - free
         return _ntuple_diskusage(total, used, free)