idalton avatar idalton committed c559df4

Fix punctuation, formatting, and style errors

- Some code was broken over multiple lines that should be on one, or
wrapped onto one line that should be on several.

- Indent subsequent lines of list items, so they are parsed as part of
the list item.

- Add some commas, change some commas to semicolons.

- Add a note about a fragment sentence, that seems to have been munged
by accident, since the first commit, so it's unrecoverable.

Comments (0)

Files changed (1)

DatabasesAndJython.rst

 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 
-In this chapter, we will look at zxJDBC package, which is a
+In this chapter, we will look at the zxJDBC package, which is a
 standard part of Jython since version 2.1 and complies with the
 Python 2.0 DBI standard. zxJDBC can be an appropriate choice for
 simple one-off scripts where database portability is not a concern.
 PostgreSQL, SQLite, SQL Server, and Sybase. And drivers are also
 available for non-relational and specialized databases, too.
 
-However, unlike JDBC, zxJDBC when used in the simplest way
+However, unlike JDBC, zxJDBC, when used in the simplest way
 possible, blocks SQL injection attacks, minimizes overhead, and
 avoids resource exhaustion. In addition, zxJDBC defaults to using a
 transactional model (when available), instead of autocommit.
     # Windows
     set CLASSPATH=<PATH TO JDBC>\\postgresql-x.x.jdbc4.jar;%CLASSPATH%
     # OS X
-    export CLASSPATH=<PATH TO
-    JDBC>/postgresql-x.x.jdbc4.jar:$CLASSPATH
+    export CLASSPATH=<PATH TO JDBC>/postgresql-x.x.jdbc4.jar:$CLASSPATH
 
 
 
 - Create a query or statement.
 - Obtain results of query or statement.
 - If using a query, obtain results in a cursor and iterate over data
-to perform tasks.
+  to perform tasks.
 - Close cursor.
 - Close connection (If not using the with_statement syntax in
-versions of Jython prior to 2.5.1).
+  versions of Jython prior to 2.5.1).
 
 Over the next few sections, we’ll take a look at each of these
 steps and how zxJDBC can make them easier than using JDBC
 using them. There are two ways to create database connections:
 
 - *Direct creation.* Standalone code, such as a script, will directly
-create a connection.
+  create a connection.
 
 - *JNDI.* Code managed by a container should use JNDI for connection
-creation. Such containers include GlassFish, JBoss, Tomcat,
-WebLogic, and WebSphere. Normally connections are pooled when run
-in this context and are also associated with a given security
-context.
+  creation. Such containers include GlassFish, JBoss, Tomcat,
+  WebLogic, and WebSphere. Normally connections are pooled when run
+  in this context and are also associated with a given security
+  context.
 
 The following is an example of the best way to create a database
 connection outside of a managed container using Jython 2.5.1. It is
 see the note that follows to find out how to implement this
 functionality in versions prior to 2.5.1. Another thing to notice
 is that in order to connect, we must use a JDBC url which conforms
-to the standards of a given database in this case, PostgreSQL.
+to the standards of a given database; in this case, PostgreSQL.
 
 *Listing 12-2*
 ::
     *with_statement* syntax is not available. For this reason, we must
     work directly with the connection (i.e. close it when finished).
     Take a look at the following code for an example of using zxJDBC
-    connections without the with_statement functionality.
+    connections without the *with_statement* functionality.
     
     ::
         
-        from __future__ import with_statement from
-        com.ziclix.python.sql import zxJDBC
+        from __future__ import with_statement
+        from com.ziclix.python.sql import zxJDBC
         
-        # for example jdbc_url = "jdbc:postgresql:test" username =
-        "postgres" password = "jython25" driver = "org.postgresql.Driver"
+        # for example
+        jdbc_url = "jdbc:postgresql:test"
+        username = "postgres"
+        password = "jython25"
+        driver = "org.postgresql.Driver"
         
         conn = zxJDBC.connect(jdbc_url, username, password, driver)
-        do_something(conn) # Be sure to clean up by closing the connection
-        (and cursor) conn.close()
+        do_something(conn) # Be sure to clean up by closing the connection (and cursor)
+        conn.close()
 
 The *with* statement ensures that the connection is immediately
-closed following the work. The alternative is to use finally to
+closed following the work. The alternative is to use *finally* to
 perform the close. Using the latter technique allows for more
 tightly controlled exception handling technique, but also adds a
 considerable amount of code. As noted previously, the with
 
 .. note::
     
-    Connection pools help ensure for more robust operation,
+    Connection pools help ensure more robust operation,
     by providing for reuse of connections while ensuring the
     connections are in fact valid. Often naive code will hold a
     connection for a very long time, to avoid the overhead of creating
 ::
     
     try:
-        # Obtain a connection that is not using auto-commit (default for
-        zxJDBC)
+        # Obtain a connection that is not using auto-commit (default for zxJDBC)
         conn = zxJDBC.connect(jdbc_url, username, password, driver)
         # Perform all work on connection
         do_something(conn)
     
     factory = "com.sun.jndi.fscontext.RefFSContextFactory"
     db = zxJDBC.lookup('jdbc/postgresDS',
-        INITIAL_CONTEXT_FACTORY=factory)
+                       INITIAL_CONTEXT_FACTORY=factory)
 
 This example assumes that the datasource defined in the container
 is named “jdbc/postgresDS,” and it uses the Sun FileSystem JNDI
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 As you’ve seen previously, it is quite easy to initiate a query
-against a given cursor. Simply provide a *sel**ect* statement in
+against a given cursor. Simply provide a *select* statement in
 string format as a parameter to the cursor *execute()* or
 *executemany()* methods and then use one of the *fetch* methods to
 iterate over the returned results. In the following examples we
     >>> cursor.description
     [('country', 1111, 2147483647, None, None, None, 2), ('region', 12, 2147483647, None, None, None, 0)]
 
-Creating a cursor using the with_statement syntax is easy, please
+Creating a cursor using the *with_statement*syntax is easy, please
 take a look at the following example for use with Jython 2.5.1 and
 beyond.
 
     >>> # work with cursor
 
 As you can see, queries are easy to work with using cursors. In the
-previous example, we used the *f**etchall()* method to retrieve all
+previous example, we used the *fetchall()* method to retrieve all
 of the results of the query. However, there are other options
 available for cases where all results are not desired including the
 *fetchone()* and *fetchmany()* options. Sometimes it is best to
 is a technique that is used to pass undesirable SQL code into an
 application in such a way that it alters a query to perform
 unwanted tasks. If the user has the ability to type free text into
-a textfield and have that text passed into a string concatenated
+a text field and have that text passed into a string-concatenated
 query, it is best to perform some other means of filtering to
 ensure certain keywords or commenting symbols are not contained in
 the value. A better way of getting around these issues is to make
     
     ...
     # Passing a string value into the query
-    qry = "select continent from country where name = ?"
+    >>> qry = "select continent from country where name = ?"
     >>> cursor.executemany(qry,['Austria'])
     >>> cursor.fetchall()
     [(u'Europe',)]
 -------------------------------------------------------
 
 Any application that will manipulate data contained in a RDBMS must
-be able to issue Data Manipulation Language (DML). Of course, DML
+be able to speak Data Manipulation Language (DML). Of course, DML
 consists of issuing statements such as INSERT, UPDATE, and DELETE.
-. .the basics of CRUD programming. zxJDBC makes it rather easy to
+**FIXME: fragment sentence.**
+the basics of CRUD programming. zxJDBC makes it rather easy to
 use DML in a standard cursor object. When doing so, the cursor will
 return a value to provide information about the result. A standard
 DML transaction in JDBC uses a prepared statement with the cursor
 *Listing 12-19. Using DML*
 ::
     
-    >>>
     # Create a table named PYTHON_IMPLEMENTATIONS
     >>> stmt = "create table python_implementations (id integer, python_implementation varchar, current_version varchar)"
     >>> result = cursor.execute(stmt)
 that live inside the database. Most often these procedures are
 written in a SQL procedural language such as Oracle’s PL/SQL or
 PostgreSQL’s PL/pgSQL. Writing database procedures and using them
-with external applications such written in Python, Java, or the
+with external applications written in Python, Java, or the
 like makes lots of sense, because procedures are often the easiest
 way to work with data. Not only are they running close to the metal
 since they are in the database, but they also perform much faster
-than say a Jython application that needs to connect and close
+than, say, a Jython application that needs to connect and close
 connections on the database. Since a procedure lives within the
 database, there is no performance penalty due to connections being
 made.
 Life Cycle
 ^^^^^^^^^^
 
