diff --git a/doc/src/cursor.rst b/doc/src/cursor.rst index c03cea84..417ab6cf 100644 --- a/doc/src/cursor.rst +++ b/doc/src/cursor.rst @@ -601,7 +601,10 @@ The ``cursor`` class The *sql* statement should be in the form :samp:`COPY {table} TO STDOUT` to export :samp:`{table}` to the *file* object passed as argument or :samp:`COPY {table} FROM STDIN` to import the content of - the *file* object into :samp:`{table}`. + the *file* object into :samp:`{table}`. If you need to compose a + :sql:`COPY` statement dynamically (because table, fields, or query + parameters are in Python variables) you may use the objects provided + by the `psycopg2.sql` module. *file* must be a readable file-like object (as required by `~cursor.copy_from()`) for *sql* statement :sql:`COPY ... FROM STDIN` diff --git a/doc/src/sql.rst b/doc/src/sql.rst index 0aee4519..fe807c6a 100644 --- a/doc/src/sql.rst +++ b/doc/src/sql.rst @@ -55,6 +55,11 @@ from the query parameters:: .format(sql.Identifier('my_table')), [10, 20]) +The objects exposed by the `!sql` module can be used to compose a query as a +Python string (using the `~Composable.as_string()` method) or passed directly +to cursor methods such as `~cursor.execute()`, `~cursor.executemany()`, +`~cursor.copy_expert()`. + .. autoclass:: Composable diff --git a/lib/sql.py b/lib/sql.py index ffd9e27e..d57fbe29 100644 --- a/lib/sql.py +++ b/lib/sql.py @@ -36,8 +36,9 @@ class Composable(object): """ Abstract base class for objects that can be used to compose an SQL string. - `!Composable` objects can be passed directly to `~cursor.execute()` and - `~cursor.executemany()` in place of the query string. + `!Composable` objects can be passed directly to `~cursor.execute()`, + `~cursor.executemany()`, `~cursor.copy_expert()` in place of the query + string. `!Composable` objects can be joined using the ``+`` operator: the result will be a `Composed` instance containing the objects joined. The operator @@ -58,9 +59,9 @@ class Composable(object): :param context: the context to evaluate the string into. :type context: `connection` or `cursor` - The method is automatically invoked by `~cursor.execute()` and - `~cursor.executemany()` if a `!Composable` is passed instead of the - query string. + The method is automatically invoked by `~cursor.execute()`, + `~cursor.executemany()`, `~cursor.copy_expert()` if a `!Composable` is + passed instead of the query string. """ raise NotImplementedError