[Python-checkins] python/dist/src/Doc/tut tut.tex, 1.196.8.13,
1.196.8.14
rhettinger at users.sourceforge.net
rhettinger at users.sourceforge.net
Sun Dec 7 06:15:21 EST 2003
Update of /cvsroot/python/python/dist/src/Doc/tut
In directory sc8-pr-cvs1:/tmp/cvs-serv15505
Modified Files:
Tag: release23-maint
tut.tex
Log Message:
Backport various tutorial fixups (with permission from the RM).
Index: tut.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/tut/tut.tex,v
retrieving revision 1.196.8.13
retrieving revision 1.196.8.14
diff -C2 -d -r1.196.8.13 -r1.196.8.14
*** tut.tex 5 Dec 2003 08:03:09 -0000 1.196.8.13
--- tut.tex 7 Dec 2003 11:15:16 -0000 1.196.8.14
***************
*** 3,9 ****
% Things to do:
- % Add a section on file I/O
- % Write a chapter entitled ``Some Useful Modules''
- % --re, math+cmath
% Should really move the Python startup file info to an appendix
--- 3,6 ----
***************
*** 332,348 ****
encoding. The list of possible encodings can be found in the
\citetitle[../lib/lib.html]{Python Library Reference}, in the section
! on \module{codecs}.
! If your editor supports saving files as \code{UTF-8} with an UTF-8
! signature (aka BOM -- Byte Order Mark), you can use that instead of an
encoding declaration. IDLE supports this capability if
\code{Options/General/Default Source Encoding/UTF-8} is set. Notice
that this signature is not understood in older Python releases (2.2
and earlier), and also not understood by the operating system for
! \code{\#!} files.
By using UTF-8 (either through the signature or an encoding
declaration), characters of most languages in the world can be used
! simultaneously in string literals and comments. Using non-ASCII
characters in identifiers is not supported. To display all these
characters properly, your editor must recognize that the file is
--- 329,345 ----
encoding. The list of possible encodings can be found in the
\citetitle[../lib/lib.html]{Python Library Reference}, in the section
! on \ulink{\module{codecs}}{../lib/module-codecs.html}.
! If your editor supports saving files as \code{UTF-8} with a UTF-8
! \emph{byte order mark} (aka BOM), you can use that instead of an
encoding declaration. IDLE supports this capability if
\code{Options/General/Default Source Encoding/UTF-8} is set. Notice
that this signature is not understood in older Python releases (2.2
and earlier), and also not understood by the operating system for
! \code{\#!} files.
By using UTF-8 (either through the signature or an encoding
declaration), characters of most languages in the world can be used
! simultaneously in string literals and comments. Using non-\ASCII
characters in identifiers is not supported. To display all these
characters properly, your editor must recognize that the file is
***************
*** 660,672 ****
\begin{verbatim}
- >>> import string
>>> 'str' 'ing' # <- This is ok
'string'
! >>> string.strip('str') + 'ing' # <- This is ok
'string'
! >>> string.strip('str') 'ing' # <- This is invalid
File "<stdin>", line 1, in ?
! string.strip('str') 'ing'
! ^
SyntaxError: invalid syntax
\end{verbatim}
--- 657,668 ----
\begin{verbatim}
>>> 'str' 'ing' # <- This is ok
'string'
! >>> 'str'.strip() + 'ing' # <- This is ok
'string'
! >>> 'str'.strip() 'ing' # <- This is invalid
File "<stdin>", line 1, in ?
! 'str'.strip() 'ing'
! ^
SyntaxError: invalid syntax
\end{verbatim}
***************
*** 810,813 ****
--- 806,824 ----
+ \begin{seealso}
+ \seetitle[../lib/typesseq.html]{Sequence Types}%
+ {Strings, and the Unicode strings described in the next
+ section, are examples of \emph{sequence types}, and
+ support the common operations supported by such types.}
+ \seetitle[../lib/string-methods.html]{String Methods}%
+ {Both strings and Unicode strings support a large number of
+ methods for basic transformations and searching.}
+ \seetitle[../lib/typesseq-strings.html]{String Formatting Operations}%
+ {The formatting operations invoked when strings and Unicode
+ strings are the left operand of the \code{\%} operator are
+ described in more detail here.}
+ \end{seealso}
+
+
\subsection{Unicode Strings \label{unicodeStrings}}
\sectionauthor{Marc-Andre Lemburg}{mal at lemburg.com}
***************
*** 882,886 ****
The latter two are variable-length encodings that store each Unicode
character in one or more bytes. The default encoding is
! normally set to ASCII, which passes through characters in the range
0 to 127 and rejects any other characters with an error.
When a Unicode string is printed, written to a file, or converted
--- 893,897 ----
The latter two are variable-length encodings that store each Unicode
character in one or more bytes. The default encoding is
! normally set to \ASCII, which passes through characters in the range
0 to 127 and rejects any other characters with an error.
When a Unicode string is printed, written to a file, or converted
***************
*** 1519,1523 ****
When a final formal parameter of the form \code{**\var{name}} is
! present, it receives a dictionary containing all keyword arguments
whose keyword doesn't correspond to a formal parameter. This may be
combined with a formal parameter of the form
--- 1530,1534 ----
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
combined with a formal parameter of the form
***************
*** 1839,1855 ****
many arguments as there are sequences and is called with the
corresponding item from each sequence (or \code{None} if some sequence
! is shorter than another). If \code{None} is passed for the function,
! a function returning its argument(s) is substituted.
!
! Combining these two special cases, we see that
! \samp{map(None, \var{list1}, \var{list2})} is a convenient way of
! turning a pair of lists into a list of pairs. For example:
\begin{verbatim}
>>> seq = range(8)
! >>> def square(x): return x*x
...
! >>> map(None, seq, map(square, seq))
! [(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25), (6, 36), (7, 49)]
\end{verbatim}
--- 1850,1861 ----
many arguments as there are sequences and is called with the
corresponding item from each sequence (or \code{None} if some sequence
! is shorter than another). For example:
\begin{verbatim}
>>> seq = range(8)
! >>> def add(x, y): return x+y
...
! >>> map(add, seq, seq)
! [0, 2, 4, 6, 8, 10, 12, 14]
\end{verbatim}
***************
*** 1974,1980 ****
We saw that lists and strings have many common properties, such as
indexing and slicing operations. They are two examples of
! \emph{sequence} data types. Since Python is an evolving language,
! other sequence data types may be added. There is also another
! standard sequence data type: the \emph{tuple}.
A tuple consists of a number of values separated by commas, for
--- 1980,1987 ----
We saw that lists and strings have many common properties, such as
indexing and slicing operations. They are two examples of
! \ulink{\emph{sequence} data types}{../lib/typesseq.html}. Since
! Python is an evolving language, other sequence data types may be
! added. There is also another standard sequence data type: the
! \emph{tuple}.
A tuple consists of a number of values separated by commas, for
***************
*** 2046,2050 ****
\section{Dictionaries \label{dictionaries}}
! Another useful data type built into Python is the \emph{dictionary}.
Dictionaries are sometimes found in other languages as ``associative
memories'' or ``associative arrays''. Unlike sequences, which are
--- 2053,2058 ----
\section{Dictionaries \label{dictionaries}}
! Another useful data type built into Python is the
! \ulink{\emph{dictionary}}{../lib/typesmapping.html}.
Dictionaries are sometimes found in other languages as ``associative
memories'' or ``associative arrays''. Unlike sequences, which are
***************
*** 2074,2082 ****
value using a non-existent key.
! The \code{keys()} method of a dictionary object returns a list of all
the keys used in the dictionary, in random order (if you want it
! sorted, just apply the \code{sort()} method to the list of keys). To
check whether a single key is in the dictionary, use the
! \code{has_key()} method of the dictionary.
Here is a small example using a dictionary:
--- 2082,2090 ----
value using a non-existent key.
! The \method{keys()} method of a dictionary object returns a list of all
the keys used in the dictionary, in random order (if you want it
! sorted, just apply the \method{sort()} method to the list of keys). To
check whether a single key is in the dictionary, use the
! \method{has_key()} method of the dictionary.
Here is a small example using a dictionary:
***************
*** 2152,2155 ****
--- 2160,2178 ----
\end{verbatim}
+ To loop over a sequence in reverse, first specify the sequence
+ in a forward direction and then call the \function{reversed()}
+ function.
+
+ \begin{verbatim}
+ >>> for i in reversed(xrange(1,10,2)):
+ ... print i
+ ...
+ 9
+ 7
+ 5
+ 3
+ 1
+ \end{verbatim}
+
\section{More on Conditions \label{conditions}}
***************
*** 2389,2393 ****
attempt to load the script as a module when that module is imported.
This will generally be an error. See section~\ref{standardModules},
! ``Standard Modules.'' for more information.
--- 2412,2416 ----
attempt to load the script as a module when that module is imported.
This will generally be an error. See section~\ref{standardModules},
! ``Standard Modules,'' for more information.
***************
*** 2455,2461 ****
\item
! The module \module{compileall}\refstmodindex{compileall} can create
! \file{.pyc} files (or \file{.pyo} files when \programopt{-O} is used) for
! all modules in a directory.
\end{itemize}
--- 2478,2485 ----
\item
! The module \ulink{\module{compileall}}{../lib/module-compileall.html}%
! {} \refstmodindex{compileall} can create \file{.pyc} files (or
! \file{.pyo} files when \programopt{-O} is used) for all modules in a
! directory.
\end{itemize}
***************
*** 2474,2478 ****
the \module{amoeba} module is only provided on systems that somehow
support Amoeba primitives. One particular module deserves some
! attention: \module{sys}\refstmodindex{sys}, which is built into every
Python interpreter. The variables \code{sys.ps1} and
\code{sys.ps2} define the strings used as primary and secondary
--- 2498,2503 ----
the \module{amoeba} module is only provided on systems that somehow
support Amoeba primitives. One particular module deserves some
! attention: \ulink{\module{sys}}{../lib/module-sys.html}%
! \refstmodindex{sys}, which is built into every
Python interpreter. The variables \code{sys.ps1} and
\code{sys.ps2} define the strings used as primary and secondary
***************
*** 2757,2768 ****
The submodules often need to refer to each other. For example, the
! \module{surround} module might use the \module{echo} module. In fact, such references
! are so common that the \code{import} statement first looks in the
containing package before looking in the standard module search path.
Thus, the surround module can simply use \code{import echo} or
\code{from echo import echofilter}. If the imported module is not
found in the current package (the package of which the current module
! is a submodule), the \code{import} statement looks for a top-level module
! with the given name.
When packages are structured into subpackages (as with the
--- 2782,2794 ----
The submodules often need to refer to each other. For example, the
! \module{surround} module might use the \module{echo} module. In fact,
! such references
! are so common that the \keyword{import} statement first looks in the
containing package before looking in the standard module search path.
Thus, the surround module can simply use \code{import echo} or
\code{from echo import echofilter}. If the imported module is not
found in the current package (the package of which the current module
! is a submodule), the \keyword{import} statement looks for a top-level
! module with the given name.
When packages are structured into subpackages (as with the
***************
*** 2774,2786 ****
Sound.Effects import echo}.
- %(One could design a notation to refer to parent packages, similar to
- %the use of ".." to refer to the parent directory in \UNIX{} and Windows
- %filesystems. In fact, the \module{ni} module, which was the
- %ancestor of this package system, supported this using \code{__} for
- %the package containing the current module,
- %\code{__.__} for the parent package, and so on. This feature was dropped
- %because of its awkwardness; since most packages will have a relative
- %shallow substructure, this is no big loss.)
-
\subsection{Packages in Multiple Directories}
--- 2800,2803 ----
***************
*** 2874,2882 ****
\begin{verbatim}
- >>> import string
>>> for x in range(1, 11):
! ... print string.rjust(repr(x), 2), string.rjust(repr(x*x), 3),
... # Note trailing comma on previous line
! ... print string.rjust(repr(x*x*x), 4)
...
1 1 1
--- 2891,2898 ----
\begin{verbatim}
>>> for x in range(1, 11):
! ... print repr(x).rjust(2), repr(x*x).rjust(3),
... # Note trailing comma on previous line
! ... print repr(x*x*x).rjust(4)
...
1 1 1
***************
*** 2908,2933 ****
\keyword{print} works: it always adds spaces between its arguments.)
! This example demonstrates the function \function{string.rjust()},
which right-justifies a string in a field of a given width by padding
! it with spaces on the left. There are similar functions
! \function{string.ljust()} and \function{string.center()}. These
! functions do not write anything, they just return a new string. If
the input string is too long, they don't truncate it, but return it
unchanged; this will mess up your column lay-out but that's usually
better than the alternative, which would be lying about a value. (If
you really want truncation you can always add a slice operation, as in
! \samp{string.ljust(x,~n)[0:n]}.)
! There is another function, \function{string.zfill()}, which pads a
numeric string on the left with zeros. It understands about plus and
minus signs:
\begin{verbatim}
! >>> import string
! >>> string.zfill('12', 5)
'00012'
! >>> string.zfill('-3.14', 7)
'-003.14'
! >>> string.zfill('3.14159265359', 5)
'3.14159265359'
\end{verbatim}
--- 2924,2948 ----
\keyword{print} works: it always adds spaces between its arguments.)
! This example demonstrates the \method{rjust()} method of string objects,
which right-justifies a string in a field of a given width by padding
! it with spaces on the left. There are similar methods
! \method{ljust()} and \method{center()}. These
! methods do not write anything, they just return a new string. If
the input string is too long, they don't truncate it, but return it
unchanged; this will mess up your column lay-out but that's usually
better than the alternative, which would be lying about a value. (If
you really want truncation you can always add a slice operation, as in
! \samp{x.ljust(~n)[:n]}.)
! There is another method, \method{zfill()}, which pads a
numeric string on the left with zeros. It understands about plus and
minus signs:
\begin{verbatim}
! >>> '12'.zfill(5)
'00012'
! >>> '-3.14'.zfill(7)
'-003.14'
! >>> '3.14159265359'.zfill(5)
'3.14159265359'
\end{verbatim}
***************
*** 3112,3116 ****
bit more effort, since the \method{read()} method only returns
strings, which will have to be passed to a function like
! \function{string.atoi()}, which takes a string like \code{'123'} and
returns its numeric value 123. However, when you want to save more
complex data types like lists, dictionaries, or class instances,
--- 3127,3131 ----
bit more effort, since the \method{read()} method only returns
strings, which will have to be passed to a function like
! \function{int()}, which takes a string like \code{'123'} and
returns its numeric value 123. However, when you want to save more
complex data types like lists, dictionaries, or class instances,
***************
*** 3119,3123 ****
Rather than have users be constantly writing and debugging code to
save complicated data types, Python provides a standard module called
! \module{pickle}. This is an amazing module that can take almost
any Python object (even some forms of Python code!), and convert it to
a string representation; this process is called \dfn{pickling}.
--- 3134,3139 ----
Rather than have users be constantly writing and debugging code to
save complicated data types, Python provides a standard module called
! \ulink{\module{pickle}}{../lib/module-pickle.html}. This is an
! amazing module that can take almost
any Python object (even some forms of Python code!), and convert it to
a string representation; this process is called \dfn{pickling}.
***************
*** 3144,3153 ****
(There are other variants of this, used when pickling many objects or
when you don't want to write the pickled data to a file; consult the
! complete documentation for \module{pickle} in the Library Reference.)
! \module{pickle} is the standard way to make Python objects which can
! be stored and reused by other programs or by a future invocation of
! the same program; the technical term for this is a
! \dfn{persistent} object. Because \module{pickle} is so widely used,
many authors who write Python extensions take care to ensure that new
data types such as matrices can be properly pickled and unpickled.
--- 3160,3172 ----
(There are other variants of this, used when pickling many objects or
when you don't want to write the pickled data to a file; consult the
! complete documentation for
! \ulink{\module{pickle}}{../lib/module-pickle.html} in the
! \citetitle[../lib/]{Python Library Reference}.)
! \ulink{\module{pickle}}{../lib/module-pickle.html} is the standard way
! to make Python objects which can be stored and reused by other
! programs or by a future invocation of the same program; the technical
! term for this is a \dfn{persistent} object. Because
! \ulink{\module{pickle}}{../lib/module-pickle.html} is so widely used,
many authors who write Python extensions take care to ensure that new
data types such as matrices can be properly pickled and unpickled.
***************
*** 3295,3304 ****
\begin{verbatim}
! import string, sys
try:
f = open('myfile.txt')
s = f.readline()
! i = int(string.strip(s))
except IOError, (errno, strerror):
print "I/O error(%s): %s" % (errno, strerror)
--- 3314,3323 ----
\begin{verbatim}
! import sys
try:
f = open('myfile.txt')
s = f.readline()
! i = int(s.strip())
except IOError, (errno, strerror):
print "I/O error(%s): %s" % (errno, strerror)
***************
*** 4339,4343 ****
\begin{verbatim}
>>> import os
! >>> os.system('copy /data/mydata.fil /backup/mydata.fil')
0
>>> os.getcwd() # Return the current working directory
--- 4358,4362 ----
\begin{verbatim}
>>> import os
! >>> os.system('time 0:02')
0
>>> os.getcwd() # Return the current working directory
***************
*** 4426,4432 ****
The \ulink{\module{re}}{../lib/module-re.html}
module provides regular expression tools for advanced string processing.
! When only simple capabilities are needed, string methods are preferred
! because they are easier to read and debug. However, for more
! sophisticated applications, regular expressions can provide succinct,
optimized solutions:
--- 4445,4449 ----
The \ulink{\module{re}}{../lib/module-re.html}
module provides regular expression tools for advanced string processing.
! For complex matching and manipulation, regular expressions offer succinct,
optimized solutions:
***************
*** 4439,4442 ****
--- 4456,4466 ----
\end{verbatim}
+ When only simple capabilities are needed, string methods are preferred
+ because they are easier to read and debug:
+
+ \begin{verbatim}
+ >>> 'tea for too'.replace('too', 'two')
+ 'tea for two'
+ \end{verbatim}
\section{Mathematics\label{mathematics}}
***************
*** 4677,4682 ****
bunch of Python-related personal home pages; many people have
downloadable software there. Many more user-created Python modules
! can be found in a third-party repository at
! \url{http://www.vex.net/parnassus}.
For Python-related questions and problem reports, you can post to the
--- 4701,4706 ----
bunch of Python-related personal home pages; many people have
downloadable software there. Many more user-created Python modules
! can be found in the \ulink{Python Package
! Index}{http://www.python.org/pypi} (PyPI).
For Python-related questions and problem reports, you can post to the
***************
*** 4691,4696 ****
asking (and answering) questions, suggesting new features, and
announcing new modules. Before posting, be sure to check the list of
! Frequently Asked Questions (also called the FAQ), at
! \url{http://www.python.org/doc/FAQ.html}, or look for it in the
\file{Misc/} directory of the Python source distribution. Mailing
list archives are available at \url{http://www.python.org/pipermail/}.
--- 4715,4719 ----
asking (and answering) questions, suggesting new features, and
announcing new modules. Before posting, be sure to check the list of
! \ulink{Frequently Asked Questions}{http://www.python.org/doc/faq/} (also called the FAQ), or look for it in the
\file{Misc/} directory of the Python source distribution. Mailing
list archives are available at \url{http://www.python.org/pipermail/}.
***************
*** 4790,4794 ****
in your \file{\~{}/.inputrc}. (Of course, this makes it harder to
! type indented continuation lines.)
Automatic completion of variable and module names is optionally
--- 4813,4818 ----
in your \file{\~{}/.inputrc}. (Of course, this makes it harder to
! type indented continuation lines if you're accustomed to using
! \kbd{Tab} for that purpose.)
Automatic completion of variable and module names is optionally
***************
*** 4819,4823 ****
the interactive commands, and removing the names avoids creating side
effects in the interactive environments. You may find it convenient
! to keep some of the imported modules, such as \module{os}, which turn
out to be needed in most sessions with the interpreter.
--- 4843,4848 ----
the interactive commands, and removing the names avoids creating side
effects in the interactive environments. 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.
More information about the Python-checkins
mailing list