Package: zopeproject
ContentsQuickstartNotes for Windows usersSharing eggs among sandboxesCommand line options for zopeprojectThe sandboxWhat are the different files and directories for?RenamingSharing and archiving sandboxesDevelopingFirst steps with your applicationAdding dependencies to the applicationWriting and running testsFunctional testsDebuggingThe interpreter promptThe interactive debug promptDebugging exceptionsDeployingDisabling debugging toolsLinux/UnixWindowsReporting bugs or asking questions about zopeprojectCreditsChanges0.4.2 (2009-02-12)0.4.1 (2007-09-29)0.4 (2007-09-15)New featuresBugfixes and restructuring0.3.2 (2007-07-17)0.3.1 (2007-07-15)0.3 (2007-07-14)0.2 (2007-07-12)0.1 (2007-07-06)QuickstartYou can start a new Zope-based web application from scratch with just
two commands:$ easy_install zopeproject
$ zopeproject HelloWorldThe second command will ask you for a name and password for an
initial administrator user.  It will also ask you where to put the
Python packages (“eggs”) that it downloads.  This way multiple
projects created withzopeprojectcan share the same packages and
won’t have to download them each time (see alsoSharing eggs among
sandboxesbelow).(Note: Depending on how they installed Python, Unix/Linux users may
have to invokeeasy_installwithsudo.  If that’s not wanted
or possible,easy_installcan be invoked with normal privileges
inside avirtual-pythonorworkingenv).After asking these questions,zopeprojectwill download thezc.buildoutpackage that will be used to build the sandbox, unless
it is already installed locally.  Then it will invokebuildoutto
download Zope and its dependencies.  If you’re doing this for the first
time or not sharing packages between different projects, this may take
a while.Whenzopeprojectis done, you will find a typical Python package
development environment in theHelloWorlddirectory: the package
itself (helloworld) and asetup.pyscript.  There’s also abindirectory that contains scripts, such aspasterwhich can
be used to start the application:$ cd HelloWorld
$ bin/paster serve deploy.iniYou may also use thehelloworld-ctlscript which works much like
thezopectlscript from Zope instances:$ bin/helloworld-ctl foregroundAfter starting the application, you should now be able to go tohttp://localhost:8080and see the default start screen of Zope.  You
will also be able to log in with the administrator user account that
you specified earlier.Notes for Windows usersSome packages required by Zope contain C extension modules.  There may
not always be binary Windows distributions available for these
packages.  In this case, setuptools will try to compile them from
source which will likely fail if you don’t have a compiler such as the
Microsoft Visual C compiler installed.  Alternatively, you can install
the freeMinGWcompiler:DownloadMinGW-x.y.z.exefromhttp://www.mingw.org/and run it
to do a full install into the standard location (ie.C:\MinGW).Tell Python to use the MinGW compiler by creatingC:\Documentsand Settings\YOUR USER\pydistutils.cfgwith the following contents:[build]
compiler=mingw32Let Python know about the MinGW installation and thepydistutils.cfgfile.  To do that, go to theControl Panel,Systemsection,Advancedtab and click on theEnvironment
variablesbutton.  Add theC:\MinGW\bindirectory to yourPathenvironment variable (individual paths are delimited by
semicolons).  Also add another environment variable calledHOMEwith the following value:C:\Documents and Settings\YOUR USERWhen installing packages from source, Python should now automatically
use the MinGW compiler to build binaries.Sharing eggs among sandboxesA great feature ofzc.buildoutis the ability to share downloaded
Python packages (“eggs”) between sandboxes.  This is achieved by
placing all eggs in a shared location.  zopeproject will ask for this
location each time.  The setting will become part ofbuildout.cfg.It could very well be that your shared eggs directory is different
from the suggested default value, so it would be good to avoid having
to type it in every time.  Furthermore, you may want to avoid having
system-dependent paths appear inbuildout.cfgbecause they hinder
the repeatibility of the setup on other machines.A way to solve these problems is to configure a user-specific default
eggs directory for buildout in your home directory:~/.buildout/default.cfg:[buildout]
eggs-directory = /home/philipp/eggszopeproject will understand that you have this default value and
change its own default when asking you for the eggs directory.  If you
just hit enter there (thereby accepting the default in~/.buildout/default.cfg), the generatedbuildout.cfgwill not
contain a reference to a path.Command line options for zopeproject--no-buildoutWhen invoked with this option,zopeprojectwill only create the
project directory with the standard files in it, but it won’t
download and invokezc.buildout.--newerThis option enables thenewest = truesetting inbuildout.cfg.  That way, buildout will always check for newer
versions of eggs online.  If, for example, you have outdated
versions of your dependencies in your shared eggs directory, this
switch will force the download of newer versions.  Note that you can
always editbuildout.cfgto change this behaviour in an existing
project area, or you can invokebin/buildoutwith the-noption.--svn-repository=REPOSThis option will import the project directory and the files in it
into the given subversion repository and provide you with a checkout
of thetrunk.REPOSis supposed to be a repository path
that is going to be created, along withtags,branchesandtrunkbelow that. This checkin ignores any files and directories
created by zc.buildout.-v,--verboseWhen this option is enabled,zopeprojectwon’t hide the output
ofeasy_install(used to installzc.buildout) and thebuildoutcommand.The sandboxWhat are the different files and directories for?deploy.iniConfiguration file forPasteDeploy.  It defines which server
software to launch and which WSGI application to invoke upon each
request (which is defined insrc/helloworld/startup.py).  You
may also define WSGI middlewares here.  Invokebin/paster servewith this file as an argument.debug.iniAlternate configuration forPasteDeploythat configures
middleware which intercepts exceptions for interactive debugging.
SeeDebugging exceptionsbelow.zope.confThis file will be read by the application factory insrc/helloworld/startup.py.  Here you can define which ZCML file
the application factory should load upon startup, the ZODB database
instance, an event log as well as whether developer mode is switched
on or not.site.zcmlThis file is referred to byzope.confand will be loaded by the
application factory.  It is the root ZCML file and includes
everything else that needs to be loaded.  ‘Everything else’ typically
is just the application package itself,helloworld, which then
goes on to include its dependencies.  Apart from this,site.zcmlalso defines the anonymous principal and the initial admin principal.setup.pyThis file defines the egg of your application.  That definition
includes listing the package’s dependencies (mostly Zope eggs) and
the entry point for thePasteDeployapplication factory.buildout.cfgThis file tellszc.buildoutwhat to do when the buildout is
executed.  This mostly involves executingsetup.pyto enable theHelloWorldegg (which also includes downloading its
dependencies), as well as installingPasteDeployfor the server.
This files also refers to the shared eggs directory
(eggs-directory) and determines whether buildout should check
whether newer eggs are available online or not (newest).bin/This directory contains all executable scripts, e.g for starting the
application (paster), installing or reinstalling dependencies
(buildout), or invoking the debug prompt (helloworld-debug).
It also contains a script (python) that invokes the standard
interpreter prompt with all packages on the module search path.src/This directory contains the Python package(s) of your application.
Normally there’s just one package (helloworld), but you may add
more to this directory if you like.  Thesrcdirectory will be
placed on the interpreter’s search path byzc.buildout.var/The ZODB filestorage will place its files (Data.fs, lock files,
etc.) here.RenamingYou can rename or move the sandbox directory any time you like.  Just
be sure to runbin/buildoutagain after doing so.  Renaming the
sandbox directory won’t change the name of the egg, however. To do
that, you’ll have to change thenameparameter insetup.py.Sharing and archiving sandboxesYou can easily share sandboxes with co-developers or archive them in a
version control system such as subversion.  You can theoretically
share or archive the whole sandbox directory, though it’s recommendednot to includethe following files and directories because they
can and will be generated by zc.buildout from the configuration files:bin/parts/develop-eggs/all files invar/all files inlog/.installed.cfgIf you receive a sandbox thas has been archived (e.g. by checking it
out from a version control system), you will first have to bootstrap
it in order to obtain thebin/buildoutexecutable.  To do that,
use thebuildoutscript from any other sandbox on your machine:$ .../path/to/some/sandbox/bin/buildout bootstrapNow the sandbox has its ownbin/buildoutscript and can be
installed:$ bin/buildoutDevelopingFirst steps with your applicationAfter having started up Zope for the first time, you’ll likely want to
start developing your web application.  Code for your application goes
into thehelloworldpackage that was created by zopeproject in thesrcdirectory.For example, to get a simple “Hello world!” message displayed, createsrc/helloworld/browser.pywith the following contents:from zope.publisher.browser import BrowserPage

