psycopg/psycopg2
1
1
Fork 0
mirror of https://github.com/psycopg/psycopg2.git synced 2024-12-01 21:23:43 +03:00
Code Issues Packages Projects Releases Wiki Activity

Completed documentation for the COPY-related methods.

Browse Source
This commit is contained in:
Daniele Varrazzo 2010-02-09 16:30:52 +00:00 committed by Federico Di Gregorio
parent d081d533b9
commit ac6640fd9e
2 changed files with 70 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
doc/cursor.rst
View File

@ -339,42 +339,67 @@ The ``cursor`` class
This method currently does nothing but it is safe to call it. 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]) .. 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 :obj:`file` must be an open, readable file for ``COPY FROM`` or an
open, writeable file for ``COPY TO``. The optional :obj:`size` open, writeable file for ``COPY TO``. The optional :obj:`size`
argument, when specified for a ``COPY FROM`` statement, will be passed 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 .. attribute:: row_factory

27
doc/usage.rst
View File

@ -339,19 +339,26 @@ Using COPY TO and COPY FROM
--------------------------- ---------------------------
Psycopg :class:`cursor` objects provide an interface to the efficient 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