From ac6640fd9e03b89700fe3351a268260dfc42fd3b Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Tue, 9 Feb 2010 16:30:52 +0000 Subject: [PATCH] Completed documentation for the COPY-related methods. --- doc/cursor.rst | 81 +++++++++++++++++++++++++++++++++----------------- doc/usage.rst | 27 ++++++++++------- 2 files changed, 70 insertions(+), 38 deletions(-) diff --git a/doc/cursor.rst b/doc/cursor.rst index 9826c2d8..a3c6855e 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_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! - - .. 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 + .. versionadded:: 2.0.6 .. attribute:: row_factory diff --git a/doc/usage.rst b/doc/usage.rst index 044c93ae..29c5b672 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