[Checkins] SVN: grok/trunk/doc/ Updating the tutorial to reflect the newest Grok. Start to update the
Martijn Faassen
faassen at startifact.com
Mon Aug 31 10:40:13 EDT 2009
Log message for revision 103403:
Updating the tutorial to reflect the newest Grok. Start to update the
tutorial examples too (each with their own buildout now. Slower but
we share eggs now so not that much slower).
Changed:
A grok/trunk/doc/groktut/an_empty_grok_project/bootstrap.py
U grok/trunk/doc/groktut/an_empty_grok_project/buildout.cfg
A grok/trunk/doc/groktut/an_empty_grok_project/etc/
A grok/trunk/doc/groktut/an_empty_grok_project/etc/README.txt
A grok/trunk/doc/groktut/an_empty_grok_project/etc/debug.ini.in
A grok/trunk/doc/groktut/an_empty_grok_project/etc/deploy.ini.in
A grok/trunk/doc/groktut/an_empty_grok_project/etc/site.zcml.in
A grok/trunk/doc/groktut/an_empty_grok_project/etc/zdaemon.conf.in
A grok/trunk/doc/groktut/an_empty_grok_project/etc/zope.conf.in
U grok/trunk/doc/groktut/an_empty_grok_project/setup.py
U grok/trunk/doc/groktut/an_empty_grok_project/src/sample/__init__.py
A grok/trunk/doc/groktut/an_empty_grok_project/src/sample/app.txt
U grok/trunk/doc/groktut/an_empty_grok_project/src/sample/app_templates/index.pt
U grok/trunk/doc/groktut/an_empty_grok_project/src/sample/configure.zcml
A grok/trunk/doc/groktut/an_empty_grok_project/src/sample/ftesting.zcml
A grok/trunk/doc/groktut/an_empty_grok_project/src/sample/static/
A grok/trunk/doc/groktut/an_empty_grok_project/src/sample/static/README.txt
A grok/trunk/doc/groktut/an_empty_grok_project/src/sample/tests.py
A grok/trunk/doc/groktut/an_empty_grok_project/versions.cfg
U grok/trunk/doc/tutorial.rst
-=-
Added: grok/trunk/doc/groktut/an_empty_grok_project/bootstrap.py
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/bootstrap.py (rev 0)
+++ grok/trunk/doc/groktut/an_empty_grok_project/bootstrap.py 2009-08-31 14:40:12 UTC (rev 103403)
@@ -0,0 +1,84 @@
+##############################################################################
+#
+# Copyright (c) 2006 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Bootstrap a buildout-based project
+
+Simply run this script in a directory containing a buildout.cfg.
+The script accepts buildout command-line options, so you can
+use the -c option to specify an alternate configuration file.
+
+$Id: bootstrap.py 85041 2008-03-31 15:57:30Z andreasjung $
+"""
+
+import os, shutil, sys, tempfile, urllib2, logging
+
+def remove_old_logger_handlers():
+ # zc.buildout installs a new log stream on every call of
+ # main(). We remove any leftover handlers to avoid multiple output
+ # of same content (doubled lines etc.)
+ root_logger = logging.getLogger()
+ if 'zc.buildout' in root_logger.manager.loggerDict.keys():
+ logger = logging.getLogger('zc.buildout')
+ for handler in logger.handlers:
+ logger.removeHandler(handler)
+ return
+
+
+tmpeggs = tempfile.mkdtemp()
+
+try:
+ import pkg_resources
+except ImportError:
+ ez = {}
+ exec urllib2.urlopen('http://peak.telecommunity.com/dist/ez_setup.py'
+ ).read() in ez
+ ez['use_setuptools'](to_dir=tmpeggs, download_delay=0)
+
+ import pkg_resources
+
+if sys.platform == 'win32':
+ def quote(c):
+ if ' ' in c:
+ return '"%s"' % c # work around spawn lamosity on windows
+ else:
+ return c
+else:
+ def quote (c):
+ return c
+
+cmd = 'from setuptools.command.easy_install import main; main()'
+ws = pkg_resources.working_set
+assert os.spawnle(
+ os.P_WAIT, sys.executable, quote (sys.executable),
+ '-c', quote (cmd), '-mqNxd', quote (tmpeggs), 'zc.buildout',
+ dict(os.environ,
+ PYTHONPATH=
+ ws.find(pkg_resources.Requirement.parse('setuptools')).location
+ ),
+ ) == 0
+
+ws.add_entry(tmpeggs)
+ws.require('zc.buildout')
+import zc.buildout.buildout
+zc.buildout.buildout.main(sys.argv[1:] + ['bootstrap'])
+remove_old_logger_handlers()
+shutil.rmtree(tmpeggs)
+
+# grokproject specific addition to standard bootstrap.py:
+# Install eggbasket too. This should be verbose to give the user
+# information about what is happening, since this can take a while.
+zc.buildout.buildout.main(sys.argv[1:] + ['-v', 'install', 'eggbasket'])
+if sys.platform == 'win32':
+ print "Now you can run 'bin\buildout.exe'"
+else:
+ print "Now you can run 'bin/buildout'"
Modified: grok/trunk/doc/groktut/an_empty_grok_project/buildout.cfg
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/buildout.cfg 2009-08-31 14:16:22 UTC (rev 103402)
+++ grok/trunk/doc/groktut/an_empty_grok_project/buildout.cfg 2009-08-31 14:40:12 UTC (rev 103403)
@@ -1,3 +1,80 @@
[buildout]
-develop = . ../../..
-extends = ../buildout_tut.cfg
\ No newline at end of file
+develop = .
+parts = eggbasket app i18n test data log zpasswd
+ zope_conf site_zcml zdaemon_conf deploy_ini debug_ini
+newest = false
+find-links = http://download.zope.org/distribution/
+extends = versions.cfg
+# eggs will be installed in the default buildout location
+# (see .buildout/default.cfg in your home directory)
+# unless you specify an eggs-directory option here.
+
+versions = versions
+
+[app]
+recipe = zc.recipe.egg
+eggs = Sample
+ z3c.evalexception>=2.0
+ Paste
+ PasteScript
+ PasteDeploy
+interpreter = python-console
+
+[data]
+recipe = zc.recipe.filestorage
+
+[log]
+recipe = zc.recipe.filestorage
+
+[test]
+recipe = zc.recipe.testrunner
+eggs = Sample
+defaults = ['--tests-pattern', '^f?tests$', '-v']
+
+# this section named so that the i18n scripts are called bin/i18n...
+[i18n]
+recipe = z3c.recipe.i18n:i18n
+packages = sample
+eggs = sample
+domain = sample
+output = src/sample/locales
+zcml =
+
+# This section is named so that the zpasswd utility is
+# called `zpasswd`
+[zpasswd]
+recipe = z3c.recipe.dev:script
+eggs = Sample
+module = zope.app.server.zpasswd
+method = main
+
+[zope_conf]
+recipe = z3c.recipe.template
+input = etc/zope.conf.in
+output = ${buildout:parts-directory}/etc/zope.conf
+
+[site_zcml]
+recipe = z3c.recipe.template
+input = etc/site.zcml.in
+output = ${buildout:parts-directory}/etc/site.zcml
+
+[zdaemon_conf]
+recipe = z3c.recipe.template
+input = etc/zdaemon.conf.in
+output = ${buildout:parts-directory}/etc/zdaemon.conf
+
+[deploy_ini]
+recipe = z3c.recipe.template
+input = etc/deploy.ini.in
+output = ${buildout:parts-directory}/etc/deploy.ini
+
+[debug_ini]
+recipe = z3c.recipe.template
+input = etc/debug.ini.in
+output = ${buildout:parts-directory}/etc/debug.ini
+
+
+[eggbasket]
+recipe = z3c.recipe.eggbasket
+eggs = grok
+url = http://grok.zope.org/releaseinfo/grok-eggs-1.0a4.tgz
Added: grok/trunk/doc/groktut/an_empty_grok_project/etc/README.txt
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/etc/README.txt (rev 0)
+++ grok/trunk/doc/groktut/an_empty_grok_project/etc/README.txt 2009-08-31 14:40:12 UTC (rev 103403)
@@ -0,0 +1,26 @@
+In this directory you can find templates which are used by
+``zc.buildout`` to create the configuration files in the parts/etc/ subdir
+of your project.
+
+If you modify files in this directory, you have to run::
+
+ $ bin/buildout
+
+afterwards to rebuild the configuration files in parts/etc/.
+
+In the templates you can use placesholders recognized by zc.buildout
+to name local paths, etc. A zc.buildout placeholder looks like this::
+
+ ${buildout:directory}
+
+which gives you the path of the project directory and will be
+substituted with the real path when you run buildout the next
+time. The set of available placeholders depends on your
+buildout.cfg.
+
+You can also modify files in parts/etc directly, but those changes
+will be overwritten after running bin/buildout the next time.
+
+To run your project you can do::
+
+ $ bin/paster serve parts/etc/deploy.ini
Added: grok/trunk/doc/groktut/an_empty_grok_project/etc/debug.ini.in
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/etc/debug.ini.in (rev 0)
+++ grok/trunk/doc/groktut/an_empty_grok_project/etc/debug.ini.in 2009-08-31 14:40:12 UTC (rev 103403)
@@ -0,0 +1,66 @@
+# debug.ini
+#
+# Debugging configuration for use with paster/WSGI
+#
+
+[loggers]
+keys = root, wsgi
+
+[handlers]
+keys = console, accesslog
+
+[formatters]
+keys = generic, accesslog
+
+[formatter_generic]
+format = %(asctime)s %(levelname)s [%(name)s] %(message)s
+
+[formatter_accesslog]
+format = %(message)s
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[handler_accesslog]
+class = FileHandler
+args = (os.path.join(r'${buildout:directory}', 'parts', 'log', 'access.log'),
+ 'a')
+level = INFO
+formatter = accesslog
+
+[logger_root]
+level = INFO
+handlers = console
+
+[logger_wsgi]
+level = INFO
+handlers = accesslog
+qualname = wsgi
+propagate = 0
+
+[filter:translogger]
+use = egg:Paste#translogger
+setup_console_handler = False
+logger_name = wsgi
+
+[filter-app:main]
+# Change the last part from 'ajax' to 'pdb' for a post-mortem debugger
+# on the console:
+use = egg:z3c.evalexception#ajax
+next = zope
+
+[app:zope]
+use = egg:Sample
+filter-with = translogger
+
+[server:main]
+use = egg:Paste#http
+host = 127.0.0.1
+port = 8080
+
+[DEFAULT]
+# set the name of the zope.conf file
+zope_conf = %(here)s/zope.conf
\ No newline at end of file
Added: grok/trunk/doc/groktut/an_empty_grok_project/etc/deploy.ini.in
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/etc/deploy.ini.in (rev 0)
+++ grok/trunk/doc/groktut/an_empty_grok_project/etc/deploy.ini.in 2009-08-31 14:40:12 UTC (rev 103403)
@@ -0,0 +1,60 @@
+# deploy.ini
+#
+# Deployment configuration for use with paster/WSGI
+#
+
+[loggers]
+keys = root, wsgi
+
+[handlers]
+keys = console, accesslog
+
+[formatters]
+keys = generic, accesslog
+
+[logger_root]
+level = INFO
+handlers = console
+
+[logger_wsgi]
+level = INFO
+handlers = accesslog
+qualname = wsgi
+propagate = 0
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[handler_accesslog]
+class = FileHandler
+args = (os.path.join(r'${buildout:directory}', 'parts', 'log', 'access.log'),
+ 'a')
+level = INFO
+formatter = accesslog
+
+[formatter_generic]
+format = %(asctime)s %(levelname)s [%(name)s] %(message)s
+
+[formatter_accesslog]
+format = %(message)s
+
+[filter:translogger]
+use = egg:Paste#translogger
+setup_console_handler = False
+logger_name = wsgi
+
+[app:main]
+use = egg:Sample
+filter-with = translogger
+
+[server:main]
+use = egg:Paste#http
+host = 127.0.0.1
+port = 8080
+
+[DEFAULT]
+# set the name of the zope.conf file
+zope_conf = %(here)s/zope.conf
Added: grok/trunk/doc/groktut/an_empty_grok_project/etc/site.zcml.in
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/etc/site.zcml.in (rev 0)
+++ grok/trunk/doc/groktut/an_empty_grok_project/etc/site.zcml.in 2009-08-31 14:40:12 UTC (rev 103403)
@@ -0,0 +1,36 @@
+<configure xmlns="http://namespaces.zope.org/zope"
+ i18n_domain="sample">
+
+ <include package="sample" />
+
+ <configure i18n_domain="sample">
+
+ <unauthenticatedPrincipal id="zope.anybody"
+ title="Unauthenticated User" />
+ <unauthenticatedGroup id="zope.Anybody"
+ title="Unauthenticated Users" />
+ <authenticatedGroup id="zope.Authenticated"
+ title="Authenticated Users" />
+ <everybodyGroup id="zope.Everybody"
+ title="All Users" />
+ <principal id="zope.manager"
+ title="Manager"
+ login="grok"
+ password_manager="SHA1"
+ password="8977f073739bd029629243732eb682db005a7541f7509622"
+ />
+
+ <!-- Replace the following directive if you do not want
+ public access -->
+ <grant permission="zope.View"
+ principal="zope.Anybody" />
+ <grant permission="zope.app.dublincore.view"
+ principal="zope.Anybody" />
+
+ <role id="zope.Manager" title="Site Manager" />
+ <role id="zope.Member" title="Site Member" />
+ <grantAll role="zope.Manager" />
+ <grant role="zope.Manager"
+ principal="zope.manager" />
+ </configure>
+</configure>
Added: grok/trunk/doc/groktut/an_empty_grok_project/etc/zdaemon.conf.in
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/etc/zdaemon.conf.in (rev 0)
+++ grok/trunk/doc/groktut/an_empty_grok_project/etc/zdaemon.conf.in 2009-08-31 14:40:12 UTC (rev 103403)
@@ -0,0 +1,8 @@
+<runner>
+ program bin/paster serve ${buildout:directory}/parts/etc/deploy.ini
+ daemon on
+ transcript ${buildout:directory}/parts/log/zdaemon.log
+ socket-name ${buildout:directory}/parts/log/zdaemonsock
+ # Enable this to run the child process as a different user
+ # user zope
+</runner>
Added: grok/trunk/doc/groktut/an_empty_grok_project/etc/zope.conf.in
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/etc/zope.conf.in (rev 0)
+++ grok/trunk/doc/groktut/an_empty_grok_project/etc/zope.conf.in 2009-08-31 14:40:12 UTC (rev 103403)
@@ -0,0 +1,42 @@
+# Identify the component configuration used to define the site:
+site-definition ${site_zcml:output}
+
+<zodb>
+ # Standard Filestorage
+ <filestorage>
+ path ${data:path}
+ </filestorage>
+
+# Uncomment this if you want to connect to a ZEO server instead:
+# <zeoclient>
+# server localhost:8100
+# storage 1
+# # ZEO client cache, in bytes
+# cache-size 20MB
+# # Uncomment to have a persistent disk cache
+# #client zeo1
+# </zeoclient>
+</zodb>
+
+<eventlog>
+ # This sets up logging to a file.
+ # The "path" setting can be a relative or absolute
+ # filesystem path.
+
+ <logfile>
+ path ${buildout:directory}/parts/log/z3.log
+ formatter zope.exceptions.log.Formatter
+ </logfile>
+
+ # This sets up logging to to standard output.
+ # The "path" setting can be the tokens STDOUT or STDERR
+
+# <logfile>
+# path STDOUT
+# formatter zope.exceptions.log.Formatter
+# </logfile>
+</eventlog>
+
+# Comment this line to disable developer mode. This should be done in
+# production
+devmode on
\ No newline at end of file
Modified: grok/trunk/doc/groktut/an_empty_grok_project/setup.py
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/setup.py 2009-08-31 14:16:22 UTC (rev 103402)
+++ grok/trunk/doc/groktut/an_empty_grok_project/setup.py 2009-08-31 14:40:12 UTC (rev 103403)
@@ -1,6 +1,6 @@
from setuptools import setup, find_packages
-version = 0.0
+version = '0.0'
setup(name='Sample',
version=version,
@@ -20,9 +20,16 @@
zip_safe=False,
install_requires=['setuptools',
'grok',
+ 'grokui.admin',
+ 'z3c.testsetup',
+ 'grokcore.startup',
# Add extra requirements here
],
- entry_points="""
- # Add entry points here
+ entry_points = """
+ [console_scripts]
+ sample-debug = grokcore.startup:interactive_debug_prompt
+ sample-ctl = grokcore.startup:zdaemon_controller
+ [paste.app_factory]
+ main = grokcore.startup:application_factory
""",
)
Modified: grok/trunk/doc/groktut/an_empty_grok_project/src/sample/__init__.py
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/src/sample/__init__.py 2009-08-31 14:16:22 UTC (rev 103402)
+++ grok/trunk/doc/groktut/an_empty_grok_project/src/sample/__init__.py 2009-08-31 14:40:12 UTC (rev 103403)
@@ -1 +1 @@
-#
+# this directory is a package
Added: grok/trunk/doc/groktut/an_empty_grok_project/src/sample/app.txt
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/src/sample/app.txt (rev 0)
+++ grok/trunk/doc/groktut/an_empty_grok_project/src/sample/app.txt 2009-08-31 14:40:12 UTC (rev 103403)
@@ -0,0 +1,32 @@
+Do a functional doctest test on the app.
+========================================
+
+:Test-Layer: functional
+
+Let's first create an instance of Sample at the top level:
+
+ >>> from sample.app import Sample
+ >>> root = getRootFolder()
+ >>> root['app'] = Sample()
+
+
+Run tests in the testbrowser
+----------------------------
+
+The zope.testbrowser.browser module exposes a Browser class that
+simulates a web browser similar to Mozilla Firefox or IE. We use that
+to test how our application behaves in a browser. For more
+information, see http://pypi.python.org/pypi/zope.testbrowser.
+
+Create a browser and visit the instance you just created:
+
+ >>> from zope.testbrowser.testing import Browser
+ >>> browser = Browser()
+ >>> browser.open('http://localhost/app')
+
+Check some basic information about the page you visit:
+
+ >>> browser.url
+ 'http://localhost/app'
+ >>> browser.headers.get('Status').upper()
+ '200 OK'
Modified: grok/trunk/doc/groktut/an_empty_grok_project/src/sample/app_templates/index.pt
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/src/sample/app_templates/index.pt 2009-08-31 14:16:22 UTC (rev 103402)
+++ grok/trunk/doc/groktut/an_empty_grok_project/src/sample/app_templates/index.pt 2009-08-31 14:40:12 UTC (rev 103403)
@@ -8,4 +8,4 @@
Edit <code>sample/app_templates/index.pt</code> to change
this page.</p>
</body>
-</html>
\ No newline at end of file
+</html>
Modified: grok/trunk/doc/groktut/an_empty_grok_project/src/sample/configure.zcml
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/src/sample/configure.zcml 2009-08-31 14:16:22 UTC (rev 103402)
+++ grok/trunk/doc/groktut/an_empty_grok_project/src/sample/configure.zcml 2009-08-31 14:40:12 UTC (rev 103403)
@@ -1,5 +1,6 @@
<configure xmlns="http://namespaces.zope.org/zope"
xmlns:grok="http://namespaces.zope.org/grok">
<include package="grok" />
+ <includeDependencies package="." />
<grok:grok package="." />
</configure>
Added: grok/trunk/doc/groktut/an_empty_grok_project/src/sample/ftesting.zcml
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/src/sample/ftesting.zcml (rev 0)
+++ grok/trunk/doc/groktut/an_empty_grok_project/src/sample/ftesting.zcml 2009-08-31 14:40:12 UTC (rev 103403)
@@ -0,0 +1,34 @@
+<configure
+ xmlns="http://namespaces.zope.org/zope"
+ i18n_domain="sample"
+ package="sample"
+ >
+
+ <include package="sample" />
+
+ <!-- Typical functional testing security setup -->
+ <securityPolicy
+ component="zope.securitypolicy.zopepolicy.ZopeSecurityPolicy"
+ />
+
+ <unauthenticatedPrincipal
+ id="zope.anybody"
+ title="Unauthenticated User"
+ />
+ <grant
+ permission="zope.View"
+ principal="zope.anybody"
+ />
+
+ <principal
+ id="zope.mgr"
+ title="Manager"
+ login="mgr"
+ password="mgrpw"
+ />
+
+ <role id="zope.Manager" title="Site Manager" />
+ <grantAll role="zope.Manager" />
+ <grant role="zope.Manager" principal="zope.mgr" />
+
+</configure>
Added: grok/trunk/doc/groktut/an_empty_grok_project/src/sample/static/README.txt
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/src/sample/static/README.txt (rev 0)
+++ grok/trunk/doc/groktut/an_empty_grok_project/src/sample/static/README.txt 2009-08-31 14:40:12 UTC (rev 103403)
@@ -0,0 +1,2 @@
+Put static files here, like javascript and css. They will be
+available as static/<filename> in views.
Added: grok/trunk/doc/groktut/an_empty_grok_project/src/sample/tests.py
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/src/sample/tests.py (rev 0)
+++ grok/trunk/doc/groktut/an_empty_grok_project/src/sample/tests.py 2009-08-31 14:40:12 UTC (rev 103403)
@@ -0,0 +1,12 @@
+import os.path
+import z3c.testsetup
+import sample
+from zope.app.testing.functional import ZCMLLayer
+
+
+ftesting_zcml = os.path.join(
+ os.path.dirname(sample.__file__), 'ftesting.zcml')
+FunctionalLayer = ZCMLLayer(ftesting_zcml, __name__, 'FunctionalLayer',
+ allow_teardown=True)
+
+test_suite = z3c.testsetup.register_all_tests('sample')
Added: grok/trunk/doc/groktut/an_empty_grok_project/versions.cfg
===================================================================
--- grok/trunk/doc/groktut/an_empty_grok_project/versions.cfg (rev 0)
+++ grok/trunk/doc/groktut/an_empty_grok_project/versions.cfg 2009-08-31 14:40:12 UTC (rev 103403)
@@ -0,0 +1,136 @@
+# This file contains a list of versions of the various grok modules that
+# belong together.
+# It was downloaded from http://grok.zope.org/releaseinfo/grok-1.0a4.cfg
+# when this project was created.
+
+[versions]
+grok = 1.0a4
+ClientForm = 0.2.9
+docutils = 0.4
+grokcore.component = 1.6
+grokcore.formlib = 1.1
+grokcore.security = 1.0
+grokcore.view = 1.7
+grokcore.viewlet = 1.0
+grokui.admin = 0.3.2
+martian = 0.11
+mechanize = 0.1.7b
+Pygments = 0.8.1
+pytz = 2007k
+RestrictedPython = 3.4.2
+simplejson = 1.7.1
+z3c.autoinclude = 0.2.2
+z3c.flashmessage = 1.0
+z3c.testsetup = 0.2.1
+zc.catalog = 1.2.0
+ZConfig = 2.5.1
+zc.recipe.testrunner = 1.0.0
+zdaemon = 2.0.2
+ZODB3 = 3.8.1
+zodbcode = 3.4.0
+zope.annotation = 3.4.1
+zope.app.apidoc = 3.4.3
+zope.app.applicationcontrol = 3.4.3
+zope.app.appsetup = 3.4.1
+zope.app.authentication = 3.4.4
+zope.app.basicskin = 3.4.0
+zope.app.broken = 3.4.0
+zope.app.catalog = 3.5.1
+zope.app.component = 3.4.1
+zope.app.container = 3.5.6
+zope.app.content = 3.4.0
+zope.app.debug = 3.4.1
+zope.app.dependable = 3.4.0
+zope.app.error = 3.5.1
+zope.app.exception = 3.4.1
+zope.app.file = 3.4.4
+zope.app.folder = 3.4.0
+zope.app.form = 3.4.1
+zope.app.generations = 3.4.1
+zope.app.http = 3.4.1
+zope.app.i18n = 3.4.4
+zope.app.interface = 3.4.0
+zope.app.intid = 3.4.1
+zope.app.keyreference = 3.4.1
+zope.app.locales = 3.4.5
+zope.app.onlinehelp = 3.4.1
+zope.app.pagetemplate = 3.4.1
+zope.app.preference = 3.4.1
+zope.app.principalannotation = 3.4.0
+zope.app.publication = 3.4.3
+zope.app.publisher = 3.5.1
+zope.app.renderer = 3.4.0
+zope.app.rotterdam = 3.4.1
+zope.app.schema = 3.4.0
+zope.app.security = 3.5.2
+zope.app.securitypolicy = 3.4.6
+zope.app.server = 3.4.2
+zope.app.session = 3.5.1
+zope.app.skins = 3.4.0
+zope.app.testing = 3.4.3
+zope.app.tree = 3.4.0
+zope.app.twisted = 3.4.1
+zope.app.wsgi = 3.4.1
+zope.app.zapi = 3.4.0
+zope.app.zcmlfiles = 3.4.3
+zope.app.zopeappgenerations = 3.4.0
+zope.cachedescriptors = 3.4.1
+zope.component = 3.4.0
+zope.configuration = 3.4.0
+zope.contentprovider = 3.4.0
+zope.contenttype = 3.4.0
+zope.copypastemove = 3.4.0
+zope.datetime = 3.4.0
+zope.deferredimport = 3.4.0
+zope.deprecation = 3.4.0
+zope.dottedname = 3.4.2
+zope.dublincore = 3.4.0
+zope.error = 3.5.1
+zope.event = 3.4.0
+zope.exceptions = 3.4.0
+zope.filerepresentation = 3.4.0
+zope.formlib = 3.4.0
+zope.hookable = 3.4.0
+zope.i18n = 3.4.0
+zope.i18nmessageid = 3.4.3
+zope.index = 3.4.1
+zope.interface = 3.4.1
+zope.lifecycleevent = 3.4.0
+zope.location = 3.4.0
+zope.minmax = 1.1.0
+zope.modulealias = 3.4.0
+zope.pagetemplate = 3.4.0
+zope.proxy = 3.4.2
+zope.publisher = 3.4.6
+zope.schema = 3.4.0
+zope.security = 3.4.1
+zope.securitypolicy = 3.4.1
+zope.server = 3.4.3
+zope.session = 3.4.1
+zope.size = 3.4.0
+zope.structuredtext = 3.4.0
+zope.tal = 3.4.1
+zope.tales = 3.4.0
+zope.testbrowser = 3.4.2
+zope.testing = 3.6.0
+zope.thread = 3.4
+zope.traversing = 3.4.1
+zope.viewlet = 3.4.2
+
+
+# Here we pin the recipes and other packages that are not in the
+# downloaded versions.cfg of grok
+Paste = 1.7.2
+PasteDeploy = 1.3.2
+PasteScript = 1.7.3
+setuptools = 0.6c9
+z3c.evalexception = 2.0
+z3c.recipe.eggbasket = 0.4.1
+z3c.recipe.i18n = 0.5.0
+z3c.recipe.template = 0.1
+zc.buildout = 1.1.1
+zc.recipe.egg = 1.1.0
+zc.recipe.filestorage = 1.0.1
+grokcore.startup = 0.2
+
+
Modified: grok/trunk/doc/tutorial.rst
===================================================================
--- grok/trunk/doc/tutorial.rst 2009-08-31 14:16:22 UTC (rev 103402)
+++ grok/trunk/doc/tutorial.rst 2009-08-31 14:40:12 UTC (rev 103403)
@@ -27,7 +27,7 @@
instead.
Grok is a powerful and flexible web application framework for Python
-developers. In this tutorial we will show you the various things you
+developers. In this tutorial we will show you the various things you
can do with Grok, and how Grok can help you build your web
application. We'll start out simple, and will slowly go to more
complex usage patterns.
@@ -46,18 +46,21 @@
around instead and read the pieces which interest you most. If
something is unclear, you can always backtrack to previous sections.
-Grok is based on Zope 3 and is compatible with Zope 3, but you do not
-need to know Zope 3 (or Zope 2) at all to follow this tutorial. Grok
-builds on existing Zope 3 technology but exposes it in a different way
-to the developer. We believe Grok makes developing with Zope 3
+Grok is based on the `Zope Toolkit`_. You do not need to know about
+the Zope Toolkit at all to follow this tutorial. Grok builds on
+existing Zope Toolkit technology but exposes it in a special way to
+the developer. We believe Grok makes developing with Zope Toolkit
technology easier and more fun for beginners and experienced
developers alike.
+.. _`Zope Toolkit`: http://docs.zope.org/zopetoolkit/
+
+
Getting started with Grok
=========================
This chapter will help you get up and running with Grok, using the
-``grokproject`` tool. We create a new project with ``grokproject``,
+``grokproject`` tool. We create a new project with ``grokproject`` and
tell you how to get that project running so you can access it with a
web browser.
@@ -74,7 +77,7 @@
You need to download `ez_setup.py`_. Then, you run it like this to
install ``easy_install`` into your system Python::
- $ sudo python2.4 ez_setup.py
+ $ sudo python2.5 ez_setup.py
.. _`ez_setup.py`: http://peak.telecommunity.com/dist/ez_setup.py
@@ -86,25 +89,106 @@
$ sudo easy_install -U setuptools
+ **Note**: it is recommended you set up ``easy_install`` in a special
+ virtualenv to isolate yourself from the system Python and whichever
+ libraries it may have installed. This is especially relevant on the
+ Mac OS X platform. See the next sidebar for more information.
+
+.. sidebar:: Setting up a virtualenv
+
+ Virtualenv is a tool that allows you to isolate your Python
+ development environment entirely from the system and globally
+ installed Python libraries.
+
+ On platforms like Mac OS X the use of virtualenv is especially
+ recommended as some older versions of libraries (notably
+ ``zope.interface``) are installed for the operation of Mac OS X
+ services. Grok needs a newer version of ``zope.interface`` however,
+ resulting in a conflict. Isolating yourself from the system Python
+ is also recommended on Linux environments however, as Python is
+ usually installed with the system package manager.
+
+ If you do not want to use virtualenv it is always also possible to
+ compile and install a different version of Python locally just for
+ the use with Grok.
+
+ During Grok installation on Linux and Mac OS X various libraries
+ with C-level components are automatically compiled for you. On Linux
+ you need to make sure you have the Python development headers
+ installed; on Debian and Ubuntu they are in the ``python-dev``
+ package.
+
+ These instructions are written for a Unix-style system and will be
+ harder to follow on Windows. On Windows environments you can skip
+ this step if you know you've installed a clean Python environment
+ yourself. If however you intend to install a lot of software that
+ uses this same version of Python, virtualenv is still recommended.
+
+ You can install virtualenv with ``easy_install``::
+
+ $ easy_install-2.5 virtualenv
+
+ The ``virtualenv`` command-line tool should now be available to
+ you. You can now create a sandbox environment for the use wih Grok::
+
+ $ virtualenv --no-site-packages virtualgrok
+
+ This will create a ``virtualgrok`` directory in your present
+ location that contains the virtual environment.
+
+ The ``--no-site-packages`` switch is important; it isolates your
+ virtual Python environment from any packages installed in the system
+ libraries.
+
+ You should now activate the virtual environment::
+
+ $ source virtualgrok
+
+ Once you have activated the virtual environment, you can use it to
+ ``easy_install`` grokproject in the regular way::
+
+ $ easy_install grokproject
+
+ Note that once you have created a Grok project from a virtual
+ environment once you do not need to activate the virtual environment
+ again afterwards -- the Grok project will know to use the special
+ virtualgrok Python environment automatically. You only need to
+ activate the ``grokproject`` virtualenv when you want to use the
+ ``grokproject`` tool directly.
+
+ For more information, see `Using Virtualenv for a clean Grok
+ installation`_.
+
+ .. _virtualenv: http://pypi.python.org/pypi/virtualenv
+
+ .. _`Using Virtualenv for a clean Grok installation`: http://grok.zope.org/documentation/how-to/using-virtualenv-for-a-clean-grok-installation
+
Setting up grok on a Unix-like (Linux, Mac OS X) environment is
easy. Most of these instructions should also work in a Windows
environment as well.
Let's go through the prerequisites first. You need a computer
connected to the internet, as Grok installs itself over the
-network. You also need Python 2.4 or Python 2.5 installed.
+network. You also need Python 2.5 (or Python 2.4) installed.
-Because Grok uses a source distribution of Zope 3, you may need to
-install your operating system's Python "dev" package. You also need a
-working C compiler (typically ``gcc``) installed, as we compile bits of
-Zope 3 during setup. Finally, you also need ``easy_install`` installed
-so it becomes easy to install Python packages.
+Because Grok uses a source distribution of the Zope Toolkit libraries,
+you may need to install your operating system's Python "dev"
+package. You also need a working C compiler (typically ``gcc``)
+installed, as we compile bits of the Zope Toolkit during setup. On
+Windows such a build environment is not necessary, as grokproject will
+download and automatically install precompiled libraries for
+Windows. Finally, you also need ``easy_install`` installed so it
+becomes easy to install Python packages.
Once you are done with the prerequisites, you can install
grokproject itself::
- $ sudo easy_install grokproject
+ $ easy_install grokproject
+If you are on a Unixy environment and you are not working from the
+recommended virtualenv, you will need to request admin rights using
+``sudo``, as this will install new libraries into your system Python.
+
We're ready to create our first grok project now!
Creating a grok project
@@ -129,86 +213,74 @@
.. sidebar:: Installing the previous 'zopectl' layout
- To install the previous 'zopectl' layout create a Grok project like::
+ Grok used to have a different layout using ``zopectl``. To install
+ this older layout, use ``grokproject`` with the ``--ctl`` flag::
$ grokproject --zopectl Sample
This tells grokproject to create a new subdirectory called ``Sample``
and set up the project in there. grokproject will automatically
-download and install Zope 3 and Grok into the project area.
+download and install the Zope Toolkit libraries as well as Grok into
+the project area.
-You will be asked a number of questions now. Grok asks you for an
-initial username and password for the Zope server. We'll use ``grok``
-for both::
+Grok asks you for an initial username and password for the Zope
+server. We'll use ``grok`` for both::
Enter user (Name of an initial administrator user): grok
Enter passwd (Password for the initial administrator user): grok
-Now you have to wait while grokproject downloads `zc.buildout`_
-(the system that's used to build the project area), Grok and the Zope
-3 libraries.
+Now you have to wait while grokproject downloads and installs the
+various tools and libraries that are needed in a Grok project. The
+second time you create a Grok project it will be faster as it can
+reuse the previously installed libraries. After all that your Grok
+project is ready to go.
-After all that, Grok, along with a Zope 3 instance, is ready to go.
-
.. sidebar:: Common problems installing Grok
One common problem when installing Grok is library mixup. You may
have some libraries installed in your Python interpreter that
- conflict with libraries that Grok wants to install. If you already
- have installed Zope 3 previously for instance, you may first have
- to remove it from your Python's ``site-packages`` directory.
-
- Another way to make sure Grok doesn't clash with any incompatible
- libraries is to install and run grokproject from within a
- virtualenv_, with the ``--no-site-packages`` option enabled. See
- also `Using Virtualenv for a clean Grok installation`_.
+ conflict with libraries that Grok wants to install. You tend to get
+ an error when starting up the Grok webserver when this is the
+ case. If you already have installed Zope Toolkit libraries (or Zope
+ 3) previously for instance, you may first have to remove these
+ libraries from your Python's ``site-packages`` directory.
- Modern versions of Mac OS X install Twisted, which in turn has a
- non-compatible version of ``zope.interface`` as a dependency. This
- means that the virtualenv option is always recommended on Mac OS X,
- unless you install a separate version of Python.
+ Better yet, see the previous ``virtualenv`` sidebar for a way to
+ isolate Grok from the system Python environment and its libraries,
+ avoiding such problems.
- During Grok installation on Linux and Mac OS X various libraries
- with C-level components are automatically compiled for you. On Linux
- you need to make sure you have the Python development headers
- installed; on Debian and Ubuntu you they are in the ``python-dev``
- package.
+Starting up the web server
+--------------------------
- .. _virtualenv: http://pypi.python.org/pypi/virtualenv
+.. sidebar:: Run a Grok instance created with the older 'zopectl' layout
- .. _`Using Virtualenv for a clean Grok installation`: http://grok.zope.org/documentation/how-to/using-virtualenv-for-a-clean-grok-installation
-
-Starting up Zope
-----------------
-
-.. sidebar:: Run a Grok instance created with the previous 'zopectl' layout
-
- To start up the Grok instance created with the previous 'zopectl' layout::
+ To start up the Grok instance created with the older 'zopectl'
+ layout::
$ cd Sample
$ bin/zopectl fg
On Windows to work with ``zopectl`` you need to make sure you have
- win32all_ installed in your Python. It's not required to install
+ win32all_ installed in your Python. It is not required to install
win32all to work with the default ``paster`` setup.
.. _win32all: http://sourceforge.net/projects/pywin32/
You can go into the ``Sample`` project directory now and start up the
-Zope instance that has been installed::
+web server for our project::
$ cd Sample
$ bin/paster serve parts/etc/deploy.ini
-This will make Zope 3 available on port 8080, and you can log in with
+This will make Grok available on port 8080. You can log in with
username ``grok`` and password ``grok``. Assuming you've started up
-Zope on your localhost, you can go to it here:
+the web server on your development computer, you can go to it here:
http://localhost:8080
This first pops up a login dialog (username: ``grok`` and password:
-``grok``). It will then show a simple Grok admin interface. This
-allows you to install new Grok applications.
+``grok``). It will then show a simple Grok admin interface. This user
+interface allows you to install new Grok applications.
Our sample application (``sample.app.Sample``) will be available for
adding. Let's try this out. Go to the Grok admin page:
@@ -229,17 +301,19 @@
Your Grok application is up and running. Edit
sample/app_templates/index.pt to change this page.
-You can shut down Zope 3 at any time by hitting ``CTRL-c``. Shut it
-down now. We will be shutting down and starting up Zope 3 often in
-this tutorial.
+You can shut down the server at any time by hitting ``CTRL-c``. Shut
+it down now. We will be shutting down and starting up the server often
+in this tutorial.
-Practice restarting Zope now, as you'll end up doing it a lot during
-this tutorial. It's just stopping Zope and starting it again:
-``CTRL-c`` and then ``bin/paster serve parts/etc/deploy.ini`` from your Sample
-project directory. Alternatively, you can use the --reload flag to start
-up paster with a monitor that scans your code base (python files only) for changes and
-automatically restart the Zope server every time you make a change::
-
+Practice restarting the server now, as you'll end up doing it a lot
+during this tutorial. It's just stopping and starting it again:
+``CTRL-c`` and then ``bin/paster serve parts/etc/deploy.ini`` from
+your Sample project directory.
+
+Alternatively, you can use the --reload flag to start up paster with a
+monitor that scans your code base (python files only) for changes and
+automatically restarts the Zope server every time you make a change::
+
$ bin/paster serve --reload parts/etc/deploy.ini
An empty Grok project
@@ -247,32 +321,33 @@
.. sidebar:: What about the other directories and files in our project?
- What about the other files and subdirectories in our ``Sample`` project
- directory? Grokproject sets up the project using a system called
- `zc.buildout`_. The ``eggs``, ``develop-eggs`` and ``bin``
- directories are all set up and maintained by zc.buildout. See its
- documentation for more information about how to use it. The
- configuration of the project and its dependency is in
+ What about the other files and subdirectories in our ``Sample``
+ project directory? Grokproject sets up the project using a system
+ called `zc.buildout`_. The ``eggs``, ``develop-eggs``, ``bin`` and
+ ``parts`` directories are all set up and maintained by
+ zc.buildout. See its documentation for more information about how to
+ use it. The configuration of the project and its dependency is in
``buildout.cfg``. For now, you can avoid these details however.
- .. _`zc.buildout`: http://cheeseshop.python.org/pypi/zc.buildout
+ .. _`zc.buildout`: http://buildout.org
Let's take a closer look at what's been created in the Sample project
directory.
-One of the things grokproject created was a ``setup.py`` file. This file
-contains information about your project. This information is used by
-Python distutils and setuptools. You can use the ``setup.py`` file to
-upload your project to the Python Package Index (PyPI).
+One of the things grokproject created was a ``setup.py`` file. This
+file contains information about your project. This information is used
+by buildout to download your project's dependencies and to install
+it. You can also use the ``setup.py`` file to upload your project to
+the Python Package Index (PyPI).
We have already seen the ``bin`` directory. It contains the startup
-script for the Zope instance (``bin/paster``) as well as the
-executable for the buildout system (``bin/buildout``) which can be
-used to re-build the Zope instance and possibly update the Grok and
-Zope packages.
+script for the web server (``bin/paster``) as well as the executable
+for the buildout system (``bin/buildout``) which can be used to
+re-build your project (to update it or to install a new dependency).
-The ``parts`` and ``etc`` directories contain configuration and data created by
-``buildout``, such as the Zope object database (ZODB) instance.
+The ``parts` directory contain configuration and data created and
+managed by ``buildout``, such as the Zope object database (ZODB)
+storage, and the ``.ini`` files to be used with ``paster``.
The actual code of the project will all be inside the ``src``
directory. In it is a Python package directory called ``sample`` with
@@ -297,15 +372,32 @@
This is the template for your project's welcome page.
-What's left is a ``configure.zcml`` file. Unlike in typical Zope 3
-applications, this will only ever contain a few lines that load Grok
-and then register this application with Grok. This means we can
-typically completely ignore it, but we'll show it here once for good
-measure:
+There is also a ``configure.zcml`` file. This file will normally only
+contain a few lines that load dependencies and then register this
+application with Grok. This means we can typically completely ignore
+it, but we'll show it here once for good measure:
.. include:: groktut/an_empty_grok_project/src/sample/configure.zcml
:literal:
+.. sidebar:: ``configure.zcml`` in non-Grok applications
+
+ In non-Grok applications that use the Zope Toolkit (such as
+ something created with Zope 2 or Zope 3), the ZCML file usually
+ plays a much bigger role. It contains directives which registers
+ particular Python objects (typically classes, such as views) with
+ the component architecture that is central to the Zope Toolkit.
+ Grok however automates this registration by putting more information
+ into the Python code directly, so that the ZCML file can remain small.
+
+There is also a ``static`` directory. This contains static files that
+can be used in the web application, such as images, css files and
+javascript files.
+
+Besides these files, there is an ``app.txt``, ``ftesting.zcml`` and
+``tests.py``. These all have to do with the automatic testing
+environment and can be ignored for now.
+
Showing pages
=============
More information about the checkins
mailing list