[Checkins] SVN: Sandbox/ulif/grokcore.startup/src/grokcore/startup/README.txt Update docs.
Uli Fouquet
uli at gnufix.de
Mon Feb 2 08:35:51 EST 2009
Log message for revision 95970:
Update docs.
Changed:
U Sandbox/ulif/grokcore.startup/src/grokcore/startup/README.txt
-=-
Modified: Sandbox/ulif/grokcore.startup/src/grokcore/startup/README.txt
===================================================================
--- Sandbox/ulif/grokcore.startup/src/grokcore/startup/README.txt 2009-02-02 13:34:48 UTC (rev 95969)
+++ Sandbox/ulif/grokcore.startup/src/grokcore/startup/README.txt 2009-02-02 13:35:51 UTC (rev 95970)
@@ -1,53 +1,271 @@
-grokcore.startup
-****************
+Detailed Description
+********************
-Single functions
-================
+Setting up Grok projects as ``paster`` served WSGI applications
+===============================================================
-application_factory(global_conf, **local_conf)
-----------------------------------------------
+The main target of this package is to provide support for enabling
+`Grok`_ applications to be run as `paster`_ served `WSGI`_
+applications. To make this working some configuration files have to be
+set up.
-`grokcore.startup` provides a function `application_factory` which
-delivers a `WSGIPublisherApplication` instance when called with an
-appropriate configuration.
+Setting up a project with ``grokproject``
+-----------------------------------------
-A call to this function is normally required as entry point in
-`setuptools`-driven paster environments.
+The most convenient way to setup a `Grok`_ project is using
+`grokproject`_. Once installed, you can a project like this::
-We have to create our own site definition file -- which will simply be
-empty -- to provide a minimal test::
+ $ grokproject Sample
- >>> import os, tempfile
- >>> temp_dir = tempfile.mkdtemp()
- >>> sitezcml = os.path.join(temp_dir, 'site.zcml')
- >>> open(sitezcml, 'w').write('<configure />')
+which will generate all configuration files for you.
-Furthermore we create a Zope configuration file, which is also quite
-plain::
+.. note:: Older versions of `grokproject`_ need an update
- >>> zope_conf = os.path.join(temp_dir, 'zope.conf')
- >>> open(zope_conf, 'wb').write('''
- ... site-definition %s
- ...
- ... <zodb>
- ... <mappingstorage />
- ... </zodb>
- ...
- ... <eventlog>
- ... <logfile>
- ... path STDOUT
- ... </logfile>
- ... </eventlog>
- ... ''' %sitezcml)
+ As older versions of `grokproject`_ do not support
+ `grokcore.startup`, you might want to update your existing
+ `grokproject`_ installation by running::
-Now we can call `application_factory` to get a WSGI application::
+ $ easy_install -U grokproject
- >>> from grokcore.startup import application_factory
- >>> app_factory = application_factory(dict(zope_conf = zope_conf))
- >>> app_factory
- <zope.app.wsgi.WSGIPublisherApplication object at 0x...>
-Clean up::
+Setting up a project manually
+-----------------------------
- >>> import shutil
- >>> shutil.rmtree(temp_dir)
+Before we can make use of ``grokcore.startup``, we have to setup
+several configuration files in the project root:
+
+* ``setup.py``
+
+* ``buildout.cfg`` (optional)
+
+* ``zope.conf`` (normally found in the ``etc/`` subdirectory of your
+ `Grok`_ project)
+
+* ``site.zcml`` (normally found in the ``etc/`` subdirectory of your
+ `Grok`_ project)
+
+* ``deploy.ini`` (or any other .ini-file; normally found in the
+ ``etc/`` subdirectory of your `Grok`_ project)
+
+
+When we want to setup a Zope instance as `paster`_ served `WSGI`_
+application, then we have to set a ``paste.app_factory`` entry point
+in ``setup.py``. A minimal setup could look like this::
+
+ # setup.py
+ from setuptools import setup, find_packages
+
+ setup(name='sampleproject',
+ version='0.1dev',
+ description="A sample project",
+ long_description="""Without a long description.""",
+ classifiers=[],
+ keywords="",
+ author="U.N.Owen",
+ author_email="",
+ url="",
+ license="",
+ package_dir={'': 'src'},
+ packages=find_packages('src'),
+ include_package_data=True,
+ zip_safe=False,
+ install_requires=['setuptools',],
+ entry_points = """
+ [paste.app_factory]
+ main = grokcore.startup:application_factory
+ """,
+ )
+
+Here the `paste.app_factory` entry point pointing to
+`grokcore.startup:application_factory` is important.
+
+Furthermore we need at least a minimal ``buildout.cfg`` which enables
+`zc.buildout`_ to create the control scripts for our instance::
+
+ [buildout]
+ develop = .
+ parts = app
+
+ [app]
+ recipe = zc.recipe.egg
+ eggs = sampleproject
+ grokcore.startup
+ Paste
+ PasteScript
+ PasteDeploy
+
+Here an egg-entry for ``grokcore.startup`` **might** be important, if
+it is not required otherwise by your application. Projects generated
+by `grokproject`_ will automatically include such a dependency and
+upcoming versions of `Grok`_ will pull in ``grokcore.startup`` anyway,
+so that ``grokcore.startup`` would not be required in this list of
+eggs any more.
+
+Next we need ``site.zcml`` and ``zope.conf`` files to define the
+Zope instance. These configurations are completely independent from
+being served by `Paste`_ or not. If you are upgrading an old `Grok`_
+project, you can use ``site.zcml`` and ``zope.conf`` of those project
+as-is. You only have to take care of the maybe changed
+``site-definition`` entry in ``zope.conf`` (see below).
+
+The file ``site.zcml`` can be quite
+short, but for real projects you certainly want to have some useful
+content in here::
+
+ <configure />
+
+A short ``zope.conf`` file for use in tests could look like this::
+
+ site-definition site.zcml
+
+ <zodb>
+ <mappingstorage />
+ </zodb>
+
+ <eventlog>
+ <logfile>
+ path STDOUT
+ </logfile>
+ </eventlog>
+
+where the ``site-definition`` entry should point to the location of
+the file ``site.zcml``. In regular Grok projects those files are put
+into the ``etc/`` subdirectory of your project root.
+
+Finally we have to provide a ``deploy.ini`` (or another .ini-file),
+which tells paster where to find the pieces. This is also put into the
+``etc/`` subdirectory of your project root in regular Grok projects
+created by `grokproject`_::
+
+ [app:main]
+ use = egg:sampleproject
+
+ [server:main]
+ use = egg:Paste#http
+ host = 127.0.0.1
+ port = 8080
+
+ [DEFAULT]
+ zope_conf = %(here)s/zope.conf
+
+
+
+API Documentation
+=================
+
+``application_factory(global_conf, **local_conf)``
+--------------------------------------------------
+
+ ``grokcore.startup`` provides a function ``application_factory``
+ which delivers a `WSGIPublisherApplication`_ instance when called
+ with an appropriate configuration. See the `zope.app.wsgi
+ documentation
+ <http://apidoc.zope.org/++apidoc++/Code/zope/app/wsgi/README.txt/index.html>`_
+ to learn more about Zope objects supporting `WSGI`_.
+
+ A call to this function is normally required as entry point in
+ `setuptools`_-driven `paster`_ environments (see
+ http://pythonpaste.org/deploy/#paste-app-factory).
+
+ We have to create our own site definition file -- which will simply
+ be empty -- to provide a minimal test::
+
+ >>> import os, tempfile
+ >>> temp_dir = tempfile.mkdtemp()
+ >>> sitezcml = os.path.join(temp_dir, 'site.zcml')
+ >>> open(sitezcml, 'w').write('<configure />')
+
+ Furthermore we create a Zope configuration file, which is also quite
+ plain::
+
+ >>> zope_conf = os.path.join(temp_dir, 'zope.conf')
+ >>> open(zope_conf, 'wb').write('''
+ ... site-definition %s
+ ...
+ ... <zodb>
+ ... <mappingstorage />
+ ... </zodb>
+ ...
+ ... <eventlog>
+ ... <logfile>
+ ... path STDOUT
+ ... </logfile>
+ ... </eventlog>
+ ... ''' %sitezcml)
+
+ Now we can call ``application_factory`` to get a WSGI application::
+
+ >>> from grokcore.startup import application_factory
+ >>> app_factory = application_factory(dict(zope_conf = zope_conf))
+ >>> app_factory
+ <zope.app.wsgi.WSGIPublisherApplication object at 0x...>
+
+ Clean up::
+
+ >>> import shutil
+ >>> shutil.rmtree(temp_dir)
+
+Update Instructions
+*******************
+
+If you want to update an existing Grok project to make use of
+``grokcore.startup``, then there are several possibilites depending on
+what version of `grokproject_` you used to create the project.
+
+First you have to make sure, that ``grokcore.startup`` is installed
+locally and loaded on startup. This can be done by adding::
+
+ grokcore.startup
+
+to the list of requirements of your project in ``setup.py``.
+
+Upcoming versions of Grok (> 1.0a1) will require ``grokcore.startup``
+anyway, so that if you use `grok`_ > 1.0.a1 then you can skip this
+step.
+
+Projects with a ``startup.py`` file
+===================================
+
+If you can find a file ``startup.py`` in your Grok application
+sources, then you can do an update in two steps:
+
+1) In your project's ``setup.py`` modify the lines reading::
+
+ [paste.app_factory]
+ main = <myapplication>.startup:application_factory
+
+ to::
+
+ [paste.app_factory]
+ main = grokcore.startup:application_factory
+
+ and rerun buildout::
+
+ $ bin/buildout
+
+2) Remove ``startup.py`` from your application sources.
+
+
+Projects without a ``startup.py`` file
+======================================
+
+Here the situation is more tricky, because you have to generate all
+the configuration files needed py `Paste`_.
+
+You can setup those files manually following the instructions above or
+simply create a new grokproject with the same name and copy all source
+files over to the new project directory.
+
+Afterwards you should also rerun buildout to make all changes active::
+
+ $ bin/buildout
+
+
+.. _grok: http://pypi.python.org/pypi/grok
+.. _grokproject: http://pypi.python.org/pypi/grokproject
+.. _Paste: http://pythonpaste.org/
+.. _paster: Paste_
+.. _setuptools: http://pypi.python.org/pypi/setuptools
+.. _WSGI: http://www.wsgi.org/wsgi/
+.. _WSGIPublisherApplication: http://apidoc.zope.org/++apidoc++/Code/zope/app/wsgi/WSGIPublisherApplication/index.html
+.. _zc.buildout: http://pypi.python.org/pypi/zc.buildout
More information about the Checkins
mailing list