[Checkins] SVN: zope.pytest/trunk/src/zope/pytest/setup.py More docstrings.
Uli Fouquet
uli at gnufix.de
Sat Jan 15 20:17:40 EST 2011
Log message for revision 119594:
More docstrings.
Changed:
U zope.pytest/trunk/src/zope/pytest/setup.py
-=-
Modified: zope.pytest/trunk/src/zope/pytest/setup.py
===================================================================
--- zope.pytest/trunk/src/zope/pytest/setup.py 2011-01-16 00:22:05 UTC (rev 119593)
+++ zope.pytest/trunk/src/zope/pytest/setup.py 2011-01-16 01:17:40 UTC (rev 119594)
@@ -25,9 +25,9 @@
`site_root` stored in the root folder under the name ``test``.
This function is meant to be used as setup/teardown handler
- deploying a ``pytest_funcarg__`` function.
+ deploying a `pytest_funcarg__`_ function.
- It sets up a ZODB connection to a ZODB DemoStorage and adds
+ It sets up a ZODB_ connection to a ZODB_ DemoStorage and adds
finalizers (`tear_down`-functionality for people from other
testing frameworks) to shutdown the whole setup after the test
session.
@@ -43,6 +43,10 @@
properly before. Most notably you have to register basic
components that subscribe to IDatabaseOpenedEvents, etc. This can
normally be done using :func:`configure` or :func:`setup_config`.
+
+ .. seealso:: `pytest_funcarg__`_ docs on pytest.org.
+
+ .. _pytest_funcarg__: http://pytest.org/funcargs.html
"""
db = setup_db()
connection = setup_connection(db)
@@ -70,6 +74,39 @@
return wsgi_app
def configure(request, module, zcml):
+ """Configure the environment.
+
+ Performs a ZCML-driven configuration.
+
+ The `request` parameter
+ is expected to be a py.test
+ :class:`FuncargRequest` (not an HTTP request or similar) which is
+ generated by py.test while running tests.
+
+ `module`
+ is a Python module in which the ZCML file is looked up.
+
+ `zcml`
+ is a string containing the name of the ZCML file to parse. In
+ many projects this configuration file for tests is called
+ ``ftesting.zcml``.
+
+ You normally run this function before calling :func:`create_app`
+ as it registers basic components and event subscribers that become
+ active when a ZODB_ connection is created and opened.
+
+ This function is normally called in a `pytest_funcarg__`_ function
+ which will be executed before your test.
+
+ It adds cached setup and teardown code to be run before and after
+ your session. That means the configuration setup and teardown will
+ happen only once for a complete test run.
+
+ .. seealso:: `pytest_funcarg__`_ docs on pytest.org.
+
+ .. _pytest_funcarg__: http://pytest.org/funcargs.html
+
+ """
def setup_function():
return setup_config(module, zcml)
@@ -78,6 +115,25 @@
scope='session')
def setup_config(package, zcml_file):
+ """Setup a configuration.
+
+ Execute the configuration specified by `package` and `zcml_file`.
+
+ `package`
+ is a Python package in which the `zcml_file` is looked up.
+
+ `zcml_file`
+ is a string giving the name of a ZCML_ file to parse.
+
+ This is a helper function used by :func:`configure`. You normally
+ use :func:`configure` to setup tests.
+
+ The function registers the most common directives and then tries
+ to parse the and execute the configuration as given in the ZCML_
+ file.
+
+ Returns the resulting ZCML_ configuration.
+ """
zcml_file = os.path.join(os.path.dirname(package.__file__),
zcml_file)
@@ -90,9 +146,25 @@
context=context, execute=True)
def teardown_config(config):
+ """Clean up a ZCML configuration.
+
+ Unregisters components registered.
+ """
cleanUp()
def setup_db():
+ """Create a ZODB_ DB with a demo storage.
+
+ Creates a ZODB :class:`DemoStorage`, turns it into a ZODB_ DB
+ named ``main`` and sends a :class:`DatebaseOpened` event to inform
+ other components.
+
+ You normally have to configure the Zope Component Architechture
+ using :func:`setup_config` or (preferably) :func:`configure`
+ before you call this function.
+
+ Returns a ZODB DB.
+ """
name = 'main'
storage = DemoStorage(name)
db = DB(storage, database_name=name)
@@ -107,6 +179,11 @@
return db
def teardown_db(db):
+ """Unregister ZODB_ DB.
+
+ Unregisters the ``main`` database with the global site manager and
+ closes the DB.
+ """
# Need to unregister DB
base = component.getGlobalSiteManager()
base.unregisterUtility(
@@ -114,15 +191,47 @@
db.close()
def setup_connection(db):
+ """Open a connection to `db`.
+
+ `db`
+ is a ZODB_ DB as returned from :func:`setup_db`.
+
+ Returns a connection to the database.
+ """
return db.open()
def teardown_connection(connection):
+ """Shutdown ZODB_ DB connection.
+
+ `connection`
+ is a (normally open) ZODB_ DB connection as returned by
+ :func:`setup_connection`.
+
+ Aborts any running transaction and closes the connection.
+ """
transaction.abort()
connection.close()
def setup_root(connection):
+ """Get the application root.
+
+ Returns the Zope application root from a ZODB DB connected to by
+ `connection`.
+
+ `connection`
+ is an (already opened) connection to a ZODB_ DB.
+
+ Return the application root, i.e. the object that contains the
+ global site manager and other fundamental ZCA-related stuff.
+ """
return connection.root()[ZopePublication.root_name]
def teardown_root(root):
+ """Shutdown the application root.
+
+ `root`
+ is a ZODB_ DB application root.
+
+ This function does actually nothing.
+ """
pass
-
More information about the checkins
mailing list