diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/functions.rst | 89 | ||||
| -rw-r--r-- | Doc/library/math.rst | 25 | ||||
| -rw-r--r-- | Doc/library/multiprocessing.rst | 18 | ||||
| -rw-r--r-- | Doc/library/optparse.rst | 47 | ||||
| -rw-r--r-- | Doc/library/shutil.rst | 2 | ||||
| -rw-r--r-- | Doc/library/signal.rst | 8 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 2 |
7 files changed, 105 insertions, 86 deletions
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 5e29b67..877d9b6 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) + <module 'foo' from ...> + >>> baz = sys.modules[name] + >>> baz + <module 'foo.bar.baz' from ...> .. rubric:: Footnotes diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 588aef3..1e9611e 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 1ff77db..dbaa64e 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 3d8b43c..7989d33 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 ac52ce4..b332d9a 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 9012291..5033e0e 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 a1eb688..de00c49 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 |