Commits

Mike Bayer committed 229c5f3

formatting

Comments (0)

Files changed (4)

 
 This package contains:
 
-* student handout, buildable as HTML or PDF via Sphinx, in handout/
+* student handout, buildable as HTML, PDF, or other formats via Sphinx_	, in ``handout/``
 
-* Software installs in sw/
+* Interactive Python "slide runner" application, which
+  is essentially a customized `REPL <http://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop>`_
+  that can step through segments of a Python script
 
-* Interactive Python slide runner
+* Demonstration Python scripts which illustrate various features
+  of SQLAlchemy; these scripts are formatted to work best with the
+  "slide runner" application, though can be run directly as
+  well.
+
+* Packages required to run the interactive slide runner and the
+  example SQLAlchemy programs in ``sw/``, including SQLAlchemy
+  itself.
 
 
 Prerequisites
 A minimum version of Python 2.6 is recommended;
 Python 2.7, 3.1, 3.2 or 3.3 are also fine.
 
-For database access, the tutorials use the SQLite database by default,
+For database access, the tutorials use the SQLite_ database by default,
 which is included as part of the Python standard library.
 
-If your Python was custom built and does not include SQLite, it
-can be added in by rebuilding with the SQLite libraries available or
+If your Python was custom built and does not include SQLite_, it
+can be added in by rebuilding with the SQLite_ libraries available or
 by installing pysqlite.
 
-To build the documentation, the Sphinx documentation system and
+To build the documentation, the Sphinx_ documentation system and
 its prerequistites must be installed.
 
-To install the slide runner and dependencies, virtualenv is strongly
-recommended, available at http://pypi.python.org/pypi/virtualenv.   Students are encouraged to gain rudimental familiarity with virtualenv prior to the class.
+To install the slide runner and dependencies, virtualenv_ is strongly
+recommended, available at http://pypi.python.org/pypi/virtualenv.   Students are encouraged to gain rudimental familiarity with virtualenv_ prior to the class.  By using virtualenv, there will
+be no dependency between the libraries used to run the local applications here
+versus those libraries that may be installed with the system-wide Python.
+For example, if students have old and broken versions of SQLAlchemy installed, they will
+be left untouched by this process, but will not interfere with the usage
+of the local application, which will be using the latest and greatest.
 
 Obtaining the Package
 ======================
 Building the Documentation Handout
 ==================================
 
-The documentation can be built using standard Sphinx techniques.
+The documentation can be built using standard Sphinx_ techniques.
 
 To build HTML on Linux / OSX::
 
 	cd handout
 	make html
 
-The documentation can also be built as PDF or any other format supported by Sphinx.   See the Sphinx documentation at http://sphinx-doc.org/ for further documentation.
+The documentation can also be built as PDF or any other format supported by Sphinx_.   See the Sphinx_ documentation at http://sphinx-doc.org/ for further usage and configuration information.
 
 Installing the Slide Environment
 ================================
 The slide environment features a working SQLAlchemy environment as well as several tutorial-style Python scripts which illustrate usage patterns.   The slides are best run using a specialized "slide runner" application, which we
 will be running as part of the class.
 
-To make the installation as easy as possible, as well as to minimize the need for network access, most of the non-standard prerequisite libraries are included here in the sw/ directory.    However, the system is best run using a Python virtualenv environment, so that system-wide installation is not required.
+To make the installation as easy as possible, as well as to minimize the need for network access, source installation
+packages for the non-standard prerequisite libraries are included here in the ``sw/`` directory.    However, the system is best run using a Python virtualenv_ environment, so that system-wide installation is not required.
 
 Steps to install:
 
-1. Create a local virtualenv::
+1. Ensure that virtualenv_ is installed, preferably systemwide.
+
+2. Create a local virtualenv_::
 
-	$ virtualenv --no-site-packages .venv
+	     $ virtualenv --no-site-packages .venv
 
-This will create a directory ``.venv/bin`` which is where scripts are run.  On Windows, the directory is called ``.venv/Scripts``.
+   This will create a directory ``.venv/bin`` which is where scripts are run.  On Windows, the directory is called ``.venv/Scripts``.
 
-2. Run the ``install.py`` script, which will install packages from the ``sw/``
-   directory into the local virtualenv.  On Linux/OSX::
+3. Run the ``install.py`` script, which will install packages from the ``sw/``
+   directory into the local virtualenv_.  On Linux/OSX::
 