class HelloPage(BrowserPage):
    def __call__(self):
        return "<html><body><h1>Hello World!</h1></body></html>"Then all you need to do is hook up the page in ZCML.  To do that, add
the following directive towards the end ofsrc/helloworld/configure.zcml:<browser:page
    for="*"
    name="hello"
    class=".browser.HelloPage"
    permission="zope.Public"
    />Note that you’ll likely need to define thebrowsernamespace
prefix at the top of the file:<configure xmlns="http://namespaces.zope.org/zope"
           xmlns:browser="http://namespaces.zope.org/browser"
           >After having restarted the application usingpaster serve, you can
visithttp://localhost:8080/helloto see the page in action.Adding dependencies to the applicationThe standardsetup.pyandconfigure.zcmlfiles list a set of
standard dependencies that are typical for most Zope applications.
You may obviously remove things from this list, but typically you’ll
want to re-use more libraries that others have written.  Many, if not
most, of additional Zope and third party libraries arelisted on the
Python Cheeseshop.Let’s say you wanted to reuse thesome.librarypackage in your
application.  The first step would be to add it to the list of
dependencies insetup.py(install_requires).  If this package
defined any Zope components, you would probably also have to load its
ZCML configuration by adding the following line tosrc/helloworld/configure.zcml:<include package="some.library" />After having changedsetup.py, you would want the newly added
dependency to be downloaded and added to the search path ofbin/paster.  To do that, simply invoke the buildout:$ bin/buildoutWriting and running testsAutomated tests should be placed in Python modules.  If they all fit
in one module, the module should simply be namedtests.  If you
need many modules, create atestspackage and put the modules in
there.  Each module should start withtest(for example, the full
dotted name of a test module could behelloworld.tests.test_app).If you prefer to separate functional tests from unit tests, you can
put functional tests in anftestsmodule or package.  Note that
this doesn’t matter to the test runner whatsoever, it doesn’t care
about the location of a test case.Each test module should define atest_suitefunction that
constructs the test suites for the test runner, e.g.:def test_suite():
    return unittest.TestSuite([
        unittest.makeSuite(ClassicTestCase),
        DocTestSuite(),
        DocFileSuite('README.txt', package='helloworld'),
        ])To run all tests in your application’s packages, simply invoke thebin/testscript:$ bin/testFunctional testsWhile unit test typically require no or very little test setup,
