From 76df3bf1e15433f81b250dfff4af3de9ebe04bce Mon Sep 17 00:00:00 2001 From: Matheus Date: Sun, 28 Apr 2013 21:50:03 -0700 Subject: [PATCH 1/2] update wrong base code in tutorial --- docs/tutorial.rst | 3 +- docs/tutorial.rst~ | 156 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 docs/tutorial.rst~ diff --git a/docs/tutorial.rst b/docs/tutorial.rst index b23a7e7..3e3a275 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -19,7 +19,8 @@ to demonstrate Momoko's functionality. Here goes:: from tornado import gen from tornado.ioloop import IOLoop from tornado.httpserver import HTTPServer - from tornado.options import parse_command_line, asynchronous + from tornado.options import parse_command_line + from tornado.web import * import psycopg2 import momoko diff --git a/docs/tutorial.rst~ b/docs/tutorial.rst~ new file mode 100644 index 0000000..b23a7e7 --- /dev/null +++ b/docs/tutorial.rst~ @@ -0,0 +1,156 @@ +.. _tutorial: + +Tutorial +======== + +This tutorial will demonstrate all the functionality found in Momoko. It's assumed +a working PostgreSQL database is avaiable and dll examples are in the context of a +webaplication. Not everything is explained.\, because Momoko just wraps Psycopg2 +and this means the `Psycopg2 documentation`_ must be used along with Momoko's. + + +Boilerplate +----------- + +Here's the code that's needed for this tutorial. Each example will replace parts +or extend upon this code. The code is kept simple and minimal, its purpose is just +to demonstrate Momoko's functionality. Here goes:: + + from tornado import gen + from tornado.ioloop import IOLoop + from tornado.httpserver import HTTPServer + from tornado.options import parse_command_line, asynchronous + + import psycopg2 + import momoko + + + class BaseHandler(RequestHandler): + @property + def db(self): + return self.application.db + + + class TutorialHandler(BaseHandler): + def get(self): + self.write('Some text here!') + self.finish() + + + if __name__ == '__main__': + parse_command_line() + application = Application([ + (r'/', TutorialHandler) + ], debug=True) + + application.db = momoko.Pool( + dsn='dbname=your_db user=your_user password=very_secret_password ' + 'host=localhost port=5432', + size=1 + ) + + http_server = HTTPServer(application) + http_server.listen(8888, 'localhost') + IOLoop.instance().start() + +For more information about all the parameters passed to ``momoko.Pool`` see +:py:class:`momoko.Pool` in the API documentation. + + +Usage +----- + +:py:meth:`~momoko.Pool.execute`, :py:meth:`~momoko.Pool.callproc`, :py:meth:`~momoko.Pool.transaction` +and :py:meth:`~momoko.Pool.mogrify` are methods of :py:class:`momoko.Pool` and +can be used to query the database. Well, ``mogrify`` not really, it's used to +escape strings, but t needs a connection. All these methods, except ``mogrify``, +return a cursor or an exception object. All of the described retrieval methods in +Psycopg2's documentation like fetchone_, fetchmany_, fetchall_, etc. can be used +to fetch the results. + +All of the example will be using `tornado.gen`_ instead of callbacks, because callbacks +are fairly simple and doesn't require as much explanation. Here's one example using a +callback:: + + class TutorialHandler(BaseHandler): + @asynchronous + def get(self): + self.db.execute('SELECT 1;', callback=self._done) + + def _done(self, cursor, error): + self.write('Results: %r' % (cursor.fetchall(),)) + self.finish() + +The callback only need to accept two parameters. The first one is the cursor and +the second is the exception object. The exception object is ``None`` when no error +occurs and it contains an instance of one of Psycopg2's exceptions_ when an error +did occur. That's all there's to know when using callbacks. + +Instead of using `tornado.gen`_ directly (or using plain callbacks) Momoko provides +subclasses of Task_, Wait_ and WaitAll_ that have some advantages. These are +:py:class:`~momoko.Op`, :py:class:`~momoko.WaitOp` and :py:class:`~momoko.WaitAllOps`. +These three classes only give a cursor back and raise an exception when something +goes wrong. Here's an example using :py:class:`~momoko.Op`:: + + class TutorialHandler(BaseHandler): + @asynchronous + @gen.engine + def get(self): + try: + cursor = yield momoko.Op(self.db.execute, 'SELECT 1;') + except (psycopg2.Warning, psycopg2.Error) as error: + self.write(str(error)) + else: + self.write('Results: %r' % (cursor.fetchall(),)) + + self.finish() + +An example with :py:class:`~momoko.WaitOp`:: + + class TutorialHandler(BaseHandler): + @asynchronous + @gen.engine + def get(self): + self.db.execute('SELECT 1;', callback=(yield gen.Callback('q1'))) + self.db.execute('SELECT 2;', callback=(yield gen.Callback('q2'))) + self.db.execute('SELECT 3;', callback=(yield gen.Callback('q3'))) + + try: + cursor1 = yield momoko.WaitOp('q1') + cursor2 = yield momoko.WaitOp('q2') + cursor3 = yield momoko.WaitOp('q3') + except (psycopg2.Warning, psycopg2.Error) as error: + self.write(str(error)) + else: + self.write('Q1: %r
' % (cursor1.fetchall(),)) + self.write('Q2: %r
' % (cursor2.fetchall(),)) + self.write('Q3: %r
' % (cursor3.fetchall(),)) + + self.finish() + +:py:class:`~momoko.WaitAllOps` can be used instead of three separate +:py:class:`~momoko.WaitOp` calls:: + + try: + cursor1, cursor2, cursor3 = yield momoko.WaitAllOps(('q1', 'q2', 'q3')) + except (psycopg2.Warning, psycopg2.Error) as error: + self.write(str(error)) + else: + self.write('Q1: %r
' % (cursor1.fetchall(),)) + self.write('Q2: %r
' % (cursor2.fetchall(),)) + self.write('Q3: %r
' % (cursor3.fetchall(),)) + +All the above examples are using :py:meth:`~momoko.Pool.execute`, but are possible +with :py:meth:`~momoko.Pool.callproc`, :py:meth:`~momoko.Pool.transaction` and +:py:meth:`~momoko.Pool.mogrify` too. + + +.. _Psycopg2 documentation: http://initd.org/psycopg/docs/cursor.html +.. _tornado.gen: http://www.tornadoweb.org/documentation/gen.html +.. _fetchone: http://initd.org/psycopg/docs/cursor.html#cursor.fetchone +.. _fetchmany: http://initd.org/psycopg/docs/cursor.html#cursor.fetchmany +.. _fetchall: http://initd.org/psycopg/docs/cursor.html#cursor.fetchall +.. _Task: http://www.tornadoweb.org/documentation/gen.html#tornado.gen.Task +.. _Wait: http://www.tornadoweb.org/documentation/gen.html#tornado.gen.Wait +.. _WaitAll: http://www.tornadoweb.org/documentation/gen.html#tornado.gen.WaitAll +.. _exceptions: http://initd.org/psycopg/docs/module.html#exceptions From 7bf98a1fb277e54aad5581e9e79cdd93a98bb30e Mon Sep 17 00:00:00 2001 From: Matheus Date: Sun, 28 Apr 2013 21:56:02 -0700 Subject: [PATCH 2/2] deleted swap file --- docs/tutorial.rst~ | 156 --------------------------------------------- 1 file changed, 156 deletions(-) delete mode 100644 docs/tutorial.rst~ diff --git a/docs/tutorial.rst~ b/docs/tutorial.rst~ deleted file mode 100644 index b23a7e7..0000000 --- a/docs/tutorial.rst~ +++ /dev/null @@ -1,156 +0,0 @@ -.. _tutorial: - -Tutorial -======== - -This tutorial will demonstrate all the functionality found in Momoko. It's assumed -a working PostgreSQL database is avaiable and dll examples are in the context of a -webaplication. Not everything is explained.\, because Momoko just wraps Psycopg2 -and this means the `Psycopg2 documentation`_ must be used along with Momoko's. - - -Boilerplate ------------ - -Here's the code that's needed for this tutorial. Each example will replace parts -or extend upon this code. The code is kept simple and minimal, its purpose is just -to demonstrate Momoko's functionality. Here goes:: - - from tornado import gen - from tornado.ioloop import IOLoop - from tornado.httpserver import HTTPServer - from tornado.options import parse_command_line, asynchronous - - import psycopg2 - import momoko - - - class BaseHandler(RequestHandler): - @property - def db(self): - return self.application.db - - - class TutorialHandler(BaseHandler): - def get(self): - self.write('Some text here!') - self.finish() - - - if __name__ == '__main__': - parse_command_line() - application = Application([ - (r'/', TutorialHandler) - ], debug=True) - - application.db = momoko.Pool( - dsn='dbname=your_db user=your_user password=very_secret_password ' - 'host=localhost port=5432', - size=1 - ) - - http_server = HTTPServer(application) - http_server.listen(8888, 'localhost') - IOLoop.instance().start() - -For more information about all the parameters passed to ``momoko.Pool`` see -:py:class:`momoko.Pool` in the API documentation. - - -Usage ------ - -:py:meth:`~momoko.Pool.execute`, :py:meth:`~momoko.Pool.callproc`, :py:meth:`~momoko.Pool.transaction` -and :py:meth:`~momoko.Pool.mogrify` are methods of :py:class:`momoko.Pool` and -can be used to query the database. Well, ``mogrify`` not really, it's used to -escape strings, but t needs a connection. All these methods, except ``mogrify``, -return a cursor or an exception object. All of the described retrieval methods in -Psycopg2's documentation like fetchone_, fetchmany_, fetchall_, etc. can be used -to fetch the results. - -All of the example will be using `tornado.gen`_ instead of callbacks, because callbacks -are fairly simple and doesn't require as much explanation. Here's one example using a -callback:: - - class TutorialHandler(BaseHandler): - @asynchronous - def get(self): - self.db.execute('SELECT 1;', callback=self._done) - - def _done(self, cursor, error): - self.write('Results: %r' % (cursor.fetchall(),)) - self.finish() - -The callback only need to accept two parameters. The first one is the cursor and -the second is the exception object. The exception object is ``None`` when no error -occurs and it contains an instance of one of Psycopg2's exceptions_ when an error -did occur. That's all there's to know when using callbacks. - -Instead of using `tornado.gen`_ directly (or using plain callbacks) Momoko provides -subclasses of Task_, Wait_ and WaitAll_ that have some advantages. These are -:py:class:`~momoko.Op`, :py:class:`~momoko.WaitOp` and :py:class:`~momoko.WaitAllOps`. -These three classes only give a cursor back and raise an exception when something -goes wrong. Here's an example using :py:class:`~momoko.Op`:: - - class TutorialHandler(BaseHandler): - @asynchronous - @gen.engine - def get(self): - try: - cursor = yield momoko.Op(self.db.execute, 'SELECT 1;') - except (psycopg2.Warning, psycopg2.Error) as error: - self.write(str(error)) - else: - self.write('Results: %r' % (cursor.fetchall(),)) - - self.finish() - -An example with :py:class:`~momoko.WaitOp`:: - - class TutorialHandler(BaseHandler): - @asynchronous - @gen.engine - def get(self): - self.db.execute('SELECT 1;', callback=(yield gen.Callback('q1'))) - self.db.execute('SELECT 2;', callback=(yield gen.Callback('q2'))) - self.db.execute('SELECT 3;', callback=(yield gen.Callback('q3'))) - - try: - cursor1 = yield momoko.WaitOp('q1') - cursor2 = yield momoko.WaitOp('q2') - cursor3 = yield momoko.WaitOp('q3') - except (psycopg2.Warning, psycopg2.Error) as error: - self.write(str(error)) - else: - self.write('Q1: %r
' % (cursor1.fetchall(),)) - self.write('Q2: %r
' % (cursor2.fetchall(),)) - self.write('Q3: %r
' % (cursor3.fetchall(),)) - - self.finish() - -:py:class:`~momoko.WaitAllOps` can be used instead of three separate -:py:class:`~momoko.WaitOp` calls:: - - try: - cursor1, cursor2, cursor3 = yield momoko.WaitAllOps(('q1', 'q2', 'q3')) - except (psycopg2.Warning, psycopg2.Error) as error: - self.write(str(error)) - else: - self.write('Q1: %r
' % (cursor1.fetchall(),)) - self.write('Q2: %r
' % (cursor2.fetchall(),)) - self.write('Q3: %r
' % (cursor3.fetchall(),)) - -All the above examples are using :py:meth:`~momoko.Pool.execute`, but are possible -with :py:meth:`~momoko.Pool.callproc`, :py:meth:`~momoko.Pool.transaction` and -:py:meth:`~momoko.Pool.mogrify` too. - - -.. _Psycopg2 documentation: http://initd.org/psycopg/docs/cursor.html -.. _tornado.gen: http://www.tornadoweb.org/documentation/gen.html -.. _fetchone: http://initd.org/psycopg/docs/cursor.html#cursor.fetchone -.. _fetchmany: http://initd.org/psycopg/docs/cursor.html#cursor.fetchmany -.. _fetchall: http://initd.org/psycopg/docs/cursor.html#cursor.fetchall -.. _Task: http://www.tornadoweb.org/documentation/gen.html#tornado.gen.Task -.. _Wait: http://www.tornadoweb.org/documentation/gen.html#tornado.gen.Wait -.. _WaitAll: http://www.tornadoweb.org/documentation/gen.html#tornado.gen.WaitAll -.. _exceptions: http://initd.org/psycopg/docs/module.html#exceptions