.. contents:: Table of Contents
:depth: 2
BlueBream
*********
Introduction
------------
`BlueBream <http://bluebream.zope.org>`_ -- formerly known as **Zope
3** -- is a web framework written in the Python programming language.
BlueBream is free/open source software, owned by the `Zope Foundation
<http://foundation.zope.org>`_, licensed under the `Zope Public
License <http://foundation.zope.org/agreements/ZPL_2.1.pdf>`_ (BSD
like, GPL compatible license).
Features
--------
Here are the features distinguishing BlueBream from other Python web frameworks:
- BlueBream is built on top of the `Zope Toolkit
<http://docs.zope.org/zopetoolkit>`_ (ZTK), which has many years of
experience proving it meets the demanding requirements for stable,
scalable software.
- BlueBream uses the powerful and familiar Buildout_ building system written in
Python.
- BlueBream employs the Zope Object Database ZODB_, a transactional
object database, providing extremely powerful and easy to use
persistence.
- BlueBream registers components with Zope Component Markup Language
(`ZCML <http://www.muthukadan.net/docs/zca.html#zcml>`_), an XML
based configuration language, providing limitless flexibility.
- BlueBream features the `Zope Component Architecture
<http://muthukadan.net/docs/zca.html>`_ (ZCA) which implements
*Separation of concerns* to create highly cohesive reusable
components (zope.component_).
- BlueBream implements the `WSGI` specification (`Web Server Gateway Interface
<http://www.wsgi.org/wsgi>`_) with the help of `PasteDeploy
<http://pythonpaste.org/deploy>`_.
- BlueBream includes a number of well tested components to implement
common activities. A few of these are:
- zope.publisher_ publishes Python objects on the web, emphasizing
`WSGI <http://www.wsgi.org/wsgi>`_ compatibility
- zope.security_ provides a generic mechanism for pluggable
security policies
- zope.testing_ and zope.testbrowser_ offer unit and functional testing
frameworks
- zope.pagetemplate_ is an XHTML-compliant language for developing
templates
- zope.schema_ is a schema engine to describe your data models
- zope.formlib_ is a tool for automatically generating forms from your schemas
.. _Buildout: http://www.buildout.org
.. _ZODB: http://www.zodb.org
.. _zope.component: http://pypi.python.org/pypi/zope.component
.. _zope.publisher: http://pypi.python.org/pypi/zope.publisher
.. _zope.security: http://pypi.python.org/pypi/zope.security
.. _zope.testing: http://pypi.python.org/pypi/zope.testing
.. _zope.testbrowser: http://pypi.python.org/pypi/zope.testbrowser
.. _zope.pagetemplate: http://pypi.python.org/pypi/zope.pagetemplate
.. _zope.schema: http://pypi.python.org/pypi/zope.schema
.. _zope.formlib: http://pypi.python.org/pypi/zope.formlib
Installation
------------
If you have installed `setuptools
<http://pypi.python.org/pypi/setuptools>`_ or `distribute
<http://pypi.python.org/pypi/distribute>`_ an ``easy_install``
command will be available. Then, you can install BlueBream using
``easy_install`` command like this::
$ easy_install bluebream
Internet access to `PyPI <http://pypi.python.org/pypi>`_ is required
to perform installation of BlueBream.
The ``bluebream`` distribution provides a quick project
creation tool based on PasteScript templates. Once BlueBream is installed,
run ``paster`` command to create the project directory structure.
The ``create`` sub-command provided by paster will show a wizard to
create the project directory structure.
::
$ paster create -t bluebream
This will bring a wizard asking details about your new project. If you provide
a package name and version number, you will get a working application which can
be modified further. The project name will be used as the egg name. You can
also change the values provided later.
The project name can be given as a command line argument::
$ paster create -t bluebream sampleproject
You can provide a dotted name so that the package be created in a namespace,
with any number of levels, such as "sample.main" or "sample.app.main". It will
result in a nested structure allowing you to split large projects into several
packages.
If you provide an option from the command line, it will not be
prompted by the wizard. The other variables are given below, you can
give the values from the command line, if required:
- ``interpreter`` -- Name of the custom Python interpreter
- ``bluebream`` -- The version of BlueBream
- ``version`` -- The version of your project (eg:- 0.1)
- ``description`` -- One-line description of the package
- ``long_description`` -- Multi-line description (in reStructuredText)
- ``keywords`` -- Space-separated keywords/tags
- ``author`` -- Author name
- ``author_email`` -- Author email
- ``url`` -- URL of the homepage
- ``license_name`` -- License name
If you are in a hurry, you can simply press *Enter/Return* key and
change the values later. But it would be a good idea, if you provide
a good name for your project.
Usage
-----
The generated package is bundled with Buildout configuration and the
Buildout bootstrap script (``bootstrap.py``). First you need to
bootstrap the buildout itself::
$ cd sampleproject
$ python bootstrap.py
The bootstrap script will install the ``zc.buildout`` and ``distribute``
packages. Also, it will create the basic directory structure. Next step is
building the application. To build the application, run the buildout::
$ ./bin/buidout
The buildout script will download all dependencies and setup the
environment to run your application.
The most common thing you need while developing an application is
running the server. BlueBream use the ``paster`` command provided by
PasteScript to run the WSGI server. To run the server, you can pass
the PasteDeploy configuration file as the argument to ``serve``
sub-command as given here::
$ ./bin/paster serve debug.ini
Once you run the server, you can access it here:
http://localhost:8080/ . The port number (``8080``) can be changed
from the PasteDeploy configuration file (``debug.ini``).
The second most common thing must be running the test cases.
BlueBream creates a testrunner using the ``zc.recipe.testrunner``
Buildout recipe. You can see a ``test`` command inside the ``bin``
directory. To run test cases, just run this command::
$ ./bin/test
Sometimes you may want to get the debug shell. BlueBream provides a
Python prompt with your application object. You can invoke the debug
shell like this::
$ ./bin/paster shell debug.ini
More about the test runner and debug shell will be explained in the
BlueBream Manual. You can continue reading about BlueBream from the
`documentation site <http://bluebream.zope.org>`_.
Resources
---------
- `Website with documentation <http://bluebream.zope.org>`_
- `Project blog <http://bluebream.posterous.com>`_
- The bugs and issues are tracked at `launchpad
<https://launchpad.net/bluebream>`_.
- `BlueBream Wiki <http://wiki.zope.org/bluebream>`_
- `PyPI Home <http://pypi.python.org/pypi/bluebream>`_
- `Twitter <http://twitter.com/bluebream>`_
- `Mailing list <https://mail.zope.org/mailman/listinfo/bluebream>`_
- IRC Channel: `#bluebream at irc.freenode.net <http://webchat.freenode.net/?randomnick=1&channels=bluebream>`_
- `Buildbot <http://buildbot.afpy.org/bluebream>`_
- The source code is managed at `Zope reposistory
<http://svn.zope.org/bluebream>`_. You can perform a read-only
checkout of trunk code like this (Anonymous access)::
svn co svn://svn.zope.org/repos/main/bluebream/trunk bluebream
You can also `become a source code contributor (committer) after signing a
contributor agreement
<http://docs.zope.org/developer/becoming-a-committer.html>`_
You can see `more details about contributing in wiki
<http://wiki.zope.org/bluebream/ContributingToBlueBream>`_.
Changelog
*********
1.0 (2011-01-18)
----------------
- Include `zope.location`, `zope.keyreference`, `zope.intid` and
`zope.contentprovider`, `zope.i18n`
from `site.zcml` file.
- Reorganized zcml files (for deploy, debug and testing)
- updated to ZTK 1.0.1
1.0b4 (2010-08-26)
------------------
- Change custom interpreter name: s/breampy/bbpy
- Fixed the generated buildout and make it repeatable
- Added the "extends-cache" Buildout option to cache
the extended configuration files
- warn the user if the project template has significant changes
- Added empty overrides.zcml - show best practices to developers
- updated to ZTK 1.0a3
- Automatically find and suggest the latest *minor* version online
- added zope.app.http registrations to get the correct unauthorized view
1.0b3 (2010-07-11)
------------------
- Directly depend on the ZTK!
- Removed the bbkit package
- Ask the version of BlueBream at project creation
- Automatically find and suggest the latest version online
1.0b2 (2010-06-30)
------------------
- Include zope.error & zope.principalregistry from site.zcml
1.0b1 (2010-04-27)
------------------
- Set `name` & `description` for the sample application
- Use project name as i18n_domain in base template
- Merge the two templates into a single one by allowing to create a
flat or nested namespace structure, and choose the package name.
- Enabled Distribute by default instead of Setuptools
- Added zope.app.schema registrations to be able to register a named vocabulary
- removed buildout templating and include two zope.conf files,
one for deployment and one for debugging with devmode
1.0a5 (2010-03-28)
------------------
- Include the sample application in the `bluebream_simple` template
- Move the sample application provided by `bluebream` template
to a sub-package named `welcome` similar to `bluebream_simple`
The sample application can be easily removed.
- The sample application object use 'zope.site.interfaces.IFolder`
instead of `zope.container.interfaces.IContainer`
- Include `zope.session` from `site.zcml`
- Include `browser` namespace in `site.zcml` for convenience.
- Added an empty `[versions]` part in `versions.cfg` with
a recommendation to pin-down versions of other dependencies.
- Remove `zope.app.twisted` from dependency list
- Since BlueBream requires ZODB 3.9, FileStorage need not be
wrapped with BlobStorage proxy to get ZODB blobs support.
- The default ZODB blob layout should be 'bushy'
Fix LP #543525
- Use relative paths in etc/zope.conf Fix LP #543451
- Specify i18n domain in ftesting.zcml Fix LP #543516
- zope.browserresource package registration was missing
Fix LP #541457
1.0a4 (2010-03-07)
------------------
- Added an empty PKG-INFO
Work around fix for "empty directory" problem.
(refer: LP #503301)
1.0a3 (2010-03-07)
------------------
- The summary of ``bluebream_base`` template changed to:
"A BlueBream project, base template"
- Enable ``bluebream_simple`` again. Documentation is
available here:
http://wiki.zope.org/bluebream/AlternateProjectTemplates
1.0a2 (2010-03-02)
------------------
- Use a template to display default page for the root
folder
- Use ``zope.formlib.form.DisplayForm`` as base class for
views instead of ``zope.publisher.browser.BrowserView``
- Sample application add form view name is changed from
``@@add`` to ``@@add_sample_app``
- Add links to to BlueBream website & mailing list
- Added license file
- Improve "Usage" section in README.txt
- Include ``zest.release`` to prepare release
- Include ``bluebream_simple`` template (This will not be released
with 1.0a2 as the documentation is not ready yet)
- Move ``bluebream`` template code to ``bluebream_base``
- Add static resource directory with CSS to ``bluebream_base``
(based on ``bluebream_simple``). The new style applied to main page.
1.0a1 (2010-02-06)
------------------
- Use released package distribution versions:
http://download.zope.org/bluebream/bluebream-1.0a1.cfg
- Include new packages to `site.zcml` template:
- `zope.app.publisher.xmlrpc` (meta.zcml)
- `zope.copypastemove`
- `zope.app.pagetemplate`
- Changed template summary into: A BlueBream project
- Removed `Sphinx-PyPI-upload` -- no more used as the
website is moved to http://bluebream.zope.org
- Added `zope.traversing.browser` from site.zcml
in the project template. Ref: http://bit.ly/80xltO
0.1.9 (2010-01-13)
------------------
- LP #506879: debug shell added. Basic usage::
./bin/paster shell debug.ini
0.1.8 (2010-01-12)
------------------
- Use `zope` ZCML namespace as default in configure.zcml
- Documentation improvements
- Create a sample application by default
0.1.7 (2010-01-10)
------------------
- Update version: zope.tales = 3.5.0
- LP #505362: Fix. Main package name is hard-coded as 'main'
- Change 'defaultView' registration location and interface
- LP #505413: Name of default custom Python interpreter
should be able to customize
0.1.6 (2010-01-07)
------------------
- LP #502819: Main page after a fresh installation
- Removed ``hello`` view from template.
- LP #502941: Add trove classifiers.
- Mention all resources in PyPI page.
0.1.5 (2010-01-07)
------------------
- LP #503388: Value of "namespace_package" should not be
empty string.
- Updated description, added promotional video.
0.1.4 (2010-01-04)
------------------
- LP #503301: Work around fix for "empty directory" problem.
- Change author as "BlueBream" team and email to zope-dev list.
0.1.3 (2010-01-04)
------------------
- LP #502817: var directory and its subdirectories not exist
- Documentation improvements: added "Usage" section
0.1.2 (2010-01-03)
------------------
- Added functional testing support for project
- Sphinx based documentation infrastruture improvements
- LP #502529: Update wizard to ask all package meta to
be updated in setup.py
0.1.1 (2010-01-02)
------------------
- Fix missing package data. The 0.1.0 releases was broken.
- Improve documentation.
0.1.0 (2010-01-02)
------------------
- Initial release.
Download
********