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. ........
This commit is contained in:
Alexandre Vassalotti
parent
fc230e8cfa
commit
6d3dfc3ff2
@ -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,7 +120,17 @@ Notes:
|
||||
Comparisons
|
||||
===========
|
||||
|
||||
.. index:: pair: chaining; comparisons
|
||||
.. index::
|
||||
pair: chaining; comparisons
|
||||
pair: operator; comparison
|
||||
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
|
||||
@ -128,17 +138,6 @@ 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: operator; comparison
|
||||
operator: ==
|
||||
operator: <
|
||||
operator: >
|
||||
operator: <=
|
||||
operator: >=
|
||||
operator: !=
|
||||
operator: is
|
||||
operator: is not
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. _tut-terminology:
|
||||
|
||||
A Word About Terminology
|
||||
========================
|
||||
|
||||
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
|
||||
(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-object:
|
||||
|
||||
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.
|
||||
"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.
|
||||
|
||||
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.)
|
||||
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.
|
||||
|
||||
Notice that code passed to ``exec()`` or ``eval()`` does not
|
||||
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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user