[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