Add docs on more module functions/constants. Add docs on getsize and …

…listdir

docsite/source/module.rst

@@ -5,6 +5,80 @@
 The ``bitmath`` Module
 ######################
 
+Functions
+*********
+
+This section describes utility functions included in the bitmath
+module.
+
+bitmath.getsize()
+=================
+.. function:: bitmath.getsize(path[, bestprefix=True[, system=NIST]])
+
+   Return a bitmath instance representing the size of a file at any
+   given path.
+
+   :param string path: The path of a file to read the size of
+   :param bool bestprefix: **Default:** ``True``, the returned
+                           instance will be in the best human-readable
+                           prefix unit. If set to ``False`` the result
+                           is a ``bitmath.Byte`` instance.
+   :param system: **Default:** ``bitmath.NIST``. The preferred system
+                  of units for the returned instance.
+   :type system: One of ``bitmath.NIST`` or ``bitmath.SI``
+
+   Internally :py:func:`bitmath.getsize` calls
+   :py:func:`os.path.realpath` before calling
+   :py:func:`os.path.getsize` on any paths.
+
+   .. versionadded:: 1.0.7
+
+bitmath.listdir()
+=================
+
+.. function:: bitmath.listdir(search_base[, followlinks=False[, filter='*'[, relpath=False[, bestprefix=False[, system=NIST]]]]])
+
+   This is a generator which recurses a directory tree yielding
+   2-tuples of:
+
+   * The absolute/relative path to a discovered file
+   * A bitmath instance representing the *apparent size* of the file.
+
+   :param string search_base: The directory to begin walking down
+   :param bool followlinks: **Default:** ``False``, do not follow
+                            links. Whether or not to follow symbolic
+                            links to directories. Setting to ``True``
+                            enables directory link following
+   :param string filter: **Default:** ``*`` (everything). A glob to
+                         filter results with. See `fnmatch
+                         <https://docs.python.org/2/library/fnmatch.html>`_
+                         for more details about *globs*
+   :param bool relpath: **Default:** ``False``, returns the fully
+                        qualified to each discovered file. ``True`` to
+                        return the relative path from the present
+                        working directory to the discovered file.
+
+			If ``relpath`` is ``False``, then
+                        :py:func:`bitmath.listdir` internally calls
+                        :py:func:`os.path.realpath` to normalize path
+                        references
+   :param bool bestprefix: **Default:** ``False``, returns
+                           ``bitmath.Byte`` instances. Set to ``True``
+                           to return the best human-readable prefix
+                           unit for representation
+   :param system: **Default:** ``bitmath.NIST``. Set a prefix
+                  preferred unit system. Requires ``bestprefix`` is
+                  ``True``
+   :type system: One of ``bitmath.NIST`` or ``bitmath.SI``
+
+
+   .. note::
+
+      * This function does NOT return tuples for directory entities.
+      * Symlinks to **files** are followed automatically
+
+   .. versionadded:: 1.0.7
+
 .. _module_context_managers:
 
 Context Managers
@@ -14,16 +88,18 @@ This section describes all of the `context managers
 <https://docs.python.org/2/reference/datamodel.html#context-managers>`_
 provided by the bitmath class.
 
-To provide a bit of background, a *context manager* (specifically, the
-``with`` statement) is a feature of the Python language which is
-commonly used to:
+.. note::
+
+   For a bit of background, a *context manager* (specifically, the
+   ``with`` statement) is a feature of the Python language which is
+   commonly used to:
 
-* Decorate, or *wrap*, an arbitrary block of code. I.e., effect a
-  certain condition onto a specific body of code
+   * Decorate, or *wrap*, an arbitrary block of code. I.e., effect a
+     certain condition onto a specific body of code
 
-* Automatically *open* and *close* an object which is used in a
-  specific context. I.e., handle set-up and tear-down of objects in
-  the place they are used.
+   * Automatically *open* and *close* an object which is used in a
+     specific context. I.e., handle set-up and tear-down of objects in
+     the place they are used.
 
 .. seealso::
 
