Commit 6d3dfc3f authored by Alexandre Vassalotti's avatar Alexandre Vassalotti

Merged revisions...

Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line

  #6513: fix example code: warning categories are classes, not instances.
........
  r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line

  #6489: fix an ambiguity in getiterator() documentation.
........
  r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line

  remove docs for deprecated -p option
........
  r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line

  use bools
........
  r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line

  Fix arg types of et#.
........
  r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line

  Dont put "void" in signature for nullary functions.
........
  r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line

  #6571: add index entries for more operators.
........
  r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line

  #6593: fix link targets.
........
  r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line

  #6591: add reference to ioctl in fcntl module for platforms other than Windows.
........
  r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line

  Add a link to readline, and mention IPython and bpython.
........
  r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line

  Fix some markup and small factual glitches found by M. Markert.
........
  r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line

  Fix a few markup glitches.
........
  r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line

  Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better.
........
parent fc230e8c
......@@ -160,7 +160,7 @@ variable(s) whose address should be passed.
In both cases, *\*buffer_length* is set to the length of the encoded data
without the trailing NUL byte.
``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
Same as ``es#`` except that string objects are passed through without recoding
them. Instead, the implementation assumes that the string object uses the
encoding passed in as parameter.
......
......@@ -64,16 +64,16 @@ Floating Point Objects
around the header file :file:`float.h`.
.. cfunction:: double PyFloat_GetMax(void)
.. cfunction:: double PyFloat_GetMax()
Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`.
.. cfunction:: double PyFloat_GetMin(void)
.. cfunction:: double PyFloat_GetMin()
Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`.
.. cfunction:: int PyFloat_ClearFreeList(void)
.. cfunction:: int PyFloat_ClearFreeList()
Clear the float free list. Return the number of items that could not
be freed.
......@@ -94,7 +94,7 @@ no longer available.
Macro version of :cfunc:`PyMethod_Self` which avoids error checking.
.. cfunction:: int PyMethod_ClearFreeList(void)
.. cfunction:: int PyMethod_ClearFreeList()
Clear the free list. Return the total number of freed items.
......@@ -73,7 +73,7 @@ accessible to C code. They all work with the current interpreter thread's
case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
on error.
.. cfunction:: void PySys_ResetWarnOptions(void)
.. cfunction:: void PySys_ResetWarnOptions()
Reset :data:`sys.warnoptions` to an empty list.
......
......@@ -107,6 +107,6 @@ Tuple Objects
raises :exc:`MemoryError` or :exc:`SystemError`.
.. cfunction:: int PyTuple_ClearFreeList(void)
.. cfunction:: int PyTuple_ClearFreeList()
Clear the free list. Return the total number of freed items.
......@@ -33,7 +33,7 @@ Type Objects
standard type object. Return false in all other cases.
.. cfunction:: unsigned int PyType_ClearCache(void)
.. cfunction:: unsigned int PyType_ClearCache()
Clear the internal lookup cache. Return the current version tag.
......
......@@ -84,10 +84,11 @@ access internal read-only data of Unicode objects:
:ctype:`PyUnicodeObject` (not checked).
.. cfunction:: int PyUnicode_ClearFreeList(void)
.. cfunction:: int PyUnicode_ClearFreeList()
Clear the free list. Return the total number of freed items.
Unicode provides many different character properties. The most often needed ones
are available through these macros which are mapped to C functions depending on
the Python configuration.
......
......@@ -86,13 +86,6 @@ document could also be refactored with this option.
The :option:`-v` option enables output of more information on the translation
process.
When the :option:`-p` is passed, the :2to3fixer:`print` fixer ``print`` as a
function instead of a statement. This is useful when ``from __future__ import
print_function`` is being used. If this option is not given, the print fixer
will surround print calls in an extra set of parentheses because it cannot
differentiate between the print statement with parentheses (such as ``print
("a" + "b" + "c")``) and a true function call.
.. _2to3-fixers:
......
......@@ -194,7 +194,7 @@ class can also install themselves in the built-in namespace as the function
:func:`translation`.
For the *names* parameter, please see the description of the translation
object's :meth:`install` method.
object's :meth:`~NullTranslations.install` method.
As seen below, you usually mark the strings in your application that are
candidates for translation, by wrapping them in a call to the :func:`_`
......
......@@ -555,6 +555,8 @@ correspond to Unix system calls applicable to sockets.
The :meth:`ioctl` method is a limited interface to the WSAIoctl system
interface. Please refer to the MSDN documentation for more information.
On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl`
functions may be used; they accept a socket object as their first argument.
.. method:: socket.listen(backlog)
......
......@@ -120,25 +120,24 @@ Notes:
Comparisons
===========
.. index:: pair: chaining; comparisons
There are eight comparison operations in Python. They all have the same
priority (which is higher than that of the Boolean operations). Comparisons can
be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and
y <= z``, except that *y* is evaluated only once (but in both cases *z* is not
evaluated at all when ``x < y`` is found to be false).
.. index::
pair: chaining; comparisons
pair: operator; comparison
operator: ==
operator: <
operator: >
operator: <=
operator: >
operator: >=
operator: !=
operator: is
operator: is not
There are eight comparison operations in Python. They all have the same
priority (which is higher than that of the Boolean operations). Comparisons can
be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and
y <= z``, except that *y* is evaluated only once (but in both cases *z* is not
evaluated at all when ``x < y`` is found to be false).
This table summarizes the comparison operations:
+------------+-------------------------+
......@@ -248,6 +247,13 @@ and imaginary parts.
builtin: int
builtin: float
builtin: complex
operator: +
operator: -
operator: *
operator: /
operator: //
operator: %
operator: **
Python fully supports mixed arithmetic: when a binary arithmetic operator has
operands of different numeric types, the operand with the "narrower" type is
......@@ -368,7 +374,15 @@ modules.
Bit-string Operations on Integer Types
--------------------------------------
.. _bit-string-operations:
.. index::
triple: operations on; integer; types
pair: bit-string; operations
pair: shifting; operations
pair: masking; operations
operator: ^
operator: &
operator: <<
operator: >>
Integers support additional operations that make sense only for bit-strings.
Negative numbers are treated as their 2's complement value (this assumes a
......@@ -400,12 +414,6 @@ This table lists the bit-string operations sorted in ascending priority
| ``~x`` | the bits of *x* inverted | |
+------------+--------------------------------+----------+
.. index::
triple: operations on; integer; types
pair: bit-string; operations
pair: shifting; operations
pair: masking; operations
Notes:
(1)
......
......@@ -206,7 +206,7 @@ check::
fxn()
# Verify some things
assert len(w) == 1
assert isinstance(w[-1].category, DeprecationWarning)
assert issubclass(w[-1].category, DeprecationWarning)
assert "deprecated" in str(w[-1].message)
One can also cause all warnings to be exceptions by using ``error`` instead of
......
......@@ -46,14 +46,14 @@ The following exception is defined:
The following functions are defined:
.. function:: open(url[, new=0[, autoraise=1]])
.. function:: open(url[, new=0[, autoraise=True]])
Display *url* using the default browser. If *new* is 0, the *url* is opened in
the same browser window if possible. If *new* is 1, a new browser window is
opened if possible. If *new* is 2, a new browser page ("tab") is opened if
possible. If *autoraise* is true, the window is raised if possible (note that
under many window managers this will occur regardless of the setting of this
variable).
Display *url* using the default browser. If *new* is 0, the *url* is opened
in the same browser window if possible. If *new* is 1, a new browser window
is opened if possible. If *new* is 2, a new browser page ("tab") is opened
if possible. If *autoraise* is ``True``, the window is raised if possible
(note that under many window managers this will occur regardless of the
setting of this variable).
Note that on some platforms, trying to open a filename using this function,
may work and start the operating system's associated program. However, this
......@@ -175,7 +175,7 @@ Browser controllers provide these methods which parallel three of the
module-level convenience functions:
.. method:: controller.open(url[, new[, autoraise=1]])
.. method:: controller.open(url[, new[, autoraise=True]])
Display *url* using the browser handled by this controller. If *new* is 1, a new
browser window is opened if possible. If *new* is 2, a new browser page ("tab")
......
......@@ -262,9 +262,9 @@ The following methods work on the element's children (subelements).
.. method:: Element.getiterator([tag=None])
Creates a tree iterator with the current element as the root. The iterator
iterates over this element and all elements below it that match the given tag.
If tag is ``None`` or ``'*'`` then all elements are iterated over. Returns an
iterable that provides element objects in document (depth first) order.
iterates over this element and all elements below it, in document (depth first)
order. If *tag* is not ``None`` or ``'*'``, only elements whose tag equals
*tag* are returned from the iterator.
.. method:: Element.insert(index, element)
......
......@@ -12,44 +12,41 @@ user not to "break into the definition." The most important features of classes
are retained with full power, however: the class inheritance mechanism allows
multiple base classes, a derived class can override any methods of its base
class or classes, and a method can call the method of a base class with the same
name. Objects can contain an arbitrary amount of private data.
name. Objects can contain an arbitrary amount of data.
In C++ terminology, normally class members (including the data members) are
*public* (except see below :ref:`tut-private`),
and all member functions are *virtual*. There are no special constructors or
destructors. As in Modula-3, there are no shorthands for referencing the
object's members from its methods: the method function is declared with an
explicit first argument representing the object, which is provided implicitly by
the call. As in Smalltalk, classes themselves are objects, albeit in the wider
sense of the word: in Python, all data types are objects. This provides
semantics for importing and renaming. Unlike C++ and Modula-3, built-in types
can be used as base classes for extension by the user. Also, like in C++ but
unlike in Modula-3, most built-in operators with special syntax (arithmetic
and all member functions are *virtual*. As in Modula-3, there are no shorthands
for referencing the object's members from its methods: the method function is
declared with an explicit first argument representing the object, which is
provided implicitly by the call. As in Smalltalk, classes themselves are
objects. This provides semantics for importing and renaming. Unlike C++ and
Modula-3, built-in types can be used as base classes for extension by the user.
Also, like in C++, most built-in operators with special syntax (arithmetic
operators, subscripting etc.) can be redefined for class instances.
(Lacking universally accepted terminology to talk about classes, I will make
occasional use of Smalltalk and C++ terms. I would use Modula-3 terms, since
its object-oriented semantics are closer to those of Python than C++, but I
expect that few readers have heard of it.)
.. _tut-terminology:
A Word About Terminology
========================
.. _tut-object:
Lacking universally accepted terminology to talk about classes, I will make
occasional use of Smalltalk and C++ terms. (I would use Modula-3 terms, since
its object-oriented semantics are closer to those of Python than C++, but I
expect that few readers have heard of it.)
A Word About Names and Objects
==============================
Objects have individuality, and multiple names (in multiple scopes) can be bound
to the same object. This is known as aliasing in other languages. This is
usually not appreciated on a first glance at Python, and can be safely ignored
when dealing with immutable basic types (numbers, strings, tuples). However,
aliasing has an (intended!) effect on the semantics of Python code involving
mutable objects such as lists, dictionaries, and most types representing
entities outside the program (files, windows, etc.). This is usually used to
the benefit of the program, since aliases behave like pointers in some respects.
For example, passing an object is cheap since only a pointer is passed by the
implementation; and if a function modifies an object passed as an argument, the
caller will see the change --- this eliminates the need for two different
argument passing mechanisms as in Pascal.
aliasing has a possibly surprising effect on the semantics of Python code
involving mutable objects such as lists, dictionaries, and most other types.
This is usually used to the benefit of the program, since aliases behave like
pointers in some respects. For example, passing an object is cheap since only a
pointer is passed by the implementation; and if a function modifies an object
passed as an argument, the caller will see the change --- this eliminates the
need for two different argument passing mechanisms as in Pascal.
.. _tut-scopes:
......@@ -73,7 +70,7 @@ built-in exception names); the global names in a module; and the local names in
a function invocation. In a sense the set of attributes of an object also form
a namespace. The important thing to know about namespaces is that there is
absolutely no relation between names in different namespaces; for instance, two
different modules may both define a function "maximize" without confusion ---
different modules may both define a function ``maximize`` without confusion ---
users of the modules must prefix it with the module name.
By the way, I use the word *attribute* for any name following a dot --- for
......@@ -112,11 +109,13 @@ name attempts to find the name in the namespace.
Although scopes are determined statically, they are used dynamically. At any
time during execution, there are at least three nested scopes whose namespaces
are directly accessible: the innermost scope, which is searched first, contains
the local names; the namespaces of any enclosing functions, which are searched
starting with the nearest enclosing scope; the middle scope, searched next,
contains the current module's global names; and the outermost scope (searched
last) is the namespace containing built-in names.
are directly accessible:
* the innermost scope, which is searched first, contains the local names
* the scopes of any enclosing functions, which are searched starting with the
nearest enclosing scope, contains non-local, but also non-global names
* the next-to-last scope contains the current module's global names
* the outermost scope (searched last) is the namespace containing built-in names
If a name is declared global, then all references and assignments go directly to
the middle scope containing the module's global names. To rebind variables
......@@ -138,15 +137,15 @@ language definition is evolving towards static name resolution, at "compile"
time, so don't rely on dynamic name resolution! (In fact, local variables are
already determined statically.)
A special quirk of Python is that -- if no :keyword:`global` or
:keyword:`nonlocal` statement is in effect -- assignments to names always go
into the innermost scope. Assignments do not copy data --- they just bind names
to objects. The same is true for deletions: the statement ``del x`` removes the
binding of ``x`` from the namespace referenced by the local scope. In fact, all
operations that introduce new names use the local scope: in particular, import
statements and function definitions bind the module or function name in the
local scope. (The :keyword:`global` statement can be used to indicate that
particular variables live in the global scope.)
A special quirk of Python is that -- if no :keyword:`global` statement is in
effect -- assignments to names always go into the innermost scope. Assignments
do not copy data --- they just bind names to objects. The same is true for
deletions: the statement ``del x`` removes the binding of ``x`` from the
namespace referenced by the local scope. In fact, all operations that introduce
new names use the local scope: in particular, :keyword:`import` statements and
function definitions bind the module or function name in the local scope. (The
:keyword:`global` statement can be used to indicate that particular variables
live in the global scope.)
The :keyword:`global` statement can be used to indicate that particular
variables live in the global scope and should be rebound there; the
......@@ -424,9 +423,9 @@ glancing through a method.
Often, the first argument of a method is called ``self``. This is nothing more
than a convention: the name ``self`` has absolutely no special meaning to
Python. (Note, however, that by not following the convention your code may be
Python. Note, however, that by not following the convention your code may be
less readable to other Python programmers, and it is also conceivable that a
*class browser* program might be written that relies upon such a convention.)
*class browser* program might be written that relies upon such a convention.
Any function object that is a class attribute defines a method for instances of
that class. It is not necessary that the function definition is textually
......@@ -462,13 +461,13 @@ argument::
Methods may reference global names in the same way as ordinary functions. The
global scope associated with a method is the module containing the class
definition. (The class itself is never used as a global scope!) While one
definition. (The class itself is never used as a global scope.) While one
rarely encounters a good reason for using global data in a method, there are
many legitimate uses of the global scope: for one thing, functions and modules
imported into the global scope can be used by methods, as well as functions and
classes defined in it. Usually, the class containing the method is itself
defined in this global scope, and in the next section we'll find some good
reasons why a method would want to reference its own class!
reasons why a method would want to reference its own class.
Each value is an object, and therefore has a *class* (also called its *type*).
It is stored as ``object.__class__``.
......@@ -519,12 +518,12 @@ An overriding method in a derived class may in fact want to extend rather than
simply replace the base class method of the same name. There is a simple way to
call the base class method directly: just call ``BaseClassName.methodname(self,
arguments)``. This is occasionally useful to clients as well. (Note that this
only works if the base class is defined or imported directly in the global
only works if the base class is accessible as ``BaseClassName`` in the global
scope.)
Python has two built-in functions that work with inheritance:
* Use :func:`isinstance` to check an object's type: ``isinstance(obj, int)``
* Use :func:`isinstance` to check an instance's type: ``isinstance(obj, int)``
will be ``True`` only if ``obj.__class__`` is :class:`int` or some class
derived from :class:`int`.
......@@ -582,28 +581,30 @@ http://www.python.org/download/releases/2.3/mro/.
Private Variables
=================
There is limited support for class-private identifiers. Any identifier of the
form ``__spam`` (at least two leading underscores, at most one trailing
underscore) is textually replaced with ``_classname__spam``, where ``classname``
is the current class name with leading underscore(s) stripped. This mangling 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, variables
stored in globals, and even variables stored in instances. private to this class
on instances of *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, no mangling occurs.
Name mangling is intended to give classes an easy way to define "private"
instance variables and methods, without having to worry about instance variables
defined by derived classes, or mucking with instance variables by code outside
the class. Note that the mangling rules are designed mostly to avoid accidents;
it still is possible for a determined soul to access or modify a variable that
is considered private. This can even be useful in special circumstances, such
as in the debugger, and that's one reason why this loophole is not closed.
(Buglet: derivation of a class with the same name as the base class makes use of
private variables of the base class possible.)
Notice that code passed to ``exec()`` or ``eval()`` does not
"Private" instance variables that cannot be accessed except from inside an
object, don't exist in Python. However, there is a convention that is followed
by most Python code: a name prefixed with an underscore (e.g. ``_spam``) should
be treated as a non-public part of the API (whether it is a function, a method
or a data member). It should be considered an implementation detail and subject
to change without notice.
Since there is a valid use-case for class-private members (namely to avoid name
clashes of names with names defined by subclasses), there is limited support for
such a mechanism, called :dfn:`name mangling`. Any identifier of the form
``__spam`` (at least two leading underscores, at most one trailing underscore)
is textually replaced with ``_classname__spam``, where ``classname`` is the
current class name with leading underscore(s) stripped. This mangling 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, variables stored in
globals, and even variables stored in instances. Truncation may occur when the
mangled name would be longer than 255 characters. Outside classes, or when the
class name consists of only underscores, no mangling occurs.
Note that the mangling rules are designed mostly to avoid accidents; it still is
possible to access or modify a variable that is considered private. This can
even be useful in special circumstances, such as in the debugger.
Notice that code passed to ``exec()``, ``eval()`` or ``execfile()`` does not
consider the classname of the invoking class to be the current class; this is
similar to the effect of the ``global`` statement, the effect of which is
likewise restricted to code that is byte-compiled together. The same
......@@ -654,7 +655,7 @@ Exceptions Are Classes Too
User-defined exceptions are identified by classes as well. Using this mechanism
it is possible to create extensible hierarchies of exceptions.
There are two valid (semantic) forms for the raise statement::
There are two new valid (semantic) forms for the :keyword:`raise` statement::
raise Class
......@@ -665,10 +666,10 @@ class derived from it. The first form is a shorthand for::
raise Class()
A class in an except clause is compatible with an exception if it is the same
class or a base class thereof (but not the other way around --- an except clause
listing a derived class is not compatible with a base class). For example, the
following code will print B, C, D in that order::
A class in an :keyword:`except` clause is compatible with an exception if it is
the same class or a base class thereof (but not the other way around --- an
except clause listing a derived class is not compatible with a base class). For
example, the following code will print B, C, D in that order::
class B(Exception):
pass
......
......@@ -130,16 +130,17 @@ Basic usage of the :meth:`str.format` method looks like this::
We are the knights who say "Ni!"
The brackets and characters within them (called format fields) are replaced with
the objects passed into the format method. The number in the brackets refers to
the position of the object passed into the format method. ::
the objects passed into the :meth:`~str.format` method. The number in the
brackets refers to the position of the object passed into the
:meth:`~str.format` method. ::
>>> print('{0} and {1}'.format('spam', 'eggs'))
spam and eggs
>>> print('{1} and {0}'.format('spam', 'eggs'))
eggs and spam
If keyword arguments are used in the format method, their values are referred to
by using the name of the argument. ::
If keyword arguments are used in the :meth:`~str.format` method, their values
are referred to by using the name of the argument. ::
>>> print('This {food} is {adjective}.'.format(
... food='spam', adjective='absolutely horrible'))
......@@ -160,7 +161,7 @@ truncates the Pi to three places after the decimal.
The value of PI is approximately 3.142.
Passing an integer after the ``':'`` will cause that field to be a minimum
number of characters wide. This is useful for making tables pretty.::
number of characters wide. This is useful for making tables pretty. ::
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
>>> for name, phone in table.items():
......@@ -181,7 +182,7 @@ square brackets ``'[]'`` to access the keys ::
Jack: 4098; Sjoerd: 4127; Dcab: 8637678
This could also be done by passing the table as keyword arguments with the '**'
notation.::
notation. ::
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
>>> print('Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab: {Dcab:d}'.format(**table))
......@@ -374,9 +375,9 @@ shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
>>> f.closed
True
File objects have some additional methods, such as :meth:`isatty` and
:meth:`truncate` which are less frequently used; consult the Library Reference
for a complete guide to file objects.
File objects have some additional methods, such as :meth:`~file.isatty` and
:meth:`~file.truncate` which are less frequently used; consult the Library
Reference for a complete guide to file objects.
.. _tut-pickle:
......
......@@ -6,8 +6,8 @@ Interactive Input Editing and History Substitution
Some versions of the Python interpreter support editing of the current input
line and history substitution, similar to facilities found in the Korn shell and
the GNU Bash shell. This is implemented using the *GNU Readline* library, which
supports Emacs-style and vi-style editing. This library has its own
the GNU Bash shell. This is implemented using the `GNU Readline`_ library,
which supports Emacs-style and vi-style editing. This library has its own
documentation which I won't duplicate here; however, the basics are easily
explained. The interactive editing and history described here are optionally
available in the Unix and Cygwin versions of the interpreter.
......@@ -148,8 +148,8 @@ interpreter. ::
.. _tut-commentary:
Commentary
==========
Alternatives to the Interactive Interpreter
===========================================
This facility is an enormous step forward compared to earlier versions of the
interpreter; however, some wishes are left: It would be nice if the proper
......@@ -158,8 +158,12 @@ token is required next). The completion mechanism might use the interpreter's
symbol table. A command to check (or even suggest) matching parentheses,
quotes, etc., would also be useful.
.. %
Do we mention IPython? DUBOIS
One alternative enhanced interactive interpreter that has been around for quite
some time is `IPython`_, which features tab completion, object exploration and
advanced history management. It can also be thoroughly customized and embedded
into other applications. Another similar enhanced interactive environment is
`bpython`_.
.. rubric:: Footnotes
......@@ -167,3 +171,7 @@ quotes, etc., would also be useful.
:envvar:`PYTHONSTARTUP` environment variable when you start an interactive
interpreter.
.. _GNU Readline: http://tiswww.case.edu/php/chet/readline/rltop.html
.. _IPython: http://ipython.scipy.org/
.. _bpython: http://www.bpython-interpreter.org/
......@@ -448,14 +448,14 @@ one would hope that this somehow goes out to the filesystem, finds which
submodules are present in the package, and imports them all. Unfortunately,
this operation does not work very well on Windows platforms, where the
filesystem does not always have accurate information about the case of a
filename! On these platforms, there is no guaranteed way to know whether a file
filename. On these platforms, there is no guaranteed way to know whether a file
:file:`ECHO.PY` should be imported as a module :mod:`echo`, :mod:`Echo` or
:mod:`ECHO`. (For example, Windows 95 has the annoying practice of showing all
file names with a capitalized first letter.) The DOS 8+3 filename restriction
adds another interesting problem for long module names.
The only solution is for the package author to provide an explicit index of the
package. The import statement uses the following convention: if a package's
package. The :keyword:`import` statement uses the following convention: if a package's
:file:`__init__.py` code defines a list named ``__all__``, it is taken to be the
list of module names that should be imported when ``from package import *`` is
encountered. It is up to the package author to keep this list up-to-date when a
......@@ -476,16 +476,16 @@ 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 import statements. Consider this code::
previous :keyword:`import` statements. Consider this code::
import sound.effects.echo
import sound.effects.surround
from sound.effects import *
In this example, the echo and surround modules are imported in the current
namespace because they are defined in the :mod:`sound.effects` package when the
``from...import`` statement is executed. (This also works when ``__all__`` is
defined.)
In this example, the :mod:`echo` and :mod:`surround` modules are imported in the
current namespace because they are defined in the :mod:`sound.effects` package
when the ``from...import`` statement is executed. (This also works when
``__all__`` is defined.)
Note that in general the practice of importing ``*`` from a module or package is
frowned upon, since it often causes poorly readable code. However, it is okay to
......@@ -537,5 +537,6 @@ modules found in a package.
.. rubric:: Footnotes
.. [#] In fact function definitions are also 'statements' that are 'executed'; the
execution enters the function name in the module's global symbol table.
execution of a module-level function enters the function name in the module's
global symbol table.
......@@ -347,12 +347,15 @@ Decimal Floating Point Arithmetic
The :mod:`decimal` module offers a :class:`Decimal` datatype for decimal
floating point arithmetic. Compared to the built-in :class:`float`
implementation of binary floating point, the new class is especially helpful for
financial applications and other uses which require exact decimal
representation, control over precision, control over rounding to meet legal or
regulatory requirements, tracking of significant decimal places, or for
applications where the user expects the results to match calculations done by
hand.
implementation of binary floating point, the class is especially helpful for
* financial applications and other uses which require exact decimal
representation,
* control over precision,
* control over rounding to meet legal or regulatory requirements,
* tracking of significant decimal places, or
* applications where the user expects the results to match calculations done by
hand.
For example, calculating a 5% tax on a 70 cent phone charge gives different
results in decimal floating point and binary floating point. The difference
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment