Added docs about the usability of sql objects with copy_expert()

See issue #529.

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`

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
 

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