==============
SQLAlchemy 0.3
==============

SQLAlchemy 0.3 for Fedora is being provided so that apps written for
TurboGears 1.0.x and SQLAlchemy 0.3 can continue to run.  It relies on eggs
to enable multiple versions to be installed.

If you are using SQLAlchemy via TurboGears, everything should work out of the
box for new projects quickstarted with the Fedora 8 packages.  Older projects
will need a small adjustment to run correctly.  In your project's start-APP.py
script you need to change the commands that import TurboGears from this::

  import pkg_resources
  pkg_resources.require('TurboGears')

to this::

  __requires__ = 'TurboGears'
  import pkg_resources

with the packages provided by Fedora 8+.

If you are using SQLAlchemy via your own code and absolutely must use the 0.3
version rather than 0.4, you will need to do one of the following to make it
work in your code:

1) Manually change your python path to place the egg directory before
   site-packages.  Note that if you do it this way you will either have to
   change your code whenever a new version comes out (for instance, if a
   bugfix release, SQLAlchemy-0.3.11, is released.)  The codewould look
   something like this::

     import sys, os, distutils
     compatSAPath = os.path.join(
            distutils.sysconfig.get_python_lib(), 'SQLAlchemy-0.3.10-py2.5.egg')
     sys.path.insert(0, compatSAPath)
     import sqlalchemy

2) Use setuptools and entrypoints. To do this you have a function in a python
   module that is your main function.  You define this as an entry point in
   setup.py.  For instance, if you wanted your script to be called
   "nifty-foo" and the entry point was the main() function in the module
   nifty.foo, you would use this in setup.py::

     # List the versions of SQLAlhcemy that will work
     install_requires = [
        'SQLAlchemy >= 0.3,<0.4alpha'
        ]
     # Add the information necessary to create the script that requires
     # the SQLAlchemy version
     setup (
        name='Nifty',
        version='1.0',
        entry_points = '''
          [console_scripts]
          nifty-foo = nifty.foo:main
        ''',
     [...]

   When you use setup.py to install this script it will create a script that
   looks like this::
      
      #!/usr/bin/python
      __requires__ = 'Nifty==1.0'
      import sys
      from pkg_resources import load_entry_point

      sys.exit(
        load_entry_point('Nifty==1.0', 'console_scripts', 'nifty-foo')()
      )

   The script in turn, references the egg metadata for your module which
   lists the dependency from Nifty to SQLAlchemy>=0.3, < 0.4alpha.

Note that although there may be other methods of making this work in some
circumstances, these are the only methods that the setuptools author and
we are able to say will work in all circumstances in this environment.  Other
methods may not work reliably in some versions of setuptools.