Update documentation

csvio/csvreader.py

@@ -25,7 +25,7 @@
 import traceback
 
 from .csvbase import CSVBase
-from .processors.processor_base import ProcessorBase
+from .processors import FieldProcessor
 from .utils.types import FN, KW, RS, R
 
 
@@ -46,6 +46,12 @@ class CSVReader(CSVBase):
         *filename* argument of this Class's constructor.
     :type fieldnames: optional
 
+    :param fieldprocessor:
+        An instance of the :py:class:`~csvio.processors.field_processor.FieldProcessor`
+        object. The processor functions defined in the :py:class:`~csvio.processors.field_processor.FieldProcessor`
+        object are applied to the rows in the CSV after they read.
+    :type fieldprocessor: optional
+
     :param open_kwargs:
         A dictionary of key, value pairs that should be passed to the open
         method within this class.
@@ -56,59 +62,26 @@ class CSVReader(CSVBase):
         DictReader constructor within this class.
     :type csv_kwargs: optional
 
-    Usage:
-
-    .. doctest::
-
-        >>> from csvio import CSVReader
-        >>> reader = CSVReader("fruit_stock.csv")
-        >>> reader.fieldnames
-        ['Supplier', 'Fruit', 'Quantity']
-
-        >>> len(reader.rows)
-        4
-
-        >>> import json
-        >>> print(json.dumps(reader.rows, indent=4))
-        [
-            {
-                "Supplier": "Big Apple",
-                "Fruit": "Apple",
-                "Quantity": "1"
-            },
-            {
-                "Supplier": "Big Melons",
-                "Fruit": "Melons",
-                "Quantity": "2"
-            },
-            {
-                "Supplier": "Big Mangoes",
-                "Fruit": "Mango",
-                "Quantity": "3"
-            },
-            {
-                "Supplier": "Small Strawberries",
-                "Fruit": "Strawberry",
-                "Quantity": "4"
-            }
-        ]
-
-    CSV file contents:
-
-    .. code-block:: bash
-
-            Supplier,Fruit,Quantity
-            Big Apple,Apple,1
-            Big Melons,Melons,2
-            Long Mangoes,Mango,3
-            Small Strawberries,Strawberry,4
+    **CSVReader Usage without** ``fieldprocessor``:
+
+    .. include:: examples/csvio.csvreader.rst
+        :start-after: start-csvreader
+        :end-before: end-csvreader
+
+    .. _csvreader_fp_usage:
+
+    **CSVReader Usage with** ``fieldprocessor``
+
+    .. include:: examples/csvio.fieldprocessor.rst
+        :start-after: start-csvreader_field_processor
+        :end-before: end-csvreader_field_processor
 
     """
 
     def __init__(
         self,
         filename: str,
-        fieldprocessor: ProcessorBase = None,
+        fieldprocessor: FieldProcessor = None,
         fieldnames: FN = [],
         open_kwargs: KW = {},
         csv_kwargs: KW = {},

csvio/processors/field_processor.py

@@ -2,6 +2,11 @@
 
 
 class FieldProcessor(ProcessorBase):
+    """
+    :param handle: Reference handle for the field processor
+    :type handle: required
+    """
+
     def __init__(self, handle: str) -> None:
 
         super().__init__(handle)

csvio/processors/processor_base.py

@@ -6,6 +6,9 @@
 
 
 class ProcessorBase:
+    """
+    Processor Base Class
+    """
 
     processors: Dict[str, Dict[str, List[PF]]] = {}
 
@@ -21,6 +24,25 @@ def add_processor(
         self, fieldname: str, func_: Union[List[PF], PF], handle: str = None
     ) -> None:
 
+        """
+        Add a processor to process fields in a row.
+
+        :param fieldname: Name of the field upon which the processor should be
+            executed.
+        :type fieldname: required
+
+        :param func_: Field processor function reference or a list of such
+            function references.
+            All function references added with the same handle will be executed
+            for the field in the same order as they are added.
+        :type func_: required
+
+        :param handle: Processor reference handle to which the processor will
+            be added.
+            If not provided, the handle of the current object will be used.
+        :type handle: optional
+        """
+
         handle = handle or self.handle
 
         if not isinstance(func_, list):

docs/source/csvio.fieldprocessor.rst

@@ -0,0 +1,34 @@
+Field Processor
+================
+
+A Field Processor may be used to transform the values in a row represented by
+a dictionary that maps ``column->value`` pairs.
+
+In *csvio* a CSV file is represented by a list of dictionaries that is
+populated in the ``rows`` attribute of the :py:class:`~csvio.CSVReader` or
+:py:class:`~csvio.CSVWriter` Classes.
+
+Once instantiated, a Field Processor Object can be used by itself to process an
+arbitrary dictionary that represents a row or can be passed to the constructors
+of :py:class:`~csvio.CSVReader` or :py:class:`~csvio.CSVWriter`.
+
+In the case where a Field Processor Object is passed to the constructor of
+:py:class:`~csvio.CSVReader`, it is applied to the rows of the
+:py:class:`~csvio.CSVReader` as soon as they are read from the CSV file.
+See :ref:`example code <csvreader_fp_usage>` for further details.
+
+Similarly, in the case where a Field Processor Object is passed to the
+constructor of :py:class:`~csvio.CSVWriter`, it is applied to the rows of the
+:py:class:`~csvio.CSVWriter` as soon as they are added for writing to the
+output CSV using the :py:func:`~csvio.CSVWriter.add_rows` method.
+
+**Standalone Example Usage**
+
+.. include:: examples/csvio.fieldprocessor.rst
+        :start-after: start-standalone_field_processor
+        :end-before: end-standalone_field_processor
+
+.. autoclass:: csvio.processors.field_processor.FieldProcessor
+    :show-inheritance:
+    :members:
+    :inherited-members:

docs/source/csvio.processorbase.rst

@@ -0,0 +1,7 @@
+Processor Base
+==============
+
+.. autoclass:: csvio.processors.processor_base.ProcessorBase
+    :show-inheritance:
+    :members:
+    :inherited-members:

docs/source/csvio.rst

@@ -6,3 +6,4 @@ API Specifications
     csvio.csvbase
     csvio.csvreader
     csvio.csvwriter
+    csvio.fieldprocessor

docs/source/examples/csvio.csvreader.rst

@@ -0,0 +1,48 @@
+.. start-csvreader
+
+.. doctest::
+
+    >>> from csvio import CSVReader
+    >>> reader = CSVReader("fruit_stock.csv")
+    >>> reader.fieldnames
+    ['Supplier', 'Fruit', 'Quantity']
+
+    >>> len(reader.rows)
+    4
+
+    >>> import json
+    >>> print(json.dumps(reader.rows, indent=4))
+    [
+        {
+            "Supplier": "Big Apple",
+            "Fruit": "Apple",
+            "Quantity": "1"
+        },
+        {
+            "Supplier": "Big Melons",
+            "Fruit": "Melons",
+            "Quantity": "2"
+        },
+        {
+            "Supplier": "Big Mangoes",
+            "Fruit": "Mango",
+            "Quantity": "3"
+        },
+        {
+            "Supplier": "Small Strawberries",
+            "Fruit": "Strawberry",
+            "Quantity": "4"
+        }
+    ]
+
+*CSV file contents:*
+
+.. code-block:: bash
+
+        Supplier,Fruit,Quantity
+        Big Apple,Apple,1
+        Big Melons,Melons,2
+        Long Mangoes,Mango,3
+        Small Strawberries,Strawberry,4
+
+.. end-csvreader