@@ -41,9 +117,9 @@ bitmath.format()
 
 .. function:: bitmath.format([fmt_str=None[, plural=False[, bestprefix=False]]])
 
-   The ``bitmath.format`` context manager allows you to specify the
-   string representation of all bitmath instances within a specific
-   block of code.
+   The :py:func:`bitmath.format` context manager allows you to specify
+   the string representation of all bitmath instances within a
+   specific block of code.
 
    This is effectively equivalent to applying the
    :ref:`format()<instances_format>` method to an entire region of
@@ -66,7 +142,9 @@ bitmath.format()
 
    .. note:: The ``bestprefix`` parameter is not yet implemented!
 
-   Let's look at an example of toggling pluralization on and off.
+   Let's look at an example of toggling pluralization on and
+   off. First we'll look over a demonstration script (below), and then
+   we'll review the output.
 
    .. code-block:: python
       :linenos:
@@ -159,6 +237,9 @@ bitmath.format()
       Some instances: 0.333333333333 KiB, 512.0 Bit
 
 
+   .. versionadded:: 1.0.8
+
+
 .. _module_class_variables:
 
 Module Variables
@@ -168,14 +249,17 @@ This section describes the module-level variables. Some of which are
 constants and are used for reference. Some of which effect output or
 behavior.
 
+.. versionchanged:: 1.0.7 The formatting strings were not available
+   for manupulate/inspection in earlier versions
+
 .. note:: Modifying these variables will change the default
           representation indefinitely. Use the
           :py:func:`bitmath.format` context manager to limit
           changes to a specific block of code.
 
 .. _module_format_string:
 
-.. py:data:: format_string
+.. py:data:: bitmath.format_string
 
    This is the default string representation of all bitmath
    instances. The default value is ``{value} {unit}`` which, when
@@ -205,7 +289,7 @@ behavior.
       >>> print bitmath.MiB(1337), bitmath.kb(0.1234567), bitmath.Byte(0)
       [1337.00-MiB] [0.12-kb] [0.00-Byte]
 
-.. py:data:: format_plural
+.. py:data:: bitmath.format_plural
 
    A boolean which controls the pluralization of instances in string
    representation. The default is ``False``.
@@ -236,3 +320,55 @@ behavior.
 
    On line **5** we disable pluralization again and then see that the
    output has no trailing "s" character.
+
+.. py:data:: bitmath.NIST
+
+   Constant used as an argument to some functions to specify the
+   **NIST** system.
+
+.. py:data:: bitmath.SI
+
+   Constant used as an argument to some functions to specify the
+   **SI** system.
+
+.. py:data:: bitmath.SI_PREFIXES
+
+   An array of all of the SI unit prefixes (e.g., ``k``, ``M``, or
+   ``E``)
+
+.. py:data:: bitmath.SI_STEPS
+
+   .. code-block:: python
+
+      SI_STEPS = {
+          'Bit': 1 / 8.0,
+          'Byte': 1,
+          'k': 1000,
+          'M': 1000000,
+          'G': 1000000000,
+          'T': 1000000000000,
+          'P': 1000000000000000,
+          'E': 1000000000000000000
+      }
+
+
+.. py:data:: bitmath.NIST_PREFIXES
+
+   An array of all of the NIST unit prefixes (e.g., ``Ki``, ``Mi``, or
+   ``Ei``)
+
+
+.. py:data:: bitmath.NIST_STEPS
+
+   .. code-block:: python
+
+      NIST_STEPS = {
+          'Bit': 1 / 8.0,
+          'Byte': 1,
+          'Ki': 1024,
+          'Mi': 1048576,
+          'Gi': 1073741824,
+          'Ti': 1099511627776,
+          'Pi': 1125899906842624,
+          'Ei': 1152921504606846976
+      }