functional tests normally bootstrap the whole application’s
configuration to create a real-life test harness.  The configuration
file that’s responsible for this test harness isftesting.zcml.
You can add more configuration directives to it if you have components
that are specific to functional tests (e.g. mockup components).To let a particular test run inside this test harness, simply apply
thehelloworld.testing.FunctionalLayerlayer to it:from helloworld.testing import FunctionalLayer
suite.layer = FunctionalLayerYou can also simply use one of the convenience test suites inhelloworld.testing:FunctionalDocTestSuite(based ondoctest.DocTestSuite)FunctionalDocFileSuite(based ondoctest.DocFileSuite)FunctionalTestCase(based onunittest.TestCase)DebuggingThe interpreter promptUse thebin/pythonscript if you’d like test some components from
the interpreter prompt and don’t need the component registrations nor
access to the ZODB.  If you do need those, go on to the next section.The interactive debug promptOccasionally, it is useful to be able to interactively debug the state
of the application, such as walking the object hierarchy in the ZODB
or looking up components manually.  This can be done with the
interactive debug prompt, which is available underbin/helloworld-debug:$ bin/helloworld-debug
Welcome to the interactive debug prompt.
The 'root' variable contains the ZODB root folder.
The 'app' variable contains the Debugger, 'app.publish(path)' simulates a request.
>>>You can now get a folder listing of the root folder, for example:>>> list(root.keys())
[u'folder', u'file']Debugging exceptionsIn case your application fails with an exception, it can be useful to
inspect the circumstances with a debugger.  This is possible with thez3c.evalexceptionWSGI middleware.  When an exception occurs in
your application, stop the process and start it up again, now using
thedebug.iniconfiguration file:$ bin/paster serve debug.iniWhen you then repeat the steps that led to the exception, you will see
the relevant traceback in your browser, along with the ability to view
the corresponding source code and to issue Python commands for
inspection.If you prefer the Python debuggerpdb, replaceajaxwithpdbin the WSGI middleware definition indebug.ini:[filter-app:main]
use = egg:z3c.evalexception#pdb
next = zopeNote: Even exceptions such as Unauthorized (which normally leads to a
login screen) or NotFound (which normally leads to an HTTP 404
response) will trigger the debugger.DeployingDisabling debugging toolsBefore deploying a zopeproject-based application, you should make sure
that any debugging tools are disabled.  In particular, this includesmaking sure there’s no debugging middleware indeploy.ini(normally these should be configured indebug.inianyway),switching offdeveloper-modeinzope.conf,disabling the APIDoc tool insite.zcml,disabling the bootstrap administrator principal insite.zcml.Linux/UnixYou can use thehelloworld-ctlscript to start the server process
in daemon mode.  It works much like theapachectltool as known
from the Apache HTTPD server or INIT scripts known from Linux:$ bin/helloworld-ctl startTo stop the server, issue:$ bin/helloworld-ctl stopOther commands, such asstatusandrestartare supported as
well.WindowsThere’s currently no particular support for deployment on Windows
other than whatpasterprovides.  Integration with Windows
services, much like what could be found in older versions of Zope, is
planned.Reporting bugs or asking questions about zopeprojectzopeproject maintains a bugtracker and help desk on Launchpad:https://launchpad.net/zopeprojectQuestions can also be directed to the zope3-users mailinglist:http://mail.zope.org/mailman/listinfo/zope3-usersCreditszopeproject is written and maintained by Philipp von Weitershausen.
It was inspired by the similargrokprojecttool from the same author.James Gardner, Martijn Faassen, Jan-Wijbrand Kolman and others gave
valuable feedback on the early prototype presented at EuroPython 2007.Michael Bernstein gave valuable feedback and made many suggestions for
improvements.zopeproject is distributed under theZope Public License,
v2.1. Copyright (c) by Zope Corporation and Contributors.Changes0.4.2 (2009-02-12)Use Zope 3.4.0 KGS in the default deployment buildout.cfg.Added blobstorage proxy to default ZODB config in zope.conf.Use ZopeSecurityPolicy from zope.securitypolicy instead
of zope.app.securitypolicy, which is a deprecated place for
that.The zope.securitypolicy uses a special role name,
thezope.Anonymousthat every user has, define
it in site.zcml and grant view permissions to it,
instead of zope.Anybody unauthenticated group.0.4.1 (2007-09-29)Improvements toREADME.txtandvar/README.txt(it was
pointing to the wrong configuration file).  Moved changelog fromREADME.txtinto separateCHANGES.txtfile.The--no-buildoutoption is no longer ignored now.Added abin/pythonscript that mimicks an interpreter.Enabled the APIDoc tool by default.  You may access it underhttp://localhost:8080/++apidoc++.Simplified*package*/testing.py.0.4 (2007-09-15)New featuresAdded a zdaemon controller script much like zopectl called*package*-ctl(where*package*is the name of the package
created with zopeproject).Added a debug script called*package*-debugthat configures the
application and drops into an interpreter session.  It is also
available via*package*-ctldebug.Addeddebug.iniwhich configures a WSGI middleware for
intercepting exceptions and live debugging (either using Paste’s
evalexception middleware or the Python debuggerpdb).Added a functional test layer in*package*.testingwhich loads
the newftesting.zcml.  Convenience definitions of test suites
pre-configured for that layer are available in*package*.testingas well.More improvements to the README.txt file.Bugfixes and restructuringMake use ofzope.app.wsgi.getApplication()to reduce the startup
boiler-plate instartup.py(formerlyapplication.py).The package that zopeproject creates is now located in asrcdirectory, where it’s easier to single out among the other files and
directories.Fixed a bug when guessing the default eggs-directory: When
~/.buildout/default.cfg did not contain an eggs-directory option,
zopeproject failed with a ConfigParser.NoOptionError.Renamedapplication.pytostartup.pyto make the intent of
the module much clearer, and to avoid clashes with e.g. Grok (where
“application” means something else, andapp.pyis commonly used
for the application object).The eggs directory will no longer be written tobuildout.cfgif
it is the same as the buildout default in~/.buidout/default.cfg.Cleaned up and enhanced the dependencies of the generated
application.  It no longer depends on zope.app.securitypolicy, only
the deployment (site.zcml) does.  Obsolete dependencies (and
their include statements in ZCML) have been removed.zope.app.catalogand friends have been added as a convenience.0.3.2 (2007-07-17)If the user already has a default eggs directory set in~/.buildout/default.cfg, it is used as the default value for the
eggs directory.Greatly improved the README.txt file.0.3.1 (2007-07-15)Thebuildout.cfgtemplate was missing settings for the shared
eggs directory and thewnewestflag.Assemble the default path for the eggs directory in a
Windows-friendly way.0.3 (2007-07-14)Renamed tozopeproject.Incorporated much of thegrokproject0.5.x infrastructure.  This
makes it much more robust, especially when launching zc.buildout.Mergedmake-zope-appanddeploy-zope-appback into one
command:zopeproject.0.2 (2007-07-12)Renamed tomake-zope-app.Splitmkzopeappinto two commands:make-zope-appanddeploy-zope-app.No longer usezope.pastefor the application factory.  Instead,
each application that’s created from the skeleton defines its own
factory (which is reasonably small and gains flexibility).Get rid of thestart<<Project>>script.  Simply usebin/paster serve deploy.inifor starting the server.Use thePaste#httpserver by default.0.1 (2007-07-06)Initial release asmkzopeapp