Completed documentation for the COPY-related methods.

2 files changed, 66 insertions, 34 deletions

diff --git a/doc/cursor.rst b/doc/cursor.rst
index 9826c2d..a3c6855 100644
--- a/doc/cursor.rst
+++ b/doc/cursor.rst
@@ -339,42 +339,67 @@ The ``cursor`` class
         This method currently does nothing but it is safe to call it.
 
 
-    .. method:: copy_expert(sql, file [, size])
+    .. method:: copy_from(file, table, sep='\\t', null='\\N', columns=None)
+ 
+        Read data *from* the file-like object :obj:`file` appending them to
+        the table named :obj:`table`.  :obj:`file` must have both ``read()``
+        and ``readline()`` method.  See :ref:`copy` for an overview. ::
 
-        Submit a user-composed COPY statement.
+            >>> f = StringIO("42\tfoo\n74\tbar\n")
+            >>> cur.copy_from(f, 'test', columns=('num', 'data'))
 
-        :obj:`file` must be an open, readable file for ``COPY FROM`` or an
-        open, writeable file for ``COPY TO``. The optional :obj:`size`
-        argument, when specified for a ``COPY FROM`` statement, will be passed
-        to file's read method to control the read buffer size.
+            >>> cur.execute("select * from test where id > 5;")
+            >>> cur.fetchall()
+            [(7, 42, 'foo'), (8, 74, 'bar')]
 
-        .. todo:: 
+        The optional argument :obj:`sep` is the columns separator and
+        :obj:`null` represents ``NULL`` values in the file.
 
-            I'm sure copy_expert can be described better!
+        The :obj:`columns` argument is a sequence of field names: if not
+        ``None`` only the specified fields will be included in the dump.
 
-    .. method:: copy_from(file, table, sep='\t', null='\N', columns=None)
-     
-        Read data *from* the file-like object :obj:`file` appending them to
-        the table named :obj:`table`.  See :ref:`copy`.
-        
-        :obj:`file` must have both ``read()`` and ``readline()`` method.
+        .. versionchanged:: 2.0.6
+            added the :obj:`columns` parameter.
+
+    .. method:: copy_to(file, table, sep='\\t', null='\\N', columns=None)
 
-        The optional arguments: :obj:`sep` is the columns separator and
+        Write the content of the table named :obj:`table` *to* the file-like object :obj:`file`.  :obj:`file` must have a ``write()`` method. See
+        :ref:`copy` for an overview. ::
+
+            >>> cur.copy_to(sys.stdout, 'test', sep="|")
+            1|100|abc'def
+            2|\N|dada
+
+        The optional argument :obj:`sep` is the columns separator and
         :obj:`null` represents ``NULL`` values in the file.
 
-        .. todo:: columns argument in copy_from
+        The :obj:`columns` argument is a sequence representing the fields
+        where the read data will be entered. Its length and column type should
+        match the content of the read file.
 
-    .. method:: copy_to(file, table, sep='\t', null='\N', columns=None)
+        .. versionchanged:: 2.0.6
+            added the :obj:`columns` parameter.
 
-        Write the content of the table named :obj:`table` *to* the file-like
-        object :obj:`file`.  See :ref:`copy`.
-        
-        :obj:`file` must have a ``write()`` method.
+    .. method:: copy_expert(sql, file [, size])
 
-        The optional arguments: :obj:`sep` is the columns separator and
-        :obj:`null` represents ``NULL`` values in the file.
+        Submit a user-composed ``COPY`` statement. The method is useful to
+        handle all the parameters that PostgreSQL makes available (see
+        |COPY|__ command documentation).
+
+            >>> cur.copy_expert("COPY test TO STDOUT WITH CSV HEADER", sys.stdout)
+            id,num,data
+            1,100,abc'def
+            2,,dada
+
+        :obj:`file` must be an open, readable file for ``COPY FROM`` or an
+        open, writeable file for ``COPY TO``. The optional :obj:`size`
+        argument, when specified for a ``COPY FROM`` statement, will be passed
+        to file's read method to control the read buffer size. 
+
+        .. |COPY| replace:: ``COPY``
+        .. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html
 
-        .. todo:: columns argument in copy_to
+        .. versionadded:: 2.0.6
 
     .. attribute:: row_factory
 
diff --git a/doc/usage.rst b/doc/usage.rst
index 044c93a..29c5b67 100644
--- a/doc/usage.rst
+++ b/doc/usage.rst
@@ -339,19 +339,26 @@ Using COPY TO and COPY FROM
 ---------------------------
 
 Psycopg :class:`cursor` objects provide an interface to the efficient
-PostgreSQL `COPY command`_ to move data from files to tables and back.
+PostgreSQL |COPY|__ command to move data from files to tables and back.
+The methods exposed are:
 
-The :meth:`cursor.copy_to()` method writes the content of a table *to* a
-file-like object. The target file must have a ``write()`` method.
+:meth:`cursor.copy_to()`
+    Writes the content of a table *to* a file-like object (``COPY table TO
+    file`` syntax). The target file must have a ``write()`` method.
 
-The :meth:`cursor.copy_from()` reads data *from* a file-like object appending
-them to a database table. The source file must have both ``read()`` and
-``readline()`` method.
+:meth:`cursor.copy_from()`
+    Reads data *from* a file-like object appending them to a database table
+    (``COPY table FROM file`` syntax). The source file must have both
+    ``read()`` and ``readline()`` method.
 
-Both methods accept two optional arguments: ``sep`` (defaulting to a tab) is
-the columns separator and ``null`` (defaulting to ``\N``) represents ``NULL``
-values in the file.
+:meth:`cursor.copy_expert()`
+    Allows to handle more specific cases and to use all the |COPY| features
+    available in PostgreSQL.
 
-.. _COPY command: http://www.postgresql.org/docs/8.4/static/sql-copy.html
+Please refer to the documentation of the single methods for details and
+examples.
+
+.. |COPY| replace:: ``COPY``
+.. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html