Completed documentation for the COPY-related methods.

doc/cursor.rst

@@ -339,42 +339,67 @@ The ``cursor`` class
         This method currently does nothing but it is safe to call it.
 
 
+    .. 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. ::
+
+            >>> f = StringIO("42\tfoo\n74\tbar\n")
+            >>> cur.copy_from(f, 'test', columns=('num', 'data'))
+
+            >>> cur.execute("select * from test where id > 5;")
+            >>> cur.fetchall()
+            [(7, 42, 'foo'), (8, 74, 'bar')]
+
+        The optional argument :obj:`sep` is the columns separator and
+        :obj:`null` represents ``NULL`` values in the file.
+
+        The :obj:`columns` argument is a sequence of field names: if not
+        ``None`` only the specified fields will be included in the dump.
+
+        .. versionchanged:: 2.0.6
+            added the :obj:`columns` parameter.
+
+    .. method:: copy_to(file, table, sep='\\t', null='\\N', columns=None)
+
+        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.
+
+        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.
+
+        .. versionchanged:: 2.0.6
+            added the :obj:`columns` parameter.
+
     .. method:: copy_expert(sql, file [, size])
 
-        Submit a user-composed COPY statement.
+        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.
+        to file's read method to control the read buffer size. 
 
-        .. todo:: 
+        .. |COPY| replace:: ``COPY``
+        .. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html
 
-            I'm sure copy_expert can be described better!
+        .. versionadded:: 2.0.6
-
-    .. 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.
-
-        The optional arguments: :obj:`sep` is the columns separator and
-        :obj:`null` represents ``NULL`` values in the file.
-
-        .. todo:: columns argument in copy_from
-
-    .. method:: copy_to(file, table, sep='\t', null='\N', columns=None)
-
-        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.
-
-        The optional arguments: :obj:`sep` is the columns separator and
-        :obj:`null` represents ``NULL`` values in the file.
-
-        .. todo:: columns argument in copy_to
 
     .. attribute:: row_factory
 

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
+:meth:`cursor.copy_to()`
-file-like object. The target file must have a ``write()`` method.
+    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
+:meth:`cursor.copy_from()`
-them to a database table. The source file must have both ``read()`` and
+    Reads data *from* a file-like object appending them to a database table
-``readline()`` method.
+    (``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
+:meth:`cursor.copy_expert()`
-the columns separator and ``null`` (defaulting to ``\N``) represents ``NULL``
+    Allows to handle more specific cases and to use all the |COPY| features
-values in the file.
+    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