diff --git a/pep-0211.txt b/pep-0211.txt index 9f8e2ea062b..0a1c73c6eab 100644 --- a/pep-0211.txt +++ b/pep-0211.txt @@ -5,189 +5,198 @@ Last-Modified: $Date$ Author: gvwilson@ddj.com (Greg Wilson) Status: Deferred Type: Standards Track +Content-Type: text/x-rst Created: 15-Jul-2000 Python-Version: 2.1 Post-History: Introduction +============ - This PEP describes a proposal to define "@" (pronounced "across") - as a new outer product operator in Python 2.2. When applied to - sequences (or other iterable objects), this operator will combine - their iterators, so that: +This PEP describes a proposal to define ``@`` (pronounced "across") +as a new outer product operator in Python 2.2. When applied to +sequences (or other iterable objects), this operator will combine +their iterators, so that:: - for (i, j) in S @ T: - pass + for (i, j) in S @ T: + pass - will be equivalent to: +will be equivalent to:: - for i in S: - for j in T: - pass + for i in S: + for j in T: + pass - Classes will be able to overload this operator using the special - methods "__across__", "__racross__", and "__iacross__". In - particular, the new Numeric module (PEP 209) will overload this - operator for multi-dimensional arrays to implement matrix - multiplication. +Classes will be able to overload this operator using the special +methods ``__across__``, ``__racross__``, and ``__iacross__``. In +particular, the new Numeric module (PEP 209) will overload this +operator for multi-dimensional arrays to implement matrix +multiplication. Background - - Number-crunching is now just a small part of computing, but many - programmers --- including many Python users --- still need to - express complex mathematical operations in code. Most numerical - languages, such as APL, Fortran-90, MATLAB, IDL, and Mathematica, - therefore provide two forms of the common arithmetic operators. - One form works element-by-element, e.g. multiplies corresponding - elements of its matrix arguments. The other implements the - "mathematical" definition of that operation, e.g. performs - row-column matrix multiplication. - - Zhu and Lielens have proposed doubling up Python's operators in - this way [1]. Their proposal would create six new binary infix - operators, and six new in-place operators. - - The original version of this proposal was much more conservative. - The author consulted the developers of GNU Octave [2], an open - source clone of MATLAB. Its developers agreed that providing an - infix operator for matrix multiplication was important: numerical - programmers really do care whether they have to write "mmul(A,B)" - instead of "A op B". - - On the other hand, when asked how important it was to have infix - operators for matrix solution and other operations, Prof. James - Rawlings replied [3]: - - I DON'T think it's a must have, and I do a lot of matrix - inversion. I cannot remember if its A\b or b\A so I always - write inv(A)*b instead. I recommend dropping \. - - Based on this discussion, and feedback from students at the US - national laboratories and elsewhere, we recommended adding only - one new operator, for matrix multiplication, to Python. +========== + +Number-crunching is now just a small part of computing, but many +programmers --- including many Python users --- still need to +express complex mathematical operations in code. Most numerical +languages, such as APL, Fortran-90, MATLAB, IDL, and Mathematica, +therefore provide two forms of the common arithmetic operators. +One form works element-by-element, e.g. multiplies corresponding +elements of its matrix arguments. The other implements the +"mathematical" definition of that operation, e.g. performs +row-column matrix multiplication. + +Zhu and Lielens have proposed doubling up Python's operators in +this way [1]_. Their proposal would create six new binary infix +operators, and six new in-place operators. + +The original version of this proposal was much more conservative. +The author consulted the developers of GNU Octave [2]_, an open +source clone of MATLAB. Its developers agreed that providing an +infix operator for matrix multiplication was important: numerical +programmers really do care whether they have to write ``mmul(A,B)`` +instead of ``A op B``. + +On the other hand, when asked how important it was to have infix +operators for matrix solution and other operations, Prof. James +Rawlings replied [3]_: + + I DON'T think it's a must have, and I do a lot of matrix + inversion. I cannot remember if its A\b or b\A so I always + write inv(A)*b instead. I recommend dropping \. + +Based on this discussion, and feedback from students at the US +national laboratories and elsewhere, we recommended adding only +one new operator, for matrix multiplication, to Python. Iterators +========= - The planned addition of iterators to Python 2.2 opens up a broader - scope for this proposal. As part of the discussion of PEP 201, - Lockstep Iteration[4], the author of this proposal conducted an - informal usability experiment[5]. The results showed that users - are psychologically receptive to "cross-product" loop syntax. For - example, most users expected: +The planned addition of iterators to Python 2.2 opens up a broader +scope for this proposal. As part of the discussion of PEP 201, +Lockstep Iteration [4]_, the author of this proposal conducted an +informal usability experiment [5]_. The results showed that users +are psychologically receptive to "cross-product" loop syntax. For +example, most users expected:: - S = [10, 20, 30] - T = [1, 2, 3] - for x in S; y in T: - print x+y, + S = [10, 20, 30] + T = [1, 2, 3] + for x in S; y in T: + print x+y, - to print "11 12 13 21 22 23 31 32 33". We believe that users will - have the same reaction to: +to print ``11 12 13 21 22 23 31 32 33``. We believe that users will +have the same reaction to:: - for (x, y) in S @ T: - print x+y + for (x, y) in S @ T: + print x+y - i.e. that they will naturally interpret this as a tidy way to - write loop nests. +i.e. that they will naturally interpret this as a tidy way to +write loop nests. - This is where iterators come in. Actually constructing the - cross-product of two (or more) sequences before executing the loop - would be very expensive. On the other hand, "@" could be defined - to get its arguments' iterators, and then create an outer iterator - which returns tuples of the values returned by the inner - iterators. +This is where iterators come in. Actually constructing the +cross-product of two (or more) sequences before executing the loop +would be very expensive. On the other hand, ``@`` could be defined +to get its arguments' iterators, and then create an outer iterator +which returns tuples of the values returned by the inner +iterators. Discussion +========== - 1. Adding a named function "across" would have less impact on - Python than a new infix operator. However, this would not make - Python more appealing to numerical programmers, who really do - care whether they can write matrix multiplication using an - operator, or whether they have to write it as a function call. +1. Adding a named function "across" would have less impact on + Python than a new infix operator. However, this would not make + Python more appealing to numerical programmers, who really do + care whether they can write matrix multiplication using an + operator, or whether they have to write it as a function call. - 2. "@" would have be chainable in the same way as comparison - operators, i.e.: +2. ``@`` would have be chainable in the same way as comparison + operators, i.e.:: - (1, 2) @ (3, 4) @ (5, 6) + (1, 2) @ (3, 4) @ (5, 6) - would have to return (1, 3, 5) ... (2, 4, 6), and *not* - ((1, 3), 5) ... ((2, 4), 6). This should not require special - support from the parser, as the outer iterator created by the - first "@" could easily be taught how to combine itself with - ordinary iterators. + would have to return ``(1, 3, 5) ... (2, 4, 6)``, and *not* + ``((1, 3), 5) ... ((2, 4), 6)```. This should not require special + support from the parser, as the outer iterator created by the + first ``@`` could easily be taught how to combine itself with + ordinary iterators. - 3. There would have to be some way to distinguish restartable - iterators from ones that couldn't be restarted. For example, - if S is an input stream (e.g. a file), and L is a list, then "S - @ L" is straightforward, but "L @ S" is not, since iteration - through the stream cannot be repeated. This could be treated - as an error, or by having the outer iterator detect - non-restartable inner iterators and cache their values. +3. There would have to be some way to distinguish restartable + iterators from ones that couldn't be restarted. For example, + if ``S`` is an input stream (e.g. a file), and ``L`` is a list, then ``S + @ L`` is straightforward, but ``L @ S`` is not, since iteration + through the stream cannot be repeated. This could be treated + as an error, or by having the outer iterator detect + non-restartable inner iterators and cache their values. - 4. Whiteboard testing of this proposal in front of three novice - Python users (all of them experienced programmers) indicates - that users will expect: +4. Whiteboard testing of this proposal in front of three novice + Python users (all of them experienced programmers) indicates + that users will expect:: - "ab" @ "cd" + "ab" @ "cd" - to return four strings, not four tuples of pairs of - characters. Opinion was divided on what: + to return four strings, not four tuples of pairs of + characters. Opinion was divided on what:: - ("a", "b") @ "cd" + ("a", "b") @ "cd" - ought to return... + ought to return... Alternatives +============ - 1. Do nothing --- keep Python simple. +1. Do nothing --- keep Python simple. - This is always the default choice. + This is always the default choice. - 2. Add a named function instead of an operator. +2. Add a named function instead of an operator. - Python is not primarily a numerical language; it may not be worth - complexifying it for this special case. However, support for real - matrix multiplication *is* frequently requested, and the proposed - semantics for "@" for built-in sequence types would simplify - expression of a very common idiom (nested loops). + Python is not primarily a numerical language; it may not be worth + complexifying it for this special case. However, support for real + matrix multiplication *is* frequently requested, and the proposed + semantics for ``@`` for built-in sequence types would simplify + expression of a very common idiom (nested loops). - 3. Introduce prefixed forms of all existing operators, such as - "~*" and "~+", as proposed in PEP 225 [1]. +3. Introduce prefixed forms of all existing operators, such as + ``~*`` and ``~+``, as proposed in PEP 225 [1]_. - Our objections to this are that there isn't enough demand to - justify the additional complexity (see Rawlings' comments [3]), - and that the proposed syntax fails the "low toner" readability - test. + Our objections to this are that there isn't enough demand to + justify the additional complexity (see Rawlings' comments [3]_), + and that the proposed syntax fails the "low toner" readability + test. Acknowledgments +=============== - I am grateful to Huaiyu Zhu for initiating this discussion, and to - James Rawlings and students in various Python courses for their - discussions of what numerical programmers really care about. +I am grateful to Huaiyu Zhu for initiating this discussion, and to +James Rawlings and students in various Python courses for their +discussions of what numerical programmers really care about. References +========== + +.. [1] PEP 225, Elementwise/Objectwise Operators, Zhu, Lielens + http://www.python.org/dev/peps/pep-0225/ - [1] PEP 225, Elementwise/Objectwise Operators, Zhu, Lielens - http://www.python.org/dev/peps/pep-0225/ +.. [2] http://bevo.che.wisc.edu/octave/ - [2] http://bevo.che.wisc.edu/octave/ +.. [3] http://www.egroups.com/message/python-numeric/4 - [3] http://www.egroups.com/message/python-numeric/4 +.. [4] PEP 201, Lockstep Iteration, Warsaw + http://www.python.org/dev/peps/pep-0201/ - [4] PEP 201, Lockstep Iteration, Warsaw - http://www.python.org/dev/peps/pep-0201/ +.. [5] http://mail.python.org/pipermail/python-dev/2000-July/006427.html - [5] http://mail.python.org/pipermail/python-dev/2000-July/006427.html - -Local Variables: -mode: indented-text -indent-tabs-mode: nil -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + End: diff --git a/pep-0218.txt b/pep-0218.txt index b12d4e0ca0e..5739cf18122 100644 --- a/pep-0218.txt +++ b/pep-0218.txt @@ -5,207 +5,220 @@ Last-Modified: $Date$ Author: gvwilson@ddj.com (Greg Wilson), python@rcn.com (Raymond Hettinger) Status: Final Type: Standards Track +Content-Type: text/x-rst Created: 31-Jul-2000 Python-Version: 2.2 -Post-History: +Post-History: Introduction +============ - This PEP proposes adding a Set module to the standard Python - library, and to then make sets a built-in Python type if that - module is widely used. After explaining why sets are desirable, - and why the common idiom of using dictionaries in their place is - inadequate, we describe how we intend built-in sets to work, and - then how the preliminary Set module will behave. The last - section discusses the mutability (or otherwise) of sets and set - elements, and the solution which the Set module will implement. +This PEP proposes adding a Set module to the standard Python +library, and to then make sets a built-in Python type if that +module is widely used. After explaining why sets are desirable, +and why the common idiom of using dictionaries in their place is +inadequate, we describe how we intend built-in sets to work, and +then how the preliminary Set module will behave. The last +section discusses the mutability (or otherwise) of sets and set +elements, and the solution which the Set module will implement. Rationale - - Sets are a fundamental mathematical structure, and are very - commonly used in algorithm specifications. They are much less - frequently used in implementations, even when they are the "right" - structure. Programmers frequently use lists instead, even when - the ordering information in lists is irrelevant, and by-value - lookups are frequent. (Most medium-sized C programs contain a - depressing number of start-to-end searches through malloc'd - vectors to determine whether particular items are present or - not...) - - Programmers are often told that they can implement sets as - dictionaries with "don't care" values. Items can be added to - these "sets" by assigning the "don't care" value to them; - membership can be tested using "dict.has_key"; and items can be - deleted using "del". However, the other main operations on sets - (union, intersection, and difference) are not directly supported - by this representation, since their meaning is ambiguous for - dictionaries containing key/value pairs. +========= + +Sets are a fundamental mathematical structure, and are very +commonly used in algorithm specifications. They are much less +frequently used in implementations, even when they are the "right" +structure. Programmers frequently use lists instead, even when +the ordering information in lists is irrelevant, and by-value +lookups are frequent. (Most medium-sized C programs contain a +depressing number of start-to-end searches through malloc'd +vectors to determine whether particular items are present or +not...) + +Programmers are often told that they can implement sets as +dictionaries with "don't care" values. Items can be added to +these "sets" by assigning the "don't care" value to them; +membership can be tested using "dict.has_key"; and items can be +deleted using "del". However, the other main operations on sets +(union, intersection, and difference) are not directly supported +by this representation, since their meaning is ambiguous for +dictionaries containing key/value pairs. Proposal +======== - The long-term goal of this PEP is to add a built-in set type to - Python. This type will be an unordered collection of unique - values, just as a dictionary is an unordered collection of - key/value pairs. - - Iteration and comprehension will be implemented in the obvious - ways, so that: +The long-term goal of this PEP is to add a built-in set type to +Python. This type will be an unordered collection of unique +values, just as a dictionary is an unordered collection of +key/value pairs. - for x in S: +Iteration and comprehension will be implemented in the obvious +ways, so that:: - will step through the elements of S in arbitrary order, while: + for x in S: - set(x**2 for x in S) +will step through the elements of S in arbitrary order, while:: - will produce a set containing the squares of all elements in S, - Membership will be tested using "in" and "not in", and basic set - operations will be implemented by a mixture of overloaded - operators: + set(x**2 for x in S) - | union - & intersection - ^ symmetric difference - - asymmetric difference - == != equality and inequality tests - < <= >= > subset and superset tests +will produce a set containing the squares of all elements in S, +Membership will be tested using "in" and "not in", and basic set +operations will be implemented by a mixture of overloaded +operators: +========= ============================= +\| union +& intersection +^ symmetric difference +\- asymmetric difference +== != equality and inequality tests +< <= >= > subset and superset tests +========= ============================= - and methods: +and methods: - S.add(x) Add "x" to the set. +================== ============================================ +``S.add(x)`` Add "x" to the set. - S.update(s) Add all elements of sequence "s" to the set. +``S.update(s)`` Add all elements of sequence "s" to the set. - S.remove(x) Remove "x" from the set. If "x" is not - present, this method raises a LookupError - exception. +``S.remove(x)`` Remove "x" from the set. If "x" is not + present, this method raises a ``LookupError`` + exception. - S.discard(x) Remove "x" from the set if it is present, or - do nothing if it is not. +``S.discard(x)`` Remove "x" from the set if it is present, or + do nothing if it is not. - S.pop() Remove and return an arbitrary element, - raising a LookupError if the element is not - present. +``S.pop()`` Remove and return an arbitrary element, + raising a LookupError if the element is not + present. - S.clear() Remove all elements from this set. +``S.clear()`` Remove all elements from this set. - S.copy() Make a new set. +``S.copy()`` Make a new set. - s.issuperset() Check for a superset relationship. +``s.issuperset()`` Check for a superset relationship. - s.issubset() Check for a subset relationship. - +``s.issubset()`` Check for a subset relationship. +================== ============================================ - and two new built-in conversion functions: +and two new built-in conversion functions: - set(x) Create a set containing the elements of the - collection "x". +================ =============================================== +``set(x)`` Create a set containing the elements of the + collection "x". - frozenset(x) Create an immutable set containing the elements - of the collection "x". +``frozenset(x)`` Create an immutable set containing the elements + of the collection "x". +================ =============================================== - Notes: +Notes: - 1. We propose using the bitwise operators "|&" for intersection - and union. While "+" for union would be intuitive, "*" for - intersection is not (very few of the people asked guessed what - it did correctly). +1. We propose using the bitwise operators "\|\&" for intersection + and union. While "+" for union would be intuitive, "\*" for + intersection is not (very few of the people asked guessed what + it did correctly). - 2. We considered using "+" to add elements to a set, rather than - "add". However, Guido van Rossum pointed out that "+" is - symmetric for other built-in types (although "*" is not). Use - of "add" will also avoid confusion between that operation and - set union. +2. We considered using "+" to add elements to a set, rather than + "add". However, Guido van Rossum pointed out that "+" is + symmetric for other built-in types (although "\*" is not). Use + of "add" will also avoid confusion between that operation and + set union. Set Notation +============ - The PEP originally proposed {1,2,3} as the set notation and {-} for - the empty set. Experience with Python 2.3's sets.py showed that - the notation was not necessary. Also, there was some risk of making - dictionaries less instantly recognizable. +The PEP originally proposed {1,2,3} as the set notation and {-} for +the empty set. Experience with Python 2.3's sets.py showed that +the notation was not necessary. Also, there was some risk of making +dictionaries less instantly recognizable. - It was also contemplated that the braced notation would support set - comprehensions; however, Python 2.4 provided generator expressions - which fully met that need and did so it a more general way. - (See PEP 289 for details on generator expressions). +It was also contemplated that the braced notation would support set +comprehensions; however, Python 2.4 provided generator expressions +which fully met that need and did so it a more general way. +(See PEP 289 for details on generator expressions). - So, Guido ruled that there would not be a set syntax; however, the - issue could be revisited for Python 3000 (see PEP 3000). +So, Guido ruled that there would not be a set syntax; however, the +issue could be revisited for Python 3000 (see PEP 3000). History - - To gain experience with sets, a pure python module was introduced - in Python 2.3. Based on that implementation, the set and frozenset - types were introduced in Python 2.4. The improvements are: - - * Better hash algorithm for frozensets - * More compact pickle format (storing only an element list - instead of a dictionary of key:value pairs where the value - is always True). - * Use a __reduce__ function so that deep copying is automatic. - * The BaseSet concept was eliminated. - * The union_update() method became just update(). - * Auto-conversion between mutable and immutable sets was dropped. - * The _repr method was dropped (the need is met by the new - sorted() built-in function). - - Tim Peters believes that the class's constructor should take a - single sequence as an argument, and populate the set with that - sequence's elements. His argument is that in most cases, - programmers will be creating sets from pre-existing sequences, so - that this case should be the common one. However, this would - require users to remember an extra set of parentheses when - initializing a set with known values: +======= + +To gain experience with sets, a pure python module was introduced +in Python 2.3. Based on that implementation, the set and frozenset +types were introduced in Python 2.4. The improvements are: + +* Better hash algorithm for frozensets +* More compact pickle format (storing only an element list + instead of a dictionary of key:value pairs where the value + is always True). +* Use a ``__reduce__`` function so that deep copying is automatic. +* The BaseSet concept was eliminated. +* The ``union_update()`` method became just ``update()``. +* Auto-conversion between mutable and immutable sets was dropped. +* The ``_repr`` method was dropped (the need is met by the new + ``sorted()`` built-in function). + +Tim Peters believes that the class's constructor should take a +single sequence as an argument, and populate the set with that +sequence's elements. His argument is that in most cases, +programmers will be creating sets from pre-existing sequences, so +that this case should be the common one. However, this would +require users to remember an extra set of parentheses when +initializing a set with known values:: >>> Set((1, 2, 3, 4)) # case 1 - On the other hand, feedback from a small number of novice Python - users (all of whom were very experienced with other languages) - indicates that people will find a "parenthesis-free" syntax more - natural: +On the other hand, feedback from a small number of novice Python +users (all of whom were very experienced with other languages) +indicates that people will find a "parenthesis-free" syntax more +natural:: >>> Set(1, 2, 3, 4) # case 2 - Ultimately, we adopted the first strategy in which the initializer - takes a single iterable argument. +Ultimately, we adopted the first strategy in which the initializer +takes a single iterable argument. Mutability - - The most difficult question to resolve in this proposal was - whether sets ought to be able to contain mutable elements. A - dictionary's keys must be immutable in order to support fast, - reliable lookup. While it would be easy to require set elements - to be immutable, this would preclude sets of sets (which are - widely used in graph algorithms and other applications). - - Earlier drafts of PEP 218 had only a single set type, but the - sets.py implementation in Python 2.3 has two, Set and - ImmutableSet. For Python 2.4, the new built-in types were named - set and frozenset which are slightly less cumbersome. - - There are two classes implemented in the "sets" module. Instances - of the Set class can be modified by the addition or removal of - elements, and the ImmutableSet class is "frozen", with an - unchangeable collection of elements. Therefore, an ImmutableSet - may be used as a dictionary key or as a set element, but cannot be - updated. Both types of set require that their elements are - immutable, hashable objects. Parallel comments apply to the "set" - and "frozenset" built-in types. +========== + +The most difficult question to resolve in this proposal was +whether sets ought to be able to contain mutable elements. A +dictionary's keys must be immutable in order to support fast, +reliable lookup. While it would be easy to require set elements +to be immutable, this would preclude sets of sets (which are +widely used in graph algorithms and other applications). + +Earlier drafts of PEP 218 had only a single set type, but the +sets.py implementation in Python 2.3 has two, Set and +ImmutableSet. For Python 2.4, the new built-in types were named +set and frozenset which are slightly less cumbersome. + +There are two classes implemented in the "sets" module. Instances +of the Set class can be modified by the addition or removal of +elements, and the ImmutableSet class is "frozen", with an +unchangeable collection of elements. Therefore, an ImmutableSet +may be used as a dictionary key or as a set element, but cannot be +updated. Both types of set require that their elements are +immutable, hashable objects. Parallel comments apply to the "set" +and "frozenset" built-in types. Copyright +========= + +This document has been placed in the Public Domain. - This document has been placed in the Public Domain. - -Local Variables: -mode: indented-text -indent-tabs-mode: nil -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + End: diff --git a/pep-0223.txt b/pep-0223.txt index bd07ea0c930..5676505e6e0 100644 --- a/pep-0223.txt +++ b/pep-0223.txt @@ -1,205 +1,234 @@ PEP: 223 -Title: Change the Meaning of \x Escapes +Title: Change the Meaning of ``\x`` Escapes Version: $Revision$ Last-Modified: $Date$ Author: tim.peters@gmail.com (Tim Peters) Status: Final Type: Standards Track +Content-Type: text/x-rst Created: 20-Aug-2000 Python-Version: 2.0 Post-History: 23-Aug-2000 Abstract +======== - Change \x escapes, in both 8-bit and Unicode strings, to consume - exactly the two hex digits following. The proposal views this as - correcting an original design flaw, leading to clearer expression - in all flavors of string, a cleaner Unicode story, better - compatibility with Perl regular expressions, and with minimal risk - to existing code. +Change ``\x`` escapes, in both 8-bit and Unicode strings, to consume +exactly the two hex digits following. The proposal views this as +correcting an original design flaw, leading to clearer expression +in all flavors of string, a cleaner Unicode story, better +compatibility with Perl regular expressions, and with minimal risk +to existing code. Syntax +====== - The syntax of \x escapes, in all flavors of non-raw strings, becomes +The syntax of ``\x`` escapes, in all flavors of non-raw strings, becomes:: - \xhh + \xhh - where h is a hex digit (0-9, a-f, A-F). The exact syntax in 1.5.2 is - not clearly specified in the Reference Manual; it says +where h is a hex digit (0-9, a-f, A-F). The exact syntax in 1.5.2 is +not clearly specified in the Reference Manual; it says:: - \xhh... + \xhh... - implying "two or more" hex digits, but one-digit forms are also - accepted by the 1.5.2 compiler, and a plain \x is "expanded" to - itself (i.e., a backslash followed by the letter x). It's unclear - whether the Reference Manual intended either of the 1-digit or - 0-digit behaviors. +implying "two or more" hex digits, but one-digit forms are also +accepted by the 1.5.2 compiler, and a plain ``\x`` is "expanded" to +itself (i.e., a backslash followed by the letter x). It's unclear +whether the Reference Manual intended either of the 1-digit or +0-digit behaviors. Semantics +========= - In an 8-bit non-raw string, - \xij - expands to the character - chr(int(ij, 16)) - Note that this is the same as in 1.6 and before. +In an 8-bit non-raw string:: - In a Unicode string, - \xij - acts the same as - \u00ij - i.e. it expands to the obvious Latin-1 character from the initial - segment of the Unicode space. + \xij - An \x not followed by at least two hex digits is a compile-time error, - specifically ValueError in 8-bit strings, and UnicodeError (a subclass - of ValueError) in Unicode strings. Note that if an \x is followed by - more than two hex digits, only the first two are "consumed". In 1.6 - and before all but the *last* two were silently ignored. +expands to the character:: + + chr(int(ij, 16)) + +Note that this is the same as in 1.6 and before. + +In a Unicode string, +:: + + \xij + +acts the same as:: + + \u00ij + +i.e. it expands to the obvious Latin-1 character from the initial +segment of the Unicode space. + +An ``\x`` not followed by at least two hex digits is a compile-time error, +specifically ``ValueError`` in 8-bit strings, and UnicodeError (a subclass +of ``ValueError``) in Unicode strings. Note that if an ``\x`` is followed by +more than two hex digits, only the first two are "consumed". In 1.6 +and before all but the *last* two were silently ignored. Example +======= - In 1.5.2: +In 1.5.2:: - >>> "\x123465" # same as "\x65" - 'e' - >>> "\x65" - 'e' - >>> "\x1" - '\001' - >>> "\x\x" - '\\x\\x' - >>> + >>> "\x123465" # same as "\x65" + 'e' + >>> "\x65" + 'e' + >>> "\x1" + '\001' + >>> "\x\x" + '\\x\\x' + >>> - In 2.0: +In 2.0:: - >>> "\x123465" # \x12 -> \022, "3456" left alone - '\0223456' - >>> "\x65" - 'e' - >>> "\x1" - [ValueError is raised] - >>> "\x\x" - [ValueError is raised] - >>> + >>> "\x123465" # \x12 -> \022, "3456" left alone + '\0223456' + >>> "\x65" + 'e' + >>> "\x1" + [ValueError is raised] + >>> "\x\x" + [ValueError is raised] + >>> History and Rationale - - \x escapes were introduced in C as a way to specify variable-width - character encodings. Exactly which encodings those were, and how many - hex digits they required, was left up to each implementation. The - language simply stated that \x "consumed" *all* hex digits following, - and left the meaning up to each implementation. So, in effect, \x in C - is a standard hook to supply platform-defined behavior. - - Because Python explicitly aims at platform independence, the \x escape - in Python (up to and including 1.6) has been treated the same way - across all platforms: all *except* the last two hex digits were - silently ignored. So the only actual use for \x escapes in Python was - to specify a single byte using hex notation. - - Larry Wall appears to have realized that this was the only real use for - \x escapes in a platform-independent language, as the proposed rule for - Python 2.0 is in fact what Perl has done from the start (although you - need to run in Perl -w mode to get warned about \x escapes with fewer - than 2 hex digits following -- it's clearly more Pythonic to insist on - 2 all the time). - - When Unicode strings were introduced to Python, \x was generalized so - as to ignore all but the last *four* hex digits in Unicode strings. - This caused a technical difficulty for the new regular expression engine: - SRE tries very hard to allow mixing 8-bit and Unicode patterns and - strings in intuitive ways, and it no longer had any way to guess what, - for example, r"\x123456" should mean as a pattern: is it asking to match - the 8-bit character \x56 or the Unicode character \u3456? - - There are hacky ways to guess, but it doesn't end there. The ISO C99 - standard also introduces 8-digit \U12345678 escapes to cover the entire - ISO 10646 character space, and it's also desired that Python 2 support - that from the start. But then what are \x escapes supposed to mean? - Do they ignore all but the last *eight* hex digits then? And if less - than 8 following in a Unicode string, all but the last 4? And if less - than 4, all but the last 2? - - This was getting messier by the minute, and the proposal cuts the - Gordian knot by making \x simpler instead of more complicated. Note - that the 4-digit generalization to \xijkl in Unicode strings was also - redundant, because it meant exactly the same thing as \uijkl in Unicode - strings. It's more Pythonic to have just one obvious way to specify a - Unicode character via hex notation. +===================== + +``\x`` escapes were introduced in C as a way to specify variable-width +character encodings. Exactly which encodings those were, and how many +hex digits they required, was left up to each implementation. The +language simply stated that ``\x`` "consumed" *all* hex digits following, +and left the meaning up to each implementation. So, in effect, ``\x`` in C +is a standard hook to supply platform-defined behavior. + +Because Python explicitly aims at platform independence, the ``\x`` escape +in Python (up to and including 1.6) has been treated the same way +across all platforms: all *except* the last two hex digits were +silently ignored. So the only actual use for ``\x`` escapes in Python was +to specify a single byte using hex notation. + +Larry Wall appears to have realized that this was the only real use for +``\x`` escapes in a platform-independent language, as the proposed rule for +Python 2.0 is in fact what Perl has done from the start (although you +need to run in Perl -w mode to get warned about ``\x`` escapes with fewer +than 2 hex digits following -- it's clearly more Pythonic to insist on +2 all the time). + +When Unicode strings were introduced to Python, ``\x`` was generalized so +as to ignore all but the last *four* hex digits in Unicode strings. +This caused a technical difficulty for the new regular expression engine:: +SRE tries very hard to allow mixing 8-bit and Unicode patterns and +strings in intuitive ways, and it no longer had any way to guess what, +for example, ``r"\x123456"`` should mean as a pattern: is it asking to match +the 8-bit character ``\x56`` or the Unicode character ``\u3456``? + +There are hacky ways to guess, but it doesn't end there. The ISO C99 +standard also introduces 8-digit ``\U12345678`` escapes to cover the entire +ISO 10646 character space, and it's also desired that Python 2 support +that from the start. But then what are ``\x`` escapes supposed to mean? +Do they ignore all but the last *eight* hex digits then? And if less +than 8 following in a Unicode string, all but the last 4? And if less +than 4, all but the last 2? + +This was getting messier by the minute, and the proposal cuts the +Gordian knot by making ``\x`` simpler instead of more complicated. Note +that the 4-digit generalization to ``\xijkl`` in Unicode strings was also +redundant, because it meant exactly the same thing as ``\uijkl`` in Unicode +strings. It's more Pythonic to have just one obvious way to specify a +Unicode character via hex notation. Development and Discussion +========================== - The proposal was worked out among Guido van Rossum, Fredrik Lundh and - Tim Peters in email. It was subsequently explained and disussed on - Python-Dev under subject "Go \x yourself", starting 2000-08-03. - Response was overwhelmingly positive; no objections were raised. +The proposal was worked out among Guido van Rossum, Fredrik Lundh and +Tim Peters in email. It was subsequently explained and discussed on +Python-Dev under subject "Go \x yourself" [1]_, starting 2000-08-03. +Response was overwhelmingly positive; no objections were raised. Backward Compatibility +====================== - Changing the meaning of \x escapes does carry risk of breaking existing - code, although no instances of incompabitility have yet been discovered. - The risk is believed to be minimal. +Changing the meaning of ``\x`` escapes does carry risk of breaking existing +code, although no instances of incompatibility have yet been discovered. +The risk is believed to be minimal. - Tim Peters verified that, except for pieces of the standard test suite - deliberately provoking end cases, there are no instances of \xabcdef... - with fewer or more than 2 hex digits following, in either the Python - CVS development tree, or in assorted Python packages sitting on his - machine. +Tim Peters verified that, except for pieces of the standard test suite +deliberately provoking end cases, there are no instances of ``\xabcdef...`` +with fewer or more than 2 hex digits following, in either the Python +CVS development tree, or in assorted Python packages sitting on his +machine. - It's unlikely there are any with fewer than 2, because the Reference - Manual implied they weren't legal (although this is debatable!). If - there are any with more than 2, Guido is ready to argue they were buggy - anyway <0.9 wink>. +It's unlikely there are any with fewer than 2, because the Reference +Manual implied they weren't legal (although this is debatable!). If +there are any with more than 2, Guido is ready to argue they were buggy +anyway <0.9 wink>. - Guido reported that the O'Reilly Python books *already* document that - Python works the proposed way, likely due to their Perl editing - heritage (as above, Perl worked (very close to) the proposed way from - its start). +Guido reported that the O'Reilly Python books *already* document that +Python works the proposed way, likely due to their Perl editing +heritage (as above, Perl worked (very close to) the proposed way from +its start). - Finn Bock reported that what JPython does with \x escapes is - unpredictable today. This proposal gives a clear meaning that can be - consistently and easily implemented across all Python implementations. +Finn Bock reported that what JPython does with ``\x`` escapes is +unpredictable today. This proposal gives a clear meaning that can be +consistently and easily implemented across all Python implementations. Effects on Other Tools +====================== - Believed to be none. The candidates for breakage would mostly be - parsing tools, but the author knows of none that worry about the - internal structure of Python strings beyond the approximation "when - there's a backslash, swallow the next character". Tim Peters checked - python-mode.el, the std tokenize.py and pyclbr.py, and the IDLE syntax - coloring subsystem, and believes there's no need to change any of - them. Tools like tabnanny.py and checkappend.py inherit their immunity - from tokenize.py. +Believed to be none. The candidates for breakage would mostly be +parsing tools, but the author knows of none that worry about the +internal structure of Python strings beyond the approximation "when +there's a backslash, swallow the next character". Tim Peters checked +python-mode.el, the std tokenize.py and pyclbr.py, and the IDLE syntax +coloring subsystem, and believes there's no need to change any of +them. Tools like tabnanny.py and checkappend.py inherit their immunity +from tokenize.py. Reference Implementation +======================== - The code changes are so simple that a separate patch will not be produced. - Fredrik Lundh is writing the code, is an expert in the area, and will - simply check the changes in before 2.0b1 is released. +The code changes are so simple that a separate patch will not be produced. +Fredrik Lundh is writing the code, is an expert in the area, and will +simply check the changes in before 2.0b1 is released. BDFL Pronouncements +=================== + +Yes, ``ValueError``, not ``SyntaxError``. "Problems with literal interpretations +traditionally raise 'runtime' exceptions rather than syntax errors." - Yes, ValueError, not SyntaxError. "Problems with literal interpretations - traditionally raise 'runtime' exceptions rather than syntax errors." + +References +========== + +.. [1] Tim Peters, Go \x yourself + https://mail.python.org/pipermail/python-dev/2000-August/007825.html Copyright +========= + +This document has been placed in the public domain. - This document has been placed in the public domain. - -Local Variables: -mode: indented-text -indent-tabs-mode: nil -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + End: diff --git a/pep-0243.txt b/pep-0243.txt index ce68b1e3bf3..098e75c34c8 100644 --- a/pep-0243.txt +++ b/pep-0243.txt @@ -6,179 +6,189 @@ Author: jafo-pep@tummy.com (Sean Reifschneider) Discussions-To: distutils-sig@python.org Status: Withdrawn Type: Standards Track +Content-Type: text/x-rst Created: 18-Mar-2001 Python-Version: 2.1 Post-History: 20-Mar-2001, 24-Mar-2001 Abstract +======== - For a module repository system (such as Perl's CPAN) to be - successful, it must be as easy as possible for module authors to - submit their work. An obvious place for this submit to happen is - in the Distutils tools after the distribution archive has been - successfully created. For example, after a module author has - tested their software (verifying the results of "setup.py sdist"), - they might type "setup.py sdist --submit". This would flag - Distutils to submit the source distribution to the archive server - for inclusion and distribution to the mirrors. +For a module repository system (such as Perl's CPAN) to be +successful, it must be as easy as possible for module authors to +submit their work. An obvious place for this submit to happen is +in the Distutils tools after the distribution archive has been +successfully created. For example, after a module author has +tested their software (verifying the results of ``setup.py sdist``), +they might type ``setup.py sdist --submit``. This would flag +Distutils to submit the source distribution to the archive server +for inclusion and distribution to the mirrors. - This PEP only deals with the mechanism for submitting the software - distributions to the archive, and does not deal with the actual - archive/catalog server. +This PEP only deals with the mechanism for submitting the software +distributions to the archive, and does not deal with the actual +archive/catalog server. Upload Process - - The upload will include the Distutils "PKG-INFO" meta-data - information (as specified in PEP-241 [1]), the actual software - distribution, and other optional information. This information - will be uploaded as a multi-part form encoded the same as a - regular HTML file upload request. This form is posted using - ENCTYPE="multipart/form-data" encoding [2]. - - The upload will be made to the host "www.python.org" on port - 80/tcp (POST http://www.python.org:80/pypi). The form - will consist of the following fields: - - distribution -- The file containing the module software (for - example, a .tar.gz or .zip file). - - distmd5sum -- The MD5 hash of the uploaded distribution, - encoded in ASCII representing the hexadecimal representation - of the digest ("for byte in digest: s = s + ('%02x' % - ord(byte))"). - - pkginfo (optional) -- The file containing the distribution - meta-data (as specified in PEP-241 [1]). Note that if this is - not included, the distribution file is expected to be in .tar - format (gzipped and bzipped compreesed are allowed) or .zip - format, with a "PKG-INFO" file in the top-level directory it - extracts ("package-1.00/PKG-INFO"). - - infomd5sum (required if pkginfo field is present) -- The MD5 hash - of the uploaded meta-data, encoded in ASCII representing the - hexadecimal representation of the digest ("for byte in digest: - s = s + ('%02x' % ord(byte))"). - - platform (optional) -- A string representing the target - platform for this distribution. This is only for binary - distributions. It is encoded as - "---". - - signature (optional) -- A OpenPGP-compatible signature [3] of - the uploaded distribution as signed by the author. This may - be used by the cataloging system to automate acceptance of - uploads. - - protocol_version -- A string indicating the protocol version that - the client supports. This document describes protocol version "1". +============== + +The upload will include the Distutils ``PKG-INFO`` meta-data +information (as specified in PEP 241 [1]_), the actual software +distribution, and other optional information. This information +will be uploaded as a multi-part form encoded the same as a +regular HTML file upload request. This form is posted using +``ENCTYPE="multipart/form-data"`` encoding [2]_. + +The upload will be made to the host "www.python.org" on port +80/tcp (``POST http://www.python.org:80/pypi``). The form +will consist of the following fields: + +- ``distribution`` -- The file containing the module software (for + example, a .tar.gz or .zip file). + +- ``distmd5sum`` -- The MD5 hash of the uploaded distribution, + encoded in ASCII representing the hexadecimal representation + of the digest (``for byte in digest: s = s + ('%02x' % + ord(byte))``). + +- ``pkginfo`` (optional) -- The file containing the distribution + meta-data (as specified in PEP 241 [1]_). Note that if this is + not included, the distribution file is expected to be in ``.tar`` + format (gzipped and bzipped compreesed are allowed) or ``.zip`` + format, with a ``PKG-INFO`` file in the top-level directory it + extracts (``package-1.00/PKG-INFO``). + +- ``infomd5sum`` (required if pkginfo field is present) -- The MD5 hash + of the uploaded meta-data, encoded in ASCII representing the + hexadecimal representation of the digest (``for byte in digest: + s = s + ('%02x' % ord(byte))``). + +- ``platform`` (optional) -- A string representing the target + platform for this distribution. This is only for binary + distributions. It is encoded as + ``---``. + +- ``signature`` (optional) -- A OpenPGP-compatible signature [3]_ of + the uploaded distribution as signed by the author. This may + be used by the cataloging system to automate acceptance of + uploads. + +- ``protocol_version`` -- A string indicating the protocol version that + the client supports. This document describes protocol version "1". Return Data +=========== - The status of the upload will be reported using HTTP non-standard - ("X-*)" headers. The "X-Swalow-Status" header may have the following - values: +The status of the upload will be reported using HTTP non-standard +("X-\*)" headers. The ``X-Swalow-Status`` header may have the following +values: - SUCCESS -- Indicates that the upload has succeeded. +- ``SUCCESS`` -- Indicates that the upload has succeeded. - FAILURE -- The upload is, for some reason, unable to be - processed. +- ``FAILURE`` -- The upload is, for some reason, unable to be + processed. - TRYAGAIN -- The server is unable to accept the upload at this - time, but the client should try again at a later time. - Potential causes of this are resource shortages on the server, - administrative down-time, etc... +- ``TRYAGAIN`` -- The server is unable to accept the upload at this + time, but the client should try again at a later time. + Potential causes of this are resource shortages on the server, + administrative down-time, etc... - Optionally, there may be a "X-Swalow-Reason" header which includes a - human-readable string which provides more detailed information about - the "X-Swalow-Status". +Optionally, there may be a ``X-Swalow-Reason`` header which includes a +human-readable string which provides more detailed information about +the ``X-Swalow-Status``. - If there is no "X-Swalow-Status" header, or it does not contain one of - the three strings above, it should be treated as a temporary failure. +If there is no ``X-Swalow-Status`` header, or it does not contain one of +the three strings above, it should be treated as a temporary failure. - Example: +Example:: - >>> f = urllib.urlopen('http://www.python.org:80/pypi') - >>> s = f.headers['x-swalow-status'] - >>> s = s + ': ' + f.headers.get('x-swalow-reason', '') - >>> print s - FAILURE: Required field "distribution" missing. + >>> f = urllib.urlopen('http://www.python.org:80/pypi') + >>> s = f.headers['x-swalow-status'] + >>> s = s + ': ' + f.headers.get('x-swalow-reason', '') + >>> print s + FAILURE: Required field "distribution" missing. Sample Form - - The upload client must submit the page in the same form as - Netscape Navigator version 4.76 for Linux produces when presented - with the following form: - -

Upload file

-
-
-
-
-
-
-
-
- -
+=========== + +The upload client must submit the page in the same form as +Netscape Navigator version 4.76 for Linux produces when presented +with the following form:: + +

Upload file

+
+
+
+
+
+
+
+
+ +
Platforms +========= - The following are valid os names: +The following are valid os names:: - aix beos debian dos freebsd hpux mac macos mandrake netbsd - openbsd qnx redhat solaris suse windows yellowdog + aix beos debian dos freebsd hpux mac macos mandrake netbsd + openbsd qnx redhat solaris suse windows yellowdog - The above include a number of different types of distributions of - Linux. Because of versioning issues these must be split out, and - it is expected that when it makes sense for one system to use - distributions made on other similar systems, the download client - will make the distinction. +The above include a number of different types of distributions of +Linux. Because of versioning issues these must be split out, and +it is expected that when it makes sense for one system to use +distributions made on other similar systems, the download client +will make the distinction. - Version is the official version string specified by the vendor for - the particular release. For example, "2000" and "nt" (Windows), - "9.04" (HP-UX), "7.0" (RedHat, Mandrake). +Version is the official version string specified by the vendor for +the particular release. For example, "2000" and "nt" (Windows), +"9.04" (HP-UX), "7.0" (RedHat, Mandrake). - The following are valid architectures: +The following are valid architectures:: - alpha hppa ix86 powerpc sparc ultrasparc + alpha hppa ix86 powerpc sparc ultrasparc Status +====== - I currently have a proof-of-concept client and server implemented. - I plan to have the Distutils patches ready for the 2.1 release. - Combined with Andrew's PEP-241 [1] for specifying distribution - meta-data, I hope to have a platform which will allow us to gather - real-world data for finalizing the catalog system for the 2.2 - release. +I currently have a proof-of-concept client and server implemented. +I plan to have the Distutils patches ready for the 2.1 release. +Combined with Andrew's PEP 241 [1]_ for specifying distribution +meta-data, I hope to have a platform which will allow us to gather +real-world data for finalizing the catalog system for the 2.2 +release. References +========== - [1] Metadata for Python Software Package, Kuchling, - http://www.python.org/dev/peps/pep-0241/ +.. [1] Metadata for Python Software Package, Kuchling, + http://www.python.org/dev/peps/pep-0241/ - [2] RFC 1867, Form-based File Upload in HTML - http://www.faqs.org/rfcs/rfc1867.html +.. [2] RFC 1867, Form-based File Upload in HTML + http://www.faqs.org/rfcs/rfc1867.html - [3] RFC 2440, OpenPGP Message Format - http://www.faqs.org/rfcs/rfc2440.html +.. [3] RFC 2440, OpenPGP Message Format + http://www.faqs.org/rfcs/rfc2440.html Copyright +========= + +This document has been placed in the public domain. - This document has been placed in the public domain. - -Local Variables: -mode: indented-text -indent-tabs-mode: nil -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + End: diff --git a/pep-0244.txt b/pep-0244.txt index 1f119f42d26..df5a9c8b3f4 100644 --- a/pep-0244.txt +++ b/pep-0244.txt @@ -1,174 +1,185 @@ PEP: 244 -Title: The `directive' statement +Title: The ``directive`` statement Version: $Revision$ Last-Modified: $Date$ Author: martin@v.loewis.de (Martin von Löwis) Status: Rejected Type: Standards Track +Content-Type: text/x-rst Created: 20-Mar-2001 Python-Version: 2.1 Post-History: Motivation - - From time to time, Python makes an incompatible change to the - advertised semantics of core language constructs, or changes their - accidental (implementation-dependent) behavior in some way. While - this is never done capriciously, and is always done with the aim - of improving the language over the long term, over the short term - it's contentious and disrupting. - - PEP 1, Guidelines for Language Evolution[1] suggests ways to ease - the pain, and this PEP introduces some machinery in support of - that. - - PEP 2, Statically Nested Scopes[2] is the first application, and - will be used as an example here. - - When a new, potentially incompatible language feature is added, - some modules and libraries may chose to use it, while others may - not. This specification introduces a syntax where a module author - can denote whether a certain language feature is used in the - module or not. - - In discussion of this PEP, readers commented that there are two - kinds of "settable" language features: - - - those that are designed to eventually become the only option, at - which time specifying use of them is not necessary anymore. The - features for which the syntax of the "Back to the __future__" - PEP 236, Back to the __future__[3] was proposed fall into this - category. This PEP supports declaring such features, and - supports phasing out the "old" meaning of constructs whose - semantics has changed under the new feature. However, it - defines no policy as to what features must be phased out - eventually. - - - those which are designed to stay optional forever, e.g. if they - change some default setting in the interpreter. An example for - such settings might be the request to always emit line-number - instructions for a certain module; no specific flags of that - kind are proposed in this specification. - - Since a primary goal of this PEP is to support new language - constructs without immediately breaking old libraries, special - care was taken not to break old libraries by introducing the new - syntax. +========== + +From time to time, Python makes an incompatible change to the +advertised semantics of core language constructs, or changes their +accidental (implementation-dependent) behavior in some way. While +this is never done capriciously, and is always done with the aim +of improving the language over the long term, over the short term +it's contentious and disrupting. + +PEP 1, Guidelines for Language Evolution [1]_ suggests ways to ease +the pain, and this PEP introduces some machinery in support of +that. + +PEP 2, Statically Nested Scopes [2]_ is the first application, and +will be used as an example here. + +When a new, potentially incompatible language feature is added, +some modules and libraries may chose to use it, while others may +not. This specification introduces a syntax where a module author +can denote whether a certain language feature is used in the +module or not. + +In discussion of this PEP, readers commented that there are two +kinds of "settable" language features: + +- those that are designed to eventually become the only option, at + which time specifying use of them is not necessary anymore. The + features for which the syntax of the "Back to the ``__future__``" + PEP 236, Back to the ``__future__`` [3]_ was proposed fall into this + category. This PEP supports declaring such features, and + supports phasing out the "old" meaning of constructs whose + semantics has changed under the new feature. However, it + defines no policy as to what features must be phased out + eventually. + +- those which are designed to stay optional forever, e.g. if they + change some default setting in the interpreter. An example for + such settings might be the request to always emit line-number + instructions for a certain module; no specific flags of that + kind are proposed in this specification. + +Since a primary goal of this PEP is to support new language +constructs without immediately breaking old libraries, special +care was taken not to break old libraries by introducing the new +syntax. Syntax +====== - A directive_statement is a statement of the form +A directive_statement is a statement of the form:: - directive_statement: 'directive' NAME [atom] [';'] NEWLINE + directive_statement: 'directive' ``NAME`` [atom] [';'] NEWLINE - The name in the directive indicates the kind of the directive; it - defines whether the optional atom can be present, and whether - there are further syntactical or semantical restrictions to the - atom. In addition, depending on the name of the directive, - certain additional syntactical or semantical restrictions may be - placed on the directive (e.g. placement of the directive in the - module may be restricted to the top of the module). +The name in the directive indicates the kind of the directive; it +defines whether the optional atom can be present, and whether +there are further syntactical or semantical restrictions to the +atom. In addition, depending on the name of the directive, +certain additional syntactical or semantical restrictions may be +placed on the directive (e.g. placement of the directive in the +module may be restricted to the top of the module). - In the directive_statement, 'directive' is a new - keyword. According to [1], this keyword is initially considered as - a keyword only when used in a directive statement, see "Backwards - Compatibility" below. +In the directive_statement, ``directive`` is a new +keyword. According to [1]_, this keyword is initially considered as +a keyword only when used in a directive statement, see "Backwards +Compatibility" below. Semantics +========= - A directive statement instructs the Python interpreter to process - a source file in a different way; the specific details of that - processing depend on the directive name. The optional atom is - typically interpreted when the source code is processed; details - of that interpretation depend on the directive. +A directive statement instructs the Python interpreter to process +a source file in a different way; the specific details of that +processing depend on the directive name. The optional atom is +typically interpreted when the source code is processed; details +of that interpretation depend on the directive. Specific Directives: transitional +================================= - If a syntactical or semantical change is added to Python which is - incompatible, [1] mandates a transitional evolution of the - language, where the new feature is initially available alongside - with the old one. Such a transition is possible by means of the - transitional directive. +If a syntactical or semantical change is added to Python which is +incompatible, [1]_ mandates a transitional evolution of the +language, where the new feature is initially available alongside +with the old one. Such a transition is possible by means of the +transitional directive. - In a transitional directive, the NAME is 'transitional'. The atom - MUST be present, and it MUST be a NAME. The possible values for - that name are defined when the language change is defined. One - example for such a directive is +In a transitional directive, the ``NAME`` is 'transitional'. The atom +MUST be present, and it MUST be a ``NAME``. The possible values for +that name are defined when the language change is defined. One +example for such a directive is:: - directive transitional nested_scopes + directive transitional nested_scopes - The transitional directive MUST occur at before any other - statement in a module, except for the documentation string - (i.e. it may appear as the second statement of a module only if - the first statement is a STRING+). +The transitional directive MUST occur at before any other +statement in a module, except for the documentation string +(i.e. it may appear as the second statement of a module only if +the first statement is a ``STRING+``). Backwards Compatibility +======================= - Introducing 'directive' as a new keyword might cause - incompatibilities with existing code. Following the guideline in - [1], in the initial implementation of this specification, - directive is a new keyword only if it was used in a valid - directive_statement (i.e. if it appeared as the first non-string - token in a module). +Introducing ``directive`` as a new keyword might cause +incompatibilities with existing code. Following the guideline in +[1]_, in the initial implementation of this specification, +directive is a new keyword only if it was used in a valid +directive_statement (i.e. if it appeared as the first non-string +token in a module). Unresolved Problems: directive as the first identifier +======================================================= - Using directive in a module as +Using directive in a module as:: directive = 1 - (i.e. the name directive appears as the first thing in a module) - will treat it as keyword, not as identifier. It would be possible - to classify it as a NAME with an additional look-ahead token, but - such look-ahead is not available in the Python tokenizer. +(i.e. the name directive appears as the first thing in a module) +will treat it as keyword, not as identifier. It would be possible +to classify it as a ``NAME`` with an additional look-ahead token, but +such look-ahead is not available in the Python tokenizer. Questions and Answers +===================== - Q: It looks like this PEP was written to allow definition of source - code character sets. Is that true? +Q: It looks like this PEP was written to allow definition of source +code character sets. Is that true? - A: No. Even though the directive facility can be extended to - allow source code encodings, no specific directive is proposed. +A: No. Even though the directive facility can be extended to +allow source code encodings, no specific directive is proposed. - Q: Then why was this PEP written at all? +Q: Then why was this PEP written at all? - A: It acts as a counter-proposal to [3], which proposes to - overload the import statement with a new meaning. This PEP - allows to solve the problem in a more general way. +A: It acts as a counter-proposal to [3]_, which proposes to +overload the import statement with a new meaning. This PEP +allows to solve the problem in a more general way. - Q: But isn't mixing source encodings and language changes like - mixing apples and oranges? +Q: But isn't mixing source encodings and language changes like +mixing apples and oranges? - A: Perhaps. To address the difference, the predefined - "transitional" directive has been defined. +A: Perhaps. To address the difference, the predefined +"transitional" directive has been defined. References and Footnotes +======================== - [1] PEP 5, Guidelines for Language Evolution, Prescod - http://www.python.org/dev/peps/pep-0005/ +.. [1] PEP 5, Guidelines for Language Evolution, Prescod + http://www.python.org/dev/peps/pep-0005/ - [2] PEP 227, Statically Nested Scopes, Hylton - http://www.python.org/dev/peps/pep-0227/ +.. [2] PEP 227, Statically Nested Scopes, Hylton + http://www.python.org/dev/peps/pep-0227/ - [3] PEP 236, Back to the __future__, Peters - http://www.python.org/dev/peps/pep-0236/ +.. [3] PEP 236, Back to the ``__future__``, Peters + http://www.python.org/dev/peps/pep-0236/ Copyright +========= + +This document has been placed in the public domain. - This document has been placed in the public domain. - -Local Variables: -mode: indented-text -indent-tabs-mode: nil -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + End: diff --git a/pep-0265.txt b/pep-0265.txt index 8ec0fd93f5a..0c761151e64 100644 --- a/pep-0265.txt +++ b/pep-0265.txt @@ -5,202 +5,213 @@ Last-Modified: $Date$ Author: g2@iowegian.com (Grant Griffin) Status: Rejected Type: Standards Track +Content-Type: text/x-rst Created: 8-Aug-2001 Python-Version: 2.2 Post-History: Abstract +======== + +This PEP suggests a "sort by value" operation for dictionaries. +The primary benefit would be in terms of "batteries included" +support for a common Python idiom which, in its current form, is +both difficult for beginners to understand and cumbersome for all +to implement. - This PEP suggests a "sort by value" operation for dictionaries. - The primary benefit would be in terms of "batteries included" - support for a common Python idiom which, in its current form, is - both difficult for beginners to understand and cumbersome for all - to implement. BDFL Pronouncement +================== - This PEP is rejected because the need for it has been largely - fulfilled by Py2.4's sorted() builtin function: +This PEP is rejected because the need for it has been largely +fulfilled by Py2.4's ``sorted()`` builtin function:: - >>> sorted(d.iteritems(), key=itemgetter(1), reverse=True) - [('b', 23), ('d', 17), ('c', 5), ('a', 2), ('e', 1)] + >>> sorted(d.iteritems(), key=itemgetter(1), reverse=True) + [('b', 23), ('d', 17), ('c', 5), ('a', 2), ('e', 1)] - or for just the keys: +or for just the keys:: - sorted(d, key=d.__getitem__, reverse=True) - ['b', 'd', 'c', 'a', 'e'] + sorted(d, key=d.__getitem__, reverse=True) + ['b', 'd', 'c', 'a', 'e'] - Also, Python 2.5's heapq.nlargest() function addresses the common use - case of finding only a few of the highest valued items: +Also, Python 2.5's ``heapq.nlargest()`` function addresses the common use +case of finding only a few of the highest valued items:: - >>> nlargest(2, d.iteritems(), itemgetter(1)) - [('b', 23), ('d', 17)] + >>> nlargest(2, d.iteritems(), itemgetter(1)) + [('b', 23), ('d', 17)] Motivation +========== - A common use of dictionaries is to count occurrences by setting - the value of d[key] to 1 on its first occurrence, then increment - the value on each subsequent occurrence. This can be done several - different ways, but the get() method is the most succinct: +A common use of dictionaries is to count occurrences by setting +the value of ``d[key]`` to 1 on its first occurrence, then increment +the value on each subsequent occurrence. This can be done several +different ways, but the ``get()`` method is the most succinct:: - d[key] = d.get(key, 0) + 1 + d[key] = d.get(key, 0) + 1 - Once all occurrences have been counted, a common use of the - resulting dictionary is to print the occurrences in - occurrence-sorted order, often with the largest value first. +Once all occurrences have been counted, a common use of the +resulting dictionary is to print the occurrences in +occurrence-sorted order, often with the largest value first. - This leads to a need to sort a dictionary's items by value. The - canonical method of doing so in Python is to first use d.items() - to get a list of the dictionary's items, then invert the ordering - of each item's tuple from (key, value) into (value, key), then - sort the list; since Python sorts the list based on the first item - of the tuple, the list of (inverted) items is therefore sorted by - value. If desired, the list can then be reversed, and the tuples - can be re-inverted back to (key, value). (However, in my - experience, the inverted tuple ordering is fine for most purposes, - e.g. printing out the list.) +This leads to a need to sort a dictionary's items by value. The +canonical method of doing so in Python is to first use ``d.items()`` +to get a list of the dictionary's items, then invert the ordering +of each item's tuple from (key, value) into (value, key), then +sort the list; since Python sorts the list based on the first item +of the tuple, the list of (inverted) items is therefore sorted by +value. If desired, the list can then be reversed, and the tuples +can be re-inverted back to (key, value). (However, in my +experience, the inverted tuple ordering is fine for most purposes, +e.g. printing out the list.) - For example, given an occurrence count of: +For example, given an occurrence count of:: - >>> d = {'a':2, 'b':23, 'c':5, 'd':17, 'e':1} + >>> d = {'a':2, 'b':23, 'c':5, 'd':17, 'e':1} - we might do: +we might do:: - >>> items = [(v, k) for k, v in d.items()] - >>> items.sort() - >>> items.reverse() # so largest is first - >>> items = [(k, v) for v, k in items] + >>> items = [(v, k) for k, v in d.items()] + >>> items.sort() + >>> items.reverse() # so largest is first + >>> items = [(k, v) for v, k in items] - resulting in: +resulting in:: - >>> items - [('b', 23), ('d', 17), ('c', 5), ('a', 2), ('e', 1)] + >>> items + [('b', 23), ('d', 17), ('c', 5), ('a', 2), ('e', 1)] - which shows the list in by-value order, largest first. (In this - case, 'b' was found to have the most occurrences.) +which shows the list in by-value order, largest first. (In this +case, ``b`` was found to have the most occurrences.) - This works fine, but is "hard to use" in two aspects. First, - although this idiom is known to veteran Pythoneers, it is not at - all obvious to newbies -- either in terms of its algorithm - (inverting the ordering of item tuples) or its implementation - (using list comprehensions -- which are an advanced Python - feature.) Second, it requires having to repeatedly type a lot of - "grunge", resulting in both tedium and mistakes. +This works fine, but is "hard to use" in two aspects. First, +although this idiom is known to veteran Pythoneers, it is not at +all obvious to newbies -- either in terms of its algorithm +(inverting the ordering of item tuples) or its implementation +(using list comprehensions -- which are an advanced Python +feature.) Second, it requires having to repeatedly type a lot of +"grunge", resulting in both tedium and mistakes. - We therefore would rather Python provide a method of sorting - dictionaries by value which would be both easy for newbies to - understand (or, better yet, not to _have to_ understand) and - easier for all to use. +We therefore would rather Python provide a method of sorting +dictionaries by value which would be both easy for newbies to +understand (or, better yet, not to *have to* understand) and +easier for all to use. Rationale +========= - As Tim Peters has pointed out, this sort of thing brings on the - problem of trying to be all things to all people. Therefore, we - will limit its scope to try to hit "the sweet spot". Unusual - cases (e.g. sorting via a custom comparison function) can, of - course, be handled "manually" using present methods. +As Tim Peters has pointed out, this sort of thing brings on the +problem of trying to be all things to all people. Therefore, we +will limit its scope to try to hit "the sweet spot". Unusual +cases (e.g. sorting via a custom comparison function) can, of +course, be handled "manually" using present methods. - Here are some simple possibilities: +Here are some simple possibilities: - The items() method of dictionaries can be augmented with new - parameters having default values that provide for full - backwards-compatibility: +The ``items()`` method of dictionaries can be augmented with new +parameters having default values that provide for full +backwards-compatibility:: - (1) items(sort_by_values=0, reversed=0) + (1) items(sort_by_values=0, reversed=0) - or maybe just: +or maybe just:: - (2) items(sort_by_values=0) + (2) items(sort_by_values=0) - since reversing a list is easy enough. +since reversing a list is easy enough. - Alternatively, items() could simply let us control the (key, value) - order: +Alternatively, ``items()`` could simply let us control the (key, value) +order:: - (3) items(values_first=0) + (3) items(values_first=0) - Again, this is fully backwards-compatible. It does less work than - the others, but it at least eases the most complicated/tricky part - of the sort-by-value problem: inverting the order of item tuples. - Using this is very simple: +Again, this is fully backwards-compatible. It does less work than +the others, but it at least eases the most complicated/tricky part +of the sort-by-value problem: inverting the order of item tuples. +Using this is very simple:: - items = d.items(1) - items.sort() - items.reverse() # (if desired) + items = d.items(1) + items.sort() + items.reverse() # (if desired) - The primary drawback of the preceding three approaches is the - additional overhead for the parameter-less "items()" case, due to - having to process default parameters. (However, if one assumes - that items() gets used primarily for creating sort-by-value lists, - this is not really a drawback in practice.) +The primary drawback of the preceding three approaches is the +additional overhead for the parameter-less ``items()`` case, due to +having to process default parameters. (However, if one assumes +that ``items()`` gets used primarily for creating sort-by-value lists, +this is not really a drawback in practice.) - Alternatively, we might add a new dictionary method which somehow - embodies "sorting". This approach offers two advantages. First, - it avoids adding overhead to the items() method. Second, it is - perhaps more accessible to newbies: when they go looking for a - method for sorting dictionaries, they hopefully run into this one, - and they will not have to understand the finer points of tuple - inversion and list sorting to achieve sort-by-value. +Alternatively, we might add a new dictionary method which somehow +embodies "sorting". This approach offers two advantages. First, +it avoids adding overhead to the ``items()`` method. Second, it is +perhaps more accessible to newbies: when they go looking for a +method for sorting dictionaries, they hopefully run into this one, +and they will not have to understand the finer points of tuple +inversion and list sorting to achieve sort-by-value. - To allow the four basic possibilities of sorting by key/value and in - forward/reverse order, we could add this method: +To allow the four basic possibilities of sorting by key/value and in +forward/reverse order, we could add this method:: - (4) sorted_items(by_value=0, reversed=0) + (4) sorted_items(by_value=0, reversed=0) - I believe the most common case would actually be "by_value=1, - reversed=1", but the defaults values given here might lead to - fewer surprises by users: sorted_items() would be the same as - items() followed by sort(). +I believe the most common case would actually be ``by_value=1, +reversed=1``, but the defaults values given here might lead to +fewer surprises by users: ``sorted_items()`` would be the same as +``items()`` followed by ``sort()``. - Finally (as a last resort), we could use: +Finally (as a last resort), we could use:: - (5) items_sorted_by_value(reversed=0) + (5) items_sorted_by_value(reversed=0) Implementation +============== - The proposed dictionary methods would necessarily be implemented - in C. Presumably, the implementation would be fairly simple since - it involves just adding a few calls to Python's existing - machinery. +The proposed dictionary methods would necessarily be implemented +in C. Presumably, the implementation would be fairly simple since +it involves just adding a few calls to Python's existing +machinery. Concerns +======== - Aside from the run-time overhead already addressed in - possibilities 1 through 3, concerns with this proposal probably - will fall into the categories of "feature bloat" and/or "code - bloat". However, I believe that several of the suggestions made - here will result in quite minimal bloat, resulting in a good - tradeoff between bloat and "value added". +Aside from the run-time overhead already addressed in +possibilities 1 through 3, concerns with this proposal probably +will fall into the categories of "feature bloat" and/or "code +bloat". However, I believe that several of the suggestions made +here will result in quite minimal bloat, resulting in a good +tradeoff between bloat and "value added". - Tim Peters has noted that implementing this in C might not be - significantly faster than implementing it in Python today. - However, the major benefits intended here are "accessibility" and - "ease of use", not "speed". Therefore, as long as it is not - noticeably slower (in the case of plain items(), speed need not be - a consideration. +Tim Peters has noted that implementing this in C might not be +significantly faster than implementing it in Python today. +However, the major benefits intended here are "accessibility" and +"ease of use", not "speed". Therefore, as long as it is not +noticeably slower (in the case of plain ``items()``, speed need not be +a consideration. References +========== - A related thread called "counting occurrences" appeared on - comp.lang.python in August, 2001. This included examples of - approaches to systematizing the sort-by-value problem by - implementing it as reusable Python functions and classes. +A related thread called "counting occurrences" appeared on +comp.lang.python in August, 2001. This included examples of +approaches to systematizing the sort-by-value problem by +implementing it as reusable Python functions and classes. Copyright +========= - This document has been placed in the public domain. +This document has been placed in the public domain. - -Local Variables: -mode: indented-text -indent-tabs-mode: nil -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + End: + diff --git a/pep-0278.txt b/pep-0278.txt index 5863965c175..b7d6876eeed 100644 --- a/pep-0278.txt +++ b/pep-0278.txt @@ -5,204 +5,212 @@ Last-Modified: $Date$ Author: jack@cwi.nl (Jack Jansen) Status: Final Type: Standards Track +Content-Type: text/x-rst Created: 14-Jan-2002 Python-Version: 2.3 Post-History: Abstract +======== - This PEP discusses a way in which Python can support I/O on files - which have a newline format that is not the native format on the - platform, so that Python on each platform can read and import - files with CR (Macintosh), LF (Unix) or CR LF (Windows) line - endings. +This PEP discusses a way in which Python can support I/O on files +which have a newline format that is not the native format on the +platform, so that Python on each platform can read and import +files with CR (Macintosh), LF (Unix) or CR LF (Windows) line +endings. - It is more and more common to come across files that have an end - of line that does not match the standard on the current platform: - files downloaded over the net, remotely mounted filesystems on a - different platform, Mac OS X with its double standard of Mac and - Unix line endings, etc. - - Many tools such as editors and compilers already handle this - gracefully, it would be good if Python did so too. +It is more and more common to come across files that have an end +of line that does not match the standard on the current platform: +files downloaded over the net, remotely mounted filesystems on a +different platform, Mac OS X with its double standard of Mac and +Unix line endings, etc. + +Many tools such as editors and compilers already handle this +gracefully, it would be good if Python did so too. Specification +============= + +Universal newline support is enabled by default, +but can be disabled during the configure of Python. + +In a Python with universal newline support the feature is +automatically enabled for all import statements and ``execfile()`` +calls. There is no special support for ``eval()`` or exec. + +In a Python with universal newline support ``open()`` the mode +parameter can also be "U", meaning "open for input as a text file +with universal newline interpretation". Mode "rU" is also allowed, +for symmetry with "rb". Mode "U" cannot be +combined with other mode flags such as "+". Any line ending in the +input file will be seen as a '\n' in Python, so little other code has +to change to handle universal newlines. + +Conversion of newlines happens in all calls that read data: ``read()``, +``readline()``, ``readlines()``, etc. + +There is no special support for output to file with a different +newline convention, and so mode "wU" is also illegal. + +A file object that has been opened in universal newline mode gets +a new attribute "newlines" which reflects the newline convention +used in the file. The value for this attribute is one of None (no +newline read yet), "\r", "\n", "\r\n" or a tuple containing all the +newline types seen. + - Universal newline support is enabled by default, - but can be disabled during the configure of Python. - - In a Python with universal newline support the feature is - automatically enabled for all import statements and execfile() - calls. There is no special support for eval() or exec. - - In a Python with universal newline support open() the mode - parameter can also be "U", meaning "open for input as a text file - with universal newline interpretation". Mode "rU" is also allowed, - for symmetry with "rb". Mode "U" cannot be - combined with other mode flags such as "+". Any line ending in the - input file will be seen as a '\n' in Python, so little other code has - to change to handle universal newlines. - - Conversion of newlines happens in all calls that read data: read(), - readline(), readlines(), etc. - - There is no special support for output to file with a different - newline convention, and so mode "wU" is also illegal. - - A file object that has been opened in universal newline mode gets - a new attribute "newlines" which reflects the newline convention - used in the file. The value for this attribute is one of None (no - newline read yet), "\r", "\n", "\r\n" or a tuple containing all the - newline types seen. - - Rationale +========= + +Universal newline support is implemented in C, not in Python. +This is done because we want files with a foreign newline +convention to be import-able, so a Python Lib directory can be +shared over a remote file system connection, or between MacPython +and Unix-Python on Mac OS X. For this to be feasible the +universal newline convention needs to have a reasonably small +impact on performance, which means a Python implementation is not +an option as it would bog down all imports. And because of files +with multiple newline conventions, which Visual C++ and other +Windows tools will happily produce, doing a quick check for the +newlines used in a file (handing off the import to C code if a +platform-local newline is seen) will not work. Finally, a C +implementation also allows tracebacks and such (which open the +Python source module) to be handled easily. + +There is no output implementation of universal newlines, Python +programs are expected to handle this by themselves or write files +with platform-local convention otherwise. The reason for this is +that input is the difficult case, outputting different newlines to +a file is already easy enough in Python. + +Also, an output implementation would be much more difficult than an +input implementation, surprisingly: a lot of output is done through +``PyXXX_Print()`` methods, and at this point the file object is not +available anymore, only a ``FILE *``. So, an output implementation would +need to somehow go from the ``FILE*`` to the file object, because that +is where the current newline delimiter is stored. + +The input implementation has no such problem: there are no cases in +the Python source tree where files are partially read from C, +partially from Python, and such cases are expected to be rare in +extension modules. If such cases exist the only problem is that the +newlines attribute of the file object is not updated during the +``fread()`` or ``fgets()`` calls that are done direct from C. + +A partial output implementation, where strings passed to ``fp.write()`` +would be converted to use fp.newlines as their line terminator but +all other output would not is far too surprising, in my view. + +Because there is no output support for universal newlines there is +also no support for a mode "rU+": the surprise factor of the +previous paragraph would hold to an even stronger degree. + +There is no support for universal newlines in strings passed to +``eval()`` or ``exec``. It is envisioned that such strings always have the +standard ``\n`` line feed, if the strings come from a file that file can +be read with universal newlines. + +I think there are no special issues with unicode. utf-16 shouldn't +pose any new problems, as such files need to be opened in binary +mode anyway. Interaction with utf-8 is fine too: values 0x0a and 0x0d +cannot occur as part of a multibyte sequence. + +Universal newline files should work fine with iterators and +``xreadlines()`` as these eventually call the normal file +readline/readlines methods. + + +While universal newlines are automatically enabled for import they +are not for opening, where you have to specifically say open(..., +"U"). This is open to debate, but here are a few reasons for this +design: + +- Compatibility. Programs which already do their own + interpretation of ``\r\n`` in text files would break. Examples of such + programs would be editors which warn you when you open a file with + a different newline convention. If universal newlines was made the + default such an editor would silently convert your line endings to + the local convention on save. Programs which open binary files as + text files on Unix would also break (but it could be argued they + deserve it :-). + +- Interface clarity. Universal newlines are only supported for + input files, not for input/output files, as the semantics would + become muddy. Would you write Mac newlines if all reads so far + had encountered Mac newlines? But what if you then later read a + Unix newline? + +The newlines attribute is included so that programs that really +care about the newline convention, such as text editors, can +examine what was in a file. They can then save (a copy of) the +file with the same newline convention (or, in case of a file with +mixed newlines, ask the user what to do, or output in platform +convention). + +Feedback is explicitly solicited on one item in the reference +implementation: whether or not the universal newlines routines +should grab the global interpreter lock. Currently they do not, +but this could be considered living dangerously, as they may +modify fields in a ``FileObject``. But as these routines are +replacements for ``fgets()`` and ``fread()`` as well it may be difficult +to decide whether or not the lock is held when the routine is +called. Moreover, the only danger is that if two threads read the +same ``FileObject`` at the same time an extraneous newline may be seen +or the "newlines" attribute may inadvertently be set to mixed. I +would argue that if you read the same ``FileObject`` in two threads +simultaneously you are asking for trouble anyway. + +Note that no globally accessible pointers are manipulated in the +``fgets()`` or ``fread()`` replacement routines, just some integer-valued +flags, so the chances of core dumps are zero (he said:-). + +Universal newline support can be disabled during configure because it does +have a small performance penalty, and moreover the implementation has +not been tested on all conceivable platforms yet. It might also be silly +on some platforms (WinCE or Palm devices, for instance). If universal +newline support is not enabled then file objects do not have the "newlines" +attribute, so testing whether the current Python has it can be done with a +simple:: + + if hasattr(open, 'newlines'): + print 'We have universal newline support' + +Note that this test uses the ``open()`` function rather than the file +type so that it won't fail for versions of Python where the file +type was not available (the file type was added to the built-in +namespace in the same release as the universal newline feature was +added). + +Additionally, note that this test fails again on Python versions +>= 2.5, when ``open()`` was made a function again and is not synonymous +with the file type anymore. + - Universal newline support is implemented in C, not in Python. - This is done because we want files with a foreign newline - convention to be import-able, so a Python Lib directory can be - shared over a remote file system connection, or between MacPython - and Unix-Python on Mac OS X. For this to be feasible the - universal newline convention needs to have a reasonably small - impact on performance, which means a Python implementation is not - an option as it would bog down all imports. And because of files - with multiple newline conventions, which Visual C++ and other - Windows tools will happily produce, doing a quick check for the - newlines used in a file (handing off the import to C code if a - platform-local newline is seen) will not work. Finally, a C - implementation also allows tracebacks and such (which open the - Python source module) to be handled easily. - - There is no output implementation of universal newlines, Python - programs are expected to handle this by themselves or write files - with platform-local convention otherwise. The reason for this is - that input is the difficult case, outputting different newlines to - a file is already easy enough in Python. - - Also, an output implementation would be much more difficult than an - input implementation, surprisingly: a lot of output is done through - PyXXX_Print() methods, and at this point the file object is not - available anymore, only a FILE *. So, an output implementation would - need to somehow go from the FILE* to the file object, because that - is where the current newline delimiter is stored. - - The input implementation has no such problem: there are no cases in - the Python source tree where files are partially read from C, - partially from Python, and such cases are expected to be rare in - extension modules. If such cases exist the only problem is that the - newlines attribute of the file object is not updated during the - fread() or fgets() calls that are done direct from C. - - A partial output implementation, where strings passed to fp.write() - would be converted to use fp.newlines as their line terminator but - all other output would not is far too surprising, in my view. - - Because there is no output support for universal newlines there is - also no support for a mode "rU+": the surprise factor of the - previous paragraph would hold to an even stronger degree. - - There is no support for universal newlines in strings passed to - eval() or exec. It is envisioned that such strings always have the - standard \n line feed, if the strings come from a file that file can - be read with universal newlines. - - I think there are no special issues with unicode. utf-16 shouldn't - pose any new problems, as such files need to be opened in binary - mode anyway. Interaction with utf-8 is fine too: values 0x0a and 0x0d - cannot occur as part of a multibyte sequence. - - Universal newline files should work fine with iterators and - xreadlines() as these eventually call the normal file - readline/readlines methods. - - - While universal newlines are automatically enabled for import they - are not for opening, where you have to specifically say open(..., - "U"). This is open to debate, but here are a few reasons for this - design: - - - Compatibility. Programs which already do their own - interpretation of \r\n in text files would break. Examples of such - programs would be editors which warn you when you open a file with - a different newline convention. If universal newlines was made the - default such an editor would silently convert your line endings to - the local convention on save. Programs which open binary files as - text files on Unix would also break (but it could be argued they - deserve it :-). - - - Interface clarity. Universal newlines are only supported for - input files, not for input/output files, as the semantics would - become muddy. Would you write Mac newlines if all reads so far - had encountered Mac newlines? But what if you then later read a - Unix newline? - - The newlines attribute is included so that programs that really - care about the newline convention, such as text editors, can - examine what was in a file. They can then save (a copy of) the - file with the same newline convention (or, in case of a file with - mixed newlines, ask the user what to do, or output in platform - convention). - - Feedback is explicitly solicited on one item in the reference - implementation: whether or not the universal newlines routines - should grab the global interpreter lock. Currently they do not, - but this could be considered living dangerously, as they may - modify fields in a FileObject. But as these routines are - replacements for fgets() and fread() as well it may be difficult - to decide whether or not the lock is held when the routine is - called. Moreover, the only danger is that if two threads read the - same FileObject at the same time an extraneous newline may be seen - or the "newlines" attribute may inadvertently be set to mixed. I - would argue that if you read the same FileObject in two threads - simultaneously you are asking for trouble anyway. - - Note that no globally accessible pointers are manipulated in the - fgets() or fread() replacement routines, just some integer-valued - flags, so the chances of core dumps are zero (he said:-). - - Universal newline support can be disabled during configure because it does - have a small performance penalty, and moreover the implementation has - not been tested on all conceivable platforms yet. It might also be silly - on some platforms (WinCE or Palm devices, for instance). If universal - newline support is not enabled then file objects do not have the "newlines" - attribute, so testing whether the current Python has it can be done with a - simple - - if hasattr(open, 'newlines'): - print 'We have universal newline support' - - Note that this test uses the open() function rather than the file - type so that it won't fail for versions of Python where the file - type was not available (the file type was added to the built-in - namespace in the same release as the universal newline feature was - added). - - Additionally, note that this test fails again on Python versions - >= 2.5, when open() was made a function again and is not synonymous - with the file type anymore. - - Reference Implementation +======================== - A reference implementation is available in SourceForge patch - #476814: http://www.python.org/sf/476814 +A reference implementation is available in SourceForge patch +#476814: http://www.python.org/sf/476814 References +========== - None. +None. Copyright +========= + +This document has been placed in the public domain. - This document has been placed in the public domain. - -Local Variables: -mode: indented-text -indent-tabs-mode: nil -fill-column: 70 -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + fill-column: 70 + End: diff --git a/pep-0279.txt b/pep-0279.txt index 38d645bb505..65154a67a90 100644 --- a/pep-0279.txt +++ b/pep-0279.txt @@ -5,199 +5,223 @@ Last-Modified: $Date$ Author: python@rcn.com (Raymond Hettinger) Status: Final Type: Standards Track +Content-Type: text/x-rst Created: 30-Jan-2002 Python-Version: 2.3 Post-History: Abstract +======== - This PEP introduces a new built-in function, enumerate() to - simplify a commonly used looping idiom. It provides all iterable - collections with the same advantage that iteritems() affords to - dictionaries -- a compact, readable, reliable index notation. +This PEP introduces a new built-in function, ``enumerate()`` to +simplify a commonly used looping idiom. It provides all iterable +collections with the same advantage that ``iteritems()`` affords to +dictionaries -- a compact, readable, reliable index notation. Rationale - - Python 2.2 introduced the concept of an iterable interface as - proposed in PEP 234 [3]. The iter() factory function was provided - as common calling convention and deep changes were made to use - iterators as a unifying theme throughout Python. The unification - came in the form of establishing a common iterable interface for - mappings, sequences, and file objects. - - Generators, as proposed in PEP 255 [1], were introduced as a means - for making it easier to create iterators, especially ones with - complex internal execution or variable states. The availability - of generators makes it possible to improve on the loop counter - ideas in PEP 212 [2]. Those ideas provided a clean syntax for - iteration with indices and values, but did not apply to all - iterable objects. Also, that approach did not have the memory - friendly benefit provided by generators which do not evaluate the - entire sequence all at once. - - The new proposal is to add a built-in function, enumerate() which - was made possible once iterators and generators became available. - It provides all iterables with the same advantage that iteritems() - affords to dictionaries -- a compact, readable, reliable index - notation. Like zip(), it is expected to become a commonly used - looping idiom. - - This suggestion is designed to take advantage of the existing - implementation and require little additional effort to - incorporate. It is backwards compatible and requires no new - keywords. The proposal will go into Python 2.3 when generators - become final and are not imported from __future__. +========= + +Python 2.2 introduced the concept of an iterable interface as +proposed in PEP 234 [3]_. The ``iter()`` factory function was provided +as common calling convention and deep changes were made to use +iterators as a unifying theme throughout Python. The unification +came in the form of establishing a common iterable interface for +mappings, sequences, and file objects. + +Generators, as proposed in PEP 255 [1]_, were introduced as a means +for making it easier to create iterators, especially ones with +complex internal execution or variable states. The availability +of generators makes it possible to improve on the loop counter +ideas in PEP 212 [2]_. Those ideas provided a clean syntax for +iteration with indices and values, but did not apply to all +iterable objects. Also, that approach did not have the memory +friendly benefit provided by generators which do not evaluate the +entire sequence all at once. + +The new proposal is to add a built-in function, ``enumerate()`` which +was made possible once iterators and generators became available. +It provides all iterables with the same advantage that ``iteritems()`` +affords to dictionaries -- a compact, readable, reliable index +notation. Like ``zip()``, it is expected to become a commonly used +looping idiom. + +This suggestion is designed to take advantage of the existing +implementation and require little additional effort to +incorporate. It is backwards compatible and requires no new +keywords. The proposal will go into Python 2.3 when generators +become final and are not imported from ``__future__``. BDFL Pronouncements +=================== + +The new built-in function is ACCEPTED. - The new built-in function is ACCEPTED. +Specification for a new built-in +================================ -Specification for a new built-in: +:: def enumerate(collection): - 'Generates an indexed series: (0,coll[0]), (1,coll[1]) ...' - i = 0 - it = iter(collection) - while 1: - yield (i, it.next()) - i += 1 - - Note A: PEP 212 Loop Counter Iteration [2] discussed several - proposals for achieving indexing. Some of the proposals only work - for lists unlike the above function which works for any generator, - xrange, sequence, or iterable object. Also, those proposals were - presented and evaluated in the world prior to Python 2.2 which did - not include generators. As a result, the non-generator version in - PEP 212 had the disadvantage of consuming memory with a giant list - of tuples. The generator version presented here is fast and - light, works with all iterables, and allows users to abandon the - sequence in mid-stream with no loss of computation effort. - - There are other PEPs which touch on related issues: integer - iterators, integer for-loops, and one for modifying the arguments - to range and xrange. The enumerate() proposal does not preclude - the other proposals and it still meets an important need even if - those are adopted -- the need to count items in any iterable. The - other proposals give a means of producing an index but not the - corresponding value. This is especially problematic if a sequence - is given which doesn't support random access such as a file - object, generator, or sequence defined with __getitem__. - - Note B: Almost all of the PEP reviewers welcomed the function but - were divided as to whether there should be any built-ins. The - main argument for a separate module was to slow the rate of - language inflation. The main argument for a built-in was that the - function is destined to be part of a core programming style, - applicable to any object with an iterable interface. Just as - zip() solves the problem of looping over multiple sequences, the - enumerate() function solves the loop counter problem. - - If only one built-in is allowed, then enumerate() is the most - important general purpose tool, solving the broadest class of - problems while improving program brevity, clarity and reliability. - - Note C: Various alternative names were discussed: - - iterindexed()-- five syllables is a mouthful - index() -- nice verb but could be confused the .index() method - indexed() -- widely liked however adjectives should be avoided - indexer() -- noun did not read well in a for-loop - count() -- direct and explicit but often used in other contexts - itercount() -- direct, explicit and hated by more than one person - iteritems() -- conflicts with key:value concept for dictionaries - itemize() -- confusing because amap.items() != list(itemize(amap)) - enum() -- pithy; less clear than enumerate; too similar to enum - in other languages where it has a different meaning - - All of the names involving 'count' had the further disadvantage of - implying that the count would begin from one instead of zero. - - All of the names involving 'index' clashed with usage in database - languages where indexing implies a sorting operation rather than - linear sequencing. - - Note D: This function was originally proposed with optional start - and stop arguments. GvR pointed out that the function call - enumerate(seqn,4,6) had an alternate, plausible interpretation as - a slice that would return the fourth and fifth elements of the - sequence. To avoid the ambiguity, the optional arguments were - dropped even though it meant losing flexibility as a loop counter. - That flexibility was most important for the common case of - counting from one, as in: - - for linenum, line in enumerate(source,1): print linenum, line - - Comments from GvR: filter and map should die and be subsumed into list - comprehensions, not grow more variants. I'd rather introduce - built-ins that do iterator algebra (e.g. the iterzip that I've - often used as an example). - - I like the idea of having some way to iterate over a sequence - and its index set in parallel. It's fine for this to be a - built-in. - - I don't like the name "indexed"; adjectives do not make good - function names. Maybe iterindexed()? - - Comments from Ka-Ping Yee: I'm also quite happy with everything you - proposed ... and the extra built-ins (really 'indexed' in - particular) are things I have wanted for a long time. - - Comments from Neil Schemenauer: The new built-ins sound okay. Guido - may be concerned with increasing the number of built-ins too - much. You might be better off selling them as part of a - module. If you use a module then you can add lots of useful - functions (Haskell has lots of them that we could steal). - - Comments for Magnus Lie Hetland: I think indexed would be a useful and - natural built-in function. I would certainly use it a lot. I - like indexed() a lot; +1. I'm quite happy to have it make PEP - 281 obsolete. Adding a separate module for iterator utilities - seems like a good idea. - - Comments from the Community: The response to the enumerate() proposal - has been close to 100% favorable. Almost everyone loves the - idea. - - Author response: Prior to these comments, four built-ins were proposed. - After the comments, xmap xfilter and xzip were withdrawn. The - one that remains is vital for the language and is proposed by - itself. Indexed() is trivially easy to implement and can be - documented in minutes. More importantly, it is useful in - everyday programming which does not otherwise involve explicit - use of generators. - - This proposal originally included another function iterzip(). - That was subsequently implemented as the izip() function in - the itertools module. + 'Generates an indexed series: (0,coll[0]), (1,coll[1]) ...' + i = 0 + it = iter(collection) + while 1: + yield (i, it.next()) + i += 1 + +Note A: PEP 212 Loop Counter Iteration [2]_ discussed several +proposals for achieving indexing. Some of the proposals only work +for lists unlike the above function which works for any generator, +xrange, sequence, or iterable object. Also, those proposals were +presented and evaluated in the world prior to Python 2.2 which did +not include generators. As a result, the non-generator version in +PEP 212 had the disadvantage of consuming memory with a giant list +of tuples. The generator version presented here is fast and +light, works with all iterables, and allows users to abandon the +sequence in mid-stream with no loss of computation effort. + +There are other PEPs which touch on related issues: integer +iterators, integer for-loops, and one for modifying the arguments +to range and xrange. The ``enumerate()`` proposal does not preclude +the other proposals and it still meets an important need even if +those are adopted -- the need to count items in any iterable. The +other proposals give a means of producing an index but not the +corresponding value. This is especially problematic if a sequence +is given which doesn't support random access such as a file +object, generator, or sequence defined with ``__getitem__``. + +Note B: Almost all of the PEP reviewers welcomed the function but +were divided as to whether there should be any built-ins. The +main argument for a separate module was to slow the rate of +language inflation. The main argument for a built-in was that the +function is destined to be part of a core programming style, +applicable to any object with an iterable interface. Just as +``zip()`` solves the problem of looping over multiple sequences, the +``enumerate()`` function solves the loop counter problem. + +If only one built-in is allowed, then ``enumerate()`` is the most +important general purpose tool, solving the broadest class of +problems while improving program brevity, clarity and reliability. + +Note C: Various alternative names were discussed: + +================= ============================================================= +``iterindexed()`` five syllables is a mouthful +``index()`` nice verb but could be confused the ``.index()`` method +``indexed()`` widely liked however adjectives should be avoided +``indexer()`` noun did not read well in a for-loop +``count()`` direct and explicit but often used in other contexts +``itercount()`` direct, explicit and hated by more than one person +``iteritems()`` conflicts with key:value concept for dictionaries +``itemize()`` confusing because ``amap.items()`` != ``list(itemize(amap))`` +``enum()`` pithy; less clear than enumerate; too similar to enum + in other languages where it has a different meaning +================= ============================================================= + +All of the names involving 'count' had the further disadvantage of +implying that the count would begin from one instead of zero. + +All of the names involving 'index' clashed with usage in database +languages where indexing implies a sorting operation rather than +linear sequencing. + +Note D: This function was originally proposed with optional start +and stop arguments. GvR pointed out that the function call +enumerate(seqn,4,6) had an alternate, plausible interpretation as +a slice that would return the fourth and fifth elements of the +sequence. To avoid the ambiguity, the optional arguments were +dropped even though it meant losing flexibility as a loop counter. +That flexibility was most important for the common case of +counting from one, as in:: + + for linenum, line in enumerate(source,1): print linenum, line + + +Comments from GvR: + filter and map should die and be subsumed into list + comprehensions, not grow more variants. I'd rather introduce + built-ins that do iterator algebra (e.g. the iterzip that I've + often used as an example). + + I like the idea of having some way to iterate over a sequence + and its index set in parallel. It's fine for this to be a + built-in. + + I don't like the name "indexed"; adjectives do not make good + function names. Maybe ``iterindexed()``? + + +Comments from Ka-Ping Yee: + I'm also quite happy with everything you + proposed ... and the extra built-ins (really 'indexed' in + particular) are things I have wanted for a long time. + + +Comments from Neil Schemenauer: + The new built-ins sound okay. Guido + may be concerned with increasing the number of built-ins too + much. You might be better off selling them as part of a + module. If you use a module then you can add lots of useful + functions (Haskell has lots of them that we could steal). + + +Comments for Magnus Lie Hetland: + I think indexed would be a useful and + natural built-in function. I would certainly use it a lot. I + like ``indexed()`` a lot; +1. I'm quite happy to have it make PEP + 281 obsolete. Adding a separate module for iterator utilities + seems like a good idea. + + +Comments from the Community: + The response to the ``enumerate()`` proposal + has been close to 100% favorable. Almost everyone loves the + idea. + + +Author response: + Prior to these comments, four built-ins were proposed. + After the comments, ``xmap`` ``xfilter`` and ``xzip`` were withdrawn. The + one that remains is vital for the language and is proposed by + itself. ``Indexed()`` is trivially easy to implement and can be + documented in minutes. More importantly, it is useful in + everyday programming which does not otherwise involve explicit + use of generators. + + This proposal originally included another function ``iterzip()``. + That was subsequently implemented as the ``izip()`` function in + the itertools module. References +========== - [1] PEP 255 Simple Generators - http://www.python.org/dev/peps/pep-0255/ +.. [1] PEP 255 Simple Generators + http://www.python.org/dev/peps/pep-0255/ - [2] PEP 212 Loop Counter Iteration - http://www.python.org/dev/peps/pep-0212/ +.. [2] PEP 212 Loop Counter Iteration + http://www.python.org/dev/peps/pep-0212/ - [3] PEP 234 Iterators - http://www.python.org/dev/peps/pep-0234/ +.. [3] PEP 234 Iterators + http://www.python.org/dev/peps/pep-0234/ Copyright +========= - This document has been placed in the public domain. - +This document has been placed in the public domain. - -Local Variables: -mode: indented-text -indent-tabs-mode: nil -fill-column: 70 -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + fill-column: 70 + End: + + diff --git a/pep-0337.txt b/pep-0337.txt index 7d6183b758c..491711954db 100644 --- a/pep-0337.txt +++ b/pep-0337.txt @@ -5,193 +5,204 @@ Last-Modified: $Date$ Author: Michael P. Dubner Status: Deferred Type: Standards Track -Content-Type: text/plain +Content-Type: text/x-rst Created: 02-Oct-2004 Python-Version: 2.5 Post-History: 10-Nov-2004 Abstract +======== - This PEP defines a standard for using the logging system (PEP 282 - [1]) in the standard library. +This PEP defines a standard for using the logging system (PEP 282 [1]_) in the +standard library. - Implementing this PEP will simplify development of daemon - applications. As a downside this PEP requires slight - modifications (however in a back-portable way) to a large number - of standard modules. +Implementing this PEP will simplify development of daemon +applications. As a downside this PEP requires slight +modifications (however in a back-portable way) to a large number +of standard modules. - After implementing this PEP one can use following filtering - scheme: +After implementing this PEP one can use following filtering +scheme:: + + logging.getLogger('py.BaseHTTPServer').setLevel(logging.FATAL) - logging.getLogger('py.BaseHTTPServer').setLevel(logging.FATAL) PEP Deferral +============ - Further exploration of the concepts covered in this PEP has been deferred - for lack of a current champion interested in promoting the goals of the - PEP and collecting and incorporating feedback, and with sufficient - available time to do so effectively. +Further exploration of the concepts covered in this PEP has been deferred +for lack of a current champion interested in promoting the goals of the +PEP and collecting and incorporating feedback, and with sufficient +available time to do so effectively. Rationale +========= - There are a couple of situations when output to stdout or stderr - is impractical: +There are a couple of situations when output to stdout or stderr +is impractical: - - Daemon applications where the framework doesn't allow the - redirection of standard output to some file, but assumes use of - some other form of logging. Examples are syslog under *nix'es - and EventLog under WinNT+. +- Daemon applications where the framework doesn't allow the + redirection of standard output to some file, but assumes use of + some other form of logging. Examples are syslog under \*nix'es + and EventLog under WinNT+. - - GUI applications which want to output every new log entry in - separate pop-up window (i.e. fading OSD). +- GUI applications which want to output every new log entry in + separate pop-up window (i.e. fading OSD). - Also sometimes applications want to filter output entries based on - their source or severity. This requirement can't be implemented - using simple redirection. +Also sometimes applications want to filter output entries based on +their source or severity. This requirement can't be implemented +using simple redirection. - Finally sometimes output needs to be marked with event timestamps, - which can be accomplished with ease using the logging system. +Finally sometimes output needs to be marked with event timestamps, +which can be accomplished with ease using the logging system. Proposal +======== + +Every module usable for daemon and GUI applications should be +rewritten to use the logging system instead of ``print`` or +``sys.stdout.write``. - Every module usable for daemon and GUI applications should be - rewritten to use the logging system instead of 'print' or - 'sys.stdout.write'. - - There should be code like this included in the beginning of every - modified module: +There should be code like this included in the beginning of every +modified module:: - import logging + import logging - _log = logging.getLogger('py.') + _log = logging.getLogger('py.') - A prefix of 'py.' [2] must be used by all modules included in the - standard library distributed along with Python, and only by such - modules (unverifiable). The use of "_log" is intentional as we - don't want to auto-export it. For modules that use log only in - one class a logger can be created inside the class definition as - follows: +A prefix of ``py.`` [2]_ must be used by all modules included in the +standard library distributed along with Python, and only by such +modules (unverifiable). The use of ``_log`` is intentional as we +don't want to auto-export it. For modules that use log only in +one class a logger can be created inside the class definition as +follows:: - class XXX: + class XXX: - __log = logging.getLogger('py.') + __log = logging.getLogger('py.') - Then this class can create access methods to log to this private - logger. +Then this class can create access methods to log to this private +logger. - So "print" and "sys.std{out|err}.write" statements should be - replaced with "_log.{debug|info}", and "traceback.print_exception" - with "_log.exception" or sometimes "_log.debug('...', exc_info=1)". +So ``print`` and ``sys.std{out|err}.write`` statements should be +replaced with ``_log.{debug|info}``, and ``traceback.print_exception`` +with ``_log.exception`` or sometimes ``_log.debug('...', exc_info=1)```. Module List +=========== - Here is a (possibly incomplete) list of modules to be reworked: +Here is a (possibly incomplete) list of modules to be reworked: - - asyncore (dispatcher.log, dispatcher.log_info) +- asyncore (dispatcher.log, dispatcher.log_info) - - BaseHTTPServer (BaseHTTPRequestHandler.log_request, - BaseHTTPRequestHandler.log_error, - BaseHTTPRequestHandler.log_message) +- BaseHTTPServer (BaseHTTPRequestHandler.log_request, + BaseHTTPRequestHandler.log_error, + BaseHTTPRequestHandler.log_message) - - cgi (possibly - is cgi.log used by somebody?) +- cgi (possibly - is cgi.log used by somebody?) - - ftplib (if FTP.debugging) +- ftplib (if FTP.debugging) - - gopherlib (get_directory) +- gopherlib (get_directory) - - httplib (HTTPResponse, HTTPConnection) +- httplib (HTTPResponse, HTTPConnection) - - ihooks (_Verbose) +- ihooks (_Verbose) - - imaplib (IMAP4._mesg) +- imaplib (IMAP4._mesg) - - mhlib (MH.error) +- mhlib (MH.error) - - nntplib (NNTP) +- nntplib (NNTP) - - pipes (Template.makepipeline) +- pipes (Template.makepipeline) - - pkgutil (extend_path) +- pkgutil (extend_path) - - platform (_syscmd_ver) +- platform (_syscmd_ver) - - poplib (if POP3._debugging) +- poplib (if POP3._debugging) - - profile (if Profile.verbose) +- profile (if Profile.verbose) - - robotparser (_debug) +- robotparser (_debug) - - smtplib (if SGMLParser.verbose) +- smtplib (if SGMLParser.verbose) - - shlex (if shlex.debug) +- shlex (if shlex.debug) - - smtpd (SMTPChannel/PureProxy where print >> DEBUGSTREAM) +- smtpd (SMTPChannel/PureProxy where print >> DEBUGSTREAM) - - smtplib (if SMTP.debuglevel) +- smtplib (if SMTP.debuglevel) - - SocketServer (BaseServer.handle_error) +- SocketServer (BaseServer.handle_error) - - telnetlib (if Telnet.debuglevel) +- telnetlib (if Telnet.debuglevel) - - threading? (_Verbose._note, Thread.__bootstrap) +- threading? (_Verbose._note, Thread.__bootstrap) - - timeit (Timer.print_exc) +- timeit (Timer.print_exc) - - trace +- trace - - uu (decode) +- uu (decode) - Additionally there are a couple of modules with commented debug - output or modules where debug output should be added. For - example: +Additionally there are a couple of modules with commented debug +output or modules where debug output should be added. For +example: - - urllib +- urllib - Finally possibly some modules should be extended to provide more - debug information. +Finally possibly some modules should be extended to provide more +debug information. Doubtful Modules +================ - Listed here are modules that the community will propose for - addition to the module list and modules that the community say - should be removed from the module list. +Listed here are modules that the community will propose for +addition to the module list and modules that the community say +should be removed from the module list. - - tabnanny (check) +- tabnanny (check) Guidelines for Logging Usage +============================ - Also we can provide some recommendation to authors of library - modules so they all follow the same format of naming loggers. I - propose that non-standard library modules should use loggers named - after their full names, so a module "spam" in sub-package "junk" - of package "dummy" will be named "dummy.junk.spam" and, of course, - the "__init__" module of the same sub-package will have the logger - name "dummy.junk". +Also we can provide some recommendation to authors of library +modules so they all follow the same format of naming loggers. I +propose that non-standard library modules should use loggers named +after their full names, so a module "spam" in sub-package "junk" +of package "dummy" will be named "dummy.junk.spam" and, of course, +the ``__init__`` module of the same sub-package will have the logger +name "dummy.junk". References +========== - [1] PEP 282, A Logging System, Vinay Sajip, Trent Mick - http://www.python.org/dev/peps/pep-0282/ +.. [1] PEP 282, A Logging System, Vinay Sajip, Trent Mick + http://www.python.org/dev/peps/pep-0282/ - [2] http://mail.python.org/pipermail/python-dev/2004-October/049282.html +.. [2] http://mail.python.org/pipermail/python-dev/2004-October/049282.html Copyright +========= + +This document has been placed in the public domain. - This document has been placed in the public domain. - -Local Variables: -mode: indented-text -indent-tabs-mode: nil -sentence-end-double-space: t -fill-column: 70 -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/pep-0356.txt b/pep-0356.txt index 4193b1b6829..0d8bde7d6a2 100644 --- a/pep-0356.txt +++ b/pep-0356.txt @@ -5,182 +5,205 @@ Last-Modified: $Date$ Author: Neal Norwitz, Guido van Rossum, Anthony Baxter Status: Final Type: Informational +Content-Type: text/x-rst Created: 07-Feb-2006 Python-Version: 2.5 Post-History: + Abstract +======== - This document describes the development and release schedule for - Python 2.5. The schedule primarily concerns itself with PEP-sized - items. Small features may be added up to and including the first - beta release. Bugs may be fixed until the final release. +This document describes the development and release schedule for +Python 2.5. The schedule primarily concerns itself with PEP-sized +items. Small features may be added up to and including the first +beta release. Bugs may be fixed until the final release. - There will be at least two alpha releases, two beta releases, and - one release candidate. The release date is planned for - 12 September 2006. +There will be at least two alpha releases, two beta releases, and +one release candidate. The release date is planned for +12 September 2006. Release Manager +=============== - Anthony Baxter has volunteered to be Release Manager. - - Martin von Loewis is building the Windows installers, - Ronald Oussoren is building the Mac installers, - Fred Drake the doc packages and - Sean Reifschneider the RPMs. +- Anthony Baxter has volunteered to be Release Manager. +- Martin von Loewis is building the Windows installers, +- Ronald Oussoren is building the Mac installers, +- Fred Drake the doc packages and +- Sean Reifschneider the RPMs. Release Schedule +================ - alpha 1: April 5, 2006 [completed] - alpha 2: April 27, 2006 [completed] - beta 1: June 20, 2006 [completed] - beta 2: July 11, 2006 [completed] - beta 3: August 3, 2006 [completed] - rc 1: August 17, 2006 [completed] - rc 2: September 12, 2006 [completed] - final: September 19, 2006 [completed] +- alpha 1: April 5, 2006 [completed] +- alpha 2: April 27, 2006 [completed] +- beta 1: June 20, 2006 [completed] +- beta 2: July 11, 2006 [completed] +- beta 3: August 3, 2006 [completed] +- rc 1: August 17, 2006 [completed] +- rc 2: September 12, 2006 [completed] +- final: September 19, 2006 [completed] Completed features for 2.5 +========================== + +- PEP 308: Conditional Expressions +- PEP 309: Partial Function Application +- PEP 314: Metadata for Python Software Packages v1.1 +- PEP 328: Absolute/Relative Imports +- PEP 338: Executing Modules as Scripts +- PEP 341: Unified try-except/try-finally to try-except-finally +- PEP 342: Coroutines via Enhanced Generators +- PEP 343: The "with" Statement (still need updates in Doc/ref and for the + contextlib module) +- PEP 352: Required Superclass for Exceptions +- PEP 353: Using ``ssize_t`` as the index type +- PEP 357: Allowing Any Object to be Used for Slicing - PEP 308: Conditional Expressions - PEP 309: Partial Function Application - PEP 314: Metadata for Python Software Packages v1.1 - PEP 328: Absolute/Relative Imports - PEP 338: Executing Modules as Scripts - PEP 341: Unified try-except/try-finally to try-except-finally - PEP 342: Coroutines via Enhanced Generators - PEP 343: The "with" Statement - (still need updates in Doc/ref and for the contextlib module) - PEP 352: Required Superclass for Exceptions - PEP 353: Using ssize_t as the index type - PEP 357: Allowing Any Object to be Used for Slicing +- ASCII became the default coding - - ASCII became the default coding +- AST-based compiler - - AST-based compiler - - Access to C AST from Python through new _ast module +- Access to C AST from Python through new _ast module - - any()/all() builtin truth functions +- ``any()``/``all()`` builtin truth functions - New standard library modules +New standard library modules: - - cProfile -- suitable for profiling long running applications - with minimal overhead +- ``cProfile`` -- suitable for profiling long running applications + with minimal overhead - - ctypes -- optional component of the windows installer +- ``ctypes`` -- optional component of the windows installer - - ElementTree and cElementTree -- by Fredrik Lundh +- ``ElementTree`` and ``cElementTree`` -- by Fredrik Lundh - - hashlib -- adds support for SHA-224, -256, -384, and -512 - (replaces old md5 and sha modules) +- ``hashlib`` -- adds support for SHA-224, -256, -384, and -512 + (replaces old md5 and sha modules) - - msilib -- for creating MSI files and bdist_msi in distutils. +- ``msilib`` -- for creating MSI files and bdist_msi in distutils. - - pysqlite +- ``pysqlite`` - - uuid +- ``uuid`` - - wsgiref +- ``wsgiref`` - Other notable features +Other notable features: - - Added support for reading shadow passwords (http://python.org/sf/579435) +- Added support for reading shadow passwords [1]_ - - Added support for the Unicode 4.1 UCD +- Added support for the Unicode 4.1 UCD - - Added PEP 302 zipfile/__loader__ support to the following modules: - warnings, linecache, inspect, traceback, site, and doctest +- Added PEP 302 ``zipfile``/``__loader__`` support to the following modules: + ``warnings``, ``linecache``, ``inspect``, ``traceback``, ``site``, and + ``doctest`` - - Added pybench Python benchmark suite -- by Marc-Andre Lemburg +- Added ``pybench`` Python benchmark suite -- by Marc-Andre Lemburg - - Add write support for mailboxes from the code in sandbox/mailbox. - (Owner: A.M. Kuchling. It would still be good if another person - would take a look at the new code.) +- Add write support for mailboxes from the code in sandbox/mailbox. + (Owner: A.M. Kuchling. It would still be good if another person + would take a look at the new code.) - - Support for building "fat" Mac binaries (Intel and PPC) +- Support for building "fat" Mac binaries (Intel and PPC) - - Add new icons for Windows with the new Python logo? +- Add new icons for Windows with the new Python logo? - - New utilities in functools to help write wrapper functions that - support naive introspection (e.g. having f.__name__ return - the original function name). +- New utilities in ``functools`` to help write wrapper functions that + support naive introspection (e.g. having ``f.__name__`` return + the original function name). - - Upgrade pyexpat to use expat 2.0. +- Upgrade ``pyexpat`` to use expat 2.0. + +- Python core now compiles cleanly with g++ - - Python core now compiles cleanly with g++ Possible features for 2.5 +========================= - Each feature below should implemented prior to beta1 or - will require BDFL approval for inclusion in 2.5. +Each feature below should implemented prior to beta1 or +will require BDFL approval for inclusion in 2.5. - - Modules under consideration for inclusion: +- Modules under consideration for inclusion: - - Add new icons for MacOS and Unix with the new Python logo? - (Owner: ???) - MacOS: http://hcs.harvard.edu/~jrus/python/prettified-py-icons.png +- Add new icons for MacOS and Unix with the new Python logo? + (Owner: ???) + MacOS: http://hcs.harvard.edu/~jrus/python/prettified-py-icons.png - - Check the various bits of code in Demo/ all still work, update or - remove the ones that don't. - (Owner: Anthony) +- Check the various bits of code in Demo/ all still work, update or + remove the ones that don't. + (Owner: Anthony) - - All modules in Modules/ should be updated to be ssize_t clean. - (Owner: Neal) +- All modules in Modules/ should be updated to be ssize_t clean. + (Owner: Neal) -Deferred until 2.6: +Deferred until 2.6 +================== - - bdist_deb in distutils package - http://mail.python.org/pipermail/python-dev/2006-February/060926.html +- ``bdist_deb`` in distutils package [2]_ - - bdist_egg in distutils package +- ``bdist_egg`` in distutils package - - pure python pgen module - (Owner: Guido) +- pure python ``pgen`` module + (Owner: Guido) - - Remove the fpectl module? +- Remove the ``fpectl`` module? - - Make everything in Modules/ build cleanly with g++ +- Make everything in Modules/ build cleanly with g++ Open issues +=========== + +- Bugs that need resolving before release, ie, they block release: - - Bugs that need resolving before release, ie, they block release: + None - None +- Bugs deferred until 2.5.1 (or later): - - Bugs deferred until 2.5.1 (or later) - http://python.org/sf/1544279 - Socket module is not thread-safe - http://python.org/sf/1541420 - tools and demo missing from windows - http://python.org/sf/1542451 - crash with continue in nested try/finally - http://python.org/sf/1475523 - gettext.py bug (owner: Martin v. Loewis) - http://python.org/sf/1467929 - %-formatting and dicts - http://python.org/sf/1446043 - unicode() does not raise LookupError + * http://python.org/sf/1544279 - ``Socket`` module is not thread-safe + * http://python.org/sf/1541420 - tools and demo missing from windows + * http://python.org/sf/1542451 - crash with continue in nested try/finally + * http://python.org/sf/1475523 - gettext.py bug (owner: Martin v. Loewis) + * http://python.org/sf/1467929 - %-formatting and dicts + * http://python.org/sf/1446043 - ``unicode()`` does not raise ``LookupError`` - - The PEP 302 changes to (at least) pkgutil, runpy and pydoc must be - documented. +- The PEP 302 changes to (at least) ``pkgutil``, ``runpy`` and ``pydoc`` must + be documented. - - test_zipfile64 takes too long and too much disk space for - most of the buildbots. How should this be handled? - It is currently disabled. +- ``test_zipfile64`` takes too long and too much disk space for + most of the buildbots. How should this be handled? + It is currently disabled. - - should C modules listed in "Undocumented modules" be removed too? - "timing" (listed as obsolete), "cl" (listed as possibly not up-to-date), - and "sv" (listed as obsolete hardware specific). +- should C modules listed in "Undocumented modules" be removed too? + "timing" (listed as obsolete), "cl" (listed as possibly not up-to-date), + and "sv" (listed as obsolete hardware specific). + + +References +========== + +.. [1] Shadow Password Support Module + http://python.org/sf/579435 + +.. [2] Joe Smith, bdist_* to stdlib? + http://mail.python.org/pipermail/python-dev/2006-February/060926.html Copyright +========= + +This document has been placed in the public domain. - This document has been placed in the public domain. - -Local Variables: -mode: indented-text -indent-tabs-mode: nil -sentence-end-double-space: t -fill-column: 70 -coding: utf-8 -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + coding: utf-8 + End: diff --git a/pep-0379.txt b/pep-0379.txt index b043776b37c..607b26959f2 100644 --- a/pep-0379.txt +++ b/pep-0379.txt @@ -5,184 +5,193 @@ Last-Modified: $Date$ Author: Jervis Whitley Status: Withdrawn Type: Standards Track -Content-Type: text/plain +Content-Type: text/x-rst Created: 14-Mar-2009 Python-Version: 2.7, 3.2 Post-History: Abstract +======== - This PEP adds a new assignment expression to the Python language - to make it possible to assign the result of an expression in - almost any place. The new expression will allow the assignment of - the result of an expression at first use (in a comparison for - example). +This PEP adds a new assignment expression to the Python language +to make it possible to assign the result of an expression in +almost any place. The new expression will allow the assignment of +the result of an expression at first use (in a comparison for +example). Motivation and Summary +====================== - Issue1714448 "if something as x:" [1] describes a feature to allow - assignment of the result of an expression in an if statement to a - name. It supposed that the 'as' syntax could be borrowed for this - purpose. Many times it is not the expression itself that is - interesting, rather one of the terms that make up the - expression. To be clear, something like this: - - if (f_result() == [1, 2, 3]) as res: +Issue1714448 "if something as x:" [1]_ describes a feature to allow +assignment of the result of an expression in an if statement to a +name. It supposed that the ``as`` syntax could be borrowed for this +purpose. Many times it is not the expression itself that is +interesting, rather one of the terms that make up the +expression. To be clear, something like this:: - seems awfully limited, when this: + if (f_result() == [1, 2, 3]) as res: - if (f_result() as res) == [1, 2, 3]: +seems awfully limited, when this:: - is probably the desired result. + if (f_result() as res) == [1, 2, 3]: + +is probably the desired result. Use Cases - - See the Examples section near the end. +========= + +See the Examples section near the end. Specification +============= + +A new expression is proposed with the (nominal) syntax:: - A new expression is proposed with the (nominal) syntax: + EXPR -> VAR - EXPR -> VAR +This single expression does the following: - This single expression does the following: +- Evaluate the value of ``EXPR``, an arbitrary expression; +- Assign the result to ``VAR``, a single assignment target; and +- Leave the result of ``EXPR`` on the Top of Stack (TOS) - - Evaluate the value of EXPR, an arbitrary expression; - - Assign the result to VAR, a single assignment target; and - - Leave the result of EXPR on the Top of Stack (TOS) - - Here '->' or (RARROW) has been used to illustrate the concept that - the result of EXPR is assigned to VAR. +Here ``->`` or (``RARROW``) has been used to illustrate the concept that +the result of ``EXPR`` is assigned to ``VAR``. - The translation of the proposed syntax is: +The translation of the proposed syntax is:: - VAR = (EXPR) - (EXPR) + VAR = (EXPR) + (EXPR) - The assignment target can be either an attribute, a subscript or - name: +The assignment target can be either an attribute, a subscript or +name:: - f() -> name[0] # where 'name' exists previously. + f() -> name[0] # where 'name' exists previously. f() -> name.attr # again 'name' exists prior to this - expression. + expression.: - f() -> name + f() -> name - This expression should be available anywhere that an expression is - currently accepted. +This expression should be available anywhere that an expression is +currently accepted. - All exceptions that are currently raised during invalid - assignments will continue to be raised when using the assignment - expression. For example, a NameError will be raised when in - example 1 and 2 above if 'name' is not previously defined, or an - IndexError if index 0 was out of range. +All exceptions that are currently raised during invalid +assignments will continue to be raised when using the assignment +expression. For example, a ``NameError`` will be raised when in +example 1 and 2 above if ``name`` is not previously defined, or an +``IndexError`` if index 0 was out of range. Examples from the Standard Library - - The following two examples were chosen after a brief search - through the standard library, specifically both are from ast.py - which happened to be open at the time of the search. - - Original: - - def walk(node): - from collections import deque - todo = deque([node]) - while todo: - node = todo.popleft() - todo.extend(iter_child_nodes(node)) - yield node - - Using assignment expression: - - def walk(node): - from collections import deque - todo = deque([node]) - while todo: - todo.extend(iter_child_nodes(todo.popleft() -> node)) - yield node - - Original: - - def get_docstring(node, clean=True): - if not isinstance(node, (FunctionDef, ClassDef, Module)): - raise TypeError("%r can't have docstrings" - % node.__class__.__name__) - if node.body and isinstance(node.body[0], Expr) and \ - isinstance(node.body[0].value, Str): - if clean: - import inspect - return inspect.cleandoc(node.body[0].value.s) - return node.body[0].value.s - - Using assignment expression: - - def get_docstring(node, clean=True): - if not isinstance(node, (FunctionDef, ClassDef, Module)): - raise TypeError("%r can't have docstrings" - % node.__class__.__name__) - if node.body -> body and isinstance(body[0] -> elem, Expr) and \ - isinstance(elem.value -> value, Str): - if clean: - import inspect - return inspect.cleandoc(value.s) - return value.s +================================== + +The following two examples were chosen after a brief search +through the standard library, specifically both are from ast.py +which happened to be open at the time of the search. + +Original:: + + def walk(node): + from collections import deque + todo = deque([node]) + while todo: + node = todo.popleft() + todo.extend(iter_child_nodes(node)) + yield node + +Using assignment expression:: + + def walk(node): + from collections import deque + todo = deque([node]) + while todo: + todo.extend(iter_child_nodes(todo.popleft() -> node)) + yield node + +Original:: + + def get_docstring(node, clean=True): + if not isinstance(node, (FunctionDef, ClassDef, Module)): + raise TypeError("%r can't have docstrings" + % node.__class__.__name__) + if node.body and isinstance(node.body[0], Expr) and \ + isinstance(node.body[0].value, Str): + if clean: + import inspect + return inspect.cleandoc(node.body[0].value.s) + return node.body[0].value.s + +Using assignment expression:: + + def get_docstring(node, clean=True): + if not isinstance(node, (FunctionDef, ClassDef, Module)): + raise TypeError("%r can't have docstrings" + % node.__class__.__name__) + if node.body -> body and isinstance(body[0] -> elem, Expr) and \ + isinstance(elem.value -> value, Str): + if clean: + import inspect + return inspect.cleandoc(value.s) + return value.s Examples +======== - The examples shown below highlight some of the desirable features - of the assignment expression, and some of the possible corner - cases. +The examples shown below highlight some of the desirable features +of the assignment expression, and some of the possible corner +cases. - 1. Assignment in an if statement for use later. +1. Assignment in an if statement for use later:: - def expensive(): - import time; time.sleep(1) - return 'spam' + def expensive(): + import time; time.sleep(1) + return 'spam' - if expensive() -> res in ('spam', 'eggs'): - dosomething(res) + if expensive() -> res in ('spam', 'eggs'): + dosomething(res) - 2. Assignment in a while loop clause. +2. Assignment in a while loop clause:: - while len(expensive() -> res) == 4: - dosomething(res) + while len(expensive() -> res) == 4: + dosomething(res) - 3. Keep the iterator object from the for loop. +3. Keep the iterator object from the for loop:: - for ch in expensive() -> res: - sell_on_internet(res) + for ch in expensive() -> res: + sell_on_internet(res) - 4. Corner case. +4. Corner case:: - for ch -> please_dont in expensive(): - pass - # who would want to do this? Not I. + for ch -> please_dont in expensive(): + pass + # who would want to do this? Not I. References +========== - [1] Issue1714448 "if something as x:", k0wax - http://bugs.python.org/issue1714448 +.. [1] Issue1714448 "if something as x:", k0wax + http://bugs.python.org/issue1714448 Copyright +========= + +This document has been placed in the public domain. - This document has been placed in the public domain. - -Local Variables: -mode: indented-text -indent-tabs-mode: nil -sentence-end-double-space: t -fill-column: 70 -coding: utf-8 -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + coding: utf-8 + End: diff --git a/pep-3144.txt b/pep-3144.txt index 96a01b0ac1c..ca606044c4b 100644 --- a/pep-3144.txt +++ b/pep-3144.txt @@ -7,191 +7,203 @@ BDFL-Delegate: Nick Coghlan Discussions-To: Status: Final Type: Standards Track -Content-Type: text/plain +Content-Type: text/x-rst Created: 6-Feb-2012 Python-Version: 3.3 Resolution: http://mail.python.org/pipermail/python-dev/2012-May/119474.html -Abstract: - This PEP proposes a design and for an IP address manipulation module for - python. +Abstract +======== +This PEP proposes a design and for an IP address manipulation module for +python. -PEP Acceptance: - This PEP was accepted by Nick Coghlan on the 15th of May, 2012. +PEP Acceptance +============== +This PEP was accepted by Nick Coghlan on the 15th of May, 2012. -Motivation: - Several very good IP address modules for python already exist. - The truth is that all of them struggle with the balance between - adherence to Pythonic principals and the shorthand upon which - network engineers and administrators rely. ipaddress aims to - strike the right balance. +Motivation +========== +Several very good IP address modules for python already exist. +The truth is that all of them struggle with the balance between +adherence to Pythonic principals and the shorthand upon which +network engineers and administrators rely. ipaddress aims to +strike the right balance. -Rationale: - The existence of several Python IP address manipulation modules is - evidence of an outstanding need for the functionality this module - seeks to provide. +Rationale +========= +The existence of several Python IP address manipulation modules is +evidence of an outstanding need for the functionality this module +seeks to provide. -Background: - PEP 3144 and ipaddr have been up for inclusion before. The - version of the library specified here is backwards incompatible - with the version on PyPI and the one which was discussed before. - In order to avoid confusing users of the current ipaddr, I've - renamed this version of the library "ipaddress". +Background +========== - The main differences between ipaddr and ipaddress are: +PEP 3144 and ipaddr have been up for inclusion before. The +version of the library specified here is backwards incompatible +with the version on PyPI and the one which was discussed before. +In order to avoid confusing users of the current ipaddr, I've +renamed this version of the library "ipaddress". - * ipaddress *Network classes are equivalent to the ipaddr *Network - class counterparts with the strict flag set to True. +The main differences between ipaddr and ipaddress are: - * ipaddress *Interface classes are equivalent to the ipaddr - *Network class counterparts with the strict flag set to False. +* ipaddress \*Network classes are equivalent to the ipaddr \*Network + class counterparts with the strict flag set to True. - * The factory functions in ipaddress were renamed to disambiguate - them from classes. +* ipaddress \*Interface classes are equivalent to the ipaddr + \*Network class counterparts with the strict flag set to False. - * A few attributes were renamed to disambiguate their purpose as - well. (eg. network, network_address) +* The factory functions in ipaddress were renamed to disambiguate + them from classes. - * A number of methods and functions which returned containers in ipaddr now - return iterators. This includes, subnets, address_exclude, - summarize_address_range and collapse_address_list. +* A few attributes were renamed to disambiguate their purpose as + well. (eg. network, network_address) +* A number of methods and functions which returned containers in ipaddr now + return iterators. This includes, subnets, address_exclude, + summarize_address_range and collapse_address_list. - Due to the backwards incompatible API changes between ipaddress and ipaddr, - the proposal is to add the module using the new provisional API status: - * http://docs.python.org/dev/glossary.html#term-provisional-package +Due to the backwards incompatible API changes between ipaddress and ipaddr, +the proposal is to add the module using the new provisional API status: +* http://docs.python.org/dev/glossary.html#term-provisional-package - Relevant messages on python-dev: - * http://mail.python.org/pipermail/python-dev/2012-January/116016.html - * http://mail.python.org/pipermail/python-dev/2012-February/116656.html - * http://mail.python.org/pipermail/python-dev/2012-February/116688.html +Relevant messages on python-dev: +* http://mail.python.org/pipermail/python-dev/2012-January/116016.html +* http://mail.python.org/pipermail/python-dev/2012-February/116656.html +* http://mail.python.org/pipermail/python-dev/2012-February/116688.html -Specification: - The ipaddr module defines a total of 6 new public classes, 3 for - manipulating IPv4 objects and 3 for manipulating IPv6 objects. - The classes are as follows: +Specification +============= - IPv4Address/IPv6Address - These define individual addresses, for - example the IPv4 address returned by an A record query for - www.google.com (74.125.224.84) or the IPv6 address returned by a - AAAA record query for ipv6.google.com (2001:4860:4001:801::1011). +The ipaddr module defines a total of 6 new public classes, 3 for +manipulating IPv4 objects and 3 for manipulating IPv6 objects. +The classes are as follows: - IPv4Network/IPv6Network - These define networks or groups of - addresses, for example the IPv4 network reserved for multicast use - (224.0.0.0/4) or the IPv6 network reserved for multicast - (ff00::/8, wow, that's big). +- IPv4Address/IPv6Address - These define individual addresses, for + example the IPv4 address returned by an A record query for + www.google.com (74.125.224.84) or the IPv6 address returned by a + AAAA record query for ipv6.google.com (2001:4860:4001:801::1011). - IPv4Interface/IPv6Interface - These hybrid classes refer to an - individual address on a given network. For example, the IPV4 - address 192.0.2.1 on the network 192.0.2.0/24 could be referred to - as 192.0.2.1/24. Likewise, the IPv6 address 2001:DB8::1 on the - network 2001:DB8::/96 could be referred to as 2001:DB8::1/96. - It's very common to refer to addresses assigned to computer - network interfaces like this, hence the Interface name. +- IPv4Network/IPv6Network - These define networks or groups of + addresses, for example the IPv4 network reserved for multicast use + (224.0.0.0/4) or the IPv6 network reserved for multicast + (ff00::/8, wow, that's big). - All IPv4 classes share certain characteristics and methods; the - number of bits needed to represent them, whether or not they - belong to certain special IPv4 network ranges, etc. Similarly, - all IPv6 classes share characteristics and methods. +- IPv4Interface/IPv6Interface - These hybrid classes refer to an + individual address on a given network. For example, the IPV4 + address 192.0.2.1 on the network 192.0.2.0/24 could be referred to + as 192.0.2.1/24. Likewise, the IPv6 address 2001:DB8::1 on the + network 2001:DB8::/96 could be referred to as 2001:DB8::1/96. + It's very common to refer to addresses assigned to computer + network interfaces like this, hence the Interface name. - ipaddr makes extensive use of inheritance to avoid code - duplication as much as possible. The parent classes are private, - but they are outlined here: +All IPv4 classes share certain characteristics and methods; the +number of bits needed to represent them, whether or not they +belong to certain special IPv4 network ranges, etc. Similarly, +all IPv6 classes share characteristics and methods. - _IPAddrBase - Provides methods common to all ipaddr objects. +ipaddr makes extensive use of inheritance to avoid code +duplication as much as possible. The parent classes are private, +but they are outlined here: - _BaseAddress - Provides methods common to IPv4Address and - IPv6Address. +- _IPAddrBase - Provides methods common to all ipaddr objects. - _BaseInterface - Provides methods common to IPv4Interface and - IPv6Interface, as well as IPv4Network and IPv6Network (ipaddr - treats the Network classes as a special case of Interface). +- _BaseAddress - Provides methods common to IPv4Address and + IPv6Address. - _BaseV4 - Provides methods and variables (eg, _max_prefixlen) - common to all IPv4 classes. +- _BaseInterface - Provides methods common to IPv4Interface and + IPv6Interface, as well as IPv4Network and IPv6Network (ipaddr + treats the Network classes as a special case of Interface). - _BaseV6 - Provides methods and variables common to all IPv6 classes. +- _BaseV4 - Provides methods and variables (eg, _max_prefixlen) + common to all IPv4 classes. - Comparisons between objects of differing IP versions results in a - TypeError [1]. Additionally, comparisons of objects with - different _Base parent classes results in a TypeError. The effect - of the _Base parent class limitation is that IPv4Interface's can - be compared to IPv4Network's and IPv6Interface's can be compared - to IPv6Network's. +- _BaseV6 - Provides methods and variables common to all IPv6 classes. +Comparisons between objects of differing IP versions results in a +``TypeError`` [1]_. Additionally, comparisons of objects with +different _Base parent classes results in a ``TypeError``. The effect +of the _Base parent class limitation is that IPv4Interface's can +be compared to IPv4Network's and IPv6Interface's can be compared +to IPv6Network's. -Reference Implementation: - The current reference implementation can be found at: - http://code.google.com/p/ipaddress-py/source/browse/ipaddress.py +Reference Implementation +======================== - Or see the tarball to include the README and unittests. - http://code.google.com/p/ipaddress-py/downloads/detail?name=ipaddress-1.0.tar.gz +The current reference implementation can be found at: - More information about using the reference implementation can be - found at: http://code.google.com/p/ipaddr-py/wiki/Using3144 +http://code.google.com/p/ipaddress-py/source/browse/ipaddress.py +Or see the tarball to include the README and unittests. +http://code.google.com/p/ipaddress-py/downloads/detail?name=ipaddress-1.0.tar.gz -References: +More information about using the reference implementation can be +found at: http://code.google.com/p/ipaddr-py/wiki/Using3144 - [1] Appealing to authority is a logical fallacy, but Vint Cerf is an - authority who can't be ignored. Full text of the email - follows: +References +========== - """ - I have seen a substantial amount of traffic about IPv4 and - IPv6 comparisons and the general consensus is that these are - not comparable. - If we were to take a very simple minded view, we might treat - these as pure integers in which case there is an ordering but - not a useful one. +.. [1] Appealing to authority is a logical fallacy, but Vint Cerf is an + authority who can't be ignored. Full text of the email + follows: - In the IPv4 world, "length" is important because we take - longest (most specific) address first for routing. Length is - determine by the mask, as you know. + """ + I have seen a substantial amount of traffic about IPv4 and + IPv6 comparisons and the general consensus is that these are + not comparable. - Assuming that the same style of argument works in IPv6, we - would have to conclude that treating an IPv6 value purely as - an integer for comparison with IPv4 would lead to some really - strange results. + If we were to take a very simple minded view, we might treat + these as pure integers in which case there is an ordering but + not a useful one. - All of IPv4 space would lie in the host space of 0::0/96 - prefix of IPv6. For any useful interpretation of IPv4, this is - a non-starter. + In the IPv4 world, "length" is important because we take + longest (most specific) address first for routing. Length is + determine by the mask, as you know. - I think the only sensible conclusion is that IPv4 values and - IPv6 values should be treated as non-comparable. + Assuming that the same style of argument works in IPv6, we + would have to conclude that treating an IPv6 value purely as + an integer for comparison with IPv4 would lead to some really + strange results. - Vint - """ + All of IPv4 space would lie in the host space of 0::0/96 + prefix of IPv6. For any useful interpretation of IPv4, this is + a non-starter. + I think the only sensible conclusion is that IPv4 values and + IPv6 values should be treated as non-comparable. -Copyright: + Vint + """ - This document has been placed in the public domain. +Copyright +========= +This document has been placed in the public domain. -Local Variables: -mode: indented-text -indent-tabs-mode: nil -sentence-end-double-space: t -fill-column: 70 -coding: utf-8 -End: + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + coding: utf-8 + End: