Edgewall Software
Modify

Opened 11 years ago

Closed 8 years ago

Last modified 7 years ago

#8647 closed enhancement (fixed)

Streamline DB Connection API

Reported by: anatoly techtonik <techtonik@…> Owned by: Christian Boos
Priority: normal Milestone: 1.0.1
Component: database backend Version: 0.11.5
Severity: normal Keywords: documentation
Cc: Branch:
Release Notes:

Added documentation for the ConnectionWrapper methods.

API Changes:

Added documentation for the ConnectionWrapper methods.

Internal Changes:

Description (last modified by Christian Boos)

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. =)

Attachments (1)

connection.wrapper.2.db.api.patch (7.1 KB ) - added by anatoly techtonik <techtonik@…> 11 years ago.

Download all attachments as: .zip

Change History (7)

by anatoly techtonik <techtonik@…>, 11 years ago

comment:1 by Christian Boos, 11 years ago

Resolution: wontfix
Status: newclosed

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 ;-) ).

comment:2 by Christian Boos, 8 years ago

Keywords: documentation added
Milestone: 1.1.1
Resolution: wontfix
Status: closedreopened

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

comment:3 by Christian Boos, 8 years ago

Owner: set to Christian Boos
Status: reopenednew

comment:4 by Christian Boos, 8 years ago

Description: modified (diff)
Milestone: 1.1.11.0.1

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.

comment:5 by Christian Boos, 8 years ago

Resolution: fixed
Status: newclosed

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 ;-)

comment:6 by Ryan J Ollos <ryan.j.ollos@…>, 7 years ago

API Changes: modified (diff)
Release Notes: modified (diff)

Modify Ticket

Change Properties
Set your email in Preferences
Action
as closed The owner will remain Christian Boos.
The resolution will be deleted. Next status will be 'reopened'.
to The owner will be changed from Christian Boos to the specified user.

Add Comment


E-mail address and name can be saved in the Preferences .
 
Note: See TracTickets for help on using tickets.