[Python-checkins] python/nondist/peps pep-0316.txt,1.1,1.2

2003年6月08日 21:34:06 -0700

Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1:/tmp/cvs-serv3991
Modified Files:
	pep-0316.txt 
Log Message:
updates from Terence Way's website; editorial corrections
Index: pep-0316.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0316.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** pep-0316.txt	9 Jun 2003 04:04:03 -0000	1.1
--- pep-0316.txt	9 Jun 2003 04:34:03 -0000	1.2
***************
*** 4,8 ****
 Last-Modified: $Date$
 Author: Terence Way <terry@wayforward.net>
! Status: Draft
 Type: Standards Track
 Content-Type: text/x-rst
--- 4,8 ----
 Last-Modified: $Date$
 Author: Terence Way <terry@wayforward.net>
! Status: Deferred
 Type: Standards Track
 Content-Type: text/x-rst
***************
*** 23,31 ****
 expressions for functions and methods.

! These expressions (contracts) are similar to assertions: they must
! be true or the program is stopped, and run-time checking of the
! contracts is typically only enabled while debugging. Contracts
! are higher-level than straight assertions and are typically
! included in documentation.

--- 23,30 ----
 expressions for functions and methods.

! These expressions (contracts) are similar to assertions: they must be
! true or the program is stopped, and run-time checking of the contracts
! is typically only enabled while debugging. Contracts are higher-level
! than straight assertions and are typically included in documentation.

***************
*** 55,64 ****
 So why add this to the language? Why not have several different
 implementations, or let programmers implement their own assertions?
! The answer is the behavior of pre-conditions under inheritance.

! If Alice produces a class library protected by her own assertions
! package, Bob cannot derive classes from Alice's library and weaken the
! pre-conditions, unless both have agreed on an assertions system that
! supports weakening pre-conditions. The natural place to find this
 assertions system is in the language's run-time library.

--- 54,65 ----
 So why add this to the language? Why not have several different
 implementations, or let programmers implement their own assertions?
! The answer is the behavior of contracts under inheritance.

! Suppose Alice and Bob use different assertions packages. If Alice
! produces a class library protected by assertions, Bob cannot derive
! classes from Alice's library and expect proper checking of
! post-conditions and invariants. If they both use the same assertions
! package, then Bob can override Alice's methods yet still test against
! Alice's contract assertions. The natural place to find this
 assertions system is in the language's run-time library.

***************
*** 82,85 ****
--- 83,87 ----

 class conn:
+ 
 """A network connection

***************
*** 92,95 ****
--- 94,98 ----

 class circbuf:
+ 
 """A circular buffer.

***************
*** 130,133 ****
--- 133,137 ----

 class circbuf:
+ 
 def __init__(self, leng):
 """Construct an empty circular buffer.
***************
*** 139,142 ****
--- 143,153 ----
 """

+ A double-colon (::) can be used instead of a single colon (:) to
+ support docstrings written using reStructuredText [#rst]_. For
+ example, the following two docstrings describe the same contract::
+ 
+ """pre: leng > 0"""
+ """pre:: leng > 0"""
+ 
 Expressions in pre- and post-conditions are defined in the module
 namespace -- they have access to nearly all the variables that the
***************
*** 152,155 ****
--- 163,167 ----

 class circbuf:
+ 
 def get(self):
 """Pull an entry from a non-empty circular buffer.
***************
*** 241,244 ****
--- 253,260 ----
 PostconditionViolationError
 InvariantViolationError
+ InvalidPreconditionError
+ 
+ The ``InvalidPreconditionError`` is raised when pre-conditions are
+ illegally strengthened, see the next section on Inheritance.

 Example::
***************
*** 262,274 ****
 post-conditions).

! A method's pre-conditions can be ignored if an overridden method's
! pre-conditions are met (method pre-conditions are ORed with all
! overridden method pre-conditions). This prevents derived classes from
! breaking assumptions made by clients that only know the base method's
! pre-conditions.

 A somewhat contrived example::

 class SimpleMailClient:
 def send(self, msg, dest):
 """Sends a message to a destination:
--- 278,291 ----
 post-conditions).

! An overridden method's pre-conditions can be ignored if the overriding
! method's pre-conditions are met. However, if the overriding method's
! pre-conditions fail, *all* of the overridden method's pre-conditions
! must also fail. If not, a separate exception is raised, the
! InvalidPreconditionError. This supports weakening pre-conditions.

 A somewhat contrived example::

 class SimpleMailClient:
+ 
 def send(self, msg, dest):
 """Sends a message to a destination:
***************
*** 306,311 ****
 """

! Because pre-conditions are ORed, a ``ComplexMailClient`` can replace a
! ``SimpleMailClient`` with no fear of breaking existing code.

--- 323,328 ----
 """

! Because pre-conditions can only be weakened, a ``ComplexMailClient`` can
! replace a ``SimpleMailClient`` with no fear of breaking existing code.

***************
*** 375,378 ****
--- 392,398 ----
 ==========

+ .. [#imp] Implementation described in this document.
+ (http://www.wayforward.net/pycontract/)
+ 
 .. [#dbc] Design By Contract is a registered trademark of Eiffel
 Software Inc.
***************
*** 394,399 ****
 (http://www.nongnu.org/pydbc/)

! .. [#imp] Implementation described in this document.
! (http://www.wayforward.net/pycontract/)

 .. [#xp] Extreme Programming Explained, Kent Beck,
--- 414,418 ----
 (http://www.nongnu.org/pydbc/)

! .. [#rst] ReStructuredText (http://docutils.sourceforge.net/rst.html)

 .. [#xp] Extreme Programming Explained, Kent Beck,