[Twisted-Python] twisted.enterprise docs suck
Because the twisted.enterprise docs currently suck (i.e. I couldn't figure it out without help :), I decided to write a small tutorial that should hopefully explain things a bit better. I've put a copy up at http://poetry.puzzling.org/twisted_db.html. I'd appreciate any feedback anyone has, in particular: * Have I stuffed up anything major? * Is my terminology ok (e.g. "...dispatch queries to your ConnectionPool...") * Am I demonstrating "best practice" use of twisted.enterprise, or should I be structuring my code differently? If someone wants to place this (or an edited version of it) on twistedmatrix.com, or distribute it with Twisted, or both, they are welcome. Regards, -Andrew.
On Wed, 2002-01-30 at 09:21, andrew-twisted@puzzling.org wrote:
Because the twisted.enterprise docs currently suck (i.e. I couldn't figure it out without help :), I decided to write a small tutorial that should hopefully explain things a bit better.
Thank you VERY much! Anybody else out there want to write some tutorials?
I've put a copy up at http://poetry.puzzling.org/twisted_db.html. I'd appreciate any feedback anyone has, in particular: * Have I stuffed up anything major?
Not really, the example looks nice 'n' simple, illustrating that ADBAPI is not a very big API at all :)
* Is my terminology ok (e.g. "...dispatch queries to your ConnectionPool...")
Sounds fine to me.
* Am I demonstrating "best practice" use of twisted.enterprise, or should I be structuring my code differently?
There is one slight modification I'd make. Typically, a method that calls runOperation will return its result, since presumably you are writing external code that uses the service and expects some way to hook into results being available :-).
If someone wants to place this (or an edited version of it) on twistedmatrix.com, or distribute it with Twisted, or both, they are welcome.
Will do. We've got lots of docs to write, and we'll integrate these as soon as I have some time. Thanks for relieving a bit of that burden! -- "Cannot stand to be one of many -- I'm not what they are." -Guster, "Rocketship" glyph lefkowitz; ninjaneer, freelance demiurge glyph @ [ninjaneering|twistedmatrix].com
Glyph wrote:
* Am I demonstrating "best practice" use of twisted.enterprise, or should I be structuring my code differently?
There is one slight modification I'd make. Typically, a method that calls runOperation will return its result, since presumably you are writing external code that uses the service and expects some way to hook into results being available :-).
Ok, so how about if I change the last example to: class AgeDatabase(adbapi.Augmentation): """A simple example that can retrieve an age from the database""" def getAge(self, name): # Define the query sql = """SELECT Age FROM People WHERE name = ?""" # Run the query, and set a callback to run when done return self.runOperation(sql, name) def gotAge(resultlist, name): """Callback for handling the result of the query""" age = resultlist[0][0] # First field of first record print "%s is %d years old" % (name, age) db = MyDatabase(dbpool) # These will *not* block. Hooray! db.getAge("Andrew").addCallbacks(gotAge, db.operationError, callbackArgs=name).arm() db.getAge("Glyph").addCallbacks(gotAge, db.operationError, callbackArgs=name).arm() If this looks sane to you, I'll update the example and the surrounding text at poetry.puzzling.org/twisted_db.html.
If someone wants to place this (or an edited version of it) on twistedmatrix.com, or distribute it with Twisted, or both, they are welcome.
Will do. We've got lots of docs to write, and we'll integrate these as soon as I have some time. Thanks for relieving a bit of that burden!
Actually, it was suggested to me that I should be more explicit with my licencing of that document. I haven't had time to probably examine documentation licences, so I'll just state this instead: I donate the copyright to that tutorial to the Twisted developers (i.e. Twisted Matrix Laboratories). Basically, do what you like, I won't sue :) -Andrew.
On Fri, Feb 01, 2002 at 12:21:33PM +1100, Andrew Bennetts wrote:
If this looks sane to you, I'll update the example and the surrounding text at poetry.puzzling.org/twisted_db.html.
Ok, so I finally did this update, but not there. http://twistedmatrix.com/users/carmstro.twistd/static/moin/wiki/cgi-bin/moin... -Andrew.
Great! Thanks a lot for putting it on the wiki. My plan to wikify the documentation is coming together! muahahahahaha! Anyway, I'm going to be implementing a PB interface to Moin. the server-side stuff looks to be really easy (despite the MoinMoin code being a pain - I only need to use a tiny bit of it). I was inspired yesterday by Emacs' Wiki-mode when Nafai showed it to be, and proclaimed "I *need* to interface this to a remote moin!" So, hopefully Allen will help me out in that area ;) On Tue, 2002-02-19 at 10:34, Andrew Bennetts wrote:
On Fri, Feb 01, 2002 at 12:21:33PM +1100, Andrew Bennetts wrote:
If this looks sane to you, I'll update the example and the surrounding text at poetry.puzzling.org/twisted_db.html.
Ok, so I finally did this update, but not there.
http://twistedmatrix.com/users/carmstro.twistd/static/moin/wiki/cgi-bin/moin...
-Andrew.
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python -- Chris Armstrong << radix@twistedmatrix.com >> http://twistedmatrix.com/users/carmstro.twistd/
participants (5)
-
Andrew Bennetts -
Andrew Bennetts -
andrew-twisted＠puzzling.org
-
Christopher Armstrong -
Glyph Lefkowitz