-	$ .venv/bin/python install.py
+	     $ .venv/bin/python install.py
 
    On Windows::
 
-	$ .venv\Scripts\python.exe install.py
+	     $ .venv\Scripts\python.exe install.py
 
-3. A particular tutorial script can be run using the ``sliderepl`` program.
+4. A particular tutorial script can be run using the ``sliderepl`` program.
    On Linux OSX::
 
-	$ .venv/bin/sliderepl 01_engine_usage.py
+	     $ .venv/bin/sliderepl 01_engine_usage.py
 
    On Windows::
 
-	$ .venv\Scripts\sliderepl.exe 01_engine_usage.py
+	     $ .venv\Scripts\sliderepl.exe 01_engine_usage.py
+
+.. _Sphinx: http://sphinx-doc.org/
+
+.. _SQLite: http://sqlite.org/
+
+.. _virtualenv: http://pypi.python.org/pypi/virtualenv

handout/source/glossary.rst

         .. sourcecode:: sql
 
             SELECT email_address.email FROM email_address
-            WHERE email_address.user_account_id=(SELECT id FROM user_account WHERE name='jack')
+            WHERE email_address.user_account_id=
+                (SELECT id FROM user_account WHERE name='jack')
 
                 email
             ---------------
 
             SELECT name FROM user_account
              WHERE EXISTS
-             (SELECT * FROM email_address WHERE email_address.user_account_id=user_account.id)
+             (SELECT * FROM email_address
+                WHERE email_address.user_account_id=user_account.id)
 
              name
             -------
                 bind = self.get_bind(mapper, clause=clause, **kw)
               File "/Users/classic/dev/sqlalchemy/lib/sqlalchemy/orm/session.py", line 1083, in get_bind
                 ', '.join(context)))
-            sqlalchemy.exc.UnboundExecutionError: Could not locate a bind configured on SQL expression or this Session
+            sqlalchemy.exc.UnboundExecutionError: Could not
+                locate a bind configured on SQL expression or this Session
 
         This is because we haven't given this :class:`~sqlalchemy.orm.session.Session`
         a source of connectivity.   We can make one using

handout/source/relational.rst

    retrieve rows from is resolved; in this case, we start with the set of all rows
    contained in the ``employee`` table:
 
-.. sourcecode:: sql
+    .. sourcecode:: sql
 
-        ... FROM employee ...
+            ... FROM employee ...
 
-        emp_id    emp_name     dep_id
-        -------+------------+----------
-          1    |   wally    |     1
-          2    |   dilbert  |     1
-          3    |   jack     |     2
-          4    |   ed       |     3
-          5    |   wendy    |     1
-          6    |   dogbert  |     4
-          7    |   boss     |     3
+            emp_id    emp_name     dep_id
+            -------+------------+----------
+              1    |   wally    |     1
+              2    |   dilbert  |     1
+              3    |   jack     |     2
+              4    |   ed       |     3
+              5    |   wendy    |     1
+              6    |   dogbert  |     4
+              7    |   boss     |     3
 
 2. For the set of all rows in the ``employee`` table, each row is tested against the
    criteria specified in the ``WHERE`` clause.  Only those rows which evaluate to "true"
    based on this expression are returned.  We now have a subset of rows retrieved
    from the ``employee`` table:
 
-.. sourcecode:: sql
+    .. sourcecode:: sql
 
-        ... WHERE dep_id=1 OR dep_id=3 OR dep_id=4 ...
+            ... WHERE dep_id=1 OR dep_id=3 OR dep_id=4 ...
 
-        emp_id    emp_name     dep_id
-        -------+------------+----------
-          1    |   wally    |     1
-          2    |   dilbert  |     1
-          4    |   ed       |     3
-          5    |   wendy    |     1
-          6    |   dogbert  |     4
-          7    |   boss     |     3
+            emp_id    emp_name     dep_id
+            -------+------------+----------
+              1    |   wally    |     1
+              2    |   dilbert  |     1
+              4    |   ed       |     3
+              5    |   wendy    |     1
+              6    |   dogbert  |     4
+              7    |   boss     |     3
 
 3. With the target set of rows assembled, ``GROUP BY`` then organizes the rows into groups,
    based on the criterion given.  Here we illustrate an "intermediary" result set which
    we would not actually see as a result, but instead indicates the
    data that's to be passed on to the next step:
 
-.. sourcecode:: sql
+    .. sourcecode:: sql
 
