Re: Psycopg documentation (was Re: State of PostgreSQL's drivers in Python)

On Tue, Feb 9, 2010 at 1:57 PM, Jonathan Ballet <[email protected]> wrote:
> On Tue, 9 Feb 2010 05:39:21 +0000, Daniele Varrazzo
> <[email protected]> wrote:

> I quickly read it and found some typos which have been commited into a
> fork on Github.

Very good: I'm glat to pull everything you will contribute.


> The only comments I have so far are:
>
> * we should make a clear distinction between *psycopg* and *psycopg2* in
> the documentation itself (I think the Python's code speaks by itself)

Yes, I've tried to be consistent but I made my mind during the course
so I may have left some old versions around.

My guideline is:

- the name of the project, or of the "thing" we speak about, is
Psycopg, with uppercase P and in regular typeface. When clarification
about the version is needed it should be "Psycopg 2", with a space.

- the name of the module is psycopg2: lowercase and rendered in a
fixed width font. In sphinx it should be :mod:`psycopg2` so that a
link to the module is created. When the link is redundant it may be
``psycopg2`` (I don't like very much the way it's rendered and I'd
like to differentiate it from the inline code samples, unfortunately
:obj:`psycopg2` creates a link anyway. Do you know any way to render
like the objects without a target, e.g. like "dsn" and
"connection_factory" in the body of the connect() documentation? see
http://piro.develer.com/psycopg2-doc/module.html#psycopg2.connect)

So, every reference to psycopg, Psycopg2 or ``psycopg`` (in fixed
font) I'd say is a typo to be fixed. I don't think we have any need to
refer back to the ``psycopg`` module (version 1): I'd say is well gone
and it's ok to stay gone.


> * I find the paragraph on query parameters is a bit alarming. Maybe

It has to be :)

> something simpler like "To avoid SQL injections problems, do this:
> ...", with maybe some "don't do this, don't do this, but do this"?

I wanted to put in a single chapter all the nuances of parameters
passing: always use %s, always use (foo,), never use % operator...
it's a continuous source of surprises for newcomers. While at it I'd
like to stress that people in Psycopg takes the SQL injection issue
*quite* seriously.


> * I wonder if we should make a clearer distinction between the DB-API
> interface and the extensions on standard objects (I'm thinking about
> .fetchXXX() methods and iterating over a cursor object for ex.).
> This would have the benefit to document precisely what psycopg offers
> that the DB-API doesn't, but I'm not sure this is a good idea, though
> (I mostly speak aloud here).

I want to add boxes for every point such as "this method is a DBAPI
extension" or "the named cursor is a Psycopg extension"...  I will
definitely do this. A different box from the regular .. note:: would
be nice, in order to have the reader's eye used to it and have notes
of other nature to still be noticed. I'll see how to add an ..
extension:: directive.


> If you need some help to fill some empty pages or fix some todo, just
> ask.

You have pages with license and installation that would be nice to
have merged. I still have to document modules tz and extras (probably
autodoc would be good enough for them, so I'd try to tweak the
docstrings instead of the doc pages). Do you want to deal with them?
Now I am dealing with the scattered small items missing (single
methods etc.) and want to write something more about adaptation
(mostly about the different objects living in the extensions module).

Thank you very much. And apologies for the apologies given to the
wrong person in my previous message ;)

-- Daniele