-*public void preExecute(Statement stmt)**throws SQLException;*
+*public void preExecute(Statement stmt) throws SQLException;*
 
 A callback prior to each execution of the statement. If the
 statement is a PreparedStatement (created when parameters are sent
 Developer Support
 ^^^^^^^^^^^^^^^^^
 
-*public String getMetaDataName**(String name);*
+*public String getMetaDataName(String name);*
 
 A callback for determining the proper case of a name used in a
 DatabaseMetaData method, such as getTables(). This is particularly
 useful for Oracle which expects all names to be upper case.
 
-*public PyObject getRowId**(Statement stmt) throws SQLException;*
+*public PyObject getRowId(Statement stmt) throws SQLException;*
 
 A callback for returning the row id of the last insert statement.
 
 Binding Prepared Statements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*public Object getJDBCObject**(PyObject object, int type);*
+*public Object getJDBCObject(PyObject object, int type);*
 
 This method is called when a PreparedStatement is created through
 use of the execute method. When the parameters are being bound to
 the statement, the DataHandler gets a callback to map the type.
 *This is only called if type bindings are present.*
 
-*public Object getJDBCObject**(PyObject object);*
+*public Object getJDBCObject(PyObject object);*
 
 This method is called when no type bindings are present during the
 execution of a PreparedStatement.
 Building Results
 ^^^^^^^^^^^^^^^^
 
-*public PyObject ge**tPyObject(**ResultSet set, int col, int type);*
+*public PyObject getPyObject(ResultSet set, int col, int type);*
 
 This method is called upon fetching data from the database. Given
 the JDBC type, return the appropriate PyObject subclass from the
 ::
     
     >>> cursor.datahandler = PyHandler(cursor.datahandler)
-    Inside DataHandler
+    # Inside DataHandler
     >>> cursor.execute("insert into test values (?,?)", [1,2])
-    calling pre-execute
+    # calling pre-execute
 
 History
 -------
 access via Jython, there are many other solutions available. Many
 developers today are choosing to use ORM (Object Relational
 Mapping) solutions to work with the database. This section is not
-an introduction to ORM, we assume that you are at least a bit
+an introduction to ORM; we assume that you are at least a bit
 familiar with the topic. Furthermore, the ORM solutions that are
 about to be discussed have an enormous amount of very good
 documentation already available either on the web or in book
 used ORM solutions for the Python programming language. It has been
 around long enough that its maturity and stability make it a great
 contender for use in your applications. It is simple to setup, and
-easy-to-use for both new databases and legacy databases alike. You
+easy to use for both new databases and legacy databases alike. You
 can download and install SqlAlchemy and begin using it in a very
 short amount of time. The syntax for using this solution is very
-straight forward, and as with other ORM technologies, working with
+straightforward, and as with other ORM technologies, working with
 database entities occurs via the use of a mapper that links a
 special Jython class to a particular table in the database. The
 overall result is that the application persists through the use of
     jython setup.py install
 
 Once you’ve completed this process, SqlAlchemy should be
-successfully installed into your jython Libsite-packages directory.
+successfully installed into your jython/Lib/site-packages directory.
 You can now access the SqlAlchemy modules from Jython, and you can
 open up your terminal and check to ensure that the install was a
-success by importing sqlalchemy and checking the version. See
+success by importing *sqlalchemy* and checking the version. See
 Listing 12-23.
 
 *Listing 12-23.*
     >>> import sqlalchemy
     >>> sqlalchemy.__version__
     '0.6beta1'
-    >>>
 
 After we’ve ensured that the installation was a success, it is time
 to begin working with SqlAlchemy via the terminal. However, we have
 to use zxJDBC, and we’ll be showing you some examples based upon
 zxoracle in the next sections. However, other dialects are in the
 works including SQL Server and MySQL. The bad news is that
-SqlAlchemy will not yet work with every database available, on the
+SqlAlchemy will not yet work with every database available; on the
 other hand, Oracle is a very good start and implementing a new
 dialect is not very difficult. You can find the zxoracle.py dialect
 included in the source for this book. Browse through it and you
 *Listing 12-25. Creating a Database Table*
 ::
     
-    >>>player = Table('player', metadata,
+    >>> player = Table('player', metadata,
     ... Column('id', Integer, primary_key=True),
     ... Column('first', String(50)),
     ... Column('last', String(50)),
 *Listing 12-30. Creating and Querying the Player Object*
 ::
     
-    #Import sqlalchemy module and zxoracle
+    # Import sqlalchemy module and zxoracle
     >>> import zxoracle
     >>> from sqlalchemy import create_engine
     >>> from sqlalchemy import Table, Column, String, Integer, MetaData, ForeignKey
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.