From 9614e7241bf8a4c713895b01018027dd35ee8c60 Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Mon, 6 Nov 2017 17:57:39 +0000 Subject: [PATCH] Further docs cleanup Recent Sphinx versions seem overly aggressive in autodetecting python, or I just didn't notice the errors, so be explicit in what language to use with code examples. --- doc/src/advanced.rst | 4 +++- doc/src/conf.py | 4 ++++ doc/src/extras.rst | 4 ++-- doc/src/faq.rst | 4 +++- doc/src/usage.rst | 44 ++++++++++++++++++++++++++++---------------- 5 files changed, 40 insertions(+), 20 deletions(-) diff --git a/doc/src/advanced.rst b/doc/src/advanced.rst index 5b5fb354..b2b8afe3 100644 --- a/doc/src/advanced.rst +++ b/doc/src/advanced.rst @@ -295,7 +295,9 @@ something to read:: print "Got NOTIFY:", notify.pid, notify.channel, notify.payload Running the script and executing a command such as :sql:`NOTIFY test, 'hello'` -in a separate :program:`psql` shell, the output may look similar to:: +in a separate :program:`psql` shell, the output may look similar to: + +.. code-block:: none Waiting for notifications on channel 'test' Timeout diff --git a/doc/src/conf.py b/doc/src/conf.py index 9e73308b..6afb2869 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -101,6 +101,10 @@ default_role = 'obj' # output. They are ignored by default. #show_authors = False +# Using 'python' instead of the default gives warnings if parsing an example +# fails, instead of defaulting to none +highlight_language = 'python' + # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' diff --git a/doc/src/extras.rst b/doc/src/extras.rst index 36118e7e..c844873a 100644 --- a/doc/src/extras.rst +++ b/doc/src/extras.rst @@ -403,7 +403,7 @@ The individual messages in the replication stream are represented by class LogicalStreamConsumer(object): - ... + # ... def __call__(self, msg): self.process_message(msg.payload) @@ -501,7 +501,7 @@ The individual messages in the replication stream are represented by from datetime import datetime def consume(msg): - ... + # ... keepalive_interval = 10.0 while True: diff --git a/doc/src/faq.rst b/doc/src/faq.rst index fb7b33dd..0ef4c708 100644 --- a/doc/src/faq.rst +++ b/doc/src/faq.rst @@ -306,7 +306,9 @@ I can't compile `!psycopg2`: the compiler says *error: libpq-fe.h: No such file API support (*i.e.* the libpq used at compile time was at least 9.3) but at runtime an older libpq dynamic library is found. - You can use:: + You can use: + + .. code-block:: shell $ ldd /path/to/packages/psycopg2/_psycopg.so | grep libpq diff --git a/doc/src/usage.rst b/doc/src/usage.rst index 429d6b92..79823b11 100644 --- a/doc/src/usage.rst +++ b/doc/src/usage.rst @@ -48,7 +48,7 @@ The main entry points of Psycopg are: - The class `connection` encapsulates a database session. It allows to: - - create new `cursor`\s using the `~connection.cursor()` method to + - create new `cursor` instances using the `~connection.cursor()` method to execute database commands and queries, - terminate transactions using the methods `~connection.commit()` or @@ -73,30 +73,40 @@ The main entry points of Psycopg are: Passing parameters to SQL queries --------------------------------- -Psycopg casts Python variables to SQL literals by type. Many standard Python types -are already `adapted to the correct SQL representation`__. +Psycopg converts Python variables to SQL values using their types: the Python +type determines the function used to convert the object into a string +representation suitable for PostgreSQL. Many standard Python types are +already `adapted to the correct SQL representation`__. .. __: python-types-adaptation_ -Example: the Python function call:: +Passing parameters to an SQL statement happens in functions such as +`cursor.execute()` by using ``%s`` placeholders in the SQL statement, and +passing a sequence of values as the second argument of the function. For +example the Python function call:: - >>> cur.execute( - ... """INSERT INTO some_table (an_int, a_date, a_string) - ... VALUES (%s, %s, %s);""", + >>> cur.execute(""" + ... INSERT INTO some_table (an_int, a_date, a_string) + ... VALUES (%s, %s, %s); + ... """, ... (10, datetime.date(2005, 11, 18), "O'Reilly")) -is converted into the SQL command:: +is converted into a SQL command similar to: + +.. code-block:: sql INSERT INTO some_table (an_int, a_date, a_string) - VALUES (10, '2005-11-18', 'O''Reilly'); + VALUES (10, '2005-11-18', 'O''Reilly'); -Named arguments are supported too using :samp:`%({name})s` placeholders. -Using named arguments the values can be passed to the query in any order and -several placeholders can use the same value:: +Named arguments are supported too using :samp:`%({name})s` placeholders in the +query and specifying the values into a mapping. Using named arguments allows +to specify the values in any order and to repeat the same value in several +places in the query:: - >>> cur.execute( - ... """INSERT INTO some_table (an_int, a_date, another_date, a_string) - ... VALUES (%(int)s, %(date)s, %(date)s, %(str)s);""", + >>> cur.execute(""" + ... INSERT INTO some_table (an_int, a_date, another_date, a_string) + ... VALUES (%(int)s, %(date)s, %(date)s, %(str)s); + ... """, ... {'int': 10, 'str': "O'Reilly", 'date': datetime.date(2005, 11, 18)}) Using characters ``%``, ``(``, ``)`` in the argument names is not supported. @@ -809,7 +819,9 @@ lifetime extends well after `~connection.commit()`, calling It is also possible to use a named cursor to consume a cursor created in some other way than using the |DECLARE| executed by `~cursor.execute()`. For example, you may have a PL/pgSQL function - returning a cursor:: + returning a cursor: + + .. code-block:: postgres CREATE FUNCTION reffunc(refcursor) RETURNS refcursor AS $$ BEGIN