Bluebream Documentation Release 1.0A4

BlueBream Documentation Release 1.0a4

Zope Foundation

March 10, 2010

CONTENTS

1 Introduction 3 1.1 Overview...... 3 1.2 Join our community...... 4 1.3 Brief history...... 4 1.4 More about the project...... 5 1.5 Organization of the documentation...... 5 1.6 Thanks...... 6

2 What’s New ? 9 2.1 What’s new in BlueBream 1.0 ?...... 9

3 Getting Started 129 3.1 Introduction...... 129 3.2 Preparations...... 129 3.3 Installation...... 130 3.4 Creating a sample project...... 130 3.5 Building the application...... 132 3.6 Basic usage...... 133 3.7 Package directory structure...... 134 3.8 Example 1: Hello World without page template...... 136 3.9 Example 2: Hello World with page template...... 137 3.10 Example 3: A dynamic hello world...... 138 3.11 Conclusion...... 139

4 Concepts and Technologies 141 4.1 Concepts...... 141 4.2 Technologies...... 146

5 Tutorial — Part 1 149 5.1 Introduction...... 149 5.2 Starting a new project...... 149 5.3 The site deﬁnition...... 156 5.4 The package meta-data...... 157 5.5 Running Tests...... 159 5.6 Creating the application object...... 159 5.7 Creating the main page...... 164 5.8 Conclusion...... 165

6 Tutorial — Part 2 167 6.1 Introduction...... 167

i 6.2 Adding tickets...... 167 6.3 Listing tickets...... 171 6.4 Adding Comments...... 172 6.5 Conclusion...... 173

7 Manual 175 7.1 Browser Resource...... 175 7.2 Browser Page...... 176 7.3 Unit Testing...... 177 7.4 Interface...... 179 7.5 Zope Component Architecture...... 182 7.6 Content Component...... 188 7.7 Conﬁguration...... 190 7.8 Startup...... 192 7.9 Functional Testing...... 193 7.10 Skinning...... 195 7.11 Zope Schemas and Widgets...... 198 7.12 Forms...... 206

8 FAQ 207 8.1 General...... 209 8.2 Concepts...... 211 8.3 Security...... 211 8.4 User Interface...... 213 8.5 Programming...... 216 8.6 Conﬁguration and Setup...... 222 8.7 Miscellaneous...... 225

9 HOWTOs 231 9.1 Default view for objects...... 231 9.2 Adding new package dependency...... 232 9.3 Retrieving absolute URL for an object...... 233 9.4 Dynamic ﬁelds in forms...... 234 9.5 Testing persistent objects...... 234

10 Core Development 237 10.1 Contributing to BlueBream...... 237 10.2 Developer Resources...... 237 10.3 Developing BlueBream...... 238 10.4 Technical Decisions...... 238 10.5 Documentation Writing Guidelines...... 239

11 Reference 243 11.1 zope.app.wsgi — WSGI Application...... 243

12 Glossary 247

13 Contributors 249 13.1 Logo Design...... 249 13.2 Other Contributors...... 249

14 Indices and tables 251

Module Index 253

Index 255

ii BlueBream Documentation, Release 1.0a4

Release 1.0a4 Date March 09, 2010

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

CONTENTS 1 BlueBream Documentation, Release 1.0a4

2 CONTENTS CHAPTER ONE

INTRODUCTION

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

1.1 Overview

BlueBream is a web framework written in the Python programming language. BlueBream is free/open source software, owned by the Zope Foundation, licensed under the Zope Public License (BSD like, GPL compatible license). BlueBream was previously known as Zope 3. A few of the features which distinguish BlueBream among Python web frameworks. • BlueBream is built on top of the Zope Tool Kit (ZTK), a distillation of many years of experience in meeting demanding requirements for stable, scalable software. • BlueBream leverages the power of Buildout a build system written in Python. • BlueBream uses the ZODB transactional object database, providing extremely powerful and easy to use persistence. • BlueBream uses ZCML, an XML based configuration language for registering components, providing limitless flexibility. If you don’t need the power of ZCML and the complexity it adds, try GROK, which adds a layer replacing the declarative configuration of ZCML with conventions and declarations in standard Python. • BlueBream features the Zope Component Architecture (ZCA) which implements Separation of concerns to create highly cohesive reusable components (zope.component). • BlueBream supports WSGI using Paste, PasteScript, and PasteDeploy. • BlueBream includes a number of components which provide well tested implementation of common requirements. A few are of these are: – zope.publisher publishes Python objects on the web, it is geared towards WSGI compatibility – zope.security provides a generic mechanism supporting pluggable security policies – zope.testing and zope.testbrowser offer unit and functional testing frameworks – zope.pagetemplate is an xhtml-compliant templating language – zope.schema and zope.formlib provide a schema engine and automatic form generation machinery

3 BlueBream Documentation, Release 1.0a4

1.2 Join our community

We invite you to become part of our community! You can become part of our community by joining/subscribing to these community platforms: • Mailing list: https://mail.zope.org/mailman/listinfo/bluebream • Twitter: http://twitter.com/bluebream • Blog: http://bluebream.posterous.com • IRC channel: #bluebream at freenode.net • Wiki: http://wiki.zope.org/bluebream • Ohloh.net: https://www.ohloh.net/p/bluebream • PyPi home : http://pypi.python.org/pypi/bluebream BlueBream developer community is an active community involved in the development of BlueBream itself. We are looking for contributors to this project. All the development related information in documented in the wiki. You can read this wiki page fore information: http://wiki.zope.org/bluebream/ContributingToBlueBream We aim to provide high quality free online documentation for BlueBream. If you would like to contribute, the Re- structuredText source for this website is available from the zope.org repository (please replace USERNAME with your zope.org username.):

svn co svn+ssh://[email protected]/repos/main/bluebream/website

If you don’t have svn commit access, please consult: becoming a contributor document. For any queries, please contact us in mailing list or irc chat, we can help you to get reference committer, which is required to ﬁll the contributor agreement form.

1.3 Brief history

Our story begins in 1996, Jim Fulton was technical director at digital creations. At the IPC (International Python Conference) that year, Jim gave a presentation on CGI: Python and Internet Programming. Jim, considering CGI less than elegant, envisioned a better way to program for the internet in Python. According to legend, Jim learned CGI on the plane to the conference, and designed Bobo on the plane ride back home. Digital creations then released three open-source Python software packages: Bobo, Document Template, and Bobopos. These packages provided a web publishing facility, text templating, and an object database and were the core of Principia, a commercial application server. In november of 1998, investor Hadar Pedhazur convinced Digital Creations to open source Principia. These packages evolved into the core components of Zope 2, and Digital Creations became Zope Corporation. Since those days, Zope has been under active development. It has evolved in several ways as the community gains experience. We continually seek the optimum balance between power and ease of use. Zope 2 emphasized rapid development, the Zope Component Architecture, which is the core of Zope 3, emphasized modularity and configurability. This proves very successful in “enterprise” applications where flexibility and scalability justify the longer learning curve which Zope 3 requires, but is overkill for many situations which otherwise stand to benefit from the distilled wisdom of the ZCA. The Zope community has responded to this in a number of ways, several projects have built frameworks which implement Convention over configuration, and other refinements of the ZCA components aimed at facilitating rapid deployment, maintaining the power of ZCA under the hood. Notable among these are grok and Repoze.

4 Chapter 1. Introduction BlueBream Documentation, Release 1.0a4

Zope 3 is now known as BlueBream. The name stems from the fact that the Z Object Publishing Environment, when spelled zope, is the name of a fish. Another name for the fish is blue bream. BlueBream presents a well defined (and documented) configuration framework which simplifies managing of the power of the ZCA. We’ve brought together ZCA, Buildout and Sphinx in a way that makes building powerhouse applications fun. The components which comprise BlueBream are under continual development by an international team of experienced coders. Take a look at the recent uploads to the PyPi site, it is rare to not see several zca projects listed.

1.4 More about the project

As mentioned earlier, BlueBream is a web framework based on Zope technology. BlueBream utilizes the Zope Toolkit (ZTK) and is the successor and logical upgrade path from the Zope 3 application server, also known as “Zope 3”. This section will show the position of BlueBream in the wider Zope ecosystem. Zope 3 was conceived as a fresh start to leave certain aspects and limitations of its presumed predecessor Zope 2 behind. Zope 3 introduced a new component architecture to address some of the inheritance-based-programming limitations of Zope 2. The Zope Component Architecture (aka ZCA), notionally includes the packages named zope.component, zope.interface and zope.configuration. As well as the ZCA packages at its core, Zope 3 offered a large number of extra libraries and provided an application server that enabled programmers to develop standalone web applications. The original intent of Zope 3 was to become a replacement for Zope 2. However, this did not happen as planned. Instead, Zope 2 continued to make up the majority of new Zope deployments, due mostly to the popularity of Plone. In the meantime, another wave of web frameworks appeared. grok evolved with many Zope 3 libraries at its core. repoze.bfg (aka BFG) evolved around the ZCA. Additionally, Zope 2 began to make use of the ZCA and various other Zope 3 packages. In 2009, a group of Zope developers agreed to concentrate primarily on the development of the Zope 3 libraries and formed the Zope Toolkit (ZTK) that focusses on a slim library subset of the Zope 3 project, which can then be efﬁciently utilized by web application frameworks on top. This development led to the following logical steps: • Form a project around the remaining web application part of Zope 3 • Name it BlueBream as a new, unique name to avoid confusion • Create an upgrade path from the former Zope 3 application server BlueBream can thus be seen as the successor of Zope 3 web application server; along with Grok, it relies on the ZTK.

1.5 Organization of the documentation

This documentation has divided into multiple chapters. Summary of each chapter is given below.

1.5.1 Introduction

This chapter introduce BlueBream with an Overview and Brief history. Then walks through the More about the project. Finally, ends with Thanks section.

1.4. More about the project 5 BlueBream Documentation, Release 1.0a4

1.5.2 Getting Started

The Getting Started chapter narrate the process of creating a new web application project using BlueBream. Also it gives few exercises to familiarize the basic concepts in BlueBream.

1.5.3 Concepts

This chapter discuss important concepts and technologies used in BlueBream.

1.5.4 Tutorial — Part 1

We demonstrate how to build a simple ticket collector application using BlueBream. Part 1 introduces basic BlueBream concepts.

1.5.5 Tutorial — Part 2

Part 2 continues the ticket collector application, providing more detail on forms and schemas.

1.5.6 Manual

This is a comprehensive guide to BlueBream.

1.5.7 FAQ

These are FAQs collected from mailing lists, blogs and other on-line resources.

1.5.8 HOWTOs

Small documents focusing on speciﬁc topics.

1.5.9 Core Development

These documents are written for core development team. Always visit the latest documentation site for recent version of these documents which is actually used by the developers.

1.5.10 Reference

A complete reference to BlueBream.

1.6 Thanks

BlueBream truly stands on the shoulders of giants. The Zope 3 concepts built on Zope 2 which was built on Bobo and friends. The list of Zope Corporation alumni is a Who’s Who of Python, including one Guido Van Rossum. Contributions from the larger community have come from all over the world, for more than 10 years. We thank you all. Please help us and add to the list of contributer names as we move forward from January 2010.

6 Chapter 1. Introduction BlueBream Documentation, Release 1.0a4

Contributors

1.6. Thanks 7 BlueBream Documentation, Release 1.0a4

8 Chapter 1. Introduction CHAPTER TWO

WHAT’S NEW ?

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

2.1 What’s new in BlueBream 1.0 ?

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

2.1.1 Migration issues

zope.app.keyreference -> zope.keyreference

This package was renamed to zope.keyreference and all its functionality was moved to the new one. The new package contains a little workaround for making old persistent keyrerefences loadable without zope.app.keyreference installed, so the latter one is not needed at all anymore. Still review your code for any imports coming from zope.app.keyreference and modify it to use zope.keyreference instead.

zope.app.intid -> zope.intid

The non-UI functionality of these packages was moved to zope.intid with backwards compatibility imports left in place. Review your imports from zope.app.intid to see whether they cannot come directly from zope.intid instead.

zope.app.catalog -> zope.catalog

The non-UI functionality of these packages was moved to zope.catalog. Review your imports from zope.app.catalog to see whether they cannot come directly from zope.catalog instead.

zope.app.container -> zope.container

The non-UI functionality of these packages was moved to zope.container. Review your imports from zope.app.container to see whether they cannot come directly from zope.container instead.

9 BlueBream Documentation, Release 1.0a4

In addition, the exceptions used by zope.container were changed, so if your code catches them, you need to review it: • The DuplicationError in setitem was changed to KeyError. • The UserError in NameChooser was changed to ValueError.

zope.app.component -> zope.security, zope.site

The implementation of the ZCML directive moved from this package to zope.security. Packages that relied on zope.app.component to obtain this directive should declare a direct dependency on zope.security, and it may be possible to lose the dependency on zope.app.component altogether. Non-UI site related functionality has been moved to the zope.site package. with backwards compatibility imports left in place. Review your imports from zope.app.component to see whether they cannot come directly from zope.site instead.

zope.app.folder -> zope.site, zope.container

The implementation of the zope.app.folder.Folder class has moved to zope.site.folder instead, with backwards compatibility imports left in place. Review your imports from zope.app.folder to see whether they cannot come directly from zope.site instead. In addition, Folder is an IContainer implementation that also mixes in site management functionality. If such site management support is not necessary, in some cases your code does not need Folder but may be able to rely on a Container implementation from zope.container instead. A base class with the implementation of the container-like behavior of Folder has moved to zope.container (and zope.site uses this for its implementation of Folder). This is not normally something you should need to retain backwards compatibility. zc.copy -> zope.copy, zope.copypastemove, zope.location

The pluggable object copying mechanism once developed in the zc.copy package was merged back into zope.location, zope.copypastemove and the new zope.copy package. The zope.copy package now provides a pluggable mechanism for copying objects from zc.copy and doesn’t depend on anything but zope.interface. The zope.copypastemove uses the copy function from zope.copy in its ObjectCopier. The zope.location now provides an ICopyHook adapter that implements conditional copy functionality based on object locations, that old zope.location.pickling.CopyPersistent used to provide. Note, that if you don’t use ZCML conﬁguration of zope.location, you may need to register zope.location.pickling.LocationCopyHook yourself. The zope.location.pickling.locationCopy and zope.location.pickling.CopyPersistent are now deprecated in favor of zope.copy and were replaced by backward-compatibility imports. See zope.copy package documentation for information on how to use the new mechanism. The new version of the zc.copy package now only contains backward-compatibility imports and is deprecated. zope.copy should be preferred for new developments. zope.app.security refactoring

The zope.app.security package was ﬁnally refactored into a few small parts with less dependencies and more clear purpose.

10 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

The implementation of the ZCML directive moved from this package to zope.security. Pack- ages that relied on zope.app.security to obtain this directive should declare a direct dependency on zope.security, and it may be possible to lose the dependency on zope.app.security altogether. The protectclass module in this package has moved to zope.security, with backwards compatibility imports left in place. Review your imports from zope.app.security to see whether they cannot come directly from zope.security instead. All interfaces (IAuthentication, IUnauthenticatedPrincipal, ILoginPassword and so on.) were moved into a new zope.authentication package, as well as several utility things, like PrincipalSource and checkPrincipal function. The new package has much less dependencies and defines an abstract contracts for implementing authentication within Zope Framewowk. While backward compatibility imports are left in place, it’s strongly reccommended to update your imports to the zope.authentication. The global principal registry and its ZCML directives are moved into a new zope.principalregistry package with backward-compatibility imports left in place. If your application uses global principals, review your code and ZCML configuration to update it to the new place. The local permission functionality was moved into a new zope.app.localpermission package. This functionality is a part of Through-The-Web development pattern that seems not to be used and supported much by Zope Toolkit and Application anymore, so it can be considered deprecated. However, it can serve as a great example of TTW-related component. The Permission vocabularies and standard protections for Message objects and __name__, __parent__ attributes as well as some common permissions, like zope.View and zope.ManageContent were merged into zope.security. The adapters from zope.publisher‘s IHTTPCredentials and IFTPCredentials to the ILoginPassword were moved into zope.publisher, thus making zope.authentication a dependency for zope.publisher. The original zope.app.security package now only contains several deprecated or application-specific permission definitions, python module protections, that are only likely to be needed with deprecated Through-The-Web development pattern, and ZMI-related browser views (login.html, zope.app.form view for PrincipalSource and so on), as well as backward-compatibility imports. So, if you’re not using TTW and/or standard ZMI browser views, you probably should review update your imports to a new places and drop dependency on zope.app.security to reduce package dependencies count. Other packages, that used zope.app.security, like zope.securitypolicy are either already adapted to the changes or will be adapted soon. zope.app.publisher refactoring

The zope.app.publisher package was also refactored into smaller parts with less dependencies and clearer purpose. The browser resources mechanism (mostly used for serving static files and directories) was factored out to the new zope.browserresource package. It was also made more pluggable, so you can register specific resource classes for some file extensions, if you need special processing. One of the example is the new zope.ptresource package, where the PageTemplateResource was moved, another example is z3c.zrtresource package that was adapted to automatically use ZRT resource class for files with .zrt extensions. Browser menu mechanism was moved into a new zope.browsermenu package with no further changes. ZCML directives for easy creation of browser views (the browser:page directive and friends) was moved into a new small package, zope.browserpage. Also, the directives don’t depend the menu mechanism now and will simply ignore “menu” and “title” arguments if zope.browsermenu package is not installed. The IModifiableBrowserLanguages adapter was moved into zope.publisher along with several ZCML security declarations for zope.publisher classes that used to be in zope.app.publisher.

2.1. What’s new in BlueBream 1.0 ? 11 BlueBream Documentation, Release 1.0a4

ZCML registrations for IXMLRPCPublisher adapter for containers was moved into the zope.container, because the actual adapters code were already in zope.container and registered there as IBrowserPublisher adapters. However, both adapters and their ZCML registrations will probably move elsewhere when we’ll be refactoring zope.container. Several parts are left in zope.app.publisher untouched: • Browser Skins vocabulary. • date ﬁeld converter for zope.publisher‘s form values conversion mechanism. • ManagementViewSelector browser view (ZMI-related part). • xmlrpc:view directive for publishing XML-RPC methods. The latter, xmlrpc:view directive is generally useful, so it may be moved into a separate package in future, however there are no clear decision about how to move XML-RPC and FTP-related things currently.

Password managers extracted from zope.app.authentication

The IPasswordManager interface and its implementations were extracted from zope.app.authentication into a new zope.password package to make them usable with other authentication systems, like z3c.authenticator or zope.principalregistry or any custom one. It basically depends only on zope.interface, so it can be really useful even in non-Zope environments, like Pylons, for example. The Password Manager Names vocabulary is also moved into zope.password, however, it’s only useful with zope.schema and zope.component, so you need them installed to work with them. They’re listed in the “vocabulary” extra requirement speciﬁcation.

ZODB 3.9 FileStorage native blob support

The FileStorage component of ZODB 3.9 used in Zope Toolkit 1.0 now supports blobs natively, so you don’t need to use BlobStorage proxy for it anymore. Thus, you can specify blob directory directly to FileStorage. If you use ZConﬁg, that means something like this:

path var/Data.fs blob-dir var/blobs

instead of:

blob-dir var/blobs path var/Data.fs

If you creating a storage from python, that means something like this:

storage= FileStorage(’var/Data.fs’, blob_dir=’var/blobs’)

instead of:

12 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

storage= BlobStorage(’var/blobs’, FileStorage(’var/Data.fs’))

Package version comparison

Package Name Zope 3.4.0 BlueBream 1.0.0 bluebream 1.0a2 clientform 0.2.9 0.2.10 distribute 0.6.10 docutils 0.4 0.6 jinja2 2.2.1 lxml 1.3.6 2.2.4 martian 0.12 mechanize 0.1.7b 0.1.11 py 1.0.0 pygments 1.2.2 python-gettext 1.0 pytz 2007k 2010b restrictedpython 3.4.2 3.5.1 roman 1.4.0 setuptools 0.6c9 0.6c11 sphinx 0.6.4 transaction 1.0.0 z3c.recipe.sphinxdoc 0.0.8 z3c.testsetup 0.6.1 zc.buildout 1.1.1 1.4.3 zc.lockﬁle 1.0.0 zc.recipe.egg 1.0.0 1.2.2 zc.recipe.testrunner 1.0.0 1.2.0 zc.resourcelibrary 1.0.1 1.3.0 zc.sourcefactory 0.6.0 zconﬁg 2.5.1 2.7.1 zdaemon 2.0.2 2.0.4 zodb3 3.8.1 3.9.4 zodbcode 3.4.0 3.4.0 zope.annotation 3.4.1 3.5.0 zope.app.apidoc 3.4.3 3.7.1 zope.app.applicationcontrol 3.4.3 3.5.5 zope.app.appsetup 3.4.1 3.13.0 zope.app.authentication 3.4.4 3.7.1 zope.app.basicskin 3.4.0 3.5.0 zope.app.broken 3.4.0 3.5.0 zope.app.cache 3.4.1 3.7.0 zope.app.catalog 3.5.1 3.8.1 zope.app.component 3.4.1 3.8.4 zope.app.container 3.5.6 3.8.2 zope.app.content 3.4.0 3.4.0 zope.app.dav 3.4.1 3.5.2 zope.app.debug 3.4.1 3.4.1 zope.app.dependable 3.4.0 3.5.1 zope.app.error 3.5.1 3.5.2 Continued on next page

2.1. What’s new in BlueBream 1.0 ? 13 BlueBream Documentation, Release 1.0a4

Table 2.1 – continued from previous page zope.app.exception 3.4.1 3.6.1 zope.app.file 3.4.4 3.5.1 zope.app.folder 3.4.0 3.5.1 zope.app.form 3.4.1 4.0.1 zope.app.ftp 3.4.0 3.5.0 zope.app.generations 3.4.1 3.5.1 zope.app.http 3.4.1 3.6.1 zope.app.i18n 3.4.4 3.6.2 zope.app.interface 3.4.0 3.5.0 zope.app.interpreter 3.4.0 3.4.0 zope.app.intid 3.4.1 3.7.1 zope.app.keyreference 3.4.1 3.6.0 zope.app.locales 3.4.5 3.6.0 zope.app.localpermission 3.7.0 zope.app.locking 3.4.0 3.5.0 zope.app.onlinehelp 3.4.1 3.5.2 zope.app.pagetemplate 3.4.1 3.10.1 zope.app.preference 3.4.1 3.6.0 zope.app.preview 3.4.0 3.4.0 zope.app.principalannotation 3.4.0 3.7.0 zope.app.publication 3.4.3 3.10.2 zope.app.publisher 3.4.1 3.10.1 zope.app.renderer 3.4.0 3.5.1 zope.app.rotterdam 3.4.1 3.5.1 zope.app.schema 3.4.0 3.5.0 zope.app.security 3.5.2 3.7.5 zope.app.securitypolicy 3.4.6 3.5.2 zope.app.server 3.4.2 3.5.0 zope.app.session 3.5.1 3.6.1 zope.app.skins 3.4.0 3.4.0 zope.app.testing 3.4.3 3.7.4 zope.app.tree 3.4.0 3.6.0 zope.app.twisted 3.4.1 3.5.0 zope.app.undo 3.4.0 3.5.0 zope.app.wsgi 3.4.1 3.6.1 zope.app.xmlrpcintrospection 3.4.0 3.5.1 zope.app.zcmlfiles 3.4.3 3.7.0 zope.app.zopeappgenerations 3.4.0 3.5.0 zope.app.zptpage 3.4.1 3.5.1 zope.applicationcontrol 3.5.5 zope.authentication 3.7.0 zope.broken 3.6.0 zope.browser 1.2 zope.browsermenu 3.9.0 zope.browserpage 3.11.0 zope.browserresource 3.10.2 zope.cachedescriptors 3.4.1 3.5.0 zope.catalog 3.8.1 zope.component 3.4.0 3.9.1 zope.componentvocabulary 1.0 zope.configuration 3.4.0 3.7.1 zope.container 3.11.0 Continued on next page

14 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

Table 2.1 – continued from previous page zope.contentprovider 3.4.0 3.6.1 zope.contenttype 3.4.0 3.5.0 zope.copy 3.5.0 zope.copypastemove 3.4.0 3.6.0 zope.datetime 3.4.0 3.4.0 zope.deferredimport 3.4.0 3.5.0 zope.deprecation 3.4.0 3.4.0 zope.documenttemplate 3.4.0 3.4.2 zope.dottedname 3.4.2 3.4.6 zope.dublincore 3.4.0 3.6.0 zope.error 3.5.1 3.7.0 zope.event 3.4.0 3.4.1 zope.exceptions 3.4.0 3.5.2 zope.ﬁle 0.3.0 0.5.0 zope.ﬁlerepresentation 3.4.0 3.6.0 zope.formlib 3.4.0 4.0 zope.hookable 3.4.0 3.4.1 zope.html 1.0.1 2.0.0 zope.i18n 3.4.0 3.7.2 zope.i18nmessageid 3.4.3 3.5.0 zope.index 3.4.1 3.6.0 zope.interface 3.4.1 3.5.3 zope.intid 3.7.2 zope.keyreference 3.6.2 zope.kgs 1.2.0 zope.lifecycleevent 3.4.0 3.6.0 zope.location 3.4.0 3.9.0 zope.login 1.0.0 zope.mimetype 0.3.0 1.2.0 zope.minmax 1.1.0 1.1.2 zope.modulealias 3.4.0 3.4.0 zope.pagetemplate 3.4.0 3.5.0 zope.password 3.5.1 zope.pluggableauth 1.0.1 zope.principalannotation 3.6.0 zope.principalregistry 3.7.0 zope.processlifetime 1.0 zope.proxy 3.4.2 3.5.0 zope.ptresource 3.9.0 zope.publisher 3.4.6 3.12.0 zope.ramcache 1.0 zope.rdb 3.4.0 3.5.0 zope.schema 3.4.0 3.6.1 zope.security 3.4.1 3.7.2 zope.securitypolicy 3.4.1 3.6.1 zope.sendmail 3.4.0 3.7.1 zope.sequencesort 3.4.0 3.4.0 zope.server 3.4.3 3.6.1 zope.session 3.4.1 3.9.2 zope.site 3.9.0 zope.size 3.4.0 3.4.1 zope.structuredtext 3.4.0 3.4.0 Continued on next page

2.1. What’s new in BlueBream 1.0 ? 15 BlueBream Documentation, Release 1.0a4

Table 2.1 – continued from previous page zope.tal 3.4.1 3.5.2 zope.tales 3.4.0 3.5.0 zope.testbrowser 3.4.2 3.7.0 zope.testing 3.5.6 3.8.7 zope.thread 3.4 3.4 zope.traversing 3.4.1 3.12.0 zope.viewlet 3.4.2 3.7.0 zope.xmlpickle 3.4.0 3.4.0

2.1.2 Possible errors and solutions

While running buildout, you may get module import errors like this:

ConfigurationError: (’Invalid value for’, ’package’, ’ImportError: Module zope.app has no global authentication’) ConfigurationError: (’Invalid value for’, ’package’, ’ImportError: Module zope.app has no global broken’) ConfigurationError: (’Invalid value for’, ’package’, ’ImportError: Module zope.app has no global error’) ConfigurationError: (’Invalid value for’, ’package’, ’ImportError: Module zope.app has no global i18n’) ConfigurationError: (’Invalid value for’, ’package’, ’ImportError: Module zope.app has no global session’) ConfigurationError: (’Invalid value for’, ’package’, ’ImportError: Module zope.app has no global schema’) ConfigurationError: (’Invalid value for’, ’package’, ’ImportError: Module zope.app has no global zopeappgenerations’) ConfigurationError: (’Invalid value for’, ’package’, ’ImportError: Module zope.app has no global keyreference’) ConfigurationError: (’Invalid value for’, ’package’, ’ImportError: Module zope.app has no global principalannotation’)

Solution Add the egg name (Eg:- zope.app.principalannotation) to install_requires inside setup.py as given here. Aftern adding this, you need to run ./bin/buildout command again. install_requires=[’setuptools’, ... ’zope.app.authentication’, ’zope.app.broken’, ’zope.app.error’, ’zope.app.i18n’, ’zope.app.session’, ’zope.app.schema’, ’zope.app.zopeappgenerations’, ’zope.app.keyreference’, ’zope.app.principalannotation’, ... ],

Another solution is to inlude egg name (Eg:- zope.app.principalannotation) in the Buildout part where other eggs are listed using‘‘zc.recipe.egg‘‘ recipe as given here:

[app] recipe = zc.recipe.egg eggs = samplproject ... zope.app.authentication zope.app.broken zope.app.error zope.app.i18n zope.app.session zope.app.schema

16 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

zope.app.zopeappgenerations zope.app.keyreference zope.app.principalannotation interpreter = breampy

Import error: zope.app.folder.interfaces.IFolder If you get error like this:

ZopeXMLConfigurationError: File "/home/baiju/myapp/src/myapp/browser.zcml", line 21.2-27.8 ConfigurationError: (’Invalid value for’, ’for’, "ImportError: Couldn’t import zope.app.folder.interfaces, No module named folder.interfaces")

Open the browser.zcml ﬁle and look at line number 21, inside that ZCML declaration change: zope.app.folder.interfaces.IFolder to zope.site.interfaces.IFolder. If you get error like this:

raise ValueError("Undefined permission id", permission_id)

zope.configuration.config.ConfigurationExecutionError: : (‘Undefined permission id’, ‘zope.ManageApplication’) You need to include zope.applicationcontrol package in your ZCML configuration file (site.zcml) as the permission definition is available there. If you are getting an error like this when accessing login.html view.

.../eggs/zope.principalregistry-3.7.0-py2.5.egg/zope/principalregistry/principalregistry.py", line 82, in unauthorized a = ILoginPassword(request) TypeError: (’Could not adapt’, , )

You need to include zope.login package in your ZCML conﬁguration ﬁle (site.zcml) as the adapter registration is available there:

2.1.3 ChangeLog of individual packages

bluebream

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 ﬁle • Improve “Usage” section in README.txt

2.1. What’s new in BlueBream 1.0 ? 17 BlueBream Documentation, Release 1.0a4

• 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 conﬁgure.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

18 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

0.1.6 (2010-01-07)

• LP #502819: Main page after a fresh installation • Removed hello view from template. • LP #502941: Add trove classiﬁers. • 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 ﬁx 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.

2.1. What’s new in BlueBream 1.0 ? 19 BlueBream Documentation, Release 1.0a4

RestrictedPython

3.5.1 (2009-03-17)

• Added tests for Utilities module. • Filtered DeprecationWarnings when importing Python’s sets module.

3.5.0 (2009-02-09)

• Dropped legacy support for Python 2.1 / 2.2 (__future__ imports of nested_scopes / generators.).

3.4.3 (2008-10-26)

• Fixed deprecation warning: with is now a reserved keyword on Python 2.6. That means RestrictedPython should run on Python 2.6 now. Thanks to Ranjith Kannikara, GSoC Student for the patch. • Added tests for ternary if expression and for ‘with’ keyword and context managers. transaction

1.0.0 (2009-07-24)

• Fix test that incorrectly relied on the order of a list that was generated from a dict. • Remove crufty DEPENDENCIES.cfg left over from zpkg.

1.0a1 (2007-12-18)

• Initial release, branched from ZODB trunk on 2007-11-08 (aka “3.9.0dev”). • Remove (deprecated) support for beforeCommitHook alias to addBeforeCommitHook. • Add weakset tests. • Remove unit tests that depend on ZODB.tests.utils from test_transaction (these are actually integration tests). z3c.testsetup

0.6.1 (2009-11-19)

• Test ﬁles that we attempt to read but that do not exist raise an error instead of passing silently. • Internal refactoring: regex caching.

20 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

0.6 (2009-11-19)

• Python unittest modules with an import error now result in a visible warning. Previously, such problems would be hidden. Also the python testrunner could not report them as broken as we did not pass those test ﬁles to the testrunner. • Fixed regex for detecting the old “:test-layer: python” marker: it did not work when preﬁxed with restructuredtext’s “..” comment marker.

0.5.1 (2009-10-22)

• Reverted allow_teardown default back to False to prevent confusion.

0.5 (2009-09-23)

Bug ﬁxes • Checkers are now applied to non-functional doctests too. Thanks to Jonathan Ballet for patches. • Normal UnitTest layers are now registered correctly. • :layer: now detects functional ZCML layers. If the deﬁned layer is derived from zope.testing.functional.ZCMLLayer, then the test is set up with the same kind of testcase as :functional-zcml-layer:. • Reordered and cleaned up the documentation.

Feature changes • By default, functional layer tests now use the allow_teardown=True option of the ZCMLLayer. This prevents the zcml layer from running in a subprocess which throws off proﬁling and thus code coverage tools. Running it in a subprocess is only normally needed when you do things like adding an interface to a class after the fact in your code. You can overrid it in the register_all_tests() call by setting allow_teardown=False.

0.4 (2009-06-11)

Bug fixes • Made z3c.testsetup selftests work with zope.testing >= 3.7.3. Thanks to Jonathan Ballet for pointing to that problem. • Ignore *nix hidden test files (i.e. such starting with a dot in filename) by default. Thanks to Jonathan Ballet for patch. • ZCML files registered via the default layer are now separated from each other, even if they own the same filename. Therefore you can now register a default layer with an ftesting.zcml in one subpackage while having another ftesting.zcml in another package. This was not handled correctly before. Many thanks go to Jonathan Ballet who contributed a patch.

Feature Changes • Added z3c.testsetup.testrunner that provides wrappers for zope.testing.testrunner‘‘s ‘‘run() and run_internal() functions. Using it, one can make sure that running testrunners inside tests will work regardless of which version of zope.testing is used during testruns.

2.1. What’s new in BlueBream 1.0 ? 21 BlueBream Documentation, Release 1.0a4

0.3 (2009-02-23)

Bug ﬁxes • Updated doctest examples to reﬂect new zope.testing behaviour. • z3c.testsetup really shouldn’t require zope.app.testing any more. If you use it in an environment without this package, then you cannot register functional tests, which is determined when loading register_all_tests from z3c.testsetup. • Broken modules are ignored while scanning for tests. • Modules are not loaded anymore if their source code does not provide a suitable marker string. For this to work, the default checker method isTestModule now expects a martian.scan.ModuleInfo as argument and not a real module. Module infos can be easily created by using module_info_from_dotted_name and module_info_from_package from the martian.scan package.

Feature Changes • New set of testfile markers: – :doctest: marks a testfile as a doctest. – :unittest: marks a testfile as a regular unittest. – :layer: dotted.name.to.layer.def applies the given layer definition to the tests in the doctest file. – :zcml-layer: filename.zcml sets up a ZCML layer with the given filename and applies this layer to the doctests in the doctest file. – :functional-zcml-layer: filename.zcml sets up a ZCML layer with the given filename and applies this layer to the doctests in the doctest file. Furthermore the tests are set up as functional doc tests. – :setup: dotted.name.to.setup.function applies the setUp function denoted by the dotted name to the tests in the doctest file. – :teardown: dotted.name.to.teardown.function applies the tearDown function denoted by the dotted name to the tests in the doctests file. See the examples in tests/othercave and README.txt to learn more about using these new directives. The old :test-layer: marker is still supported but it is deprecated now and will vanish at least with the 0.5 version of z3c.testsetup.

0.2.2 (2008-02-29)

Bug ﬁxes • z3c.testsetup now does not require zope.component nor zope.app.testing for usage in other packages. You must take care, that those packages are available during tests, for example by adding those packages to your setup.py.

22 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

0.2.1 (2008-02-18)

Bug ﬁxes • Fix faulty upload egg.

0.2 (2008-02-17)

Feature Changes • An ftesting.zcml in the root of a handled package is now taken as default layer for functional doctests if it exists.

0.1 (2008-02-15)

• Initial Release zc.buildout

1.4.3 (2009-12-10)

Bugs ﬁxed: • Using pre-detected setuptools version for easy_installing tgz ﬁles. This prevents a recursion error when easy_installing an upgraded “distribute” tgz. Note that setuptools did not have this recursion problem solely because it was packaged as an .egg, which does not have to go through the easy_install step.

1.4.2 (2009-11-01)

New Feature: • Added a –distribute option to the bootstrap script, in order to use Distribute rather than Setuptools. By default, Setuptools is used. Bugs fixed: • While checking for new versions of setuptools and buildout itself, compare requirement locations instead of requirement objects. • Incrementing didn’t work properly when extending multiple files. https://bugs.launchpad.net/zc.buildout/+bug/421022 • The download API computed MD5 checksums of text files wrong on Windows.

1.4.1 (2009-08-27)

New Feature: • Added a debug built-in recipe to make writing some tests easier. Bugs ﬁxed: • (introduced in 1.4.0) option incrementing (-=) and decrementing (-=) didn’t work in the buildout section. https://bugs.launchpad.net/zc.buildout/+bug/420463 • Option incrementing and decrementing didn’t work for options speciﬁed on the command line.

2.1. What’s new in BlueBream 1.0 ? 23 BlueBream Documentation, Release 1.0a4

• Scripts generated with relative-paths enabled couldn’t be symbolically linked to other locations and still work. • Scripts run using generated interpreters didn’t have __ﬁle__ set correctly. • The standard Python -m option didn’t work for custom interpreters.

1.4.0 (2009-08-26)

• When doing variable substitutions, you can omit the section name to refer to a variable in the same section (e.g. ${:foo}). • When doing variable substitution, you can use the special option, _buildout_section_name_ to get the section name. This is most handy for getting the current section name (e.g. ${:_buildout_section_name_}). • A new special option, < allows sections to be used as macros. • Added annotate command for annotated sections. Displays sections key-value pairs along with the value origin. • Added a download API that handles the download cache, offline mode etc and is meant to be reused by recipes. • Used the download API to allow caching of base configurations (specified by the buildout section’s ‘extends’ option).

1.3.1 (2009-08-12)

• Bug ﬁxed: extras were ignored in some cases when versions were speciﬁed.

1.3.0 (2009-06-22)

• Better Windows compatibility in test infrastructure. • Now the bootstrap.py has an optional –version argument, that can be used to force zc.buildout version to use. • zc.buildout.testing.buildoutSetUp installs a new handler in the python root logging facility. This handler is now removed during tear down as it might disturb other packages reusing buildout’s testing infrastructure. • ﬁxed usage of ‘relative_paths’ keyword parameter on Windows • Added an unload entry point for extensions. • Fixed bug: when the relative paths option was used, relative paths could be inserted into sys.path if a relative path was used to run the generated script.

1.2.1 (2009-03-18)

• Refactored generation of relative egg paths to generate simpler code.

1.2.0 (2009-03-17)

• Added a relative_paths option to zc.buildout.easy_install.script to generate egg paths relative to the script they’re used in.

24 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

1.1.2 (2009-03-16)

• Added Python 2.6 support. Removed Python 2.3 support. • Fixed remaining deprecation warnings under Python 2.6, both when running our tests and when using the package. • Switched from using os.popen* to subprocess.Popen, to avoid a deprecation warning in Python 2.6. See: http://docs.python.org/library/subprocess.html#replacing-os-popen-os-popen2-os-popen3 • Made sure the ‘redo_pyc’ function and the doctest checkers work with Python executable paths containing spaces. • Expand shell patterns when processing the list of paths in develop, e.g:

[buildout] develop = ./local-checkouts/*

• Conditionally import and use hashlib.md5 when it’s available instead of md5 module, which is deprecated in Python 2.6. • Added Jython support for bootstrap, development bootstrap and zc.buildout support on Jython • Fixed a bug that would cause buildout to break while computing a directory hash if it found a broken symlink (Launchpad #250573) zc.lockﬁle

1.0.0 (2008-10-18)

• Fixed a small bug in error logging.

1.0.0b1 (2007-07-18)

Initial release

ZConﬁg

2.7.1 (2009-06-13)

• Improved documentation • Fixed tests failures on windows.

2.7.0 (2009-06-11)

• Added a convenience function, ZConfig.configureLoggers(text) for conﬁguring loggers. • Relaxed the requirement for a logger name in logger sections, allowing the logger section to be used for both root and non-root loggers.

2.1. What’s new in BlueBream 1.0 ? 25 BlueBream Documentation, Release 1.0a4

2.6.1 (2008-12-05)

• Fixed support for schema descriptions that override descriptions from a base schema. If multiple base schema provide descriptions but the derived schema does not, the ﬁrst base mentioned that provides a description wins. https://bugs.launchpad.net/zconﬁg/+bug/259475 • Fixed compatibility bug with Python 2.5.0. • No longer trigger deprecation warnings under Python 2.6.

2.6.0 (2008-09-03)

• Added support for ﬁle rotation by time by specifying when and interval, rather than max-size, for log ﬁles. • Removed dependency on setuptools from the setup.py. zc.recipe.testrunner

1.2.0 (2009-03-23)

• Added a relative-paths option to use egg, test, and working-directory paths relative to the test script.

1.1.0 (2008-08-25)

• Requiring at least zope.testing 3.6.0. • Fixed a bug: Parallel runs of layers failed when using working-directory parameter. zc.resourcelibrary

1.3.0 (2009-10-08)

• Use zope.browserresource instead of zope.app.publisher, removing a dependency on latter. • Look up the “resources view” via queryMultiAdapter instead of looking into the adapter registry. • Moved the dependency on zope.site to the test dependencies.

1.2.0 (2009-06-04)

• Use zope.site instead of zope.app.component. Removes direct dependency on zope.app.component.

1.1.0 (2009-05-05)

New features:

26 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

• An attempt to generate resource URLs using the “resources view” (@@) is now made; if unsucces- ful, we fall back to the previous method of crafting the URL by hand from the site url. This ensures that the resource library respects the existing plugging points for resource publishing (see zope.app.publisher.browser.resources). • You can now explicitly specify where resource links should be inserted using the special marker comment ‘’.

1.0.2 (2009-01-27)

• Remove zope.app.zapi from dependencies, substituting its uses with direct imports. • Use zope-dev at zope.org mailing list address instead of zope3-dev at zope.org as the latter one is retired. • Change “cheeseshop” to “pypi” in the package homepage. zc.sourcefactory

0.6.0 (2009-08-15)

• Change package homepage to PyPI instead of Subversion. • Dropped Support for Zope 3.2 by removing a conditional import. • Use hashlib for Python 2.5 and later to avoid deprecation warnings.

0.5.0 (2009-02-03)

• FactoredContextualSourceBinder.__call__ now accepts arguments giving the args to pass to source class. Con- textualSourceFactory now uses a class variable to tell what kind of Source to make. • Use zope.intid instead of zope.app.intid. • Corrected e-mail address as [email protected] has been retired.

0.4.0 (2008-12-11)

• Removed zope.app.form dependency. Changed ITerms import from zope.app.form.browser.interfaces to zope.browser.interfaces. [projekt01]

0.3.5 (2008-12-08)

• Fixed bug in __new__ of contexual factories that would disallow subclasses to use constructors that expect a different signature. [icemac]

0.3.4 (2008-08-27)

• Added all documents in package to long description, so they are readable in pypi. [icemac]

2.1. What’s new in BlueBream 1.0 ? 27 BlueBream Documentation, Release 1.0a4

0.3.3 (2008-06-10)

• Fixed bug in __new__ of factories that would disallow subclasses to use constructors that expect a different signature. (Thanks to Sebastian Wehrmann for the patch.)

0.3.2 (2008-04-09)

• Fixed scalability bug caused by missing __nonzero__ on ValueMappingSource

0.3.1 (2008-02-12)

• Fixed scalability bug caused by missing __nonzero__ on BasicSourceFactory

0.3.0

• Added class-level defaults for attributes that are declared in the interfaces to not have the Zope 2 security machinery complain about them.

0.2.1 (2007-07-10)

• Fixed a bug in the contextual token policy that was handling the resolution of values for a given token incorrectly.

0.2.0 (2007-07-10)

• Added a contextual token policy interface that allows getToken and getValue to access the cotext for contextual sources. • Added a contextual term policy interface that allows createTerm and getTitle to access the context for contextual sources. • Added compatibility for Zope 3.2 and Zope 2.9 (via Five 1.3) zdaemon

2.0.4 (2009-04-20)

• Version 2.0.3 broke support for relative paths to the socket (-s option and socket-name parameter), now relative paths work again as in version 2.0.2. • Fixed change log format, made table of contents nicer. • Fixed author’s email address. • Removed zpkg stuff.

28 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

2.0.3 (2009-04-11)

• Added support to bootstrap on Jython. • If the run directory does not exist it will be created. This allow to use /var/run/mydaemon as run directory when /var/run is a tmpfs (LP #318118).

Bugs Fixed • No longer uses a hardcoded ﬁlename (/tmp/demo.zdsock) in unit tests. This lets you run the tests on Python 2.4 and 2.5 simultaneously without spurious errors. • make -h work again for both runner and control scripts. Help is now taken from the __doc__ of the options class users by the zdaemon script being run.

ZODB3

3.9.4 (2009-12-14)

Bugs Fixed • A ZEO threading bug could cause transactions to read inconsistent data. (This sometimes caused an Assertion- Error in Connection._setstate_noncurrent.) • DemoStorage.loadBefore sometimes returned invalid data which would trigger AssertionErrors in ZODB.Connection. • History support was broken when using stprages that work with ZODB 3.8 and 3.9. • zope.testing was an unnecessary non-testing dependency. • Internal ZEO errors were logged at the INFO level, rather than at the error level. • The FileStorage backup and restore script, repozo, gave a deprecation warning under Python 2.6. • C Header ﬁles weren’t installed correctly. • The undo implementation was incorrect in ways that could cause subtle missbehaviors.

3.9.3 (2009-10-23)

Bugs Fixed • 2 BTree bugs, introduced by a bug ﬁx in 3.9.0c2, sometimes caused deletion of keys to be improperly handled, resulting in data being available via iteraation but not item access.

3.9.2 (2009-10-13)

Bugs Fixed • ZEO manages a separate thread for client network IO. It created this thread on import, which caused problems for applications that implemented daemon behavior by forking. Now, the client thread isn’t created until needed. • File-storage pack clean-up tasks that can take a long time unnecessarily blocked other activity. • In certain rare situations, ZEO client connections would hang during the initial connection setup.

2.1. What’s new in BlueBream 1.0 ? 29 BlueBream Documentation, Release 1.0a4

3.9.1 (2009-10-01)

Bugs Fixed • Conﬂict errors committing blobs caused ZEO servers to stop committing transactions.

3.9.0 (2009-09-08)

New Features (in more or less reverse chronological order) • The Database class now has an xrefs keyword argument and a corresponding allow-implicit-cross-references conﬁguration option. which default to true. When set to false, cross-database references are disallowed. • Added support for RelStorage. • As a convenience, the connection root method for returning the root object can now also be used as an object with attributes mapped to the root-object keys. • Databases have a new method, transaction, that can be used with the Python (2.5 and later) with statement:

db = ZODB.DB(...) with db.transaction() as conn: # ... do stuff with conn

This uses a private transaction manager for the connection. If control exits the block without an error, the transaction is committed, otherwise, it is aborted. • Convenience functions ZODB.connection and ZEO.connection provide a convenient way to open a connection to a database. They open a database and return a connection to it. When the connection is closed, the database is closed as well. • The ZODB.config databaseFrom... methods now support multi-databases. If multiple zodb sections are used to define multiple databases, the databases are connected in a multi-database arrangement and the first of the defined databases is returned. • The zeopack script has gotten a number of improvements: – Simplified command-line interface. (The old interface is still supported, except that support for ZEO version 1 servers has been dropped.) – Multiple storages can be packed in sequence.

* This simplifies pack scheduling on servers serving multiple databases. * All storages are packed to the same time. – You can now specify a time of day to pack to. – The script will now time out if it can’t connect to s storage in 60 seconds. • The connection now estimates the object size based on its pickle size and informs the cache about size changes. The database got additional configurations options (cache-size-bytes and historical-cache-size-bytes) to limit the cache size based on the estimated total size of cached objects. The default values are 0 which has the interpretation “do not limit based on the total estimated size”. There are corresponding methods to read and set the new configuration parameters. • Connections now have a public opened attribute that is true when the connection is open, and false otherwise. When true, it is the seconds since the epoch (time.time()) when the connection was opened. This is a renaming of the previous _opened private variable.

30 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

• FileStorage now supports blobs directly. • You can now control whether FileStorages keep .old files when packing. • POSKeyErrors are no longer logged by ZEO servers, because they are really client errors. • A new storage interface, IExternalGC, to support external garbage collection, http://wiki.zope.org/ZODB/ExternalGC, has been defined and implemented for FileStorage and ClientStorage. • As a small convenience (mainly for tests), you can now specify initial data as a string argument to the Blob constructor. • ZEO Servers now provide an option, invalidation-age, that allows quick verification of ZEO clients have been disconnected for less than a given time even if the number of transactions the client hasn’t seen exceeds the invalidation queue size. This is only recommended if the storage being served supports efficient iteration from a point near the end of the transaction history. • The FileStorage iterator now handles large files better. When iterating from a starting transaction near the end of the file, the iterator will scan backward from the end of the file to find the starting point. This enhancement makes it practical to take advantage of the new storage server invalidation-age option. • Previously, database connections were managed as a stack. This tended to cause the same connection(s) to be used over and over. For example, the most used connection would typically be the only connection used. In some rare situations, extra connections could be opened and end up on the top of the stack, causing extreme memory wastage. Now, when connections are placed on the stack, they sink below existing connections that have more active objects. • There is a new pool-timeout database configuration option to specify that connections unused after the given time interval should be garbage collection. This will provide a means of dealing with extra connections that are created in rare circumstances and that would consume an unreasonable amount of memory. • The Blob open method now supports a new mode, ‘c’, to open committed data for reading as an ordinary file, rather than as a blob file. The ordinary file may be used outside the current transaction and even after the blob’s database connection has been closed. • ClientStorage now provides blob cache management. When using non-shared blob directories, you can set a target cache size and the cache will periodically be reduced try to keep it below the target size. The client blob directory layout has changed. If you have existing non-shared blob directories, you will have to remove them. • ZODB 3.9 ZEO clients can connect to ZODB 3.8 servers. ZODB ZEO clients from ZODB 3.2 on can connect to ZODB 3.9 servers. • When a ZEO cache is stale and would need verification, a ZEO.interfaces.StaleCache event is published (to zope.event). Applications may handle this event and take action such as exiting the application without verifying the cache or starting cold. • There’s a new convenience function, ZEO.DB, for creating databases using ZEO Client Storages. Just call ZEO.DB with the same arguments you would otherwise pass to ZEO.ClientStorage.ClientStorage:

import ZEO db= ZEO.DB((’some_host’, 8200))

• Object saves are a little faster • When conﬁguring storages in a storage server, the storage name now defaults to “1”. In the overwhelmingly common case that a single storage, the name can now be omitted. • FileStorage now provides optional garbage collection. A ‘gc’ keyword option can be passed to the pack method. A false value prevents garbage collection.

2.1. What’s new in BlueBream 1.0 ? 31 BlueBream Documentation, Release 1.0a4

• The FileStorage constructor now provides a boolean pack_gc option, which defaults to True, to control whether garbage collection is performed when packing by default. This can be overridden with the gc option to the pack method. The ZConfig configuration for FileStorage now includes a pack-gc option, corresponding to the pack_gc constructor argument. • The FileStorage constructor now has a packer keyword argument that allows an alternative packer to be supplied. The ZConfig configuration for FileStorage now includes a packer option, corresponding to the packer constructor argument. • MappingStorage now supports multi-version concurrency control and iteration and provides a better storage implementation example. • DemoStorage has a number of new features: – The ability to use a separate storage, such as a file storage to store changes – Blob support – Multi-version concurrency control and iteration – Explicit support for demo-storage stacking via push and pop methods. • Wen calling ZODB.DB to create a database, you can now pass a file name, rather than a storage to use a file storage. • Added support for copying and recovery of blob storages: – Added a helper function, ZODB.blob.is_blob_record for testing whether a data record is for a blob. This can be used when iterating over a storage to detect blob records so that blob data can be copied. In the future, we may want to build this into a blob-aware iteration interface, so that records get blob file attributes automatically. – Added the IBlobStorageRestoreable interfaces for blob storages that support recovery via a restoreBlob method. – Updated ZODB.blob.BlobStorage to implement IBlobStorageRestoreable and to have a copyTransactions- From method that also copies blob data. • New ClientStorage configuration option drop_cache_rather_verify. If this option is true then the ZEO client cache is dropped instead of the long (unoptimized) verification. For large caches, setting this option can avoid effective down times in the order of hours when the connection to the ZEO server was interrupted for a longer time. • Cleaned-up the storage iteration API and provided an iterator implementation for ZEO. • Versions are no-longer supported. • Document conflict resolution (see ZODB/ConflictResolution.txt). • Support multi-database references in conflict resolution. • Make it possible to examine oid and (in some situations) database name of persistent object references during conflict resolution. • Moved the ‘transaction’ module out of ZODB. ZODB depends upon this module, but it must be installed separately. • ZODB installation now requires setuptools. • Added offset information to output of fstail script. Added test harness for this script.

32 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

• Added support for read-only, historical connections based on datetimes or serials (TIDs). See src/ZODB/historical_connections.txt. • Removed the ThreadedAsync module. • Now depend on zc.lockﬁle

Bugs Fixed • CVE-2009-2701: Fixed a vulnerability in ZEO storage servers when blobs are available. Someone with write access to a ZEO server configured to support blobs could read any file on the system readable by the server process and remove any file removable by the server process. • BTrees (and TreeSets) kept references to internal keys. https://bugs.launchpad.net/zope3/+bug/294788 • BTree Sets and TreeSets don’t support the standard set add method. (Now either add or the original insert method can be used to add an object to a BTree-based set.) • The runzeo script didn’t work without a configuration file. (https://bugs.launchpad.net/zodb/+bug/410571) • Officially deprecated PersistentDict (https://bugs.launchpad.net/zodb/+bug/400775) • Calling __setstate__ on a persistent object could under certain uncommon cause the process to crash. • When committing transactions involving blobs to ClientStorages with non-shared blob directories, a failure could occur in tpc_finish if there was insufficient disk space to copy the blob file or if the file wasn’t available. https://bugs.launchpad.net/zodb/+bug/224169 • Savepoint blob data wasn’t properly isolated. If multiple simultaneous savepoints in separate transactions modified the same blob, data from one savepoint would overwrite data for another. • Savepoint blob data wasn’t cleaned up after a transaction abort. https://bugs.launchpad.net/zodb/+bug/323067 • Opening a blob with modes ‘r+’ or ‘a’ would fail when the blob had no committed changes. • PersistentList’s sort method did not allow passing of keyword parameters. Changed its sort parameter list to match that of its (Python 2.4+) UserList base class. • Certain ZEO server errors could cause a client to get into a state where it couldn’t commit transactions. https://bugs.launchpad.net/zodb/+bug/374737 • Fixed vulnerabilities in the ZEO network protocol that allow: – CVE-2009-0668 Arbitrary Python code execution in ZODB ZEO storage servers – CVE-2009-0669 Authentication bypass in ZODB ZEO storage servers The vulnerabilities only apply if you are using ZEO to share a database among multiple applications or application instances and if untrusted clients are able to connect to your ZEO servers. • Fixed the setup test command. It previously depended on private functions in zope.testing.testrunner that don’t exist any more. • ZEO client threads were unnamed, making it hard to debug thread management. • ZEO protocol 2 support was broken. This caused very old clients to be unable to use new servers. • zeopack was less flexible than it was before. -h should default to local host. • The “lawn” layout was being selected by default if the root of the blob directory happened to contain a hidden file or directory such as “.svn”. Now hidden files and directories are ignored when choosing the default layout. • BlobStorage was not compatible with MVCC storages because the wrappers were being removed by each database connection. Fixed.

2.1. What’s new in BlueBream 1.0 ? 33 BlueBream Documentation, Release 1.0a4

• Saving indexes for large file storages failed (with the error: RuntimeError: maximum recursion depth exceeded). This can cause a FileStorage to fail to start because it gets an error trying to save its index. • Sizes of new objects weren’t added to the object cache size estimation, causing the object-cache size limiting feature to let the cache grow too large when many objects were added. • Deleted records weren’t removed when packing file storages. • Fixed analyze.py and added test. • fixed Python 2.6 compatibility issue with ZEO/zeoserverlog.py • using hashlib.sha1 if available in order to avoid DeprecationWarning under Python 2.6 • made runzeo -h work • The monitor server didn’t correctly report the actual number of clients. • Packing could return spurious errors due to errors notifying disconnected clients of new database size statistics. • Undo sometimes failed for FileStorages configured to support blobs. • Starting ClientStorages sometimes failed with non-new but empty cache files. • The history method on ZEO clients failed. • Fix for bug #251037: Make packing of blob storages non-blocking. • Fix for bug #220856: Completed implementation of ZEO authentication. • Fix for bug #184057: Make initialisation of small ZEO client file cache sizes not fail. • Fix for bug #184054: MappingStorage used to raise a KeyError during load instead of a POSKeyError. • Fixed bug in Connection.TmpStore: load() would not defer to the backend storage for loading blobs. • Fix for bug #181712: Make ClientStorage update lastTransaction directly after connecting to a server, even when no cache verification is necessary. • Fixed bug in blob filesystem helper: the isSecure check was inverted. • Fixed bug in transaction buffer: a tuple was unpacked incorrectly in clear. • Bugfix the situation in which comparing persistent objects (for instance, as members in BTree set or keys of BTree) might cause data inconsistency during conflict resolution. • Fixed bug 153316: persistent and BTrees were using int for memory sizes which caused errors on x86_64 Intel Xeon machines (using 64-bit Linux). • Fixed small bug that the Connection.isReadOnly method didn’t work after a savepoint. • Bug #98275: Made ZEO cache more tolerant when invalidating current versions of objects. • Fixed a serious bug that could cause client I/O to stop (hang). This was accompanied by a critical log message along the lines of: “RuntimeError: dictionary changed size during iteration”. • Fixed bug #127182: Blobs were subclassable which was not desired. • Fixed bug #126007: tpc_abort had untested code path that was broken. • Fixed bug #129921: getSize() function in BlobStorage could not deal with garbage files • Fixed bug in which MVCC would not work for blobs. • Fixed bug in ClientCache that occurred with objects larger than the total cache size. • When an error occured attempting to lock a file and logging of said error was enabled.

34 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

• FileStorages previously saved indexes after a certain number of writes. This was done during the last phase of two-phase commit, which made this critical phase more subject to errors than it should have been. Also, for large databases, saves were done so infrequently as to be useless. The feature was removed to reduce the chance for errors during the last phase of two-phase commit. • File storages previously kept an internal object id to transaction id mapping as an optimization. This mapping caused excessive memory usage and failures during the last phase of two-phase commit. This optimization has been removed. • Refactored handling of invalidations on ZEO clients to fix a possible ordering problem for invalidation messages. • On many systems, it was impossible to create more than 32K blobs. Added a new blob-directory layout to work around this limitation. • Fixed bug that could lead to memory errors due to the use of a Python dictionary for a mapping that can grow large. • Fixed bug #251037: Made packing of blob storages non-blocking. • Fixed a bug that could cause InvalidObjectReference errors for objects that were explicitly added to a database if the object was modified after a savepoint that added the object. • Fixed several bugs that caused ZEO cache corruption when connecting to servers. These bugs affected both persistent and non-persistent caches. • Improved the the ZEO client shutdown support to try to avoid spurious errors on exit, especially for scripts, such as zeopack. • Packing failed for databases containing cross-database references. • Cross-database references to databases with empty names weren’t constructed properly. • The zeo client cache used an excessive amount of memory, causing applications with large caches to exhaust available memory. • Fixed a number of bugs in the handling of persistent ZEO caches: – Cache records are written in several steps. If a process exits after writing begins and before it is finishes, the cache will be corrupt on restart. The way records are written was changed to make cache record updates atomic. – There was no lock file to prevent opening a cache multiple times at once, which would lead to corruption. Persistent caches now use lock files, in the same way that file storages do. – A bug in the cache-opening logic led to cache failure in the unlikely event that a cache has no free blocks. • When using ZEO Client Storages, Errors occured when trying to store objects too big to fit in the ZEO cache file. • Fixed bug in blob filesystem helper: the isSecure check was inverted. • Fixed bug in transaction buffer: a tuple was unpacked incorrectly in clear. • Fixed bug in Connection.TmpStore: load() would not defer to the back-end storage for loading blobs. • Fixed bug #190884: Wrong reference to POSKeyError caused NameError. • Completed implementation of ZEO authentication. This fixes issue 220856. zodbcode

(No changes)

2.1. What’s new in BlueBream 1.0 ? 35 BlueBream Documentation, Release 1.0a4 zope.annotation

3.5.0 (2009-09-07)

• Add ZODB3 to install_requires, because it’s a true requirement of this package, not just a testing requirement, as BTrees are in use. • Fix one test that was inactive because it’s function was overriden by a mistake.

3.4.2 (2009-03-09)

• Clean up package description and documentation a bit. • Change mailing list address to zope-dev at zope.org, as zope3-dev at zope.org is now retired. • Remove old zpkg-related ﬁles. zope.app.apidoc

3.7.2 (2010-03-07)

• Adapted tests for Python2.4

3.7.1 (2010-01-05)

• Updated tests to work with zope.publisher 3.12 (using zope.login).

3.7.0 (2009-12-22)

• Updated tests to work with latest zope.testing and use zope.browserpage in favor of zope.app.pagetemplate.

3.6.8 (2009-11-18)

• Updated the tests after moving IPossibleSite and ISite to zope.component.

3.6.7 (2009-09-29)

• Updated the tests after moving ITraverser back to zope.traversing.

3.6.6 (2009-09-15)

• Made the tests work again with the most recent Zope Toolkit KGS.

3.6.5 (2009-07-24)

• Update documentation ﬁle in zope.site from README.txt to site.txt.

36 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

3.6.4 (2009-07-23)

• The IContained interface moved to zope.location.interfaces. Make a test pass.

3.6.3 (2009-05-16)

• Explicitly deﬁned default views. • Replace relative url links with absolute ones. • Added z3c packages to the code browser. • Made bin/static-apidoc principially working (publisher and webserver mode). There are still some ﬁles which are not correctly fetched.

3.6.2 (2009-03-17)

• Adapt principal registry book chapter to a new place, as it was moved from zope.app.security to zope.principalregistry. • Remove zcml slugs and old zpkg-related ﬁles.

3.6.1 (2009-02-04)

• When a module provides an interface or has an __all__ attribute, use one of those for the module documentation. Fixes LP #323375. • Undid broken link to savepoint.txt caused in 3.6.0. The latest version of the transaction package puts savepoint.txt in the tests subpackage. • Expanded the presentation of module documentation. • Class documentation now includes constructor information.

3.6.0 (2009-01-31)

• Use zope.container instead of zope.app.container. • Use zope.site instead of zope.app.component and zope.app.folder (in at least a few places). • savepoint.txt moved from ZODB’s test directory a level up – we follow. • Make compatible with new zope.traversing and zope.location.

3.5.0 (2009-01-17)

• Adapted transaction book chapters for new transaction egg. The README.txt was removed and savepoint.txt was moved. Also add chapter about dooming transactions (doom.txt). • Changed mailing list address to zope-dev at zope.org, because zope3-dev is retired now. • Cleaned up dependencies.

2.1. What’s new in BlueBream 1.0 ? 37 BlueBream Documentation, Release 1.0a4 zope.app.applicationcontrol

3.5.5 (2010-01-09)

• Extracted RuntimeInfo and ApplicationRoot functionality into zope.applicationcontrol. Import this functionality from this package instead (see BBB imports inside this package).

3.5.4 (2010-01-08)

• Test dependency on zptpage removed.

3.5.3 (2010-01-05)

• Updated to use newer zope.publisher 3.12 and zope.login to make tests work.

3.5.2 (2009-12-19)

• Move ‘zope.ManageApplication’ permission from zope.app.security package • Break dependency on zope.app.appsetup by using a conditional import

3.5.1 (2009-08-15)

• Added missing (normal and test) dependencies. • Renenabled functional tests.

3.5.0 (2009-05-23)

• The application controller is now registered as a utility so that other packages like zope.traversing and zope.app.publication do not need to depend on this package directly. This also makes the application controller pluggable. zope.app.appsetup

3.13.0 (2009-12-24)

• Import hooks functionality from zope.component after it was moved there from zope.site. • Import ISite from zope.component after it was moved there from zope.location. This lifts the dependency on zope.location. • Added missing install dependency on zope.testing.

38 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

3.12.0 (2009-06-20)

• Using zope.processlifetime interfaces and implementations directly instead of BBB imports from zope.app.appsetup. • Got rid of depencency on zope.app.component. • Got rid of test dependency on zope.app.security.

3.11 (2009-05-13)

• Event interfaces / implementations moved to zope.processlifetime, version 1.0. Depend on this package, and add BBB imports.

3.10.1 (2009-03-31)

• Fixed a DeprecationWarning introduced in 3.10.0. • Added doctests to long description to show up at pypi.

3.10.0 (2009-03-19)

• Finally deprecate the “asObject” argument of helper functions in the zope.app.appsetup.bootstrap module. If your code uses any of these functions, please remove the “asObject=True” argument passing anywhere, because the support for that argument will be dropped soon. • Move session utility bootstrapping logic from zope.session into this package. This removes a dependency from zope.session to this package. • Remove one more deprecated function.

3.9.0 (2009-01-31)

• Use zope.site instead of zope.app.folder and zope.app.component. • Use zope.container instead of zope.app.container. • Move error log bootstrapping logic from zope.error into this package. This removes a dependency from zope.error to this package. Also added a test for bootstrapping the error log here, which was missing in zope.error.

3.8.0 (2008-08-25)

• Feature: Developed an entry point that allows you to quickly bring up an application instance for debugging purposes. (Implemented by Marius Gedminas and Stephan Richter.)

2.1. What’s new in BlueBream 1.0 ? 39 BlueBream Documentation, Release 1.0a4

3.7.0 (2008-08-19)

• Added .product.loadConfiguration test-support function; loads product configuration (only) from a file object, allowing test code (including setup) to make use of the same configuration schema support used by normal startup.

3.6.0 (2008-07-23)

• Added additional test support functions to set the conﬁguration for a single section, and save/restore the entire conﬁguration.

3.5.0 (2008-06-17)

• Added helper class for supporting product conﬁguration tests. • Added documentation for the product conﬁguration API, with tests. zope.app.authentication

3.7.1 (2010-02-11)

• Using the new principalfactories.zcml ﬁle, from zope.pluggableauth, to avoid duplication errors, in the adapters registration.

3.7.0 (2010-02-08)

• The Pluggable Authentication utility has been severed and released in a standalone package: zope.pluggableauth. We are now using this new package, providing backward compatibility imports to assure a smooth transition.

3.6.2 (2010-01-05)

• Fix tests by using zope.login, and require new zope.publisher 3.12.

3.6.1 (2009-10-07)

• Fix ftesting.zcml due to zope.securitypolicy update. • Don’t use zope.app.testing.ztapi in tests, use zope.component’s testing functions instead. • Fix functional tests and stop using port 8081. Redirecting to different port without trusted ﬂag is not allowed.

3.6.0 (2009-03-14)

• Separate the presentation template and camefrom/redirection logic for the loginForm.html view. Now the logic is contained in the zope.app.authentication.browser.loginform.LoginForm class.

40 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

• Fix login form redirection failure in some cases with Python 2.6. • Use the new zope.authentication package instead of zope.app.security. • The “Password Manager Names” vocabulary and simple password manager registry were moved to the zope.password package. • Remove deprecated code.

3.5.0 (2009-03-06)

• Split password manager functionality off to the new zope.password package. Backward-compatibility imports are left in place. • Use zope.site instead of zope.app.component.

3.5.0a2 (2009-02-01)

• Make old encoded passwords really work.

3.5.0a1 (2009-01-31)

• Use zope.container instead of zope.app.container. • Encoded passwords are now stored with a preﬁx ({MD5}, {SHA1}, {SSHA}) indicating the used encoding schema. Old (encoded) passwords can still be used. • Add an SSHA password manager that is compatible with standard LDAP passwords. As this encoding gives better security agains dictionary attacks, users are encouraged to switch to this new password schema. • InternalPrincipal now uses SSHA password manager by default.

zope.app.basicskin

3.5.0 (2009-12-16)

• Avoid extraneous testing dependencies and remove test extra. • Avoid zope.app.component testing dependency. • Removed BBB import for IBasicSkin.

3.4.1 (2009-08-15)

• Added missing test dependency: zope.app.component.

zope.app.broken

3.5.0 (2009-02-05)

• Depend on new zope.broken package for the IBroken interface.

2.1. What’s new in BlueBream 1.0 ? 41 BlueBream Documentation, Release 1.0a4

zope.app.cache

3.7.0 (2009-07-25)

• Use the RAM cache implementation from zope.ramcache.

3.6.0 (2009-05-27)

• Use zope.componentvocabulary instead of zope.app.component.

3.5.0 (2009-01-31)

• Use zope.container instead of zope.app.container.

zope.app.catalog

3.8.1 (2010-01-08)

• Removed unneeded dependencies on zope.app.publisher and zope.app.form, moved zope.app.intid to the test dependencies. • Import hooks functionality from zope.component after it was moved there from zope.site. This lifts the test dependency on zope.site. • Use new zope.publisher that requires zope.login.

3.8.0 (2009-02-01)

• Move most of this package’s code to new zope.catalog package, leaving only ZMI-related views and backward-compatibility imports here.

3.7.0 (2009-01-31)

• Change catalog’s addMenuItem permission to zope.ManageServices as it doesn’t make any sense to add an empty catalog that you can’t modify with zope.ManageContent permission and it’s completely useless without indexes. So there’s no need to show a menu item. • Replaced dependency on zope.app.container with a lighter-weight dependency upon the newly refactored zope.container package.

3.6.0 (2009-01-03)

• Make TextIndex addform use default values as speciﬁed in zope.app.catalog.text.ITextIndex interface. Also, change “searchableText” to “getSearchableText” there, as it’s the right value. • Add Keyword (case-insensitive and case-sensitive) catalog indices. It’s now possible to use them, because ones in zope.index now implement IIndexSearch interface.

42 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

• Add support for sorting, reversing and limiting result set in the searchResults method, using new IIndex- Sort interface features of zope.index.

3.5.2 (2008-12-28)

• Remove testing dependencies from install_requires. zope.app.component

3.8.4 (2010-01-08)

• Import hooks functionality from zope.component after it was moved there from zope.site. • Import ISite and IPossibleSite from zope.component after they were moved there from zope.location. This lifts the direct dependency on zope.location. • Fix tests using a newer zope.publisher that requires zope.login.

3.8.3 (2009-07-11)

• Removed unnecessary dependency on zope.app.interface.

3.8.2 (2009-05-22)

• Fix missing import in zope.app.component.metadirectives.

3.8.1 (2009-05-21)

• Add deprecation note.

3.8.0 (2009-05-21)

• IMPORTANT: this package is now empty except for some ZMI deﬁnitions in zope.app.component.browser. Functionality from this package has been moved to zope.site, zope.componentvocabulary and zope.component, so preferably import from those locations. • zope.componentvocabulary has the vocabulary implementations that were in zope.app.componentvocabulary now, import them from there for backwards compatibility. • moved zope:resource and zope:view directive implementation and tests over into zope.component [zcml].

3.7.0 (2009-04-01)

• Removed deprecated zope:defaultView directive and its implementation. New directive to set default view is browser:defaultView.

2.1. What’s new in BlueBream 1.0 ? 43 BlueBream Documentation, Release 1.0a4

3.6.1 (2009-03-12)

• Make class directive schemas importable from old location, raising a deprecation warning. It was moved in the previous release, but some custom directives could possibly use its schemas. • Deprecate import of ClassDirective to announce about new location. • Change package’s mailing list address to zope-dev at zope.org, because zope3-dev at zope.org is now retired. • Adapt to the move of IDefaultViewName from zope.component.interfaces to zope.publisher.interfaces.

3.6.0 (2009-01-31)

• Moved the implementation of the directive from this package to zope.security. In particular, the module zope.app.component.contentdirective has moved to zope.security.metaconfigure, and a compatibility import has been left in its place. • Extracted zope.site from zope.app.component with backwards compatibility imports in place. Local site related functionality is now in zope.site and packages should import from there. • Remove more deprecated on 3.5 code: – zope.app.component.fields module that was pointing to the removed back35’s LayerField. – zope.app.component.interface module that was moved to zope.component.interface ages ago. – zope:content and zope:localUtility directives. – zope:factory directive. – deprecated imports in zope.component.metaconfigure – browser:tool directive and all zope.component.browser meta.zcml stuff. • Remove “back35” extras_require as it doesn’t make any sense now. • Remove zope.modulealias test dependency as it is not used anywhere. • Deprecate ISite and IPossibleSite imports from zope.app.component.interfaces. They were moved to zope.location.interfaces ages ago. Fix imports in zope.app.component itself.

3.5.0 (2008-10-13)

• Remove deprecated code slated for removal on 3.5. zope.app.container

3.8.2 (2010-01-08)

• Fix tests using a newer zope.publisher that requires zope.login.

3.8.1 (2009-12-26)

• Fixed test_directive. Some parts of zope.app.publisher were moved to zope.browsermenu and zope.browserpage.

44 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

• Moved tests/test_view_permissions.py to browser/tests. • Added undeclared install dependency on zope.app.publisher. • Test no longer use deprecated zope.testing.doctestunit but python’s doctest instead.

3.8.0 (2009-05-13)

• Moved IAdding interface to zope.browser.interfaces, leaving BBB imports.

3.7.2 (2009-03-12)

• Show a “nothing to add” message instead of empty list in the adding view, if there’s nothing to add. • Don’t show the “Add” menu item if there’s nothing to add. • Adapt to the removal of deprecated interfaces from zope.component.interfaces. Now IAdding inherits from zope.publisher.interfaces.browser.IBrowserView.

3.7.1 (2009-02-05)

• Updated test to accomodate “Pythonic” exception now raised from __setitem__ provided by zope.container (KeyError instead of zope.exceptions.UserError).

3.7.0 (2009-01-31)

• Remove long-time deprecated IContentContainer class. • We now rely on a new package called zope.container, which contains the basic implementation of zope.container and is intended to have less dependencies. We have gone through a wide range of packages and updated their dependencies to point to zope.container so that they will also have less indirect dependencies. For backwards compatibility we have left the original modules in zope.app.container in place and have placed imports to make sure the symbols exist in their original locations.

3.6.2 (2008-10-21)

• Fixed bug in _zope_app_container_contained.c.

3.6.1 (2008-10-15)

• Reimplemented the BTreeContainer so that it directly accesses the btree methods (removed an old #TODO) • Removed usage of deprecated LayerField. • Made C code compatible with Python 2.5 on 64bit architectures. • Fixed bug: Error thrown during __setitem__ for an ordered container leaves bad key in order • Fixed https://bugs.launchpad.net/zope3/+bug/238579, https://bugs.launchpad.net/zope3/+bug/163149: Error with unicode traversing

2.1. What’s new in BlueBream 1.0 ? 45 BlueBream Documentation, Release 1.0a4

• Fixed https://bugs.launchpad.net/zope3/+bug/221025: The Adding menu is sorted with translated item by using a collator (better localized sorting) • Fixed https://bugs.launchpad.net/zope3/+bug/227617: – prevent the namechooser from failing on ‘+’, ‘@’ and ‘/’ – added tests in the namechooser – be sure the name chooser returns unicode • Fixed https://bugs.launchpad.net/zope3/+bug/175388: The setitem’s size modiﬁcation is now done in setitemf: setting an existing item does not change the size, and the event subscribers should see the new size instead of the old size.

3.6.0 (2008-05-06)

• Added an IBTreeContainer interface that allows an argument to the items, keys, and values methods with the same semantics as for a BTree object. The extended interface is implemented by the BTreeContainer class.

3.5 (2007-10-11)

• Updated bootstrap script to current version. • Store length of BTreeContainer in its own Length object for faster __len__ implementation of huge containers. • Send IObjectModifiedEvent when changing the title through the @@contents.html view. This ﬁxes https://bugs.edge.launchpad.net/zope3/+bug/98483. • Resolve ZopeSecurityPolicy and IRolePermissionManager deprecation warning.

3.4 (2007-04-22)

• Initial release as a separate project, corresponds to zope.app.container from Zope 3.4.0a1. zope.app.content

(No changes) zope.app.dav

3.5.2 (2010-01-08)

• Fix tests using a newer zope.publisher that requires zope.login.

3.5.1 (2009-09-15)

• Corrected invalid use of datetime.strftime. The timezone is denoted by %Z.

46 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

3.5.0 (2009-02-01)

• Use zope.container instead of zope.app.container. • Use zope.site instead of zope.app.folder.

3.4.2 (2009-01-27)

• Substitute zope.app.zapi by direct calls to its wrapped apis. See bug 219302. zope.app.debug

(No changes) zope.app.dependable

3.5.1 (2009-12-15)

• Added missing zcml namespace to the conﬁgure ﬁle.

3.5.0 (2009-12-15)

• Moved CheckDependency event handler and its tests into this package from its former place in zope.container. zope.app.error

3.5.2 (2009-01-22)

• Removed zope.app.zapi from dependencies, replacing its uses with direct imports. • Clean dependencies. • Changed mailing list address to [email protected], changed url from cheeseshop to pypi. • Use zope.ManageServices permission instead of zope.ManageContent for errorRedirect view and menu item, because all IErrorReportingUtility views are registered for zope.ManageServices as well. • Fix package’s README.txt zope.app.exception

3.6.1 (2010-01-08)

• Require zope.browserpage which now contains namedtemplate. • Fix ftesting.zcml due to zope.securitypolicy update. • Fix tests using a newer zope.publisher that requires zope.login.

2.1. What’s new in BlueBream 1.0 ? 47 BlueBream Documentation, Release 1.0a4

3.6.0 (2009-05-18)

• ISystemErrorView interface has been moved to zope.browser.interfaces, leaving BBB import here. • Cut dependency on zope.formlib by requiring newer version of zope.app.pagetemplate which now contains namedtemplate.

3.5.0 (2009-04-06)

• Use new zope.authentication instead of zope.app.security. • Removed deprecated code and thus removed dependency on zope.deferredimport. • Removed old zpkg-related SETUP.cfg ﬁle.

3.4.2 (2009-01-27)

• Substitute zope.app.zapi by direct calls to its wrapped apis. See bug 219302. • Fixed author email and home page. zope.app.ﬁle

3.5.1 (2010-01-08)

• Fix ftesting.zcml due to zope.securitypolicy update. • Added missing dependency on transaction. • Import content-type parser from zope.contenttype, reducing zope.publisher to a test dependency. • Fix tests using a newer zope.publisher that requires zope.login.

3.5.0 (2009-01-31)

• Replace zope.app.folder use by zope.site. Add missing dependency in setup.py.

3.4.6 (2009-01-27)

• Remove zope.app.zapi dependency again. Previous release was wrong. We removed the zope.app.zapi uses before, so we don’t need it anymore.

3.4.5 (2009-01-27)

• added missing dependency: zope.app.zapi

48 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4 zope.app.folder

3.5.1 (2009-02-14)

• Added missing dependency to zope.app.content. • Fixed e-mail address and homepage. • Fixed buildout.cfg, as there is no test extra.

3.5.0 (2009-01-31)

• Everything except zope.app.folder.browser moved to zope.site and zope.container. • Import IPossibleSite from zope.location.interfaces instead of deprecated place in zope.app.component.interfaces. • Use zope.container instead of zope.app.container. zope.app.form

4.0.2 (2010-01-22)

• Seems like 4.0.1 was released already. Brown bag.

4.0.1 (2010-01-08)

• Import ‘escape’ for backwards compatibility as packages turn out to be importing this too, even though it’s actually from the Python standard library. • Widget documentation is now on PyPI too.

4.0 (2010-01-08)

• The widget implementations have been moved to zope.formlib. This makes this package depend on zope.formlib. The dependency of zope.formlib on this package has been broken.

3.12.1 (2009-12-22)

• Added missing zope.datetime dependency.

3.12.0 (2009-12-22)

• Use zope.browserpage in favor of zope.app.pagetemplate.

3.11.1 (2009-12-22)

• Prefer zope.testing.doctest over doctestunit and adjust test output to newer zope.schema release.

2.1. What’s new in BlueBream 1.0 ? 49 BlueBream Documentation, Release 1.0a4

3.11.0 (2009-12-18)

• Use zope.component.testing in favor of zope.app.testing where possible. • Deﬁne dummy standard_macros for test purposes. This reduces the test dependencies by zope.app.basicskin and zope.browserresource. • Removed the zope.app.container and zope.app.publisher testing dependencies. • Refactored code to remove zope.app.component dependency. • Made the tests independent of zope.app.locales. • Reduce zope.app test dependencies by avoiding zope.app.securitypolicy and zope.app.zcmlﬁles.

3.10.0 (2009-12-17)

• Avoid the zope.app.basicskin dependency, by deﬁning our own FormMacros.

3.9.0 (2009-10-08)

• Internationalized ‘Invalid value’ used with ConversionError • Added dependency on transaction and test dependency on zope.app.component. • Moved dependencies on ZODB3 and zope.location to the test extra. • Reduced the dependency on zope.app.publisher to a dependency on zope.browsermenu plus a test dependency on zope.browserpage.

3.8.1 (2009-07-23)

• Fix unittest failure due to translation update.

3.8.0 (2009-05-24)

• Use standard properties instead of zope.cachedescriptors. • Require zope.browser 1.1 instead of zope.app.container for IAdding.

3.7.3 (2009-05-11)

• Fixed invalid markup.

3.7.2 (2009-03-12)

• Fixed bug where OrderedMultiSelectWidget did not respect the widgets size attribute. • Fixed bug in SequenceWidget where it crashed while trying to iterate a missing_value (None in most of cases) on _getRenderedValue.

50 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4

• Adapt to removal of deprecated interfaces from zope.component.interfaces. The IView was moved to zope.publisher and we use our custom IWidgetFactory interface instead of removed zope.component.interfaces.IViewFactory. • Fix tests to work on Python 2.6.

3.7.1 (2009-01-31)

• Adapt to the upcoming zope.schema release 3.5.1 which will also silence the spurious set failures.

3.7.0 (2008-12-11)

• use zope.browser.interfaces.ITerms instead of zope.app.form.browser.interfaces • Depending on zope.schema>=3.5a1 which uses the builtin set instead of the sets module.

3.6.4 (2008-11-26)

• The URIDisplayWidget doesn’t render an anchor for empty/None values.

3.6.3 (2008-10-15)

• Get rid of deprecated usage of LayerField from zope.app.component.back35, replaced by zope.conﬁguration.ﬁelds.GlobalInterface.

3.6.2 (2008-09-08)

• Fixed restructured text in doc tests to unbreak the PyPI page. (3.6.1 skipped due to a typo)

3.6.0 (2008-08-22)

• Dropdown widgets display an item for the missing value even if the ﬁeld is required when no value is selected. See zope/app/form/browser/README.txt on how to switch this off for BBB. • Source select widgets for required ﬁelds are now required as well. They used not to be required on the assump- tion that some value would be selected by the browser, which had always been wrong except for dropdown widgets.

3.5.0 (2008-06-05)

• Translate the title on SequenceWidget’s “Add ” button. • No longer uses zapi.2.1. What’s new in BlueBream 1.0 ? 51 BlueBream Documentation, Release 1.0a43.4.2 (2008-02-07)• Made display widgets for sources translate message IDs correctly. zope.app.ftp3.5.0 (2009-02-01)• Use zope.container instead of zope.app.container. zope.app.generations3.5.1 (2010-01-08)• Depend on new zope.processlifetime interfaces instead of using BBB imports from zope.app.appsetup. • Fix ftesting.zcml due to zope.securitypolicy update. • Fix tests using a newer zope.publisher that requires zope.login.3.5.0 (2009-04-05)• Moved getRootFolder utility method from zope.app.zopeappgenerations to zope.app.generations.utility. • Removed not necessary install dependency on zope.app.testing.3.4.2 (2009-01-27)• Provide more logging output for the various stages and actions of evolving a database. • Fixed bug: A failing last generation would allow starting an app server without having evolved to the minimum generation. • Substitute zope.app.zapi by direct calls to its wrapped apis. See bug 219302. • Corrected author email and home page address. zope.app.http3.6.1 (2010-01-08)• Replaced the dependency on zope.deprecation with BBB imports • Made the dependency on zope.app.publisher explicit • Fix tests using a newer zope.publisher that requires zope.login.52 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.6.0 (2009-05-23)• Moved IHTTPException, IMethodNotAllowed, and MethodNotAllowed from zope.app.http to zope.publisher.interfaces.http, fixing dependency cycles involving zope.app.http.3.5.2 (2009-04-01)• Replaced deprecated ‘zope:defaultView’ directive with ‘browser:defaultView’3.5.1 (2009-03-12)• If the ‘CONTENT_LENGTH’ header is provided, provide this length as argument to the read method of the input stream object.3.5.0 (2009-02-01)• Change dependency on zope.app.container to zope.container.3.4.5 (2010-01-28)• Backport r108613 from trunk: Fix for an edge case: If someone does a defaultView for the context object and someone comes with a not allowed method, the exception view fails on getAdapters3.4.4 (2009-01-29)• Make tests compatible with new zope.traversing release.3.4.3 (2009-01-27)• Added missing depencendy: zope.app.zcmlfiles3.4.2 (2009-01-26)• Add a couple of tests to the OPTIONS verb. • Substitute zope.app.zapi by direct calls to its wrapped apis and get rid of zope.app.zapi as a dependency. See bug LP219302. zope.app.i18n3.6.2 (2009-10-07)• Fix test_translate and follow recent change of HTTPResponse.redirect.2.1. What’s new in BlueBream 1.0 ? 53 BlueBream Documentation, Release 1.0a43.6.1 (2009-08-15)• Added a missing testing dependency on zope.app.component.3.6.0 (2009-03-18)• Some of ZCML configuration was moved into another packages: – The global INegotiator utility registration was moved into zope.i18n. – The include of zope.i18n.locales was also moved into zope.i18n. – The registration of IModifiableUserPreferredLanguages adapter was moved into zope.app.publisher. – The IAttributeAnnotation implementation statement for HTTPRequest was moved into zope.publisher and will only apply if zope.annotation is available. – The IUserPreferredCharsets adapter registration was also moved into zope.publisher. • Depend on zope.component >= 3.6 instead of zope.app.component as the queryNextUtility function was moved there. • Remove the old zope.app.i18n.metadirectives module as the directive was moved to zope.i18n ages ago.3.5.0 (2009-02-01)• Use zope.container instead of zope.app.container.3.4.6 (2009-01-27)• Fix a simple inconsistent MRO problem in tests • Substitute zope.app.zapi by direct calls to its wrapped apis. See bug 219302.3.4.5 (unreleased)• This was skipped over by accident. zope.app.interface3.5.0 (2009-05-21)• Factor out ObjectInterfacesVocabulary into zope.componentvocabulary. • Remove various test dependencies. zope.app.interpreter(No changes)54 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4 zope.app.intid3.7.1 (2010-01-10)• Fix ftesting.zcml due to the zope.securitypolicy update. • Removed unneeded dependency on zope.app.publisher, added the missing one on zope.security. • Added test dependency on zope.login.3.7.0 (2009-02-01)• Move core functionality to new zope.intid package, leaving only ZMI-related browser views here. Note, that if you used the exclude directive from zc.configuration package to exclude the subscribers.zcml file from zope.app.intid, you need to change the directive to exclude it from zope.intid now.3.6.0 (2009-01-31)• Changed dependency from zope.app.container to zope.container. • Move test dependencies zope.app.folder and zope.app.component as zope.site.3.5.1 (2008-12-11)• Make it possible to subscribe object-specific handlers for IntIdAddedEvent/IntIdRemovedEvent. Use them like the zope.app.container.interfaces.IObjectAddedEvent. • Include utility->id mapping of added ids to the IntIdAddedEvent. • Removed testing dependencies from install_requires.3.5.0 (2008-06-19)• Separate subscriber configuration into a separate ZCML file. zope.app.keyreference3.6.1 (2010-03-07)• Adapted tests for Python 2.4 • Added license file3.6.0 (2009-01-39)• Move all functionality to new zope.keyreference package. This package only provides backward- compatibility imports now.2.1. What’s new in BlueBream 1.0 ? 55 BlueBream Documentation, Release 1.0a43.5.0b2 (unknown)• Performance related change to the conflict resolution code in zope.app.keyreference.persistent.KeyReferenceToPersistent.__cmp__. • Added support for new ZODB.ConflictResolution.PersistentReference behavior to persistent key references so that they can now, in many cases, allow conflict resolution when they are used as keys or set members in ZODB BTrees data structures. • Move zope.testing to the “test” extra require, because it’s only needed for testing.3.4.0 (2007-10-24)• Initial release independent of the main Zope tree. zope.applicationcontrol3.5.5 (2010-01-09)• Initial release, extracted from zope.app.applicationcontrol. zope.app.locales3.6.0 (2009-12-28)• Added configure.zcml which registers the translations in the package. So the package contains its configuration. (Till now it was done in zope.app.zcmlfiles.)3.5.2 (2009-12-22)• Updated tests to handle Unicode correctly. • Update Japanese Translation (thanks Takeshi Yamamoto).3.5.1 (2009-01-27)• Added missing dependency (zope.tal) for tests.3.5.0 (2009-01-26)• Moved the dependencies of the extract console script into an extract extras_require to avoid runtime dependencies. • Fixed bug #227582 (bad size in zh_CN locale)56 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4 zope.app.localpermission3.7.1 (2010-02-22)• The zope.app namespace wasn’t declared correctly.3.7.0 (2009-03-14)Initial release. This package was extracted from zope.app.security to separate the functionality without additional dependencies. zope.app.locking3.5.0 (2009-02-01)• Use zope.site instead of zope.app.folder in test. • Remove usage of deprecated zope.app.zapi. zope.app.onlinehelp3.5.2 (2010-01-08)• Fix tests using a newer zope.publisher that requires zope.login.3.5.1 (2009-03-21)• Use zope.site instead of zope.app.folder.3.5.0 (2009-02-01)• Removed OnlineHelpTopicFactory, simple and SimpleViewClass. All of them where using old deprecated and removed Zope3 imports. None of them where used and tested. • Use zope.container instead of zope.app.container. • Removed use of zope.app.zapi. zope.app.pagetemplate3.10.1 (2010-01-04)• Fixed the zope.browserpage imports in the namedtemplate module. 3.10.0 (2009-12-22) (************** • Moved named template implementation to zope.browserpage.2.1. What’s new in BlueBream 1.0 ? 57 BlueBream Documentation, Release 1.0a43.9.0 (2009-12-22)• Moved viewpagetemplatefile, simpleviewclass and metaconfigure.registerType into the zope.browserpage package, reversing the dependency.3.8.0 (2009-12-16)• Refactored nested macro test from a functional test into a unit test. This allowed to remove the last outside zope.app dependencies. • Fixed undeclared testing dependency on zope.app.component. • Copy trivial NoTraverser class from zope.app.publication to avoid a ZCML dependency on that package. • Correct testing dependency to point to zope.securitypolicy instead of its zope.app variant. The app version is no longer required since 3.4.1. • Removed the inline-evaluation extra referring to zope.app.interpreter. There’s no code or ZCML left pointing to that package.3.7.1 (2009-05-27)• Restored zope.app.pagetemplate.engine module, using BBB imports from zope.pagetemplate.engine.3.7.0 (2009-05-25)• Moved the engine module and associated testing machinery to zope.pagetemplate (version 3.5.0).3.6.0 (2009-05-18)• Moved namedtemplate.* from zope.formlib here as it is more about a page template engine than a formular library. This also breaks some dependencies on zope.formlib. • Added doctests to long_description to show up on pypi.3.5.0 (2009-02-01)• Use zope.container instead of zope.app.container. zope.app.preference3.6.0 (2009-02-01)• Use zope.container instead of zope.app.container.58 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.5.0 (2009-01-17)• Get rid of zope.app.zapi dependency, replacing its uses with direct imports from original places. • Change mailing address from zope3-dev to zope-dev, as the first one is retired now. • Fix tests for python 2.6. • Remove zpkg stuff and zcml include files for old mkzopeinstance-based instances. zope.app.preview(No changes) zope.app.principalannotation3.7.0 (2009-12-26)• Depend on new zope.processlifetime interfaces instead of using BBB imports from zope.app.appsetup. • Removed unneeded dependency on zope.app.publisher, added the missing one on transaction.3.6.1 (2009-03-31)• Got rid of DeprecationWarning in zope.app.appsetup >= 3.10. Ironically older versions now produce a DeprecationWarning.3.6.0 (2009-03-09)• Most of functionality is now moved to the zope.principalannotation package. This package now only provides the bootstrap subscriber for the zope3 application server as well as browser menu item for adding PrincipalAnnotationUtility using ZMI.3.5.1 (2009-03-06)• Make boostrap subscriber called on IDatabaseOpenedWithRootEvent instead of IDatabaseOpenedEvent, because this can cause bug if subscriber will be called before root object is created. • Use zope.site instead of zope.app.component.3.5.0 (2009-02-01)• Move boostrap subscriber to bootstrap.zcml file and browser menu item definition to browser.zcml file to ease overriding and excluding configuration. • Use zope.container instead of zope.app.container.2.1. What’s new in BlueBream 1.0 ? 59 BlueBream Documentation, Release 1.0a4 zope.app.publication3.10.2 (2010-01-08)• Lift the test dependency on zope.app.zptpage.3.10.1 (2010-01-08)• make zope.testing an optional (test) dependency • Fix tests using a newer zope.publisher that requires zope.login.3.10.0 (2009-12-15)• Moved EndRequestEvent and IEndRequestEvent to zope.publisher. • Moved BeforeTraverseEvent and IBeforeTraverseEvent to zope.traversing. • Removed dependency on zope.i18n. • Import hooks functionality from zope.component after it was moved there from zope.site. • Import ISite from zope.component after it was moved there from zope.location.3.9.0 (2009-09-29)• An abort within handleExceptions could have failed without logging what caused the error. It now logs the original problem. • Moved registration of and tests for two publication-specific event handlers here from zope.site in order to invert the package dependency. • Declared the missing dependency on zope.location.3.8.1 (2009-06-21)• Bug fix: The publication traverseName method used ProxyFactory rather than the publication proxy method.3.8.0 (2009-06-20)• Added a proxy method that can be overridden in subclasses to control how/if security proxies are created. • Replaced zope.deprecation dependency with backward-compatible imports3.7.0 (2009-05-23)• Moved the publicationtraverse module to zope.traversing, removing the zope.app.publisher -> zope.app.publication dependency (which was a cycle). • Moved IHTTPException to zope.publisher, removing the dependency on zope.app.http.60 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4• Moved the DefaultViewName API from zope.app.publisher.browser to zope.publisher.defaultview, making it accessible to other packages that need it. • Look up the application controller through a utility registration rather than a direct reference.3.6.0 (2009-05-18)• Use zope:adapter ZCML directive instead of zope:view. This avoid dependency on zope.app.component. • Update imports from zope.app.security to zope.authentication and zope.principalregistry. • Use zope.browser.interfaces.ISystemError to avoid dependency on zope.app.exception. • Refactored tests so they can run successfully with ZODB 3.8 and 3.9.3.5.3 (2009-03-13)• Adapt to the removal of IXMLPresentation from zope.app.publisher which was removed to adapt to removal of deprecated interfaces from zope.component.3.5.2 (2009-03-10)• Use ISkinnable.providedBy(request) instead of IBrowserRequest as condition for calling setDefaultSkin. This at the same time removes dependency to the browser part of zope.publisher. • Remove deprecated code. • Use built-in set class instead of the deprecated sets.Set and thus don’t cause deprecation warning in Python 2.6.3.5.1 (2009-01-31)• Import ISite from zope.location.interfaces instead of deprecated place in zope.app.component.interfaces.3.5.0 (2008-10-09)• Now zope.app.publication.zopepublication.ZopePublication annotates the request with the connection to the main ZODB when getApplication is called. • Removed support for non-existent Zope versions. zope.app.publisher3.10.1 (2010-01-08)• Fix tests using a newer zope.publisher that requires zope.login.2.1. What’s new in BlueBream 1.0 ? 61 BlueBream Documentation, Release 1.0a43.10.0 (2009-08-31)• Fix test dependency on zope.container, now we depend on zope.container >= 3.9.3.9.0 (2009-08-27)Refactor package, spliting it to several new packages: • zope.browserresource - the resources mechanism was moved here, see its CHANGES.txt for more information about changes during move. • zope.ptresource - the page template resource was moved into another package so zope.browserresource doesn’t depend on any templating system. See zope.ptresource’s CHANGES.txt for more information. • zope.browsermenu - the menu mechanism was moved here completely. • zope.browserpage - the browser:page directive and friends were moved here. Also, these directives don’t depend hardly on menu system anymore, so they simply ignore the “menu” argument when zope.browsermenu is not available. Backward-compatibility imports are provided, so there should not be much impact for those who uses old imports. The CacheableBrowserLanguages and ModifiableBrowserLanguages adapters were moved into zope.publisher package, as well as browser:defaultSkin and browser:defaultView ZCML directives and ZCML class configuration for zope.publisher classes. ZCML registrations of IXMLRPCPublisher adapters for zope.container were moved into zope.container for now.3.8.4 (2009-07-23)• Added dependency on zope.app.pagetemplate, it is used by zope.app.publisher.browser.viewmeta.3.8.3 (2009-06-18)• Bugfix: Fix IAbsoluteURL for IResource configuration. The latest release was moving the url generation for resources to an adapter which was a good idea. But the adapter was configured for IDefaultBrowserLayer. This means every existing project which dosen’t use IDefaultBrowserLayer will get a wrong IAbsoluteURL adapter and is loosing the @@ part in the resource url.3.8.2 (2009-06-16)• Remove test dependency on zope.app.pagetemplate. • Calling a resource to get its URL now uses IAbsoluteURL.3.8.1 (2009-05-25)• Updated to use zope.pagetemplate.engine module (requires versino 3.5.0 or later), instead of zope.app.pagetemplate precursor.62 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4• Replaced zope.deprecation dependency with BBB imports3.8.0 (2009-05-23)• There is no direct dependency on zope.app.component anymore (even in the tests). • Moved the publicationtraverse module to zope.traversing, removing the zope.app.publisher -> zope.app.publication dependency (which was a cycle). • Moved the DefaultViewName API from zope.app.publisher.browser to zope.publisher.defaultview, making it accessible to other packages that need it.3.7.0 (2009-05-22)• Use zope.componentvocabulary instead of zope.app.component (except for tests and IBasicViewInformation). • Use zope.browser for IAdding interface (instead of zope.app.container) • Update references to zope.app.component.tests.views to point to the new locations in zope.component.testfiles.views.3.6.2 (2009-03-18)• Register IModifiableUserPreferredLanguages adapter in the ZCML configuration of zope.app.publisher.browser package. This was previously done by zope.app.i18n.3.6.1 (2009-03-12)• Remove deprecated code. • Adapt to removal of deprecated interfaces from zope.component.interfaces. The IResource is now moved to zope.app.publisher.interfaces. The IView and IDefaultViewName is now in zope.publisher.interfaces. The IPresentation interface was removed completely.3.6.0 (2009-01-31)• Use zope.container instead of zope.app.container. • Use zope.site.folder instead of zope.app.folder.3.5.3 (2009-01-27)• Finally removed <browser:skin> and <browser:layer> that were marked as deprecated in 2006/02.3.5.2 (2008-12-06)• Added possibility to specify custom item class in menuItem, subMenuItem and addMenuItem directives using the item_class argument (LP #291865).2.1. What’s new in BlueBream 1.0 ? 63 BlueBream Documentation, Release 1.0a4• Menu items registered with <browser:page/> were not re-registered after the first functional test layer ran. In any subsequent functional test layer the items where not availabe (introduced in 3.5.0a3). • Added a hook to specify a different BaseURL for resources. This makes sense if you want to put resources on a Content Delivery Network. All you need to do is to register an named Adapter ‘resource’ that implements IAbsoluteURL.3.5.1 (2008-10-13)• Removed usage of deprecated LayerField from zope.app.component.back35.3.5.0 (2008-08-05)• Refactored code to provide more hooks when deriving code from this pacakge. – A resource’s URL creation is now in its own method. – The resource class of factories can be overwritten. – The cache timeout value can now be set as a class or instance attribute.3.5.0a4 (2007-12-28)• Backed out the changes for the controversial XML-RPC skin support.3.5.0a3 (2007-11-27)• make it possible to override menus: this was not possible because new interfaces where created any time a menu with the same name was created. • Resolve ZopeSecurityPolicy deprecation warning.3.5.0a2 (2007-08-23)• <browser:defaultView> now accepts classes as well as interfaces.3.5.0a1 (2007-08-21)• Added a layer attribute to xmlrpc:view. This works just like layers for browser:view etc. but uses the IXMLR- PCSkinType. zope.app.renderer3.5.1 (2009-07-21)• Require the new roman package, since docutils does not install it correctly.64 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.5.0 (2009-01-17)• Adapted to docutils 0.5 for ReST rendering: get rid of the ZopeTranslator class, because docutils changed the way it uses translator so previous implementation doesn’t work anymore. Instead, use publish_parts and join needed parts in the render method of the renderer itself. • Removed deprecated meta.zcml stuff and zpkg stuff. • Replaced __used_for__ with zope.component.adapts calls. zope.app.rotterdam3.5.1 (2010-01-08)• Fix tests using a newer zope.publisher that requires zope.login.3.5.0 (2009-02-01)• Use zope.container instead of zope.app.container. zope.app.schema3.5.0 (2008-12-16)• Remove deprecated vocabulary directive. • Add test for component-based vocabulary registry. zope.app.security3.7.5 (2010-01-08)• Move ‘zope.ManageApplication’ permission to zope.app.applicationcontrol • Fix tests using a newer zope.publisher that requires zope.login.3.7.3 (2009-11-29)• provide a clean zope setup and move zope.app.testing to a test dependency • removed unused dependencies like ZODB3 etc. from install_requires3.7.2 (2009-09-10)• Added data attribute to ‘_protections.zcml’ for PersistentList and PersistentDict to accomodate UserList and UserDict behavior when they are proxied.2.1. What’s new in BlueBream 1.0 ? 65 BlueBream Documentation, Release 1.0a43.7.1 (2009-08-15)• Changed globalmodules.zcml to avoid making declarations for deprecated standard modules, to avoid deprecation warnings. Note that globalmodules.zcml should be avoided. It’s better to make declarations for only what you actually need to use.3.7.0 (2009-03-14)• All interfaces, as well as some authentication-related helper classes and functions (checkPrincipal, Princi- palSource, PrincipalTerms, etc.) were moved into the new zope.authentication package. Backward- compatibility imports are provided. • The “global principal registry” along with its zcml directives was moved into new “zope.principalregistry” package. Backward-compatibility imports are provided. • The IPrincipal -> zope.publisher.interfaces.logginginfo.ILoggingInfo adapter was moved to zope.publisher. Backward-compatibility import is provided. • The PermissionsVocabulary and PermissionIdsVocabulary has been moved to the zope.security package. Backward-compatibility imports are provided. • The registration of the “zope.Public” permission as well as some other common permissions, like “zope.View” have been moved to zope.security. Its configure.zcml is now included by this package. • The “protect” function is now a no-op and is not needed anymore, because zope.security now knows about i18n messages and __name__ and __parent__ attributes and won’t protect them by default. • The addCheckerPublic was moved from zope.app.security.tests to zope.security.testing. Backward- compatibility import is provided. • The LocalPermission class is now moved to new zope.app.localpermission package. This package now only has backward-compatibility imports and zcml includes. • Cleanup dependencies after refactorings. Also, don’t depend on zope.app.testing for tests anymore. • Update package’s description to point about refactorings done.3.6.2 (2009-03-10)• The Allow, Deny and Unset permission settings was preferred to be imported from zope.securitypolicy.interfaces for a long time and now they are completely moved there from zope.app.security.settings as well as the PermissionSetting class. The only thing left for backward compatibility is the import of Allow/Unset/Deny constants if zope.securitypolicy is installed to allow unpickling of security settings.3.6.1 (2009-03-09)• Depend on new zope.password package instead of zope.app.authentication to get password managers for the authentication utility, thus remove dependency on zope.app.authentication. • Use template for AuthUtilitySearchView instead of ugly HTML constructing in the python code.66 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4• Bug: The sha and md5 modules has been deprecated in Python 2.6. Whenever the ZCML of this package was included when using Python 2.6, a deprecation warning had been raised stating that md5 and sha have been deprecated. Provided a simple condition to check whether Python 2.6 or later is installed by checking for the presense of json module thas was added only in Python 2.6 and thus optionally load the security declaration for md5 and sha. • Remove deprecated code, thus removing explicit dependency on zope.deprecation and zope.deferredimport. • Cleanup code a bit, replace old __used_for__ statements by adapts calls.3.6.0 (2009-01-31)• Changed mailing list address to zope-dev at zope.org, because zope3-dev is retired now. Changed “cheeseshop” to “pypi” in the package homepage. • Moved the protectclass module to zope.security leaving only a compatibility module here that imports from the new location. • Moved the <module> directive implementation to zope.security. • Use zope.container instead of zope.app.container;.3.5.3 (2008-12-11)• use zope.browser.interfaces.ITerms instead of zope.app.form.browser.interfaces. zope.app.securitypolicy3.5.2 (2010-01-08)• Remove deprecated compatibility imports. Now, this package only contains ZMI views for zope.securitypolicy. • Update package’s description and mailing list address. • Fix tests using a newer zope.publisher that requires zope.login.3.5.1 (2009-01-27)• Added missing dependency for tests: zope.app.zcmlfiles3.5.0 (2008-12-11)• use zope.browser.interfaces.ITerms instead of zope.app.form.browser.interfaces This version requires zope.app.form 3.7.0 or higher if you use the browser part of this package. (grant form) • Substitute zope.app.zapi by direct calls to its wrapped apis. See bug 2193022.1. What’s new in BlueBream 1.0 ? 67 BlueBream Documentation, Release 1.0a4 zope.app.server3.5.0 (2009-12-19)• Use zope.password instead of zope.app.authentication • Depend on new zope.processlifetime implementations instead of using BBB imports from zope.app.appsetup. zope.app.session3.6.1 (2010-02-06)• Include meta.zcml from zope.securitypolicy3.6.0 (2009-02-01)• Use zope.site instead of zope.app.folder in tests.3.5.2 (2009-01-27)• Fixed tearDown-Error in tests. zope.app.skins(No changes) zope.app.testing3.7.4 (2010-01-08)• Import hooks functionality from zope.component after it was moved there from zope.site. • Import ISite from zope.component after it was moved there from zope.location. This lifts the dependency on zope.location. • Fix tests using a newer zope.publisher that requires zope.login.3.7.3 (2009-08-20)• Fixed tests for python 2.4 as well as python 2.5 and 2.6; the change in version 3.7.1 introduced test regressions in python 2.4.3.7.2 (2009-07-24)• Adjusted tests after the referenced memory leak problem has been fixed in zope.component.68 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.7.1 (2009-07-21)• Fixed failing tests. The code revealed that the tests expected the wrong value.3.7.0 (2009-06-19)• Depend on new zope.processlifetime interfaces instead of using BBB imports from zope.app.appsetup. • Removed unused dependency on zope.app.component.3.6.2 (2009-04-26)• Removed deprecated back35 module and loose the dependency on zope.deferredimport. • Adapt to zope.app.authentication refactoring. We depend on zope.password now instead. • Adapt to latest zope.app.security refactoring. We don’t need this package anymore.3.6.1 (2009-03-12)• Use ISkinnable.providedBy(request) instead of IBrowserRequest as condition for calling setDefaultSkin in HTTPCaller. This at the same time removes dependency to the browser part of zope.publisher. • Adapt to the move of IDefaultViewName from zope.component.interfaces to zope.publisher.interfaces. • Remove the DEPENDENCIES.cfg file for zpkg.3.6.0 (2009-02-01)• Fix AttributeError in zope.app.testing.setup.setUpTestAsModule (when called without name argument). • Use zope.container instead of zope.app.container. • Use zope.site instead of zope.app.folder and zope.app.component for some parts.3.5.6 (2008-10-13)• Change argument variable name in provideAdapter to not conflict with buitin keyword in Python 2.6.3.5.5 (2008-10-10)• Re-configured functional test setup to create test-specific instances of HTTPCaller to ensure that cookies are not shared by doctests in a test suite.3.5.4 (2008-08-25)• Clean up some transaction management in the functional test setup.2.1. What’s new in BlueBream 1.0 ? 69 BlueBream Documentation, Release 1.0a43.5.3 (2008-08-22)• Fix isolation enforcement for product configuration around individual tests.3.5.2 (2008-08-21)• Added missing dependency information in setup.py. • Added missing import. • Repair memory leak fix released in 3.4.3 to be more sane in the presence of generations.3.5.1 (2008-08-20)• Correct Fred’s “I’m a doofus” release.3.5.0 (2008-08-20)• Add support for product-configuration as part of functional layers; this more closely mirrors the configuration order for normal operation. zope.app.tree3.6.0 (2009-02-01)• Converted from using zope.app.container to zope.container.3.5.1 (2009-01-29)• Add compatibility for newer zope.traversing releases that require us to explicitly set up testing. This also works with older releases.3.5.0 (2009-01-17)• Get rid of zope.app.zapi dependency, replacing its uses with direct imports. • Clean up dependencies, move testing and rotterdam dependencies to extra requires. • Fix mailing list address to zope-dev@zope.org instead of retired zope3-dev@zope.org. Change cheeseshop to pypi in the package url. • Replace __used_for__ in adapters.py with zope.component.adapts calls to make more sense. • Remove obsolete zpkg files, zcml include file for mkzopeinstance-based installations, versions.txt that makes no sense now.70 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4 zope.app.twisted3.5.0 (2009-07-24)• Update tests to work with latest packages.3.4.2 (2009-01-27)• Fix tests. Remove unused code. • Add zope.testbrowser to testing dependencies for ZEO tests. • Remove unneeded dependency on ZODB3. • Remove dependency on zope.app.zapi, substituting its uses with direct imports. • Change “cheeseshop” to “pypi” in the package homepage. zope.app.undo3.5.0 (2009-02-01)• Adjusted tests so that basic objects and interfaces are pulled from zope.site and zope.location rather than zope.app.component. zope.app.wsgi3.6.1 (2010-01-29)• Support product configuration sections in Zope configuration files.3.6.0 (2009-06-20)• Import database events directly from zope.processlifetime instead of using BBB imports in zope.app.appsetup.3.5.2 (2009-04-03)• The WSGIPublisherApplication uses now the ILoggingInfo concept given from zope.publisher.interfaces.logginginfo for log user infos usable for access logs. This allows you to implement your own access log user info message. See zope.publisher.interfaces.logginginfo.ILoggingInfo for more information.3.5.1 (2009-03-31)• The WSGIPublisherApplication call now provides a user name in the environment meant for use in logs.2.1. What’s new in BlueBream 1.0 ? 71 BlueBream Documentation, Release 1.0a43.5.0 (2009-02-10)• Make devmode warning message more generic. We don’t nesessary have the etc/zope.conf file nowadays when using buildout-based setups. • Add an application factory for Paste. So Zope application can now be easily deployed with Paste .ini configuration like this:[app:main] use = egg:zope.app.wsgi config_file = %(here)s/zope.conf handle_errors = falseThe config_file is a required argument, however the handle_errors defaults to True if not specified. Setting it to False allows you to make WSGIPublisherApplication not handle exceptions itself but propagate them to an upper middleware, like WebError or something. • The WSGIPublisherApplication constructor and getWSGIApplication function now accept optional handle_errors argument, described above. • Change mailing list address to zope-dev at zope.org instead of retired one. zope.app.xmlrpcintrospection3.5.1 (2010-02-06)• Fix test by including zope.login • Include ftesting.zcml from zope.app.securitypolicy.browser.tests • Include meta.zcml from zope.securitypolicy3.5.0 (2009-02-01)• Update zope.app.folder with zope.site. zope.app.zcmlfiles3.7.0 (2009-12-28)• Use new zope.app.locales which has its own configure.zcml. • No longer using zope.testing.doctestunit as it is deprecated now. Using python’s doctest module.3.6.1 (2009-12-16)• Removed reference to no longer existing configure.zcml from zope.app.pagetemplate.tests.3.6.0 (2009-07-11)• No longer depends on deprecated zope.app.interface but on zope.componentvocabulary.72 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.5.5 (2009-05-23)• Added missing dependencies, including zope.app.http and zope.app.applicationcontrol.3.5.4 (2009-05-18)• Added missing zope.app.exception dependency, as we include its ZCML. • Added missing zope.app.testing test dependency to make tests pass.3.5.3 (2009-02-04)• Added zope.app.broken dependency (we include its ZCML).3.5.2 (2009-01-31)• We depended on zope.formlib but didn’t include its configuration. Now it’s included in configure.zcml. • We include ZCML of zope.app.error but didn’t mention it as a dependency.3.5.1 (2008-12-28)• Add include of zope.app.schema:configure.zcml. Because component-based vocabularies are used everywhere and we need to import zope.app.schema somehow to make it work. This is needed because of removal of the include of zope.app.schema’s meta.zcml in the previous release.3.5.0 (2008-12-16)• Remove deprecated include of zope.app.component.browser:meta.zcml. • Remove deprecated include of zope.app.schema:meta.zcml. • Remove use of zope.modulealias. zope.app.zopeappgenerations3.5.0 (2009-04-05)• Moved getRootFolder utility method from zope.app.zopeappgenerations to zope.app.generations.utility. • Fixed author email and home page address.2.1. What’s new in BlueBream 1.0 ? 73 BlueBream Documentation, Release 1.0a4 zope.app.zptpage3.5.1 (2010-01-08)• Use zope.pagetemplate instead of zope.app.pagetemplate. • Fix tests using a newer zope.publisher that requires zope.login.3.5.0 (2009-01-31)• Use zope.container instead of zope.app.container. • Use zope.site instead of zope.app.folder. Add missing dependency on zope.site. zope.authentication3.7.0 (2009-03-14)Initial release. This package was splitted off from zope.app.security to provide a separate common interface definition for authentication utilities without extra dependencies. zope.broken3.6.0 (2010-01-09)• The IBroken interface has been merged into the ZODB3 distribution. Import the interface from there, while providing a copy for backwards compatibility with older versions of the ZODB3.3.5.0 (2009-02-04)• Created zope.broken to hold depended upon bits of zope.app.broken. zope.browser0.5.0 (2008-12-11)• Moved ITerms interface here from zope.app.form.browser.interfaces to break undesirable dependencies. zope.browsermenu3.9.0 (2009-08-27)Initial release. This package was splitted off zope.app.publisher.74 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4 zope.browserpage3.11.0 (2009-12-22)• Also moved named template implementation from zope.app.pagetemplate here.3.10.1 (2009-12-22)• We need to depend on the untrustedpython extra of zope.security, since we import from zope.pagetemplate.engine.3.10.0 (2009-12-22)• Remove dependency on zope.app.pagetemplate by moving viewpagetemplatefile, simpleviewclass and metaconfigure.registerType into this package.3.9.0 (2009-08-27)• Initial release. This package was split off from zope.app.publisher. zope.browserresource3.10.2 (2009-11-25)• The previous release had a broken egg, sorry.3.10.1 (2009-11-24)• Import hooks functionality from zope.component after it was moved there from zope.site. This lifts the dependency on zope.site and thereby, ZODB. • Import ISite and IPossibleSite from zope.component after they were moved there from zope.location.3.10.0 (2009-09-25)• Add an ability to forbid publishing of some files in the resource directory, this is done by fnmatch’ing the wildcards in the forbidden_names‘‘class attribute of ‘‘DirectoryResource. By default, the .svn is in that attribute, so directories won’t publish subversion system directory that can contain private information.3.9.0 (2009-08-27)Initial release. This package was splitted off zope.app.publisher as a part of refactoring process. Additional changes that are made during refactoring:2.1. What’s new in BlueBream 1.0 ? 75 BlueBream Documentation, Release 1.0a4• Resource class for file resources are now selected the pluggable way. The resource directory publisher and browser:resource ZCML directive now creating file resources using factory utility lookup based on the file extension, so it’s now possible to add new resource types without introducing new ZCML directives and they will work inside resource directories as well. NOTE: the “resource_factories” attribute from the DirectoryResource was removed, so if you were using this attribute for changing resource classes for some file extensions, you need to migrate your code to new utility- based mechanism. See zope.browserresource.interfaces.IResourceFactoryFactory interface. • The Image resource class was removed, as they are actually simple files. To migrate, simply rename the “image” argument in browser:resource and browser:i18n-resource directives to “file”, if you don’t do this, resouces will work, but you’ll get deprecation warnings. If you need custom behaviour for images, you can register a resource factory utility for needed file extensions. • The PageTemplateResource was moved into a separate package, “zope.ptresource”, which is a plugin for this package now. Because of that, the “template” argument of browser:resource directive was deprecated and you should rename it to “file” to migrate. The PageTemplateResource will be created for “pt”, “zpt” and “html” files automatically, if zope.ptresource package is included in your configuration. • Fix stripping the “I” from an interface name for icon title, if no title is specified. • When publishing a resource via Resources view, set resource parent to an ISite object, not to current site manager. • Clean up code and improve test coverage. zope.cachedescriptors3.5.0 (2009-02-10)• Remove dependency on ZODB by allowing to specify storage factory for zope.cachedescriptors.method.cachedIn which is now dict by default. If you need to use BTree instead, you must pass it as factory argument to the zope.cachedescriptors.method.cachedIn decorator. • Remove zpkg-related file. • Clean up package description and documentation a bit. • Change package mailing list address to zope-dev at zope.org, as zope3-dev at zope.org is now retired.3.4.0 (2007-08-30)Initial release as an independent package zope.catalog3.8.1 (2009-12-27)• Removed zope.app.testing dependency.76 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.8.0 (2009-02-01)• Move core functionality from zope.app.catalog to this package. The zope.app.catalog package now only contains ZMI-related browser views and backward-compatibility imports. zope.component3.9.2 (2010-01-22)• Fixed a bug introduced by recent refactoring, where passing CheckerPublic to securityAdapterFactory wrongly wrapped the factory into a LocatingUntrustedAdapterFactory.3.9.1 (2010-01-21)• The tested testrunner somehow gets influenced by options of the outer testrunner, such a the -v option. We modified the tests so that it avoids this.3.9.0 (2010-01-21)• Add testlayer support. It is now possible to load a ZCML file within tests more easily. See zope.component.testlayer.py and zope.component.testlayer.txt.3.8.0 (2009-11-16)• Removed the dependencies on zope.proxy and zope.security from the zcml extra: zope.component does not hard depend on them anymore; the support for security proxied components ZCML registrations is enabled only if zope.security and zope.proxy are available. • Moved the IPossibleSite and ISite interfaces here from zope.location as they are dealing with zope.component’s concept of a site, but not with location. • Moved the zope.site.hooks functionality to zope.component.hooks as it isn’t actually dealing with zope.site’s concept of a site.3.7.1 (2009-07-24)• Fixed a problem, where queryNextUtility could fail if the context could not be adapted to a IComponentLookup. • Fixed 2 related bugs: When a utility is registered and there was previously a utility registered for the same interface and name, then the old utility is unregistered. The 2 bugs related to this: – There was no Unregistered for the implicit unregistration. Now there is. – The old utility was still held and returned by getAllUtilitiesRegisteredFor. In other words, it was still considered registered, eeven though it wasn’t. A particularly negative consequence of this is that the utility is held in memory or in the database even though it isn’t used.2.1. What’s new in BlueBream 1.0 ? 77 BlueBream Documentation, Release 1.0a43.7.0 (2009-05-21)• The HookableTests were not run by the testrunner. • Add in zope:view and zope:resource implementations into zope.component.zcml (dependency loaded with zope.component [zcml]).3.6.0 (2009-03-12)• IMPORTANT: the interfaces that were defined in the zope.component.bbb.interfaces and deprecated for years are now (re)moved. However, some packages, including part of zope framework were still using those interfaces. They will be adapted for this change. If you were using some of those interfaces, you need to adapt your code as well: – The IView and IDefaultViewName were moved to zope.publisher.interfaces. – The IResource was moved to zope.app.publisher.interfaces. – IContextDependent, IPresentation, IPresentationRequest, IResourceFactory, IViewFactory were removed completely. If you used IViewFactory in context of zope.app.form, there’s now IWidgetFactory in the zope.app.form.interfaces instead. • Add getNextUtility/queryNextUtility functions that used to be in zope.site earlier (and in zope.app.component even more earlier). • Added a pure-Python ‘hookable’ implementation, for use when ‘zope.hookable’ is not present. • Removed use of ‘zope.deferredimport’ by breaking import cycles. • Cleanup package documentation and changelog a bit. Add sphinx-based documentation building command to the buildout. • Remove deprecated code. • Change package’s mailing list address to zope-dev at zope.org, because zope3-dev at zope.org is now retired.3.5.1 (2008-07-25)• Fix bug introduced in 3.5.0: <utility factory=”...”> no longer supported interfaces declared in Python and always wanted an explicit provides=”...” attribute. https://bugs.launchpad.net/zope3/+bug/2518653.5.0 (2008-07-25)• Support registration of utilities via factories through the component registry and return factory information in the registration information. This fixes https://bugs.launchpad.net/zope3/+bug/240631 • Optimized un/registerUtility via storing an optimized data structure for efficient retrieval of already registered utilities. This avoids looping over all utilities when registering a new one.78 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4 zope.componentvocabulary1.0 (2009-05-19)• Initial public release, derived from zope.app.component and zope.app.interface to replace them. zope.configuration3.7.1 (2010-01-05)• Jython support: use __builtin__ module import rather than assuming __builtins__ is available • Jython support: deal with the fact that the Jython SAX parser returns attribute sets that have an empty string indicating no namespace instead of None. • Allow setup.py test to run at least a subset of the tests that would be run when using the zope testrunner: setup.py test runs 53 tests, while bin/test runs 156.3.7.0 (2009-12-22)• Adjust testing output to newer zope.schema. • Prefer zope.testing.doctest over doctestunit.3.6.0 (2009-04-01)• Removed dependency of zope.deprecation package. • Don’t suppress deprecation warnings any more in ‘zope.configuration’ package level. This makes it more likely other packages will generate deprecation warnings now, which will allow us to remove more outdated ones. • Don’t fail when zope.testing is not installed. • Added missing processFile method to IConfigurationContext. It is already implemented in the mix-in class, zope.configuration.config.ConfigurationContext, and used by implementations of include and exclude directives.3.5.0 (2009-02-26)• Added the exclude directive to standard directives. It was previously available via zc.configuration package and now it’s merged into zope.configuration. • Changed package’s mailing list address to zope-dev at zope.org, change “cheeseshop” to “pypi” in the package’s url.3.4.1 (2008-12-11)• Use built-in ‘set’ type, rather than importin the ‘sets’ module, which is deprecated in Python 2.6. • Added support to bootstrap on Jython.2.1. What’s new in BlueBream 1.0 ? 79 BlueBream Documentation, Release 1.0a4 zope.container3.11.0 (2009-12-31)• Copy two trivial classes from zope.cachedescriptors into this package, which allows us to remove that dependency. We didn’t actually use any caching properties as the dependency suggested.3.10.1 (2009-12-29)• Moved zope.copypastemove related tests into that package. • Removed no longer used zcml prefix from the configure file. • Stop importing DocTestSuite from zope.testing.doctestunit. Fixes compatibility problems with zope.testing 3.8.4.3.10.0 (2009-12-15)• Break testing dependency on zope.app.testing. • Break testing dependency on zope.app.dependable by moving the code and tests into that package. • Import ISite from zope.component after it was moved there from zope.location.3.9.1 (2009-10-18)• Rerelease 3.9.0 as it had a broken Windows 2.6 egg. • Marked as part of the ZTK.3.9.0 (2009-08-28)• Previous releases should be versioned 3.9.0 as they are not pure bugfix releases and worth a “feature” release, increasing feature version. Packages that depend on any changes introduced in version 3.8.2 or 3.8.3 should depend on version 3.9 or greater.3.8.3 (2009-08-27)• Move IXMLRPCPublisher ZCML registrations for containers from zope.app.publisher.xmlrpc to zope.container for now.3.8.2 (2009-05-17)• Rid ourselves of IContained interface. This interface was moved to zope.location.interfaces.A b/w compat import still exists to keep old code running. Depend on zope.location>=3.5.4.80 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4• Rid ourselves of the implementations of IObjectMovedEvent, IObjectAddedEvent, IObjectRemovedEvent interfaces and ObjectMovedEvent, ObjectAddedEvent and ObjectRemovedEvent classes. B/w compat imports still exist. All of these were moved to zope.lifecycleevent. Depend on zope.lifecycleevent>=3.5.2. • Fix a bug in OrderedContainer where trying to set the value for a key that already exists (duplication error) would actually delete the key from the order, leaving a dangling reference. • Partially break dependency on zope.traversing by disusing zope.traversing.api.getPath in favor of using ILocationInfo(object).getPath(). The rest of the runtime dependencies on zope.traversing are currently interface dependencies. • Break runtime dependency on zope.app.dependable by using a zcml condition on the qsubscriber ZCML directive that registers the CheckDependency handler for IObjectRemovedE- vent. If zope.app.dependable is not installed, this subscriber will never be registered. zope.app.dependable is now a testing dependency only.3.8.1 (2009-04-03)• Fixed misspackaged 3.8.03.8.0 (2009-04-03)• Change configure.zcml to not depend on zope.app.component. Fixes: https://bugs.launchpad.net/bugs/348329 • Moved the declaration of IOrderedContainer.updateOrder to a new, basic IOrdered interface and let IOrderedContainer inherit it. This allows easier reuse of the declaration.3.7.2 (2009-03-12)• Fix: added missing ComponentLookupError, missing since revision 95429 and missing in last release. • Adapt to the move of IDefaultViewName from zope.component.interfaces to zope.publisher.interfaces. • Add support for reserved names for containers. To specify reserved names for some container, you need to provide an adapter from the container to the zope.container.interfaces.IReservedNames interface. The default NameChooser is now also aware of reserved names.3.7.1 (2009-02-05)• Raise more “Pythonic” errors from __setitem__, losing the dependency on zope.exceptions: o zope.exceptions.DuplicationError -> KeyError o zope.exceptions.UserError -> ValueError • Moved import of IBroken interface to use new zope.broken package, which has no dependencies beyond zope.interface. • Made test part pull in the extra test requirements of this package. • Split the z3c.recipe.compattest configuration out into a new file, compat.cfg, to reduce the burden of doing standard unit tests. • Stripped out bogus develop eggs from buildout.cfg.2.1. What’s new in BlueBream 1.0 ? 81 BlueBream Documentation, Release 1.0a43.7.0 (2009-01-31)• Split this package off zope.app.container. This package is intended to have far less dependencies than zope.app.container. • This package also contains the container implementation that used to be in zope.app.folder. zope.contentprovider3.6.1 (2009-12-23)• Ensure that our configure.zcml can be loaded without requiring further dependencies. It uses a tales:expressiontype directive defined in zope.app.pagetemplate. We keep that dependency optional, as not all consumers of this package use ZCML to configure the expression type.3.6.0 (2009-12-22)• Updated test dependency to use zope.browserpage.3.5.0 (2009-03-18)• Add very simple, but useful base class for implementing content providers, see zope.contentprovider.provider.ContentProviderBase. • Remove unneeded testing dependencies. We only need zope.testing and zope.app.pagetemplate. • Remove zcml slug and old zpkg-related files. • Added setuptools dependency to setup.py. • Clean up package’s description and documentation a bit. Remove duplicate text in README. • Change mailing list address to zope-dev at zope.org instead of retired one. • Change cheeseshop to pypi in the package url. zope.contenttype3.5.0 (2009-10-22)• Moved the implementation of zope.publisher.contenttype to zope.contenttype.parse, moved tests along.3.4.3 (2009-12-28)• Updated mime-type for .js to be application/javascript.3.4.2 (2009-05-28)• Added MS Office 12 types based on: http://www.therightstuff.de/2006/12/16/Office+2007+File+Icons+For+Windows+SharePoint+Services+20+And+SharePoint+Portal+Server+2003.aspx82 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.4.1 (2009-02-04)• Improved text_type(). Based on the patch from http://www.zope.org/Collectors/Zope/2355/ • Add missing setuptools dependency to setup.py. • Added reference documentation. zope.copy3.5.0 (2009-02-09)• Initial release. The functionality was extracted from zc.copy to provide a generic object copying mechanism with minimal dependencies. zope.copypastemove3.6.0 (2009-12-16)• Use zope.principalannotation in favor of its app variant. • Avoid zope.app.component and testing dependencies.3.5.2 (2009-08-15)• Fix documentation for the IObjectCopier.copyTo method. • Added missing dependency on zope.app.component.3.5.1 (2009-02-09)• Use the new zope.copy package for ObjectCopier to provide pluggable copying mechanism that is not dependent on zope.location hardly. • Move the ItemNotFoundError exception to the interfaces module as it’s part of public API. Old import still works as we actually use it where it was previously defined, however, the new import place is preferred.3.5.0 (2009-01-31)• Use zope.container instead of zope.app.container.3.4.1 (2009-01-26)• Moved the test dependencies to a test extra requirement. zope.datetime(No changes)2.1. What’s new in BlueBream 1.0 ? 83 BlueBream Documentation, Release 1.0a4 zope.deferredimport3.5.0 (2009-02-04)• Added support to bootstrap on Jython. • Added reference documentation. zope.deprecation(No changes) zope.documenttemplate3.4.2 (2008/10/10)• Re-release 3.4.13.4.1 (2008/10/10)• Fixed usage of ‘with’ as a variable name. It is now a keyword in Python 2.6, causing a SyntaxError. zope.documenttemplate now supports Python 2.6. zope.dottedname3.4.6 (2009-09-15)• Make tests pass on python26.3.4.5 (2009-01-27)• Move README.txt in the egg, so tests works with the released egg as well.3.4.4 (2009-01-27)• Fix ReST in README.txt, fix broken tests with recent zope.testing.3.4.3 (2008-12-02)• More documentation and tests.84 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4 zope.dublincore3.6.0 (2009-12-02)• Removed the marker interface IZopeDublinCoreAnnotatable which doesn’t seem to be used. • Made the registration of ZDCAnnotatableAdapter conditional, lifting the dependency on zope.annotation and thereby the ZODB, leaving it as a test dependency.3.5.0 (2009-09-15)• Add missing dependencies. • Get rid of any testing dependencies beyond zope.testing. • Include browser ZCML configuration only if zope.browserpage is installed. • Specify i18n domain in package’s configure.zcml, because we use message IDs for permission titles. • Remove unused imports, fix one test that was inactive because of being overriden by another one by a mistake.3.4.2 (2009-01-31)• Declare dependency on zope.datetime.3.4.1 (2009-01-26)• Test dependencies are declared in a test extra now. • Fix: Make CreatorAnnotator not to fail if participation principal is None zope.error3.7.0 (2009-09-29)• Clean up dependencies. Drop all testing dependencies as we only need zope.testing now. • Fix ImportError when zope.testing is not available for some reason. • Remove zcml slug and old zpkg-related files. • Remove word “version” from changelog entries. • Change package’s mailing list address to zope-dev at zope.org as zope3-dev at zope.org is now retired. Also change cheeseshop to pypi in the package’s homepage url. • Add dependency on ZODB3 as we use Persistent. • Use a mock request for testing. Dropped the dependency on zope.publisher which was really only a testing dependency. • Reduced the dependency on zope.container to one on zope.location by no longer using the Contained mix-in class.2.1. What’s new in BlueBream 1.0 ? 85 BlueBream Documentation, Release 1.0a43.6.0 (2009-01-31)• Use zope.container instead of zope.app.container • Move error log bootstrapping logic (which was untested) to zope.app.appsetup, to which we added a test. zope.event3.4.1 (2009-03-03)• A few minor cleanups. zope.exceptions3.5.2 (2008-04-30)• Updated CHANGES.txt.3.5.1 (2008-04-28)• Reverted changes in 3.5.0.3.5.0• Added the capability for exceptions to be formatted line-by-line. Unfortunately, also introduced a bug cause each line of the exception to be its own log message. zope.file0.5.0 (2009-07-23)• Change package’s mailing list address to zope-dev at zope.org instead of the retired one. • Made tests compatible with ZODB 3.9. • Removed not needed install requirement declarations.0.4.0 (2009-01-31)• openDetached is now protected by zope.View instead of zope.ManageContent. • Use zope.container instead of zope.app.container.86 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4 zope.filerepresentation3.6.0 (2009-10-08)• Added IRawReadFile and IRawWriteFile interfaces. These extend IReadFile and IWritefile, respectively, to behave pretty much like a standard Python file object with a few embellishments. This in turn allows efficient, iterator- based implementations of file reading and writing. • Removed DEPENDENCIES.cfg • Removed dependency on zope.container: IReadDirectory and IWriteDirectory inherit only from interfaces defined in zope.interface and zope.interface.common.mapping.3.5.0 (2009-01-31)• Changed use of zope.app.container to zope.container. zope.formlib4.0.1 (2010-02-21)• Documentation uploaded to PyPI now contains widget documentation. • Escape MultiCheckBoxWidget content [LP:302427].4.0 (2010-01-08)• Widget implementation and all widgets from zope.app.form have been moved into zope.formlib, breaking zope.formlib’s dependency on zope.app.form (instead zope.app.form now depends on zope.formlib). Widgets can all be imported from zope.formlib.widgets. Widget base classes and render functionality is in zope.formlib.widget. All relevant widget interfaces are now in zope.formlib.interfaces.3.10.0 (2009-12-22)• Use named template from zope.browserpage in favor of zope.app.pagetemplate.3.9.0 (2009-12-22)• Use ViewPageTemplateFile from zope.browserpage.3.8.0 (2009-12-22)• Adjusted test output to new zope.schema release.2.1. What’s new in BlueBream 1.0 ? 87 BlueBream Documentation, Release 1.0a43.7.0 (2009-12-18)• Rid ourselves from zope.app test dependencies. • Fix: Button label needs escaping3.6.0 (2009-05-18)• Remove deprecated imports. • Remove dependency on zope.app.container (use IAdding from zope.browser.interfaces) instead. Depend on zope.browser>=1.1 (the version with IAdding). • Moved namedtemplate to zope.app.pagetemplate, to cut some dependencies on zope.formlib when using this feature. Left BBB imports here.3.5.2 (2009-02-21)• Adapt tests for Python 2.5 output.3.5.1 (2009-01-31)• Adapt tests to upcoming zope.schema release 3.5.1.3.5.0 (2009-01-26)New Features • Test dependencies are declared in a test extra now. • Introduced zope.formlib.form.applyData which works like applyChanges but returns a dictionary with information about which attribute of which schema changed. This information is then sent along with the IObjectModifiedEvent. This fixes https://bugs.launchpad.net/zope3/+bug/98483.Bugs Fixed • Actions that cause a redirect (301, 302) do not cause the render method to be called anymore. • The zope.formlib.form.Action class didn’t fully implement zope.formlib.interfaces.IAction. • zope.formlib.form.setupWidgets and zope.formlib.form.setupEditWidgets did not check for write access on the adapter but on context. This fixes https://bugs.launchpad.net/zope3/+bug/219948 zope.hookable3.4.1 (2009-04-05)• Updated tests for compatibility with Python 2.6 traceback formats. • Use Jython-compatible bootstrap.py.88 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4 zope.html2.0.0 (2009-09-04)• Add CKeditor 3.0 widget.1.2.0 (2009-07-06)• Use FCKeditor 2.6.4.1 • Remove _samples directory and erect a barrier to its resurrection1.1.0 (2008-06-18)• Use FCKeditor 2.6 • Use versioned directories for javascript to cache-bust zope.i18n3.7.2 (2009-12-14)• It’s a critical error when the GetText library is unavailable and compilation is required. • Use getSiteManager rather than getGlobalSiteManager in ZCML (these should be one in the same in any non- fancy setup, however if you’ve hooked getSiteManager, you want the ZCML handler to use the hooked version).3.7.1 (2009-08-07)• Fixed the interpackage translation domain merging feature to actually work. We need to defer the merging into the ZCML handler execution phase, as the utilities don’t exist yet during the ZCML parsing phase. Thx to Andreas Zeidler for finding and fixing the issue in PlacelessTranslationService in the first place. • Fix translation domains translating a message for a different domain. In the process, fix testMessageIDTrans- lateForDifferentDomain which seemed to work by mistake as the “other” and “default” domains used the same catalog. This is basically a reversion of 39991.3.7.0 (2009-03-18)• Updated locale data to CLDR 1.1. This introduces contextual month and day names and different month/day name widths. More CLDR updates are expected, see the “nadako-cldr” branch of zope.i18n. • Add configure.zcml that registers standard negotiator utility and includes zope.i18n.locales configuration. This was previously done by zope.app.i18n.2.1. What’s new in BlueBream 1.0 ? 89 BlueBream Documentation, Release 1.0a43.6.0 (2008-10-26)• Fixed a test failure in the compile mo file support. • Move the zcml support into an extra. This reduces the dependencies of a standard zope.i18n install by half a dozen packages.3.5.0 (2008-07-10)• Feature: Added new top-level negotiate function, which can be used to negotiate the language when the available languages are set globally via zope_i18n_allowed_languages. • Feature: Added support for restricting the available languages. We support an environment variable called zope_i18n_allowed_languages now, which is a list of comma or space separated language codes. If the environment variable is set, the ZCML registration will only process those folders which are in the allowed languages list. • Feature: Added optional automatic compilation of mo files from po files. You need to depend on the zope.i18n [compile] extra and set an environment variable called zope_i18n_compile_mo_files to any True value to enable this option. • Feature: Re-use existing translation domains when registering new ones. This allows multiple packages to register translations in the same domain. If the same message exists in multiple catalogs the one registered first will take precedence. • Feature: Recursive translations of message strings with mappings (https://bugs.launchpad.net/zope3/+bug/210177), thanks to Hermann Himmelbauer for the inital patch. • Bug: When parsing a date, the parsing pattern did not ensure that the line started and ended with the matching pattern, so that ‘1/1/2007’ parsed into ‘1/1/20’ for example. zope.i18nmessageid3.5.0 (2009-06-27)• Made compilation of C extension optional. • Added support to bootstrap on Jython. • Changed package’s mailing list address from zope3-dev at zope.org to zope-dev at zope.org, because zope3-dev is now retired. • Reformatted change log to common formatting style. • Update package description and docs a little. • Remove old .cfg files for zpkg. zope.index3.6.0 (2009-08-03)• Improved test readability and reached 100% test coverage. • Fixed a broken optimization in okascore.c: it was passing a Python float to the PyInt_AS_LONG() macro. This resulted in wrong scores, especially on 64 bit platforms, where all scores typically ended up being zero.90 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4• Changed okascore.c to produce the same results as its Python equivalent, reducing the brittleness of the text index tests.3.5.2 (2009-06-09)• Port okascore.c optimization used in okapiiindex from Zope2 catalog implementation. This module is compiled conditionally, based on whether your environment has a working C compiler. • Don’t use len(self._docweight) in okapiindex _search_wids method (obtaining the length of a BTree is very expensive at scale). Instead use self.documentCount(). Also a Zope2 port.3.5.1 (2009-02-27)• The baseindex, okapiindex, and lexicon used plain counters for various lengths, which is unsuitable for production applications. Backport code from Zope2 indexes which opportunistically replaces the counters with BTree.Length objects. • Backport non-insane version of baseindex._del_wordinfo from Zope2 text index. This improves deletion performance by several orders of magnitude. • Don’t modify given query dictionary in the KeywordIndex.apply method. • Move FieldIndex’s sorting functionality to a mixin class so it can be reused by zc.catalog’s ValueIndex.3.5.0 (2008-12-30)• Remove zope.testing from dependencies, as it’s not really needed. • Define IIndexSort interface for indexes that support sorting. • Implement sorting for FieldIndex (adapted from repoze.catalog/ZCatalog). • Add an apply method for KeywordIndex/TopicIndex, making them implement IIndexSearch that can be useful in catalog. • Optimize the search method of KeywordIndex/TopicIndex by using multiunion for the or operator and sorting before intersection for and. • IMPORTANT: KeywordIndex/TopicIndex now use IFSets instead of IISets. This makes it more compatible with other indexes (for example, when using in catalog). This change can lead to problems, if your code somehow depends on the II nature of sets, as it was before. Also, FilteredSets used to use IFSets as well, if you have any FilteredSets pickled in the database, you need to migrate them to IFSets yourself. You can do it like that: filter._ids = filter.family.IF.Set(filter._ids) Where filter is an instance of FilteredSet. • IMPORTANT: KeywordIndex are now non-normalizing. Because it can be useful for non-string keywords, where case-normalizing doesn’t make any sense. Instead, it provides the normalize method that can be overriden by subclasses to provide some normalization. The CaseInsensitiveKeywordIndex class is now provided that do case-normalization for string-based keywords. The old CaseSensitiveKeywordIndex is gone, applications should use KeywordIndex for that.2.1. What’s new in BlueBream 1.0 ? 91 BlueBream Documentation, Release 1.0a4Looks like the KeywordIndex/TopicIndex was sort of abadonware and wasn’t used by application developers, so after some discussion we decided to refactor them to make them more usable, optimal and compatible with other indexes and catalog. Porting application from old KeywordIndex/TopicIndex to new ones are rather easy and explained above, so we believe that it isn’t a problem. Please, use zope3-users@zope.org or zope-dev@zope.org mailing lists, if you have any problems with migration. Thanks Chris McDonough of repoze for supporting and useful code. zope.interface3.5.4 (2009-12-23)• Use the standard Python doctest module instead of zope.testing.doctest, which has been deprecated.3.5.3 (2009-12-08)• Fix an edge case: make providedBy() work when a class has ‘__provides__’ in its __slots__ (see http://thread.gmane.org/gmane.comp.web.zope.devel/22490)3.5.2 (2009-07-01)• BaseAdapterRegistry.unregister, unsubscribe: Remove empty portions of the data structures when something is removed. This avoids leaving references to global objects (interfaces) that may be slated for removal from the calling application.3.5.1 (2009-03-18)• verifyObject: use getattr instead of hasattr to test for object attributes in order to let exceptions other than AttributeError raised by properties propagate to the caller • Add Sphinx-based documentation building to the package buildout configuration. Use the bin/docs command after buildout. • Improve package description a bit. Unify changelog entries formatting. • Change package’s mailing list address to zope-dev at zope.org as zope3-dev at zope.org is now retired.3.5.0 (2008-10-26)• Fixed declaration of _zope_interface_coptimizations, it’s not a top level package. • Add a DocTestSuite for odd.py module, so their tests are run. • Allow to bootstrap on Jython. • Fix https://bugs.launchpad.net/zope3/3.3/+bug/98388: ISpecification was missing a declaration for __iro__. • Added optional code optimizations support, which allows the building of C code optimizations to fail (Jython). • Replaced _flatten with a non-recursive implementation, effectively making it 3x faster.92 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4 zope.intid3.7.2 (2009-12-27)• Use the zope.component API in favor of ztapi. • Removed zope.app.testing dependency.3.7.1 (2009-05-18)• Remove dependencies on zope.container. Instead import Object*Event classes from zope.lifecycleevent and import IContained from zope.location. In order to be able to do this, depend on zope.lifecycleevent>=3.5.2 and zope.location>=3.5.4. • Remove a dependency on zope.container.contained.Contained (this is a dumb base class that defines __parent__ and __name__ as None and declares that the class implements IContained).3.7.0 (2009-02-01)• Split out this package from zope.app.intid. The latter one now only contains browser views and compatibility imports while whole IntId functionality is moved here. zope.keyreference3.6.2 (2009-09-15)• Made the tests pass with ZODB3.9, which changed the repr() of the persistent classes.3.6.1 (2009-02-01)• Load keyreferences, pickled by old zope.app.keyreference even if its not installed anymore (so don’t break if one updates a project that don’t directly depends on zope.app.keyreference).3.6.0 (2009-01-31)• Rename zope.app.keyreference to zope.keyreference. zope.kgs1.2.0 (2009-07-24)• Add ability to specify the extra-includes for running tests.2.1. What’s new in BlueBream 1.0 ? 93 BlueBream Documentation, Release 1.0a41.1.0 (2009-02-01)• Added ‘–no-links’, ‘–no-index’, and ‘–no-minimal-index’ options to the site generation sctipt to make it faster. • Generating list of latest versions does not fail anymore, if downloading and parsing of the index page fails. • Update links to PyPI web sites.1.0.1 (2009-01-29)• Fix documentation in all scripts, fixing missing imports and incorrect wording. • The package should depend on python-dateutl and not datetutil, since the latter is not available in PyPI anymore.1.0.0 (2009-01-29)• Initial version as zope.kgs. – A script that extracts the relevant part of the changelog of each package in the KGS. – A script that lists all versions of a package released after the latest version listed in the KGS. – A script that manages the generation of the entire KGS site.* Generates generic and version-specific pages. * Page generation is template-based for easy customization. – Generate links.html file which lists all controlled packages files. – Features copied from zope.release:* Parser for KGS configuration files. * Generate versions.cfg and buildout.cfg script. – Features copied from zc.mirrorcheeseshopslashsimple:* Generate new index pages for the controlled packages. zope.lifecycleevent3.6.0 (2009-12-29)• Refactor tests to loose zope.annotation and zope.dublincore as dependencies.3.5.2 (2009-05-17)• IObjectMovedEvent, IObjectAddedEvent, IObjectRemovedEvent interfaces and ObjectMovedEvent, ObjectAddedEvent and ObjectRemovedEvent classes copied here from zope.container (plus tests). The intent is to allow packages that rely on these interfaces or the event classes to rely on zope.lifecycleevent (which has few dependencies) instead of zope.container (which has many).94 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.5.1 (2009-03-09)• Remove deprecated code and thus remove dependency on zope.deferredimport. • Change package’s mailing list address to zope-dev at zope.org, as zope3-dev at zope.org is now retired. • Update package’s description and documentation.3.5.0 (2009-01-31)• Remove old module declarations from classes. • Use zope.container instead of zope.app.container. zope.location3.9.0 (2009-12-29)• Moved LocationCopyHook related tests to zope.copy and remove a test dependency on that package.3.8.2 (2009-12-23)• Fixed a typo in the configure.zcml.3.8.1 (2009-12-23)• Removed dependency on zope.copy: the LocationCopyHook adapter is registered only if zope.copy is available. • Use the standard Python doctest module instead of zope.testing.doctest, which has been deprecated.3.8.0 (2009-12-22)• Adjusted to testing output caused by new zope.schema.3.7.1 (2009-11-18)• Moved the IPossibleSite and ISite interfaces to zope.component as they are dealing with zope.component’s concept of a site, but not with location.3.7.0 (2009-09-29)• Added getParent() to ILocationInfo and moved the actual implementation here from zope.traversal.api, analo- gous to getParents(). • Actually removed deprecated PathPersistent class from zope.location.pickling. • Moved ITraverser back to zope.traversing where it belongs conceptually. The interface had been moved to zope.location to invert the package interdependency but is no longer used here.2.1. What’s new in BlueBream 1.0 ? 95 BlueBream Documentation, Release 1.0a43.6.0 (2009-08-27)• New feature release: deprecated locationCopy, CopyPersistent and PathPersistent from zope.location.pickling. These changes were already part of the 3.5.3 release, which was erroneously numbered as a bugfix relese. • Removed dependency on zope.deferredimport, directly import deprecated modules without using it.3.5.5 (2009-08-15)• Add zope.deferredimport as a dependency as it’s used directly by zope.location.pickling.3.5.4 (2009-05-17)• Add IContained interface to zope.location.interfaces module. This interface was moved from zope.container (after zope.container 3.8.2); consumers of IContained may now depend on zope.location rather than zope.container to reduce dependency cycles.3.5.3 (2009-02-09)• Use new zope.copy package for implementing location copying. Thus there’s changes in the zope.locaton.pickling module: – The locationCopy and CopyPersistent was removed in prefer to their equivalents in zope.copy. Deprecated backward-compatibility imports provided. – The module now provides a zope.copy.interfaces.ICopyHook adapter for ILocation objects that replaces the old CopyPersistent functionality of checking for the need to clone objects based on their location.3.5.2 (2009-02-04)• Split RootPhysicallyLocatable adapter back from LocationPhysicallyLocatable, because the IRoot object may not always provide ILocation and the code for the root object is also simplier. It’s basically a copy of the RootPhysicallyLocatable adapter from zope.traversing version 3.5.0 and below with getParents method added (returns an empty list).3.5.1 (2009-02-02)• Improve test coverage. • The new getParents method was extracted from zope.traversing and added to ILocationInfo interface in the previous release. Custom ILocationInfo implementations should make sure they have this method as well. That method is already used in zope.traversing.api.getParents function. • Make getName of LocationPhysicallyLocatable always return empty string for the IRoot object, like Root- PhysicallyLocatable from zope.traversing did. So, now LocationPhysicallyLocatable is fully compatible with RootPhysicallyLocatable, making the latter one obsolete. • Change package mailing list address to zope-dev at zope.org instead of retired zope3-dev at zope.org.96 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.5.0 (2009-01-31)• Reverse the dependency between zope.location and zope.traversing. This also causes the dependency to various other packages go away. zope.login1.0.0 (2009-12-31)• Extracted BasicAuthAdapter and FTPAuth adapters from zope.publisher. They should have never gone into that package in the first place. zope.mimetype1.2.0 (2009-12-26)• Converted functional tests to unit tests and get rid of all extra test dependencies as a result. • Use the ITerms interface from zope.browser. • Declared missing dependencies, resolved direct dependency on zope.app.publisher. • Import content-type parser from zope.contenttype, adding a dependency on that package.1.1.2 (2009-05-22)• No longer depends on zope.app.component.1.1.1 (2009-04-03)• Fixed wrong package version (version 1.1.0 was released as 0.4.0 at pypi but as 1.1dev at download.zope.org/distribution) • Fixed author email and home page address.1.1.0 (2007-11-01)• Package data update. • First public release.1.0.0 (2007-??-??)• Initial release.2.1. What’s new in BlueBream 1.0 ? 97 BlueBream Documentation, Release 1.0a4 zope.minmax1.1.2 (2009-09-24)• Use the standard Python doctest module instead of the deprecated zope.testing.doctest.1.1.1 (2009-09-09)• Fixed homepage link and mailing list address. • Cleaned up.1.1 (2007-10-02)• Refactored package setup.1.0 (2007-09-28)• No further changes since 1.0b21.0b2 (2007-07-09)• Removed _p_independent method from AbstractValue class.1.0b1 (2007-07-03)• Initial release. zope.modulealias zope.pagetemplate3.5.0 (2009-05-25)• Added test coverage reporting support. • Moved ‘engine’ module and related test scaffolding here from zope.app.pagetemplate package.3.4.2 (2009-03-17)• Remove old zpkg-related DEPENDENCIES.cfg file. • Change package’s mailing list address to zope-dev at zope.org, as zope3-dev at zope.org is now retired. • Change cheeseshop to pypi in the packages’ homepage url.98 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.4.1 (2009-01-27)• Fix test due to recent changes in zope.tal. zope.password3.5.1 (2009-03-14)• Make security protection directives in configure.zcml execute only if zope.security is installed. This will allow reuse of the configure.zcml file in environments without zope.security, for example with repoze.zcml. • Add “Password Manager Names” vocabulary for use with zope.schema and zope.component, like it was in zope.app.authentication. It’s an optional feature so it doesn’t add hard dependency. We use “vocabulary” extra to list dependencies needed for vocabulary functionality.3.5.0 (2009-03-06)First release. This package was splitted off from zope.app.authentication to separate password manager functionality that is greatly re-usable without any bit of zope.app.authentication and to reduce its dependencies. zope.pluggableauth1.0.1 (2010-02-11)• Adapters are now declared in a new ZCML file : principalfactories.zcml. This avoids duplication errors in zope.app.authentication.1.0 (2010-02-05)• Splitting off from zope.app.authentication zope.principalannotation3.6.0 (2009-03-09)Initial release. This package was splitted off zope.app.principalannotation to remove its dependencies on “zope 3 application server” components. In addition, the following changes were made after split off: • The IAnnotations implementation was fixed to look in the higher-level utility not only on __getitem__, but also on get and __nonzero. • Tests was reworked into the README.txt doctest. • Added a buildout part that generates Sphinx documentation from the README.txt2.1. What’s new in BlueBream 1.0 ? 99 BlueBream Documentation, Release 1.0a4 zope.principalregistry3.7.0 (2009-03-14)• Remove zope.container dependency, as contained principals didn’t make any sense, since PrincipalReg- istry never provided IContainer. Also, zope.container pulls a number dependencies, that are not needed for non-persistent principal registry (like, ZODB, for example). Set __name__ and __parent__ by hand to provide some backward-compatibility and to save a pointer to registry from principal objects. • Initial release. This package was splitted from zope.app.security as a part of the refactoring process to provide global principal registry without extra dependencies. zope.processlifetime zope.proxy3.5.0 (2009/01/31)• Added support to bootstrap on Jython. • Use zope.container instead of zope.app.container. zope.ptresource3.9.0 (2009-08-27)Initial release. This package was splitted off zope.app.publisher as a part of refactoring process. It’s now a plugin for another package that was refactored from zope.app.publisher - zope.browserresource. See its documentation for more details. Other changes: • Don’t render PageTemplateResource when called as the IResource interface requires that __call__ method should return an absolute URL. When accessed by browser, it still will be rendered, because “browserDefault” method now returns a callable that will render the template to browser. zope.publisher3.12.1 (2010-02-21)• BaseRequest.traverse should not call traversal hooks on elements previously traversed but wrapped in a security Proxy.3.12.0 (2009-12-31)• Reverted change done in 3.6.2. The zope.authentication dependency has been removed again. The BasicAu- thAdapter and FTPAuth adapters are now found in the new zope.login package.100 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.11.0 (2009-12-15)• Moved EndRequestEvent and IEndRequestEvent from zope.app.publication into this package.3.10.1 (2009-11-28)• Version 3.10.0 needs at least version 3.5 of zope.contenttype but it did not declare it.3.10.0 (2009-10-22)• Moved the implementation of zope.publisher.contenttype to zope.contenttype.parse, leaving BBB imports and moving tests along. zope.contenttype is a new but light-weight dependency of this package. • Supported Python 2.6 by keeping QUERY_STRING out of request.form if the method is a POST. The original QUERY_STRING is still available if further processing is needed. • Better supported the zcml defaultSkin directive’s behavior (registering an interface as a default skin) in the setDefaultSkin function.3.9.3 (2009-10-08)• Fixed the check for untrusted redirects introduced in 3.9.0 so it works with virtual hosting.3.9.2 (2009-10-07)• Make redirect validation works without HTTP_HOST variable. • Add DoNotReRaiseException adapter that can be registered for exceptions to flag that they should not be reraised by publisher when handle_errors parameter of the publish method is False.3.9.1 (2009-09-01)• Convert a location, passed to a redirect method of HTTPRequest to string before checking for trusted host redirection, because a location object may be some non-string convertable to string, like URLGetter.3.9.0 (2009-08-27)• Some parts of zope.app.publisher packages was moved into this package during zope.app.publisher refactoring: – IModifiableUserPreferredLanguages adapter for requests – browser:defaultView and browser:defaultSkin ZCML directives – IHTTPView, IXMLRPCView and like interfaces – security ZCML declarations for some of zope.publisher classes2.1. What’s new in BlueBream 1.0 ? 101 BlueBream Documentation, Release 1.0a4• Introduced IReRaiseException interface. If during publishing an exception occurs and for this exception an adapter is available that returns False on being called, the exception won’t be reraised by the publisher. This happens only if handle_errors parameter of the publish() method is set to False. Fixes problems when acting in a WSGI pipeline with a debugger middleware enabled. See https://bugs.launchpad.net/grok/+bug/332061 for details. • Fix #98471: Restrict redirects to current host. This causes a ValueError to be raised in the case of redirecting to a different host. If this is intentional, the parameter trusted can be given. • Moved dependency on zope.testing from install_requires to tests_require. • Removed behavior of doing a time.sleep in the supportsRetry http request. • Add a fix for Internet Explorer versions that upload files will full filesystem paths as filenames.3.8.0 (2009-05-23)• Moved IHTTPException, IMethodNotAllowed, and MethodNotAllowed from zope.app.http to zope.publisher.interfaces.http, fixing dependency cycles involving zope.app.http. • Moved the DefaultViewName API from zope.app.publisher.browser to zope.publisher.defaultview, making it accessible to other packages that need it.3.7.0 (2009-05-13)• Move IView and IBrowserView interfaces into zope.browser.interfaces, leaving BBB imports.3.6.4 (2009-04-26)• Added some BBB code to setDefaultSkin to allow IBrowserRequest’s to continue to work without configuring any special adapter for IDefaultSkin. • Move getDefaultSkin to the skinnable module next to the setDefaultSkin method, leaving a BBB import in place. Mark IDefaultBrowserLayer as a IBrowserSkinType in code instead of relying on the ZCML to be loaded.3.6.3 (2009-03-18)• Mark HTTPRequest as IAttributeAnnotatable if zope.annotation is available, this was previously done by zope.app.i18n. • Register IHTTPRequest -> IUserPreferredCharsets adapter in ZCML configuration. This was also previously done by zope.app.i18n.3.6.2 (2009-03-14)• Add an adapter from zope.security.interfaces.IPrincipal to zope.publisher.interfaces.logginginfo.ILoggingInfo. It was moved from zope.app.security as a part of refactoring process.102 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4• Add adapters from HTTP and FTP request to zope.authentication.ILoginPassword interface. They are moved from zope.app.security as a part of refactoring process. This change adds a dependency on the zope.authentication package, but it’s okay, since it’s a tiny contract definition-only package. See http://mail.zope.org/pipermail/zope-dev/2009-March/035325.html for reasoning.3.6.1 (2009-03-09)• Fix: remove IBrowserRequest dependency in http implementation based on condition for setDefaultSkin. Use ISkinnable instead of IBrowserRequest.3.6.0 (2009-03-08)• Clean-up: Move skin related code from zope.publisher.interfaces.browser and zope.publisher.browser to zope.publihser.interfaces and zope.publisher.skinnable and provide BBB imports. See skinnable.txt for more information. • Fix: ensure that we only apply skin interface in setDefaultSkin which also provide IBrowserSkinType. This will ensure that we find a skin if the applySkin method will lookup for a skin based on this type interface. • Fix: Make it possible to use adapters and not only interfaces as skins from the adapter registry. Right now the defaultSkin directive registers simple interfaces as skin adapters which will run into a TypeError if someone tries to adapter such a skin adapter. Probably we should change the defaultSkin directive and register real adapters instead of using the interfaces as fake adapters where we expect adapter factories. • Feature: allow to use applySkin with different skin types using the optional argument skinType which is by default set to IBrowserSkinType • Feature: implemented the default skin pattern within adapters. This allows us to register default skins for other requests then only IBrowserRequest using IDefaultSkin adapters. Note, ISkinnable and ISkinType and the skin implementation should be moved out of the browser request modules. Packages like z3c.jsonrpc do not depend on IBrowserRequest but they are skinnable. • Feature: added ISkinnable interface which allows us to implement the apply skin pattern not only for IBrowser- Request • Fix: Don’t cause warnings on Python 2.6 • Fix: Make IBrowserPage inherit IBrowserView. • Move IView and IDefaultViewName from zope.component.interfaces to zope.publisher.interfaces. Stop inheriting from deprecated (for years) interfaces defined in zope.component. • Remove deprecated code. • Clean-up: Move “zope.testing” from extras to dependencies, per Zope Framework policy. Remove zope.app.testing as a dependency: tests run fine without it.3.5.6 (2009-02-14)Bugs fixed: • An untested code path that incorrectly attempted to construct a NotFound was fixed, with a test.2.1. What’s new in BlueBream 1.0 ? 103 BlueBream Documentation, Release 1.0a43.5.5 (2009-02-04)• LP #322486: setStatus() now allows any int()-able status value.3.5.4 (2008-09-22)Bugs fixed: • LP #98440: interfaces lost on retried request • LP #273296: dealing more nicely with malformed HTTP_ACCEPT_LANGUAGE headers within getPreferred- Languages(). • LP #253362: dealing more nicely with malformed HTTP_ACCEPT_CHARSET headers within getPreferred- Charsets(). • LP #98284: Pass the size argument to readline, as the version of twisted used in zope.app.twisted supports it. • Fix the LP #98284 fix: do not pass size argument of None that causes cStringIO objects to barf with a TypeError.3.5.3 (2008-06-20)Bugs fixed: • It turns out that some Web servers (Paste for example) do not send the EOF character after the data has been transmitted and the read() of the cached stream simply hangs if no expected content length has been specified.3.5.2 (2008-04-06)Bugs fixed: • A previous fix to handle posting of non-form data broke handling of form data with extra information in the content type, as in: application/x-www-form-urlencoded; charset=UTF-83.5.1 (2008-03-23)Bugs fixed: • When posting non-form (and non-multipart) data, the request body was consumed and discarded. This makes it impossible to deal with other post types, like xml-rpc or json without resorting to overly complex “request factory” contortions. • https://bugs.launchpad.net/zope2/+bug/143873 The zope.publisher.http.HTTPCharsets was confused by the Zope 2 publisher, which gives missleading information about which headers it has.104 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.5.0 (2008-03-02)Features added: • Added a PasteDeploy app_factory implementation. This should make it easier to integrate Zope 3 applications with PasteDeploy. It also makes it easier to control the publication used, giving far greater control over application policies (e.g. whether or not to use the ZODB).3.4.2 (2007-12-07)• Made segmentation of URLs not strip (trailing) whitespace from path segments to allow URLs ending in %20 to be handled correctly. (#172742)3.4.1 (2007-09-29)No changes since 3.4.1b2.3.4.1b2 (2007-08-02)• zope.publisher now works on Python 2.5. • Fix a problem with request.get() when the object that’s to be retrieved is the request itself.3.4.1b1 (2007-07-13)No changes.3.4.0b2 (2007-07-05)• Fix https://bugs.launchpad.net/zope3/+bug/122054: HTTPInputStream understands both the CON- TENT_LENGTH and HTTP_CONTENT_LENGTH environment variables. It is also now tolerant of empty strings and will treat those as if the variable were absent.3.4.0b1 (2007-07-05)• Fix caching issue. The input stream never got cached in a temp file because of a wrong content- length header lookup. Added CONTENT_LENGTH header check in addition to the previous used HTTP_CONTENT_LENGTH. The HTTP_ prefix is sometimes added by some CGI proxies, but CON- TENT_LENGTH is the right header info for the size. • Fix https://bugs.launchpad.net/zope3/+bug/98413: HTTPResponse.handleException should set the content type3.4.0a1 (2007-04-22)Initial release as a separate project, corresponds to zope.publisher from Zope 3.4.0a12.1. What’s new in BlueBream 1.0 ? 105 BlueBream Documentation, Release 1.0a4 zope.ramcache1.0 (2009-07-23)• Broke out the ram cache functionality from zope.app.cache. zope.rdb3.5.0 (2009/01/31)• Use zope.container instead of zope.app.container.3.4.2 (2008/10/10)• Re-release 3.4.13.4.1 (2008/10/10)• Remove body of DatabaseException, base Exception class already provides the same functionality. • Use hashlib.md5 instead of md5.new if available. md5 module is deprecated and will be removed in a future Python release. • Remove usage of ‘as’ as variable name. ‘as’ is a keyword in Python 2.6 and generates a SyntaxError. zope.schema3.6.1 (2010-01-05)• Allow “setup.py test” to run at least a subset of the tests runnable via bin/test (227 for setup.py test vs. 258. for bin/test) • Make zope.schema._bootstrapfields.ValidatedProperty descriptor work under Jython. • Make “setup.py test” tests pass on Jython.3.6.0 (2009-12-22)• Prefer zope.testing.doctest over doctestunit. • Extend validation error to hold the field name. • Add FieldProperty class that uses Field.get and Field.set methods instead of storing directly on the instance __dict__.106 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.5.4 (2009-03-25)• Don’t fail trying to validate default value for Choice fields with IContextSourceBinder object given as a source. See https://bugs.launchpad.net/zope3/+bug/340416. • Add an interface for DottedName field. • Add vocabularyName attribute to the IChoice interface, change “vocabulary” attribute description to be more sensible, making it zope.schema.Field instead of plain zope.interface.Attribute. • Make IBool interface of Bool more important than IFromUnicode so adapters registered for IBool take precen- dence over adapters registered for IFromUnicode.3.5.3 (2009-03-10)• Make Choice and Bool fields implement IFromUnicode interface, because they do provide the fromUnicode method. • Change package’s mailing list address to zope-dev at zope.org, as zope3-dev at zope.org is now retired. • Fix package’s documentation formatting. Change package’s description. • Add buildout part that builds Sphinx-generated documentation. • Remove zpkg-related file.3.5.2 (2009-02-04)• Made validation tests compatible with Python 2.5 again (hopefully not breaking Python 2.4) • Added an __all__ package attribute to expose documentation.3.5.1 (2009-01-31)• Stop using the old old set type. • Make tests compatible and silent with Python 2.4. • Fix __cmp__ method in ValidationError. Show some side effects based on the existing __cmp__ implementation. See validation.txt • Make ‘repr’ of the ValidationError and its subclasses more sensible. This may require you to adapt your doctests for the new style, but now it makes much more sense for debugging for developers.3.5.0a2 (2008-12-11)• Move zope.testing to “test” extras_require, as it is not needed for zope.schema itself. • Change the order of classes in SET_TYPES tuple, introduced in previous release to one that was in 3.4 (SetType, set), because third-party code could be dependent on that order. The one example is z3c.form’s converter.2.1. What’s new in BlueBream 1.0 ? 107 BlueBream Documentation, Release 1.0a43.5.0a1 (2008-10-10)• Added the doctests to the long description. • Removed use of deprecated ‘sets’ module when running under Python 2.6. • Removed spurious doctest failure when running under Python 2.6. • Added support to bootstrap on Jython. • Added helper methods for schema validation: getValidationErrors and getSchemaValidationErrors. • zope.schema now works on Python2.5 zope.security3.7.2 (2009-11-10)• Added compatibility with Python 2.6 abstract base classes.3.7.1 (2009-08-13)• Fix for LP bug 181833 (from Gustavo Niemeyer). Before “visiting” a sub-object, a check should be made to ensure the object is still valid. Because garbage collection may involve loops, if you garbage collect an object, it is possible that the actions done on this object may modify the state of other objects. This may cause another round of garbage collection, eventually generating a segfault (see LP bug). The Py_VISIT macro does the necessary checks, so it is used instead of the previous code.3.7.0 (2009-05-13)• Made pytz a soft dependency: the checker for pytz.UTC is created / tested only if the package is already present. Run bin/test_pytz to run the tests with pytz on the path.3.6.3 (2009-03-23)• Ensure that simple zope.schema’s VocabularyRegistry is used for PermissionVocabulary tests, because it’s replaced implicitly in environments with zope.app.schema installed that makes that tests fail. • Fixed a bug in DecoratedSecurityCheckerDescriptor which made security-wrapping location proxied exception instances throw exceptions on Python 2.5. See https://bugs.launchpad.net/zope3/+bug/2518483.6.2 (2009-03-14)• Add zope.i18nmessageid.Message to non-proxied basic types. It’s okay, because messages are immutable. It was done by zope.app.security before. • Add “__name__” and “__parent__” attributes to list of available by default. This was also done by zope.app.security package before.108 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4• Added PermissionsVocabulary and PermissionIdsVocabulary vocabularies to the zope.security.permission module. They were moved from the zope.app.security package. • Add zcml permission definitions for most common and useful permissions, like “zope.View” and “zope.ManageContent”, as well as for the special “zope.Public” permission. They are placed in a separate “permissions.zcml” file, so it can be easily excluded/redefined. They are selected part of permissions moved from zope.app.security and used by many zope.* packages. • Add addCheckerPublic helper function in zope.security.testing module that registers the “zope.Public” permission as an IPermission utility. • Add security declarations for the zope.security.permisson.Permission class. • Improve test coverage.3.6.1 (2009-03-10)• Use from imports instead of zope.deferred to avoid circular import problems, thus drop dependency on zope.deferredimport. • Raise NoInteraction when zope.security.checkPermission is called without interaction being active (LP #301565). • Don’t define security checkers for deprecated set types from the “sets” module on Python 2.6. It’s discouraged to use them and set and frozenset built-in types should be used instead. • Change package’s mailng list address to zope-dev at zope.org as zope3-dev at zope.org is now retired. • Remove old zpkg-related files.3.6.0 (2009-01-31)• Install decorated security checker support on LocationProxy from the outside. • Added support to bootstrap on Jython. • Moved the protectclass module from zope.app.security to this package to reduce the number of dependencies on zope.app.security. • Moved the <module> directive implementation from zope.app.security to this package. • Moved the <class> directive implementation from zope.app.component to this package.3.5.2 (2008-07-27)• Made C code compatible with Python 2.5 on 64bit architectures.3.5.1 (2008-06-04)• Add frozenset, set, reversed, and sorted to the list of safe builtins.2.1. What’s new in BlueBream 1.0 ? 109 BlueBream Documentation, Release 1.0a43.5.0 (2008-03-05)• Changed title for zope.security.management.system_user to be more presentable.3.4.0 (2007-10-02)• Updated meta-data.3.4.0b5 (2007-08-15)• Bug: Fixed a circular import in the C implementation.3.4.0b4 (2007-08-14)• Bug: zope.security.management.system_user had an ugly/brittle id.3.4.0b3 (2007-08-14)• zope.security now works on Python 2.5 • Bug: zope.security.management.system_user wasn’t a valid principal (didn’t provide IPrincipal). • Bug: Fixed inclusion of doctest to use the doctest module from zope.testing. Now tests can be run multiple times without breaking. (#98250)3.4.0b2 (2007-06-15)• Bug: Removed stack extraction in newInteraction. When using eggs this is an extremly expensive function. The publisher is now more than 10 times faster when using eggs and about twice as fast with a zope trunk checkout.3.4.0b1• Temporarily fixed the hidden (and accidental) dependency on zope.testing to become optional. Note: The releases between 3.2.0 and 3.4.0b1 where not tracked as an individual package and have been documented in the Zope 3 changelog.3.2.0 (2006-01-05)• Corresponds to the verison of the zope.security package shipped as part of the Zope 3.2.0 release. • Removed deprecated helper functions, ‘proxy.trustedRemoveSecurityProxy’ and ‘proxy.getProxiedObject’. • Made handling of ‘management.{end,restore}Interaction’ more careful w.r.t. edge cases. • Made behavior of ‘canWrite’ consistent with ‘canAccess’: if ‘canAccess’ does not raise ‘ForbiddenAttribute’, then neither will ‘canWrite’. See: http://www.zope.org/Collectors/Zope3-dev/506 • Code style / documentation / test fixes.110 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.1.0 (2005-10-03)• Added support for use of the new Python 2.4 datatypes, ‘set’ and ‘frozenset’, within checked code. • C security proxy acquired a dependency on the ‘proxy.h’ header from the ‘zope.proxy’ package. • XXX: the spelling of the ‘#include’ is bizarre! It seems to be related to ‘zpkg’-based builds, and should likely be revisited. For the moment, I have linked in the ‘zope.proxy’ package into our own ‘include’ directory. See the subversion checkin: http://svn.zope.org/Zope3/?rev=37882&view=rev • Updated checker to avoid re-proxying objects which have and explicit ‘__Security_checker__’ assigned. • Corresponds to the verison of the zope.security package shipped as part of the Zope 3.1.0 release. • Clarified contract of ‘IChecker’ to indicate that its ‘check*’ methods may raise only ‘Forbidden’ or ‘Unautho- rized’ exceptions. • Added interfaces, (‘IPrincipal’, ‘IGroupAwarePrincipal’, ‘IGroup’, and ‘IPermission’) specifying contracts of components in the security framework. • Code style / documentation / test fixes.3.0.0 (2004-11-07)• Corresponds to the version of the zope.security package shipped as part of the Zope X3.0.0 release. zope.securitypolicy3.6.1 (2009-07-24)• Make tests work when the default and Zope vocabulary registry compete in the cleanup.3.6.0 (2009-03-14)• Change zope.app.security dependency to the new zope.authentication package, dropping a big number of unused dependencies. • Get rid of zope.app.testing and other testing dependencices. • Add ZODB3 to install dependencies, because we use Persistent class. We didn’t fail before, because it was installed implicitly.3.5.1 (2009-03-10)• Don’t depend on the hook extra of zope.component, as we don’t need it explicitly. • Import security settings (Allow, Deny, Unset) in the interfaces module from the zope.securitypolicy.settings, added in previous release instead of old zope.app.security.settings. The zope.app.security will be adapted to import them from zope.securitypolicy.interfaces. • Use _z_instances instead of __instances__ for storing instances for zope.securitypolicy.settings.PermissionSetting singleton implementation, because __*__ name pattern is reserved for special names in python.2.1. What’s new in BlueBream 1.0 ? 111 BlueBream Documentation, Release 1.0a4• Add security protections for the PermissionSetting. • Improve documentation formatting, add it to the package’s long description. • Remove unneeded dependencies. • Remove old zpkg-related files and zcml slugs.3.5.0 (2009-01-31)• Include settings that were previously imported from zope.app.security.3.4.2 (2009-01-28)• Changed mailing list address to zope-dev at zope.org. Fix package homepage to the pypi page. • Fix test in buildout which still depended on zope.app.securitypolicy by mistake. • Remove explicit dependency on zope.app.form from setup.py; nothing in the code directly depends on this. zope.sendmail3.7.1 (2010-01-13)• Backward compatibility import of zope.sendmail.queue.QueueProcessorThread in zope.sendmail.delivery.3.7.0 (2010-01-12)• Removed dependency on zope.security: the security support is optional, and only available if the zope.security package is available. This change is similar to the optional security support introduced in zope.component 3.8.0, and in fact it uses the same helpers. • Sort by modification time the messages in zope.sendmail.maildir so earlier messages are sent before later messages during queue processing. • Added the new parameter processorThread to the queuedDelivery ZCML directive: if False, the Queue- ProcessorThread is not started and thus an independent process must process the queue; it defaults to True for b/c. • Provide a console script zope-sendmail which can be used to process the delivery queue in case proces- sorThread is False. The console script can either process the messages in the queue once, or run in “daemon” mode.3.6.1 (2009-11-16)• Depend on zope.component >= 3.8.0, which supports the new semantic of zope.component.zcml.proxify needed by zope.sendmail.zcml.112 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.6.0 (2009-09-14)• Use simple vocabulary factory function instead of custom UtilityTerm and UtilityVocabulary classes, copied from zope.app.component in the previous release. • Depend on the transaction package instead of ZODB3. • Remove zcml slugs and zpkg-related files. • Work around problem when used with Python >=2.5.1. See https://bugs.edge.launchpad.net/zope.sendmail/+bug/413335 .3.5.1 (2009-01-26)• Copied over the UtilityTerm and UtilityVocabulary implementation from zope.app.component to avoid a dependency. • Work around a problem when smtp quit fails, the mail was considered not delivered where just the quit failed.3.5.0 (2008-07-05)• final release (identical with 3.5.0b2)3.5.0b2 (2007-12-19)• If the SMTP server rejects a message (for example, when the sender or recipient address is malformed), that email stays in the queue forever (https://bugs.launchpad.net/zope3/+bug/157104).3.5.0b1 (2007-11-08)• Added README.txt • Can now talk to servers that don’t implement EHLO • Fix bug that caused files with very long names to be created • Fix for https://bugs.launchpad.net/zope3/+bug/157104: move aside mail that’s causing 5xx server responses.3.5.0a2 (2007-10-23)• Cleaned up does_esmtp in faux SMTP connection classes provided by the tests. • If the QueueProcessorThread is asked to stop while sending messages, do so after sending the current message; previously if there were many, many messages to send, the thread could stick around for quite a while.3.5.0a1 (2007-10-23)• QueueProcessorThread now accepts an optional parameter interval for defining how often to process the mail queue (default is 3 seconds)2.1. What’s new in BlueBream 1.0 ? 113 BlueBream Documentation, Release 1.0a4• Several QueueProcessorThreads (either in the same process, or multiple processes) can now deliver messages from a single maildir without duplicates being sent. zope.sequencesort(No changes) zope.server3.6.1 (2009-10-07)• Made tests pass with current zope.publisher which restricts redirects to the current host by default.3.6.0 (2009-05-27)• Moved some imports from test modules to their setUp to prevent failures when ZEO tests are run by the same testrunner • Removed unused dependency on zope.deprecation. • Remove old zpkg-related DEPENDENCIES.cfg file.3.5.0 (2008-03-01)• Improve package meta-data. • Fix of 599 error on conflict error in request see: http://mail.zope.org/pipermail/zope-dev/2008- January/030844.html • Removed dependency on ZODB.3.5.0a2 (2007-06-02)Made WSGI server really WSGI-compliant by adding variables to the environment that are required by the spec.3.5.0a1 (2007-06-02)Added a factory and entry point for PasteDeploy.3.4 (2007-04-22)• Initial release as a separate project, corresponds to zope.server from Zope 3.4.0a1 • Made WSGI server really WSGI-compliant by adding variables to the environment that are required by the spec.114 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4 zope.session3.9.2 (2009-11-23)• Fix Python 2.4 hmac compatibility issue by only using hashlib in Python versions 2.5 and above. • Use the CookieClientIdManager’s secret as the hmac key instead of the message when constructing and verifying client ids. • Make it possible to construct CookieClientIdManager passing cookie namespace and/or secret as constructor’s arguments. • Use zope.schema.fieldproperty.FieldProperty for “namespace” attribute of CookieClientIdManager, just like for other attributes in its interface. Also, make ICookieClientIdManager’s “namespace” field an ASCIILine, so it accepts only non-unicode strings for cookie names.3.9.1 (2009-04-20)• Restore compatibility with Python 2.4.3.9.0 (2009-03-19)• Don’t raise deprecation warnings on Python 2.6. • Drop dependency on zope.annotation. Instead, we make classes implement IAttributeAnnotatable in ZCML configuration, only if zope.annotation is available. If your code relies on annotatable CookieCli- entIdManager and PersistentSessionDataContainer and you don’t include the zcml classes configuration of this package, you’ll need to use classImplements function from zope.interface to make those classes implement IAttributeAnnotatable again. • Drop dependency on zope.app.http, use standard date formatting function from the email.utils module. • Zope 3 application bootstrapping code for session utilities was moved into zope.app.appsetup package, thus drop dependency on zope.app.appsetup in this package. • Drop testing dependencies, as we don’t need anything behind zope.testing and previous dependencies was simply migrated from zope.app.session before. • Remove zpkg files and zcml slugs. • Update package’s description a bit.3.8.1 (2009-02-23)• Add an ability to set cookie effective domain for CookieClientIdManager. This is useful for simple cases when you have your application set up on one domain and you want your identification cookie be active for subdomains. • Python 2.6 compatibility change. Encode strings before calling hmac.new() as the function no longer accepts the unicode() type.3.8.0 (2008-12-31)• Add missing test dependency on zope.site and zope.app.publication.2.1. What’s new in BlueBream 1.0 ? 115 BlueBream Documentation, Release 1.0a43.7.1 (2008-12-30)• Specify i18n_domain for titles in apidoc.zcml • ZODB 3.9 no longer contains ZODB.utils.ConflictResolvingMappingStorage, fixed tests, so they work both with ZODB 3.8 and 3.9.3.7.0 (2008-10-03)New features: • Added a ‘postOnly’ option on CookieClientIdManagers to only allow setting the client id cookie on POST requests. This is to further reduce risk from broken caches handing the same client id out to multiple users. (Of course, it doesn’t help if caches are broken enough to cache POSTs.)3.6.0 (2008-08-12)New features: • Added a ‘secure’ option on CookieClientIdManagers to cause the secure set-cookie option to be used, which tells the browser not to send the cookie over http. This provides enhanced security for ssl-only applications. • Only set the client-id cookie if it isn’t already set and try to prevent the header from being cached. This is to minimize risk from broken caches handing the same client id out to multiple users.3.5.2 (2008-06-12)• Remove ConflictErrors caused on SessionData caused by setting lastAccessTime.3.5.1 (2008-04-30)• Split up the ZCML to make it possible to re-use more reasonably.3.5.0 (2008-03-11)• Change the default session “resolution” to a sane value and document/test it. zope.site3.9.0 (2009-12-29)• Avoid a test dependency on zope.copypastemove by testing the correct persistent behavior of a site manager using the normal pickle module.116 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.8.0 (2009-12-15)• Removed functional testing setup and dependency on zope.app.testing.3.7.1 (2009-11-18)• Moved the zope.site.hooks functionality to zope.component.hooks as it isn’t actually dealing with zope.site’s concept of a site. • Import ISite and IPossibleSite from zope.component after they were moved there from zope.location.3.7.0 (2009-09-29)• Cleaned up the undeclared dependency on zope.app.publication by moving the two relevant subscriber registrations and their tests to that package. • Dropped the dependency on zope.traversing which was only used to access zope.location functionality. Config- ure zope.location for some tests. • Demoted zope.configuration to a testing dependency.3.6.4 (2009-09-01)• Set __parent__ and __name__ in the LocalSiteManager’s constructor after calling constructor of its superclasses, so __name__ doesn’t get overwritten with empty string by the Components constructor. • Don’t set __parent__ and __name__ attributes of site manager in SiteManagerContainer’s setSiteManager method, as they’re already set for LocalSiteManager. Other site manager implementations are not required to have those attributes at all, so we’re not adding them anymore.3.6.3 (2009-07-27)• Propagate an ObjectRemovedEvent to the SiteManager upon removal of a SiteManagerContainer.3.6.2 (2009-07-24)• Fixed tests to pass with latest packages. • Removed failing test of persistent interfaces, since it did not test anything in this package and used the deprecated zodbcode module. • Fix NameError when calling zope.site.testing.siteSetUp(site=True). • The getNextUtility and queryNextUtility functions was moved to zope.component. While backward-compatibility imports are provided, it’s strongly recommended to update your imports.3.6.1 (2009-02-28)• Import symbols moved from zope.traversing to zope.location from the new location. • Don’t fail when changing component registry bases while moving ISite object to non-ISite object.2.1. What’s new in BlueBream 1.0 ? 117 BlueBream Documentation, Release 1.0a4• Allow specify whether to create ‘default’ SiteManagementFolder on initializing LocalSiteManager. Use the default_folder argument. • Add a containment constraint to the SiteManagementFolder that makes it only available to be contained in ILocalSiteManagers and other ISiteManagementFolders. • Change package’s mailing list address to zope-dev at zope.org, as zope3-dev at zope.org is now retired. • Remove old unused code. Update package description.3.6.0 (2009-01-31)• Use zope.container instead of zope.app.container.3.5.1 (2009-01-27)• Extracted from zope.app.component (trunk, 3.5.1 under development) as part of an effort to clean up dependencies between Zope packages. zope.size3.4.1 (2009-09-10)• Added support to bootstrap on Jython. • Added docstrings • Beautify package’s README and include CHANGES into the description. • Changed package’s url to PyPI instead of Subversion. zope.structuredtext(No changes) zope.tal3.5.2 (2009-10-31)• In talgettext.POEngine.translate, print a warning if a msgid already exists in the domain with a different default.3.5.1 (2009-03-08)• Updated tests of “bad” entities for compatibility with the stricter HTMLParser module shipped with Python 2.6.x.118 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.5.0 (2008-06-06)• Removed artificial addition of a trailing newline if the output doesn’t end in one; this allows the template source to be the full specification of what should be included. (See https://bugs.launchpad.net/launchpad/+bug/218706.) zope.tales3.5.0 (2010-01-01)• Ported the lazy expression from Products.PageTemplates. zope.testbrowser3.7.0 (2009-12-17)• Moved zope.app.testing dependency into the scope of the PublisherConnection class. Zope2 specifies its own PublisherConnection which isn’t dependent on zope.app.testing. • Fixed LP #419119: return None when the browser has no contents instead of raising an exception.3.7.0a1 (2009-08-29)• Remove dependency on zope.app.publisher in favor of zope.browserpage, zope.browserresource and zope.ptresource. • Remove dependencies on zope.app.principalannotation and zope.securitypolicy by using the simple Permis- siveSecurityPolicy. We aren’t testing security in our tests. • Replaced the testing dependency on zope.app.zcmlfiles with explicit dependencies of a minimal set of packages. • Remove unneeded zope.app.authentication from ftesting.zcml. • Test dependency on zope.securitypolicy instead of its app variant.3.6.0a2 (2009-01-31)• Test dependency on zope.site.folder instead of zope.app.folder. • Remove useless test dependency in zope.app.component.3.6.0a1 (2009-01-08)• Author e-mail to zope-dev rather than zope3-dev. • New lines are no longer stripped in XML and HTML code contained in a textarea; fix requires ClientForm >= 0.2.10 (LP #268139). • Added cookies attribute to browser for easy manipulation of browser cookies. See brief example in main documentation, plus new cookies.txt documentation.2.1. What’s new in BlueBream 1.0 ? 119 BlueBream Documentation, Release 1.0a43.5.1 (2008-10-10)• Provide a work around for a mechanize/urllib2 bug on Python 2.6 missing ‘timeout’ attribute on ‘Request’ base class. • Provide a work around for a mechanize/urllib2 bug in creating request objects that won’t handle fragment URLs correctly.3.5.0 (2008-03-30)• Added a zope.testbrowser.testing.Browser.post method that allows tests to supply a body and a content type. This is handy for testing Ajax requests with non-form input (e.g. JSON). • Remove vendor import of mechanize. • Fix bug that caused HTTP exception tracebacks to differ between version 3.4.0 and 3.4.1. • Workaround for bug in Python Cookie.SimpleCookie when handling unicode strings. • Fix bug introduced in 3.4.1 that created incompatible tracebacks in doctests. This necessitated adding a patched mechanize to the source tree; patches have been sent to the mechanize project. • Fix https://bugs.launchpad.net/bugs/149517 by adding zope.interface and zope.schema as real dependencies • Fix browser.getLink documentation that was not updated since the last API modification. • Move tests for fixed bugs to a separate file. • Removed non-functional and undocumented code intended to help test servers using virtual hosting. zope.testing3.8.6 (2009-12-23)• Added MANIFEST.in and reuploaded to fix broken 3.8.5 release on PyPI.3.8.5 (2009-12-23)• Added DocFileSuite, DocTestSuite, debug_src and debug back BBB imports back into zope.testing.doctestunit; apparently many packages still import them from there! • Made zope.testing.doctest and zope.testing.doctestunit emit deprecation warnings: use the stdlib doctest instead.3.8.4 (2009-12-18)• Fixed missing imports and undefined variables reported by pyflakes, adding tests to exercise the blind spots. • Cleaned up unused imports reported by pyflakes. • Added two new options to generate randomly ordered list of tests and to select a specific order of tests. • RENormalizing checkers can be combined via + now: checker1 + checker2 creates a checker with the transformations of both checkers. • Test fixes for Python 2.7.120 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.8.3 (2009-09-21)• Avoid a split() call or we get test failures when running from a directory with spaces in it. • Fix testrunner behavior on Windows for -j2 (or greater) combined with -v (or greater).3.8.2 (2009-09-15)• Removing hotshot profiler when using Python 2.6. That makes zope.testing compatible with Python 2.63.8.1 (2009-08-12)• Avoid hardcoding sys.argv[0] as script; allow, for instance, Zope 2’s bin/instance test (LP#407916). • Produce a clear error message when a subprocess doesn’t follow the zope.testing.testrunner protocol (LP#407916). • Do not unnecessarily squelch verbose output in a subprocess when there are not multiple subprocesses. • Do not unnecessarily batch subprocess output, which can stymie automated and human processes for identifying hung tests. • Include incremental output when there are multiple subprocesses and a verbosity of -vv or greater is requested. This again is not batched, supporting automated processes and humans looking for hung tests.3.8.0 (2009-07-24)• Testrunner automatically picks up descendants of unittest.TestCase in test modules, so you don’t have to provide a test_suite() anymore.3.7.7 (2009-07-15)• Clean up support for displaying tracebacks with supplements by turning it into an always-enabled feature and making the dependency on zope.exceptions explicit. • Fix #251759: Test runner descended into directories that aren’t Python packages. • Code cleanups.3.7.6 (2009-07-02)• Add zope-testrunner console_scripts entry point. This exposes a zope-testrunner binary with default installs allowing the testrunner to be run from the command line.3.7.5 (2009-06-08)• Fix bug when running subprocesses on Windows. • The option REPORT_ONLY_FIRST_FAILURE (command line option “-1”) is now respected even when a doctest declares its own REPORTING_FLAGS, such as REPORT_NDIFF.2.1. What’s new in BlueBream 1.0 ? 121 BlueBream Documentation, Release 1.0a4• Fixed bug that broke readline with pdb when using doctest (see http://bugs.python.org/issue5727). • Made tests pass on Windows and Linux at the same time.3.7.4 (2009-05-01)• Filenames of doctest examples now contain the line number and not only the example number. So a stack trace in pdb tells the exact line number of the current example. This fixes https://bugs.launchpad.net/bugs/339813 • Colorization of doctest output correctly handles blank lines.3.7.3 (2009-04-22)• Better deal with rogue threads by always exiting with status so even spinning daemon threads won’t block the runner from exiting. This deprecated the --with-exit-status option.3.7.2 (2009-04-13)• fix test failure on Python 2.4 because of slight difference in the way coverage is reported (__init__ files with only a single comment line are now not reported) • fixed bug that caused the test runner to hang when running subprocesses (as a result Python 2.3 is no longer supported). • there is apparently a bug in Python 2.6 (related to http://bugs.python.org/issue1303673) that causes the profile tests to fail. • added explanitory notes to buildout.cfg about how to run the tests with multiple versions of Python3.7.1 (2008-10-17)• The setupstack temporary-directory support now properly handles read-only files by making them writable before removing them.3.7.0 (2008-09-22)• Added an alterate setuptools / distutils commands for running all tests using our testrunner. See ‘zope.testing.testrunner.eggsupport:ftest’. • Added a setuptools-compatible test loader which skips tests with layers: the testrunner used by ‘setup.py test’ doesn’t know about them, and those tests then fail. See ‘zope.testing.testrunner.eggsupport:SkipLayers’. • Added support for Jython, when a garbage collector call is sent. • Added support to bootstrap on Jython. • Fixed NameError in StartUpFailure. • Open doctest files in universal mode, so that packages released in Windoes can be tested in Linux, for example.122 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.6.0 (2008/07/10)• Added -j option to parallel tests run in subprocesses. • RENormalizer accepts plain Python callables. • Added –slow-test option. • Added –no-progress and –auto-progress options. • Complete refactoring of the test runner into multiple code files and a more modular (pipeline-like) architecture. • Unified unit tests with the layer support by introducing a real unit test layer. • Added a doctest for zope.testing.module. There were several bugs that were fixed: – README.txt was a really bad default argument for the module name, as it is not a proper dotted name. The code would immediately fail as it would look for the txt module in the README package. The default is now __main__. – The tearDown function did not clean up the __name__ entry in the global dictionary. • Fix a bug that caused a SubprocessError to be generated if a subprocess sent any output to stderr. • Fix a bug that caused the unit tests to be skipped if run in a subprocess.3.5.1 (2007/08/14)Bugs Fixed • Post-mortem debugging wasn’t invoked for layer-setup failures.3.5.0 (2007/07/19)New Features • The test runner now works on Python 2.5. • Added support for cProfile. • Added output colorizing (-c option). • Added –hide-secondary-failures and –show-secondary-failures options (https://bugs.launchpad.net/zope3/+bug/115454).Bugs Fixed • Fix some problems with Unicode in doctests. • Fix “Error reading from subprocess” errors on Unix-like systems.3.4 (2007/03/29)New Features • Added exit-with-status support (supports use with buildbot and zc.recipe.testing) • Added a small framework for automating set up and tear down of doctest tests. See setupstack.txt.2.1. What’s new in BlueBream 1.0 ? 123 BlueBream Documentation, Release 1.0a4Bugs Fixed • Fix testrunner-wo-source.txt and testrunner-errors.txt to run with a read-only source tree.3.0 (2006/09/20)• Updated the doctest copy with text-file encoding support. • Added logging-level support to loggingsuppport module. • At verbosity-level 1, dots are not output continuously, without any line breaks. • Improved output when the inability to tear down a layer causes tests to be run in a subprocess. • Made zope.exception required only if the zope_tracebacks extra is requested.2.x.y (???)• Fix the test coverage. If a module, for example interfaces, was in an ignored directory/package, then if a module of the same name existed in a covered directory/package, then it was also ignored there, because the ignore cache stored the result by module name and not the filename of the module.2.0 (2006/01/05)• Corresponds to the version of the zope.testing package shipped as part of the Zope 3.2.0 release. zope.thread(No changes) zope.traversing3.12.0 (2009-12-29)• Avoid testing dependencies on zope.securitypolicies and zope.principalregistry.3.11.0 (2009-12-27)• Removed testing dependency on zope.app.publication.3.10.0 (2009-12-16)• Removed stray test claiming a no longer existing dependency on zope.app.applicationcontrol. • Refactored functional tests to loose dependency on both zope.app.appsetup and zope.app.testing. • Simplified tests for the browser sub-package by using PlacelessSetup from zope.component.testing instead of zope.app.testing. • Simplified test_dependencies module by using zope.configuration instead of zope.app.testing.functional.124 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a4• Removed testing dependency on zope.app.publisher. • Replaced testing dependency on zope.app.security with zope.securitypolicy. • Removed testing dependency on zope.app.zcmlfiles in favor of more explicit dependencies. • Removed testing dependency on zope.app.component. • Replaced a test dependency on zope.app.zptpage with a dependency on zope.pagetemplate.3.9.0 (2009-12-15)• Moved IBeforeTraverseEvent from zope.app.publication into this package, as we already deal with publication traversal.3.8.0 (2009-09-29)• In zope.traversing.api.getParent(), try to delegate to zope.location.interfaces.ILocationInfo.getParent(), analo- gous to getParents(). Keep returning the traversal parent as a fallback. • Brought ITraverser back from zope.location where it had been moved to invert the package interdependency, but is no longer used now.3.7.2 (2009-08-29)• Made virtual hosting tests compatible with zope.publisher 3.9. Redirecting to a different host requires an explicit trusted redirect now.3.7.1 (2009-06-16)• AbsoluteURL now implements the fact that __call__ returns the same as __str__ in a manner that it applies for subclasses, too, so they only have to override __str__ and not both.3.7.0 (2009-05-23)• Moved the publicationtraverse module to zope.traversing, removing the zope.app.publisher -> zope.app.publication dependency (which was a cycle). • Look up the application controller through a utility registration rather than a direct reference.3.6.0 (2009-04-06)• Change configure.zcml to not depend on zope.app.component. • This release includes the BBB-incompatible zope.publisher.skinnable change from 3.5.3.3.5.4 (2009-04-06)• Revert BBB-incompatible use of zope.publisher.skinnable: that change belongs in a 3.6.0 release, because it requires a BBB-incompatible version of zope.publisher.2.1. What’s new in BlueBream 1.0 ? 125 BlueBream Documentation, Release 1.0a43.5.3 (2009-03-10)• Use applySkin from new location. zope.publisher.skinnable instead of zope.publisher.browser. • Use IAbsoluteURL lookup instead of the “absolute_url” view in the recursive AbsoluteURL adapters (LP: #338101).3.5.2 (2009-02-04)• The RootPhysicallyLocatable is not the same as LocationPhysicallyLocatable now in zope.location. Fix the import and testing setups.3.5.1 (2009-02-02)• The RootPhysicallyLocatable adapter has been superseded by the refactored zope.location.traversing.LocationPhysicallyLocatable that we depend on since 3.5.0a4. Remove the adapter and its registration, and making its import place pointing to zope.location.traversing.LocationPhysicallyLocatable to maintain backward- compatibility. This also fixes a bug introduced in version 3.5.0a4 when trying to call getParents function for the root object. • Use direct imports instead of compatibility ones for things that were moved to zope.location. • Remove the zope.traversing.interfaces.INamespaceHandler interface, as it seems not to be used for years. • Change package’s mailing list address to zope-dev at zope.org instead of retired zope3-dev at zope.org3.5.0 (2009-01-31)• Use zope.container instead of zope.app.container. • Use zope.site instead of zope.app.folder in the unit tests. • Reduced, but did not eliminate, test dependencies on zope.app.component.3.5.0a4 (2008-08-01)• Reverse dependencies between zope.location and zope.traversing. • Updated (test) dependencies and tests to expect and work with a spec compliant TAL interpreter as available in zope.tal >= 3.5.0. • Fixed deprecation warning caused by using an old module name for ZopeSecurityPolicy in ftesting.zcml • Made sure traversing doesn’t raise an TypeError but a TraversalError when the traversal step before yielded a string.126 Chapter 2. What’s New ? BlueBream Documentation, Release 1.0a43.5.0a3 (2007-12-28)• backed out the controversial ++skin++ traverser for XML-RPC.3.5.0a2 (2007-11-28)• ported 3.4.1a1 to trunk – Do not use unicode strings to set the application server in the virtual host namespace. This caused abso- lute_url to create unicode URL’s. • Added a traverer for ++skin++ for XMLRPC skins (IXMLRPCSkinType). This also means that the normal ++skin++ namespace handler is only bound to IBrowserRequest. • Resolved the dependency on zope.app.applicationcontrol by importing the application controller only if the package is available.3.4.1a1 (2007-11-13)Do not use unicode strings to set the application server in the virtual host namespace. This caused absolute_url to create unicode URL’s.3.4.0 (2007-09-29)No further changes since 3.4.0a1.3.4.0a1 (2007-04-22)Initial release as a separate project, corresponds to zope.traversing from Zope 3.4.0a1 zope.viewlet3.7.0 (2009-12-22)• Depend on zope.browserpage in favor of zope.app.pagetemplate.3.6.1 (2009-08-29)• Fixed unit tests in README.txt.3.6.0 (2009-08-02)• Optimize the the script tag for the JS viewlet. This makes YSlow happy. • Remove ZCML slugs and old zpkg-related files. • Drop all testing dependncies except zope.testing.2.1. What’s new in BlueBream 1.0 ? 127 BlueBream Documentation, Release 1.0a43.5.0 (2009-01-26)• Removed the dependency on zope.app.publisher by moving four simple helper functions into this package and making the interface for describing the ZCML content provider directive explicit. • Typo fix in CSSViewlet docstring. zope.xmlpickle(No changes)128 Chapter 2. What’s New ? CHAPTER THREEGETTING STARTEDWarning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.3.1 IntroductionThis chapter narrates creating a web application project using BlueBream. If you complete this chapter, you should be able to: • Install PasteScript based BlueBream project template • Create a BlueBream application project using the template • Bootstrap the build system (Buildout) and build the application • Run WSGI based web server to serve the application • Run test cases and use the debug shell • Create Hello World applications Before proceeding, here is an overview of the sections. • Preparations: – Prerequisites and preparations you need to make to start a web application project using Blue- Bream. • Installation: – Instructions for installing BlueBream. • Creating a sample project: – Explain creating a sample project using bluebream project template. • Building the application: – Explain how to build the application using Buildout. • Basic usage: – Explain the basic usage of BlueBream commands. • Package directory structure: – Show the directory structure and describe the purpose of each directories and files. • At the end, a few hello world examples are also given.3.2 PreparationsThis document assume that you have already installed Python 2.6 and setuptools. As an alternative to setuptools, you can install distribute. If setuptools or distribute is installed you will get an easy_install command which you can use to install bluebream distribution.129 BlueBream Documentation, Release 1.0a4You can also install BlueBream inside a Python environment created using virtualenv. Although, virtualenv may not be required when you are working on the application itself. Because, Buildout support will available in the application created. Buildout is the recommended approach to create repeatable, isolated working environments. Buildout is a declarative, configuration driven build system created by Jim Fulton. It is recommended to use a custom built Python for working with BlueBream. You will be required to install a C compiler (gcc) in your system. Internet access to PyPI is required to perform installation of bluebream distribution. Later, to build the application using Buildout and to bootstrap the buildout itself, you need internet access. But for deployment, you can avoid the internet access using zc.sourcerelease package.3.3 InstallationIf you have installed setuptools or distribute an easy_install command will be available. Then, you can install BlueBream using easy_install command like this:$ easy_install bluebreamAs mentioned earlier, Internet access to PyPI is required to perform installation of bluebream distribution. If you use any proxy, make sure it works. The easy_install will look for the environment variable named http_proxy in GNU/Linux platforms. You can set it like this:$ set http_proxy="http://username:password@PROXY-IP-ADDRESS:PORT"Apart from bluebream distribution, easy_install will download and install its dependencies. The dependencies are: • PasteScript • PasteDeploy • Paste The installation of bluebream project template package is a one time process. Once the project package is ready, you don’t require the bluebream project template package anymore. Because, the project package you are going to create will be self-bootstrappable.3.4 Creating a sample projectThe bluebream distribution provides project templates based on PasteScript template. 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 bluebreamThis will bring a wizard asking details about your new project. If you provide package name, namespace package name and version number, you will get a working application which can be modified further. The project name will be used as the name of egg. You can also change the values provided later. Here is a screenshot of sample project creation:130 Chapter 3. Getting Started BlueBream Documentation, Release 1.0a4The project name can be give given as a command line argument:$ paster create -t bluebream sampleprojectThe name of namespace package also can be given from the command line:$ paster create -t bluebream sampleproject namespace_package=mycompanyIf you provide an option from the command line, it will not be prompted by the wizard. The other variables are give below, you may be give the values from command line, if required: • interpreter – Name of custom Python interpreter • version – Version (like 0.1) • description – One-line description of the package • long_description – Multi-line description (in reST) • keywords – Space-separated keywords/tags • author – Author name • author_email – Author email • url – URL of homepage • license_name – License name • zip_safe – True, if the package can be distributed as a .zip file otherwise False. 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. Note: Alternate Project Templates Alternate project templates will be available from 1.0b1 release onwards, and it is documented in the wiki.3.4. Creating a sample project 131 BlueBream Documentation, Release 1.0a43.5 Building the applicationAs mentioned earlier, the generated package is bundled with Buildout configuration (buildout.cfg) and Buildout bootstrap script (bootstrap.py). First you need to bootstrap the buildout itself:$ cd sampleproject $ python2.6 bootstrap.pyThe bootstrap script will install zc.buildout and setuptools package. Also, it will create the basic directory structure. Here is a screenshot of bootstrapping the buildout:Next step is building the application. To build the application, run the buildout:$ ./bin/buildoutHere is a screenshot of building the application:132 Chapter 3. Getting Started BlueBream Documentation, Release 1.0a4The buildout script will download all dependencies and setup the environment to run your application. The next section will show the basic usage.3.6 Basic usageThe most common thing you need while developing application is running the server. BlueBream use 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.iniAfter running the server, you can access the site from browser here: http://localhost:8080/ . The port number (8080) can be changed from the PasteDeploy configuration file (debug.ini). When you open the browser, it will look like as given in this screenshot:3.6. Basic usage 133 BlueBream Documentation, Release 1.0a4The second most common thing must be running the test cases. BlueBream by create a testrunner using the zc.recipe.testrunner Buildout recipe. You can see a test command inside the bin directory. To run test cases, you can run this command:$ ./bin/testSometimes 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.iniMore about the test runner and debug shell will be exaplained in the BlueBream Manual.3.7 Package directory structureThe default directory structure created by the bluebream paster project template will look like this: myproject/ |-- bootstrap.py |-- buildout.cfg |-- debug.ini |-- deploy.ini |-- etc/ | |-- site.zcml | ‘-- zope.conf |-- setup.py |-- src/134 Chapter 3. Getting Started BlueBream Documentation, Release 1.0a4| |-- mynamespace.egg-info/ | ‘-- mynamespace/ | |-- __init__.py | ‘-- main/ | |-- application.zcml | |-- app.py | |-- configure.zcml | |-- debug.py | |-- ftesting.zcml | |-- __init__.py | |-- interfaces.py | |-- README.txt | |-- securitypolicy.zcml | |-- startup.py | |-- tests.py | |-- views.py | ‘-- static/ | |-- logo.png | ‘-- style.css |-- templates/ | ‘-- zope_conf.in |-- var/ ‘-- versions.cfgThe name of top-level directory will be always what you gave as project name in the wizard. The name of egg also will be same as that of package name by default. But if you want, you can change it to something else from setup.py. Here are the details about other files inside the project.3.7.1 Files & Purpose• bootstrap.py – Bootstrap script for Buildout • buildout.cfg – The buildout configuration • debug.ini – The PasteDeploy configuration for development • deploy.ini – The PasteDeploy configuration for deployment • etc/ – A location to add configuration files • etc/site.zcml – The main ZCML file • etc/zope.conf – The main Zope configuration file (generated from template) • setup.py – Project meta-data for creating distribution • src/ – All source code will be residing inside this directory • src/mynamespace.egg-info/ – This is where all distribution related info residing • src/mynamespace/ – The namespace package • src/mynamespace/__init__.py – This file with default content would be enough to make this a namespace package. • src/mynamespace/main/ – This is the main package which contains your application code. • src/mynamespace/main/application.zcml – Boiler plate ZCML to include other application specific ZCMLs. Now only the main package is included, you can add other ZCMLs from here.3.7. Package directory structure 135 BlueBream Documentation, Release 1.0a4• src/mynamespace/main/app.py – The main application object implementation. Replace the sample implementation with your application. • src/mynamespace/main/configure.zcml – You can customize this ZCML which is included from application.zcml • src/mynamespace/main/debug.py – The debug application object. The class given here will be registered from an entry point. • src/mynamespace/main/ftesting.zcml – ZCML for functional testing • src/mynamespace/main/__init__.py – The main package • src/mynamespace/main/interfaces.py – Interface definitions • src/mynamespace/main/README.txt – main packages’ README • src/mynamespace/main/securitypolicy.zcml – security policy declarations which is included from site.zcml • src/mynamespace/main/startup.py This script is called by WSGI server to start the application. (Mostly boiler plate code) • src/mynamespace/main/tests.py – Boiler plate to register tests. • src/mynamespace/main/views.py – An example view. • src/mynamespace/main/static/ – Static resource files (images, CSS etc.) • templates/ – Buildout specific templates used by “collective.recipe.template” • templates/zope_conf.in – Zope conf template, modify this file for any change in zope.conf • var/ – A place holder directory for storing all ZODB files, log files etc. • versions.cfg – All versions of files can be pinned down here. The next few sections will explain how to create hello world applications.3.8 Example 1: Hello World without page templateYou can watch the video creating hello world application here: To create a web page which displays Hello World!, you need to create a view class and register it using browser:page ZCML directive. In BlueBream, this is called as Browser Page. Sometimes more generic term, View is used instead of Browser Page which can be used to refer to HTTP, XMLRPC, REST and other views. By default, the default page which you are getting when you access: http://localhost:8080 is a page registered like this. You can see the registration inside configure.zcml, the name of view will be index. You can access the default page by explicitly mentioning the page name in the URL like this: http://localhost:8080/@@index. You can refer the Default view for objects HOWTO for more details about how the default view for a container object is working. First you need to create a Python file named myhello.py at src/mynamespace/main/myhello.py:$ touch src/mynamespace/main/myhello.pyYou can define your browser page inside this module. All browser pages should implement zope.publisher.interfaces.browser.IBrowserView interface. An easy way to do this would be to inherit from zope.publisher.browser.BrowserView which is already implementing the IBrowserView interface. The content of this file could be like this:136 Chapter 3. Getting Started BlueBream Documentation, Release 1.0a4 from zope.publisher.browser import BrowserView class HelloView(BrowserView): def __call__(self): return "Hello World!"Now you can register this page for a particular interface. So that it will be available as a browser page for any object which implement that particular interface. Now you can register this for the root folder, which is implementing zope.site.interfaces.IRootFolder interface. So, the registration will be like this:<browser:page for="zope.site.interfaces.IRootFolder" name="hello" permission="zope.Public" class=".myhello.HelloView" />Since you are using the browser XML namespace, you need to advertise it in the configure directive:<configure xmlns="http://namespaces.zope.org/zope" xmlns:browser="http://namespaces.zope.org/browser">You can add this configuration to: src/mynamespace/main/configure.zcml. Now you can access the view by visiting this URL: http://localhost:8080/@@hello Note: The @@ symbol for view @@ is a shortcut for ++view++. (Mnemonically, it kinda looks like a pair of goggle-eyes) To specify that you want to traverse to a view named bar of content object foo, you could (compactly) say .../foo/@@bar instead of .../foo/++view++bar. Note that even the @@ is not necessary if container foo has no element named bar - it only serves to disambiguate between views of an object and things contained within the object.3.9 Example 2: Hello World with page templateIn this example, you will create a hello world using a page template.3.9.1 Create a page templateFirst you need to create a page template file inside your package. You can save it as src/mynamespace/main/helloworld.pt, with the following content:<html> <head> <title>Hello World!

Hello World!

3.9. Example 2: Hello World with page template 137 BlueBream Documentation, Release 1.0a4

3.9.2 Register the page

Update configure.zcml to add this new page registration.

This declaration means: there is a web page called hello2, available for any content, rendered by the template helloworld.pt, and this page is public. This kind of XML conﬁguration is very common in BlueBream and you will need it for every page or component. In the above example, instead of using zope.site.interfaces.IRootFolder interface, * is used. So, this view will be available for all objects. Restart your application, then visit the following URL: http://127.0.0.1:8080/@@hello2

3.10 Example 3: A dynamic hello world

This section explain creating a dynamic hello world application.

3.10.1 Python class

In the src/mynamespace/main/hello.py ﬁle, add few lines of Python code like this:

class Hello(object):

def getText(self): name= self.request.get(’name’) if name: return "Hello %s !"% name else: return "Hello ! What’s your name ?"

This class deﬁnes a browser view in charge of displaying some content.

3.10.2 Page template

Now you need a page template to render the page content in html. So let’s add a hello.pt in the src/mynamespace/main directory:

hello world page

138 Chapter 3. Getting Started BlueBream Documentation, Release 1.0a4

fake content

The tal:content directive tells zope to replace the fake content of the tag with the output of the getText method of the view class.

3.10.3 ZCML registration

The next step is to associate the view class, the template and the page name. This is done with a simple XML configuration language (ZCML). Edit the existing file called configure.zcml and add the following content before the final :

This declaration means: there is a web page called hello3, available for any content, managed by the view class Hello, rendered by the template hello.pt, and this page is public. Since you are using the browser XML namespace, you need to declare it in the configure directive. Modify the first lines of the configure.zcml file so it looks like this (You can skip this step if the browser namespace is already there from the static hello world view):

Restart your application, then visit the following URL: http://127.0.0.1:8080/@@hello3 You should then see the following text in your browser:

Hello ! What’s your name ?

You can pass a parameter to the Hello view class, by visiting the following URL: http://127.0.0.1:8080/@@hello3?name=World You should then see the following text:

Hello World !

3.11 Conclusion

This chapter walked through the process of getting started with web application development with BlueBream. Also introduced few simple Hello World example applications. The Tutorial — Part 1 chapter will go through a bigger application to introduce more concepts.

3.11. Conclusion 139 BlueBream Documentation, Release 1.0a4

140 Chapter 3. Getting Started CHAPTER FOUR

CONCEPTS AND TECHNOLOGIES

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

4.1 Concepts

4.1.1 Interface

4.1.2 Zope Component Architecture

The main idea in the Zope Component Architecture is the use of components, rather than multiple-inheritance for managing complexity. Zope Component Architecture is about how to create reusable components, but not reusable components itself. A component is a reusable object with introspectable interfaces. Also components are cohesive and decoupled objects. A component provides an interface implemented in a class. It doesn’t matter how a component is implemented, the important part is that it complies with its interface contracts. An interface is an object that describes how you work with a particular component. Using Zope component architecture we can spread the complexity of systems over multiple cooperating components. Zope component architecture help us to create two basic kinds of components, adapters and utilities.

141 BlueBream Documentation, Release 1.0a4

4.1.3 Event

Events are objects that represent something happening in a system. They are used to extend processing by providing processing plug points. The zope.event provides the basic event publishing system. The zope.event package also provides a very simple event-dispatching system on which more sophisticated event dispatching systems can be built. For example, a type-based event dispatching system that builds on zope.event can be found in zope.component.

4.1.4 Adapter

Summary: Adapter takes the Interface of an existing component and adapts it to provide another Interface. When applications gets bigger, there is a side effect on the code, called the spaggethi effect: interactions between classes can lead to unwanted dependencies and the code turns into a monolithic bloc. Adapters provides a way to prevent from this, by implementing the Liskov substitution principle. Adapters provide a cooperation mechanism between any given object and a particular context, using interfaces. They allow an abritary type of class to be compatible with a given interface, by giving a compatibility layer. This mechanism is used in systems like Microsoft COM’s QueryAdapter, and let the developer gathers objects in a speciﬁc functional context. This also known as glue code. Adapters provides several advantages: • They can gather class instances in contexts they where not implemented for, without having to change their code or make them depend on each other. • They offer a smooth way to gather generic features, that can be applied on several kind of classes. Adapters can be seen as a formalized duck typing and where proposed some years ago in PEP 246. There are also Python implementations of it, like PyProtocols.

4.1.5 Utility

Utility components are components that serve only one speciﬁc function, and are not designed to act on another component. A good analogy for Python programmers are functions and methods. Utility components, like Python functions, are standalone objects that do not need any other objects to do their work. Adapter components, like Python methods, require another object to work upon. Utility components will mostly be used for simple, throw-away components that serve one simple task, like an XML parser. Sometimes it would be useful to register an object which is not adapting anything. Database connection, XML parser, object returning unique Ids etc. are examples of these kinds of objects. These kind of components provided by the ZCA are called utility components. Utilities are just objects that provide an interface and that are looked up by an interface and a name. This approach creates a global registry by which instances can be registered and accessed by different parts of your application, with no need to pass the instances around as parameters.

4.1.6 Subscriber

Unlike regular adapters, subscription adapters (subscriber) are used when we want all of the adapters that adapt an object to a particular interface. Subscription adapter is also known as subscriber.

142 Chapter 4. Concepts and Technologies BlueBream Documentation, Release 1.0a4

4.1.7 Handler

Handlers are subscription adapter factories that don’t produce anything. They do all of their work when called. Han- dlers are typically used to handle events. Handlers are also known as event subscribers or event subscription adapters. Event subscribers are different from other subscription adapters in that the caller of event subscribers doesn’t expect to interact with them in any direct way. For example, an event publisher doesn’t expect to get any return value. Because subscribers don’t need to provide an API to their callers, it is more natural to deﬁne them with functions, rather than classes.

4.1.8 Component Registry

Registries keep the list of which components are available, which interface they provide, which interface(s) they possibly adapt, along with an optional registration name. The zope.component package implements a global component registry.

4.1.9 Object Publishing

BlueBream puts your objects on the web. This is called object publishing. One of BlueBream’s unique characteristics is the way it allows you to walk up to your objects and call methods on them with simple URLs. In addition to HTTP, BlueBream makes your objects available to other network protocols including FTP, WebDAV and XML-RPC.

4.1.10 View

Views provide a connection between an external actor and an object. A View is typically a display component. Views are typically reponsible for creating HTML. Views can directly return HTML, but will often supply presentational logic and processed data to a Zope Page Template, which then contains the HTML. Web developers will normally deal with a specialized View called a BrowserView. This is just a View that is made for a web browser, as BlueBream can also provide Views for other protocols, such as FTP or WebDAV. In a BrowserView, the external actor is a web browser request, and the object that the view connects is looked up using traversal and is called the context. Because the Web is the predominant focus of most Zope developers, often the term View is assumed to be a BrowserView. The constructor for a BrowserView looks like this: class BrowserView(Location): implements(IBrowserView)

def __init__(self, context, request): self.context= context self.request= request

Context is the object that the View is acting upon. Often context will be a Content or Model object, but it may also be a Container or Site object or any object that Zope can publish. Request is an HTTP Request. If the View is a BrowserView, the Request will have a form attribute where all form data is already marshalled for the programmer. Consider the URL http://localhost:8080/your-id/a-todo-list/get-cat-food. In BlueBream, your-id would be a Con- tainer component that also provided a IHomeFolder interface, a-todo-list would be a To-Do Container component that also provided a IToDoList interaface, and get-cat-food would be a ToDo-Item Content or Model

4.1. Concepts 143 BlueBream Documentation, Release 1.0a4 component that also provided a IToDoItem interface. If you entered the URL http://localhost:8080/your-id/a-todo- list/get-cat-food into your web browser, then context would be an object that provided the IToDoItem interface, while request would be an object that represented the web browser request for that web page. However, if the URL was just http://localhost:8080/your-id/ then context would be an object that represented your home folder. You can look-up a View programmatically with a query: view= component.queryMultiAdapter((object, request), name=’index’)

For more reading on Views, there is a section about them in the Plone Core Developer Reference that provides information on how BlueBream Views are being used in Plone: http://plone.org/documentation/manual/plone-developer- reference/patterns/views

4.1.11 Content Object

Content obejcts are objects with a user visisble view.

4.1.12 Container

Containers are content objects which hold content objects.

4.1.13 Schema

Schemas are just an extension to interfaces and therefore depend on the zope.interface package. Fields in schemas are equivalent to methods in interfaces. Both are complementary to each other, since they describe different aspects of an object. The methods of an interface describe the functionality of a component, while the schema’s ﬁelds represent the state. Schemas provide: 1. Full speciﬁcation of properties on an API level 2. Data input validation and conversion 3. Automated GUI form generation (mainly for the Web browser)

4.1.14 Widget

The views of schema ﬁelds are called widgets. Widgets responsible for data display and conversion in their speciﬁc presentation type. Currently widgets exist mainly for HTML (the Web browser). Widgets are separated into two groups, display and input widgets. Display widgets are often very simply and only show a text representation of the Python object. The input widgets, however, are more complex and display a greater variety of choices.

4.1.15 Layer

• Deﬁne the “feel” of a site • Contain presentation logic • Common artifacts: pages, content providers, viewlet managers, and viewlets • Developed by BlueBream application developers

144 Chapter 4. Concepts and Technologies BlueBream Documentation, Release 1.0a4

4.1.16 Skin

• Define the “look” of a site • Common artifacts: templates and resources (CSS, Javascript, etc.) • Use layers to retrieve the data for templates • Developed by HTML and Graphic Designer/Scripter Technically, skins are interfaces inherited from a special interface called IDefaultBrowserLayer. The IDefaultBrowserLayer is defined in zope.publisher.interfaces.browser module. You can also inherit from an already existing skin. It is also important to register the skin interface type as IBrowserSkinType. Skins are directly provided by a request. Note: Layers versus skins • Both are implemented as interfaces • BlueBream does not differentiate between the two • In fact, the distinction of layers defining the “feel” and skins the “look” is a convention. You may not want to follow the convention, if it is too abstract for you, but if you are developing application with multiple look and feel, I strongly suggest using this convention, since it cleanly separates concerns. • Both support inheritance/acquisition

4.1.17 Annotation

Every object that comes with BlueBream and can have some sort of annotation, uses attribute annotations. Attribute annotations store the annotation data directly in the objects. This implementation works ﬁne as long as the object is persistent and is stored in the ZODB. But what if you have SQL-based objects, such as in relational-to-object mapping solutions? Storing annotations on the attribute of the object would certainly not work. In these scenarios it becomes necessary to implement a custom annotations implementation. First, there exists an interface named IAnnotatable. By providing this interface, an object declares that it is possible to store annotations for itself. However, IAnnotable is too general, since it does not specify how the annotation can be stored and should therefore never be provided directly. One should never assume that one method works for all possible objects. BlueBream comes by default with an IAttributeAnnotatable interface that allows you to store the annotations in the attribute __annotations__ on the object itself. This works well for any object whose instances are stored in the ZODB. As second part to the equation we have the IAnnotations interface, which provides a simple mapping API (i.e. dictionary-like) that allows you to look up annotation data using a unique key. This interface is commonly implemented as an adapter requiring IAnnotatable and providing IAnnotations. Thus we need to provide an implementation for IAnnotations to have our own annotations storage mechanism. For IAttributeAnnotable we have an AttributeAnnotations adapter. Note that by deﬁnition IAnnotations extends IAnnotable, since an IAnnotation can always adapt to itself. Another important aspect about annotations is the key (unique id) that is being used in the mapping. Since annotations may contain a large amount of data, it is important to choose keys in a way that they will always be unique. The simplest way to ensure this is to include the package name in the key. So for dublin core meta data, for example, instead of using ZopeDublinCore as the key one should use zope.app.dublincore.ZopeDublinCore. Some people also use a URI-based namespace notation: http://namespace.zope.org/dublincore/ZopeDublinCore/1.0.

4.1. Concepts 145 BlueBream Documentation, Release 1.0a4

4.1.18 Content Provider

Content Provider is a term from the Java world that refers to components that can provide HTML content. It means nothing more! How the content is found and returned is totally up to the implementation. The BlueBream touch to the concept is that content providers are multi-adapters that are looked up by the context, request (and thus the layer/skin), and view they are displayed in. The second important concept of content providers are their two-phase rendering design. In the ﬁrst phase the state of the content provider is prepared and, if applicable, any data, the provider is responsible for, is updated.

4.1.19 Viewlet

Viewlets provide a generic framework for building pluggable user interfaces.

4.2 Technologies

4.2.1 ZODB

The Zope Object Database provides an object-oriented database for Python that provides a high-degree of transparency. Applications can take advantage of object database features with few, if any, changes to application logic. ZODB includes features such as a pluggable storage interface, rich transaction support, and undo. Python programs are written with the object-oriented paradigm. You use objects that reference each other freely and can be of any form and shape: no object has to adhere to a specific schema and can hold arbitrary information. Storing those objects in relational databases requires you to give up on the freedom of reference and schema. The constraints of the relational model reduces your ability to write object-oriented code. The ZODB is a native object database, that stores your objects while allowing you to work with any paradigms that can be expressed in Python. Thereby your code becomes simpler, more robust and easier to understand. Also, there is no gap between the database and your program: no glue code to write, no mappings to configure. Have a look at the tutorial to see, how easy it is. Some of the features that ZODB brings to you: • Transparent persistence for Python objects • Full ACID-compatible transaction support (including savepoints) • History/undo ability • Efficient support for binary large objects (BLOBs) • Pluggable storages • Scalable architecture

4.2.2 ZCML

BlueBream separates all the policy from the actual code and moves it out to separate configuration files. The Zope Configuration Markup Language (ZCML), the XML-based configuration language that is used for this, is tailored to do component registration and security declarations, for the most part. By enabling or disabling certain components in ZCML, you can configure certain policies of the overall application. If you don’t enable it explicitly, it will not be found.

146 Chapter 4. Concepts and Technologies BlueBream Documentation, Release 1.0a4

4.2.3 WSGI

WSGI is the Web Server Gateway Interface. It is a speciﬁcation for web servers and application servers to communicate with web applications (though it can also be used for more than that). It is a Python standard, described in detail in PEP 333.

4.2.4 PasteScript

PasteScript is an external package created by Ian Bicking. PasteScript is a framework for defining commands. It comes with a few commands out of the box, like paster serve and paster create. The paster serve command loads and serves a WSGI application defined in a Paste Deploy config file. The paster create command creates directory layout for packages from a template.

4.2.5 PasteDeploy

PasteDeploy is an external package created by Ian Bicking. PasteDeploy is a system for loading and configuring WSGI applications and servers. PasteDeploy create a WSGI app as specified in the configuration file. The INI format of configuration file is specified by PasteDeploy. From the PasteDeploy site: Paste Deployment is a system for finding and configuring WSGI applications and servers. For WSGI application consumers it provides a single, simple function (loadapp) for loading a WSGI application from a configuration file or a Python Egg. For WSGI application providers it only asks for a single, simple entry point to your application, so that application users don’t need to be exposed to the implementation details of your application.

4.2. Technologies 147 BlueBream Documentation, Release 1.0a4

148 Chapter 4. Concepts and Technologies CHAPTER FIVE

TUTORIAL — PART 1

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

5.1 Introduction

In the Getting Started chapter you learned how to install BlueBream and create a new project using the bluebream project template. In this tutorial, you can learn creating a simple ticket collector application. This will help you to get more familiar with the concepts of BlueBream. Here is the user stories for the ticket collector application: 1. Any number of tickets can be added to one collector. 2. Each ticket will be added with a description and one initial comment. 3. Additional comments can be added to tickets. This is the ﬁrst part of the tutorial. After completing this chapter, you should be able to: • Understand the project directory structure • Use Buildout and edit Buildout conﬁguration • Create content objects and interfaces • Use form generation tool (zope.formlib) Note: The examples in this documentation can be downloaded from here: http://download.zope.org/bluebream/examples/ticketcollector-1.0.0.tar.bz2

5.2 Starting a new project

5.2.1 Using the bluebream project template

In this section we will create the directory layout for our ticket collector application. I will assume that you have already installed bluebream using the easy_install bluebream command as mentioned in the Getting Started chapter. We are going to use the project name ticketcollector and namespace package name tc. Let’s create the project directory layout for ticketcollector:

149 BlueBream Documentation, Release 1.0a4

$ paster create -t bluebream Selected and implied templates: bluebream#bluebream A BlueBream project

Enter project name: ticketcollector Variables: egg: ticketcollector package: ticketcollector project: ticketcollector Enter namespace_package (Namespace package name) [’ticketcollector’]: tc Enter main_package (Main package name (under the namespace)) [’main’]: Enter interpreter (Name of custom Python interpreter) [’breampy’]: Enter version (Version (like 0.1)) [’0.1’]: Enter description (One-line description of the package) [’’]: Ticket Collector Enter long_description (Multi-line description (in reST)) [’’]: An issue tracking application Enter keywords (Space-separated keywords/tags) [’’]: Enter author (Author name) [’’]: Baiju M Enter author_email (Author email) [’’]: [email protected] Enter url (URL of homepage) [’’]: Enter license_name (License name) [’’]: ZPL Enter zip_safe (True/False: if the package can be distributed as a .zip file) [False]: Creating template bluebream Creating directory ./ticketcollector Copying bootstrap.py to ./ticketcollector/bootstrap.py Copying buildout.cfg_tmpl to ./ticketcollector/buildout.cfg Copying debug.ini_tmpl to ./ticketcollector/debug.ini Copying deploy.ini_tmpl to ./ticketcollector/deploy.ini Recursing into etc Creating ./ticketcollector/etc/ Copying site.zcml_tmpl to ./ticketcollector/etc/site.zcml Copying setup.py_tmpl to ./ticketcollector/setup.py Recursing into src Creating ./ticketcollector/src/ Recursing into +namespace_package+ Creating ./ticketcollector/src/tc/ Recursing into +main_package+ Creating ./ticketcollector/src/tc/main/ Copying README.txt_tmpl to ./ticketcollector/src/tc/main/README.txt Copying __init__.py to ./ticketcollector/src/tc/main/__init__.py Copying app.py to ./ticketcollector/src/tc/main/app.py Copying application.zcml_tmpl to ./ticketcollector/src/tc/main/application.zcml Copying configure.zcml_tmpl to ./ticketcollector/src/tc/main/configure.zcml Copying debug.py to ./ticketcollector/src/tc/main/debug.py Copying ftesting.zcml_tmpl to ./ticketcollector/src/tc/main/ftesting.zcml Copying index.pt_tmpl to ./ticketcollector/src/tc/main/index.pt Copying interfaces.py to ./ticketcollector/src/tc/main/interfaces.py Copying securitypolicy.zcml_tmpl to ./ticketcollector/src/tc/main/securitypolicy.zcml Copying startup.py to ./ticketcollector/src/tc/main/startup.py Recursing into static Creating ./ticketcollector/src/tc/main/static/ Copying logo.png to ./ticketcollector/src/tc/main/static/logo.png Copying style.css to ./ticketcollector/src/tc/main/static/style.css Copying tests.py_tmpl to ./ticketcollector/src/tc/main/tests.py Copying views.py to ./ticketcollector/src/tc/main/views.py Copying __init__.py to ./ticketcollector/src/tc/__init__.py Recursing into +package+.egg-info Creating ./ticketcollector/src/ticketcollector.egg-info/

150 Chapter 5. Tutorial — Part 1 BlueBream Documentation, Release 1.0a4

Copying PKG-INFO to ./ticketcollector/src/ticketcollector.egg-info/PKG-INFO Recursing into templates Creating ./ticketcollector/templates/ Copying zope_conf.in to ./ticketcollector/templates/zope_conf.in Recursing into var Creating ./ticketcollector/var/ Recursing into blob Creating ./ticketcollector/var/blob/ Copying README.txt to ./ticketcollector/var/blob/README.txt Recursing into filestorage Creating ./ticketcollector/var/filestorage/ Copying README.txt to ./ticketcollector/var/filestorage/README.txt Recursing into log Creating ./ticketcollector/var/log/ Copying README.txt to ./ticketcollector/var/log/README.txt Copying versions.cfg to ./ticketcollector/versions.cfg Running /usr/bin/python2.6 setup.py egg_info

As you can see above we have provided most of the project details. The values you provided here may be changed later, however changing the package name or the namespace package name may not be as easy as changing the description because the name and namespace package might be referred to from many places.

5.2.2 Organize the new package

If you change directory to ticketcollector you can see a few directories and ﬁles: jack@computer:/projects/ticketcollector$ ls -CF bootstrap.py debug.ini etc/ src/ var/ buildout.cfg deploy.ini setup.py templates/ versions.cfg

Once the project directory layout is ready you can add it to your version control system. You should not add src/ticketcollector.egg-info directory as it is generated automatically by setuptools. Here is an example using bzr: jack@computer:/projects/ticketcollector$ rm -fr src/ticketcollector.egg-info/ jack@computer:/projects/ticketcollector$ bzr init Created a standalone tree (format: 2a) jack@computer:/projects/ticketcollector$ bzr add * adding bootstrap.py adding buildout.cfg adding debug.ini ... jack@computer:/projects/ticketcollector$ bzr ci -m "Initial import" Committing to: /projects/ticketcollector/ added bootstrap.py added buildout.cfg ... Committed revision 1.

Adding the project to a version control system is an optional but recommended step. You now have a valid source code distribution of your project that after building will produce a running application. The project is now completely independent of the bluebream distribution, it’s only purpose is to help us get to this point. The project now contains all mechanisms required to install the dependencies from the Internet and setting up the application.

5.2. Starting a new project 151 BlueBream Documentation, Release 1.0a4

5.2.3 Bootstrapping the project

The next step is to install Buildout. The purpose of Buildout is to automate the building of Python applications from their bare source code form. The only basic requirement for Buildout is a Python installation. BlueBream provides a bootstrapping script to install Buildout and to set up the project directory for running it. This bootstrap script is named bootstrap.py and will do these things: • Download and install setuptools package from PyPI • Download and install zc.buildout package from PyPI • Create a directory structure eg:- bin/ eggs/ parts/ develop-eggs/ • Create a script inside the bin directory named buildout When you run bootstrap.py you can see that it creates a few directories and the bin/buildout script as mentioned earlier: jack@computer:/projects/ticketcollector$ python2.6 bootstrap.py Creating directory ’/projects/ticketcollector/bin’. Creating directory ’/projects/ticketcollector/parts’. Creating directory ’/projects/ticketcollector/develop-eggs’. Creating directory ’/projects/ticketcollector/eggs’. Generated script ’/projects/ticketcollector/bin/buildout’.

• The bin directory is where Buildout install all the executable scripts. • The eggs directory is where Buildout install Python eggs • The parts is where Buildout save all output generated by buildout. Buildout expects you to not change anything inside parts directory as it is auto generated by Buildout. • The develop-eggs directory is where Buildout save links to all locally developped Python eggs.

5.2.4 Buildout conﬁguration

After bootstrapping the project you can build your application. All the steps you did so far is only required once per project, but running buildout is required whenever you make changes to the buildout conﬁguration. You are now ready to run bin/buildout to build the application, but before doing this let’s have a look at the content of buildout.cfg:

[config] site_zcml = ${buildout:directory}/etc/site.zcml blob = ${buildout:directory}/var/blob filestorage = ${buildout:directory}/var/filestorage log = ${buildout:directory}/var/log

[buildout] develop = . extends = versions.cfg parts = app zope_conf test

[app] recipe = zc.recipe.egg eggs = ticketcollector z3c.evalexception>=2.0 Paste

152 Chapter 5. Tutorial — Part 1 BlueBream Documentation, Release 1.0a4

PasteScript PasteDeploy interpreter = breampy

[zope_conf] recipe = collective.recipe.template input = templates/zope_conf.in output = etc/zope.conf

[test] recipe = zc.recipe.testrunner eggs = ticketcollector

The buildout configuration file is divided into multiple sections called parts. The main part is called [buildout], and that is given as the second part in the above configuration file. We have added a part named [config] for convenience which includes some common options referred to from other places. Each part will be handled by the Buildout plugin mechanism called recipes except for [buildout] and [config]. [buildout] is handled specially by Buildout as it contains general settings and [config] only contains options used for other parts. We will look at each part here. Let’s start with [config]:

[config] site_zcml = ${buildout:directory}/etc/site.zcml blob = ${buildout:directory}/var/blob filestorage = ${buildout:directory}/var/filestorage log = ${buildout:directory}/var/log

The [config] is a kind of abstract part which exists for convenience to hold options used by other parts and is an idiom in many projects using Buildout. In this configuration the options provided are _not_ used by other parts directly, but all are used in one template given in the [zope_conf] part. Here is details about each options: • site_zcml – this is the location where final site.zcml file will be residing. The value of ${buildout:directory} will be the absolute path to the directory where you are running buildout. In the above example, the value will be: /projects/ticketcollector. So, the value of site_zcml will be: /projects/ticketcollector/etc/site.zcml • blob – location where ZODB blob files are stored. • filestorage – ZODB data files are stored here. • log – All log files goes here. Let’s look at the main [buildout] part:

[buildout] develop = . extends = versions.cfg parts = app zope_conf test

The first option (develop) tells buildout that, the current directory is a Python distribution source, i.e., it contains a setup.py file. Buildout will inspect the setup.py and create a develop egg link inside the develop-eggs directory. The link file should contain path to the location where the Python package is residing. So buildout will make sure that the packages is always importable. The value of the develop option could be a relative path as given above or absolute path to some directory. You can also add multiple lines to develop option with different paths. The extends option tells buildout to include the full content of versions.cfg file as part the configuration. The versions.cfg is another Buildout configuration file of the same format as buildout.cfg and contains the release

5.2. Starting a new project 153 BlueBream Documentation, Release 1.0a4

numbers of different dependencies. You can add multiple lines to extends option to include multiple conﬁguration ﬁles. The parts option list all the parts to be built by Buildout. Buildout expects a recipe for each parts listed here. Which means that you cannot include config part here as it doesn’t have any recipe associated with it. Now let’s look at the app part:

[app] recipe = zc.recipe.egg eggs = ticketcollector z3c.evalexception>=2.0 Paste PasteScript PasteDeploy interpreter = breampy

This part takes care of all the eggs required for the application to function. The zc.recipe.egg is an advanced Buildout recipe with many features to deal with egg. Majority of the dependencies will come as part of the main application egg. The option eggs list all the eggs. The ﬁrst egg, ticketcollector is the main locally developing egg. The last option, interpreter specify the name of a custom interpreter create by this part. The custom interpreter contains the paths to all eggs listed here. The [zope_conf] part creates the zope.conf from a template:

[zope_conf] recipe = collective.recipe.template input = templates/zope_conf.in output = etc/zope.conf

This part is fairly self explanatory, it creates a zope.conf file from the template file templates/zope_conf.in. This collective.recipe.template recipe is very popular among Buildout users. Here is the template file (templates/zope_conf.in):

# Identify the component configuration used to define the site: site-definition ${config:site_zcml}

# Wrap standard FileStorage with BlobStorage proxy to get ZODB blobs # support. # This won’t be needed with ZODB 3.9, as its FileStorage supports # blobs by itself. If you use ZODB 3.9, remove the proxy and specify # the blob-dir parameter right in in filestorage, just after path. blob-dir ${config:blob} path ${config:filestorage}/Data.fs

# Uncomment this if you want to connect to a ZEO server instead: # # server localhost:8100 # storage 1 # # ZEO client cache, in bytes # cache-size 20MB # # Uncomment to have a persistent disk cache # #client zeo1

154 Chapter 5. Tutorial — Part 1 BlueBream Documentation, Release 1.0a4

# This sets up logging to both a file and to standard output (STDOUT). # The "path" setting can be a relative or absolute filesystem path or # the tokens STDOUT or STDERR.

path ${config:log}/z3.log formatter zope.exceptions.log.Formatter

path STDOUT formatter zope.exceptions.log.Formatter

# Comment this line to disable developer mode. This should be done in # production devmode on

The last part creates the test runner:

[test] recipe= zc.recipe.testrunner eggs= ticketcollector

The testrunner recipe creates a test runner using the zope.testing module. The only mandatory option is eggs where you can specify the eggs.

5.2.5 Building the project

Now you can run the bin/buildout command. It will take some time to download all packages from PyPI. When you run buildout, it will show something like this:

jack@computer:/projects/ticketcollector$ ./bin/buildout Develop: ’/projects/ticketcollector/.’ Installing app. Generated script ’/projects/ticketcollector/bin/paster’. Generated interpreter ’/projects/ticketcollector/bin/breampy’. Installing zope_conf. Installing test. Generated script ’/projects/ticketcollector/bin/test’.

In the above example, all eggs are already available in the eggs folder, otherwise it will download and install eggs. The buildout also created three more scripts inside bin directory. • The paster command can be used to run web server. • The breampy command provides a custom Python interpreter with all eggs included in path. • The test command can be used to run the test runner. Now we have a project source where we can continue developing this application.

5.2. Starting a new project 155 BlueBream Documentation, Release 1.0a4

5.3 The site deﬁnition

BlueBream use ZCML for application specific configuration. ZCML is an XML-based declarative configuration language. As you have seen already in zope.conf the main configuration is located at etc/site.zcml. Here is the default listing:

The main configuration, site.zcml include other configuration files specific to packages. The ZCML has some directives like include‘, page, defaultView etc. available through various XML-namespaces. In the site.zcml the default XML-namespace is http://namespaces.zope.org/zope. If you look at the top of site.zcml, you can see the XML-namespace refered to like this:

156 Chapter 5. Tutorial — Part 1 BlueBream Documentation, Release 1.0a4

The include directive is available in http://namespaces.zope.org/zope namespace. If you look at other configuration files, you can see some other namespaces like http://namespaces.zope.org/browser used which has some directives like page. At the end of site.zcml, two application specific configuration files are included like this:

The securitypolicy.zcml is where you can define the security policies. The application.zcml is a generic configuration file where you can include other application specific configuration files. Also you can define common configuration for your entire application. By default, it will look like this:

As you can see in the application.zcml, it includes tc.main. By default, if you include a package without mentioning the conﬁguration ﬁle, it will include configure.zcml.

5.4 The package meta-data

BlueBream use Setuptools to distribute the application package. However, you could easily replace it with Distribute. Your ticketcollector package’s setup.py will look like this:

from setuptools import setup, find_packages

setup(name=’ticketcollector’, version=’0.1’, description=’Ticket Collector’, long_description="""\ A ticket collector application""", # Get strings from http://www.python.org/pypi?%3Aaction=list_classifiers classifiers=[], keywords=’’, author=’Baiju M’, author_email=’[email protected]’, url=’’,

5.4. The package meta-data 157 BlueBream Documentation, Release 1.0a4

license=’ZPL’, package_dir={’’:’src’}, packages=find_packages(’src’), namespace_packages=[’tc’,], include_package_data=True, zip_safe=False, install_requires=[’setuptools’, ’zope.app.twisted’, ’zope.securitypolicy’, ’zope.component’, ’zope.annotation’, ’zope.app.dependable’, ’zope.app.appsetup’, ’zope.app.content’, ’zope.publisher’, ’zope.app.broken’, ’zope.app.component’, ’zope.app.generations’, ’zope.app.error’, ’zope.app.interface’, ’zope.app.publisher’, ’zope.app.security’, ’zope.app.form’, ’zope.app.i18n’, ’zope.app.locales’, ’zope.app.zopeappgenerations’, ’zope.app.principalannotation’, ’zope.app.basicskin’, ’zope.app.rotterdam’, ’zope.app.folder’, ’zope.app.wsgi’, ’zope.formlib’, ’zope.i18n’, ’zope.app.pagetemplate’, ’zope.app.schema’, ’zope.app.container’, ’zope.app.debug’, ’z3c.testsetup’, ’zope.app.testing’, ’zope.testbrowser’, ’zope.login’, ’zope.app.zcmlfiles’, ], entry_points= """ [paste.app_factory] main = tc.main.startup:application_factory

[paste.global_paster_command] shell = tc.main.debug:Shell """, )

Most of the details in the setup.py is what you’re given when creating the project from template. In the install_requires keyword argument, you can list all dependencies for the package. There are two entry points, the ﬁrst one is used by PasteDeploy to ﬁnd the WSGI application factory. The second entry point register a sub- command for paster script named shell.

158 Chapter 5. Tutorial — Part 1 BlueBream Documentation, Release 1.0a4

5.5 Running Tests

BlueBream use zope.testing as the main framework for automated testing. Along with zope.testing, you can use Python’s unittest and doctest modules. Also there is a functional testing module called zope.testbrowser . To setup the test cases, layers etc. BlueBream use the z3c.testsetup package. BlueBream use the Buildout recipe called zc.recipe.testrunner to generate test runner script. If you look at the buildout conﬁguration, you can see the test runner part:

[test] recipe= zc.recipe.testrunner eggs= ticketcollector

The testrunner recipe creates a test runner using zope.testing module. The only mandatory option is eggs where you can specify the eggs. To run all test cases, use the bin/test command:

jack@computer:/projects/ticketcollector$ bin/test

This command will ﬁnd all the test cases and run it.

5.6 Creating the application object

5.6.1 Container objects

In this section we will explore one of the main concepts in BlueBream called container object. As mentioned earlier BlueBream use an object database called ZODB to store your Python objects. You can think of an object database as a container which contains objects, the inner object may be another container which contains other objects. The object hierarchy may look like this:

+------+ | | | +------+ +--+ | | | | +--+ | | | +--+ | | | | +--+ | | | +------+ +--+ | | +--+ | +------+

BlueBream will take care of the persistence of the objects. In order to make a custom object persistent the object class will have to inherit from persistent.Persistent. Some classes in BlueBream that inherits persistent.Persistent: • zope.container.btree.BTreeContainer • zope.container.folder.Folder • zope.site.folder.Folder When you inherit from any of these classes the instances of that class will be persistent. The second thing you need to do to make it persistent is to add the object to an existing container object. You can experiment with this from the debug shell provided by BlueBream. But before you try that out create a container class somewhere in your code

5.5. Running Tests 159 BlueBream Documentation, Release 1.0a4

which can be imported later. You can add this deﬁnition to the src/tc/main/__init__.py ﬁle (Delete it after the experiment):

from zope.container.btree import BTreeContainer

class MyContainer(BTreeContainer): pass

Then open the debug shell as given below:

$ ./bin/paster shell debug.ini ... 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. >>>

The name root refers to the top-level container in the database. You can import your own container class, create an instance and add it to the root folder:

>>> from tc.main import MyContainer >>> root[’c1’]= MyContainer()

ZODB is a transactional database so you will have to commit your changes in order for them to be performed. To commit your changes use the function transaction.commit as described below:

>>> import transaction >>> transaction.commit()

Now you can exit the debug prompt and open it again and see that you can access the persistent object again:

Persisting random objects like this is not a particulary good idea. The next section will explain how to create a formal schema for your objects. Now you can delete the object and remove the MyContainer class deﬁnition from src/tc/main/__init__.py. You can delete the object like this:

>>> del(root[’c1’]) >>> import transaction >>> transaction.commit()

5.6.2 Declaring an Interface

Note: If you have never worked with zope.interface before, we recommend that you read through the Interface chapter in the manual before proceding. As the ﬁrst step for creating the main application container object which is going to hold all other objects, you need to create an interface. You can name the main container interface as ICollector, the easiest way to create a

160 Chapter 5. Tutorial — Part 1 BlueBream Documentation, Release 1.0a4

container is to inherit from zope.container.interfaces.IContainer interface. You can modify the ﬁle named src/tc/main/interfaces.py to add new interfaces like this:

from zope.container.interfaces import IContainer from zope.schema import TextLine from zope.schema import Text

class ICollector(IContainer): """The main application container"""

name= TextLine( title=u"Name", description=u"Name of application container", default=u"", required=True)

description= Text( title=u"Description", description=u"Description of application container", default=u"", required=False)

The interface defined here is your schema for the object. There are two fields defined in the schema. The first one is name and the second one is description. The schema is also can be used to auto-generate web forms.

5.6.3 Implementing Interface

Schema is kind of blueprint for your objects, schema deﬁne the contracts for the objects. Once you have schema ready, you can create some concrete classes which implement the schema. Next, you need to implement this interface. To implement IContainer, it is recommended to inherit from zope.container.btree.BTreeContainer. You can create the implementation in src/tc/main/ticketcollector.py:

from zope.interface import implements from zope.container.btree import BTreeContainer

from tc.main.interfaces import ICollector

class Collector(BTreeContainer): """A simple implementation of a collector using B-Tree Container."""

implements(ICollector)

name= u"" description= u""

To declare a class is implementing a particular interface, you can use implements function. The class also provides defaults values for attributes.

5.6.4 Registering components

Once the interfaces and its implementations are ready. You can do the conﬁguration in ZCML. Open the src/tc/main/configure.zcml ﬁle to edit, then mark the ICollector as a content component:

5.6. Creating the application object 161 BlueBream Documentation, Release 1.0a4

The zope.app.content.interfaces.IContentType represents a content type. If an interface provides IContentType interface type, then all objects providing the interface are considered content objects. To set annotations for collector objects, we need to mark it as implementing zope.annotation.interfaces.IAttributeAnnotatable marker interface. Also this conﬁgura- tion declare that Collector class implements zope.container.interfaces.IContentContainer. These two classes are marker interfaces. An interface used to declare that a particular object belongs to a special type is called marker interface. Marker interface won’t be having any attribute or method.

The class directive is a complex directive. There are subdirective like implements and require below the class directive. The above class directive also declared permission setting for Collector.

5.6.5 A view for adding collector

Now the content component is ready to use. You need a web page from where we can add the ticket collector. You can use zope.formlib package to create a form. You can add the view class deﬁnition inside src/tc/main/views.py like this:

from zope.container.interfaces import INameChooser from zope.formlib import form

from tc.main.interfaces import ICollector

from tc.main.ticketcollector import Collector class AddTicketCollector(form.AddForm):

form_fields= form.Fields(ICollector)

def createAndAdd(self, data): name= data[’name’] description= data.get(’description’) namechooser= INameChooser(self.context)

162 Chapter 5. Tutorial — Part 1 BlueBream Documentation, Release 1.0a4

collector= Collector() collector.name= name collector.description= description name= namechooser.chooseName(name, collector) self.context[name]= collector self.request.response.redirect(".")

The createAndAdd function will be called when used submit Add button from web form. The last last thing you need to do is registering this view in ZCML. As you have already seen in the previous chapter, browser:page directive is used for registering pages. You can give the name as add_ticket_collector and register it for zope.site.interfaces.IRootFolder. Add these lines to src/tc/main/configure.zcml:

Now you can access the URL: http://localhost:8080/@@add_ticket_collector . It should display a form where you can enter details like name and description. You can enter the name as mycollector, after entering data, submit the form. You can see the ﬁle size of var/filestorage/Data.fs is increasing as objects are getting added. The Data.fs is where the data is physically stored. You can also conﬁrm the object is actually saved into database from Python shell. If you go to Python shell and try to access the root object, you can see that it has the object you added: jack@computer:/projects/ticketcollector$ ./bin/paster shell debug.ini ... 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. >>> list(root.keys()) [u’mycollector’]

You can use this debug shell to introspect Python objects stored in ZODB. You can add, update or delete objects and attributes from the debug shell.

5.6.6 A default view for collector

If you try to access the collector from the URL: http://localhost:8080/mycollector , you will get NotFound error like this:

URL: http://localhost:8080/mycollector ... NotFound: Object: , name: u’@@index’

This error is raised, because there is no view named index registered for ICollector. This section will show how to create a default view for ICollector interface. As you have already seen in the Getting Started chapter, you can create a simple view and register it from ZCML. In the src/tc/main/views.py add a new view like this:

5.6. Creating the application object 163 BlueBream Documentation, Release 1.0a4

class TicketCollectorMainView(form.DisplayForm):

def __call__(self): return "Hello ticket collector!"

Then, in the src/tc/main/configure.zcml:

Now you can visit: http://localhost:8080/mycollector It should display a message like this:

Hello ticket collector!

In the next section, you will see more details about the main page for collector. Also we are going to learn about Zope Page Template.

5.7 Creating the main page

5.7.1 Browser Page

The browser page can be created using a page template. The form.DisplayForm supports a template and form_fields attributes. You can also remove the __call__ method from TicketCollectorMainView. from zope.browserpage import ViewPageTemplateFile class TicketCollectorMainView(form.DisplayForm):

form_fields= form.Fields(ICollector)

template= ViewPageTemplateFile("collectormain.pt")

You can create src/tc/main/collectormain.pt with the following content:

Welcome to ticket collector!

Now you can visit: http://localhost:8080/mycollector . It should display “Welcome to ticket collector!” message.

164 Chapter 5. Tutorial — Part 1 BlueBream Documentation, Release 1.0a4

5.8 Conclusion

This part of tutorial covered the basics of creating a web application using BlueBream. This chapter narrated in detail about the usage of bluebream paster project template to create a new project. This part of tutorial also walked though the process of building application using Buildout. Then, narrated creating an application container. Finally, a default view for application container is also created. The Tutorial — Part 2 will expand the application with additional functionalities.

5.8. Conclusion 165 BlueBream Documentation, Release 1.0a4

166 Chapter 5. Tutorial — Part 1 CHAPTER SIX

TUTORIAL — PART 2

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

6.1 Introduction

This is the second part of tutorial. In the first part, you learned about project directory structure, Buildout configuration, content components and using the form library. Content components are objects with a user visisble view. A view could be a browser view (HTML/JS/CSS) or JSON or XMLRPC or any other view. To exaplain the idea of content components, the ticket collector project started in the first part of tutorial will be expanded with additional functionalities. In fact, the collector object created in the last chapter is a content component. In this chapter, you will create new content objects like tickets and comments. Another thing you might be noticed that, every content component, including container components has well defined interfaces. This chapter explore content components in more detail. After completing this chapter, you should be able to: • Define schema for content components • Create container objects • Use ZCML to configure various components Before proceeding further, here is an overview of sections: • Adding tickets – This section shows creating a ticket collector objects. This section provide a detailed overview of creating content object and demonstrate with a simple example. • Listing tickets – This section shows displaying tickets from the main collector page. • Adding comments – This section explain about adding content object inside other container objects. Ticket objects will be transformed to a container object. Note: The examples in this documentation can be downloaded from here: http://download.zope.org/bluebream/examples/ticketcollector-1.0.0.tar.bz2

6.2 Adding tickets

6.2.1 Schema deﬁnition

In this section, you will learn about adding tickets to collector. In order to use ticket objects, ﬁrst you need to create an interface for tickets. Update the src/tc/main/interfaces.py with the ticket interface:

167 BlueBream Documentation, Release 1.0a4

from zope.interface import Interface

class ITicket(Interface): """Ticket - the ticket content component"""

number= TextLine( title=u"Number", description=u"Ticket number", default=u"", required=True)

summary= Text( title=u"Summary", description=u"Ticket summary", default=u"", required=True)

The TextLine and Text are already imported, if not, you can import it from these locations:

from zope.schema import TextLine from zope.schema import Text

It would be good if you set a precondition to restrict what types of objects you want to add inside a collector. Now you know that, you only expect tickets objects inside collector. So, you can add a precondition for restricting only ticket objects inside collector. To do this, you need to add a __setitem__ method to ICollector interface definition (The __setitem__ is part of IContainer API). Then below that, you can add precondition attribute, which is an instance of ItemTypePrecondition class. You can pass the interfaces as arguments to ItemTypePrecondition class. Below, only one class (ITicket) is passed. So, only ticket objects are allowed inside collector. You need to move the definition of ITicket above the IContainer as the ITicket being used there. Add the following method definition to ICollector class:

from zope.app.container.constraints import ItemTypePrecondition

def __setitem__(name, object): """Add an ICollector object."""

__setitem__.precondition= ItemTypePrecondition(ITicket)

The ItemTypePrecondition provides a way to restrict the type of object which can be added inside a container. You can also specify that ticket objects can be only added inside collector. To do this, you need to create another interface inheriting from zope.container.interfaces.IContained.

from zope.schema import Field from zope.container.interfaces import IContained from zope.app.container.constraints import ContainerTypesConstraint

class ITicketContained(IContained): """Interface that specifies the type of objects that can contain tickets. So a ticket can only contain in a collector."""

__parent__= Field( constraint= ContainerTypesConstraint(ICollector))

Here you added a constraint for __parent__ ﬁeld using ContainerTypesConstraint class.

168 Chapter 6. Tutorial — Part 2 BlueBream Documentation, Release 1.0a4

6.2.2 Implementation

Next, you can implement this interface inside src/tc/main/ticket.py: from zope.interface import implements from tc.main.interfaces import ITicket from tc.main.interfaces import ITicketContained from zope.container.contained import Contained class Ticket(Contained):

implements(ITicket, ITicketContained)

number= u"" summary= u""

6.2.3 Conﬁguration

Then, register the interface & class. Open the src/tc/main/configure.zcml and update it with these details:

Now you can add a link to @@add_ticket in src/tc/main/collectormain.pt. Now the template will look like this:

Welcome to ticket collector

Welcome to ticket collector!

Add Ticket

6.2. Adding tickets 169 BlueBream Documentation, Release 1.0a4

When you click on this link, it expects a view. You can create an AddForm inside src/tc/main/views.py: from tc.main.interfaces import ITicket from tc.main.ticket import Ticket class AddTicket(form.AddForm):

form_fields= form.Fields(ITicket)

def createAndAdd(self, data): number= data[’number’] summary= data[’summary’] ticket= Ticket() self.context[number]= ticket self.request.response.redirect(’.’)

You can register the view inside src/tc/main/configure.zcml:

You can add a ticket by visiting: http://localhost:8080/mycollector/@@add_ticket You can give the ticket number as ‘1’ and provide summary as ‘Test Summary’. You can check the object from debug shell: jack@computer:/projects/ticketcollector$ ./bin/paster shell debug.ini ... 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. >>> root[’mycollector’] >>> root[’mycollector’][’1’]

6.2.4 Default browser page for tickets

Now there is no default browser page for tickets. If you try to access the ticket from the URL: http://localhost:8080/mycollector/1 , you will get NotFound error like this:

URL: http://localhost:8080/mycollector/1 ... NotFound: Object: , name: u’@@index’

This error is raised, because there is no view named index registered for ITicket. This section will show how to create a default view for ITicket interface. As you have already seen in the Getting Started chapter, you can create a simple view and register it from ZCML. In the src/tc/main/views.py add a new view like this:

170 Chapter 6. Tutorial — Part 2 BlueBream Documentation, Release 1.0a4

class TicketMainView(form.DisplayForm):

form_fields= form.Fields(ITicket)

template= ViewPageTemplateFile("ticketmain.pt")

You can create the template ﬁle here: src/tc/main/ticketmain.pt with this content:

Welcome to ticket collector!

You are looking at ticket number: number

Summary

Summary goes here

Then, in the src/tc/main/configure.zcml:

Now you can visit: http://localhost:8080/mycollector/1/@@index It should display the ticket number and summary. If you open the HTML source from browser, it will look like this:

Welcome to ticket collector!

You are looking at ticket number: 1

Summary

Test Summary

6.3 Listing tickets

This section explain listing tickets in the main collector page, so that the user can navigate to ticket and see the details.

6.3. Listing tickets 171 BlueBream Documentation, Release 1.0a4

To list the tikets in the main collector page, you need to modify the src/tc/main/collectormain.pt:

Welcome to ticket collector!

Ticket Summary

You need to change the TicketCollectorMainView deﬁned in src/main/tc/main/views.py ﬁle: from zope.browserpage import ViewPageTemplateFile class TicketCollectorMainView(form.DisplayForm):

form_fields= form.Fields(ICollector)

template= ViewPageTemplateFile("collectormain.pt")

def getTickets(self): tickets=[] for ticket in self.context: tickets.append({’url’:ticket.number, ’summary’: ticket.summary}) return tickets

6.4 Adding Comments

Warning: This section is incomplete

In this section, you will create comment objects and add it to tickets. As the first step, you need to define the interface for the comments. You can add this interface definition inside interfaces.py: class IComment(Interface): """Comment for Ticket"""

body= Text( title=u"Additional Comment", description=u"Body of the Comment.", default=u"", required=True)

Next, you can implement the comment like this:

172 Chapter 6. Tutorial — Part 2 BlueBream Documentation, Release 1.0a4

from zope.interface import implements from tc.main.interfaces import IComment from tc.main.interfaces import ICommentContained from zope.location.contained import Contained class Comment(Contained):

implements(IComment, ICommentContained)

body= u""

Then, register the interface & class:

6.5 Conclusion

This chapter explored creating content components. You can learn more about BlueBream from the Manual.

6.5. Conclusion 173 BlueBream Documentation, Release 1.0a4

174 Chapter 6. Tutorial — Part 2 CHAPTER SEVEN

MANUAL

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

7.1 Browser Resource

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

7.1.1 File Resource

Certain presentation, like images and style sheets are not associated with any other component, so that one cannot create a view. To solve this problem, resources were developed, which are presentation components that do not require any context. This chapter will demonstrate how resources are created and registered with BlueBream. The first goal is to register a simple plain-text file called resource.txt as a browser resource. The first step is to create this file anywhere you wish on the filesystem, and adding the following content:

Hello, I am a BlueBream Resource Component!

Now just register the resource in a ZCML conﬁguration ﬁle using the browser resource directive:

Line 2: This is the name under which the resource will be known in Zope. Line 3: The file attribute specifies the path to the resource on the filessytem. The current working directory (‘.’) is always the directory the configuration file is located. So in the example above, the file resource.txt is located in the same folder as the configuration file is. Line 4: The optional layer attribute specifies the layer the resource is added to. By default, the default layer is selected. Once you hook up the configuration file to the main configuration path and restart BlueBream, you should be able to access the resource now via a Browser using http://localhost:8080/@@/resource.txt. The @@/ in the URL tells the traversal mechanism that the following object is a resource.

175 BlueBream Documentation, Release 1.0a4

7.1.2 Image Resource

If you have an image resource, you might want to use different conﬁguration. Create a simple image called img.png and register it as follows:

Line 3: As you can see, instead of the file attribute we use the image one. Internally this will create an Image object, which is able to detect the content type and returns it correctly. There is a third possible attribute named template. If specified, a Page Template that is executed when the resource is called. Note that only one of file, image, or template attributes can be specified inside a resource directive. Line 4: A final optional attribute is the “permission” one must have to view the resource. To demonstrate the security, I set the permission required for viewing the image to zope.ManageContent, so that you must log in as an administrator/manager to be able to view it. The default of the attribute is zope.Public so that everyone can see the resource.

7.1.3 Directory Resource

If you have many resource files to register, it can be very tedious to write a single directive for every resource. For this purpose the resourceDirectory is provided, with which you can simply declare an entire directory, including its content as resources. Thereby the filenames of the files are reused as the names for the resource available. Assuming you put your two previous resources in a directory called resource, then you can use the following: The image will then be publically available under the URL: http://localhost:8080/@@/resources/img.png The directory resource object uses a simple resource type recognition. It looks at the filename extensions to discover the type. For page templates, currently the extensions pt, zpt and html are registered and for an image gif, png and jpg‘. All other extensions are converted to file resources. Note that it is not necessary to have a list of all image types, since only Browser-displayable images must be recognized.

7.2 Browser Page

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

7.2.1 Introduction

In the last chapter we have seen how to use resources HTML. The resource HTML will be only available on site-level with the @@ preﬁx. Browser page (or more generically views) are representations for particular objects/components. If you have a template like this (helloworld.pt):

Hello, World !

Here is how to register a page for IFolder interface:

176 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

7.2.2 View components

While templates display data view components are preparing data. View components convert data to output formats also prepare related data (meta-data). Then, create TAL-friendly object structures (dicts and lists). View components know about: component for which the representation is created (context) and request object holding all output media information (request)

Implementation

Normally view components are added inside browser package inside your main package. The organization of the browser code is really up to you and the above examples are just the most basic rules of thumb. Here is simple view deﬁned:

from zope.publisher.browser import BrowserPage from zope.app.folder import interfaces class HelloWorld(BrowserPage):

def subFolderIds(self): for name, subobj in self.context.items(): if interfaces.IFolder.providedBy(subobj): yield name

Since methods and attributes of the view component are directly used by the template, they should return simple iterable objects (e.g. lists, tuples, generators) or mappings (e.g. dicts).

7.2.3 View components - integration

7.3 Unit Testing

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

7.3.1 Introduction

This chapter will discuss about unit testing and integration testing. Doctest-based testing is heavily used in Zope 3. And test driven development (TDD) is prefered in Zope 3. To explain the idea, consider a use case. A module is required with a function which returns “Good morning, name!”. The name will be given as an argument. Before writing the real code write the unit test for this. In fact you will be writing the real code and it’s test cases almost in parallel. So create a ﬁle named example1.py with the function deﬁnition:

7.3. Unit Testing 177 BlueBream Documentation, Release 1.0a4

def goodmorning(name): "This returns a good morning message"

See, you have not yet written the logic. But this is necessary to run tests successfully with failures!. Ok, now create a ﬁle named example1.txt with test cases, use reStructuredText format:

These are tests for example1 module.

First import the module:

>>> import example1

Now call the function goodmorning without any arguments:

>>> example1.goodmorning() Traceback (most recent call last): ... TypeError: goodmorning() takes exactly 1 argument (0 given)

Now call the function goodmorning with one argument:

>>> example1.goodmorning(’Jack’) ’Good morning, Jack!’

See the examples are written like executed from prompt. You can use your python prompt and copy paste from there. Now create another ﬁle test_example1.py with this content: import unittest import doctest def test_suite(): return unittest.TestSuite(( doctest.DocFileSuite(’example1.txt’), )) if __name__ ==’__main__’: unittest.main(defaultTest=’test_suite’)

This is just boilerplate code for running the test. Now run the test using python2.4 test_example1.py command. You will get output with following text:

File "example1.txt", line 16, in example1.txt Failed example: example1.goodmorning(’Jack’) Expected: ’Good morning, Jack!’ Got nothing

Now one test failed, so implement the function now: def goodmorning(name): "This returns a good morning message" return "Good morning, %s!"% name

178 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

Now run the test again, it will run without failures. Now start thinking about other functionalities required for the module. Before start coding write about it in text ﬁle. Decide API, write test, write code, than continue this cycle until you ﬁnish your requirements.

7.3.2 Running tests

By conventions your test modules are put in tests module under each package. But the doctest ﬁles can be placed in the package itself. For example if the package is ticketcollector. Then the main doctest ﬁle can be placed in ticketcollector/README.txt. And create a sub-package zopetic.tests, under this package create test modules like test_main.py, test_extra.py etc. To run the unit tests, change to instance home:

$ cd ticketcollector $ ./bin/test

7.4 Interface

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

7.4.1 Introduction

Interfaces are objects that specify (document) the external behavior of objects that “provide” them. An interface specifies behavior through: • Informal documentation in a doc string • Attribute definitions • Invariants, which are conditions that must hold for objects that provide the interface Some of the motivations for using interfaces are: • Avoid monolithic design by developing small, exchangeable pieces • Model external responsibility, functionality, and behavior • Establish contracts between pieces of functionality • Document the API The classic software engineering book Design Patterns by the Gang of Four recommends that you Program to an interface, not an implementation. Defining a formal interface is helpful in understanding a system. Moreover, interfaces bring you all the benefits of Zope Component Architecture. In some modern programming languages: Java, C#, VB.NET etc, interfaces are an explicit aspect of the language. Since Python lacks interfaces, Zope implements them as a meta-class to inherit from. I can do X Describing the ability to do something is the classical definition of an API. Those abilities are defined and implemented as methods. I have X This statement declares the availability of data, which is classically associated with schemas. The data is stored in attributes and properties.

7.4. Interface 179 BlueBream Documentation, Release 1.0a4

You can do X with me Here we describe the behavior of an object. Classically there is no analog. However, MIME- types are great example of behavior declaration. This is implemented using empty “marker interfaces” as they describe implicit behavior. The distinction between those three types of contracts was ﬁrst pointed out in this form by Philipp von Weitershausen. Understanding those distinctions is very important, since other programming languages do not necessarily use all three of these notions. In fact, often only the ﬁrst one is used.

7.4.2 Deﬁning Interfaces

• Python has no concept of interfaces • Not a problem • Interfaces are just objects • “Abuse” the class statement to create an interface • Syntax proposed in PEP 245 In Java, for example, interfaces are special types of objects that can only serve as interfaces in their intended, limited scope. An interface from the zope.interface package, on the other hand, deﬁnes the interface by implementing a meta-class, a core concept of Python. Thus, interfaces are merely using an existing Python pattern.

7.4.3 An example

Here is a classic hello world style example:

>>> class Host(object): ...... def goodmorning(self, name): ... """Say good morning to guests""" ...... return "Good morning, %s!"% name

In the above class, you deﬁned a goodmorning method. If you call the goodmorning method from an object created using this class, it will return Good morning, ...!

>>> host= Host() >>> host.goodmorning(’Jack’) ’Good morning, Jack!’

Here host is the actual object your code uses. If you want to examine implementation details you need to access the class Host, either via the source code or an API documentation tool. Now we will begin to use the Zope interfaces. For the class given above you can specify the interface like this:

>>> from zope.interface import Interface

>>> class IHost(Interface): ...... def goodmorning(guest): ... """Say good morning to guest"""

180 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

As you can see, the interface inherits from zope.interface.Interface. This use (abuse?) of Python’s class statement is how Zope deﬁnes an interface. The I preﬁx for the interface name is a useful convention.

7.4.4 Declaring interfaces

You have already seen how to declare an interface using zope.interface in previous section. This section will explain the concepts in detail. Consider this example interface:

>>> from zope.interface import Interface >>> from zope.interface import Attribute

>>> class IHost(Interface): ... """A host object""" ...... name= Attribute("""Name of host""") ...... def goodmorning(guest): ... """Say good morning to guest"""

The interface, IHost has two attributes, name and goodmorning. Recall that, at least in Python, methods are also attributes of classes. The name attribute is defined using zope.interface.Attribute class. When you add the attribute name to the IHost interface, you don’t set an initial value. The purpose of defining the attribute name here is merely to indicate that any implementation of this interface will feature an attribute named name. In this case, you don’t even say what type of attribute it has to be!. You can pass a documentation string as a first argument to Attribute. The other attribute, goodmorning is a method defined using a function definition. Note that self is not required in interfaces, because self is an implementation detail of class. For example, a module can implement this interface. If a module implements this interface, there will be a name attribute and goodmorning function defined. And the goodmorning function will accept one argument. Now you will see how to connect interface-class-object. So object is the real living thing, objects are instances of classes. And interface is the actual definition of the object, so classes are just the implementation details. This is why you should program to an interface and not to an implementation. Now you should familiarize yourself with two more terms to understand other concepts. The first one is “provide” and the other one is “implement”. Object provides interfaces and classes implement interfaces. In other words, objects provide interfaces that their classes implement. In the above example, host (object) provides IHost (interface), and Host (class) implements IHost (interface). One object can provide more than one interface; also one class can implement more than one interface. Objects can also provide interfaces directly, in addition to what their classes implement. Note: Classes are the implementation details of objects. In Python, classes are callable objects, so why can’t other callable objects implement an interface? Yes, it is possible. For any callable object you can declare that it produces objects that provide some interfaces by saying that the callable object implements the interfaces. The callable objects are generally called “factories”. Since functions are callable objects, a function can be an implementer of an interface.

7.4.5 Implementing interfaces

To declare a class implements a particular interface, use the function zope.interface.implements in the class statement. Consider this example, here Host implements IHost:

>>> from zope.interface import implements

>>> class Host(object):

7.4. Interface 181 BlueBream Documentation, Release 1.0a4

...... implements(IHost) ...... name= u’’ ...... def goodmorning(self, guest): ... """Say good morning to guest""" ...... return "Good morning, %s!"% guest

Note: If you wonder how implements function works, refer the blog post by James Henstridge (http://blogs.gnome.org/jamesh/2005/09/08/python-class-advisors/) . In the adapter section, you will see an adapts function, it is also working similarly. Since Host implements IHost, instances of Host provide IHost. There are some utility methods to introspect the declarations. The declaration can write outside the class also. If you don’t write interface.implements(IHost) in the above example, then after deﬁning the class statement, you can write like this:

>>> from zope.interface import classImplements >>> classImplements(Host, IHost)

7.4.6 Marker interfaces

An interface can be used to declare that a particular object belongs to a special type. An interface without any attribute or method is called marker interface. Here is a marker interface:

>>> from zope.interface import Interface

>>> class ISpecialGuest(Interface): ... """A special guest"""

This interface can be used to declare an object is a special guest.

7.5 Zope Component Architecture

7.5.1 Introdction

Zope Component Architecture (ZCA) is a framework for supporting component based design and programming. It is very well suited to developing large Python software systems. The ZCA is not speciﬁc to the Zope web application server: it can be used for developing any Python application. The ZCA is all about using Python objects effectively. Components are reusable objects with introspectable interfaces. A component provides an interface implemented in a class, or any other callable object. It doesn’t matter how the component is implemented, the important part is that it comply with its interface contracts. Using ZCA, you can spread the complexity of systems over multiple cooperating components. It helps you to create two basic kinds of components: adapter and utility. There are two core packages related to the ZCA: • zope.interface is used to deﬁne the interface of a component. • zope.component deals with registration and retrieval of components.

182 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

Remember, the ZCA is not about the components themselves, rather it is about creating, registering, and retrieving components. Remember also, an adapter is a normal Python class (or a factory in general) and utility is a normal Python callable object. The ZCA framework is developed as part of the Zope 3 project. As noted earlier, it is a pure Python framework, so it can be used in any kind of Python application. Currently both Zope 3 and Zope 2 projects use this framework extensively. There are many other projects including non-web applications using it.

7.5.2 Installation

Using zc.buildout with zc.recipe.egg recipe you can create Python interpreter with speciﬁed Python eggs. First you can create a directory and initialize Buildout:

$ mkdir explore-zope.component $ cd explore-zope.component $ echo "#Buildout configuration" > buildout.cfg $ svn co svn://svn.zope.org/repos/main/zc.buildout/trunk/bootstrap $ ~/usr/bin/python2.4 bootstrap/bootstrap.py

Now modify the buildout.cfg like this:

[buildout] parts= py

[py] recipe= zc.recipe.egg eggs= zope.component interpreter= mypython

Now run buildout script inside bin directory. This will download zope.component and its dependency eggs and install it. Now you can access the interpreter created by the Buildout recipe like this:

$ ./bin/buildout $ ./bin/mypython >>> import zope.component

7.5.3 Adapters

Implementation

This section will describe adapters in detail. Zope component architecture, as you noted, helps to effectively use Python objects. Adapter components are one of the basic components used by Zope component architecture for effectively using Python objects. Adapter components are Python objects, but with well deﬁned interface. To declare a class is an adapter use adapts function deﬁned in zope.component package. Here is a new FrontDeskNG adapter with explicit interface declaration:

>>> from zope.interface import implements >>> from zope.component import adapts

>>> class FrontDeskNG(object): ...... implements(IDesk) ... adapts(IGuest)

7.5. Zope Component Architecture 183 BlueBream Documentation, Release 1.0a4

...... def __init__(self, guest): ... self.guest= guest ...... def register(self): ... guest= self.guest ... next_id= get_next_id() ... bookings_db[next_id]={ ... ’name’: guest.name, ... ’place’: guest.place, ... ’phone’: guest.phone ... }

What you deﬁned here is an adapter for IDesk, which adapts IGuest object. The IDesk interface is implemented by FrontDeskNG class. So, an instance of this class will provide IDesk interface.

>>> class Guest(object): ...... implements(IGuest) ...... def __init__(self, name, place): ... self.name= name ... self.place= place

>>> jack= Guest("Jack","Bangalore") >>> jack_frontdesk= FrontDeskNG(jack)

>>> IDesk.providedBy(jack_frontdesk) True

The FrontDeskNG is just one adapter you created, you can also create other adapters which handles guest registration differently.

Registration

To use this adapter component, you have to register this in a component registry also known as site manager. A site manager normally resides in a site. A site and site manager will be more important when developing a Zope 3 application. For now you only required to bother about global site and global site manager ( or component registry). A global site manager will be in memory, but a local site manager is persistent. To register your component, ﬁrst get the global site manager:

>>> from zope.component import getGlobalSiteManager >>> gsm= getGlobalSiteManager() >>> gsm.registerAdapter(FrontDeskNG, ... (IGuest,), IDesk,’ng’)

To get the global site manager, you have to call getGlobalSiteManager function available in zope.component package. In fact, the global site manager is available as an attribute (globalSiteManager) of zope.component package. So, you can directly use zope.component.globalSiteManager attribute. To register the adapter in component, as you can see above, use registerAdapter method of component registry. The ﬁrst argument should be your adapter class/factory. The second argument is a tuple of adaptee objects, i.e, the object which you are adapting. In this example, you are adapting only IGuest object. The third argument is the interface implemented by the adapter component. The fourth argument is optional, that is the name of the particular adapter. Since you gave a name for this adapter, this is a named adapter. If name is not given, it will default to an empty string (‘’).

184 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

In the above registration, you have given the adaptee interface and interface to be provided by the adapter. Since you have already given these details in adapter implementation, it is not required to specify again. In fact, you could have done the registration like this:

>>> gsm.registerAdapter(FrontDeskNG, name=’ng’)

There are some old API to do the registration, which you should avoid. The old API functions starts with provide, eg: provideAdapter, provideUtility etc. While developing a Zope 3 application you can use Zope conﬁguration markup language (ZCML) for registration of components. In Zope 3, local components (persistent components) can be registered from Zope Management Interface (ZMI) or you can do it programmatically also. You registered FrontDeskNG with a name ng. Similarly you can register other adapters with different names. If a component is registered without name, it will default to an empty string.

Querying adapter

Retrieving registered components from component registry is achieved through two functions available in zope.component package. One of them is getAdapter and the other is queryAdapter. Both functions accepts same arguments. The getAdapter will raise ComponentLookupError if component lookup fails on the other hand queryAdapter will return None. You can import the methods like this:

>>> from zope.component import getAdapter >>> from zope.component import queryAdapter

In the previous section you have registered a component for guest object (adaptee) which provides IDesk interface with name as ng. In the ﬁrst section of this chapter, you have created a guest object named jack. This is how you can retrieve a component which adapts the interface of jack object (IGuest) and provides IDesk interface also with name as ng. Here both getAdapter and queryAdapter works similarly:

>>> getAdapter(jack, IDesk,’ng’) #doctest: +ELLIPSIS >>> queryAdapter(jack, IDesk,’ng’) #doctest: +ELLIPSIS

As you can see, the ﬁrst argument should be adaptee then, the interface which should be provided by component and last the name of adapter component. If you try to lookup the component with an name not used for registration but for same adaptee and interface, the lookup will fail. Here is how the two methods works in such a case:

>>> getAdapter(jack, IDesk,’not-exists’) #doctest: +ELLIPSIS Traceback (most recent call last): ... ComponentLookupError: ... >>> reg= queryAdapter(jack, ... IDesk,’not-exists’) #doctest: +ELLIPSIS >>> reg is None True

As you can see above, getAdapter raised a ComponentLookupError exception, but queryAdapter returned None when lookup failed.

7.5. Zope Component Architecture 185 BlueBream Documentation, Release 1.0a4

The third argument, the name of registration, is optional. If the third argument is not given it will default to empty string (‘’). Since there is no component registered with an empty string, getAdapter will raise ComponentLookupError. Similarly queryAdapter will return None, see yourself how it works:

>>> getAdapter(jack, IDesk) #doctest: +ELLIPSIS Traceback (most recent call last): ... ComponentLookupError: ... >>> reg= queryAdapter(jack, IDesk) #doctest: +ELLIPSIS >>> reg is None True

In this section you have learned how to register a simple adapter and how to retrieve it from component registry. These kind of adapters is called single adapter, because it adapts only one adaptee. If an adapter adapts more that one adaptee, then it is called multi adapter.

Retrieving adapter using interface

Adapters can be directly retrieved using interfaces, but it will only work for non-named single adapters. The ﬁrst argument is the adaptee and the second argument is a keyword argument. If adapter lookup fails, second argument will be returned.

>>> IDesk(jack, alternate=’default-output’) ’default-output’

Keyword name can be omitted:

>>> IDesk(jack,’default-output’) ’default-output’

If second argument is not given, it will raise ‘TypeError‘:

>>> IDesk(jack) #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS Traceback (most recent call last): ... TypeError: (’Could not adapt’, , )

Here ‘FrontDeskNG‘ is registered without name:

>>> gsm.registerAdapter(FrontDeskNG)

Now the adapter lookup should succeed:

>>> IDesk(jack,’default-output’) #doctest: +ELLIPSIS

For simple cases, you may use interface to get adapter components.

7.5.4 Utility

Now you know the concept of interface, adapter and component registry. Sometimes it would be useful to register an object which is not adapting anything. Database connection, XML parser, object returning unique Ids etc. are examples of these kinds of objects. These kind of components provided by the ZCA are called utility components.

186 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

Utilities are just objects that provide an interface and that are looked up by an interface and a name. This approach creates a global registry by which instances can be registered and accessed by different parts of your application, with no need to pass the instances around as parameters. You need not to register all component instances like this. Only register components which you want to make replace- able.

Simple utility

A utility can be registered with a name or without a name. A utility registered with a name is called named utility, which you will see in the next section. Before implementing the utility, as usual, deﬁne its interface. Here is a greeter interface:

>>> from zope.interface import Interface >>> from zope.interface import implements

>>> class IGreeter(Interface): ...... def greet(name): ... """Say hello"""

Like an adapter a utility may have more than one implementation. Here is a possible implementation of the above interface:

>>> class Greeter(object): ...... implements(IGreeter) ...... def greet(self, name): ... return "Hello"+ name

The actual utility will be an instance of this class. To use this utility, you have to register it, later you can query it using the ZCA API. You can register an instance of this class (utility) using registerUtility:

>>> from zope.component import getGlobalSiteManager >>> gsm= getGlobalSiteManager()

>>> greet= Greeter() >>> gsm.registerUtility(greet, IGreeter)

In this example you registered the utility as providing the IGreeter interface. You can look the interface up with either queryUtility or getUtility:

>>> from zope.component import queryUtility >>> from zope.component import getUtility

>>> queryUtility(IGreeter).greet(’Jack’) ’Hello Jack’

>>> getUtility(IGreeter).greet(’Jack’) ’Hello Jack’

As you can see, adapters are normally classes, but utilities are normally instances of classes. Only once you are creating the instance of a utility class, but adapter instances are dynamically created whenever you query for it.

7.5. Zope Component Architecture 187 BlueBream Documentation, Release 1.0a4

Named utility

When registering a utility component, like adapter, you can use a name. As mentioned in the previous section, a utility registered with a particular name is called named utility. This is how you can register the greeter utility with a name:

>>> greet= Greeter() >>> gsm.registerUtility(greet, IGreeter,’new’)

In this example you registered the utility with a name as providing the IGreeter interface. You can look up the interface with either queryUtility or getUtility:

>>> from zope.component import queryUtility >>> from zope.component import getUtility

>>> queryUtility(IGreeter,’new’).greet(’Jill’) ’Hello Jill’

>>> getUtility(IGreeter,’new’).greet(’Jill’) ’Hello Jill’

As you can see here, while querying you have to use the name as second argument. Calling getUtility function without a name (second argument) is equivalent to calling with an empty string as the name. Because, the default value for second (keyword) argument is an empty string. Then, component lookup mechanism will try to ﬁnd the component with name as empty string, and it will fail. When component lookup fails it will raise ComponentLookupError exception. Remember, it will not return some random component registered with some other name. The adapter look up functions, getAdapter and queryAdapter also works similarly.

7.6 Content Component

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

7.6.1 Introduction

See this example:

>>> from zope import interface

>>> class IPerson(interface.Interface): ... name= interface.Attribute("Name") >>> class Person(object): ... interface.implements(IPerson) ... name= None >>> jack= Person() >>> jack.name="Jack"

Here jack is a content component. So a content component is nothing but an object which provides a particular interface. As said in the previous chapter, use zope.schema to deﬁne ﬁelds of interface. The above interface can be declared like this:

188 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

>>> from zope import interface >>> from zope import schema

>>> class IPerson(interface.Interface): ... name= schema.TextLine( ... title=u"Name", ... description=u"Name of person", ... default=u"", ... required=True)

If you are developing an enterprise application content will be the most important thing you have to organize ﬁrst. To learn Zope 3 application development with content components, this chapter introduce a simple ticket/issue collector application. First look at the user stories, this book will implement these stories in coming chapters. 1. Individual small ticket collector for each project. Many collectors can be added to one running zope. 2. Any number of tickets can be added to one collector. 3. Each ticket will be added with a description and one initial comment. 4. Additional comments can be added to tickets. This chapter starts a simple implementation of ticket collector. As stated above, our goal is to develop a fully functional, though not great-looking, web-based ticket collector application. The root object will be the Collector, which can contain Ticket objects from various users. Since you want to allow people to respond to various tickets, you have to allow tickets to contain replies, which are Comment objects. That means you have two container-based components: The Collector contains only tickets and can be added to any Folder or container that wishes to be able to contain it. To make the ticket collector more interesting, it also has a description, which brieﬂy introduces the subject/theme of the discussions hosted. Tickets, on the other hand should be only contained by ticket collector. They will each have a summary and a description. And last Comment should be only contained by tickets. This setup should contain all the essential things that you need to make the object usable. Later on you will associate a lot of other meta-data with these components to integrate them even better into BlueBream and add additional functionality. The most convenient place to put your package is $HOME/myzope/lib/python. To create that package, add a directory using:

$ cd $HOME/myzope/lib/python/ $ mkdir collector on GNU/Linux. To make this directory a package, place an empty __init__.py ﬁle in the new directory. In GNU/Linux you can do something like:

$ echo "# Make it a Python package" >> collector/__init__.py but you can of course also just use a text editor and save a file of this name. Just make sure that there is valid Python code in the file. The file should at least contain some whitespace, since empty files confuse some archive programs. From now on you are only going to work inside this collector package, which should be located at $HOME/myzope/lib/python/collector.

7.6. Content Component 189 BlueBream Documentation, Release 1.0a4

7.7 Conﬁguration

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

7.7.1 Introduction

Developing components alone does not make a framework. There must be some configuration utility that tells the system how the components work together to create the application server framework. This is done using the Zope Configuration Markup Language (ZCML) for all filesystem-based code. Therefore it is very important that a developer knows how to use ZCML to hook up his/her components to the framework. As stated above, it became necessary to develop a method to setup and configure the components that make up the application server. While it might seem otherwise, it is not that easy to develop an effective configuration system, since there are several requirements that must be satisfied. Over time the following high-level requirements developed that caused revisions of the implementation and coding styles to be created: 1. While the developer is certainly the one that writes the initial cut of the configuration, this user is not the real target audience. Once the product is written, you would expect a system administrator to interact much more frequently with the configuration, adding and removing functionality or adjust the configuration of the server setup. System administrators are often not developers, so that it would be unfortunate to write the configuration in the programming language, here Python. But an administrator is familiar with configuration scripts, shell code and XML to some extend. Therefore an easy to read syntax that is similar to other configuration files is of advantage. 2. Since the configuration is not written in Python, it is very important that the tight integration with Python is given. For example, it must be very simple to refer to the components in the Python modules and to internation- alize any human-readable strings. 3. The configuration mechanism should be declarative and not provide any facilities for logical operations. If the configuration would support logic, it would become very hard to read and the initial state of the entire system would be unclear. This is another reason Python was not suited for this task. 4. Developing new components sometimes requires to extend the configuration mechanism. So it must be easy for the developer to extend the configuration mechanism without much hassle. To satisfy the first requirement, we decided to use an XML-based language (as the name already suggests). The advantage of XML is also that it is a “standard format”, which increases the likelihood for people to be able to read it right away. Furthermore, we can use standard Python modules to parse the format and XML namespaces help us to group the configuration by functionality. A single configuration step is called a directive. Each directive is an XML tag, and therefore the tags are grouped by namespaces. Directives are done either by simple or complex directives. Complex directives can contain other sub- directives. They are usually used to provide a set of common properties, but do not generate an action immediately. A typical configuration file would be:

190 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

All configuration files are wrapped by the configure tag, which represents the beginning of the configuration. In the opening of this tag, we always list the namespaces we wish to use in this configuration file. Here we only want to use the generic Zope 3 namespace, which is used as the default. Then we register an adapter with the system on line 4-7. The interfaces and classes are referred to by a proper Python dotted name. The configure tag might also contain an i18n_domain attribute that contains the domain that is used for all the translatable strings in the configuration. As everywhere in Zope 3, there are several naming and coding conventions for ZCML inside a package. By default you should name the configuration file configure.zcml. Inside the file you should only declare namespaces that you are actually going to use. When writing the directives make sure to logically group directives together and use comments as necessary. Comments are written using the common XML syntax: . For more info see Steve’s detailed ZCML Style Guide at http://dev.zope.org/Zope3/ZCMLStyleGuide for more info. To satisfy our fourth requirement, it is possible to easily extend ZCML through itself using the meta namespace. A directive can be completely described by four components, its name, the namespace it belongs to, the schema and the directive handler:

These meta-directives are commonly placed in a file called meta.zcml. The schema of a directive, which commonly lives in a file called metadirectives.py, is a simple Zope 3 schema whose fields describe the available attributes for the directive. The configuration system uses the fields to convert and validate the values of the configuration for use. For example, dotted names are automatically converted to Python objects. There are several specialized fields specifically for the configuration machinery: • PythonIndentifier - This field describes a python identifier, for example a simple variable name. • GlobalObject - An object that can be accessed as a module global, such as a class, function or constant. • Tokens - A sequence that can be read from a space-separated string. The value_type of the field describes token type. • Path - A file path name, which may be input as a relative path. Input paths are converted to absolute paths and normalized. • Bool - An extended boolean value. Values may be input (in upper or lower case) as any of: yes, no, y, n, true, false, t, or f. • MessageID - Text string that should be translated. Therefore the directive schema is the only place that needs to deal with internationalization. This satisfies part of requirement 2 above. The handler, which commonly lives in a file called metaconfigure.py, is a function or another callable object that knows what needs to be done with the given information of the directive. Here is a simple (simplified to the actual code) example: def adapter(_context, factory, provides, for_, name=’’):

_context.action( discriminator=(’adapter’, for_, provides, name), callable= provideAdapter, args= (for_, provides, factory, name), )

7.7. Conﬁguration 191 BlueBream Documentation, Release 1.0a4

The first argument of the handler is always the _context variable, which has a similar function to self in classes. It provides some common methods necessary for handling directives. The following arguments are the attributes of the directive (and their names must match). If an attribute name equals a Python keyword, like for in the example, then an underscore is appended to the attribute name. The handler should also not directly execute an action, since the system should first go through all the configuration and detect possible conflicts and overrides. Therefore the _context object has a method called action that registers an action to be executed at the end of the configuration process. The first argument is the discriminator, which uniquely defines a specific directive. The callable is the function that is executed to provoke the action, the args argument is a list of arguments that is passed to the callable and the kw contains the callable’s keywords. As you can see, there is nothing inheritly difficult about ZCML. Still, people coming to Zope 3 often experience ZCML as the most difficult part to understand. This often created huge discussions about the format of ZCML. However, I believe that the problem lies not within ZCML itself, but the task it tries to accomplish. The components themselves always seem so clean in implementation; and then you get to the configuration. There you have to register this adapter and that view, make security assertions, and so on. And this in itself seems overwhelming at first sight. When I look at a configuration file after a long time I often have this feeling too, but reading directive for directive often helps me to get a quick overview of the functionality of the package. In fact, the configuration files can help you understand the processes of the Zope 3 framework without reading the code, since all of the interesting interactions are defined right there. Furthermore, ZCML is well documented at many places, including the Zope 3 API documentation tool at http://localhost:8080/++apidoc++/. Here is a short list of the most important namespaces: • zope - This is the most generic and fundamental namespace of all, since it allows you to register all basic components with the component architecture. • browser - This namespace contains all of the directives that deal with HTML output, including managing skins and layer, declare new views (pages) and resources as well as setup auto-generated forms. • meta - As discussed above, you can use this namespace to extend available directives. • xmlrpc - This is the equivalent to browser, except that allows one to specify methods of components that should be available via XML-RPC. • i18n - This namespace contains all internationalization- and localization-specific configuration. Using register- Translations you can register new message catalogs with a translation domain. • help - Using the register directive, you can register new help pages with the help system. This will give you context-sensitive help for the ZMI screens of your products. • mail - Using the directives of this namespace you can setup mailing components that your application can use to

7.8 Startup

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

7.8.1 Introduction

The BlueBream framework creates WSGI applications, which can run behind any WSGI compliant web servers. The main application is configured and created via a factory function defined inside startup.py. This functions returns the WSGI complaint application object to the server. For example, in the “ticket collector” tutorial, you can see the factory function defined in src/tc/main/startup.py file:

192 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

import zope.app.wsgi def application_factory(global_conf): zope_conf= global_conf[’zope_conf’] return zope.app.wsgi.getWSGIApplication(zope_conf)

PaseDeploy together with PasteScript are then used to run the WSGI application. However, any WSGI server can be used to run BlueBream application 1. We provide PaseDeploy with the WSGI application factory as an entry point. For example, in the “ticket collector” tutorial, you can see the entry point deﬁned in setup.py ﬁle:

[paste.app_factory] main = tc.main.startup:application_factory

The application can now be launched as a web service using the paster serve command provided by PasteScript. To configure the web server, an INI file has to be passed to the command as an argument. The INI file defines the WSGI application, any WSGI middleware we may want and web server options. For example, in the “ticket collector” tutorial, you can see the WSGI application defined in deploy.ini file:

[app:main] use = egg:ticketcollector

[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/etc/zope.conf

You can read more about PasteDeploy and PasteScript in the PythonPaste site.

7.8.2 Running WSGI application

When you run BlueBream application using the paster server command, you can see something like this:

$ ./bin/paster serve deploy.ini ... Starting server in PID 13367. serving on http://127.0.0.1:8080

7.9 Functional Testing

7.9.1 Introduction

In this chapter, you will learn more about functional testing. A doctest based package (zope.testbrowser) is used in BlueBream for functional testing. Unlike unit tests, functional tests are user interface (view) oriented.

1 WSGI servers like mod_wsgi don’t require the paster serve command provided by PasteDeploy to run the WSGI server.

7.9. Functional Testing 193 BlueBream Documentation, Release 1.0a4

7.9.2 zope.testbrowser

The central part of this package is a browser object. This create this object, import Browser class from zope.testbrowser.testing:

>>> from zope.testbrowser.testing import Browser >>> browser= Browser()

To learn the usage of package, ﬁrst create a simple HTML page with following content:

Test Page

To open a page:

>>> browser.open(’http://localhost/zopetest/simple.html’) >>> browser.url ’http://localhost/zopetest/simple.html’

7.9.3 Test layer

7.9.4 Running tests

Your test suites can be placed in tests.py module under each packages. By default, in BlueBream there will be a tests.py with one test suite created using z3c.testsetup:

import z3c.testsetup

test_suite= z3c.testsetup.register_all_tests(’tc.main’)

The z3c.testsetup will aut-recover test suites from doctest ﬁles. You can create your doctest ﬁles, similar to example given in README.txt:

ticketcollector

:doctest: :functional-zcml-layer: ftesting.zcml

Open browser and test::

>>> from zope.testbrowser.testing import Browser >>> browser = Browser() >>> browser.open(’http://localhost/@@index’) >>> ’Welcome to BlueBream’ in browser.contents True

The fouth line speciﬁes that a ZCML ﬁle named ftesting.zcml is required to setup the test layer. To run the tests:

194 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

$ ./bin/test

7.10 Skinning

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

7.10.1 Introduction

It is often required to build web applications with equal/similar features, but different look and feel. Variation of look and feel can be simple or complex. It can be either just an exchange of a CSS ﬁle and some images. Sometimes, you will be required to reconﬁgure the application to have different user interface components, such as widgets, tables etc. Also you will be required to mix and match user interface components from multiple packages. In BlueBream, the skin concept is implemented to use the Zope component architecture. There are two terms associated with skinning named, layer and skin. Before proceeding, it would be better to understand the meaning of these two terms in BlueBream skinning.

Layers

• Deﬁne the “feel” of a site • Contain presentation logic • Common artifacts: pages, content providers, viewlet managers, and viewlets • Developed by BlueBream (Python) developers

Skins

Layers versus skins

• Both are implemented as interfaces • BlueBream does not differentiate between the two • In fact, the distinction of layers deﬁning the “feel” and skins the “look” is a convention. You may not want to follow the convention, if it is too abstract for you, but if you are developing application with multiple look and feel, I strongly suggest using this convention, since it cleanly separates concerns. • Both support inheritance/acquisition

7.10. Skinning 195 BlueBream Documentation, Release 1.0a4

This is realized through a combination of interface inheritance and component lookup techniques. This book will discuss this in more detail later. Skins are directly provided by a request

7.10.2 Core skins

• Access skin using ++skin++Name after the server root • Core Skins that are part of the repository – Rotterdam – the default skin shown – Boston – a newer skin featuring viewlets – Basic – a skin with no layout styles – Debug – based on Rotterdam, shows debug information upon failures • Try http://localhost:8080/++skin++Boston Unfortunately, it is hard to reuse the UI components developed for these skins, since they still rely on the not so ﬂexible macro pattern. Thus, it is better if you start from scratch. This will also avoid a lot of the overhead that comes with the over-generalized core skins.

7.10.3 A new skin

• Views registered for default layer by default zope.publisher.interfaces.browser.IDefaultBrowserLayer • Default layer contains a lot of things you do not need (security concerns) • Since pretty much everything in zope.app is registered into the default layer, it has an uncontrollable amount of junk in it. It is very hard to verify that all those registrations fulﬁll your security needs. Another problem is that views might be available that you do not want to be available. • Always want to develop skins from scratch • Some registrations in the default layer are very useful • Examples of those useful registrations include error views, traversal registrations, and widgets.

Setting up a layer

Write an interface for the layer that inherits the minimal layer:

from zope.publisher.interfaces.browser import IBrowserSkinType class IHelloWorldLayer(IBrowserSkinType): """Hello World Application Layer"""

Change all page, viewletmanager, and viewlet directives to specify this layer: layer=”.interfaces.IHelloWorldLayer” Once you changed those registrations, the helloworld.html page is not available anymore in the core skins. The templates by themselves do not matter.

196 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

Using layer

Registering views and resources is not any different now, but you can simply register them on the skin directly:

As you can see, you don’t have to create an extra layer just to create a custom skin. You were also able to use standard Component Architecture ZCML directives instead of custom ones whose special syntax the developer needs to remember additionally. A typical browser:page with with layer speciﬁed is like this:

Setting up a skin

Skins are technically interfaces deﬁned using zope.interface package. To create a custom skin it is always better to inherit from a standard layer or another skin interface. It is by convention that skins will be created in sub-package named skin in your browser package of your main package. For example, if your package name is foo, then foo.browser.skin will be the skin package, but this is not mandatory. Your skin interfaces can be deﬁned in foo.browser.skin.interfaces. Write an interface for each new skin that inherits the Hello World application layer:

class IBasicSkin(IHelloWorldLayer): """Basic Skin for Hello World App."""

To register this you can use interface and utility directives in zope namespace. The type of the IShanghaiSkin skin is zope.publisher.interfaces.browser.IBrowserSkinType. Here is a sample configure.zcml:

As a shortcut, you can also just use the interface directive and pass the new name parameter. The following one directive has the same effect as the two above regarding the skin registration:

7.10. Skinning 197 BlueBream Documentation, Release 1.0a4

Using the skin

Access it via: http://localhost:8080/++skin++BasicSkin Hide skin traversal step by using Apache’s Virtual Hosting feature To change the default skin to something else use: Simply specifying the browser:defaultSkin directive in your configuration file will not work, since it has been specified in zope/app/zcmlfiles/browser.zcml already. You can either change the skin at this location or use the zope:includeOverrides directive, which will override the any included directives.

7.10.4 Summary

This chapter introduced skinnig in BlueBream.

7.11 Zope Schemas and Widgets

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

7.11.1 Introduction

In the early stages of development, the BlueBream developers decided that it would be cumbersome to manually write HTML forms and to manually validate the input. BlueBream team realized that if they could extend interfaces, we could auto-generate HTML forms and also automatically validate any input. This chapter gives some background information and formally introduces the zope.schema and zope.app.form packages.

7.11.2 History and Motivation

Originally, Stephan Richter wanted to port Formulator, a very successful Zope 2 product to auto-generate and validate forms, to BlueBream (then know as Zope 3). In Formulator, one would create various input fields (like integers or text lines) in a form and provide some meta-data about the fields, like the maximum and minimum length of a string. You could then tell the form to simply render itself. For more details see http://zope.org/Members/infrae/Formulator. Even though Formulator tried to split application logic and presentation, various parts were still not sufficiently separated, mainly due to the limitations Zope 2 provided. Therefore the original port remained a hack in Zope 3 until

198 Chapter 7. Manual BlueBream Documentation, Release 1.0a4 the idea of schemas was developed by Jim Fulton and Martijn Faassen (the original author of Formulator) during the Berlin BBQ Sprint (April 2002) when trying to combine Zope 3’s version of Formulator and class properties. After all presentation logic was removed, Formulator fields felt a lot like interface specification for attributes. So it was realized, that if we supply more meta-data to the attribute declarations in interfaces, then we could accomplish auto-generation and validation of HTML forms. These extended attributes are still known as “fields”. If an interface contains any fields, then this interface is conventionally called a schema. The following three main goals of schemas developed: 1. Full specification of properties on an API level 2. Data input validation and conversion 3. Automated GUI form generation (mainly for the Web browser)

7.11.3 Schema versus Interfaces

As mentioned before, schemas are just an extension to interfaces and therefore depend on the zope.interface package. Fields in schemas are equivalent to methods in interfaces. Both are complementary to each other, since they describe different aspects of an object. The methods of an interface describe the functionality of a component, while the schema’s ﬁelds represent the state. It is thus not necessary to develop a new syntax for writing schemas and we simply reuse the interface declaration: from zope.interface import Interface from zope.schema import Text class IExample(Interface):

text= Text( title=u"Text", description=u"The text of the example.", required=True)

• Line 2: All default fields can be simply imported from zope.schema. • Line 7-8: The title and description are used as human-readable text for the form generation. Of course, they also serve as documentation of the field itself. • Line 9: Various fields support several other meta-data fields. The required option is actually available for all fields and specifies whether an object implementing IExample must provide a value for text or not.

7.11.4 Core Schema Fields

After we have seen a simple example of a schema, let’s now look at all the basic fields and their properties. • Properties that all fields support: – title (type: TextLine): The title of the attribute is used as label when displaying the field widget. – description (type: Text): The description of the attribute is used for tooltips and advanced help. – required (type: Bool): Specifies whether an attribute is required or not to have a value. In add-forms, required attributes are equivalent to required constructor arguments. – readonly (type: Bool): If a field is readonly, then the value of the attribute can be set only once and can then only be displayed. Often a unique id for some object is a good candidate for a read-only field.

7.11. Zope Schemas and Widgets 199 BlueBream Documentation, Release 1.0a4

– default (type: depends on field): The default value that is given to the attribute, if no initialization value was provided. This value is often specified, if a field is required. – order (type: Int): Fields are often grouped by some logical order. This value specifies a relative position in this order. We usually do not set this value manually, since it is automatically assigned when an interface is initialized. The order of the fields in a schema is by default the same as the order of the fields in the Python code. • Bytes, BytesLine Bytes and BytesLine only differ by the fact that BytesLine cannot contain a new line character. Bytes behave identical to the Python type str. Bytes and BytesLine fields are iteratable. – min_length (type: Int): After the white space has been normalized, there cannot be less than this amount of characters in the bytes string. The default is None, which refers to no minimum. – max_length (type: Int): After the white space has been normalized, there cannot be more than this amount of characters in the bytes string. The default is None, which refers to no maximum. • Text, TextLine The two fields only differ by the fact that TextLine cannot contain a newline character. Text fields contain unicode, meaning that they are intended to be human-readable strings/text. Text and TextLine fields are iteratable. – min_length (type: Int): After the white space has been normalized, there cannot be less than this amount of characters in the text string. The default is None, which refers to no minimum. – max_length (type: Int): After the white space has been normalized, there cannot be more than this amount of characters in the text string. The default is None, which refers to no maximum. • SourceText Source Text is a special field derived from Text, which contains source code of any type. It is more or less a marker field for the forms machinery, so that special input fields can be used for source code. • Password Password is a special derivative for the TextLine field and is treated separately for presentation reasons. How- ever, someone also might want more fine-grained validation for passwords. • Bool The Bool field has no further attributes. It maps directly to Python’s bool object. • Int Int fields directly map to Python’s int type. – min (type: Int): Specifies the smallest acceptable integer. This is useful in many ways, such as allowing only positive values by making this field 0. – max (type: Int): Specifies the largest acceptable integer, which excludes the value itself. It can be used to specify an upper bound, such as the current year, if you are interested in the past only. Both attributes combined allow the programmer to specify ranges of acceptable values. • Float Float fields directly map to Python’s float type. – min (type: Float): Specifies the smallest acceptable floating point number. This is useful in many ways, such as allowing only positive values by making this field 0.0.

200 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

– max (type: Float): Specifies the largest acceptable floating point number, which excludes the value itself (typical computer programming pattern). It can be used to specify an upper bound, such as 1.0, if you are only interested in probabilities. Both attributes combined allow the programmer to specify ranges of acceptable values. • Datetime Similar to Int and Float, Datetime has a min and max field that specify the boundaries of the possible values. Acceptable values for these fields must be instances of the builtin datetime type. • Tuple, List The reason both of these fields exists is that we can easily map them to their Python type tuple and list, respectively. Tuple and List fields are iteratable. – min_length (type: Int): There cannot be less than this amount of items in the sequence. The default is None, which means there is no minimum. – max_length (type: Int): There cannot be more than this amount of items in the sequence. The default is None, which means there is no maximum. – value_type (type: Field): Values contained by these sequence types must conform to this field’s constraint. Most commonly a Choice field (see below) is specified here, which allows you to select from a fixed set of values. • Dict The Dict is a mapping field that maps from one set of fields to another. fields are iteratable. – min_length (type: Int): There cannot be less than this amount of items in the dictionary. The default is None, which means there is no minimum. – max_length (type: Int): There cannot be more than this amount of items in the dictionary. The default is None, which means there is no maximum. – key_type (type: Field): Every dictionary item key has to conform to the specified field. – value_type (type: Field): Every dictionary item value has to conform to the specified field. • Choice The Choice field allows one to select a particular value from a provided set of values. You can either provide the values as a simple sequence (list or tuple) or specify a vocabulary (by reference or name) that will provide the values. Vocabularies provide a flexible list of values, in other words the set of allowed values can change as the system changes. Since they are so complex, they are covered separately in “Vocabularies and Fields”. – vocabulary (type: Vocabulary): A vocabulary instance that is used to provide the available values. This attribute is None, if a vocabulary name was specified and the field has not been bound to a context. – vocabularyName (type: TextLine): The name of the vocabulary that is used to provide the values. The vocabulary for this name can only be looked up, when the field is bound, in other words has a context. Upon binding, the vocabulary is automatically looked using the name and the context. The constructor also accepts a values argument that specifies a static set of values. These values are immediately converted to a static vocabulary. • Object This field specifies an object that must implement a specific schema. Only objects that provide the specified schema are allowed.

7.11. Zope Schemas and Widgets 201 BlueBream Documentation, Release 1.0a4

– schema (type: Interface): This field provides a reference to the schema that must be provided by objects that want to be stored in the described attribute. • DottedName Derived from the BytesLine field, the DottedName field represents valid Python-style dotted names (object references). This field can be used when it is desirable that a valid and resolvable Python dotted name is provided. This field has no further attributes. • URI Derived from the BytesLine field, the URI field makes sure that the value is always a valid URI. This is particularly useful when you want to reference resources (such as RSS feeds or images) on remote computers. This field has no further attributes. • Id Both, the DottedName and URI field, make up the Id field. Any dotted name or URI represent a valid id in Zope. Ids are used for identifying many types of objects, such as permissions and principals, but also for providing annotation keys. This field has no further attributes. • InterfaceField The Interface field has no further attributes. Its value must be an object that provides zope.interface.Interface, in other words it must be an interface. For a formal listing of the Schema/Field API, see the API documentation tool at http://localhost:8080/++apidoc++ or see zope.schema.interfaces module.

7.11.5 Auto-generated Forms using the forms Package

Forms are much more Zope-specific than schemas and can be found in the zope.app.forms package. The views of schema fields are called widgets. Widgets responsible for data display and conversion in their specific presentation type. Currently widgets exist mainly for HTML (the Web browser). Widgets are separated into two groups, display and input widgets. Display widgets are often very simply and only show a text representation of the Python object. The input widgets, however, are more complex and display a greater variety of choices. The following list shows all available browser- based input widgets (found in zope.app.form.browser):

Text Widgets

Text-based widgets always require some sort of keyboard input. A string representation of a ﬁeld is then converted to the desired Python object, like and integer or a date. • TextWidget: Being probably the simplest widget, it displays the text input element and is mainly used for the TextLine, which expects to be unicode. It also serves as base widget for many of the following widgets. • TextAreaWidget: As the name suggests this widget displays a text area and assumes its input to be some unicode string. (note that the Publisher already takes care of the encoding issues). • BytesWidget, BytesAreaWidget: Direct descendents from TextWidget and TextAreaWidget, the only difference is that these widgets expect bytes as input and not a unicode string, which means they must be valid ASCII encodable. • ASCIIWidget: This widget, based on the BytesWidget, ensures that only ASCII character are part of the inputted data.

202 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

• PasswordWidget: Almost identical to the TextWidget, it only displays a password element instead of a text element. • IntWidget: A derivative of TextWidget, it only overwrites the conversion method to ensure the conversion to an integer. • FloatWidget: Derivative of TextWidget, it only overwrites the conversion method to ensure the conversion to an ﬂoating point. • DatetimeWidget: Someone might expect a smart and complex widget at this point, but for now it is just a simple TextWidget with a string to datetime converter. There is also a DateWidget that only handles dates.

Boolean Widgets

Boolean widgets’ only responsibility is to convert some binary input to the Python values True or False. • CheckBoxWidget: This widget displays a single checkbox widget that can be either checked or unchecked, representing the state of the boolean value. • BooleanRadioWidget: Two radio buttons are used to represent the true and false state of the boolean. One can pass the textual value for the two states in the constructor. The default is “on” and “off” (or their translation for languages other than English). • BooleanSelectWidget, BooleanDropdownWidget: Similar to the BooleanRadioWidget, textual representations of the true and false state are used to select the value. See SelectWidget and DropdownWidget, respectively, for more details.

Single Selection Widgets

Widgets that allow a single item to be selected from a list of values are usually views of a field, a vocabulary and the request, instead of just the field and request pair. Therefore so called proxy-widgets are used to map from field-request to field-vocabulary-request pairs. For example the ChoiceInputWidget, which takes a Choice field and a request object, is simply a function that looks up another widget that is registered for the Choice field, its vocabulary and the request. Below is a list of all available widgets that require the latter three inputs. • SelectWidget: This widget provides a multiply-sized selection element where the options are populated through the vocabulary terms. If the field is not required, a “no value” option will be available as well. The user will allowed to only select one value though, since the Choice field is not a sequence-based field. • DropdownWidget: As a simple derivative of the SelectWdiget, it has its size set to “1”, which makes it a dropdown box. Dropdown boxes have the advantage that they always just show one value, which makes some more user-friendly for single selections. • RadioWidget: This widget displays a radio button for each term in the vocabulary. Radio buttons have the advantage that they always show all choices and are therefore well suitable for small vocabularies.

Multiple Selections Widgets

This group of widgets is used to display input forms collection-based fields, such as List or Set. Similar to the single selection widgets, two proxy- widgets are used to look up the correct widget. The first step is to map from field- request to field- value_type- request using a widget called CollectionInputWidget. This allows us to use different widgets when the value type is an Int or Choice field for example. Optionally, a second proxy-widget is used to convert the field- value_type- request pair to a field- vocabulary- request pair, as it is the case when the value type is a choice field.

7.11. Zope Schemas and Widgets 203 BlueBream Documentation, Release 1.0a4

• MultiSelectWidget: Creates a select element with the multiple attribute set to true. This creates a multi-selection box. This is especially useful for vocabularies with many terms. Note that if your vocabulary supports a query interface, you can even filter your selectable items using queries. • MultiCheckBoxWidget: Similar to the multi-selection widget, this widget allows multi-value selections of a given list, but uses checkboxes instead of a list. This widget is more useful for smaller vocabularies. • TupleSequenceWidget: This widget is used for all cases where the value type is not a Choice field. It used the widget of the value type field to add new values to the tuple. Other input elements are used to remove items. • ListSequenceWidget: This widget is equivalent to the previous one, except that it generates lists instead of tuples.

Miscellaneous Widgets

• FileWidget: This widget displays a file input element and makes sure the received data is a file. This field is ideal for quickly uploading byte streams as required for the Bytes field. • ObjectWidget: The ObjectWidget is the view for an object field. It uses the schema of the object to construct an input form. The object factory, which is passed in as a constructor argument, is used to build the object from the input afterwards. Here is a simple interactive example demonstrating the rendering and conversion functionality of a widget:

>>> from zope.publisher.browser import TestRequest >>> from zope.schema import Int >>> from zope.app.form.browser import IntWidget >>> field= Int(__name__=’number’, title=u’Number’, min=0, max=10) >>> request= TestRequest(form={’field.number’: u’9’}) >>> widget= IntWidget(field, request) >>> widget.hasInput() True >>> widget.getInputValue() 9 >>> print widget().replace(’’,’ \n ’)

• Line 1 & 5: For views, including widgets, we always need a request object. The TestRequest class is the quick and easy way to create a request without much hassle. For each presentation type there exists a TestRequest class. The class takes a form argument, which is a dictionary of values contained in the HTML form. The widget will later access this information. • Line 2: Import an integer field. • Line 3 & 6: Import the widget that displays and converts an integer from the HTML form. Initializing a widget only requires a field and a request. • Line 4: Create an integer field with the constraint that the value must lie between 0 and 10. The __name__ argument must be passed here, since the field has not been initialized inside an interface, where the __name__ would be automatically assigned.

204 Chapter 7. Manual BlueBream Documentation, Release 1.0a4

• Line 7-8: This method checks whether the form contained a value for this widget. • Line 9-10: If so, then we can use the getInputValue() method to return the converted and validated value (an integer in this case). If we would have chosen an integer outside this range, a WidgetInputError would have been raised. • Line 11-20: Display the HTML representation of the widget. The replace() call is only for better readability of the output. Note that you usually will not have to deal with these methods at all manually, since the form generator and data converter does all the work for you. The only method you will commonly overwrite is _validate(), which you will use to validate custom values. This brings us right into the next subject, customizing widgets. There are two ways of customizing widgets. For small adjustments to some parameters (properties of the widget), one can use the browser:widget subdirective of the browser:addform and browser:editform directives. For example, to change the widget for a ﬁeld called “name”, the following ZCML code can be used.

In this case we force the system to use the TextWidget for the name, set the display width to 45 characters and add a style attribute that should try to set the width of the input box to the available width. The second possibility to change the widget of a ﬁeld is to write a custom view class. In there, custom widgets are easily realized using the CustomWidget wrapper class. Here is a brief example: from zope.app.form.widget import CustomWidget from zope.app.form.browser import TextWidget class CustomTextWidget(TextWidget): ... class SomeView: name_widget= CustomWidget(CustomTextWidget)

• Line 1: Since CustomWidget is presentation type independent, it is defined in zope.app.form.widget. • Line 4-5: You simply extend an existing widget. Here you can overwrite everything, including the _validate() method. • Line 7-8: You can hook in the custom widget by adding an attribute called name_widget, where name is the name of the field. The value of the attribute is a CustomWidget instance. CustomWidget has only one required constructor argument, which is the custom widget for the field. Other keyword arguments can be specified as well, which will be set as attributes on the widget. More information about schemas can be found in the README.txt file of the zope.schema package. The Zope 3 development Web site also contains some additional material. This concludes our introduction to schemas and forms. For examples of schemas and forms in practice, see the first chapters of the “Content Components - The Basics” part.

7.11. Zope Schemas and Widgets 205 BlueBream Documentation, Release 1.0a4

7.12 Forms

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

7.12.1 Introduction

BlueBream provides a HTML form library called zope.formlib to generate forms and widgets. There is an advanced community supported library called z3c.form. This chapter will describe about using zope.formlib. Forms are web components that use widgets to display and input data. Typically a template displays the widgets by accessing an attribute or method on an underlying class. BlueBream use zope.formlib to create various forms. Example form are AddForm, EditForm, Form. Instead of using a form library, you can create all form manually. But the formlib avoids many duplication works. The formlib generate form for getting input data. You can also create validators and responses.

7.12.2 Creating an AddForm

7.12.3 Creating an EditForm

7.12.4 Conclusion

This chapter introduced zope.formlib library to generate HTML forms and widgets.

206 Chapter 7. Manual CHAPTER EIGHT

FAQ

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

207 BlueBream Documentation, Release 1.0a4

Contents • FAQ – General * What is BlueBream ? * Why BlueBream ? * What is the Zope Foundation ? * How can I help ? * What is the license of BlueBream ? * Is BlueBream stable enough to be used in production environment ? * Which Python version is required? * What is the KGS (Known Good Set) ? * How do I start a new BlueBream project ? – Concepts * What is the component architecture ? * Where can I find pointers to resources ? * What’s the deal with the /@@ syntax ? * Are ContainerTypesConstraint & ItemTypePrecondition deprecated ? – Security * How do I configure several classes with the same permissions? * How can I determine (in code) if a principal has the right permissions ? * I’ve registered a PAU in the site-root; now I cannot log in as zope.Manager. What gives? * How do I setup authentication (using a PAU)? * How do I logout from BlueBream ? * Why I am getting ILoginPassword adaptation error when accessing login.html ? – User Interface * How do I set up z3c.traverser and zope.contentprovider? * How do I declare global constants in ZCML? * How can I register a content provider without using viewlet managers? * How do I serve out static content in zope3? * Is webdav source server available in BlueBream ? * How does one use ZCML overrides in buildout in site.zcml for zc.zope3recipes:app recipe ? * How write custom traversal in BlueBream ? – Programming * Is API documentation available online? * How do I check out a project/package from Zope subversion repository? * How do I upgrade from one minor release to another? * Must I always restart the BlueBream server, when I modify my code ? * How do I automatically create some needed object at application startup? * How do I validate two or more fields simultaneously? * How do I get the parent of location? * How do I set content type header for a HTTP request? * How do I give unique names to objects added to a container? * How do I add a catalog programmatically? * Is there a function with which I can get the url of a zope object? * How do I sort BTreeContainer objects ? * How do I extract request parameters in a view method? * How do I use Reportlab threadsafely? * Why isn’t my object getting added to the catalog? * How do I add custom interfaces to pre-existing components/classes? * How do I get IRequest object in event handler ? * How do I create RSS feeds? * Where to get zope.conf syntax details ? * How do I register a browser resource in a test? * How do I get a registered browser resource in a test? * How do I write a custom 404 error page? 208 * How do I delete an entire tree of objects? Chapter 8. FAQ – Configuration and Setup * How do I disable the url selection of the skin? * How do I set up z3c.traverser and zope.contentprovider? * How do I declare global constants in ZCML? * How can I register a content provider without using viewlet managers? * How do I serve out static content in zope3? * Is webdav source server available in BlueBream ? * How does one use ZCML overrides in buildout in site.zcml for zc.zope3recipes:app recipe ? * How write custom traversal in BlueBream ? * How do I make my project (or a third party project) appear in the APIDOC? * How can I determine (in code) if the instance is running in devmode or not? – Miscellaneous * How to check an object is implementing/providing a particular interface ? * How do I run a particular test from a package? * How do I record a session? * How do I test file upload using zope.testbrowser? * Why do I see ForbiddenAttribute exceptions/errors ? * “order” attribute not in browser:menuItem directive: * When running $instance/bin/runzope zlib import error appears? * I get a Server Error page when doing something that should work. How do I debug this? * I cannot see source when debugging eggified code * How do I get more details about system errors, in the browser itself? * How can I get a postmortem debugger prompt when a request raises an exception? * What version of ZODB does BlueBream use ? * How do I use ZODB blob ? * How to clear history (pack) in ZODB ? * Do you have an example of CRUD (create/read/update/delete) ? * Is there any tool to monitor ZODB activity ? * Where is zope.app.workflow ? BlueBream Documentation, Release 1.0a4

8.1 General

8.1.1 What is BlueBream ?

BlueBream is a production ready free/open source web application framework written in the Python programming language. BlueBream provides a component architecture, transactional object database, tightly integrated security model and many other features. BlueBream is coming from the Zope community which is started around 1998. Initially Zope’s core technologies were designed by Zope Corporation. The development of BlueBream started in late 2001. In November 2004, BlueBream was released. BlueBream is a complete rewrite that only preserves the original ZODB object database. The design of BlueBream is driven by the needs of large companies. It is directly intended for enterprise web application development using the newest development paradigms. Extreme programming development process has a real inﬂuence in BlueBream development. Automated testing is a major strength of BlueBream. Sprints were introduced to help accel- erate BlueBream development. In 2006 Zope foundation was formed to help organize and formalize the relationships with the Zope community.

8.1.2 Why BlueBream ?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-August/004205.html BlueBream has: • WSGI-compatible object publisher (zope.publisher) • Object database (ZODB) for transparently persisting objects; comes with load-balancing support (ZEO). • Component Architecture for making things pluggable very easily (zope.component) • XML-conﬁguration language for registering components (zope.conﬁguration), not mandatory but pretty much standard • Flexible security architecture with pluggable security policies (zope.security) • Good unit, integration and functional testing frameworks (zope.testing, zope.testbrowser) • XHTML-compliant templating language (zope.pagetemplate) • Schema engine and automatic form generation machinery (zope.formlib) • many more core and third-party packages that may already solve some of your problems. See http://svn.zope.org, for instance. BlueBream is: • ZPL (BSD-ish license) • Owned by Zope Foundation • written mostly by contributors, not just Zope Corporation. • usable in pieces or in whole

8.1.3 What is the Zope Foundation ?

From http://foundation.zope.org:

8.1. General 209 BlueBream Documentation, Release 1.0a4

The Zope Foundation has the goal to promote, maintain, and develop the Zope platform. It does this by supporting the Zope community. Our community includes the open source community of contributors to the Zope software, contributors to the documentation and web infrastructure, as well as the community of businesses and organizations that use Zope.

The Zope Foundation is the copyright holder of the Zope software and many extensions and associated software. The Zope Foundation also manages the zope.org website, and manages the infrastructure for open source collaboration.

For more details: http://foundation.zope.org/about

8.1.4 How can I help ?

If you’re interested in helping and you have time, educate yourself on the component architecture and BlueBream then volunteer to assist in your particular area of expertise. Please come to our IRC channel: #bluebream at irc.freenode.net Also join the mailing list: https://mail.zope.org/mailman/listinfo/bluebream

8.1.5 What is the license of BlueBream ?

BlueBream is licensed under Zope Public License (BSD like, GPL compatible license).

8.1.6 Is BlueBream stable enough to be used in production environment ?

Yes, it is stable enough to be used in production environment. BlueBream (or old Zope 3) is used in several larger production sites already. Several custom solutions have been written too. But the development of BlueBream will probably never be done, it will continue until all our needs are met :)

8.1.7 Which Python version is required?

Python 2.5 & 2.6 are the supported versions for BlueBream 1.0 ﬁnal release.

8.1.8 What is the KGS (Known Good Set) ?

Starting from version Zope 3.4, Zope 3 (BlueBream) has been split into many packages called “eggs”, that are released independently. The KGS is a set of python eggs, that are known to work together listed as a Buildout version ﬁle. • The KGS package index for zope 3.4 is : http://download.zope.org/zope3.4/ New versions ﬁle will be available here: http://download.zope.org/bluebream/

8.1.9 How do I start a new BlueBream project ?

Please look at the Getting Started documentation.

210 Chapter 8. FAQ BlueBream Documentation, Release 1.0a4

8.2 Concepts

8.2.1 What is the component architecture ?

It’s similar to other component architectures in that it lets you ﬁt small pieces of functionality together.

8.2.2 Where can I ﬁnd pointers to resources ?

1. IRC : #bluebream at irc.freenode.net 2. Mailing list: [email protected], Archives at: http://mail.zope.org/pipermail/bluebream/ 3. Wiki: http://wiki.zope.org/bluebream 4. Zope 3 book by Philipp von Weitershausen: http://worldcookery.com/ (Bit outdated) 5. Planet: http://planetzope.org/

8.2.3 What’s the deal with the /@@ syntax ?

@@ is a shortcut for ++view++. (Mnemonically, it kinda looks like a pair of goggle-eyes) To specify that you want to traverse to a view named bar of content object foo, you could (compactly) say .../foo/@@bar instead of .../foo/++view++bar. Note that even the @@ is not necessary if container foo has no element named bar - it only serves to disambiguate between views of an object and things contained within the object.

8.2.4 Are ContainerTypesConstraint & ItemTypePrecondition deprecated ?

These two are not deprecated, but contains and containers functions are recommended.

8.3 Security

8.3.1 How do I conﬁgure several classes with the same permissions?

Ref: http://mail.zope.org/pipermail/zope3-users/2007-June/006291.html Use like_class attribute of require tag, Here are some examples:

8.2. Concepts 211 BlueBream Documentation, Release 1.0a4

8.3.2 How can I determine (in code) if a principal has the right permissions ?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-August/004201.html The question is: how do I know if the current principal has permission for a speciﬁc view? Something like:

def canEdit(self): ppal= self.request.principal return canView(’edit’, INewsItem, ppal)

Use zope.security.canAccess and/or zope.security.canWrite To check for a speciﬁc permission on an object, you can do something like:

from zope.security.management import checkPermission has_permission= checkPermission(’zope.ModifyContent’, self.context)

8.3.3 I’ve registered a PAU in the site-root; now I cannot log in as zope.Manager. What gives?

Start zopedebug then unregister the utility. This will then let you log in as a user deﬁned in principals.zcml. Example (execute the following with zopedebug):

import transaction from zope.component import getSiteManager from zope.app.security.interfaces import IAuthentication lsm= getSiteManager(root) lsm.unregisterUtility(lsm.getUtility(IAuthentication), IAuthentication) transaction.commit()

When you exit zopedebug and start the server, you should be able to log in again using the user deﬁned in principals.zcml. This should have the zope.Manager permission. To avoid this happening, either assign a role to a user deﬁned in the PAU or set up a folder beneath the root, make it a site and add and register the PAU there. Then you will still be able to log in to the root of the site and have full permissions.

8.3.4 How do I setup authentication (using a PAU)?

site= getSite() sm= site.getSiteManager() pau= PluggableAuthentication() sm[’authentication’]= pau sm.registerUtility(pau, IAuthentication) users= PrincipalFolder() sm[’authentication’][’Users’]= users sm.registerUtility(users, IAuthenticatorPlugin, name="Users") pau.authenticatorPlugins= (users.__name__, ) pau.credentialsPlugins=("No Challenge if Authenticated","Session Credentials")

212 Chapter 8. FAQ BlueBream Documentation, Release 1.0a4

8.3.5 How do I logout from BlueBream ?

Ref: http://mail.zope.org/pipermail/zope3-users/2005-October/001112.html Ref: http://svn.zope.org/*checkout*/Zope3/branches/3.3/src/zope/app/security/browser/loginlogout.txt Logout is available from Zope 3.3 onwards, but it is disabled by default. To enable add this line to $instance/etc/overrides.zcml:

8.3.6 Why I am getting ILoginPassword adaptation error when accessing login.html ?

Ref: https://mail.zope.org/pipermail/zope3-users/2010-January/008745.html Q I am getting an error like this when accessing login.html view.

.../eggs/zope.principalregistry-3.7.0-py2.5.egg/zope/principalregistry/principalregistry.py", line 82, in unauthorized a = ILoginPassword(request) TypeError: (’Could not adapt’, , )

You need to include zope.login package in your ZCML conﬁguration ﬁle (site.zcml) as the adapter registration is available there:

8.4 User Interface

8.4.1 How do I set up z3c.traverser and zope.contentprovider? z3c.traverser and zope.contentprovider are helpful packages with good and clear doctests. It takes not too much time to get up and running with them. However the packages do not include an example of how to configure your new useful code into your project. It is clear from the doctests (and from your own doctests written while making and testing your own code) what needs to be configured. But if you are like me and it all isn’t yet quite second-nature, it isn’t clear how it can be configured. So, for z3c.traverser:

And for zope.contentprovider:

8.4.2 How do I declare global constants in ZCML?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-September/004381.html You could just use the directive, and group your constants into logical chunks. interfaces.py: class IDatabaseLoginOptions(Interface): username= Attribute() password= Attribute() conﬁg.py: class DatabaseLoginOptions(object): implements(IDatabaseLoginOptions) username=’foo’ password=’bar’ conﬁgure.zcml:

used: opts= getUtility(IDatabaseLoginOptions)

214 Chapter 8. FAQ BlueBream Documentation, Release 1.0a4

Obviously, this is a bit more work than just declaring some constants in ZCML, but global constants suffer the same problems whether they’re deﬁned in Python or XML. Parts of your application are making assumptions that they are there, with very speciﬁc names, which are not type checked.

8.4.3 How can I register a content provider without using viewlet managers?

You need to create and register simple adapter for object, request and view that implements the IContentProvider interface: class LatestNews(object):

implements(IContentProvider) adapts(Interface, IDefaultBrowserLayer, Interface)

def __init__(self, context, request, view): self.context= context self.request= request self.__parent__= view

def update(self): pass

def render(self): return ’Latest news’

In the ZCML:

Then you can use it in your TAL templates just like this:

Also, you may want to pass some parameters via TAL. For info on how to do this, read documentation in the zope.contentprovider. If you want to bind some content provider to some skin, change IDefaultBrowserLayer to your skin interface.

8.4.4 How do I serve out static content in zope3?

Ref: http://zope3.pov.lt/irclogs/%23zope3-dev.2006-10-02.log.html See the ZCML directives and they let you publish static ﬁles through Zope

8.4.5 Is webdav source server available in BlueBream ?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-September/004648.html Yes, see this: http://svn.zope.org/zope.webdav/trunk

8.4. User Interface 215 BlueBream Documentation, Release 1.0a4

8.4.6 How does one use ZCML overrides in buildout in site.zcml for zc.zope3recipes:app recipe ?

Ref: http://mail.zope.org/pipermail/zope3-users/2007-April/006106.html

8.4.7 How write custom traversal in BlueBream ?

See this blog entry by Marius Gedminas: http://mg.pov.lt/blog/zope3-custom-traversal.html

8.5 Programming

8.5.1 Is API documentation available online?

The Zope3 documentation infrastructure is powerful in that the html content is generated on the ﬂy. This makes it somewhat slow while browsing on older machines. A cached (and therefore fast) version of the docs are available online at: http://apidoc.zope.org/++apidoc++/

8.5.2 How do I check out a project/package from Zope subversion repository?

Ref: SettingUpAZope3Sandbox You can browse available projects here: http://svn.zope.org (in the package names, “zc” stands for “Zope Corporation”, “z3c” stands for “Zope 3 Community”) Then, to check out Zope3 trunk anonymously: svn co svn://svn.zope.org/repos/main/Zope3/trunk Zope3

Stable branches are available from : http://svn.zope.org/Zope3/branches (online) . And release tags from: http://svn.zope.org/Zope3/tags (online) To check out Zope 3.3 stable branch: svn co svn://svn.zope.org/repos/main/Zope3/branches/3.3 Zope33

8.5.3 How do I upgrade from one minor release to another?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-August/004025.html You can have more than one BlueBream installed, e.g. you can install Zope 3.2.1 in parallel to 3.2.0 and switch your instance over to 3.2.1 (by editing the start scripts in $INSTANCE/bin). You can also install Zope 3.2.1 into the place where 3.2.0 was installed; your instance should continue to work. Such a thing isn’t recommended when upgrading between major versions, though (3.2 to 3.3). Note: this is even easier if you use an egg based infrastructure. However, learning how to use eggs in a realistic way, is a signiﬁcant leap.

216 Chapter 8. FAQ BlueBream Documentation, Release 1.0a4

8.5.4 Must I always restart the BlueBream server, when I modify my code ?

No, you need not to restart, if you use the --reload option provided by the paster serve command. So, you can run like this:

./bin/paster serve --reload debug.ini

Note: We recommend writing automated tests to see the effect of changes. In the beginning, this seems like a huge annoyance - however, getting in the habit of writing unit and functional tests as you develop code will greatly alleviate this issue.

8.5.5 How do I automatically create some needed object at application startup?

http://mail.zope.org/pipermail/zope-dev/2007-December/030562.html Do it by subscribing to IDatabaseOpenedWithRootEvent (from zope.app.appsetup) Example code:

from zope.app.appsetup.interfaces import IDatabaseOpenedWithRootEvent from zope.app.appsetup.bootstrap import getInformationFromEvent import transaction

@adapter(IDatabaseOpenedWithRootEvent) def create_my_container(event): db, connection, root, root_folder= getInformationFromEvent(event) if ’mycontainer’ not in root_folder: root_folder[’mycontainer’]= MyContainer() transaction.commit() connection.close()

Then register this subscriber in your conﬁgure.zcml:

8.5.6 How do I validate two or more ﬁelds simultaneously?

Consider a simple example: there is a person object. A person object has name, email and phone attributes. How do we implement a validation rule that says either email or phone have to exist, but not necessarily both. First we have to make a callable object - either a simple function or callable instance of a class:

>>> def contacts_invariant(obj): ... if not (obj.email or obj.phone): ... raise Exception("At least one contact info is required")

Then, we deﬁne the person object’s interface like this. Use the interface.invariant function to set the invariant:

>>> class IPerson(interface.Interface): ...... name= interface.Attribute("Name") ... email= interface.Attribute("Email Address") ... phone= interface.Attribute("Phone Number") ...... interface.invariant(contacts_invariant)

8.5. Programming 217 BlueBream Documentation, Release 1.0a4

Now use validateInvariants method of the interface to validate:

>>> class Person(object): ... interface.implements(IPerson) ...... name= None ... email= None ... phone= None >>> jack= Person() >>> jack.email= u"[email protected]" >>> IPerson.validateInvariants(jack) >>> jill= Person() >>> IPerson.validateInvariants(jill) Traceback (most recent call last): ... Exception: At least one contact info is required

8.5.7 How do I get the parent of location?

To get the parent of an object use zope.traversing.api.getParent(obj). To get a list of the parents above an object use zope.traversing.api.getParents(obj).

8.5.8 How do I set content type header for a HTTP request?

From IRC (http://zope3.pov.lt/irclogs/%23zope3-dev.2006-06-20.log.html):

Is there any way using the browser:page directive, that I can specify that the Type of a page rendered is not "text/html" but rather "application/vnd.mozilla.xul+xml"?

Use request.response.setHeader(‘content-type’, ...)

8.5.9 How do I give unique names to objects added to a container?

First: from zope.app.container.interfaces import INameChooser

Name will be assigned from ‘create’ or ‘createAndAdd’ methods, here is an eg: def create(self, data): mycontainer= MyObject() mycontainer.value1= data[’value1’] anotherobj= AnotherObject() anotherobj.anothervalue1= data[’anothervalue1’] namechooser= INameChooser(mycontainer) name= chooser.chooseName(’AnotherObj’, anotherobj) mycontainer[name]= anotherobj return mycontainer

218 Chapter 8. FAQ BlueBream Documentation, Release 1.0a4

8.5.10 How do I add a catalog programmatically?

Ref: http://zopetic.googlecode.com/svn/trunk/src/browser/collectorform.py see this eg: from zopetic.interfaces import ITicket from zopetic.interfaces import ICollector from zopetic.ticketcollector import Collector from zope.app.intid.interfaces import IIntIds from zope.app.intid import IntIds from zope.component import getSiteManager from zope.app.catalog.interfaces import ICatalog from zope.app.catalog.catalog import Catalog from zope.security.proxy import removeSecurityProxy from zope.app.catalog.text import TextIndex

...

def create(self, data): collector = Collector() collector.description = data[’description’] return collector

def add(self, object): ob = self.context.add(object) sm = getSiteManager(ob) rootfolder = ob.__parent__ cat = Catalog() rootfolder[’cat’] = cat if sm.queryUtility(IIntIds) is None: uid = IntIds() rootfolder[’uid’] = uid sm.registerUtility(removeSecurityProxy(uid), IIntIds, ’’) pass sm.registerUtility(removeSecurityProxy(cat), ICatalog, ’cat’) cat[’description’] = TextIndex(’description’, ITicket) self._finished_add = True return ob

8.5.11 Is there a function with which I can get the url of a zope object?

Ref: http://zope3.pov.lt/irclogs/%23zope3-dev.2006-09-25.log.html Use: zope.component.getMultiAdapter((the_object, the_request), name=’absolute_url’) or: zope.traversing.browser.absoluteURL

8.5. Programming 219 BlueBream Documentation, Release 1.0a4

8.5.12 How do I sort BTreeContainer objects ?

Q Is there a way to sort the objects returned by values() from a zope.app.container.btree.BTreeContainer instance? Ref: http://zope3.pov.lt/irclogs/%23zope3-dev.2006-09-25.log.html Use sorted builtin function (available from Python 2.4 onwards) sorted(my_btree.values())

8.5.13 How do I extract request parameters in a view method?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-July/003876.html class MyPageView(BrowserView):

def __call__(self): if ’myOperation’ in self.request.form: param1= self.request.form[’param1’] param2= self.request.form[’param2’] do_something(param1, param2)

MyPageView has to be either the default view associated to the ‘mypage’ object or a view called ‘mypage’ associated to the RootFolder object. Alternately, you could use: class MyPageView(BrowserView):

def __call__(self, param1, param2="DEFAULT"): if ’myOperation’ in self.request.form: do_something(param1, param2)

8.5.14 How do I use Reportlab threadsafely?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-September/004583.html Use a mutex (a recursive lock makes things easier too): lock= threading.RLock() lock.acquire() try: ... finally: lock.release()

8.5.15 Why isn’t my object getting added to the catalog?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-May/003392.html Is it adaptable to IKeyReference? If you’re using the ZODB, deriving from Persistent is enough.

220 Chapter 8. FAQ BlueBream Documentation, Release 1.0a4

8.5.16 How do I add custom interfaces to pre-existing components/classes?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-November/004918.html You can do so with a little zcml:

8.5.17 How do I get IRequest object in event handler ?

Q How I can get IRequest in my event handler (I have only context)? Ref: http://mail.zope.org/pipermail/zope3-users/2007-April/006051.html import zope.security.management import zope.security.interfaces import zope.publisher.interfaces def getRequest(): i= zope.security.management.getInteraction() # raises NoInteraction

for p in i.participations: if zope.publisher.interfaces.IRequest.providedBy(p): return p

raise RuntimeError(’Could not find current request.’)

8.5.18 How do I create RSS feeds?

Refer http://kpug.zwiki.org/ZopeCreatingRSS (Taken from old zope-cookbook.org)

8.5.19 Where to get zope.conf syntax details ?

Refer: http://zope3.pov.lt/irclogs/%23zope3-dev.2008-04-01.log.html Look at schema.xml inside zope.app.appsetup egg And this xml ﬁle can point you to rest of the syntax. for details about look for component.xml in ZODB egg

8.5.20 How do I register a browser resource in a test?

First create a ﬁleresource factory (or imageresourcefactory, or another one): from zope.app.publisher.browser.fileresource import FileResourceFactory from zope.security.checker import CheckerPublic path=’path/to/file.png’ registration_name=’file.png’ factory= FileResourceFactory(path, CheckerPublic, name)

Then register it for your layer:

8.5. Programming 221 BlueBream Documentation, Release 1.0a4

from zope.component import provideAdapter provideAdapter(factory, (IYourLayer,), Interface, name)

8.5.21 How do I get a registered browser resource in a test?

A resource is just an adapter on the request. It can be seen as a view without any context. you can retrieve the FileResource or DirectoryResource like this:: getAdapter(request, name=’file.png’)

If this is a directory resource, you can access the ﬁles in it:: getAdapter(request, name=’img_dir’)[’foobar.png’]

Then get the content of the ﬁle with the GET method (although this is not part of any interface): getAdapter(request, name=’img_dir’)[’foobar.png’].GET()

8.5.22 How do I write a custom 404 error page?

Register a view for zope.publisher.interfaces.INotFound in your layer. The default corresponding view is zope.app.exception.browser.notfound.NotFound An equivalent exists for pagelets : z3c.layer.pagelet.browser.NotFoundPagelet

8.5.23 How do I delete an entire tree of objects?

You can’t control the order of deletion. The problem is that certain objects get deleted too soon, and other items may need them around, particularly if you have speciﬁed IObjectRemoved adapters. You basically have to manually create a deletion dependency tree, and force the deletion order yourself. This is one of the problems with events, ie: their order is not well deﬁned.

8.6 Conﬁguration and Setup

8.6.1 How do I disable the url selection of the skin?

FIXME: override the ++skin++ namespace traversal?

8.6.2 How do I set up z3c.traverser and zope.contentprovider? z3c.traverser and zope.contentprovider are helpful packages with good and clear doctests. It takes not too much time to get up and running with them. However the packages do not include an example of how to configure your new useful code into your project. It is clear from the doctests (and from your own doctests written while making and testing your own code) what needs to be configured. But if you are like me and it all isn’t yet quite second-nature, it isn’t clear how it can be configured. So, for z3c.traverser:

222 Chapter 8. FAQ BlueBream Documentation, Release 1.0a4

And for zope.contentprovider:

8.6.3 How do I declare global constants in ZCML?

8.6. Conﬁguration and Setup 223 BlueBream Documentation, Release 1.0a4

username=’foo’ password=’bar’ conﬁgure.zcml:

used: opts= getUtility(IDatabaseLoginOptions)

8.6.4 How can I register a content provider without using viewlet managers?

You need to create and register simple adapter for object, request and view that implements the IContentProvider interface: class LatestNews(object):

implements(IContentProvider) adapts(Interface, IDefaultBrowserLayer, Interface)

def __init__(self, context, request, view): self.context= context self.request= request self.__parent__= view

def update(self): pass

def render(self): return ’Latest news’

In the ZCML:

Then you can use it in your TAL templates just like this:

224 Chapter 8. FAQ BlueBream Documentation, Release 1.0a4

8.6.5 How do I serve out static content in zope3?

Ref: http://zope3.pov.lt/irclogs/%23zope3-dev.2006-10-02.log.html See the ZCML directives and they let you publish static ﬁles through Zope

8.6.6 Is webdav source server available in BlueBream ?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-September/004648.html Yes, see this: http://svn.zope.org/zope.webdav/trunk

8.6.7 How does one use ZCML overrides in buildout in site.zcml for zc.zope3recipes:app recipe ?

Ref: http://mail.zope.org/pipermail/zope3-users/2007-April/006106.html

8.6.8 How write custom traversal in BlueBream ?

See this blog entry by Marius Gedminas : http://mg.pov.lt/blog/zope3-custom-traversal.html

8.6.9 How do I make my project (or a third party project) appear in the APIDOC?

Add the following in your apidoc.zcml or conﬁgure.zcml: If it does not show up, add the following:

8.6.10 How can I determine (in code) if the instance is running in devmode or not? from zope.app.appsetup.appsetup import getConfigContext

def is_devmode_enabled(): """Is devmode enabled in zope.conf?""" config_context = getConfigContext() return config_context.hasFeature(’devmode’)

8.7 Miscellaneous

8.7.1 How to check an object is implementing/providing a particular interface ?

Use the providedBy available for the interface, it will return True, if the object provides the interface otherwise False. Eg:

8.7. Miscellaneous 225 BlueBream Documentation, Release 1.0a4

>>> IMyInterface.providedBy(myobject) True

8.7.2 How do I run a particular test from a package?

Go to your $ZOPE3INSTANCE/etc, then:

$ cd $HOME/myzope/etc $ ../bin/test.py -vpu --dir package/tests test_this_module

Here I assumed $HOME/myzope is your Zope3 instance directory. Replace ‘package’ with your package name.

8.7.3 How do I record a session?

You will need to download Shane Hathaways’ excellent (and minimal) tcpwatch package. This will log ALL data ﬂowing between client and server for you, and you can use this in developing tests. To record a session:

$ mkdir record $ tcpwatch.py -L8081:8080 -r record # Note: use the "-s" option if you don’t need a GUI (Tk).

8.7.4 How do I test ﬁle upload using zope.testbrowser?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-July/003830.html eg:-

>>> import StringIO >>> myPhoto= StringIO.StringIO(’my photo’) >>> control= user.getControl(name=’photoForm.photo’) >>> fileControl= control.mech_control >>> fileControl.add_file(myPhoto, filename=’myPhoto.gif’) >>> user.getControl(name=’photoForm.actions.add’).click() >>> imgTag= ’src="http://localhost/++skin++Application/000001/0001/1/photo"’ >>> imgTag in user.contents True

8.7.5 Why do I see ForbiddenAttribute exceptions/errors ?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-August/004027.html ForbiddenAttribute are always (ALWAYS!!!) an sign of missing security declarations, or of code accessing stuff it shouldn’t. If you’re accessing a known method, you’re most deﬁnitely lacking a security declaration for it. Zope, by default, is set to deny access for attributes and methods that don’t have explicit declarations.

226 Chapter 8. FAQ BlueBream Documentation, Release 1.0a4

8.7.6 “order” attribute not in browser:menuItem directive:

Q. I want to add a new view tab in the ZMI to be able to edit object attributes of some objects. So I’m adding a new menuItem in the zmi_views menu via ZCML with:

(MyClass is just a derived Folder with custom attributes) The problem is: the new tab always appear in the first place. I would like to put it just after the “content” tab, not before. The “order” directive does not work for that. How can I reorder the tabs so that my new tab appears in the 2nd position? The default implementation of menus sorts by interface first, and this item is most specific. See zope.app.publisher.browser.menu. If you do not like this behavior, you have to implement your own menu code.

8.7.7 When running $instance/bin/runzope zlib import error appears?

Ref: http://mail.zope.org/pipermail/zope/2004-November/154739.html When you compile Python, make sure you have installed zlib development library. In Debian 3.1 (Sarge) it is zlib1g- dev.

8.7.8 I get a Server Error page when doing something that should work. How do I debug this?

Here’s a nicely formatted IRC log detailing how Steve Alexander found a particular bug; it gives lots of good advice on tracking bugs: http://dev.zope.org/Members/spascoe/HowOneZope3BugWasFixed (Scott Pascoe) Ken Manheimer wrote up an in-depth account of interactive Zope debugging using the python prompt - it was written for Zope 2, but many of the principles and some of the actual techniques should translate to BlueBream. It’s at: http://www.zope.org/Members/klm/ZopeDebugging Here is ‘Using the Zope Debugger’ from the Zope3 docs: http://svn.zope.org/*checkout*/Zope3/trunk/doc/DEBUG.txt

8.7.9 I cannot see source when debugging eggiﬁed code

When you try to step into eggified code (libraries), you find that the source file referenced is invalid. Closer inspection reveals that the source path referenced has an invalid member like ‘tmpXXXXX’. The fix is easy, but first the reason why this happens: When you install eggs with easy_install, it creates a temp directory, and byte compiles the python code. Hence, the .pyc files that are generated reference this (working, but temporary) path. Easy_install then copies the entire package into the right place, and so the .pyc files are stuck with invalid references to source files. To solve this, simply remove all the “.pyc” files from any .egg paths that you have. On Unix, something like:

8.7. Miscellaneous 227 BlueBream Documentation, Release 1.0a4

find . -name "*.pyc" | xargs rm should do the trick.

8.7.10 How do I get more details about system errors, in the browser itself?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-November/004881.html Use the Debug skin via ++skin++Debug or via ++debug++errors (the latter is better if you still want to see your own skin).

8.7.11 How can I get a postmortem debugger prompt when a request raises an exception?

Edit your zope.conf and change the server type from HTTP (or whatever it is) to PostmortemDebuggingHTTP or WSGI-PostmortemDebuggingHTTP.:

address 8080 type PostmortemDebuggingHTTP

Restart the server in the foreground (you need an attached console to interact with the debugger).: path/to/instance/control/script stop path/to/instance/control/script fg

Now, when a request raises an exception, you’ll be dropped into a post-mortem debugger at the point of the exception.

8.7.12 What version of ZODB does BlueBream use ?

BlueBream 1.0 is using ZODB 3.9.x

8.7.13 How do I use ZODB blob ?

You can use z3c.blobfile implementation for storing images and other normal files. In BlueBream, blob storage is configured by default. The final configuration is inside etc/zope.conf, but this configuration file is generated from a template by Buildout. The templates is available in templates/zope_conf.in. So, if you want to make any changes, you can do it there:

228 Chapter 8. FAQ BlueBream Documentation, Release 1.0a4

The blob-dir specifies where you want to store blobs. As you can see, the directory location information is getting from Buildout configuration file. So, if you want to change the location, you need to change it in the Buildout configuration.

8.7.14 How to clear history (pack) in ZODB ?

From the debug shell, call the app.db.pack function:

$ ./bin/paster shell debug.ini >>> app.db.pack()

8.7.15 Do you have an example of CRUD (create/read/update/delete) ?

Ref: http://mail.zope.org/pipermail/zope3-users/2006-September/004248.html The Zope Object DataBase (ZODB), available by default to your application, makes CRUD very simpe. Create:

>>> from recipe import MyFolder, Recipe >>> folder= MyFolder() >>> recipe= Recipe() >>> folder[’dead_chicken’]= recipe

Read:

>>> folder[’dead_chicken’]

Update:

>>> recipe= folder[’dead_chicken’] >>> recipe.title= u’Dead chicken’ >>> recipe.description= u’Beat it to death’

Delete:

>>> del recipe[’dead_chicken’]

8.7.16 Is there any tool to monitor ZODB activity ?

Ref: http://zope3.pov.lt/irclogs/%23zope3-dev.2007-05-15.log.html There are some packages under development: • http://svn.zope.org/zc.z3monitor • http://svn.zope.org/zc.zservertracelog • http://svn.zope.org/zc.zodbactivitylog

8.7. Miscellaneous 229 BlueBream Documentation, Release 1.0a4

8.7.17 Where is zope.app.workﬂow ?

It has never been released with BlueBream, just as an add-on package. Please look at these packages: • http://pypi.python.org/pypi/hurry.workﬂow • http://pypi.python.org/pypi/zope.wfmc

230 Chapter 8. FAQ CHAPTER NINE

HOWTOS

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

9.1 Default view for objects

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

In BlueBream, a browser view can be accessed using @@ symbols before the view name. For example, if you have registered a view named testview for a container object named myobject, that view can be accessed like this: myobject/@@testview. Note: Container object – Any object implementing zope.content.interfaces.IContainer interface is called a content object. The view could be accessed without using the @@ symbols also, provided there is no content object with the same same exist inside the container. In the above example, If there is no content object named testview inside myobject container, then, the view can be accessed like myobject/testview. However, BlueBream recommend, always to use @@ symbols to access view to avoid ambiguity. Note: Content Object – If an interface provides zope.app.content.interfaces.IContentType interface type, then all objects providing the interface are considered content objects. In BlueBream, index is registered as the view name for zope.container.interfaces.IContainer interface. So, if you try to access any container object without specifying any view name, BlueBream will try to display the view registered with name as index. You can configure the name of default view for a particular type of object with browser:defaultView directive available in zope.publisher package. If the name of default view is not configured, and when you try to access an object without specifying the view name, you will get a ComponentLookupError with a message like this: Couldn’t find default view name. For example, if you try to access the root folder like: http://localhost:8080/ and name of default view is not configured, you will get an error like this:

ComponentLookupError: ("Couldn’t find default view name", , )

231 BlueBream Documentation, Release 1.0a4

Note: In order to use any ZCML except few built-ins like configure and include, you include the ZCML where it is deﬁned the directive, conventionally in BlueBream it will be inside meta.zcml for any package. For example, to use defaultView directive, you need to include meta.zcml ﬁle inside zope.publisher:

If you have created the application using the bluebream project template, you won’t get this error. Because there is already a a default view name (index) is configured in application.zcml configuration file inside the main package. If there is a default view name configured, but there is no view registered with that name, you will get NotFound error when you try to access object directly without specifying the name of view. For example, if the default view name is index and there is no such view registered for root folder, you will get an error like this:

NotFound: Object: , name: u’@@index’

As mentioned earlier, the browser:defaultView directive is deﬁned in zope.publisher. To use this directive, you need to include meta.zcml using include directive:

For example, you can specify the default view for IContainer like this:

If index is registered as the name for default view and the view is not explicitly mentioned in the URL, BlueBream will try to get @@index view for containers. However, you need to have a browser view registered to access the view, otherwise a NotFound error will be raised as mentioned above. More details about registering a browser view using browser:page directive is explained in Browser Page manual.

9.2 Adding new package dependency

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

You are working in your instance or developing your package and then you discover that there is a package you may ﬁnd useful, let’s say ‘ldappas’. Edit setup.py and add in install_requires the name of the package: setup(name=’ticketcollector’ ... install_requires = [’setuptools’, ... ’ldappas’, ], ...

Now it is time to rebuild your application:

232 Chapter 9. HOWTOs BlueBream Documentation, Release 1.0a4

$ ./bin/buildout

Finally, remember to register the new package at etc/site.zcml:

...

If there is any new directive required for this package, you need to include the conﬁguration ﬁle where the directive is registered. Normally the ZCML directives will be registered in meta package. You can use the file option as given below:

...

And restart application:

$ ./bin/paster serve debug.ini

9.3 Retrieving absolute URL for an object

BlueBream has a different, cleaner approach on how to handle URLs of objects. This recipe presents how to retrieve an URL for a given object, and the logic behind. This HOWTO assume that you have included zope.traversing.browser in your etc/site.zcml like this:

9.3.1 Understanding URLs

Each persistent object stored in the ZODB is reached through views, that handles its display. The URL is the location from wich the object is reached through the browser. For example, is the user tries to display foo , which is in bar , she will type: http://server/foo/bar. The object is pulled by the publisher which traverses the tree of objects from the root. In our case, it traverses foo , ask it for bar , and so on. foo will point bar to the publisher, because its __name__ property is bar . Getting an object URL is done by doing the back trip from the object to the root, building the string with the names of all traversed objects. The main difference with older behaviors is that bar doesn’t hold its URL.

9.3.2 Getting an object URL

The URL of all publishable objects can be retrieved this way, and a generic view class, called AbsoluteURL provide this feature under the absolute_url name.

9.3. Retrieving absolute URL for an object 233 BlueBream Documentation, Release 1.0a4

In a ZPT for instance, a given object URL can be retrieved with: my_object/@@absolute_url. In Python code, a call to the zope.traversing.browser.absoluteurl.absoluteURL function can be used. To try this function, open the debug shell:

$ ./bin/paster shell debug.ini

You can retrieve the root object URL, like this:

>>> from zope.publisher.browser import TestRequest >>> from zope.traversing.browser.absoluteurl import absoluteURL >>> request= TestRequest() >>> absoluteURL(root, request) ’http://127.0.0.1’

In the above example, root is the root folder object.

9.4 Dynamic ﬁelds in forms

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

To add fields dynamically using zope.formlib machinery, one should avoid subclassing form.EditForm. The form.EditForm would require you to also setup an adapter for your form field. The following code shows what is involved in having a custom field inside your form.

from zope.formlib import form from zope.schema import TextLine

class TestForm(form.PageForm): my_field_name = ’something’

def __init__(self, context, request): super(TestForm, self).__init__(context, request) self.form_fields = form.Fields(TextLine(__name__=self.my_field_name, title=u"Test Field"))

def setUpWidgets(self, ignore_request=False): name = self.name self.widgets = form.setUpWidgets( self.form_fields, self.prefix, self.context, self.request, data={self.my_field_name:SOME_VALUE}, ignore_request=ignore_request)

@form.action(label=_("Submit")) def handleSubmitAction(self, action, data): #do something relevant to you here

9.5 Testing persistent objects

You can create a fake module to test persistent objects with transaction commits, otherwise you will get an error like this:

234 Chapter 9. HOWTOs BlueBream Documentation, Release 1.0a4

PicklingError: Can’t pickle : attribute lookup __builtin__.TestItem failed

This HOWTO explain creating fake module to write test cases. The functionality to create fake module is provided by zope.testing.module. Inside your ticket collector application, you can create a persistent_test.txt ﬁle with a test case like this:

:doctest:

>>> from ZODB.tests.util import DB >>> import transaction >>> db = DB() >>> conn = db.open() >>> root = conn.root()

>>> from persistent import Persistent

>>> class TestItem(Persistent): ... pass

>>> item = TestItem() >>> root[’item’] = item >>> transaction.commit()

Now invoke the test runner as given below:

$ ./bin/test

You should get an erorr like this:

PicklingError: Can’t pickle : attribute lookup __builtin__.TestItem failed

Now open the tests.py and add two keyword arguments to z3c.testsetup.register_all_tests function named setup and teardown. The values of those keyword arguments could be zope.testing.module.setUp and zope.testing.module.tearDown respectively as given here:

from zope.testing import module test_suite= z3c.testsetup.register_all_tests(’testp2.main’, setup=module.setUp, teardown=module.tearDown)

A better method would be to create your own setUp and tearDown functions as given below so that you can add more code there, if required. Here is custom setUp and tearDown without any extra code:

import z3c.testsetup from zope.testing import module

def setUp(test): module.setUp(test)

def tearDown(test): module.tearDown(test)

test_suite= z3c.testsetup.register_all_tests(’testp2.main’, setup=setUp, teardown=tearDown)

By default the fake module name will be __main__. If you require another name for the module, you can specify it like this:

9.5. Testing persistent objects 235 BlueBream Documentation, Release 1.0a4

module.setUp(test,’mymodule’) module.tearDown(test,’mymodule’)

Now you can import the mymodule from the test cases (persistent_test.txt). Based on this module name functionality, here is a better way to create setUp and tearDown: import z3c.testsetup from zope.testing import module module_name=’testp2.main.mypersistent’ def setUp(test): module.setUp(test, module_name) def tearDown(test): module.tearDown(test, module_name) test_suite= z3c.testsetup.register_all_tests(’testp2.main’, setup=setUp, teardown=tearDown)

236 Chapter 9. HOWTOs CHAPTER TEN

CORE DEVELOPMENT

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

These documents are written for core development team. Always visit the latest documentation site for recent version of these documents which is actually used by the developers.

10.1 Contributing to BlueBream

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

If you are interested in contributing to BlueBream project, please look at the wiki page: http://wiki.zope.org/bluebream/ContributingToBlueBream

10.2 Developer Resources

• The source code is managed at Zope reposistory. You can checkout the trunk code like this (Anonymous access):

svn co svn://svn.zope.org/repos/main/bluebream/trunk bluebream

You can also become a contributor after signing a contributor agreement. • Project blog • The bugs and issues are tracked at launchpad. • BlueBream Wiki. • PyPI page • Documentation • Twitter • Mailing list • IRC Channel: #bluebream at irc.freenode.net • Buildbot

237 BlueBream Documentation, Release 1.0a4

10.3 Developing BlueBream

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

10.3.1 Making BlueBream Releases

The release procedure followed by BlueBream is very similar to that of ZTK release guidelines. Part of the ofﬁcial release guidelines is reviewing the changelog recorded in CHANGES.txt. This is an important step that cannot be automated. In other words, before starting a release make sure that: 1. All tests pass 2. All local changes are committed 3. The changelog is up to date.

10.3.2 Post release steps

10.4 Technical Decisions

• BlueBream is a “web framework”. • Shortening BlueBream as Bream or BB is acceptable. As of now, the “BB” shortening is getting popular in community. • The only public API exposed by “bluebream - the package” is an entry point:

"paste.paster_create_template": ["bluebream = bluebream.bluebream_base.template:BlueBream"]

The implementation of “bluebream” template is deﬁned in “bluebream.bluebream_base.template.BlueBream”. The template implementation location could be changed if required later. • All the framework code will be using “zope” or “zope.app” namespace packages. Although “bb” could be used as a namespace in future. • “bluebream” the project consists of project templates • “bluebream_website” is the location where web content is stored. • “bbkit” is where KGS infrastructure located. • BlueBream 1.0 should provide an up-gradation path from Zope 3.4 KGS • Any “shell command” required to be repeated should not be automated by the project template. • Running bootstrap.py and buildout inside project should not be added to project template creation for the previous reason. Another supporting reason is the easiness of adding sources to version controlling system.

238 Chapter 10. Core Development BlueBream Documentation, Release 1.0a4

10.5 Documentation Writing Guidelines

Original location: http://www.zope.org/DocProjects/writing_tips

10.5.1 Overview

Clear writing is hard. Explaining a complex subject like computer software to a novice audience is difﬁcult because you, the writer, are immersed in technical details before you even begin writing. Your task is to bring the reader to a level of familiarity with your subject equal to, or at least close to, your own familiarity. Writing in an unclear way, or drowning the reader in technical details will confuse them, cause them to “skim” the material, and come away with bad or false impressions of you or your subject. This guide gives you practical advice, from my own writing experience, to help you develop clear, instructive, main- tainable, and ultimately valuable software documentation. What follows is a series of rules that you can apply to what you’ve written, or are going to write, to improve the documentation you produce. These tips do not attempt to cover the most common English usage and composition errors. I consider the best resource of usage and composition rules to be The Elements of Style by William Strunk, Jr. A follow up of this book, edited and expanded by E. B. White, is also available (and is the most common edition found in bookstores). The Elements of Style is indispensable for anyone whose task is to write clear English. While the rules presented here are inspired by, and often reiterate, rules and concepts from The Elements of Style, their focus is primarily toward writing clear documentation for computer software, or anything equivalently technical. Here are some interesting links on the web to other style-related documents and references: • English usage in Cyberspace • Writer’s General Reference

10.5.2 Writing Tips

Speak directly to the reader

Address the reader in the second person as “you” , and use the possessive “your”. Use first person sparingly and only to refer to yourself: the writer. “We” should not be used to include yourself with the reader, but only to refer to multiple authors. Here is an example of text that includes the author with the reader: When we add a new method to this class, it will override any methods with the same name defined in our subclasses. This is often referred to as “The Royal We”. Fixing this is almost always a simple transformation: When you add a new method to this class, it will override any methods with the same name defined in your subclasses.

Be assertive

Do not speak in a weak, indeﬁnite, or probable way. As described in The Elements of Style (rule #11), use the active voice. This is so common an error it is worth repeating here with some examples. Active voice means engaging the subject of a sentence with an active verb. The opposite, passive voice, usually involves saying that the subject constantly is doing some inﬁnitive action. For example:

10.5. Documentation Writing Guidelines 239 BlueBream Documentation, Release 1.0a4

Something to remember about ZPublisher is that it will refuse to publish any method that doesn’t have a doc string. The standard convention for product management is to provide a series of tabbed management screens. Here are the same sentences speaking in active voice. Notice how this sometimes involves rearranging the sentence: Remember, ZPublisher refuses to publish any method that lacks a doc string. Tabbed management screens provide a standard convention for product management. Do not speak in probable terms like may, maybe, or probably. This is often the unconscious effect of writing documentation before the software it describes is written. Be assertive, and state what is, not what may be. “Maybe” can be struck entirely. “May be” and “probably is” can be replaced by “is”. “Should” sometimes falls under this rule also.

Explain key ideas in simple terms

Documentation should explain key ideas to the reader. Often, these ideas are not obvious to the reader when they use the software, and therefore must be explained. Writers are tempted to explain key ideas in terms of concrete technical details those ideas are based on. Unless your are specificly targeting an audience that seeks technical details, readers are often uninterested (at least initially) in the details that implement a key idea. Would you describe a building to a cave-dweller as a shelter from the elements, or a collection of bricks, boards, nails and other materials? Would you describe a car as an object that transports you from one place to another, or as a machine with pistons, brakes, wires and other parts? The first of these descriptions are the key ideas, the second of them are the details that implement the key ideas. If your audience seeks implementation details and is already familiar with the key idea then detailed explanation is correct. If you audience is the equivalent of a cave-dweller to your subject, then you must avoid implementation and focus on the key idea at first. When a reader fails to understand the meaning of documentation, it is usually because they encounter a word they do not understand. Clear explanation involves building a key idea in the readers mind using a succession of simple terms they can understand. When you throw an implementation detail in the explanation before they key idea is completed the reader stumbles; resulting in confusion. The reader skims over the technical parts that they don’t understand yet, or can’t understand yet, because you have not completed explaining the key idea to them. For example, the first paragraph of a draft of user documentation for Zope’s Python Methods states: All of Zope’s capabilities are provided by methods, one way or another. When you ask Zope for a URL, it first fetches an object from the ZODB and then calls some method of that object. The methods of built-in Zope objects are defined in Zope’s source code, or in Python classes stored in Product modules on the filesystem. Additional object classes (and their methods) can be defined by creating new filesystem Products, and this is appropriate when the implementation of a class requires extensive access to resources (such as the filesystem) which should be carefully protected. Before readers can even begin to understand what this paragraph is really saying they must understand ZODB, methods on objects, built-in Zope objects, what or where Zope’s source code is, Python classes, Product modules, the filesystem, object classes (and their methods), file-system Products, and why implementing them involves a class if it requires extensive access to resources which should be carefully protected. The first sentence should really say something like: You can write simple scripts in Zope in the Python programming language with Python Methods. Students in Driver’s Education do not learn how to use a steering wheel by being told about rack-and-pinions, Cardon shafts, toe, castor or double-wishbone suspensions. None of these technical details are relevant to teaching a driver’s- ed student to steer a car.

240 Chapter 10. Core Development BlueBream Documentation, Release 1.0a4

Use simple examples

Prose documentation is used to explain a key idea to the reader. An example is used to show a key idea to the reader. Both methods are very complimentary; prose documentation explains the workings of an example, and an example reveals the concrete concept behind an explanation. Your explanations should not be overly complex and neither should your examples. The level of complexity that is appropriate for both your explanations and your examples depends on your target audience, but neither should be written to exceed the level of complexity your target audience is expected to understand.

Avoid colloquial expression

Speak simply. If your audience is global, you cannot assume your reader’s native language is English. Colloquial speech is unnecessary and distracting for a reader that struggles to understand not only the concept your are describing, but also the language you are describing it in. By adjusting the interpreter check interval to reduce how often Python switches contexts you can really make Zope scream. Should be written as: By adjusting the interpreter check interval to reduce how often Python switches contexts you can really improve performance.

Provide answers, not questions

It is tempting to ask a question followed immediately by the answer. For example: What if you want the reptile page to display something besides the welcome message? You can replace the *index_html* method in the reptile section with a more appropriate display method, and still take advantage of the zoo header and footer including navigation. The question serves only to introduce a concept, not really to ask a question of the reader. State the concept directly: To display something besides the welcome message on the reptile page, replace the *index_html* method in the reptile section with a more appropriate display method. This still takes advantage of the zoo header and footer, including navigation. The result is a more assertive paragraph, one less sentence, and fewer words. This does not mean you should never ask questions, rather, you should ask questions to make the reader think about a possibility, or to engage their imagination, not to introduce a concept that can be stated directly.

Revise sentences that say little or nothing

The following sentences say little or nothing, and should be struck. What concepts they do present should be revised into surrounding sentences: At ﬁrst it would appear straightforward. You should begin at the beginning.

10.5. Documentation Writing Guidelines 241 BlueBream Documentation, Release 1.0a4

242 Chapter 10. Core Development CHAPTER ELEVEN

REFERENCE

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

11.1 zope.app.wsgi — WSGI Application

Warning: This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

• getWSGIApplication def getWSGIApplication(configfile, schemafile=None, features=(), requestFactory=HTTPPublicationRequestFactory, handle_errors=True): db= config(configfile, schemafile, features) application= WSGIPublisherApplication(db, requestFactory, handle_errors)

# Create the application, notify subscribers. notify(interfaces.WSGIPublisherApplicationCreated(application))

return application

The first argument “configfile” should an absolute path to “zope.conf” file. All other arguments are optional. The “schemafile” argument value will be the ZConfig schema (XXX: what is ZConfig) file. By default the value for “schemafile” will be “schema/schema.xml” defined inside “zope.app.appsetup”.

243 BlueBream Documentation, Release 1.0a4

244 Chapter 11. Reference BlueBream Documentation, Release 1.0a4

11.1.1 zope.annotation

11.1.2 zope.app.applicationcontrol

11.1.3 zope.app.appsetup

11.1.4 zope.app.authentication

11.1.5 zope.app.basicskin

11.1.6 zope.app.broken

11.1.7 zope.app.component

11.1.8 zope.app.container

11.1.9 zope.app.content

11.1.10 zope.app.debug

11.1.11 zope.app.dependable

11.1.12 zope.app.error

11.1.13 zope.app.folder

11.1.14 zope.app.form

11.1.15 zope.app.generations

11.1.16 zope.app.i18n

11.1.17 zope.app.interface

11.1.18 zope.app.locales

11.1.19 zope.app.localpermission

11.1.20 zope.app.pagetemplate

11.1.21 zope.app.principalannotation

11.1.22 zope.app.publication

11.1.23 zope.app.publisher

11.1.24 zope.app.renderer

11.1.25 zope.app.rotterdam

11.1.26 zope.app.schema 11.1. zope.app.wsgi — WSGI Application 245 11.1.27 zope.app.security

11.1.28 zope.app.server

11.1.29 zope.app.testing

11.1.30 zope.app.twisted

11.1.31 zope.app.zopeappgenerations

11.1.32 zope.authentication

11.1.33 zope.broken

11.1.34 zope.browser

11.1.35 zope.browsermenu

11.1.36 zope.browserpage

11.1.37 zope.browserresource

11.1.38 zope.cachedescriptors

11.1.39 zope.component

11.1.40 zope.componentvocabulary

11.1.41 zope.conﬁguration

11.1.42 zope.container

11.1.43 zope.contenttype

11.1.44 zope.copy

11.1.45 zope.copypastemove

11.1.46 zope.datetime

11.1.47 zope.deferredimport

11.1.48 zope.deprecation

11.1.49 zope.dottedname

11.1.50 zope.dublincore

11.1.51 zope.error

11.1.52 zope.event

11.1.53 zope.exceptions

11.1.54 zope.ﬁlerepresentation

11.1.55 zope.formlib

11.1.56 zope.hookable

11.1.57 zope.i18n

11.1.58 zope.i18nmessageid

11.1.59 zope.interface

11.1.60 zope.lifecycleevent

11.1.61 zope.location

11.1.62 zope.minmax

11.1.63 zope.pagetemplate

11.1.64 zope.password

11.1.65 zope.principalannotation

11.1.66 zope.principalregistry

11.1.67 zope.processlifetime

11.1.68 zope.proxy

11.1.69 zope.ptresource

11.1.70 zope.publisher

11.1.71 zope.schema

11.1.72 zope.security

11.1.73 zope.securitypolicy

11.1.74 zope.server

11.1.75 zope.session

11.1.76 zope.site

11.1.77 zope.size

11.1.78 zope.structuredtext

11.1.79 zope.tal

11.1.80 zope.tales

11.1.81 zope.testbrowser

11.1.82 zope.testing

11.1.83 zope.traversing BlueBream Documentation, Release 1.0a4

246 Chapter 11. Reference CHAPTER TWELVE

GLOSSARY

BlueBream BlueBream is a renaming of Zope 3, started in 2010 Setuptools Using Setuptools, developers can distribute Python packages. It creates the Egg deployment format. Setuptools is built on top of distutils, a built-in Python module. Distribute is a community developed fork of Setuptools. Egg An Egg is a deployment format created by Setuptools. Buildout A Python based Build system created by Jim Fulton. See the Buildout PyPI page for more detailed documentation. Zope 2 The Z Object Publishing Framework, a Python based web application server. Zope Component Architecture Zope Component Architecture (ZCA) is a Python framework for supporting component based design and programming Distribute A community developed fork of the Setuptools project. Zope Tool Kit The Zope Tool Kit (ZTK) is a set of libraries intended for reuse by projects to develop web applications or web frameworks. Zope Foundation The Zope Foundation is a not-for-profit organization that provides support for the Zope community and the Zope platform and its associated software. Zope 3 A project started in 2001 by the Zope community under the leadership of Jim Fulton. Zope Public License The ZPL has been certified as open source. It has also been designated as GPL compatible by the Free Software Foundation (FSF). WSGI The Web Server Gateway Interface defines a simple and universal interface between web servers and web applications or frameworks for the Python programming language. The latest version 3.0 of Python, released in December 2008, is already supported by mod_wsgi (a module for the Apache Web server). Paste Paste is a tool for using a Web Server Gateway Interface stack PasteDeploy PasteDeploy provides code to load WSGI applications and servers from URIs; these URIs can refer to Python Eggs for INI-style configuration files. Paste Script provides commands to serve applications based on this configuration file. PasteScript PasteScript is a pluggable command-line frontend, including commands to setup package file layouts Separation of concerns Separation of concerns (SoC) is the process of separating a computer program into distinct features that overlap in functionality as little as possible. ZODB The Zope Object Database provides an object-oriented database for Python that provides a high-degree of transparency. Applications can take advantage of object database features with few, if any, changes to application logic. ZODB includes features such as a pluggable storage interface, rich transaction support, and undo.

247 BlueBream Documentation, Release 1.0a4

ZCML The Zope Conﬁguration Markup Language Jim Fulton James Fulton - Chief Technology Ofﬁcer, Zope Corp, AKA the Zope Pope, J1m in IRC. He’s the man. Bobo Jim Fulton’s original design of object oriented internet publishing technology, implemented in Python. Jim has recently come full circle, releasing Bobo, a Web application framework for the impatient. CGI Common Gateway Interface Grok Grok is a web application framework for Python developers. It is aimed at both beginners and very experienced web developers. Grok has an emphasis on agile development. Grok is easy and powerful. mod_wsgi Apache module to host any Python application which supports the Python WSGI interface. The module would be suitable for use in hosting high performance production web sites, as well as average self managed personal sites running on web hosting services. Web application framework for the impatient

248 Chapter 12. Glossary CHAPTER THIRTEEN

CONTRIBUTORS

There are many people who contributed to BlueBream through the old Zope 3 project from 2001. In fact, many of the technologies came from Zope 2 project which was started in 1998. Thanks to all contributors from 1998 for developing Zope. It would be difﬁcult to list all the names here as we don’t have enough details. So, this is a list of new contributors to documentation and bluebream package from January, 2010. This is a list of people who directly committed to bluebream documentation and bluebream package. But there are many others who helped us through IRC, mailing list, wiki etc. Thanks to all. Please update this list, as soon as somebody is committed to documentation directly. • Baiju M (baijum) • Chris McDonough (chrism) • Daniel Nilsson • Kent Tenney (ktenney) • Michael Haubenwallner (d2m)

13.1 Logo Design

Thanks to Hiran V for the logo design.

13.2 Other Contributors

Please add other contributors name here who helped but not committed directly. • Justin Denney (IRC nick: jdenney) • Hermann Himmelbauer

249 BlueBream Documentation, Release 1.0a4

250 Chapter 13. Contributors CHAPTER FOURTEEN

INDICES AND TABLES

• Index • Module Index • Search Page • Glossary

251 BlueBream Documentation, Release 1.0a4

252 Chapter 14. Indices and tables MODULE INDEX

Z zope.app.wsgi, 243

253 BlueBream Documentation, Release 1.0a4

254 Module Index INDEX

B Zope Component Architecture, 247 BlueBream, 247 Zope Foundation, 247 Bobo, 248 Zope Public License, 247 Buildout, 247 Zope Tool Kit, 247 zope.app.wsgi (module), 243 C CGI, 248 D Distribute, 247 E Egg, 247 G Grok, 248 J Jim Fulton, 248 M mod_wsgi, 248 P Paste, 247 PasteDeploy, 247 PasteScript, 247 S Separation of concerns, 247 Setuptools, 247 W WSGI, 247 Z ZCML, 247 ZODB, 247 Zope 2, 247 Zope 3, 247

255