Merge pull request #5 from tekktrik/doc/update-documentation

Update documentation

Author: tekktrik

circuitpython_csv.py

@@ -31,18 +31,27 @@
 import re
 
 try:
-    from typing import List, Optional, Any, Dict, Iterable, Sequence
+    from typing import List, Optional, Any, Dict, Iterable, Sequence, Tuple
+    from abc import ABC, abstractmethod
     import io
+
+    class SupportsStringCasting(ABC):  # pylint: disable=missing-class-docstring
+        @abstractmethod
+        def __str__(self) -> str:  # pylint: disable=invalid-str-returned
+            pass
+
+
 except ImportError:
     pass
 
 
 class reader:  # pylint: disable=invalid-name
-    """Basic CSV reader class
+    """Basic CSV reader class that behaves like CPython's ``csv.reader()``
 
     :param csvfile: The open file to read from
-    :param delimiter: The CSV delimiter, default is comma (,)
-    :param quotechar: The CSV quote character for encapsulating special characters
+    :type csvfile: io.TextIOWrapper
+    :param str delimiter: (Optional) The CSV delimiter, default is comma (,)
+    :param str quotechar: (Optional) The CSV quote character for encapsulating special characters
         including the delimiter, default is double quotation mark (")
     """
 
@@ -97,11 +106,12 @@ def __next__(self) -> List[str]:
 
 
 class writer:  # pylint: disable=invalid-name
-    """Basic CSV writer class
+    """Basic CSV writer class that behaves like CPython's ``csv.writer()``
 
     :param csvfile: The open CSVfile to write to
-    :param delimiter: The CSV delimiter, default is comma (,)
-    :param quotechar: The CSV quote character for encapsulating special characters
+    :type csvfile: io.TextIOWrapper
+    :param str delimiter: (Optional) The CSV delimiter, default is comma (,)
+    :param str quotechar: (Optional) The CSV quote character for encapsulating special characters
         including the delimiter, default is double quotation mark (")
     """
 
@@ -114,10 +124,12 @@ def __init__(
         self.quotechar = quoterchar
         self.newlinechar = "\r\n"
 
-    def writerow(self, seq: List[str]) -> None:
+    def writerow(self, seq: Sequence[SupportsStringCasting]) -> None:
         """Write a row to the CSV file
 
-        :param seq: The list of values to write
+        :param seq: The list of values to write, which must all be str or be able to
+            be cast to str
+        :type seq: Sequence[SupportsStringCasting]
         """
 
         str_seq = [str(entry) for entry in seq]
@@ -128,18 +140,19 @@ def writerow(self, seq: List[str]) -> None:
         parsed_str = (self.delimiter).join(quoted_seq)
         self.file_iterator.write(parsed_str + self.newlinechar)
 
-    def writerows(self, rows: iter) -> None:
+    def writerows(self, rows: Iterable[Sequence[SupportsStringCasting]]) -> None:
         """Write multiple rows to the CSV file
 
         :param rows: An iterable item that yields multiple rows to write (e.g., list)
+        :type rows: Iterable[Sequence[str]]
         """
         for row in rows:
             self.writerow(row)
 
     def _apply_quotes(self, entry: str) -> str:
         """Apply the quote character to entries as necessary
 
-        :param entry: The entry to add the quote charcter to, if needed
+        :param str entry: The entry to add the quote charcter to, if needed
         """
 
         return (
@@ -155,18 +168,21 @@ class DictReader:
     it also accepts the delimiter and quotechar keywords
 
     :param f: The open file to read from
-    :param fieldnames: The fieldnames for each of the columns, if none is given,
+    :type f: io.TextIOWrapper
+    :param fieldnames: (Optional) The fieldnames for each of the columns, if none is given,
         it will default to the whatever is in the first row of the CSV file
-    :param restkey: A key name for values that have no key (row is larger than
+    :type fieldnames: Sequence[str]
+    :param str restkey: (Optional) A key name for values that have no key (row is larger than
         the length of fieldnames), default is None
-    :param restval: A default value for keys that have no values (row is small
+    :param restval: (Optional) A default value for keys that have no values (row is small
         than the length of fieldnames, default is None
+    :type restval: Any
     """
 
     def __init__(
         self,
         f: io.TextIOWrapper,
-        fieldnames: Optional[List] = None,
+        fieldnames: Optional[Sequence[str]] = None,
         restkey: Optional[str] = None,
         restval: Optional[Any] = None,
         **kwargs
@@ -205,17 +221,20 @@ class DictWriter:
     delimiter and quotechar keywords
 
     :param f: The open file to write to
+    :type f: io.TextIOWrapper
     :param fieldnames: The fieldnames for each of the comlumns
-    :param restval: A default value for keys that have no values
-    :param extrasaction: The action to perform if a key is encountered when parsing the dict that is
-        not included in the fieldnames parameter, either "raise" or "ignore".  Ignore raises a
-        ValueError, and "ignore" simply ignore that key/value pair.  Default behavior is "raise"
+    :type fieldnames: Sequence[str]
+    :param str restval: A default value for keys that have no values
+    :param str extrasaction: The action to perform if a key is encountered when parsing the dict
+        that is not included in the fieldnames parameter, either "raise" or "ignore".  Ignore
+        raises a ValueError, and "ignore" simply ignore that key/value pair.  Default behavior
+        is "raise"
     """
 
     def __init__(
         self,
         f: io.TextIOWrapper,
-        fieldnames: List,
+        fieldnames: Sequence[str],
         restval: str = "",
         extrasaction: str = "raise",
         **kwargs
@@ -233,7 +252,7 @@ def writeheader(self) -> None:
         """Writes the header row to the CSV file"""
         self.writerow(dict(zip(self.fieldnames, self.fieldnames)))
 
-    def _dict_to_list(self, rowdict: Dict[str, Any]) -> Sequence[Any]:
+    def _dict_to_tuple(self, rowdict: Dict[str, Any]) -> Tuple[Any]:
         if self.extrasaction == "raise":
             wrong_fields = []
             for field in rowdict.keys():
@@ -246,17 +265,19 @@ def _dict_to_list(self, rowdict: Dict[str, Any]) -> Sequence[Any]:
                 )
         return (rowdict.get(key, self.restval) for key in self.fieldnames)
 
-    def writerow(self, rowdict: Dict[str, Any]) -> None:
+    def writerow(self, rowdict: Dict[str, SupportsStringCasting]) -> None:
         """Writes a row to the CSV file
 
         :param rowdict: The row to write as a dict, with keys of the DictWriter's
             fieldnames parameter
+        :type rowdict: Dict[str, SupportsStringCasting]
         """
-        return self.writer.writerow(self._dict_to_list(rowdict))
+        return self.writer.writerow(self._dict_to_tuple(rowdict))
 
-    def writerows(self, rowdicts: Iterable[Any]) -> None:
+    def writerows(self, rowdicts: Iterable[Dict[str, SupportsStringCasting]]) -> None:
         """Writes multiple rows to the CSV files
 
         :param rowdicts: An iterable item that yields multiple rows to write
+        :type rowdicts: Iterable[Dict[str, SupportsStringCasting]]
         """
-        return self.writer.writerows(map(self._dict_to_list, rowdicts))
+        return self.writer.writerows(map(self._dict_to_tuple, rowdicts))