Changeset 693 for trunk/docs


Ignore:
Timestamp:
Jan 4, 2016, 5:51:09 PM (4 years ago)
Author:
cito
Message:

Support copy_from() and copy_to() in pgdb

Location:
trunk/docs
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/docs/changelog.rst

    r692 r693  
    1717- The DB-API 2 module now supports the callproc() cursor method. Note
    1818  that output parameters are currently not replaced in the return value.
     19- The DB-API 2 module no supports copy operations between data streams
     20  on the client and database tables via the COPY command of PostgreSQL.
     21  The cursor method copy_from() can be used to copy data from the database
     22  to the client, and the cursor method copy_to() can be used to copy data
     23  from the client to the database.
    1924- The 7-tuples returned by the description attribute of a pgdb cursor
    2025  are now named tuples, i.e. their elements can be also accessed by name.
  • trunk/docs/pgdb.rst

    r692 r693  
    268268    :meth:`Cursor.execute` or :meth:`Cursor.executemany` call produced
    269269    (for DQL statements like SELECT) or affected (for DML statements like
    270     UPDATE or INSERT ). The attribute is -1 in case no such method call has
    271     been performed on the cursor or the rowcount of the last operation
    272     cannot be determined by the interface.
     270    UPDATE or INSERT). It is also set by the :meth:`Cursor.copy_from` and
     271    :meth':`Cursor.copy_to` methods. The attribute is -1 in case no such
     272    method call has been performed on the cursor or the rowcount of the
     273    last operation cannot be determined by the interface.
    273274
    274275close -- close the cursor
     
    436437
    437438   The following methods and attributes are not part of the DB-API 2 standard.
     439
     440.. method:: Cursor.copy_from(stream, table, [format], [sep], [null], [size], [columns])
     441
     442        Copy data from an input stream to the specified table
     443
     444    :param stream: the input stream
     445        (must be a file-like object, a string or an iterable returning strings)
     446    :param str table: the name of a database table
     447    :param str format: the format of the data in the input stream,
     448        can be ``'text'`` (the default), ``'csv'``, or ``'binary'``
     449    :param str sep: a single character separator
     450        (the default is ``'\t'`` for text and ``','`` for csv)
     451    :param str null: the textual representation of the ``NULL`` value,
     452        can also be an empty string (the default is ``'\\N'``)
     453    :param int size: the size of the buffer when reading file-like objects
     454    :param list column: an optional list of column names
     455    :returns: the cursor, so you can chain commands
     456
     457    :raises TypeError: parameters with wrong types
     458    :raises ValueError: invalid parameters
     459    :raises IOError: error when executing the copy operation
     460
     461This method can be used to copy data from an input stream on the client side
     462to a database table on the server side using the ``COPY FROM`` command.
     463The input stream can be provided in form of a file-like object (which must
     464have a ``read()`` method), a string, or an iterable returning one row or
     465multiple rows of input data on each iteration.
     466
     467The format must be text, csv or binary. The sep option sets the column
     468separator (delimiter) used in the non binary formats. The null option sets
     469the textual representation of ``NULL`` in the input.
     470
     471The size option sets the size of the buffer used when reading data from
     472file-like objects.
     473
     474The copy operation can be restricted to a subset of columns. If no columns are
     475specified, all of them will be copied.
     476
     477.. method:: Cursor.copy_to(stream, table, [format], [sep], [null], [decode], [columns])
     478
     479        Copy data from the specified table to an output stream
     480
     481    :param stream: the output stream (must be a file-like object or ``None``)
     482    :param str table: the name of a database table or a ``SELECT`` query
     483    :param str format: the format of the data in the input stream,
     484        can be ``'text'`` (the default), ``'csv'``, or ``'binary'``
     485    :param str sep: a single character separator
     486        (the default is ``'\t'`` for text and ``','`` for csv)
     487    :param str null: the textual representation of the ``NULL`` value,
     488        can also be an empty string (the default is ``'\\N'``)
     489    :param bool decode: whether decoded strings shall be returned
     490        for non-binary formats (the default is True in Python 3)
     491    :param list column: an optional list of column names
     492    :returns: a generator if stream is set to ``None``, otherwise the cursor
     493
     494    :raises TypeError: parameters with wrong types
     495    :raises ValueError: invalid parameters
     496    :raises IOError: error when executing the copy operation
     497
     498This method can be used to copy data from a database table on the server side
     499to an output stream on the client side using the ``COPY TO`` command.
     500
     501The output stream can be provided in form of a file-like object (which must
     502have a ``write()`` method). Alternatively, if ``None`` is passed as the
     503output stream, the method will return a generator yielding one row of output
     504data on each iteration.
     505
     506Output will be returned as byte strings unless you set decode to true.
     507
     508Note that you can also use a ``SELECT`` query instead of the table name.
     509
     510The format must be text, csv or binary. The sep option sets the column
     511separator (delimiter) used in the non binary formats. The null option sets
     512the textual representation of ``NULL`` in the output.
     513
     514The copy operation can be restricted to a subset of columns. If no columns are
     515specified, all of them will be copied.
    438516
    439517.. method:: Cursor.row_factory(row)
Note: See TracChangeset for help on using the changeset viewer.