Main Copy objects #

class psycopg. Copy ( cursor , * , binary = None , writer = None ) #

Manage a COPY operation.

Parameters :

• cursor ( Cursor [ Any ]) - the cursor where the operation is performed.

• binary ( Optional [ bool ]) - if True , write binary format.

• writer ( Optional [ Writer ]) - the object to write to destination. If not specified, write to the cursor connection.

Choosing binary is not necessary if the cursor has executed a COPY operation, because the operation result describes the format too. The parameter is useful when a Copy object is created manually and no operation is performed on the cursor, such as when using writer= FileWriter .

The object is normally returned by with Cursor.copy() .

write_row ( row ) #

Write a record to a table after a COPY FROM operation.

The data in the tuple will be converted as configured on the cursor; see Data adaptation configuration for details.

write ( buffer ) #

Write a block of data to a table after a COPY FROM operation.

If the COPY is in binary format buffer must be bytes . In text mode it can be either bytes or str .

read ( ) #

Read an unparsed row after a COPY TO operation.

Return an empty string when the data is finished.

Return type :

Union [ bytes , bytearray , memoryview ]

Instead of using !read() you can iterate on the !Copy object to read its data row by row, using for row in copy: ... .

rows ( ) #

Iterate on the result of a COPY TO operation record by record.

Note that the records returned will be tuples of unparsed strings or bytes, unless data types are specified using set_types() .

Return type :

Iterator [ Tuple [ Any , ... ]]

Equivalent of iterating on read_row() until it returns !None

read_row ( ) #

Read a parsed row of data from a table after a COPY TO operation.

Return !None when the data is finished.

Note that the records returned will be tuples of unparsed strings or bytes, unless data types are specified using set_types() .

Return type :

Optional [ Tuple [ Any , ... ]]

set_types ( types ) #

Set the types expected in a COPY operation.

The types must be specified as a sequence of oid or PostgreSQL type names (e.g. int4 , timestamptz[] ).

This operation overcomes the lack of metadata returned by PostgreSQL when a COPY operation begins:

• On COPY TO , !set_types() allows to specify what types the operation returns. If !set_types() is not used, the data will be returned as unparsed strings or bytes instead of Python objects.

• On COPY FROM , !set_types() allows to choose what type the database expects. This is especially useful in binary copy, because PostgreSQL will apply no cast rule.

class psycopg. AsyncCopy ( cursor , * , binary = None , writer = None ) #

Manage an asynchronous COPY operation.

The object is normally returned by async with AsyncCursor.copy() . Its methods are similar to the ones of the Copy object but offering an asyncio interface ( await , async for , async with ).

async write_row ( row ) #

async write ( buffer ) #

async read ( ) #

Return type :

Union [ bytes , bytearray , memoryview ]

Instead of using !read() you can iterate on the !AsyncCopy object to read its data row by row, using async for row in copy: ... .

async rows ( ) #

Return type :

AsyncIterator [ Tuple [ Any , ... ]]

Use it as async for record in copy.rows(): …

async read_row ( ) #

Return type :

Optional [ Tuple [ Any , ... ]]

Writer objects #

Copy writers are helper objects to specify where to write COPY-formatted data. By default, data is written to the database (using the LibpqWriter ). It is possible to write copy-data for offline use by using a FileWriter , or to customize further writing by implementing your own Writer or AsyncWriter subclass.

Writers instances can be used passing them to the cursor ~psycopg.Cursor.copy() method or to the ~psycopg.Copy constructor, as the !writer argument.

class psycopg.copy. Writer #

A class to write copy data somewhere.

This is an abstract base class: subclasses are required to implement their write() method.

abstract write ( data ) #

Write some data to destination.

finish ( exc = None ) #

Called when write operations are finished.

If operations finished with an error, it will be passed to exc .

class psycopg.copy. LibpqWriter ( cursor ) #

A Writer to write copy data to a Postgres database.

This is the writer used by default if none is specified.

class psycopg.copy. FileWriter ( file ) #

A Writer to write copy data to a file-like object.

Parameters :

file ( IO [ bytes ]) - the file where to write copy data. It must be open for writing in binary mode.

This writer should be used without executing a COPY operation on the database. For example, if records is a list of tuples containing data to save in COPY format to a file (e.g. for later import), it can be used as:

with open("target-file.pgcopy", "wb") as f:
    with Copy(cur, writer=FileWriter(f)) as copy:
        for record in records
            copy.write_row(record)

class psycopg.copy. AsyncWriter #

A class to write copy data somewhere (for async connections).

This class methods have the same semantics of the ones of Writer , but offer an async interface.

abstract async write ( data ) #

async finish ( exc = None ) #

class psycopg.copy. AsyncLibpqWriter ( cursor ) #

An AsyncWriter to write copy data to a Postgres database.