Streamline DB Connection API

[anatoly techtonik <techtonik@…>]

This patch simplifies Trac DB API to make it easier to extend and add new DB backends. It introduces abstract DatabaseConnection class that clearly defines what required methods are used by Trac and must be implemented by Connection classes.

I've made it, because I found implicit ConnectionWrapper behavior misleading. I used SQLiteConnection method set as an example, but in the end my implementation failed to execute, because it didn't have commit() method - just like SQLiteConnection. It took a while to dig through PooledConnection to ConnectionWrapper then to SQLiteConnection and finally to ConnectionWrapper again to realize that commit() method is implicitly called from bundled SQLite library when it isn't found anywhere else.

I hope this negative developer experience will find more response in tracker than it had in mailing list. =)

[Christian Boos]

Not really enthusiastic about this patch which merely adds a class full of:

... 	174	 
 	175	    def concat(self, *args): 
 	176	        raise TracError('Not implemented.') 
 	177	 
 	178	    def like(self): 
 	179	        raise TracError('Not implemented.') 
 	180	 
 	181	    def like_escape(self, text): 
 	182	        raise TracError('Not implemented.') 

methods (and btw, there's a standard NotImplemented exception you might find interesting ;-) ).

[Christian Boos]

… however, adding those methods for documenting them makes sense ;-)

[Christian Boos]

commit() and other such methods are documented in Python DB API 2.0 (​pep:0249) for the Connection Objects.

In ConnectionWrapper, we should add the documentation for the following methods: cast, concat, like, like_escape, quote, get_last_id, and update_sequence.

[Christian Boos]

Documented in r11322 (​apidoc:api/trac_db_util)

Doing it as docstring in the code proved to be annoying, as this implied forwarding the calls to the wrapped .cnx. Fortunately with Sphinx one can happily mix auto-generated documentation and manual documentation ;-)