zopeproject 0.4.1

Notes for Windows users

Some 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 the Microsoft Visual C compiler installed. You can, however, install the free MinGW compiler:

1. Download MinGW-x.y.z.exe and rund it to do a full install into the standard location (C:\MinGW).

2. Tell Python to use the MinGW compiler by creating C:\Documents and Settings\YOUR USER\pydistutils.cfg with the following contents:

   [build]
   compiler=mingw32

3. Let Python know about the MinGW installation and the pydistutils.cfg file. To do that, go to the Control Panel, System section, Advanced tab and click on the Environment variables button. Add the C:\MinGW\bin directory to your Path environment variable (individual paths are delimited by semicolons). Also add another environment variable called HOME with the following value:

   C:\Documents and Settings\YOUR USER

When installing packages from source, Python should now use the MinGW compiler to build binaries.

Sharing eggs among sandboxes

A great feature of zc.buildout is the ability to share downloaded Python packages (“eggs”) between sandboxes. This is achieved by placing all eggs in a central location. zopeproject will ask for this location each time. The setting will become part of buildout.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 in buildout.cfg because they hinder the repeatibility of the setup on other machines.

A way to solve these problems is to configure a system-wide default eggs directory for buildout in ~/.buildout/default.cfg:

[buildout]
eggs-directory = /home/philipp/eggs

zopeproject 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 generated buildout.cfg will not contain a reference to path.

What are the different files and directories for?

deploy.ini

Configuration file for PasteDeploy. It defines which server software to launch and which WSGI application to invoke upon each request (which is defined in src/helloworld/startup.py). You may also define WSGI middlewares here. Invoke bin/paster serve with this file as an argument.

debug.ini

Alternate configuration for PasteDeploy that configures a middleware which intercepts exceptions for interactive debugging. See Debugging exceptions below.

zope.conf

This file will be read by the application factory in src/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.zcml

This file is referred to by zope.conf and will be loaded by the application factory. It is the root ZCML file and includes everything else that needs to be loaded. That typically is just the application package itself, helloworld, which then goes on to include its dependencies. Apart from this, site.zcml also defines the anonymous principal and the initial admin principal.

setup.py

This file defines the egg of your application. That includes the package’s dependencies (mostly Zope eggs) and the entry point for the PasteDeploy application factory.

buildout.cfg

This file tells zc.buildout what to do when the buildout is executed. This mostly involves executing setup.py to enable the HelloWorld egg (which also includes downloading its dependencies), as well as installing PasteDeploy for 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. The src directory will be placed on the interpreter’s search path by zc.buildout.

var/

The ZODB filestorage will place its files (Data.fs, lock files, etc.) here.

Renaming

You can rename or move the sandbox directory any time you like. Just be sure to run bin/buildout again after doing so. Renaming the sandbox directory won’t change the name of the egg, however. To do that, you’ll have to change the name parameter in setup.py.

Sharing and archiving sandboxes

You 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 recommended not to include the following files and directories because they can and will be generated by zc.buildout from the configuration files:

• bin/

• parts/

• develop-eggs/

• all files in var/

• all files in log/

• .installed.cfg

If 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 the bin/buildout executable. To do that, use the buildout script from any other sandbox on your machine:

$ .../path/to/some/sandbox/bin/buildout bootstrap

Now the sandbox has its own bin/buildout script and can be installed:

$ bin/buildout

First steps with your application

After having started up Zope for the first time, you’ll likely want to start developing your web application. Code for your application goes into the helloworld package that was created by zopeproject in the src directory.

For example, to get a simple “Hello world!” message displayed, create src/helloworld/browser.py with 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 of src/helloworld/configure.zcml:

<browser:page
    for="*"
    name="hello"
    class=".browser.HelloPage"
    permission="zope.Public"
    />

Note that you’ll likely need to define the browser namespace 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 using paster serve, you can visit http://localhost:8080/hello to see the page in action.

Adding dependencies to the application

