From f0b4476e41187f7c348b7754bf2860def70e25fb Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Wed, 13 Aug 2014 20:01:07 -0400 Subject: [PATCH] Add docs on more module functions/constants. Add docs on getsize and listdir --- docsite/source/module.rst | 164 ++++++++++++++++++++++++++++++++++---- 1 file changed, 150 insertions(+), 14 deletions(-) diff --git a/docsite/source/module.rst b/docsite/source/module.rst index 35976a5..066c2bb 100644 --- a/docsite/source/module.rst +++ b/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 + `_ + 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 `_ 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()` 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,6 +249,9 @@ 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 @@ -175,7 +259,7 @@ behavior. .. _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 + }