[Python-checkins] python/dist/src/Doc/tut glossary.tex, 1.9,
1.9.4.1 tut.tex, 1.261, 1.261.2.1
rhettinger at users.sourceforge.net
rhettinger at users.sourceforge.net
Thu Dec 2 09:57:23 CET 2004
Update of /cvsroot/python/python/dist/src/Doc/tut
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv20401/tut
Modified Files:
Tag: release24-maint
glossary.tex tut.tex
Log Message:
Backport minor documentation fixups.
Index: glossary.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/tut/glossary.tex,v
retrieving revision 1.9
retrieving revision 1.9.4.1
diff -u -d -r1.9 -r1.9.4.1
--- glossary.tex 7 Jun 2004 21:52:47 -0000 1.9
+++ glossary.tex 2 Dec 2004 08:57:19 -0000 1.9.4.1
@@ -40,7 +40,7 @@
The implicit conversion of an instance of one type to another during an
operation which involves two arguments of the same type. For example,
-{}\code{int(3.15)} converts the floating point number to the integer,
+{}\code{int(3.15)} converts the floating point number to the integer
{}\code{3}, but in {}\code{3+4.5}, each argument is of a different type (one
int, one float), and both must be converted to the same type before they can
be added or it will raise a {}\code{TypeError}. Coercion between two
@@ -169,7 +169,7 @@
An object with fixed value. Immutable objects are numbers, strings or
tuples (and more). Such an object cannot be altered. A new object
has to be created if a different value has to be stored. They play an
-important role in places where a constant hash value is needed. For
+important role in places where a constant hash value is needed, for
example as a key in a dictionary.
\index{integer division}
@@ -189,7 +189,7 @@
\index{interactive}
\item[interactive]
Python has an interactive interpreter which means that you can try out
-things and directly see its result. Just launch \code{python} with no
+things and immediately see their results. Just launch \code{python} with no
arguments (possibly by selecting it from your computer's main menu).
It is a very powerful way to test out new ideas or inspect modules and
packages (remember \code{help(x)}).
@@ -235,7 +235,7 @@
(such as a \class{list}) produces a fresh new iterator each time you
pass it to the \function{iter()} function or use it in a
{}\keyword{for} loop. Attempting this with an iterator will just
-return the same exhausted iterator object from the second iteration
+return the same exhausted iterator object used in the previous iteration
pass, making it appear like an empty container.
\index{list comprehension}
@@ -245,7 +245,15 @@
\% x for x in range(256) if x \% 2 == 0]} generates a list of strings
containing hex numbers (0x..) that are even and in the range from 0 to 255.
The \keyword{if} clause is optional. If omitted, all elements in
-{}\code{range(256)} are processed in that case.
+{}\code{range(256)} are processed.
+
+
+\index{LBYL}
+\item[LBYL]
+Look before you leap. This coding style explicitly tests for
+pre-conditions before making calls or lookups. This style contrasts
+with the \emph{EAFP} approach and is characterized by the presence of
+many \keyword{if} statements.
\index{mapping}
\item[mapping]
@@ -265,13 +273,6 @@
tracking object creation, implementing singletons, and many other
tasks.
-\index{LBYL}
-\item[LBYL]
-Look before you leap. This coding style explicitly tests for
-pre-conditions before making calls or lookups. This style contrasts
-with the \emph{EAFP} approach and is characterized the presence of
-many \keyword{if} statements.
-
\index{mutable}
\item[mutable]
Mutable objects can change their value but keep their \function{id()}.
@@ -280,8 +281,8 @@
\index{namespace}
\item[namespace]
The place where a variable is stored. Namespaces are implemented as
-dictionary. There is the local, global and builtins namespace and the
-nested namespaces in objects (in methods). Namespaces support
+dictionaries. There are the local, global and builtin namespaces
+as well asnested namespaces in objects (in methods). Namespaces support
modularity by preventing naming conflicts. For instance, the
functions \function{__builtin__.open()} and \function{os.open()} are
distinguished by their namespaces. Namespaces also aid readability
@@ -312,7 +313,7 @@
\index{Python3000}
\item[Python3000]
-A mythical python release, allowed not to be backward compatible, with
+A mythical python release, not required be backward compatible, with
telepathic interface.
\index{__slots__}
@@ -321,7 +322,7 @@
pre-declaring space for instance attributes and eliminating instance
dictionaries. Though popular, the technique is somewhat tricky to get
right and is best reserved for rare cases where there are large
-numbers of instances in a memory critical application.
+numbers of instances in a memory-critical application.
\index{sequence}
\item[sequence]
Index: tut.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/tut/tut.tex,v
retrieving revision 1.261
retrieving revision 1.261.2.1
diff -u -d -r1.261 -r1.261.2.1
--- tut.tex 29 Nov 2004 13:12:44 -0000 1.261
+++ tut.tex 2 Dec 2004 08:57:19 -0000 1.261.2.1
@@ -33,7 +33,7 @@
The Python interpreter and the extensive standard library are freely
available in source or binary form for all major platforms from the
-Python Web site, \url{http://www.python.org/}, and can be freely
+Python Web site, \url{http://www.python.org/}, and may be freely
distributed. The same site also contains distributions of and
pointers to many free third party Python modules, programs and tools,
and additional documentation.
@@ -84,7 +84,7 @@
Another situation: perhaps you have to work with several C libraries,
and the usual C write/compile/test/re-compile cycle is too slow. You
-need to develop software more quickly. Possibly perhaps you've
+need to develop software more quickly. Possibly you've
written a program that could use an extension language, and you don't
want to design a language, write and debug an interpreter for it, then
tie it into your application.
@@ -103,8 +103,8 @@
Python allows you to split up your program in modules that can be
reused in other Python programs. It comes with a large collection of
standard modules that you can use as the basis of your programs --- or
-as examples to start learning to program in Python. There are also
-built-in modules that provide things like file I/O, system calls,
+as examples to start learning to program in Python. Some of these
+modules provide things like file I/O, system calls,
sockets, and even interfaces to graphical user interface toolkits like Tk.
Python is an interpreted language, which can save you considerable time
@@ -145,7 +145,7 @@
Now that you are all excited about Python, you'll want to examine it
in some more detail. Since the best way to learn a language is
-using it, you are invited here to do so.
+using it, you are invited to do so with this tutorial.
In the next chapter, the mechanics of using the interpreter are
explained. This is rather mundane information, but essential for
@@ -603,7 +603,7 @@
print hello
\end{verbatim}
-Note that newlines would still need to be embedded in the string using
+Note that newlines still need to be embedded in the string using
\code{\e n}; the newline following the trailing backslash is
discarded. This example would print the following:
@@ -847,7 +847,7 @@
Starting with Python 2.0 a new data type for storing text data is
available to the programmer: the Unicode object. It can be used to
store and manipulate Unicode data (see \url{http://www.unicode.org/})
-and integrates well with the existing string objects providing
+and integrates well with the existing string objects, providing
auto-conversions where necessary.
Unicode has the advantage of providing one ordinal for every character
@@ -978,8 +978,8 @@
['eggs', 100]
>>> a[:2] + ['bacon', 2*2]
['spam', 'eggs', 'bacon', 4]
->>> 3*a[:3] + ['Boe!']
-['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boe!']
+>>> 3*a[:3] + ['Boo!']
+['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boo!']
\end{verbatim}
Unlike strings, which are \emph{immutable}, it is possible to change
@@ -1553,8 +1553,9 @@
\end{verbatim}
When a final formal parameter of the form \code{**\var{name}} is
-present, it receives a \ulink{dictionary}{../lib/typesmapping.html} containing all keyword arguments
-whose keyword doesn't correspond to a formal parameter. This may be
+present, it receives a \ulink{dictionary}{../lib/typesmapping.html}
+containing all keyword arguments except for those corresponding to
+a formal parameter. This may be
combined with a formal parameter of the form
\code{*\var{name}} (described in the next subsection) which receives a
tuple containing the positional arguments beyond the formal parameter
@@ -1883,8 +1884,8 @@
[0, 2, 4, 6, 8, 10, 12, 14]
\end{verbatim}
-\samp{reduce(\var{func}, \var{sequence})} returns a single value
-constructed by calling the binary function \var{func} on the first two
+\samp{reduce(\var{function}, \var{sequence})} returns a single value
+constructed by calling the binary function \var{function} on the first two
items of the sequence, then on the result and the next item, and so
on. For example, to compute the sum of the numbers 1 through 10:
@@ -2174,10 +2175,14 @@
\begin{verbatim}
>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
{'sape': 4139, 'jack': 4098, 'guido': 4127}
->>> dict([(x, x**2) for x in vec]) # use a list comprehension
+>>> dict([(x, x**2) for x in (2, 4, 6)]) # use a list comprehension
{2: 4, 4: 16, 6: 36}
\end{verbatim}
+Later in the tutorial, we will learn about Generator Expressions
+which are even better suited for the task of supplying key-values pairs to
+the \function{dict()} constructor.
+
\section{Looping Techniques \label{loopidioms}}
@@ -2635,7 +2640,7 @@
>>> import fibo, sys
>>> fib = fibo.fib
>>> dir()
-['__name__', 'a', 'fib', 'fibo', 'sys']
+['__builtins__', '__doc__', '__file__', '__name__', 'fib', 'fib2']
\end{verbatim}
Note that it lists all types of names: variables, modules, functions, etc.
@@ -2647,27 +2652,29 @@
\begin{verbatim}
>>> import __builtin__
>>> dir(__builtin__)
-['ArithmeticError', 'AssertionError', 'AttributeError',
- 'DeprecationWarning', 'EOFError', 'Ellipsis', 'EnvironmentError',
- 'Exception', 'False', 'FloatingPointError', 'IOError', 'ImportError',
+['ArithmeticError', 'AssertionError', 'AttributeError', 'DeprecationWarning',
+ 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
+ 'FloatingPointError', 'FutureWarning', 'IOError', 'ImportError',
'IndentationError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented',
'NotImplementedError', 'OSError', 'OverflowError', 'OverflowWarning',
- 'PendingDeprecationWarning', 'ReferenceError',
- 'RuntimeError', 'RuntimeWarning', 'StandardError', 'StopIteration',
- 'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError',
- 'True', 'TypeError', 'UnboundLocalError', 'UnicodeError', 'UserWarning',
- 'ValueError', 'Warning', 'ZeroDivisionError', '__debug__', '__doc__',
- '__import__', '__name__', 'abs', 'apply', 'bool', 'buffer',
- 'callable', 'chr', 'classmethod', 'cmp', 'coerce', 'compile', 'complex',
- 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod',
+ 'PendingDeprecationWarning', 'ReferenceError', 'RuntimeError',
+ 'RuntimeWarning', 'StandardError', 'StopIteration', 'SyntaxError',
+ 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'True',
+ 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError',
+ 'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError',
+ 'UserWarning', 'ValueError', 'Warning', 'WindowsError',
+ 'ZeroDivisionError', '_', '__debug__', '__doc__', '__import__',
+ '__name__', 'abs', 'apply', 'basestring', 'bool', 'buffer',
+ 'callable', 'chr', 'classmethod', 'cmp', 'coerce', 'compile',
+ 'complex', 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod',
'enumerate', 'eval', 'execfile', 'exit', 'file', 'filter', 'float',
- 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id',
- 'input', 'int', 'intern', 'isinstance', 'issubclass', 'iter',
+ 'frozenset', 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex',
+ 'id', 'input', 'int', 'intern', 'isinstance', 'issubclass', 'iter',
'len', 'license', 'list', 'locals', 'long', 'map', 'max', 'min',
- 'object', 'oct', 'open', 'ord', 'pow', 'property', 'quit',
- 'range', 'raw_input', 'reduce', 'reload', 'repr', 'round',
- 'setattr', 'slice', 'staticmethod', 'str', 'string', 'sum', 'super',
+ 'object', 'oct', 'open', 'ord', 'pow', 'property', 'quit', 'range',
+ 'raw_input', 'reduce', 'reload', 'repr', 'reversed', 'round', 'set',
+ 'setattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super',
'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange', 'zip']
\end{verbatim}
@@ -2824,8 +2831,8 @@
If \code{__all__} is not defined, the statement \code{from Sound.Effects
import *} does \emph{not} import all submodules from the package
\module{Sound.Effects} into the current namespace; it only ensures that the
-package \module{Sound.Effects} has been imported (possibly running its
-initialization code, \file{__init__.py}) and then imports whatever names are
+package \module{Sound.Effects} has been imported (possibly running any
+initialization code in \file{__init__.py}) and then imports whatever names are
defined in the package. This includes any names defined (and
submodules explicitly loaded) by \file{__init__.py}. It also includes any
submodules of the package that were explicitly loaded by previous
@@ -2907,7 +2914,7 @@
simply printing space-separated values. There are two ways to format
your output; the first way is to do all the string handling yourself;
using string slicing and concatenation operations you can create any
-lay-out you can imagine. The standard module
+layout you can imagine. The standard module
\module{string}\refstmodindex{string} contains some useful operations
for padding strings to a given column width; these will be discussed
shortly. The second way is to use the \code{\%} operator with a
@@ -3322,8 +3329,8 @@
Standard exception names are built-in identifiers (not reserved
keywords).
-The rest of the line is a detail whose interpretation depends on the
-exception type; its meaning is dependent on the exception type.
+The rest of the line provides detail based on the type of exception
+and what caused it.
The preceding part of the error message shows the context where the
exception happened, in the form of a stack backtrace.
@@ -3367,9 +3374,8 @@
\item
If an exception occurs during execution of the try clause, the rest of
the clause is skipped. Then if its type matches the exception named
-after the \keyword{except} keyword, the rest of the try clause is
-skipped, the except clause is executed, and then execution continues
-after the \keyword{try} statement.
+after the \keyword{except} keyword, the except clause is executed, and
+then execution continues after the \keyword{try} statement.
\item
If an exception occurs which does not match the exception named in the
@@ -3480,7 +3486,7 @@
... except ZeroDivisionError, detail:
... print 'Handling run-time error:', detail
...
-Handling run-time error: integer division or modulo
+Handling run-time error: integer division or modulo by zero
\end{verbatim}
@@ -3499,7 +3505,9 @@
The first argument to \keyword{raise} names the exception to be
raised. The optional second argument specifies the exception's
-argument.
+argument. Alternatively, the above could be written as
+\code{raise NameError('HiThere')}. Either form works fine, but there
+seems to be a growing stylistic preference for the latter.
If you need to determine whether an exception was raised but don't
intend to handle it, a simpler form of the \keyword{raise} statement
@@ -3545,10 +3553,14 @@
__main__.MyError: 'oops!'
\end{verbatim}
+In this example, the default \method{__init__} of \class{Exception} has
+been overriden. The new behavior simply creates the \var{value} attribute.
+This replaces the default behavior of creating the \var{args} attribute.
+
Exception classes can be defined which do anything any other class can
do, but are usually kept simple, often only offering a number of
attributes that allow information about the error to be extracted by
-handlers for the exception. When creating a module which can raise
+handlers for the exception. When creating a module that can raise
several distinct errors, a common practice is to create a base class
for exceptions defined by that module, and subclass that to create
specific exception classes for different error conditions:
@@ -3623,7 +3635,8 @@
whether or not the use of the resource was successful.
A \keyword{try} statement must either have one or more except clauses
-or one finally clause, but not both.
+or one finally clause, but not both (because it would be unclear which
+clause should be executed).
\chapter{Classes \label{classes}}
@@ -3825,7 +3838,7 @@
object} is created. This is basically a wrapper around the contents
of the namespace created by the class definition; we'll learn more
about class objects in the next section. The original local scope
-(the one in effect just before the class definitions was entered) is
+(the one in effect just before the class definitions were entered) is
reinstated, and the class object is bound here to the class name given
in the class definition header (\class{ClassName} in the example).
@@ -3907,9 +3920,9 @@
Now what can we do with instance objects? The only operations
understood by instance objects are attribute references. There are
-two kinds of valid attribute names.
+two kinds of valid attribute names, data attributes and methods.
-The first I'll call \emph{data attributes}. These correspond to
+\emph{data attributes} correspond to
``instance variables'' in Smalltalk, and to ``data members'' in
\Cpp. Data attributes need not be declared; like local variables,
they spring into existence when they are first assigned to. For
@@ -3925,16 +3938,16 @@
del x.counter
\end{verbatim}
-The second kind of attribute references understood by instance objects
-are \emph{methods}. A method is a function that ``belongs to'' an
+The other kind of instance attribute references is a \emph{method}.
+A method is a function that ``belongs to'' an
object. (In Python, the term method is not unique to class instances:
other object types can have methods as well. For example, list objects have
methods called append, insert, remove, sort, and so on. However,
-below, we'll use the term method exclusively to mean methods of class
-instance objects, unless explicitly stated otherwise.)
+in the following discussion, we'll use the term method exclusively to mean
+methods of class instance objects, unless explicitly stated otherwise.)
Valid method names of an instance object depend on its class. By
-definition, all attributes of a class that are (user-defined) function
+definition, all attributes of a class that are function
objects define corresponding methods of its instances. So in our
example, \code{x.f} is a valid method reference, since
\code{MyClass.f} is a function, but \code{x.i} is not, since
@@ -4029,12 +4042,12 @@
variables and instance variables when glancing through a method.
-Conventionally, the first argument of methods is often called
+Conventionally, the first argument of a method is often called
\code{self}. This is nothing more than a convention: the name
\code{self} has absolutely no special meaning to Python. (Note,
however, that by not following the convention your code may be less
-readable by other Python programmers, and it is also conceivable that
-a \emph{class browser} program be written which relies upon such a
+readable to other Python programmers, and it is also conceivable that
+a \emph{class browser} program might be written that relies upon such a
convention.)
@@ -4180,6 +4193,7 @@
variables'' or data attributes used by the common base class), it is
not clear that these semantics are in any way useful.
+%% XXX Add rules for new-style MRO?
\section{Private Variables \label{private}}
@@ -4188,9 +4202,9 @@
leading underscores, at most one trailing underscore) is textually
replaced with \code{_classname__spam}, where \code{classname} is the
current class name with leading underscore(s) stripped. This mangling
-is done without regard of the syntactic position of the identifier, so
+is done without regard to the syntactic position of the identifier, so
it can be used to define class-private instance and class variables,
-methods, as well as globals, and even to store instance variables
+methods, variables stored in globals, and even variables stored in instances.
private to this class on instances of \emph{other} classes. Truncation
may occur when the mangled name would be longer than 255 characters.
Outside classes, or when the class name consists of only underscores,
@@ -4219,7 +4233,7 @@
\section{Odds and Ends \label{odds}}
Sometimes it is useful to have a data type similar to the Pascal
-``record'' or C ``struct'', bundling together a couple of named data
+``record'' or C ``struct'', bundling together a few named data
items. An empty class definition will do nicely:
\begin{verbatim}
@@ -4238,7 +4252,7 @@
can often be passed a class that emulates the methods of that data
type instead. For instance, if you have a function that formats some
data from a file object, you can define a class with methods
-\method{read()} and \method{readline()} that gets the data from a string
+\method{read()} and \method{readline()} that get the data from a string
buffer instead, and pass it as an argument.% (Unfortunately, this
%technique has its limitations: a class can't define operations that
%are accessed by special syntax such as sequence subscripting or
@@ -4248,7 +4262,7 @@
Instance method objects have attributes, too: \code{m.im_self} is the
-object of which the method is an instance, and \code{m.im_func} is the
+instance object with the method \method{m}, and \code{m.im_func} is the
function object corresponding to the method.
@@ -4413,7 +4427,7 @@
Another key feature is that the local variables and execution state
are automatically saved between calls. This made the function easier to write
-and much more clear than an approach using class variables like
+and much more clear than an approach using instance variables like
\code{self.index} and \code{self.data}.
In addition to automatic method creation and saving program state, when
@@ -4517,7 +4531,7 @@
\section{Command Line Arguments\label{command-line-arguments}}
-Common utility scripts often invoke processing command line arguments.
+Common utility scripts often need to process command line arguments.
These arguments are stored in the
\ulink{\module{sys}}{../lib/module-sys.html}\ module's \var{argv}
attribute as a list. For instance the following output results from
@@ -4544,7 +4558,7 @@
messages to make them visible even when \var{stdout} has been redirected:
\begin{verbatim}
->>> sys.stderr.write('Warning, log file not found starting a new one')
+>>> sys.stderr.write('Warning, log file not found starting a new one\n')
Warning, log file not found starting a new one
\end{verbatim}
@@ -4623,7 +4637,7 @@
>>> import smtplib
>>> server = smtplib.SMTP('localhost')
>>> server.sendmail('soothsayer at example.org', 'jceasar at example.org',
-"""To: jceasar at example.org
+"""To: jcaesar at example.org
From: soothsayer at example.org
Beware the Ides of March.
@@ -4647,8 +4661,8 @@
>>> now = date.today()
>>> now
datetime.date(2003, 12, 2)
->>> now.strftime("%m-%d-%y or %d%b %Y is a %A on the %d day of %B")
-'12-02-03 or 02Dec 2003 is a Tuesday on the 02 day of December'
+>>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.")
+'12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'
# dates support calendar arithmetic
>>> birthday = date(1964, 7, 31)
@@ -4678,8 +4692,8 @@
37
>>> zlib.decompress(t)
'witch which has which witches wrist watch'
->>> zlib.crc32(t)
--1438085031
+>>> zlib.crc32(s)
+226805979
\end{verbatim}
@@ -5206,7 +5220,7 @@
\chapter{What Now? \label{whatNow}}
Reading this tutorial has probably reinforced your interest in using
-Python --- you should be eager to apply Python to solve your
+Python --- you should be eager to apply Python to solving your
real-world problems. Now what should you do?
You should read, or at least page through, the
@@ -5369,7 +5383,7 @@
this deletes the names it creates once they are no longer needed; this
is done since the startup file is executed in the same namespace as
the interactive commands, and removing the names avoids creating side
-effects in the interactive environments. You may find it convenient
+effects in the interactive environment. You may find it convenient
to keep some of the imported modules, such as
\ulink{\module{os}}{../lib/module-os.html}, which turn
out to be needed in most sessions with the interpreter.
@@ -5461,7 +5475,7 @@
and so on. No matter how many digits you're willing to write down, the
result will never be exactly 1/3, but will be an increasingly better
-approximation to 1/3.
+approximation of 1/3.
In the same way, no matter how many base 2 digits you're willing to
use, the decimal value 0.1 cannot be represented exactly as a base 2
@@ -5507,7 +5521,7 @@
\var{x}, but rounding to 16 digits is not enough to make that true.
Note that this is in the very nature of binary floating-point: this is
-not a bug in Python, it is not a bug in your code either, and you'll
+not a bug in Python, it is not a bug in your code either. You'll
see the same kind of thing in all languages that support your
hardware's floating-point arithmetic (although some languages may
not \emph{display} the difference by default, or in all output modes).
@@ -5621,7 +5635,7 @@
\code{< 2**53}), the best value for \var{N} is 56:
\begin{verbatim}
->>> 2L**52
+>>> 2**52
4503599627370496L
>>> 2L**53
9007199254740992L
More information about the Python-checkins
mailing list