Docs/comments: further additions/fixes/improvements...

docs/index.rst

@@ -1,8 +1,8 @@
 *unittest_expander* -- test parametrization library
 ===================================================
 
-Welcome to the documentation for *unittest_expander* -- a library that
-provides flexible and easy-to-use tools **to parametrize Python unit
+Welcome to the documentation for *unittest_expander* -- a Python library
+that provides flexible and easy-to-use tools **to parametrize unit
 tests**, especially (but not limited to) those based on
 :class:`unittest.TestCase`.
 

docs/reference.rst

@@ -204,7 +204,50 @@ The :obj:`current` special object
 
 .. data:: current
 
-   A special singleton object XXX...........
+   A special singleton object which, when used during execution of a
+   parametrized test method, provides (in a `thread-local`_ manner)
+   access to the following properties of the currently executed test:
+
+   .. attribute:: current.label
+
+      :type: :class:`str`
+      :value: the :ref:`test's label <test-labels>`
+
+   .. attribute:: current.context_targets
+
+      :type: :class:`list`
+      :value: the :ref:`test's context manager as-targets <test-context-targets>`
+
+   .. attribute:: current.args
+
+      :type: :class:`tuple`
+      :value: all positional arguments obtained by the currently
+              executed parametrized test method
+
+   .. attribute:: current.kwargs
+
+      :type: :class:`dict`
+      :value: all keyword arguments obtained by the currently
+              executed parametrized test method
+
+   .. attribute:: current.count
+
+      :type: :class:`int`
+      :value: the consecutive number (within a single application of
+              :func:`@expand`) of the generated parametrized test method
+
+   .. attribute:: current.base_name
+
+      :type: :class:`str`
+      :value: the name of the original (non-parametrized) test method
+
+   .. attribute:: current.base_obj
+
+      :type: :class:`function <types.FunctionType>`
+      :value: the original (non-parametrized) test method itself
+
+.. _thread-local: https://docs.python.org/library/threading.html#thread-local-data
+
 
 Non-essential constants and classes
 -----------------------------------
@@ -221,8 +264,8 @@ Non-essential constants and classes
    applied <about-substitute>` by the machinery of :func:`expand` to
    each test method previously decorated with :func:`foreach`.
 
-   The sole constructor argument (*actual_object*) is the object (test
-   method) to be proxied.
+   The sole constructor argument (*actual_object*) is the object
+   (typically, a test method) to be proxied.
 
    Apart from exposing in a transparent way nearly all attributes
    of the proxied object, the public interface of a :class:`Substitute`

unittest_expander.py

@@ -178,6 +178,8 @@
 ...Ran 5 tests...
 OK
 
+.. _test-labels:
+
 Generated *labels* of our tests (attached to the names of the generated
 test methods) became less cryptic.  But what to do if we need to label
 our parameters explicitly?
@@ -646,6 +648,8 @@
 ...Ran 4 tests...
 OK
 
+.. _`test-context-targets`
+
 As you can see in the above example, a *sequence* of context manager
 *as-targets* (i.e., objects returned by context managers'
 :meth:`__enter__`) is available within the test method definition as
@@ -2860,7 +2864,7 @@
     ...             None,
     ...          ),
     ...         'xyz__<4>__4': (   # (because 'xyz__<4>', 'xyz__<4>__2' abd 'xyz__<4>__3'
-    ...             Function,      #  already in PseudoClass.__mro__ namespaces)
+    ...             Function,      #  are already in PseudoClass.__mro__ namespaces)
     ...             'WeirdPseudoMetaclass.__init__.<locals>.xyz__<4>__4',
     ...          ),
     ...         'qwerty': (
@@ -2896,7 +2900,7 @@
     ...         'xyz__<3>': Function,
     ...         'xyz__<4>': int,
     ...         'xyz__<4>__4': Function,  # (because 'xyz__<4>', 'xyz__<4>__2' abd 'xyz__<4>__3'
-    ...         'qwerty': Substitute,     #  already in PseudoClass.__mro__ namespaces)
+    ...         'qwerty': Substitute,     #  are already in PseudoClass.__mro__ namespaces)
     ...         'qwerty__<5>__2': Function, # (because hasattr(PseudoClass, 'qwerty__<5>') is true)
     ...         'qwerty__<6>__2': Function,   # (because 'qwerty__<6>' already in dir(PseudoClass))
     ...         'disregarded': types.MethodType,