Skip to content

Z
Zope
Commit c815993a authored by Hanno Schlichting's avatar Hanno Schlichting
Browse files
Options

Update documentation some more. Removed pretty much outdated and obsolete bits

parent c4eb640d
Hide whitespace changes
Inline Side-by-side
Showing with 48 additions and 1596 deletions
doc/DEBUGGING.txt
View file @ c815993a
Running Zope in Debug Mode
If you wish to run Zope in debug mode, set the 'debug-mode'
......@@ -14,64 +13,16 @@ Running Zope in Debug Mode
Using 'zopectl debug'
In Zopes 2.7 and better, a utility known as 'zopectl' is installed
into generated instance homes. You can use it to inspect a Zope
instance's running state via an interactive Python interpreter by
passing zopectl the 'debug' parameter on the command line. The
'top-level' Zope object (the root folder) will be bound to the name
'app' within the interpreter. You can then use normal Python method
calls against app and use the Python interpreter normally to inspect
results::
A utility known as 'zopectl' is installed into generated instance homes.
You can use it to inspect a Zope instance's running state via an
interactive Python interpreter by passing zopectl the 'debug' parameter
on the command line. The 'top-level' Zope object (the root folder) will
be bound to the name 'app' within the interpreter. You can then use
normal Python method calls against app and use the Python interpreter
normally to inspect results::
[chrism@james Trunk]$ bin/zopectl debug
Starting debugger (the name "app" is bound to the top-level Zope object)
>>> app.objectIds()
['acl_users', 'Control_Panel', 'temp_folder', 'browser_id_manager', 'session _data_manager', 'error_log', 'index_html', 'standard_error_message', 'standa rd_html_footer', 'standard_html_header', 'standard_template.pt']
['acl_users', 'Control_Panel', 'temp_folder', 'browser_id_manager', 'session_data_manager', 'error_log', 'index_html', 'standard_error_message']
>>>
Using the Medusa Monitor
NOTE: as of Zope 2.7, the Medusa monitor client is known to have
operational problems due to lack of maintenance. It may work, it
may not. If it doesn't work as advertised, please try 'zopectl
debug' instead.
If you're running Zope with a medusa monitor port, you can connect
and interact via a python prompt with a running Zope session, while
others interact with it over the web.
Some constraints:
o You must connect to a server running on the local host.
o You must authenticate as superuser.
o At the time of writing the superuser password (in the access
file) must be plain text, not encrypted.
To use the monitor, start it from the shell prompt like so (as if
from the Zope root):
python lib/python/ZServer/medusa/monitor_client.py localhost 8099
You'll get back a python prompt. To connect with the running Zope
session:
>>> import Zope
>>> app = Zope.app()
>>> dir(app.Control_Panel.Products)
['ExternalMethod', 'MIMETools', 'MailHost', 'OFSP', 'ZCatalog',
'ZGadflyDA', 'ZSQLMethods', '_objects']
>>>
To see ODB changes caused by access concurrent with your debug
session (eg, those web connections that can still be happening, or
other debug sessions!), you may have to do a bit of magic:
>>> app._p_jar.sync()
To commit changes you make, before exiting, you may have to do
another bit of magic:
>>> import transaction
>>> transaction.commit()
doc/FAQ.txt
View file @ c815993a
Zope Installation Frequently Asked Questions
--------------------------------------------
Installing Zope
1. On certain Unix platforms (usually Solaris) I get a "checksum
......@@ -27,7 +26,7 @@ Zope Installation Frequently Asked Questions
changing the line: do('make') to: do('make -k').
3. I am having trouble building Zope on my OpenBSD system. I get
some wierd compilation errors.
some weird compilation errors.
Make sure you unpack Zope using GNU tar; you will not get any
error messages with OpenBSD's standard tar, but your installation
......@@ -59,7 +58,6 @@ Zope Installation Frequently Asked Questions
Look in the error log for your web server for details of the error.
2. I have installed Zope, and when I go to the URL in my web
browser, I get a password prompt. Although I type in the correct
username and password, I keep getting prompted. What is going on?
......@@ -74,24 +72,15 @@ Zope Installation Frequently Asked Questions
Zope. See the doc/WEBVSERVER.txt file for information on correctly
configuring your web server to pass authentication information.
3. I have installed Zope, and when I go to the URL in my web
browser, I get a "Connection refused" error.
Probably this means that Zope has failed to start. You should try
to start Zope in the foreground and look for error messages.
On Linux / Unix / OSX, you can do this by giving the command
"./bin/runzope" or "./bin/zopectl fg" in your zope instance
(they are equivalent).
On Windows, navigate to the Zope folder in your Start Menu and
click on "Run Zope in Console". A console window with process
startup information will be displayed.
If there are errors, the last error shown should explain
what went wrong.
You can do this by giving the command "./bin/zopectl fg" in your
Zope instance. If there are errors, the last error shown should
explain what went wrong.
4. When I go to a URL for an application that isn't running, it
takes quite a while to startup. Why is that?
......@@ -101,21 +90,7 @@ Zope Installation Frequently Asked Questions
take a while. Packing your Zope database at regular intervals
can reduce startup time.
5. I have Zope with the Oracle Database adapter installed, and can't
get it running. Why?
If you have Oracle installed, you need to ensure that the
environment variable "ORACLE_HOME" is in the environment of
the running application. You can do this by adding a line to
the <environment> section of etc/zope.conf, such as:
<environment>
ORACLE_HOME /foo/bar/
</environment>
6. I have forgotten the only password used to access the site or
5. I have forgotten the only password used to access the site or
I have modified the security settings in such a way that even
I can't get access. How do I fix it?
......@@ -133,8 +108,8 @@ Zope Installation Frequently Asked Questions
As the emergency user, you are allowed to create user folders
and user accounts as well as adjust security settings but you
are not allowed to create objects like DTML methods or folders.
This is a safety precaution.
are not allowed to create objects like folders. This is a
safety precaution.
See more details in the file SECURITY.TXT.
......@@ -174,80 +149,30 @@ Zope Installation Frequently Asked Questions
Upgrading from Earlier Versions of Zope
1. How can I upgrade to Zope 2.8?
1. How can I upgrade to the latest Zope 2 version?
The usual procedure when installing a new version of Zope is:
- Create a new instance (see doc/INSTALL.txt).
- Copy the var/Data.fs file from your old instance into your
new instance's var/ directory.
- Create a new environment (see doc/INSTALL.txt).
It is best to do this while the old instance is not running;
alternatively, you can use repozo.py as described at
http://www.zope.org/Wikis/ZODB/FileStorageBackup
to make a live backup, then create a new Data.fs from that
backup in your new instance.
- Include your application code in the environment.
Keep your old Data.fs in the old instance as a backup.
- Copy the Products and Extensions directories from your old
instance into the new instance.
Leave the old instance directories intact as a backup.
- Copy your database files, (often var/Data.fs) from your old
environment into your new environment's var/ directory.
Only do this while the old database files are not in use.
- Update etc/zope.conf with any changes you made in your
old instance. (Likewise for zeo.conf if you are using zeo.)
- Start the new instance. (Be sure the old instance is not running.)
- Update any ZCatalogs as described below.
- Update any Python Scripts. This is not strictly necessary,
but it will make Zope restart somewhat faster. Visit this URL
in your browser:
old environment.
http://.../manage_addProduct/PythonScripts/recompile
- Start the new application process. (Be sure the old process
is not running.)
2. After moving my old Data.fs to Zope 2.8 I get an
"AttributeError, _length" when trying to use the ZCatalog?
In Zope 2.8 we cleaned up the index implementations and therefore
you need to migrate every single ZCatalog manually.
Notice: **YOU SHOULD BACKUP YOUR var/Data.fs file before starting
the migration**, see http://www.zope.org/Wikis/ZODB/FileStorageBackup
for backup instructions.
To perform the migration:
- go to the ZMI
- click on your ZCatalog instance (or portal_catalog inside
your CMF or Plone instance)
- you will get an "AttributeError, _length"...don't panic
- call the "manage_convertIndexes" method of the ZCatalog
(by replacing the "manage_main" part of the URL with
"manage_convertIndexes")
- depending on the size of your ZCatalog the migration may
take a while
- after the conversion a message will appear: "Indexes
converted and reindexed"
3. CMF doesn't work!
2. CMF doesn't work!
Check that you have a recent stable version of CMF.
As of Zope 2.8.0, you need at least CMF-1.4.8.
CMF is available at http://www.zope.org/Products/CMF/
4. Plone doesn't work!
3. Plone doesn't work!
All Plone versions require a certain Zope version.
Check the Plone release informations on http://www.plone.org
......@@ -255,7 +180,6 @@ Zope Installation Frequently Asked Questions
General
1. My browser is giving a message, 'Sorry, an error occurred.'
How do I find out what the real error is?
......@@ -271,12 +195,11 @@ Zope Installation Frequently Asked Questions
In general, error_log will show the *traceback* for errors.
This traceback explains the error message.
Occassionally you won't see any error message. Rather, the HTML
Occasionally you won't see any error message. Rather, the HTML
source will contain the last good HTML returned by the request
before the error occurred. This is due to caching by the
browser. Clear your cache and view the HTML source again.
2. I'm using Python 2.x and I'm having a problem ...
The correct version of Python should always be automatically detected
......
doc/HELPSYS.txt deleted 100644 → 0
View file @ c4eb640d
Zope Help System
The Zope Help System provides context-sensitive on-line help for
Zope users. The system is flexible and can provide help for
Python Zope Products.
In the future the Help System will be expanded to provide additional
help including API documentation.
Using the Help System
Every standard Zope management screen should include a help button
which provides access to help for that screen.
Additionally all the installed help topics can be browsed and
searched.
Architecture
The Help System is based around Zope Products. When a product is
installed, its help objects are installed along with it. All help
content is associated with a product.
Help content is provided by 'Help Topic' objects. These objects live
inside Product folders within a special container object called a
'Product Help' object. When you browse a Product folder in the
Control Panel you will see these 'Product Help' objects and their
'Help Topics'.
In general you get access to the Help System through the help system
object which has methods for drawing help buttons. This object lives
in the Zope application object and has an id of 'HelpSys'.
Writing Help for Python Products
To support help your Python product needs to register help topics
during product registration, and it needs to indicate which help
topics should be associated with which management screens.
Registering Help Topics
To register help topics use the 'registerHelp' method on the
ProductContext object. For example::
def initialize(context):
...
context.registerHelp()
This method will create help topics for all files found in the
'help' subdirectory of the product. Supported file types include:
.html, .htm, .txt, .stx, .dtml, .gif, .jpg, .png. Appropriate
classes of help topics are used depending on the suffix of the
help files.
If you want more control over how your help topics are created you
can use the 'registerHelpTopic' method that takes an id and a help
topic object as arguments. For example::
from mySpecialHelpTopics import MyTopic
def initialize(context):
...
context.registerHelpTopic('myTopic', MyTopic())
Associating Help Topics with Management Screens
The chief way to bind a help topic to a management screen is to
include information about the help topic in the class's
'manage_options' structure. For example::
manage_options=(
{'label':'Edit',
'action':'editMethod',
'help':('productId','topicId')},
)
In this example, 'productId' refers to the name of the Zope
Product in which the class is defined, and 'topicId' refers to the
id of the Help Topic associated with this management view.
When Zope draws the management view it will automatically include
a help button pointing to the right help topic if you provide this
information in the 'manage_options' structure.
Note: sometimes Zope gets confused and defaults to highlighting
the first management tab in place of the correct one. To fix this,
set the 'management_view' variable to the name of the correct
view. If the wrong view is hilighted, then the wrong help button
will be drawn.
To draw a help button on a management screen that is not a view,
use the 'HelpButton' method of the 'HelpSys' object like so::
<dtml-var "HelpSys.HelpButton('productId', 'topicId')">
This will draw a help button linked to the specified help topic.
If you prefer to draw your own help button you can use the helpURL
method instead like so::
<dtml-var "HelpSys.helpURL(
topic='productId',
product='topicId')">
This will give you a URL to the help topic. You can choose to draw
whatever sort of button or link you wish.
\ No newline at end of file
doc/INSTALL.txt
View file @ c815993a
......@@ -15,12 +15,12 @@ Prerequisites
System requirements when building from source
- A supported version of Python, including the development support if
installed from system-level packages. Supported versions include::
installed from system-level packages. Supported versions include:
o 2.4.x, (x >= 4)
* 2.5.x, (x >= 4)
* 2.6.x
o 2.5.x
- Zope needs the Python ``zlib`` module to be importable. If you are
building your own Python from source, please be sure that you have the
headers installed which correspond to your system's ``zlib``.
......@@ -145,7 +145,7 @@ by directing your browser to::
http://yourhost:8080/manage
.. where 'yourhost' is the DNS name or IP address of the machine
where 'yourhost' is the DNS name or IP address of the machine
running Zope. If you changed the HTTP port as described, use the port
you configured.
......@@ -165,22 +165,11 @@ start. You can access the Zope Book at:
http://www.zope.org/Documentation/Books/ZopeBook
Integrating Zope With An Existing Webserver
--------------------------------------------
Zope doesn't require any existing webserver to run, but you can
integrate it with other webservers as necessary. See the
``doc/WEBSERVER.txt`` file for more information about configuring Zope
with an existing web server. There is also information about integrating
Zope with existing webservers on the Zope.org website.
Troubleshooting
---------------
- This version of Zope requires Python 2.4.4 or better, including
2.5.x. It may run with Python 2.6.x, although this configuration
is not supported in this version of Zope. It will *not* run with
Python 3.x.
- This version of Zope requires Python 2.5.4 or better, including
2.6.x. It will *not* run with Python 3.x.
- The Python you run Zope with *must* have threads compiled in,
which is the case for a vanilla build. Warning: Zope will not run
......
doc/PLATFORMS/AIX.txt deleted 100644 → 0
View file @ c4eb640d
from Thiebaut Champenier
"python wo_pcgi.py" doesn't build the extensions correctly due to
linking problems. To fix it, I just SymLinked ld_so_aix, makexp_aix
and python.exp (found in <python-build>/Modules/) into each of the
dirs in <Zope-build>/python/lib that contain .c files... and it
worked just great. But I'm sure it's not the best solution
from Wolfgang Roesner (reporting segfaults and a fix)
The default stack size for a pthread on AIX (at least in my
configuration) is 96kB. On Solaris it's 1M. As soon as I explicitly
set the initial stack size to 1M the problem went away and it
appears as if Zope is up and running.
Unfortunately I really had to change "thread_pthread.h" in Python
which obviously is not a nice thing to do as I now have a need for
my own private version of Python. But at least I have a running
version of Zope on AIX.
doc/PLATFORMS/BSD.txt deleted 100644 → 0
View file @ c4eb640d
Steps to building python for use with Zope on FreeBSD to avoid
segmentation faults (by Andrew Sawyers for Pythons up to 2.3).
The default thread stack size for FreeBSD is too small; when building
Python for use with Zope it is often necessary to increase the thread
stack size to avoid segmentation faults. There are two ways which you
can increase the default python thread stack size.
Way #1: In your Python source directory:
* >cd Python
* >edit thread_pthreads.h
at the top of the header file, add #define THREAD_STACK_SIZE 1000000
* >save
* >cd ..; ./configure
Way #2: In your Python source directory:
* >./configure
* >make OPT="-DNDEBUG -g -O3 -Wall -Wstrict-prototypes -DTHREAD_STACK_SIZE=1000000"
Passing in the define or adding the define to your source solves all
experiences I have experienced with Zope segfaulting while running on
my FreeBSD platforms.
doc/PLATFORMS/README.txt deleted 100644 → 0
View file @ c4eb640d
This directory is to collect notes that people send us on using Zope
on Platforms that we (Digital Creations) don't have and can't support
directly.
doc/RESTRUCTUREDSTEXT.txt deleted 100644 → 0
View file @ c4eb640d
Integration of reStructuredText (reST) in Zope:
Zope 2.7 or higher integrates reST as part of the Python
docutils package. The syntax of reST is defined under
http://docutils.sf.net/spec/rst/introduction.html
Usage inside DTML:
<dtml-var rest-document fmt="restructured-text">
Usage inside ZPT:
<span tal:content="structure python: modules['Products.PythonScripts.standard'].restructured_test(rest_txt)" />
Usage inside PythonScripts:
from Products.PythonScripts.standard import restructured_text
rendered_html = restructured_test(rest_txt)
return rendered_html
Usage inside Zope products:
from reStructuredText import HTML
rendered_html = HTML(rest_txt)
...
Character set issues:
reST processes the reST document internally using unicode. A reST
document is converted using Pythons default encoding to unicode and
converted back from unicode to the default encoding on the output side.
This means you must ensure that Python default encoding is properly.
You can customize the default encoding by creating a file sitecustomize.py
somewhere in yout PYTHONPATH:
import sys
sys.setdefaultencoding("iso-8859-1")
This version of Zope also includes the ZReST product written by Richard Jones.
ZRest is a standalone Zope product to handle reStructuredText documents.
doc/UNITTEST.txt deleted 100644 → 0
View file @ c4eb640d
Zope Unit Testing
Zope Testing
If you encounter a directory named "tests" in a package within
within the Zope source code, it most likely indicates that the
directory contains test code used to ensure that the code owned by
the package works as it was designed. Many of the test scripts
contained within Zope "tests" directories will be scripts which
contain "unit tests".
What Unit Tests Are
A "unit" may be defined as a piece of code with a single intended
purpose. A "unit test" is defined as a piece of code which exists
to codify the intended behavior of a unit and to compare its
intended behavior against its actual behavior.
Unit tests are a way for developers and quality assurance engineers
to quickly ascertain whether independent units of code are working as
expected. Unit tests are generally written at the same time as the
code they are intended to test. A unit testing framework allows a
collection of unit tests to be run without human intervention,
producing a minimum of output if all the tests in the collection are
successful.
What Unit Tests Are Not
It's very useful to define unit tests in terms of what they are
not. From the "Extreme Programming Enthusiast" website
(http://c2.com/cgi/wiki?UnitTestsDefined)::
Unit tests are not:
- Manually operated.
- Automated screen-driver tests that simulate user input (these
are "functional tests").
- Interactive. They run "no questions asked."
- Coupled. They run without dependencies except those native to
the thing being tested.
- Complicated. Unit test code is typically straightforward
procedural code that simulates an event.
Unit Testing Frameworks
A unit testing framework is generally employed to collect related
unit tests together in order to make it easier to run them as a
group. When used with a unit testing framework, unit tests live
outside of the modules of code they're intended to test.
How Unit Tests Help In The Development Process
Unit tests should be written at the same time the code they test is
written. A short, healthy cycle of "code/write test/run
test/repeat" can help a developer code more quickly by reducing
"backtracking" effort and by helping the developer focus on the
actual problem at hand. Additonally, the unit tests generated at
initial development time can serve as later assurance that
maintenance and refactoring performed on code does not break any of
its intended functionality or behavior. The results of unit tests
may additionally be used as a metric by quality assurance personnel
along with the results of other tests to gauge code quality before
before it is "shipped."
Basic Unit Testing Philosophies
Write unit tests at the same time that you write the code.
Nothing's worse than being faced with the prospect of writing tests
against a huge chunk of existing code because you "have to."
Writing unit tests post-facto can be boring and also robs you of the
main benefits that unit testing can provide. Writing unit tests at
the same time you write the code helps you focus on the task at
hand. Writing unit tests in conjuction with code can be fun and
satisfying, and can help you improve the quality of your code while
its goals are fresh in your mind. Used properly, unit testing may
also help you write code faster, because you will need to
"backtrack" less. Some "Extreme Programming" enthusiasts posit that
you should write a test before you write its associated code, and
then develop the code until it passes the test.
Unit tests should be developed against as small and specific a
subset of a system's or subsystem's functionality as possible. For
instance, a one unit test may test that a unique id generator
produces ids of a specific length, while another unit test in the
same group may ensure that a thousand ids from the same unique id
generator do not contain the same value. Writing a single unit test
which tests a broad swath of a system's capabilities is
counterproductive, because it does not allow for a fine enough
granularity when attempting to figure out "what went wrong,"
requiring the developer to "backtrack". Unit testing is capable of
helping to help reduce backtracking, but only if used properly.
A unit test does not produce any output unless it fails. If a unit
test fails, it should print something useful, but short. A unit
test should never fill the screen with output or otherwise produce
output that needs to be manually examined for "clues". This is the
realm of other testing methodologies. If unit tests are written at
sufficiently granular level, it is often enough just to know the
name of the unit test that failed.
"It is better to have tried to test and failed than to not have
tried to test at all" aka "test the riskist things first." If the
prospect of writing a series of unit tests for an existing system
seems daunting, it's important to remember that no matter how many
unit tests you write, you cannot prove that your software does not
have bugs. Therefore, you cannot possibly test every case while
developing. You should plan to write tests against code based on
the risks involved in not testing that code. Don't feel that you
need to write a test case for every "corner case" (although do try
to hit the riskiest ones). In the worst case, it's better to have a
test module with one lonely unit test in it than none at all.
"Test fixtures" are employed by unit tests. Test fixtures are bits
of state and environment that allow the unit test to perform its job
properly. An example of a test fixture might be a file, an instance
of a class, or a row in a database table. Any part of the
environment needed by a unit test besides the unit testing framework
itself is considered a test fixture.
In general, the common fixtures required by individual tests in a
testing group should be more or less identical. If the fixtures
needed by a single test are radically different than the fixtures
required by the rest of the tests, or if the test does not require
the fixtures provided to the other tests, it probably belongs in
another (or its own) group of tests.
When a unit test in a group modifies the state of a test fixture,
the test fixture should be restored to a known state before the next
unit test in the group is run. Often, this means "rolling back"
changes to a transactional database or restoring the state of a
string so the next unit test can inherit a known state of the same
fixtures. The unit testing framework has capabilities which allow
you to automate most of this work by providing a "set up" method
which gets called before each test is run and a "tear down" method
that gets called after a test is finished.
Unit tests should play nicely with the unit testing framework they
employ. Unit tests should not call "sys.exit()" or do similar
things which effect their ability to be run as part of a group of
tests. The testing framework attempts to deal with misbehaved unit
tests, but it's better just to make them behave nicely in the first
place.
Unit tests should "grow" with the code that they're intended to
test. For example, if a group of unit tests is intended to verify
the behavior of all of the routines within a module, additional unit
tests should be added to the test group when new functionality is
added to that module.
Writing Unit Tests For The Zope Core
If you're writing core code, you probably don't need to listen to
any more of this. :-) The rules for writing tests for Zope core
code are simple:
- The testing code should make use of PyUnit
(/lib/python/unittest.py). Instructions for using PyUnit are
available at http://pyunit.sourceforge.net.
- Tests must be placed in a "tests" subdirectory of the package or
directory in which the core code you're testing lives.
- Test modules should be named something which represents the
functionality they test, and should begin with the prefix "test."
E.g., a test module for BTree should be named testBTree.py.
- An individual test module should take no longer than 60 seconds
to complete.
Writing Unit Tests For Applications Based On Zope
Zope uses the PyUnit unit testing framework, the documentation for
which is available at http://pyunit.sourceforge.net. The
lib/python/unittest.py module is the framework. You may establish
your own conventions for naming and placement of test modules, but
using the same rules as for Zope Core is recommended, and the
standard used by most.
Writing unit tests against applications based on Zope can be
difficult. Zope is a collection of related modules, some with
non-trivial interdependencies. Running its code successfully also
in some cases depends on state provided only in the context of a web
request, so calling Zope methods directly may not work as you
expect. If you're not intimately familiar with Zope, implementing
unit tests can be fustrating. For example, for the common case,
before you are able to write code which tests a Zope SQL Method, you
must establish a test fixture which represents your entire Zope
site.
This is made easier by the ZopeTestCase package, included with
Zope from Zope 2.8. It is located in the directory
lib/python/Testing/ZopeTestCase and the documentation in the
doc subdirectory.
In principle, subclassing from Testing.ZopeTestCase.ZopeTestCase
instead of subclassing from unittest.TestCase will mean that you
have a zope test fixture set up for you.
There are several examples of how to use ZopeTestCase in the
ZopeTestCase directory.
If you don't want to do that, you can still set up the fixture
yourself.
- add the 'lib/python' directory of your Zope installation to the
PYTHONPATH (via sys.path.insert())
- 'import ZODB' (may not be required, but just put it in for good measure)
- 'import Zope'
- 'app = Zope.app()'
- operate on the Zope instance space by calling methods from the
root object (bound to 'app'), e.g.:
app.acl_users.manage_addUser(<parameters>)
- a transaction will not be committed to the Zope object database
until you call "transaction.commit()",
so changes made to the ZODB are not visible to succeeding tests
unless that function is called explicitly.
- As a part of your tearDown, make sure to call
"app._p_jar.close()". This closes the database connection
cleanly.
For more information on operating on Zope programatically by
"importing" it, see Michel Pelletier's "The Debugger Is Your
Friend" at
http://www.zope.org/Members/michel/HowTos/TheDebuggerIsYourFriend
Running the unit tests
The basic command to run unit tests is::
bin/python bin/test.py --config-file etc/zope.conf
or on windows::
C:\Path\To\Python.exe bin\test.py --config-file etc\zope.conf
This will run all unit tests in lib/python and below (that is,
it will run the zope core unit tests.
To run the unit tests located in the Products directory you need to
add two parameters --libdir Products so that test.py will look
for modules in the Products directory, and --dir Products to look
for tests in the Products directory and below. You can of course
specify --dir even closer, so a typical command to run the tests
for the "Myproduct" product would be
bin/python bin/test.py -v --config-file etc/zope.conf --libdir Products \
--dir Products/Myproduct
This is rather long, and on unix you can shorten this to::
bin/zopectl test --dir Products/Myproduct
These commands are equivalent. bin/zopectl will just run test.py
with some useful defaults for you::
-v increases verbosity. You can add -vv for even more output.
--config-file etc/zope.conf reads in the Zope configuration file,so that
important paths are set up.
--libdir Products tells test.py to include Products as a module path and
to include the tests there.
To see the rest of the command options you can run it with --help::
bin/zopectl test --help
The test output should look something like this::
Running unit tests at level 1
Running unit tests from /home/zope/Products/CMFCore/tests
Parsing /home/zope/etc/zope.conf
.....................
----------------------------------------------------------------------
Ran 21 tests in 0.130s
OK
Speeding up the tests
Not all unit tests will need a zope test fixture. If you have many
tests that do not need it, it can be a good idea to separate them
into different test files, so that you can run the tests that do not
need a fixture separately, since setting up the fixture takes time.
This will not save you time when running all your tests, but it can
save time while developing, since you can skip loading Zope when
running some tests (also see Functional testing, below).
Also, one of the most effective tools for facilitating unit
testing is ZEO (http://www.zope.org/Products/ZEO). ZEO is an
open-source clustering solution for Zope which makes it possible to
front-end a single "storage server" which manages a Zope object
database with multiple Zope clients that run a "client storage".
The reason ZEO is interesting for unit testing is mostly an
unintended side-effect of how it works as compared to Zope without
ZEO. Zope without ZEO commonly uses a "FileStorage" to hold its
object database. When Zope is started with a FileStorage, the
FileStorage code processes an "index" file. This takes time. Zope
using a ClientStorage as with ZEO does not process an index file,
making startup faster. Fast startup of Zope is critical to
effective unit testing. It is recommended that you implement ZEO if
you're heavy in to unit testing, as it really speeds things up.
It's not strictly required, however.
Emulating requests
Sometimes, just importing Zope isn't enough. For example, it's
often not possible to obtain the results of a DTML or Python method
by simply calling it from your running code without doing lots of
trickery by establishing fake REQUEST object to pass in to it, as
Zope expects a REQUEST object to exist in the context of a web
request (which a DTML method is somewhat logically designed to
serve).
There are two ways of doing this. The old and complicated way is
using Zope.debug() (documented below), but the new way is known
as "functional tests". Support for this is included in ZopeTestCase,
see lib/python/Testing/ZopeTestCase/doc/FunctionalTesting.stx for
more information. It does almost the same thing as the "debug"
method, but it returns a RESPONSE object, so you can easily check
that the output is correct, and not only that the request finished
without raising any exceptions.
Zope.debug()
Zope.debug() allows you to simulate a web request, which
generally provides all the state necessary to run methods which
depend on web requests, and returns the results of the web request
as it would be seen in by a web browser. To use the Zope debug
method, do the following:
- add the lib/python path to your PYTHONPATH (via sys.path.insert())
- 'import ZODB'
- 'import Zope'
- 'Zope.debug('/a/url/representing/a/method?with=a?couple=arguments',
u='username:password', s='silent', e={'some':'environment',
'variable':'settings'})
The "silent" option causes Zope not to print anything. You can set
your python's stdout to a file or a file-like object to capture the
output if you do not set the silent flag.
Administrivia
Unit test scripts found in the Zope source code make use of Pythons
PyUnit unit testing framework, written by Stephen Purcell (thanks
Stephen!). PyUnit is based on the JUnit testing framework for Java
(written by Kent Beck and Erich Gamma), which in turn was based on a
testing framework designed for Smalltalk (also written by Kent
Beck).
Unit testing is a primary tenet of "Extreme Programming", a software
development methodology designed to faciliate the rapid production
of high quality code with a minimum of developmental ceremony. For
more information on unit tests as they relate to Extreme
Programming, see http://c2.com/cgi/wiki?UnitTestsDefined. Although
Zope Corporation has not embraced the entire spectrum of Extreme
Programming methodologies in its software development process, we've
found unit tests a way to speed development and produce
higher-quality code.
ZopeTestCase was written by Stefan H. Holek, and is included with
Zope from Zope 2.8. (Thanks Stefan!)
doc/WEBSERVER.txt deleted 100644 → 0
View file @ c4eb640d
Using Zope with an existing web server
--------------------------------------
While Zope comes with a web server, you may wish to use it with an
existing web server. Use Persistent CGI (PCGI) or FastCGI to allow
your existing web server to work with Zope on Unix and Windows.
Roughly, PCGI is a protocol for translating CGI requests from a web
server into Zope requests. CGI requests are traditionally one shot
events; the web server handles a request for a CGI script by
spawning a new process to handle the requests, returning the results
of the request when the process dies.
Zope is a long running process, which means that it does not start
up and die on each request like traditional CGI programs. If it
did, each request would take far too long due to the time to start
and stop an application server like Zope. Thus, PCGI is one of the
options for gatewaying from the separate CGI processes to the Zope
long running process.
FastCGI is very similar to PCGI. Where PCGI has a "wafer-thin"
external CGI program to connect Apache and Zope, FastCGI has an
Apache module. This saves the so called "fork tax" which is incurred
when Apache forks to execute the PCGI CGI program.
Using Zope in multi-threaded mode with ZServer
----------------------------------------------
ZServer is a general purpose TCP server for publishing Zope objects
over various transport protocols. For Zope to run multi-threaded,
you must run ZServer.
ZServer is based on Sam Rushing's Medusa software. The benefit of
using Medusa as the ZServer core is that it is not protocol specific
(Medusa provides libraries to program for any protocol) and it is
easily extensible. Because Medusa is written in Python, is
extremely high performance by design, and comes with an HTTP and FTP
server, we chose it for the Zope core.
It is not necessary, however, for ZServer to actually listen for
incoming HTTP requests. If you want Apache to do the actual
listening and serving, then you can use ZServer's PCGI or FastCGI
components to communicate with Apache.
PCGI
PCGI is deprecated and should not be used anymore.
To install PCGI, please get the PCGI support package from the Zope
2.6 tarball (it no longer ships with Zope 2.7), and read the
pcgi/README file from that package.
To run ZServer with PCGI, you must configure Zope with a PCGI
server. You can do this by adding a section to the etc/zope.conf
file like this::
<persistent-cgi>
address /path/to/PCGI/resource/file
</persistent-cgi>
Note, you must have gone through the directions in 'INSTALL.txt' for
this to work.
This command will cause Zope to start with a PCGI server as well as
any other servers you specify in the zope.conf file. For PCGI to
work, the webserver and Zope must agree on a PCGI resource file.
Now the Zope long running process is started up, and the PCGI
component is loaded and ready to receive CGI requests from your
webserver.
The installation process should create a 'Zope.cgi' PCGI file. Copy
the 'Zope.cgi' file to your web server's 'cgi-bin' directory.
On Unix you can also create a symbolic link to 'Zope.cgi' from your
cgi-bin directory. For example::
ln -s /home/amos/Zope/Zope.cgi /usr/local/apache/cgi-bin/Zope
At this point you should perform any other steps you web server
requires to install and configure a CGI script.
Note: For more information on PCGI check out Jeff Bauer's "PCGI pages",
http://starship.python.net/crew/jbauer/persistcgi/.
When your Zope.cgi file is correctly configured as a CGI script with
your web server, you are ready to access Zope through the web. You
should point your browser at:
'http://youmachine.example.com:8998/cgi-bin/Zope.cgi/manage'
(Your URL maybe be different depending on how your web server is configured.)
You should be prompted to enter a username and password. Enter the
Zope "super manager" name and password.
Note: Apache requires some tricky configuration to get it to pass
the HTTP authentication header information to Zope. See the section
'Zope authentication with existing web servers'.
There is an Apache module for Zope/PCGI:
http://www.zope.org/Members/phd/mod_pcgi2/
One can easily compile and configure it. It passes the HTTP
authentication header and other environment variables. It supports
virtual hosting.
FastCGI
FastCGI is deprecated and should not be used anymore.
FastCGI is relatively easy to set up if you have installed an Apache
module before. If you haven't, don't worry, it isn't difficult. It
comes with straightforward instructions. You will need to download
the mod_fastcgi module from FastCGI.com:
http://www.fastcgi.com/
A version more recent than 2.2.2 is needed.
Extract the archive and follow the directions in its 'INSTALL' file.
Using the 'DSO' method is usually easiest.
Next, Zope must be set up to use FastCGI. You must decide whether
you want to use FastCGI via a Unix domain socket or a TCP port.
You will have to use a TCP port if you are using a Win32 box, or any
other operating system that does not provide Unix domain sockets
(sockets in the filesystem). It is also the method you must use if
Apache and Zope reside on different computers. You will need to
select a port number. This is arbitrary, but it must not already be
in use, and if you are not the super-user, it must be a sufficiently
high number. For illustrative purposes, I will use 8889.
Unix domain sockets do not open a TCP port, which may be significant
in some tight-security situation, but it requires slightly more
setup, and so it is slightly less fool-proof. You will need to
select a location and filename for the socket. Likely options are
'/tmp/zope.soc' or within Zope's 'var' directory. Make sure that
both Zope and Apache will have adequate file permissions to read and
write to the socket. For illustrative purposes, I will use
'/tmp/zope.soc'.
This can be configured by adding a fast-cgi section in your
etc/zope.conf file. The section should look like this for a TCP
port::
<fast-cgi>
address localhost:8889
</fast-cgi>
To use a Unix domain socket instead, specify the path of the socket
file instead of a [hostname:]port::
<fast-cgi>
address /tmp/zope.soc
</fast-cgi>
You can start Zope at this point by running the 'runzope' script::
$ ./bin/runzope
Next, Apache must be set up to pass FastCGI requests to Zope. This
is done with a 'FastCgiExternalServer' directive in Apache's
httpd.conf. By using 'FastCgiExternalServer' we are telling FastCGI
that we'll be launching and killing the long-running process
manually. It goes at the beginning of 'Section 2'. This directive
will look like this for a TCP port configuration::
FastCgiExternalServer /PATH/TO/apache/htdocs/zope \
-host localhost:8889 \
-pass-header Authorization
...or like this for a socket configuration::
FastCgiIpcDir /tmp
FastCgiExternalServer /PATH/TO/apache/htdocs/zope \
-socket zope.soc \
-pass-header Authorization
The FastCgiIpcDir directive is needed to tell FastCGI where to find
the socket file. By default, FastCGI will look in /tmp/fcgi. You
*cannot* specify a full path with the '-socket' option, only a
filename within the FastCgiIpcDir.
The first argument after the directive name is confusing. Apache
maps URLs to directories and files within your 'DocumentRoot'. You
must specify the name of a file within your DocumentRoot directory,
but that file need not (and probably should not) actually exist.
When Apache tries to serve that file, it will instead send the
request through FastCGI. Make sense?
Say, for instance, you want zope to be accessible from this URL:
http://myserver.org/myzope
Suppose further that you have Apache installed at /usr/local/apache.
The directive would have to look like this::
FastCgiExternalServer /usr/local/apache/htdocs/myzope \
...
...
The next argument depends on whether you are using a TCP port or a
socket. Note that the -host (port) argument requires the hostname.
In the example, it's the same host as Apache runs on, but this need
not be the case. If you are using a socket, make sure Apache has
the appropriate privileges to find it.
The last argument, '-pass-header Authorization', tells FastCGI to
pass the Authorization headers to Zope. Without this, you would not
be able to use the Zope web management interface, or anything else
that requires authorization. (Note: This feature was not in
mod_fastcgi 2.2.2)
One more item must be added to the httpd.conf. Below the
'FastCgiExternServer' directive, enter the following::
<Location /zope>
SetHandler fastcgi-script
</Location>
...changing '/zope' as appropriate. Using the
'http://myserver.org/myzope' example from above, it would look like
this::
<Location /myzope>
SetHandler fastcgi-script
</Location>
This creates a special case for the location specified, telling
Apache to let FastCGI handle the request.
That is all that is needed. Make sure Zope is running, start or
restart Apache, and you are finished.
Using Zope in single-threaded mode with pcgi_publisher
------------------------------------------------------
The installation process should create a 'Zope.cgi' PCGI file. Copy the
'Zope.cgi' file to your web server's cgi-bin directory.
On Unix you can also create a symbolic link to 'Zope.cgi' from your cgi-bin
directory. For example::
ln -s /home/amos/Zope/Zope.cgi /usr/local/apache/cgi-bin/Zope
At this point you should perform any other steps you web server
requires to install and configure a CGI script.
Note: For more information on PCGI check out Jeff Bauer's "PCGI pages",
http://starship.python.net/crew/jbauer/persistcgi/.
When your Zope.cgi file is correctly configured as a CGI script with
your web server, you are ready to access Zope through the web. You
should point your browser at:
'http://youmachine.example.com:8998/cgi-bin/Zope.cgi/manage'
(Your URL maybe be different depending on how your web server is
configured.)
You should be prompted to enter a username and password. Enter the Zope
"super manager" name and password.
Zope authentication with existing web servers
---------------------------------------------
Zope normally performs both authentication and authorization of
users. Some web servers don't pass authentication information to
CGI scripts. If you keep getting rejected when you try to access
Zope through the web with the "super manager" user name and
password, there is a good chance that your web server is not passing
authentication information to Zope.
Getting Apache to pass authentication headers
Before attempting to use your own Apache with Zope, it is highly
recommended that you look at Zap. Zap is a preconfigured and
precompiled version of Apache for Linux that drops right into Zope
with no hassles. Even if you want to use your own Apache, or if
you use it on a different platform than Linux, it is very helpful
to have Zap's 'httpd.conf' file to guide you through configuring
Apache.
Zap can be found on the Zope website at:
http://www.zope.org/Download/Releases/Zap-1.1.0
If you are using Apache you will need to convince Apache to pass
authentication headers to Zope. The easiest way to do this with
Apache 1.3 and above is to use mod_rewrite. Here is an example of
configuration information which you would place in an Apache conf
file::
# Zope configuration maps /Zope/ to the Zope.cgi CGI script
RewriteEngine on
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^/Zope(.*) /usr/local/apache/cgi-bin/Zope.cgi/$1 [e=HTTP_CGI_AUTHORIZATION:%1,t=application/x-httpd-cgi,l]
Note that the RewriteRule should be one long line, and that the last
character is the letter l, not the number 1.
For Apache servers version 1.3b4 and above, there is an alternate way
to get the server to pass through authorization headers, but you must
have the ability to recompile your Apache server binary. If you pass
the flag -DSECURITY_HOLE_PASS_AUTHORIZATION when compiling the server,
the resulting Apache binary will allow authorization headers to pass
through to CGI programs and you can avoid using the Rewrite rules
described above.
Allowing your server to handle authentication itself
Sometimes you may prefer to handle authentication outside Zope, for
example if your web server already does complex authorization, or
if it seems too difficult to convince it to pass authentication
information to Zope.
As of 1.9, Zope began supporting a mode that allowed the web
server to handle authentication. The 'REMOTE_USER' environment
variable is then matched to the identity of a user object in Zope.
The following provide step-by-step instructions for setting this
up in Apache, allowing both the Zope "super manager" defined in
the Zope 'access' file and users defined in Zope User Folders to
be authenticated via the web server.
Get Apache to authenticate /cgi-bin/Zope
Add a directive in your Apache configuration file such as::
<Location /cgi-bin/Zope/>
AuthType Basic
AuthName Zope-realm
AuthUserFile /usr/local/etc/httpd/conf/ru_users
require valid-user
</Location>
Then send Apache a '-1' signal to tell it to re-read its
configuration files.
*Note*: The above presumes that '/cgi-bin/Zope' has been made
executable by some other Apache directive in the configuration
file.
Ensure Apache has 'superuser'
Using Apache's tools for managing a user database, make
sure that the 'AuthUserFile' defined above has a valid user
called 'superuser'.
Get Zope to use Apache's authentication
Change Zope's access file to contain just the superuser
id followed by a colon, as in::
superuser:
Note that this can be any value, including spaces. The only
restriction is that the value must match a user defined in
Apache's user database.
N.B.: removing the password in the access file also enables
access to the monitor for any user connecting through
the localhost interface -- DISABLE THE MONITOR if using
this option on any box which allows untrusted logins.
Shut down Zope by doing::
kill `cat var/Main.pid`
from the Zope directory.
Configure Zope
At this point you are able to log in using the "superuser"
identity. If you want other people defined in the Apache user
database to have identities in Zope, you need to add them to
a User Folder (the object whose ID is acl_users). Either click on
the pre-defined acl_users in the top folder or add a User Folder
object to a subfolder.
Specific web servers
Apache
* As mentioned above, Apache does not pass authorization
information to CGI scripts by default. See above for information
on how to deal with this situation.
* There is Apache module to support PCGI (mod_pcgi2). See the
section "PCGI" above for details.
Netscape Servers
* Like Apache, Netscape does not pass HTTP Authorization
information to CGI scripts. We have a plugin at our website
that addresses this. http://www.zope.org
* Alternatively, you can allow the web server to perform the
authentication step. See above for more information.
IIS
* You must turn off Windows NT Challenge/Response
authentication. To do this, go to IIS Manager, right-click on
the server, select Service Properties, and deselect *both*
'Windows NT Challenge/Response' and, strangely, Basic
Authentication from the Password Authentication area of the
Service tabbed worksheet.
* IIS kindly throws out PATH_INFO when writing to its logs, so if
you want to log which Zope objects are actually being
accessed, you will need to investigate an ISAPI filter
* An ISAPI module to support PCGI is under development.
* IIS 4.0 throws away Zope's error messages by default. This
behavior can create quite a few problems, including
authentication problems.
Microsoft prides itself on the clear error messages that IIS 4.0
presents, when the user makes a mistake. These error messages
are implemented in the form of Custom Error handlers, that
return a file, or URL to a user when a certain error occurs.
This means, that when you forget to fill in an Id when you want
to create, say, a new SQL Method, Zope's clear error message is
replaced by IIS's totally irrelevant error message. Also, it
completely breaks authentication when the user uses IE5.0 when
trying to log into a secure area of the server. These Custom
Error handlers are enabled by default.
Luckily, the handlers can quite easily be switched off:
Open the IIS website in the Management Console, and navigate to
the folder you put the PCGI executable in. If you named your
Zope installation 'Zope', it will be called
'Zope.exe'. Double-click on that file. A property page will
appear. Select the 'Custom Errors' tab. Now, select every HTTP
Error code in the listbox that doesn't have type 'Default', and
click on the 'Set to Default' button for each one. This will
disable IIS overriding the error message returned by Zope.
Click OK, and voila, Zope is allowed to tell the world what it
thinks went wrong.
doc/WINDOWS.txt
View file @ c815993a
How to build and install Zope from source code on Windows.
----------------------------------------------------------
These instructions appear to work for 2.7 and the trunk:
* Ensure you have the correct MSVC version installed for the
version of Python you will be using.
* Install (or build from sources) Python
http://www.python.org
* Install (or build from sources) the Python for Windows extensions
http://sourceforge.net/projects/pywin32/
* Unpack the Zope source distribution or pull from CVS. Change
to that directory.
* Unpack the Zope source distribution. Change to that directory.
* Execute:
% python.exe inst\configure.py
It should say something like:
>
> - Zope top-level binary directory will be c:\Zope-2.7.
> - Zope top-level binary directory will be c:\Zope-2.12.
> - Makefile written.
>
> Next, run the Visual C++ batch file "VCVARS32.bat" and then "nmake".
......@@ -33,16 +31,6 @@ These instructions appear to work for 2.7 and the trunk:
but they can be ignored. The last message in the build process should be:
> Zope binaries installed successfully.
* If you are running from CVS, the build may fail:
See http://collector.zope.org/Zope/1530
> running install_data
> error: can't copy 'version.txt': no matching files
> NMAKE : fatal error U1077: '"e:\src\python-2.3-cvs\pcbuild\python.exe"' : return code '0x1'
> Stop.
If you see this error, edit setup.py and comment the line referencing
'version.txt'
* Zope itself has now been installed. We need to create an instance. Run:
% python.exe {install_path}\bin\mkzopeinstance.py
......
doc/ZODB.txt deleted 100644 → 0
View file @ c4eb640d
The Zope Object Database, ZODB, version 3.0
ZODB is the next generation of our object database architecture.
It provides a number of advantages over or existing databases:
- Support for concurrency,
- Well-defined storage management interface that will allow many
different storage management strategies to be used, from file
storage, to RDBMS storage, to memory storage,
- More robust file storage format,
- Much better version support and integrations of
versions with the transaction system. For example,
it is possible to commit from one version to another,
to undo version commit and abort, and to use "temporary
versions" to reduce memory use when manipulating large
quantities of data.
- Support for multiple databases in the same object system.
- Support for multi-process storage managers, although the
standard distribution will not include any multiple process
storage managers.
Note: Using ZODB 3 from Python
In ZODB 2, you could access the top-level application object
with::
import Main
app=Main.app
You could then navigate from the top-level object by getting
attributes, calling methods, etc..
In ZODB 3, you get the top-level object like this::
import Zope
app=Zope.app()
... do stuff with objects
# and when you're done:
app._p_jar.close()
You have to import the Zope application module, which uses
ZODB 3 rather than ZODB 2. In ZODB 3, you have to get a
connection to a database before you access an object. The
'app()' function combines opening a connection and getting the
top level object. When your done using the top-level object
(or any objects accessible from it) you can close the database
connection by calling the 'close' method on the '_p_jar'
attribute, which is the database connection. You don't need
to close the connection if you are going to exit Python
without doing any more work.
Don't forget to::
import transaction
transaction.commit()
If you want any changes to made to be saved.
Note: Converting ZODB 2 (aka BoboPOS) data files to ZODB 3.
The bbb.py script in utilities can be used to convert data
files from ZODB 2 to ZODB 3 format::
utilities/bbb.py -f output_file input_file
Here's a example::
utilities/bbb.py -f var/Data.fs var/Data.bbb
You can also convert export files from ZODB 2 by inclding the
-x option::
utilities/bbb.py -x -f output.zexp input.bbe
ZODB 3 and Zope Database Adapters
Most database adapters are *currently* likely to be problematic unless
the underlying extensions and libraries:
- allow multiple simultaneous database connections,
- are thread safe,
- give up the Python global interpreter lock when
making database calls.
This is only a problem when running Zope 2 with multiple
threads.
ZODB 3 Futures
These are features that are lkely to wait for releases after 2.0.
- Multiple database support
- OPTIMIZATION: FileStorage will get a more efficient data
structure for maintaining index information and key methods
in the ZODB framework will move to C.
doc/ZOPE3.txt
View file @ c815993a
Using Zope 3 Components in Zope 2 Applications
Using Zope Components in Zope 2 Applications
Background
Zope 3 is the next major revision of Zope. It is designed to be more
'programmer-centric' and easier to learn, use and extend. Zope 3
introduces an interface-centric component architecture that makes
it easier to develop and deploy components without requiring
developers to learn and understand the entire Zope framework.
Much more information on Zope 3 is available on the Zope 3 area
of the zope.org Website at http://dev.zope.org/Zope3/.
Zope 3 is a separate project from the Zope community aimed at web
development. It is designed to be more 'programmer-centric' and easier
to learn, use and extend for programmers. Zope 3 introduces an
interface-centric component architecture that makes it easier to develop
and deploy components without requiring developers to learn and
understand the entire Zope framework.
As of Zope 2.8, the "Five" project has been integrated into the
Zope 2 core. The "Five" project implements a compatibility layer
that allows many Zope 3 components and patterns to be used in
new and existing Zope 2 applications. This provides a number of
benefits::
- availability of Zope 3 technologies in Zope 2 like the
component architecture and declarative configuration
- you can gradually evolve your Zope 2 projects to better plan
for migration to Zope 3
- you start learning about Zope 3 right now, preparing yourself
better for the future. Since Zope 3 is open to contributions,
you could even influence your future for the better ;)
new and existing Zope 2 applications.
Features
The Five integration layer provides support for Zope 3 interfaces,
Zope Configuration Markup Language (ZCML), adapters, views,
utilities, schema-driven content, and Zope 3 add and edit forms.
utilities and schema-driven content.
Note that the Five layer does *not* attempt to provide a ZMI user
interface for Zope 3 components.
Zope 2.8+ includes the essential Zope 3 packages, so it is not
Zope 2 includes the essential Zope 3 packages, so it is not
necessary to install Zope 3.
Zope 3 Interfaces
Everything in the zope.interface package should work. Zope 3 interfaces
are the foundation of the component architecture, and also the foundation
of schemas.
Historically, Zope 2 has used the ``__implements__`` class attribute for
interface declarations. Zope 2 cannot detect Zope 3 interfaces and the
Zope 3 machinery cannot detect Zope 2 interfaces. This is a good thing,
as Zope 2 has no way to deal with Zope 3 interfaces, and Zope 3 cannot
work with Zope 2 interfaces. This means you can safely make a class
declare both a Zope 2 and Zope 3 interface independently from each
other. It's a rare case where you need this - you're usually better off
just switching to ``implements()`` for your application if possible.
Switching from Zope 2 interfaces to Zope 3 interfaces is easy -- just
make your interfaces inherit from ``zope.interface.Interface`` instead
of ``Interface.Interface`` (or ``Interface.Base``). Next, change all
``__implements__`` to ``implements()``.
You will also have to change any calls to ``isImplementedBy`` and such
in your application to ``providedBy``, as ``isImplementedBy`` has been
deprecated (you'll see the DeprecationWarnings in your Zope log).
ZCML
ZCML is the Zope Configuration Markup Language, an XML application.
Zope 3 code consists of a lot of components that can be plugged together
using ZCML.
If you put a 'site.zcml' in the home directory of your Zope instance,
this is the root of the ZCML tree. An example of 'site.zcml' is in
'site.zcml.in'. If you don't place a site.zcml, Five falls back on
'fallback.zcml'.
ZCML in Zope 2 with Five has a special directive, 'five:loadProducts',
to load the ZCML ('meta.zcml', 'configure.zcml') of all installed
Zope 2 products, if available.
Another special directive, 'five:loadProductsOverrides' is available to
load any overriding ZCML (overrides.zcml) in these products. In the
'overrides.zcml' you can override existing views or adapters, in this
or in other products.
The Five integration layer tries to use the Zope 3 ZCML directives where
possible, though it does sometimes support only a subset of the possible
attributes. It also introduces a few directives of its own under the
``five`` namespace. The supported directives are listed per namespace
in alphabetic order below.
zope ``http://namespaces.zope.org/zope``
========================================
adapter
-------
Hook an adapter factory to an interface.
content
-------
Declare interface and permissions on content object. Declares Zope 2
permissions.
permission
----------
Way to make Zope 2 permissions available to Five, ``title`` is
permission name.
redefinePermission
------------------
Redefine a permission in included ZCML as another one.
service
-------
Declare a global service
serviceType
-----------
Declare a type of service.
skin
----
Declare a skin, consisting of layers.
utility
-------
Declare a global utility.
browser ``http://namespaces.zope.org/browser``
==============================================
page
----
Declare a page view for an interface. Permission is a Zope 2
permission.
pages
-----
Declare multiple page views for an interface. Permissions are Zope 2
permissions.
defaultView
-----------
Declare the name of the view that should be used for the default when
viewing the object; i.e. when the object is traversed to without a view.
defaultSkin
-----------
Declare the default skin used.
interface
---------
Define an interface in ZCML.
layer
-----
Declare a layer.
menu
----
Declare a menu
menuItem, menuItems
-------------------
Declare menuItems
five ``http://namespaces.zope.org/five``
========================================
implements
----------
Make a class declare it implements an interface.
loadProducts
------------
Loads ZCML in all Zope 2 products. First processes all ``meta.zcml``
files, then processes all ``configure.zcml`` files.
loadProductsOverrides
---------------------
Loads overriding ZCML in all products (``overrides.zcml``).
traversable
-----------
Make a Zope 2 content class traversable in the Zope 3 manner using
Five. This is used to attached views, resources and other things to
Zope 2 objects.
defaultViewable
---------------
Make a Zope 2 content class use a Zope 3 default view when looking at
it without any paths appended to it. This works then instead of
``index_html`` in Zope 2.
pagesFromDirectory
------------------
Load all *.pt files in a directory as pages. Useful when you want to
share templates between Five and CMF, so you can declare pages like
this is a similar way to setting up skin folders in portal_skins.
browser:editform
----------------
Create an edit form based on a schema.
browser:addform
---------------
Create an add form based on a schema.
Adapters
Generally, adapters can now be used in Zope 2 just as they are used in
Zope 3.
Zope 3 Views
Zope 3 views work in Zope 2 with Five, including layers and skins. To
make them work however, you need to make a Zope 2 class "traversable".
This can be done by using the 'five:traversable' directive in ZCML.
Schemas and Forms
With the Five layer, it is possible to use schema-based content using
the standard Zope 3 patterns.
Security declarations
Five aims to eradicate declareProtected, ClassSecurityInfo and
initializeClass from your Zope 2 code.
In order to do this, Five provides the Zope 3 way of declaring
permissions from ZCML, but uses the Zope 2 mechanisms to actually set
them. To declare permissions for methods and templates on views you use
the permission attribute on the browser:page directive, and specify a
Zope 2 permission (given a Zope 3 name). You can find a list of these
permissions in permissions.zcml in Five. The permission check takes
place before the view is executed.
The content directive can also be used to declare permissions on Zope 2
content classes. Note however that these permissions will be ignored by
views anyway, as they are trusted -- it only serves to protect directly
exposed methods on content classes (the python scripts and the ZPublisher).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7