[Zodb-checkins] SVN: ZODB/branches/3.3/ Act as if a 3.3c1 release
were being made. Maybe it will
Tim Peters
tim.one at comcast.net
Tue Sep 14 16:17:24 EDT 2004
Log message for revision 27526:
Act as if a 3.3c1 release were being made. Maybe it will
be. Besides "the usual" release fiddling, repaired many
out-of-date pieces of the ZODB programming guide; I'm sure
many remain, though.
Changed:
U ZODB/branches/3.3/NEWS.txt
U ZODB/branches/3.3/README.txt
U ZODB/branches/3.3/doc/guide/prog-zodb.tex
U ZODB/branches/3.3/doc/guide/transactions.tex
U ZODB/branches/3.3/doc/guide/zeo.tex
U ZODB/branches/3.3/doc/guide/zodb.tex
U ZODB/branches/3.3/doc/zodb.pdf
U ZODB/branches/3.3/setup.py
U ZODB/branches/3.3/src/ZEO/__init__.py
U ZODB/branches/3.3/src/ZEO/version.txt
U ZODB/branches/3.3/src/ZODB/__init__.py
-=-
Modified: ZODB/branches/3.3/NEWS.txt
===================================================================
--- ZODB/branches/3.3/NEWS.txt 2004-09-14 18:18:17 UTC (rev 27525)
+++ ZODB/branches/3.3/NEWS.txt 2004-09-14 20:17:23 UTC (rev 27526)
@@ -1,16 +1,16 @@
-What's new in ZODB3 3.3 ?
-=========================
-Release date: DD-MMM-YYYY
+What's new in ZODB3 3.3 release candidate 1?
+============================================
+Release date: 14-Sep-2004
Connection
----------
-ZODB intends to raise ConnnectionStateError if an attempt is made to close
-a connection while modifications are pending (the connection is involved in
-a transaction that hasn't been ``abort()``'ed or ``commit()``'ed). It was
-missing the case where the only pending modifications were made in
-subtransactions. This has been fixed. If an attempt to close a connection
-with pending subtransactions is made now::
+ZODB intends to raise ``ConnnectionStateError`` if an attempt is made to
+close a connection while modifications are pending (the connection is
+involved in a transaction that hasn't been ``abort()``'ed or
+``commit()``'ed). It was missing the case where the only pending
+modifications were made in subtransactions. This has been fixed. If an
+attempt to close a connection with pending subtransactions is made now::
ConnnectionStateError: Cannot close a connection with a pending subtransaction
@@ -91,7 +91,7 @@
>>> ...
>>> txn.commit()
- can't work as intended ib 3.3, because ``txn`` is no longer the current
+ can't work as intended in 3.3, because ``txn`` is no longer the current
``Transaction`` object the instant ``txn.begin()`` returns.
BTrees
@@ -110,12 +110,12 @@
confusion was really due to that the detail on a ConflictError exception
didn't make sense. It called the current revision "was", and the old
revision "now". The detail is much more informative now. For example,
-if the exception said:
+if the exception said::
ConflictError: database conflict error (oid 0xcb22,
serial was 0x03441422948b4399, now 0x034414228c3728d5)
-before, it now says:
+before, it now says::
ConflictError: database conflict error (oid 0xcb22,
serial this txn started with 0x034414228c3728d5 2002-04-14 20:50:32.863000,
@@ -131,20 +131,20 @@
Tools
-----
-FileStorage.FileIterator was confused about how to read a transaction's
+``FileStorage.FileIterator`` was confused about how to read a transaction's
user and description fields, which caused several tools to display
binary gibberish for these values.
-ZODB.utils.oid_repr() changed to add a leading "0x", and to strip leading
-zeroes. This is used, e.g., in the detail of a POSKeyError exception, to
-identify the missing oid. Before, the output was ambiguous. For example,
-oid 17 was displayed as 0000000000000011. As a Python integer, that's
-octal 9. Or was it meant to be decimal 11? Or was it meant to be hex?
-Now it displays as 0x11.
+``ZODB.utils.oid_repr()`` changed to add a leading "0x", and to strip
+leading zeroes. This is used, e.g., in the detail of a ``POSKeyError``
+exception, to identify the missing oid. Before, the output was ambiguous.
+For example, oid 17 was displayed as 0000000000000011. As a Python
+integer, that's octal 9. Or was it meant to be decimal 11? Or was it
+meant to be hex? Now it displays as 0x11.
fsrefs.py:
- When run with -v, produced tracebacks for objects whose creation was
+ When run with ``-v``, produced tracebacks for objects whose creation was
merely undone. This was confusing. Tracebacks are now produced only
if there's "a real" problem loading an oid.
@@ -156,13 +156,13 @@
Now makes two passes, so that an accurate report can be given of all
invalid references.
-analyze.py produced spurious "len of unsized object" messages when
+``analyze.py`` produced spurious "len of unsized object" messages when
finding a data record for an object uncreation or version abort. These
no longer appear.
-fsdump.py's get_pickle_metadata() function (which is used by several
+``fsdump.py``'s ``get_pickle_metadata()`` function (which is used by several
tools) was confused about what to do when the ZODB pickle started with
-a pickle GLOBAL opcode. It actually loaded the class then, which it
+a pickle ``GLOBAL`` opcode. It actually loaded the class then, which it
intends never to do, leading to stray messages on stdout when the class
wasn't available, and leading to a strange return value even when it was
available (the repr of the type object was returned as "the module name",
Modified: ZODB/branches/3.3/README.txt
===================================================================
--- ZODB/branches/3.3/README.txt 2004-09-14 18:18:17 UTC (rev 27525)
+++ ZODB/branches/3.3/README.txt 2004-09-14 20:17:23 UTC (rev 27526)
@@ -1,5 +1,5 @@
-ZODB3 3.3 beta 2
-================
+ZODB3 3.3 release candidate 1
+=============================
Introduction
------------
Modified: ZODB/branches/3.3/doc/guide/prog-zodb.tex
===================================================================
--- ZODB/branches/3.3/doc/guide/prog-zodb.tex 2004-09-14 18:18:17 UTC (rev 27525)
+++ ZODB/branches/3.3/doc/guide/prog-zodb.tex 2004-09-14 20:17:23 UTC (rev 27526)
@@ -239,15 +239,25 @@
\end{verbatim}
The \module{transaction} module defines a few top-level functions for
-working with transactions. \method{commit()} writes any modified
-objects to disk, making the changes permanent. \method{abort()} rolls
+working with transactions. \function{commit()} writes any modified
+objects to disk, making the changes permanent. \function{abort()} rolls
back any changes that have been made, restoring the original state of
the objects. If you're familiar with database transactional
-semantics, this is all what you'd expect. \method{get()} returns a
+semantics, this is all what you'd expect. \function{get()} returns a
\class{Transaction} object that has additional methods like
-\method{status()}, to check the current state of the transaction, and
\method{note()}, to add a note to the transaction metadata.
+More precisely, the \module{transaction} module exposes an instance of
+the \class{ThreadTransactionManager} transaction manager class as
+\code{transaction.manager}, and the \module{transaction} functions
+\function{get()} and \function{begin()} redirect to the same-named
+methods of \code{transaction.manager}. The \function{commit()} and
+\function{abort()} functions apply the methods of the same names to
+the \class{Transaction} object returned by \code{transaction.manager.get()}.
+This is for convenience. It's also possible to create your own transaction
+manager instances, and to tell \code{DB.open()} to use your transaction
+manager instead.
+
Because the integration with Python is so complete, it's a lot like
having transactional semantics for your program's variables, and you
can experiment with transactions at the Python interpreter's prompt:
Modified: ZODB/branches/3.3/doc/guide/transactions.tex
===================================================================
--- ZODB/branches/3.3/doc/guide/transactions.tex 2004-09-14 18:18:17 UTC (rev 27525)
+++ ZODB/branches/3.3/doc/guide/transactions.tex 2004-09-14 20:17:23 UTC (rev 27526)
@@ -4,13 +4,37 @@
% Undoing
% Versions
% Multithreaded ZODB Programs
-
+
\section{Transactions and Versioning}
-%\subsection{Committing and Aborting}
-% XXX There seems very little to say about commit/abort...
+\subsection{Committing and Aborting}
+Changes made during a transaction don't appear in the database until
+the transaction commits. This is done by calling the \method{commit()}
+method of the current \class{Transaction} object, where the latter is
+obtained from the \method{get()} method of the current transaction
+manager. If the default thread transaction manager is being used, then
+\code{transaction.commit()} suffices.
+
+Similarly, a transaction can be explicitly aborted (all changes within
+the transaction thrown away) by invoking the \method{abort()} method
+of the current \class{Transaction} object, or simply
+\code{transaction.abort()} if using the default thread transaction manager.
+
+Prior to ZODB 3.3, if a commit failed (meaning the \code{commit()} call
+raised an exception), the transaction was implicitly aborted and a new
+transaction was implicitly started. This could be very surprising if the
+exception was suppressed, and especially if the failing commit was one
+in a sequence of subtransaction commits.
+
+So, starting with ZODB 3.3, if a commit fails, all further attempts to
+commit, join, or register with the transaction raise
+\exception{ZODB.POSException.TransactionFailedError}. You must explicitly
+start a new transaction then, either by calling the \method{abort()} method
+of the current transaction, or by calling the \method{begin()} method of the
+current transaction's transaction manager.
+
\subsection{Subtransactions}
Subtransactions can be created within a transaction. Each
@@ -29,20 +53,20 @@
objects are then written to permanent storage and can be purged from
the cache to free more space.
-To commit a subtransaction instead of a full transaction,
+To commit a subtransaction instead of a full transaction,
pass a true value to the \method{commit()}
or \method{abort()} method of the \class{Transaction} object.
\begin{verbatim}
# Commit a subtransaction
-get_transaction().commit(1)
+transaction.commit(True)
# Abort a subtransaction
-get_transaction().abort(1)
+transaction.abort(True)
\end{verbatim}
-A new subtransaction is automatically started on committing or
-aborting the previous subtransaction.
+A new subtransaction is automatically started upon successful committing
+or aborting the previous subtransaction.
\subsection{Undoing Changes}
@@ -57,7 +81,7 @@
If a database supports undo, then the \method{undoLog(\var{start},
\var{end}\optional{, func})} method on the \class{DB} instance returns
the log of past transactions, returning transactions between the times
-\var{start} and \var{end}, measured in seconds from the epoch.
+\var{start} and \var{end}, measured in seconds from the epoch.
If present, \var{func} is a function that acts as a filter on the
transactions to be returned; it's passed a dictionary representing
each transaction, and only transactions for which \var{func} returns
@@ -65,7 +89,7 @@
caller of \method{undoLog()}. The dictionary contains keys for
various properties of the transaction. The most important keys are
\samp{id}, for the transaction ID, and \samp{time}, for the time at
-which the transaction was committed.
+which the transaction was committed.
\begin{verbatim}
>>> print storage.undoLog(0, sys.maxint)
@@ -83,7 +107,7 @@
To store a description and a user name on a commit, get the current
transaction and call the \method{note(\var{text})} method to store a
description, and the
-\method{setUser(\var{user_name})} method to store the user name.
+\method{setUser(\var{user_name})} method to store the user name.
While \method{setUser()} overwrites the current user name and replaces
it with the new value, the \method{note()} method always adds the text
to the transaction's description, so it can be called several times to
@@ -91,8 +115,8 @@
transaction.
\begin{verbatim}
-get_transaction().setUser('amk')
-get_transaction().note('Change ownership')
+transaction.get().setUser('amk')
+transaction.get().note('Change ownership')
\end{verbatim}
To undo a transaction, call the \method{DB.undo(\var{id})} method,
@@ -115,6 +139,11 @@
\subsection{Versions}
+\begin{notice}[warning]
+ Versions should be avoided. They're going to be deprecated,
+ replaced by better approaches to long-running transactions.
+\end{notice}
+
While many subtransactions can be contained within a single regular
transaction, it's also possible to contain many regular transactions
within a long-running transaction, called a version in ZODB
@@ -155,7 +184,7 @@
from ZODB.POSException import VersionLockError
try:
- get_transaction().commit()
+ transaction.commit()
except VersionLockError, (obj_id, version):
print ('Cannot commit; object %s '
'locked by version %s' % (obj_id, version))
@@ -169,5 +198,5 @@
ZODB databases can be accessed from multithreaded Python programs.
The \class{Storage} and \class{DB} instances can be shared among
several threads, as long as individual \class{Connection} instances
-are created for each thread.
+are created for each thread.
Modified: ZODB/branches/3.3/doc/guide/zeo.tex
===================================================================
--- ZODB/branches/3.3/doc/guide/zeo.tex 2004-09-14 18:18:17 UTC (rev 27525)
+++ ZODB/branches/3.3/doc/guide/zeo.tex 2004-09-14 20:17:23 UTC (rev 27526)
@@ -99,6 +99,7 @@
\begin{verbatim}
from ZEO import ClientStorage
from ZODB import DB
+import transaction
# Change next line to connect to your ZEO server
addr = 'kronos.example.com', 1975
@@ -112,7 +113,7 @@
root['dict'] = {'a':1, 'b':4}
# Commit the transaction
-get_transaction().commit()
+transaction.commit()
\end{verbatim}
If this code runs properly, then your ZEO server is working correctly.
Modified: ZODB/branches/3.3/doc/guide/zodb.tex
===================================================================
--- ZODB/branches/3.3/doc/guide/zodb.tex 2004-09-14 18:18:17 UTC (rev 27525)
+++ ZODB/branches/3.3/doc/guide/zodb.tex 2004-09-14 20:17:23 UTC (rev 27526)
@@ -1,7 +1,7 @@
\documentclass{howto}
\title{ZODB/ZEO Programming Guide}
-\release{3.3b2}
+\release{3.3c1}
\date{\today}
\author{A.M.\ Kuchling}
Modified: ZODB/branches/3.3/doc/zodb.pdf
===================================================================
(Binary files differ)
Modified: ZODB/branches/3.3/setup.py
===================================================================
--- ZODB/branches/3.3/setup.py 2004-09-14 18:18:17 UTC (rev 27525)
+++ ZODB/branches/3.3/setup.py 2004-09-14 20:17:23 UTC (rev 27526)
@@ -216,7 +216,7 @@
doclines = __doc__.split("\n")
setup(name="ZODB3",
- version="3.3b2",
+ version="3.3c1",
maintainer="Zope Corporation",
maintainer_email="zodb-dev at zope.org",
url = "http://www.zope.org/Wikis/ZODB",
Modified: ZODB/branches/3.3/src/ZEO/__init__.py
===================================================================
--- ZODB/branches/3.3/src/ZEO/__init__.py 2004-09-14 18:18:17 UTC (rev 27525)
+++ ZODB/branches/3.3/src/ZEO/__init__.py 2004-09-14 20:17:23 UTC (rev 27526)
@@ -22,4 +22,4 @@
"""
# The next line must use double quotes, so release.py recognizes it.
-version = "2.3b2"
+version = "2.3c1"
Modified: ZODB/branches/3.3/src/ZEO/version.txt
===================================================================
--- ZODB/branches/3.3/src/ZEO/version.txt 2004-09-14 18:18:17 UTC (rev 27525)
+++ ZODB/branches/3.3/src/ZEO/version.txt 2004-09-14 20:17:23 UTC (rev 27526)
@@ -1 +1 @@
-2.3b2
+2.3c1
Modified: ZODB/branches/3.3/src/ZODB/__init__.py
===================================================================
--- ZODB/branches/3.3/src/ZODB/__init__.py 2004-09-14 18:18:17 UTC (rev 27525)
+++ ZODB/branches/3.3/src/ZODB/__init__.py 2004-09-14 20:17:23 UTC (rev 27526)
@@ -13,7 +13,7 @@
##############################################################################
# The next line must use double quotes, so release.py recognizes it.
-__version__ = "3.3b2"
+__version__ = "3.3c1"
import sys
import __builtin__
More information about the Zodb-checkins
mailing list