[Zope3-checkins] SVN: Zope3/branches/ZopeX3-3.0/doc/ Convert more
documentation to reStructuredText.
Fred L. Drake, Jr.
fred at zope.com
Thu Jul 1 12:11:22 EDT 2004
Log message for revision 26016:
Convert more documentation to reStructuredText.
-=-
Modified: Zope3/branches/ZopeX3-3.0/doc/ENVIRONMENT.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/doc/ENVIRONMENT.txt 2004-07-01 15:33:37 UTC (rev 26015)
+++ Zope3/branches/ZopeX3-3.0/doc/ENVIRONMENT.txt 2004-07-01 16:11:22 UTC (rev 26016)
@@ -1,21 +1,23 @@
-Usage of environment variables:
+===============================
+Environment Variables in Zope 3
+===============================
- - The test suite uses the LOGGING variable to determine the PEP 282
- logging level. This should be a decimal number with the following
- meaning: 10 DEBUG, 20 INFO, 30 WARN, 40 ERROR, 50 CRITICAL
- (default).
+- The test suite uses the LOGGING variable to determine the PEP 282
+ logging level. This should be a decimal number with the following
+ meaning: 10 DEBUG, 20 INFO, 30 WARN, 40 ERROR, 50 CRITICAL
+ (default).
- - Some ZEO code still uses environment variables, in particular
- ZEO_CACHE_TRACE, ZEO_CLIENT, INSTANCE_HOME, ZEO_SERVER_PID.
+- Some ZEO code still uses environment variables, in particular
+ ZEO_CACHE_TRACE, ZEO_CLIENT, INSTANCE_HOME, ZEO_SERVER_PID.
- - ZOPE_WATCH_CHECKERS used by src/zope/security/checker.py.
+- ZOPE_WATCH_CHECKERS used by src/zope/security/checker.py.
- - ZOPE_SERVER_SIMULT_MODE used by src/zope/server/serverchannelbase.py.
+- ZOPE_SERVER_SIMULT_MODE used by src/zope/server/serverchannelbase.py.
- - ZOPE_SERVER_DEBUG used by
- src/zope/server/linereceiver/lineserverchannel.py.
+- ZOPE_SERVER_DEBUG used by
+ src/zope/server/linereceiver/lineserverchannel.py.
- - NEW_ZOPE_EXCEPTION_FORMATTER used by src/zope/testing/.
+- NEW_ZOPE_EXCEPTION_FORMATTER used by src/zope/testing/.
- - PYUNIT_EDITOR, EDITOR, EDITOR_REMOTE used by
- utilities/unittestgui.py.
+- PYUNIT_EDITOR, EDITOR, EDITOR_REMOTE used by
+ utilities/unittestgui.py.
Modified: Zope3/branches/ZopeX3-3.0/doc/FTEST.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/doc/FTEST.txt 2004-07-01 15:33:37 UTC (rev 26015)
+++ Zope3/branches/ZopeX3-3.0/doc/FTEST.txt 2004-07-01 16:11:22 UTC (rev 26016)
@@ -1,81 +1,88 @@
+=========================
Zope 3 Functional Testing
+=========================
- How to run Zope 3 functional tests
+How to run Zope 3 functional tests
+----------------------------------
- In the top-level directory, run "python test.py -f". If you've read
- UNITTEST.txt you'll notice that the same script is used, but with an
- additional argument '-f'. That's because in Zope 3 functional tests are
- just a special case of unit tests. The rest of test.py options work as
- well, for example you can use "python test.py -fpv" to get a nice progress
- indicator. For information about all options run "python test.py -h".
+In the top-level directory, run "python test.py -f". If you've read
+UNITTEST.txt you'll notice that the same script is used, but with an
+additional argument '-f'. That's because in Zope 3 functional tests are
+just a special case of unit tests. The rest of test.py options work as
+well, for example you can use "python test.py -fpv" to get a nice progress
+indicator. For information about all options run "python test.py -h".
- If your Zope 3 doesn't yet have a products.zcml, create one by
- copying products.zcml.in to products.zcml.
+If your Zope 3 doesn't yet have a products.zcml, create one by
+copying products.zcml.in to products.zcml.
- Zope Functional Testing
+Zope Functional Testing
+-----------------------
- Functional tests live in directories called "ftests" all over the source
- tree. They use the same PyUnit framework as unit tests, and I recommend
- reading UNITTEST.txt and familiarizing with unit tests before moving on to
- functional tests.
+Functional tests live in directories called "ftests" all over the source
+tree. They use the same PyUnit framework as unit tests, and I recommend
+reading UNITTEST.txt and familiarizing with unit tests before moving on to
+functional tests.
- Functional tests differ from unit tests in that nearly all ZCML configuration
- files are parsed and a virtual in-memory storage is created before running
- them. Any changes made to the storage will be discarded at the end of the
- test.
+Functional tests differ from unit tests in that nearly all ZCML configuration
+files are parsed and a virtual in-memory storage is created before running
+them. Any changes made to the storage will be discarded at the end of the
+test.
- What Functional Tests Are
+What Functional Tests Are
+-------------------------
- Functional tests are meant to test more than just a single unit of code.
- While unit tests make sure that all components work as designed, functional
- tests ensure that those components are connected correctly, and that the
- system works as a whole.
+Functional tests are meant to test more than just a single unit of code.
+While unit tests make sure that all components work as designed, functional
+tests ensure that those components are connected correctly, and that the
+system works as a whole.
- Writing Functional Tests
+Writing Functional Tests
+------------------------
- Functional tests in Zope 3 use the same conventions as unit tests, but with
- the following differences:
+Functional tests in Zope 3 use the same conventions as unit tests, but with
+the following differences:
- - Functional test modules live in directories called 'ftests'.
+- Functional test modules live in directories called 'ftests' or
+ modules name 'ftests.py'.
- - Functional test cases inherit from
- zope.testing.functional.FunctionalTestCase or
- zope.testing.functional.BrowserTestCase instead of unittest.TestCase.
+- Functional test cases inherit from
+ `zope.testing.functional.FunctionalTestCase` or
+ `zope.testing.functional.BrowserTestCase` instead of
+ `unittest.TestCase`.
- - All global services, components etc. defined in assorted configure.zcml
- are available during test run time.
+- All global services, components etc. defined in assorted configure.zcml
+ are available during test run time.
- - A volatile in-memory storage with an empty root folder and all essential
- services is available and is automatically cleaned after every test.
- The test code can access and modify the root folder by calling
- self.getRootFolder().
+- A volatile in-memory storage with an empty root folder and all essential
+ services is available and is automatically cleaned after every test.
+ The test code can access and modify the root folder by calling
+ `self.getRootFolder()`.
- - Browser requests can be emulated by inheriting from BrowserTestCase and
- calling self.publish(). See the docstring in
- src/zope/app/tests/functional.py for detailed information. Here are a
- couple of simple examples::
+- Browser requests can be emulated by inheriting from
+ `BrowserTestCase` and calling `self.publish()`. See the docstring
+ in src/zope/app/tests/functional.py for detailed information. Here
+ are a couple of simple examples::
- response = self.publish('/folder/object')
- self.assertEquals(response.getStatus(), 200)
- self.assert_(response.getBody().find("some text") != -1)
+ response = self.publish('/folder/object')
+ self.assertEquals(response.getStatus(), 200)
+ self.assert_(response.getBody().find("some text") != -1)
- response = self.publish(
- '/something/action.html',
- basic='username:password',
- form={'id': u'foo', 'UPDATE_SUBMIT': u'Submit'})
- self.assertEquals(response.getStatus(), 302)
- self.assertEquals(response.getHeader('Location'),
- 'http://localhost/something.html')
+ response = self.publish(
+ '/something/action.html',
+ basic='username:password',
+ form={'id': u'foo', 'UPDATE_SUBMIT': u'Submit'})
+ self.assertEquals(response.getStatus(), 302)
+ self.assertEquals(response.getHeader('Location'),
+ 'http://localhost/something.html')
- - If you want to make changes made directly through access to
- self.getRootFolder() available to an emulated request, make sure to commit
- the transaction. Here's how you do it::
+- If you want to make changes made directly through access to
+ `self.getRootFolder()` available to an emulated request, make sure
+ to commit the transaction. Here's how you do it::
- from transaction import get_transaction
- get_transaction().commit()
+ from transaction import get_transaction
+ get_transaction().commit()
- - Functional tests should not change any global registries. In particular,
- functional unit test cases should not inherit from
- zope.testing.cleanup.CleanUp or any of the PlacelessSetup classes that
- inherit from CleanUp.
-
+- Functional tests should not change any global registries. In
+ particular, functional unit test cases should not inherit from
+ `zope.testing.cleanup.CleanUp` or any of the `PlacelessSetup`
+ classes that inherit from `CleanUp`.
Modified: Zope3/branches/ZopeX3-3.0/doc/INSTALL.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/doc/INSTALL.txt 2004-07-01 15:33:37 UTC (rev 26015)
+++ Zope3/branches/ZopeX3-3.0/doc/INSTALL.txt 2004-07-01 16:11:22 UTC (rev 26016)
@@ -1,114 +1,118 @@
+========================================
Building and installing Zope from source
-----------------------------------------
+========================================
- This document describes building and installing Zope3 on Unix.
- We will provide Windows instructions in later releases. We
- will also provide binary releases for some platforms.
+This document describes building and installing Zope3 on Unix.
+We will provide Windows instructions in later releases. We
+will also provide binary releases for some platforms.
-Important notes
+Important Notes
+---------------
- ZOPE 3 REQUIRES PYTHON 2.3.4!
+ZOPE 3 REQUIRES PYTHON 2.3.4!
Quick Start
+-----------
- The following commands should get you up and running with the
- development version of Zope3 on Unix:
+The following commands should get you up and running with the
+development version of Zope3 on Unix:
- * If you have not yet checked out the Subversion tree, do so::
+* If you have not yet checked out the Subversion tree, do so::
- svn co svn://svn.zope.org/repos/main/Zope3/trunk/ Zope3
+ svn co svn://svn.zope.org/repos/main/Zope3/trunk/ Zope3
- * cd Zope3
+* cd Zope3
- * python setup.py build_ext -i
+* python setup.py build_ext -i
- (On Unix, typing "make" will do the same thing.)
+ (On Unix, typing "make" will do the same thing.)
- * Copy sample_principals.zcml to principals.zcml, and edit the
- entries in your new principals.zcml. At the very least, change
- the passwords!
+* Copy sample_principals.zcml to principals.zcml, and edit the entries
+ in your new principals.zcml. At the very least, change the
+ passwords!
- * python z3.py
+* python z3.py
- (On Unix, typing "make run" will do the same thing.)
+ (On Unix, typing "make run" will do the same thing.)
- You should shortly see logging messages indicating Zope3 is listening on
- port 8080. At that point you can connect to Zope3 by directing
- your browser to::
+You should shortly see logging messages indicating Zope3 is listening
+on port 8080. At that point you can connect to Zope3 by directing
+your browser to::
- http://yourhost:8080/manage
+ http://yourhost:8080/manage
- where yourhost is the name or address of the machine running Zope 3.
+where yourhost is the name or address of the machine running Zope 3.
- This will access the Zope 3 default management interface. Note that
- this release of Zope 3 requires recent versions of Mozilla or IE.
+This will access the Zope 3 default management interface. Note that
+this release of Zope 3 requires recent versions of Mozilla or IE.
- If you insist on using an older browser (or a text-based browser)
- you can use the basic Zope 3 skin by putting '++skin++basic' after
- the server part of the URL::
+If you insist on using an older browser (or a text-based browser) you
+can use the basic Zope 3 skin by putting '++skin++basic' after the
+server part of the URL::
- http://localhost:8080/++skin++basic/manage
+ http://localhost:8080/++skin++basic/manage
- You will be prompted for a user name and password. Use the user name
- and password you entered into your principals.zcml file.
+You will be prompted for a user name and password. Use the user name
+and password you entered into your principals.zcml file.
- Now you're off and running!
+Now you're off and running!
Resources
+---------
- If you haven't used Zope3 before, you should head to the Zope web
- site and read some documentation. The Zope 3 Python Programmers
- Tutorial is a good place to start. You can access it on the Zope
- site at::
+If you haven't used Zope3 before, you should head to the Zope web site
+and read some documentation. The Zope 3 Python Programmers Tutorial is
+a good place to start. You can access it on the Zope site at::
- http://dev.zope.org/Zope3/ProgrammerTutorial
+ http://dev.zope.org/Zope3/ProgrammerTutorial
- You will also find some additional documentation in the 'doc'
- directory of the Zope3 tree, where this file lives. All other
- existing Zope3 documentation is linked from somewhere in the Zope
- project Wiki::
+You will also find some additional documentation in the 'doc'
+directory of the Zope3 tree, where this file lives. All other
+existing Zope3 documentation is linked from somewhere in the Zope
+project Wiki::
- http://dev.zope.org/Zope3/ComponentArchitecture
+ http://dev.zope.org/Zope3/ComponentArchitecture
- You may also want to subscribe to the Zope3-dev mailing list::
+You may also want to subscribe to the Zope3-dev mailing list::
- http://lists.zope.org/mailman/listinfo/zope3-dev
+ http://lists.zope.org/mailman/listinfo/zope3-dev
- Have fun!
+Have fun!
Random Details
+--------------
- * There are some Python scripts in the top-level directory that
- will help you track changes during the development process.
- Specifically, 'setup.py' helps you build the extension modules,
- and 'test.py' will run all of the unit tests (see UNITTEST.txt
- in the doc directory for more information on unit tests).
+* There are some Python scripts in the top-level directory that will
+ help you track changes during the development process.
+ Specifically, 'setup.py' helps you build the extension modules, and
+ 'test.py' will run all of the unit tests (see UNITTEST.txt in the
+ doc directory for more information on unit tests).
- * You should be using Python 2.3.4 or later to run anything
- related to Zope3.
+* You should be using Python 2.3.4 or later to run anything related to
+ Zope3.
- * The Python you run Zope with *must* have threads compiled in.
- This is typically the case for a vanilla build on platforms that
- support thread, but be sure this wasn't disabled if you use a
- custom build. (If the Python statement "import thread" raises
- an exception, your Python interpreter does not support threads.)
- Warning: Zope will not run with a Python version that uses
- libpth. You *must* use libpthread.
+* The Python you run Zope with *must* have threads compiled in. This
+ is typically the case for a vanilla build on platforms that support
+ threads, but be sure this wasn't disabled if you use a custom build.
+ (If the Python statement "import thread" raises an exception, your
+ Python interpreter does not support threads.) Warning: Zope will
+ not run with a Python version that uses libpth. You *must* use
+ libpthread.
- * To build Python extensions you need to have Python configuration
- information available. If your Python comes from an RPM you may
- need the python-devel package installed too. If you built Python
- from source all the configuration information should already be
- there.
+* To build Python extensions you need to have Python configuration
+ information available. If your Python comes from an RPM you may need
+ the python-devel package installed too. If you built Python from
+ source all the configuration information should already be there.
- * If you just want to use Zope components it's not necessary to
- build Zope but it's a good idea since it will compile Python C
- extensions for you.
+* If you just want to use Zope components it's not necessary to build
+ Zope but it's a good idea since it will compile Python C extensions
+ for you.
Troubleshooting
+---------------
- * We've seen segfaults when running the test suite. This was
- invariably caused by having parts of Zope 2 or ZODB 3 (which
- goes with Zope 2) installed in site-packages or elsewhere on
- Python's module search path (sys.path). So make sure you have
- no parts of Zope 2 or ZODB 3 on sys.path when running Zope 3!
+* We've seen segfaults when running the test suite. This was
+ invariably caused by having parts of Zope 2 or ZODB 3 installed in
+ site-packages or elsewhere on Python's module search path
+ (sys.path). So make sure you have no parts of Zope 2 or ZODB 3 on
+ sys.path when running Zope 3!
Modified: Zope3/branches/ZopeX3-3.0/doc/LOGGING.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/doc/LOGGING.txt 2004-07-01 15:33:37 UTC (rev 26015)
+++ Zope3/branches/ZopeX3-3.0/doc/LOGGING.txt 2004-07-01 16:11:22 UTC (rev 26016)
@@ -1,145 +1,154 @@
+==============
Zope 3 Logging
+==============
- Logging is done through the logging package (PEP 282-based logging).
- It is fairly easy to use and to configure.
+Logging is done through the `logging` package (PEP 282-based logging).
+It is fairly easy to use and to configure.
- Configuring the logging package for z3.py
+Configuring the logging package for z3.py
+-----------------------------------------
- XXX This is out of date; see zope.conf.in for an example of the
- current way of configuring logging.
+XXX This is out of date; see zope.conf.in for an example of the
+current way of configuring logging.
- The log file used by z3.py can be configured in the zserver.zcml
- file with this directive::
+The log file used by z3.py can be configured in the zserver.zcml
+file with this directive::
- <startup:useLog file="..." level="...">
+ <startup:useLog file="..." level="...">
- The file argument should give the filename where you want the log to
- go. If the filename is STDERR or STDOUT, logging goes to the
- process's standard error or standard output stream, respectively.
+The file argument should give the filename where you want the log to
+go. If the filename is STDERR or STDOUT, logging goes to the
+process's standard error or standard output stream, respectively.
- The level argument should give the logging severity level; anything
- below this level is not logged. The supported levels are, in
- increasing severity: DEBUG, INFO, WARN, ERROR, CRITICAL.
+The level argument should give the logging severity level; anything
+below this level is not logged. The supported levels are, in
+increasing severity: `DEBUG`, `INFO`, `WARN`, `ERROR`, `CRITICAL`.
- Configuring the logging package for running unit tests
+Configuring the logging package for running unit tests
+------------------------------------------------------
- When running unit tests, logging is configured through the file
- log.ini in the current directory, if it exists. This file should be
- self-explanatory, and provides full access to the logging package's
- advanced features. If log.ini is not found, critical messages are
- logged to the process's standard error stream, and other messages
- are not logged.
+When running unit tests, logging is configured through the file
+log.ini in the current directory, if it exists. This file should be
+self-explanatory, and provides full access to the logging package's
+advanced features. If log.ini is not found, critical messages are
+logged to the process's standard error stream, and other messages
+are not logged.
- test.py also understands the LOGGING environment variable, which can
- be used to specify an integer logging level. So a simple way to run
- the tests with all logging going to standard error is to set LOGGING
- to 0, e.g.:
+test.py also understands the LOGGING environment variable, which can
+be used to specify an integer logging level. So a simple way to run
+the tests with all logging going to standard error is to set LOGGING
+to 0, e.g.::
export LOGGING=0
python test.py
- Using the logging package
+Using the logging package
+-------------------------
- There are two ways of using the logging package. You can use
- functions defined in the logging package directly, or you can use
- methods on a logger object. In either case you need a simple import
- statement::
+There are two ways of using the logging package. You can use
+functions defined in the logging package directly, or you can use
+methods on a logger object. In either case you need a simple import
+statement::
- import logging
+ import logging
- Using the logging functions
+Using the logging functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
- To use the logging functions defined by the package directly, use
- one of the functions debug(), info(), warn(), error() or critical()
- from the package. Each of these takes a message argument. The
- message may be a standard Python format string, and then the
- following arguments are the format arguments. This allows you to
- write, for example::
+To use the logging functions defined by the package directly, use one
+of the functions `debug()`, `info()`, `warn()`, `error()` or
+`critical()` from the package. Each of these takes a message
+argument. The message may be a standard Python format string, and
+then the following arguments are the format arguments. This allows
+you to write, for example::
- logging.warn("Cannot open file %r: %s", filename, err)
+ logging.warn("Cannot open file %r: %s", filename, err)
- instead of::
+instead of::
- logging.warn("Cannot open file %r: %s" % (filename, err))
+ logging.warn("Cannot open file %r: %s" % (filename, err))
- Apart from slight savings in typing, the advantage of the former is
- that if warnings are not logged, the string formatting operation is
- not carried out, saving some time.
+Apart from slight savings in typing, the advantage of the former is
+that if warnings are not logged, the string formatting operation is
+not carried out, saving some time.
- It is also possible to log a traceback. This is done by adding a
- keyword argument exc_info=True. For example::
+Only positional format arguments are supported.
- try:
- ...something...
- except:
- logging.error("Unexpected problem", exc_info=True)
+It is also possible to log a traceback. This is done by adding a
+keyword argument ``exc_info=True``. For example::
- The logging package will call sys.exc_info() and use the traceback
- module to format the traceback. When the message is not logged,
- this is skipped. In fact, there's a shorthand for this particular
- case (logging a traceback at the error level)::
+ try:
+ ...something...
+ except:
+ logging.error("Unexpected problem", exc_info=True)
- try:
- ...something...
- except:
- logging.exception("Unexpected problem")
+The logging package will call sys.exc_info() and use the traceback
+module to format the traceback. When the message is not logged, this
+is skipped. In fact, there's a shorthand for this particular case
+(logging a traceback at the error level)::
- Finally, there is a generic log function; it has a first argument
- specifying a logging severity level, followed by the standard
- arguments of all the above functions::
+ try:
+ ...something...
+ except:
+ logging.exception("Unexpected problem")
- logging.log(level, message, ..., exc_info=...)
+Finally, there is a generic log function; it has a first argument
+specifying a logging severity level, followed by the standard
+arguments of all the above functions::
- The predefined logging levels are available as symbolic constants:
- logging.DEBUG, logging.INFO, logging.WARN, logging.ERROR, and
- logging.CRITICAL. (There's no logging.EXCEPTION level, because
- exception() is not a separate logging level; it's a shorthand for
- passing exc_info=True to the error() method.)
+ logging.log(level, message, ..., exc_info=...)
+The predefined logging levels are available as symbolic constants:
+`logging.DEBUG`, `logging.INFO`, `logging.WARN`, `logging.ERROR`, and
+`logging.CRITICAL`. (There's no `logging.EXCEPTION` level, because
+`exception()` is not a separate logging level; it's a shorthand for
+passing ``exc_info=True`` to the `error()` method.)
- Using a logger object
- Often you'd like all log messages coming out of a particular class
- or module to be "tagged" with a label identifying that class or
- module, regardless of the logging severity of the message. In some
- cases, you'd like that label to convey additional run-time
- information, such as a storage or thread name.
+Using a logger object
+~~~~~~~~~~~~~~~~~~~~~
- Rather than prefixing all log messages with an identifying string,
- you can create a logger object that does this for you. Logger
- objects have methods debug(), info(), etc., corresponding to the
- logging functions described in the previous section, and with
- exactly the same signature; these are what you use to log a message
- using a logger object, for example::
+Often you'd like all log messages coming out of a particular class or
+module to be "tagged" with a label identifying that class or module,
+regardless of the logging severity of the message. In some cases,
+you'd like that label to convey additional run-time information, such
+as a storage or thread name.
- logger.warn("Oil temperature: %g", temp)
+Rather than prefixing all log messages with an identifying string, you
+can create a logger object that does this for you. Logger objects
+have methods `debug()`, `info()`, etc., corresponding to the logging
+functions described in the previous section, and with exactly the same
+signature; these are what you use to log a message using a logger
+object. For example::
- To create a logger object, use the getLogger() function::
+ logger.warn("Oil temperature: %g", temp)
- foo_bar_logger = logging.getLogger("foo.bar")
+To create a logger object, use the `getLogger()` function::
- The string argument to getLogger() is interpreted as a sequence of
- names separated by dots; this creates a hierarchy that can be used
- for additional filtering or handling. Normally, however, a logger
- object inherits all its properties (except for its name) from its
- parent logger object. For the foo_bar_logger above, the parent
- would be the logger object returned by this call::
+ foo_bar_logger = logging.getLogger("foo.bar")
- foo_logger = logging.getLogger("foo")
+The string argument to `getLogger()` is interpreted as a sequence of
+names separated by dots; this creates a hierarchy that can be used for
+additional filtering or handling. Normally, however, a logger object
+inherits all its properties (except for its name) from its parent
+logger object. For the foo_bar_logger above, the parent would be the
+logger object returned by this call::
- Its parent in turn is the root logger; the logging functions
- described in the previous section correspond to methods of the root
- logger object. By configuring the root logger you can configure all
- loggers in the hierarchy, unless some configuration is overridden at
- a lower level. This an advanced feature of the logging module that
- we won't discuss further here.
+ foo_logger = logging.getLogger("foo")
- Logger objects are lightweight and cached by the logging module;
- subsequent calls to logging.getLogger() with the same logger name
- will return the same logger object. However, there is no way to
- delete logger objects, so it's not a good idea to make up arbitrary
- logger names dynamically.
+Its parent in turn is the root logger; the logging functions described
+in the previous section correspond to methods of the root logger
+object. By configuring the root logger you can configure all loggers
+in the hierarchy, unless some configuration is overridden at a lower
+level. This an advanced feature of the logging module that we won't
+discuss further here.
+
+Logger objects are lightweight and cached by the logging module;
+subsequent calls to `logging.getLogger()` with the same logger name
+will return the same logger object. However, there is no way to
+delete logger objects, so it's not a good idea to make up arbitrary
+logger names dynamically.
Modified: Zope3/branches/ZopeX3-3.0/doc/ROADMAP.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/doc/ROADMAP.txt 2004-07-01 15:33:37 UTC (rev 26015)
+++ Zope3/branches/ZopeX3-3.0/doc/ROADMAP.txt 2004-07-01 16:11:22 UTC (rev 26016)
@@ -1,13 +1,17 @@
+=============
Zope Road Map
+=============
- This file lists features or tasks planned for future releases. It is roughly
- the compliment of CHANGES.txt. Over time, entries from this file
- will migrate to CHANGES.txt and then to HISTORY.txt.
+This file lists features or tasks planned for future releases. It is roughly
+the compliment of CHANGES.txt. Over time, entries from this file
+will migrate to CHANGES.txt and then to HISTORY.txt.
- Zope X3 1.0 (Zope X3.0.0?)
+Zope X3 1.0 (Zope X3.0.0?)
+--------------------------
- See the to-do list: TODO.txt.
+See the to-do list: TODO.txt.
- Later releases
+Later releases
+--------------
- See the list of things to do later: TODOLATER.txt.
+See the list of things to do later: TODOLATER.txt.
Modified: Zope3/branches/ZopeX3-3.0/doc/UNITTEST.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/doc/UNITTEST.txt 2004-07-01 15:33:37 UTC (rev 26015)
+++ Zope3/branches/ZopeX3-3.0/doc/UNITTEST.txt 2004-07-01 16:11:22 UTC (rev 26016)
@@ -1,240 +1,233 @@
+===================
Zope 3 Unit Testing
+===================
- How to run Zope 3 unit tests
+How to run Zope 3 unit tests
+----------------------------
- In the top level directory, run "python test.py". This runs all unit
- tests silently (unless errors occur). It is possible to run the
- tests more verbosely or to be more selective about which tests to
- run. There are also other options. For information about all this,
- run "python test.py -h" which prints an extensive usage message.
+In the top level directory, run **python test.py**. This runs all unit
+tests silently (unless errors occur). It is possible to run the tests more
+verbosely or to be more selective about which tests to run. There are also
+other options. For information about all this, run **python test.py -h**
+which prints an extensive usage message.
- Zope 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".
+If you encounter a directory named "tests" (or a file named "tests.py") 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 modules which contain "unit tests".
- What Unit Tests Are
+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.
+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.
+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
+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)::
+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:
+ Unit tests are not:
- - Manually operated.
+ - Manually operated.
- - Automated screen-driver tests that simulate user input (these
- are "functional tests").
+ - Automated screen-driver tests that simulate user input (these are
+ "functional tests").
- - Interactive. They run "no questions asked."
+ - Interactive. They run "no questions asked."
- - Coupled. They run without dependencies except those native to
- the thing being tested.
+ - 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.
+ - Complicated. Unit test code is typically straightforward procedural
+ code that simulates an event.
- Unit Testing Frameworks
+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.
+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
+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. Additionally, 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."
+Unit tests should be written at the same time the code they test is
+written. A short, healthy cycle of "write test/code/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. Additionally,
+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
+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 conjunction 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.
+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 conjunction 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.
+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.
+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 riskiest 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.
+"It is better to have tried to test and failed than to not have tried to
+test at all" aka "test the riskiest 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.
+*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.
+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.
+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 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.
+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
+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:
+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 the standard Python unittest
- module. See the Python docs for usage information.
+- The testing code should make use of the standard Python `unittest`
+ module. See the Python documentation for usage information.
- - Tests must be placed in a "tests" subdirectory of the package or
- directory in which the core code you're testing lives.
+- 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.
+- 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.
+- Running an individual test module should take no longer than 60 seconds
+ to complete.
- more information available at http://dev.zope.org/Zope3/WritingUnitTests
+More information is available at http://dev.zope.org/Zope3/WritingUnitTests.
- Writing Unit Tests For Applications Based On Zope
+Writing Unit Tests For Applications Based On Zope
+-------------------------------------------------
- Zope uses the standard Python unittest module. See the Python docs
- for usage information. You should establish your own conventions
- for naming and placement of test modules.
+Zope uses the standard Python unittest module. See the Python docs for
+usage information. You should establish your own conventions for naming
+and placement of test modules.
- 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 frustrating. 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.
+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 frustrating. 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.
- Luckily, some tools are at your disposal to make writing unit tests
- against Zope components and applications easier by making the
- creation of these fixtures easier.
+Luckily, some tools are at your disposal to make writing unit tests against
+Zope components and applications easier by making the creation of these
+fixtures easier.
- Surprisingly, 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.
+Surprisingly, 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.
- Administrivia
+Administrivia
+-------------
- Unit test scripts found in the Zope source code is based on
- the PyUnit unit testing framework, available from
- http://pyunit.sourceforge.net, 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 test scripts found in the Zope source code is based on the PyUnit unit
+testing framework, available from http://pyunit.sourceforge.net, 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 facilitate 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
- Digital Creations 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.
-
-
+Unit testing is a primary tenet of "Extreme Programming", a software
+development methodology designed to facilitate 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.
More information about the Zope3-Checkins
mailing list