The standard setup.py and configure.zcml files 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 are listed on the Python Cheeseshop.

Let’s say you wanted to reuse the some.library package in your application. The first step would be to add it to the list of dependencies in setup.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 to src/helloworld/configure.zcml:

<include package="some.library" />

After having changed setup.py, you would want the newly added dependency to be downloaded and added to the search path of bin/paster. To do that, simply invoke the buildout:

$ bin/buildout

Writing and running tests

Automated tests should be placed in Python modules. If they all fit in one module, the module should simply be named tests. If you need many modules, create a tests package and put the modules in there. Each module should start with test (for example, the full dotted name of a test module could be helloworld.tests.test_app).

If you prefer to separate functional tests from unit tests, you can put functional tests in an ftests module 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 a test_suite function 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 the bin/test script:

$ bin/test

Functional tests

While 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 is ftesting.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 the helloworld.testing.FunctionalLayer layer to it:

from helloworld.testing import FunctionalLayer
suite.layer = FunctionalLayer

You can also simply use one of the convenience test suites in helloworld.testing:

• FunctionalDocTestSuite (based on doctest.DocTestSuite)

• FunctionalDocFileSuite (based on doctest.DocFileSuite)

• FunctionalTestCase (based on unittest.TestCase)

The interpreter prompt

Use the bin/python script 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 prompt

Occasionally, 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 under bin/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 exceptions

In case your application fails with an exception, it can be useful to inspect the circumstances with a debugger. This is possible with the z3c.evalexception WSGI middleware. When an exception occurs in your application, stop the process and start it up again, now using the debug.ini configuration file:

$ bin/paster serve debug.ini

When you now 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 debugger pdb, replace ajax with pdb in the WSGI middleware definition in debug.ini:

[filter-app:main]
use = egg:z3c.evalexception#pdb
next = zope

Note: 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.

Disabling debugging tools

Before deploying a zopeproject-based application, you should make sure that any debugging tools are disabled. In particular, this includes

• making sure there’s no debugging middleware in deploy.ini (normally these should be configured in debug.ini anyway),

• switching off developer-mode in zope.conf,

• disabling the APIDoc tool in site.zcml,

• disabling the bootstrap administrator principal in site.zcml.

Linux/Unix

You can use the helloworld-ctl script to start the server process in daemon mode. It works much like the apachectl tool as known from the Apache HTTPD server or INIT scripts known from Linux:

$ bin/helloworld-ctl start

To stop the server, issue:

$ bin/helloworld-ctl stop

Other commands, such as status and restart are supported as well.

Windows

There’s currently no particular support for deployment on Windows other than what paster provides. Integration with Windows services, much like what could be found in older versions of Zope, is planned.

0.4.1 (2007-09-29)

• Improvements to README.txt and var/README.txt (it was pointing to the wrong configuration file). Moved changelog from README.txt into separate CHANGES.txt file.

• The --no-buildout option is no longer ignored now.

• Added a bin/python script that mimicks an interpreter.

• Enabled the APIDoc tool by default. You may access it under http://localhost:8080/++apidoc++.

• Simplified *package*/testing.py.

0.4 (2007-09-15)

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)

• The buildout.cfg template was missing settings for the shared eggs directory and thew newest flag.

• Assemble the default path for the eggs directory in a Windows-friendly way.

0.3 (2007-07-14)

• Renamed to zopeproject.

• Incorporated much of the grokproject 0.5.x infrastructure. This makes it much more robust, especially when launching zc.buildout.

• Merged make-zope-app and deploy-zope-app back into one command: zopeproject.

0.2 (2007-07-12)

• Renamed to make-zope-app.

• Split mkzopeapp into two commands: make-zope-app and deploy-zope-app.

• No longer use zope.paste for 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 the start<<Project>> script. Simply use bin/paster serve deploy.ini for starting the server.

• Use the Paste#http server by default.

0.1 (2007-07-06)

Initial release as mkzopeapp