From 6ebe78f5ccf7a58e64b42e74f7977c49d1c8f08b Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Sun, 21 Dec 2008 00:06:59 +0000 Subject: Merged revisions 67654,67676-67677,67681,67692,67725,67761,67784-67785,67787-67788,67802,67848-67850,67862-67864,67880,67882 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67654 | georg.brandl | 2008-12-07 16:42:09 -0600 (Sun, 07 Dec 2008) | 2 lines #4457: rewrite __import__() documentation. ........ r67676 | benjamin.peterson | 2008-12-08 20:03:03 -0600 (Mon, 08 Dec 2008) | 1 line specify how things are copied ........ r67677 | benjamin.peterson | 2008-12-08 20:05:11 -0600 (Mon, 08 Dec 2008) | 1 line revert unrelated change to installer script ........ r67681 | jeremy.hylton | 2008-12-09 15:03:10 -0600 (Tue, 09 Dec 2008) | 2 lines Add simple unittests for Request ........ r67692 | amaury.forgeotdarc | 2008-12-10 18:03:42 -0600 (Wed, 10 Dec 2008) | 2 lines #1030250: correctly pass the dry_run option to the mkpath() function. ........ r67725 | benjamin.peterson | 2008-12-12 22:02:20 -0600 (Fri, 12 Dec 2008) | 1 line fix incorrect example ........ r67761 | benjamin.peterson | 2008-12-14 11:26:04 -0600 (Sun, 14 Dec 2008) | 1 line fix missing bracket ........ r67784 | georg.brandl | 2008-12-15 02:33:58 -0600 (Mon, 15 Dec 2008) | 2 lines #4446: document "platforms" argument for setup(). ........ r67785 | georg.brandl | 2008-12-15 02:36:11 -0600 (Mon, 15 Dec 2008) | 2 lines #4611: fix typo. ........ r67787 | georg.brandl | 2008-12-15 02:58:59 -0600 (Mon, 15 Dec 2008) | 2 lines #4578: fix has_key() usage in compiler package. ........ r67788 | georg.brandl | 2008-12-15 03:07:39 -0600 (Mon, 15 Dec 2008) | 2 lines #4568: remove limitation in varargs callback example. ........ r67802 | amaury.forgeotdarc | 2008-12-15 16:29:14 -0600 (Mon, 15 Dec 2008) | 4 lines #3632: the "pyo" macro from gdbinit can now run when the GIL is released. Patch by haypo. ........ r67848 | benjamin.peterson | 2008-12-18 20:28:56 -0600 (Thu, 18 Dec 2008) | 1 line fix typo ........ r67849 | benjamin.peterson | 2008-12-18 20:31:35 -0600 (Thu, 18 Dec 2008) | 1 line _call_method -> _callmethod and _get_value to _getvalue ........ r67850 | raymond.hettinger | 2008-12-19 03:06:07 -0600 (Fri, 19 Dec 2008) | 9 lines Fix-up and clean-up docs for int.bit_length(). * Replace dramatic footnote with in-line comment about possible round-off errors in logarithms of large numbers. * Add comments to the pure python code equivalent. * replace floor() with int() in the mathematical equivalent so the type is correct (should be an int, not a float). * add abs() to the mathematical equivalent so that it matches the previous line that it is supposed to be equivalent to. * make one combined example with a negative input. ........ r67862 | benjamin.peterson | 2008-12-19 20:48:02 -0600 (Fri, 19 Dec 2008) | 1 line copy sentence from docstring ........ r67863 | benjamin.peterson | 2008-12-19 20:51:26 -0600 (Fri, 19 Dec 2008) | 1 line add headings ........ r67864 | benjamin.peterson | 2008-12-19 20:57:19 -0600 (Fri, 19 Dec 2008) | 1 line beef up docstring ........ r67880 | benjamin.peterson | 2008-12-20 16:49:24 -0600 (Sat, 20 Dec 2008) | 1 line remove redundant sentence ........ r67882 | benjamin.peterson | 2008-12-20 16:59:49 -0600 (Sat, 20 Dec 2008) | 1 line add some recent releases to the list ........ --- Doc/distutils/setupscript.rst | 2 + Doc/extending/extending.rst | 2 +- Doc/howto/functional.rst | 9 ++--- Doc/library/functions.rst | 89 ++++++++++++++++++++++++----------------- Doc/library/math.rst | 25 +++++++----- Doc/library/multiprocessing.rst | 18 ++++----- Doc/library/optparse.rst | 47 ++++++++++------------ Doc/library/shutil.rst | 2 +- Doc/library/signal.rst | 8 ++-- Doc/library/stdtypes.rst | 2 +- Doc/whatsnew/2.6.rst | 2 +- 11 files changed, 113 insertions(+), 93 deletions(-) (limited to 'Doc') diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst index 6e3fd3826e..7a6be8b270 100644 --- a/Doc/distutils/setupscript.rst +++ b/Doc/distutils/setupscript.rst @@ -561,6 +561,8 @@ This information includes: +----------------------+---------------------------+-----------------+--------+ | ``classifiers`` | a list of classifiers | list of strings | \(4) | +----------------------+---------------------------+-----------------+--------+ +| ``platforms`` | a list of platforms | list of strings | | ++----------------------+---------------------------+-----------------+--------+ Notes: diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index c05bcfd7d4..ef2c726f1d 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -882,7 +882,7 @@ memory and should be avoided completely. [#]_ The advantage of borrowing over owning a reference is that you don't need to take care of disposing of the reference on all possible paths through the code --- in other words, with a borrowed reference you don't run the risk of leaking -when a premature exit is taken. The disadvantage of borrowing over leaking is +when a premature exit is taken. The disadvantage of borrowing over owning is that there are some subtle situations where in seemingly correct code a borrowed reference can be used after the owner from which it was borrowed has in fact disposed of it. diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index 47798e9e11..1d9b42d7b6 100644 --- a/Doc/howto/functional.rst +++ b/Doc/howto/functional.rst @@ -677,11 +677,10 @@ indexes at which certain conditions are met:: if line.strip() == '': print('Blank line at line #%i' % i) - -``sorted(iterable, [cmp=None], [key=None], [reverse=False)`` collects all the -elements of the iterable into a list, sorts the list, and returns the sorted -result. The ``cmp``, ``key``, and ``reverse`` arguments are passed through to -the constructed list's ``.sort()`` method. :: +``sorted(iterable, [key=None], [reverse=False])`` collects all the elements of +the iterable into a list, sorts the list, and returns the sorted result. The +``key``, and ``reverse`` arguments are passed through to the constructed list's +``.sort()`` method. :: >>> import random >>> # Generate 8 random numbers between [0, 10000) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 5e29b67cf2..877d9b66ec 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1172,47 +1172,64 @@ are always available. They are listed here in alphabetical order. This is an advanced function that is not needed in everyday Python programming. - The function is invoked by the :keyword:`import` statement. It mainly exists - so that you can replace it with another function that has a compatible - interface, in order to change the semantics of the :keyword:`import` - statement. See the built-in module :mod:`imp`, which defines some useful - operations out of which you can build your own :func:`__import__` function. - - For example, the statement ``import spam`` results in the following call: - ``__import__('spam', globals(), locals(), [], -1)``; the statement - ``from spam.ham import eggs`` results in ``__import__('spam.ham', globals(), - locals(), ['eggs'], -1)``. Note that even though ``locals()`` and ``['eggs']`` - are passed in as arguments, the :func:`__import__` function does not set the - local variable named ``eggs``; this is done by subsequent code that is generated - for the import statement. (In fact, the standard implementation does not use - its *locals* argument at all, and uses its *globals* only to determine the - package context of the :keyword:`import` statement.) + This function is invoked by the :keyword:`import` statement. It can be + replaced (by importing the :mod:`builtins` module and assigning to + ``builtins.__import__``) in order to change semantics of the + :keyword:`import` statement, but nowadays it is usually simpler to use import + hooks (see :pep:`302`). Direct use of :func:`__import__` is rare, except in + cases where you want to import a module whose name is only known at runtime. + + The function imports the module *name*, potentially using the given *globals* + and *locals* to determine how to interpret the name in a package context. + The *fromlist* gives the names of objects or submodules that should be + imported from the module given by *name*. The standard implementation does + not use its *locals* argument at all, and uses its *globals* only to + determine the package context of the :keyword:`import` statement. + + *level* specifies whether to use absolute or relative imports. The default + is ``-1`` which indicates both absolute and relative imports will be + attempted. ``0`` means only perform absolute imports. Positive values for + *level* indicate the number of parent directories to search relative to the + directory of the module calling :func:`__import__`. When the *name* variable is of the form ``package.module``, normally, the top-level package (the name up till the first dot) is returned, *not* the module named by *name*. However, when a non-empty *fromlist* argument is - given, the module named by *name* is returned. This is done for - compatibility with the :term:`bytecode` generated for the different kinds of import - statement; when using ``import spam.ham.eggs``, the top-level package - :mod:`spam` must be placed in the importing namespace, but when using ``from - spam.ham import eggs``, the ``spam.ham`` subpackage must be used to find the - ``eggs`` variable. As a workaround for this behavior, use :func:`getattr` to - extract the desired components. For example, you could define the following - helper:: - - def my_import(name): - mod = __import__(name) - components = name.split('.') - for comp in components[1:]: - mod = getattr(mod, comp) - return mod - - *level* specifies whether to use absolute or relative imports. The default is - ``-1`` which indicates both absolute and relative imports will be attempted. - ``0`` means only perform absolute imports. Positive values for *level* indicate - the number of parent directories to search relative to the directory of the - module calling :func:`__import__`. + given, the module named by *name* is returned. + For example, the statement ``import spam`` results in bytecode resembling the + following code:: + + spam = __import__('spam', globals(), locals(), [], -1) + + The statement ``import spam.ham`` results in this call:: + + spam = __import__('spam.ham', globals(), locals(), [], -1) + + Note how :func:`__import__` returns the toplevel module here because this is + the object that is bound to a name by the :keyword:`import` statement. + + On the other hand, the statement ``from spam.ham import eggs, sausage as + saus`` results in :: + + _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], -1) + eggs = _temp.eggs + saus = _temp.sausage + + Here, the ``spam.ham`` module is returned from :func:`__import__`. From this + object, the names to import are retrieved and assigned to their respective + names. + + If you simply want to import a module (potentially within a package) by name, + you can get it from :data:`sys.modules`:: + + >>> import sys + >>> name = 'foo.bar.baz' + >>> __import__(name) + + >>> baz = sys.modules[name] + >>> baz + .. rubric:: Footnotes diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 588aef33f0..1e9611e364 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -21,8 +21,9 @@ was generated in the first place. The following functions are provided by this module. Except when explicitly noted otherwise, all return values are floats. -Number-theoretic and representation functions: +Number-theoretic and representation functions +--------------------------------------------- .. function:: ceil(x) @@ -110,8 +111,8 @@ Number-theoretic and representation functions: .. function:: modf(x) - Return the fractional and integer parts of *x*. Both results carry the sign of - *x*, and both are floats. + Return the fractional and integer parts of *x*. Both results carry the sign + of *x* and are floats. .. function:: trunc(x) @@ -131,7 +132,9 @@ Python floats typically carry no more than 53 bits of precision (the same as the platform C double type), in which case any float *x* with ``abs(x) >= 2**52`` necessarily has no fractional bits. -Power and logarithmic functions: + +Power and logarithmic functions +------------------------------- .. function:: exp(x) @@ -169,7 +172,8 @@ Power and logarithmic functions: Return the square root of *x*. -Trigonometric functions: +Trigonometric functions +----------------------- .. function:: acos(x) @@ -217,7 +221,8 @@ Trigonometric functions: Return the tangent of *x* radians. -Angular conversion: +Angular conversion +------------------ .. function:: degrees(x) @@ -229,7 +234,8 @@ Angular conversion: Converts angle *x* from degrees to radians. -Hyperbolic functions: +Hyperbolic functions +-------------------- .. function:: acosh(x) @@ -262,9 +268,8 @@ Hyperbolic functions: Return the hyperbolic tangent of *x*. - -The module also defines two mathematical constants: - +Constants +========= .. data:: pi diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 1ff77dbaa3..dbaa64e248 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -1436,13 +1436,13 @@ itself. This means, for example, that one shared object can contain a second:: Proxy objects are instances of subclasses of :class:`BaseProxy`. - .. method:: _call_method(methodname[, args[, kwds]]) + .. method:: _callmethod(methodname[, args[, kwds]]) Call and return the result of a method of the proxy's referent. If ``proxy`` is a proxy whose referent is ``obj`` then the expression :: - proxy._call_method(methodname, args, kwds) + proxy._callmethod(methodname, args, kwds) will evaluate the expression :: @@ -1455,26 +1455,26 @@ itself. This means, for example, that one shared object can contain a second:: argument of :meth:`BaseManager.register`. If an exception is raised by the call, then then is re-raised by - :meth:`_call_method`. If some other exception is raised in the manager's + :meth:`_callmethod`. If some other exception is raised in the manager's process then this is converted into a :exc:`RemoteError` exception and is - raised by :meth:`_call_method`. + raised by :meth:`_callmethod`. Note in particular that an exception will be raised if *methodname* has not been *exposed* - An example of the usage of :meth:`_call_method`:: + An example of the usage of :meth:`_callmethod`:: >>> l = manager.list(range(10)) - >>> l._call_method('__len__') + >>> l._callmethod('__len__') 10 - >>> l._call_method('__getslice__', (2, 7)) # equiv to `l[2:7]` + >>> l._callmethod('__getslice__', (2, 7)) # equiv to `l[2:7]` [2, 3, 4, 5, 6] - >>> l._call_method('__getitem__', (20,)) # equiv to `l[20]` + >>> l._callmethod('__getitem__', (20,)) # equiv to `l[20]` Traceback (most recent call last): ... IndexError: list index out of range - .. method:: _get_value() + .. method:: _getvalue() Return a copy of the referent. diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index 3d8b43c3ad..7989d332da 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -1625,36 +1625,33 @@ directly). Nevertheless, here's a stab at a callback for an option with variable arguments:: - def vararg_callback(option, opt_str, value, parser): - assert value is None - done = 0 - value = [] - rargs = parser.rargs - while rargs: - arg = rargs[0] - - # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f", - # etc. Note that this also stops on "-3" or "-3.0", so if - # your option takes numeric values, you will need to handle - # this. - if ((arg[:2] == "--" and len(arg) > 2) or - (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")): - break - else: - value.append(arg) - del rargs[0] - - setattr(parser.values, option.dest, value) + def vararg_callback(option, opt_str, value, parser): + assert value is None + value = [] + + def floatable(str): + try: + float(str) + return True + except ValueError: + return False + + for arg in parser.rargs: + # stop on --foo like options + if arg[:2] == "--" and len(arg) > 2: + break + # stop on -a, but not on -3 or -3.0 + if arg[:1] == "-" and len(arg) > 1 and not floatable(arg): + break + value.append(arg) + + del parser.rargs[:len(value)] + setattr(parser.values, option.dest, value)) [...] parser.add_option("-c", "--callback", dest="vararg_attr", action="callback", callback=vararg_callback) -The main weakness with this particular implementation is that negative numbers -in the arguments following ``"-c"`` will be interpreted as further options -(probably causing an error), rather than as arguments to ``"-c"``. Fixing this -is left as an exercise for the reader. - .. _optparse-extending-optparse: diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index ac52ce4b03..b332d9a5cf 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -139,7 +139,7 @@ copying and removal. For operations on individual files, see also the Recursively move a file or directory to another location. If the destination is on the current filesystem, then simply use rename. - Otherwise, copy src to the dst and then remove src. + Otherwise, copy src (with :func:`copy2`) to the dst and then remove src. .. exception:: Error diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst index 901229110e..5033e0e2a9 100644 --- a/Doc/library/signal.rst +++ b/Doc/library/signal.rst @@ -52,10 +52,10 @@ The variables defined in the :mod:`signal` module are: .. data:: SIG_DFL - This is one of two standard signal handling options; it will simply perform the - default function for the signal. For example, on most systems the default - action for :const:`SIGQUIT` is to dump core and exit, while the default action - for :const:`SIGCLD` is to simply ignore it. + This is one of two standard signal handling options; it will simply perform + the default function for the signal. For example, on most systems the + default action for :const:`SIGQUIT` is to dump core and exit, while the + default action for :const:`SIGCHLD` is to simply ignore it. .. data:: SIG_IGN diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index a1eb6886b4..de00c491e7 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -442,7 +442,7 @@ Additional Methods on Integer Types Equivalent to:: def bit_length(self): - s = bin(self) # binary representation: bin(-37) --> '-0b100101' + s = bin(x) # binary representation: bin(-37) --> '-0b100101' s = s.lstrip('-0b') # remove leading zeros and minus sign return len(s) # len('100101') --> 6 diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index 98850eabf0..d9a19935a9 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -738,7 +738,7 @@ The formatting template uses curly brackets (`{`, `}`) as special characters:: Curly brackets can be escaped by doubling them:: - >>> format("Empty dict: {{}}") + >>> "Empty dict: {{}}".format() "Empty dict: {}" Field names can be integers indicating positional arguments, such as -- cgit v1.2.1