-        ... GROUP BY dep_id ...
+            ... GROUP BY dep_id ...
 
-         "group"    emp_id    emp_name     dep_id
-        ----------+---------+------------+---------
-        dep_id=1  |    1    |   wally    |     1
-                  |    2    |   dilbert  |     1
-                  |    5    |   wendy    |     1
-        ----------+---------+------------+---------
-        dep_id=3  |    4    |   ed       |     3
-                  |    7    |   boss     |     3
-        ----------+---------+------------+---------
-        dep_id=4  |    6    |   dogbert  |     4
+             "group"    emp_id    emp_name     dep_id
+            ----------+---------+------------+---------
+            dep_id=1  |    1    |   wally    |     1
+                      |    2    |   dilbert  |     1
+                      |    5    |   wendy    |     1
+            ----------+---------+------------+---------
+            dep_id=3  |    4    |   ed       |     3
+                      |    7    |   boss     |     3
+            ----------+---------+------------+---------
+            dep_id=4  |    6    |   dogbert  |     4
 
 4. Aggregate functions are now applied to each group.   We've passed
    emp_id to the ``count()`` function, which means for group "1" it will
    column expression here.  Below, we observe that the "emp_id" and
    "emp_name" columns go away, as we've aggregated on the count:
 
-.. sourcecode:: sql
+    .. sourcecode:: sql
 
-        ... count(emp_id) AS emp_count ...
+            ... count(emp_id) AS emp_count ...
 
-          emp_count     dep_id
-        ------------+-----------
-             3      |    1
-        ------------+-----------
-             2      |    3
-        ------------+-----------
-             1      |    4
+              emp_count     dep_id
+            ------------+-----------
+                 3      |    1
+            ------------+-----------
+                 2      |    3
+            ------------+-----------
+                 1      |    4
 
 5. Almost through all of our keywords, ``HAVING`` takes effect once we have the aggregations,
    and acts like a ``WHERE`` clause for aggregate values.   In our statement, it filters
    out groups that don't have more than one member:
 
-.. sourcecode:: sql
+    .. sourcecode:: sql
 
-        ... HAVING emp_count > 1 ...
+            ... HAVING emp_count > 1 ...
 
-          emp_count     dep_id
-        ------------+-----------
-             3      |    1
-        ------------+-----------
-             2      |    3
+              emp_count     dep_id
+            ------------+-----------
+                 3      |    1
+            ------------+-----------
+                 2      |    3
 
 
 6. Finally, ``ORDER BY`` is applied last.   It's important to remember in SQL that
    our data are done before any ordering is applied, and only right before
    the final results are returned to us are they ordered:
 
-.. sourcecode:: sql
+    .. sourcecode:: sql
 
-        ... ORDER BY emp_count, dep_id
+            ... ORDER BY emp_count, dep_id
 
-          emp_count     dep_id
-        ------------+-----------
-             2      |    3
-        ------------+-----------
-             3      |    1
+              emp_count     dep_id
+            ------------+-----------
+                 2      |    3
+            ------------+-----------
+                 3      |    1
 
 .. _acid_model:
 

handout/source/setup.rst

 
 2. Create a local virtualenv_::
 
-	$ virtualenv --no-site-packages .venv
+	     $ virtualenv --no-site-packages .venv
 
-This will create a directory ``.venv/bin`` which is where scripts are run.  On Windows, the directory is called ``.venv/Scripts``.
+   This will create a directory ``.venv/bin`` which is where scripts are run.  On Windows, the directory is called ``.venv/Scripts``.
 
 3. Run the ``install.py`` script, which will install packages from the ``sw/``
    directory into the local virtualenv_.  On Linux/OSX::
 
-	$ .venv/bin/python install.py
+	     $ .venv/bin/python install.py
 
    On Windows::
 
-	$ .venv\Scripts\python.exe install.py
+	     $ .venv\Scripts\python.exe install.py
 
 4. A particular tutorial script can be run using the ``sliderepl`` program.
    On Linux OSX::
 
-	$ .venv/bin/sliderepl 01_engine_usage.py
+	     $ .venv/bin/sliderepl 01_engine_usage.py
 
    On Windows::
 
-	$ .venv\Scripts\sliderepl.exe 01_engine_usage.py
-
+	     $ .venv\Scripts\sliderepl.exe 01_engine_usage.py
 
 .. _Sphinx: http://sphinx-doc.org/