[Checkins] SVN: Zope/trunk/doc/ Update documentation some more. Removed pretty much outdated and obsolete bits
Hanno Schlichting
plone at hannosch.info
Mon Feb 9 15:43:30 EST 2009
Log message for revision 96336:
Update documentation some more. Removed pretty much outdated and obsolete bits
Changed:
U Zope/trunk/doc/DEBUGGING.txt
U Zope/trunk/doc/FAQ.txt
D Zope/trunk/doc/HELPSYS.txt
U Zope/trunk/doc/INSTALL.txt
D Zope/trunk/doc/PLATFORMS/
D Zope/trunk/doc/RESTRUCTUREDSTEXT.txt
D Zope/trunk/doc/UNITTEST.txt
D Zope/trunk/doc/WEBSERVER.txt
U Zope/trunk/doc/WINDOWS.txt
D Zope/trunk/doc/ZODB.txt
U Zope/trunk/doc/ZOPE3.txt
-=-
Modified: Zope/trunk/doc/DEBUGGING.txt
===================================================================
--- Zope/trunk/doc/DEBUGGING.txt 2009-02-09 20:23:50 UTC (rev 96335)
+++ Zope/trunk/doc/DEBUGGING.txt 2009-02-09 20:43:30 UTC (rev 96336)
@@ -1,4 +1,3 @@
-
Running Zope in Debug Mode
If you wish to run Zope in debug mode, set the 'debug-mode'
@@ -14,64 +13,16 @@
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 at 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()
Modified: Zope/trunk/doc/FAQ.txt
===================================================================
--- Zope/trunk/doc/FAQ.txt 2009-02-09 20:23:50 UTC (rev 96335)
+++ Zope/trunk/doc/FAQ.txt 2009-02-09 20:43:30 UTC (rev 96336)
@@ -1,7 +1,6 @@
Zope Installation Frequently Asked Questions
--------------------------------------------
-
Installing Zope
1. On certain Unix platforms (usually Solaris) I get a "checksum
@@ -27,7 +26,7 @@
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 @@
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,25 +72,16 @@
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).
+ 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.
- 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.
-
-
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 @@
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 @@
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,88 +149,37 @@
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).
+ - Create a new environment (see doc/INSTALL.txt).
- - Copy the var/Data.fs file from your old instance into your
- new instance's var/ directory.
+ - Include your application code in the environment.
- 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.
-
- 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.)
+ old environment.
- - Start the new instance. (Be sure the old instance is not running.)
+ - Start the new application process. (Be sure the old process
+ is not running.)
- - Update any ZCatalogs as described below.
+ 2. CMF doesn't work!
- - Update any Python Scripts. This is not strictly necessary,
- but it will make Zope restart somewhat faster. Visit this URL
- in your browser:
-
- http://.../manage_addProduct/PythonScripts/recompile
-
-
- 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!
-
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/
+ 3. Plone doesn't work!
- 4. Plone doesn't work!
-
All Plone versions require a certain Zope version.
Check the Plone release informations on http://www.plone.org
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 @@
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
Deleted: Zope/trunk/doc/HELPSYS.txt
===================================================================
--- Zope/trunk/doc/HELPSYS.txt 2009-02-09 20:23:50 UTC (rev 96335)
+++ Zope/trunk/doc/HELPSYS.txt 2009-02-09 20:43:30 UTC (rev 96336)
@@ -1,110 +0,0 @@
-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
Modified: Zope/trunk/doc/INSTALL.txt
===================================================================
--- Zope/trunk/doc/INSTALL.txt 2009-02-09 20:23:50 UTC (rev 96335)
+++ Zope/trunk/doc/INSTALL.txt 2009-02-09 20:43:30 UTC (rev 96336)
@@ -15,12 +15,12 @@
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)
- o 2.5.x
-
+ * 2.6.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 @@
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 @@
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
Deleted: Zope/trunk/doc/RESTRUCTUREDSTEXT.txt
===================================================================
--- Zope/trunk/doc/RESTRUCTUREDSTEXT.txt 2009-02-09 20:23:50 UTC (rev 96335)
+++ Zope/trunk/doc/RESTRUCTUREDSTEXT.txt 2009-02-09 20:43:30 UTC (rev 96336)
@@ -1,50 +0,0 @@
-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.
-
Deleted: Zope/trunk/doc/UNITTEST.txt
===================================================================
--- Zope/trunk/doc/UNITTEST.txt 2009-02-09 20:23:50 UTC (rev 96335)
+++ Zope/trunk/doc/UNITTEST.txt 2009-02-09 20:43:30 UTC (rev 96336)
@@ -1,378 +0,0 @@
-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!)
-
Deleted: Zope/trunk/doc/WEBSERVER.txt
===================================================================
--- Zope/trunk/doc/WEBSERVER.txt 2009-02-09 20:23:50 UTC (rev 96335)
+++ Zope/trunk/doc/WEBSERVER.txt 2009-02-09 20:43:30 UTC (rev 96336)
@@ -1,462 +0,0 @@
-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.
-
-
-
-
-
-
-
-
-
-
-
Modified: Zope/trunk/doc/WINDOWS.txt
===================================================================
--- Zope/trunk/doc/WINDOWS.txt 2009-02-09 20:23:50 UTC (rev 96335)
+++ Zope/trunk/doc/WINDOWS.txt 2009-02-09 20:43:30 UTC (rev 96336)
@@ -1,24 +1,22 @@
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 @@
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
Deleted: Zope/trunk/doc/ZODB.txt
===================================================================
--- Zope/trunk/doc/ZODB.txt 2009-02-09 20:23:50 UTC (rev 96335)
+++ Zope/trunk/doc/ZODB.txt 2009-02-09 20:43:30 UTC (rev 96336)
@@ -1,105 +0,0 @@
-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.
Modified: Zope/trunk/doc/ZOPE3.txt
===================================================================
--- Zope/trunk/doc/ZOPE3.txt 2009-02-09 20:23:50 UTC (rev 96335)
+++ Zope/trunk/doc/ZOPE3.txt 2009-02-09 20:43:30 UTC (rev 96336)
@@ -1,273 +1,27 @@
-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.
+ 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.
- Much more information on Zope 3 is available on the Zope 3 area
- of the zope.org Website at http://dev.zope.org/Zope3/.
-
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::
+ new and existing Zope 2 applications.
- - 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 ;)
-
-
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).
-
More information about the Checkins
mailing list