Changeset 4284

Timestamp:

13 Jun 2009, 23:14:24 (16 years ago)

Author:

uli

Message:

Extend csvfile docs.

File:

• waeup/branches/ulif-rewrite/src/waeup/csvfile/README.txt (modified) (5 diffs)

waeup/branches/ulif-rewrite/src/waeup/csvfile/README.txt

@@ -7 +7 @@
    :synopsis: generic support for handling CSV files.
 
-.. Module Contents
-.. ================
+
+.. note::
+
+   This version of the :mod:`waeup.csvfile` module doesn't support
+   Unicode input.  Also, there are currently some issues regarding
+   ASCII NUL characters.  Accordingly, all input should be UTF-8 or
+   printable ASCII to be safe. These restrictions will be removed in
+   the future.
+
+
+Module Contents
+================
 
 .. class:: CSVFile(filepath)
@@ -16 +26 @@
    strings).
 
+   :class:`CSVFile` is designed as a base for derived, more
+   specialized types of CSV files wrappers, although it can serve as a
+   basic wrapper for simple, unspecified CSV files.
+
    .. method:: grok.context(basestring)
       :noindex:
@@ -61 +75 @@
       values for correct data types or so.
 
-
+   .. method:: getHeaderFields()
+
+      Get a sorted list of header fields in the wrapped CSV file.
+
+.. function:: getCSVFile(filepath)
+
+   `filepath`
+      String with a filepath to an existing CSV file.
+
+   Get a CSV file wrapper for the given `filepath`. :func:`getCSVFile`
+   knows about all registered :class:`CSVFile` wrappers registered and
+   searches them for the most appropriate one.
+
+   If none can be found ``None`` is returned.
+
+   .. seealso:: 
+
+      :ref:`getcsvfilewrapper`,
+
+      :ref:`getcsvfiledecision`
 
 Basic example
 =============
 
-To initialize the whole framework we have to grok the `waeup` package
-first:
+To initialize the whole framework we have to grok the :mod:`waeup`
+package first:
 
     >>> import grok
@@ -180 +213 @@
     ['col1', 'col2']
 
+.. _getcsvfilewrapper:
+
 Getting a wrapper
 =================
@@ -221 +256 @@
     True
 
+.. _getcsvfiledecision:
 
 How `getCSVFile()` decides which wrapper to use