Commits  committed 54d39d0

Update documentation.

  • Participants
  • Parent commits 9915817
  • Branches default

Comments (0)

Files changed (7)

File BUGS.txt

-* None. :)
-* None. :)
 dev   (unreleased)
+1.0 (2011-12-25)
+- Add ``set_base()`` function and unit test.
+- Change all remaining references to pyramid_sqla to sqlahelper.
+- Delete demo application, which was for an old version of Pyramid.
 1.0b1 (2011-03-11)

File docs/bugs.rst

-Bugs and TODO
-.. include:: ../BUGS.txt

File docs/

 # -*- coding: utf-8 -*-
-# pyramid_sqla documentation build configuration file, created by
+# sqlahelper documentation build configuration file, created by
 # sphinx-quickstart on Tue Dec 21 15:59:18 2010.
 # This file is execfile()d with the current directory set to its containing dir.
 # The short X.Y version.
 version = '1.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0b1'
+release = '1.0'
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #html_additional_pages = {}
 # If false, no module index is generated.
-#html_use_modindex = True
+html_use_modindex = False
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = False
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
 #html_file_suffix = ''
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'pyramid_sqladoc'
+htmlhelp_basename = 'sqlahelperdoc'
 # -- Options for LaTeX output --------------------------------------------------
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'pyramid_sqla.tex', u'pyramid\\_sqla Documentation',
+  ('index', 'sqlahelper.tex', u'SQLAHelper Documentation',
    u'Mike Orr', 'manual'),
 #latex_appendices = []
 # If false, no module index is generated.
-#latex_use_modindex = True
+latex_use_modindex = False

File docs/index.rst

-:Version: 1.0b1, released 2010-03-11
+:Version: 1.0, released 2011-12-25
 :Source: (Mercurial)
 **SQLAHeler** is a small library for SQLAlchemy_ web applications. It acts as a
 container for the application's contextual session, engines, and declarative
-base. This avoids circular dependencies or the need for a 'meta' module if your
-model is split across multiple modules. SQLAHelper does not try to hide the
-underlying SQLAlchemy objects; it merely provides a way to organize them and
-some convenience functions for initializing them.
+base. This avoids circular dependencies between the application's model
+modules, and allows cooperating third-party libraries to use the application's
+session, base, and transaction. SQLAHelper does not try to hide or disguise the
+underlying SQLAlchemy objects; it merely provides a way to organize them.
-The contextual session can be used with transaction managers (it's initialized
-with the ZopeTransactionExtension, as TurboGears has long done). A transaction
-manager provides automatic commit at the end of request processing, or rollback
-if an exception or HTTP error status occurred. SQLAHelper does not include any
-transaction managers, but it's known to work with repoze.tm2_, which is
-middleware and should work with any WSGI framework, and pyramid_tm_ which is
-specific to Pyramid.
+The contextual session is initialized with the popular
+ZopeTransactionExtension, which allows it to work with transaction managers
+like pyramid_tm_ and repoze.tm2_. A transaction manager provides automatic
+commit at the end of request processing, or rollback if an exception is raised
+or HTTP error status occurs. Some transaction managers can commit both SQL and
+non-SQL actions in one step. SQLAHelper does not include a transaction manager,
+but it works with the most common ones.
-Version 1.0b1 is a public beta test before the final release. We want to try it
-in real applications before making it final.
-It's currently tested on Python 2.6/Linux but should
-work on 2.5 and other platforms. A set of unit tests is included.
+It's currently tested on Python 2.7/Linux but should work on other
+platforms. A set of unit tests is included.
 .. _SQLAlchemy:
 .. _Pyramid:
-   bugs
-Indices and tables
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

File docs/release.txt

 Todo at release
 - Update version number in, docs/, and docs/index.rst
+- Update release date in CHANGES.txt and docs/index.rst

File docs/usage.rst

 Install SQLAHelper like any Python package, using either "pip install
 SQLAHelper" or "easy_install SQLAHelper". To check out the development
-repository: "hg clone". 
+repository: "hg clone SQLAHelper". 
 SQLAlchemy vocabulary
-We can't explain all the concepts needed to use SQLAlchemy here, but a few
-terms are critical for understanding SQLAHelper. To learn how to use
-SQLAlchemy, see the excellent and detailed SQLAlchemy manual.
+These are a few SQLAlchemy terms which are critical for understanding
 An **engine** is a SQLAlchemy object that knows how to connect to a certain
 database. All SQLAlchemy applications have at least one engine.
 with HTTP sessions despite the identical name. A session is required when using
 the ORM, but is not needed for lower-level SQL access.
-A **contextual session** (often called a **Session** with a capital S) is a
-threadlocal session proxy. This means it can be a global variable in
-multithreaded web servers (which may be processing different requests
-simultaneously in different threads). Externally it looks like a session;
-internally it maintains a separate session for each thread.  (SQLAlchemy
-manual: `contextual session`_.)
+A **contextual session** (often called a **Session** with a capital S, or a
+**DBSession**) is a threadlocal session proxy. It acts like a session and has
+the same API, but internally it maintains a separate session for each thread.
+This allows it to be a golabl variable in multithreaded web applications.
+(SQLAlchemy manual: `contextual session`_.)
-A **declarative base** is a class that serves as the superclass of your ORM
-classes. ORM classes correspond to database tables. SQLAlchemy has two syntaxes
-for defining tables and ORM classes. A declarative base is needed only when
-using the "Declarative" syntax.
+A **declarative base** (often called a **Base**) is a common superclass for all
+your ORM classes. An ORM class represents one database table, and is associated
+with a separate table object. An instance of the class represents one record in
+the table.
 Most SQLAlchemy applications nowadays use all of these.
 2. In models or views or wherever you need them, access the contextual session,
    engines, and declarative base this way::
-        import pyramid_sqla
+        import sqlahelper
-        Session = pyramid_sqla.get_session()
-        engine = pyramid_sqla.get_dbengine()
-        Base = pyramid_sqla.get_base()
+        Session = sqlahelper.get_session()
+        engine = sqlahelper.get_dbengine()
+        Base = sqlahelper.get_base()
 It gets slightly more complex with multiple engines as you'll see below.
 .. autofunction:: get_base
+.. autofunction:: set_base
 .. autofunction:: reset
     # Initialize the default engine.
     default = sa.engine_from_config(settings, prefix="sqlalchemy.")
-    sqlalchelper.add_engine(default)
+    sqlahelper.add_engine(default)
     # Initialize the other engines.
     engine1 = sa.engine_from_config(settings, prefix="engine1.")
 mapper objects.
-Declarative base
-The library includes a declarative base for convenience, but some people may
-choose to define their own declarative base in their model instead. And there's
-one case where you *have* to create your own declarative base; namely, if you
-want to modify its constructor args. The ``cls`` argument is the most common:
-it specifies a superclass which all ORM object should inherit. This allows you
-to define class methods and other methods which are available in all your ORM
 .. _Engine Configuration:
 .. _contextual session: