diff options
author | Benjamin Peterson <benjamin@python.org> | 2013-01-04 04:34:40 (GMT) |
---|---|---|
committer | Benjamin Peterson <benjamin@python.org> | 2013-01-04 04:34:40 (GMT) |
commit | d73f369f4c52e921ba225043c0a820856369ef44 (patch) | |
tree | 4bc702b04312d48bc99c52c7621e15ef99f3c0ac /Doc | |
parent | 0a2c4f55c4d3288dce74513ef135fae167646f02 (diff) | |
parent | c44057dfbdb4e4f651e7cc4761aa63b7e8d128c3 (diff) | |
download | cpython-d73f369f4c52e921ba225043c0a820856369ef44.zip cpython-d73f369f4c52e921ba225043c0a820856369ef44.tar.gz cpython-d73f369f4c52e921ba225043c0a820856369ef44.tar.bz2 |
merge heads
Diffstat (limited to 'Doc')
-rw-r--r-- | Doc/faq/programming.rst | 4 | ||||
-rw-r--r-- | Doc/glossary.rst | 27 | ||||
-rw-r--r-- | Doc/howto/regex.rst | 49 | ||||
-rw-r--r-- | Doc/library/argparse.rst | 2 | ||||
-rw-r--r-- | Doc/library/audioop.rst | 6 | ||||
-rw-r--r-- | Doc/library/configparser.rst | 8 | ||||
-rw-r--r-- | Doc/library/ftplib.rst | 8 | ||||
-rw-r--r-- | Doc/library/pickle.rst | 9 | ||||
-rw-r--r-- | Doc/library/poplib.rst | 2 | ||||
-rw-r--r-- | Doc/library/smtplib.rst | 3 | ||||
-rw-r--r-- | Doc/library/socketserver.rst | 4 | ||||
-rw-r--r-- | Doc/reference/compound_stmts.rst | 14 | ||||
-rw-r--r-- | Doc/reference/expressions.rst | 28 | ||||
-rw-r--r-- | Doc/using/windows.rst | 2 |
14 files changed, 96 insertions, 70 deletions
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 2d5d2b1..aac8e81 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -313,6 +313,10 @@ calling another function by using ``*`` and ``**``:: g(x, *args, **kwargs) +.. index:: + single: argument; difference from parameter + single: parameter; difference from argument + .. _faq-argument-vs-parameter: What is the difference between arguments and parameters? diff --git a/Doc/glossary.rst b/Doc/glossary.rst index ddecc09..55c3470 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -240,8 +240,9 @@ Glossary function A series of statements which returns some value to a caller. It can also - be passed zero or more arguments which may be used in the execution of - the body. See also :term:`argument` and :term:`method`. + be passed zero or more :term:`arguments <argument>` which may be used in + the execution of the body. See also :term:`parameter`, :term:`method`, + and the :ref:`function` section. __future__ A pseudo-module which programmers can use to enable new language features @@ -355,17 +356,17 @@ Glossary slowly. See also :term:`interactive`. iterable - An object capable of returning its members one at a - time. Examples of iterables include all sequence types (such as - :class:`list`, :class:`str`, and :class:`tuple`) and some non-sequence - types like :class:`dict` and :class:`file` and objects of any classes you - define with an :meth:`__iter__` or :meth:`__getitem__` method. Iterables - can be used in a :keyword:`for` loop and in many other places where a - sequence is needed (:func:`zip`, :func:`map`, ...). When an iterable - object is passed as an argument to the built-in function :func:`iter`, it - returns an iterator for the object. This iterator is good for one pass - over the set of values. When using iterables, it is usually not necessary - to call :func:`iter` or deal with iterator objects yourself. The ``for`` + An object capable of returning its members one at a time. Examples of + iterables include all sequence types (such as :class:`list`, :class:`str`, + and :class:`tuple`) and some non-sequence types like :class:`dict`, + :term:`file objects <file object>`, and objects of any classes you define + with an :meth:`__iter__` or :meth:`__getitem__` method. Iterables can be + used in a :keyword:`for` loop and in many other places where a sequence is + needed (:func:`zip`, :func:`map`, ...). When an iterable object is passed + as an argument to the built-in function :func:`iter`, it returns an + iterator for the object. This iterator is good for one pass over the set + of values. When using iterables, it is usually not necessary to call + :func:`iter` or deal with iterator objects yourself. The ``for`` statement does that automatically for you, creating a temporary unnamed variable to hold the iterator for the duration of the loop. See also :term:`iterator`, :term:`sequence`, and :term:`generator`. diff --git a/Doc/howto/regex.rst b/Doc/howto/regex.rst index 3beca38..9adfa85 100644 --- a/Doc/howto/regex.rst +++ b/Doc/howto/regex.rst @@ -354,9 +354,9 @@ for a complete listing. +------------------+-----------------------------------------------+ :meth:`match` and :meth:`search` return ``None`` if no match can be found. If -they're successful, a ``MatchObject`` instance is returned, containing -information about the match: where it starts and ends, the substring it matched, -and more. +they're successful, a :ref:`match object <match-objects>` instance is returned, +containing information about the match: where it starts and ends, the substring +it matched, and more. You can learn about this by interactively experimenting with the :mod:`re` module. If you have :mod:`tkinter` available, you may also want to look at @@ -386,16 +386,16 @@ interpreter to print no output. You can explicitly print the result of None Now, let's try it on a string that it should match, such as ``tempo``. In this -case, :meth:`match` will return a :class:`MatchObject`, so you should store the -result in a variable for later use. :: +case, :meth:`match` will return a :ref:`match object <match-objects>`, so you +should store the result in a variable for later use. :: >>> m = p.match('tempo') >>> m #doctest: +ELLIPSIS <_sre.SRE_Match object at 0x...> -Now you can query the :class:`MatchObject` for information about the matching -string. :class:`MatchObject` instances also have several methods and -attributes; the most important ones are: +Now you can query the :ref:`match object <match-objects>` for information +about the matching string. :ref:`match object <match-objects>` instances +also have several methods and attributes; the most important ones are: +------------------+--------------------------------------------+ | Method/Attribute | Purpose | @@ -436,8 +436,9 @@ case. :: >>> m.span() (4, 11) -In actual programs, the most common style is to store the :class:`MatchObject` -in a variable, and then check if it was ``None``. This usually looks like:: +In actual programs, the most common style is to store the +:ref:`match object <match-objects>` in a variable, and then check if it was +``None``. This usually looks like:: p = re.compile( ... ) m = p.match( 'string goes here' ) @@ -454,8 +455,8 @@ Two pattern methods return all of the matches for a pattern. ['12', '11', '10'] :meth:`findall` has to create the entire list before it can be returned as the -result. The :meth:`finditer` method returns a sequence of :class:`MatchObject` -instances as an :term:`iterator`:: +result. The :meth:`finditer` method returns a sequence of +:ref:`match object <match-objects>` instances as an :term:`iterator`:: >>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...') >>> iterator #doctest: +ELLIPSIS @@ -476,7 +477,7 @@ You don't have to create a pattern object and call its methods; the :func:`search`, :func:`findall`, :func:`sub`, and so forth. These functions take the same arguments as the corresponding pattern method, with the RE string added as the first argument, and still return either ``None`` or a -:class:`MatchObject` instance. :: +:ref:`match object <match-objects>` instance. :: >>> print(re.match(r'From\s+', 'Fromage amk')) None @@ -786,9 +787,9 @@ Groups indicated with ``'('``, ``')'`` also capture the starting and ending index of the text that they match; this can be retrieved by passing an argument to :meth:`group`, :meth:`start`, :meth:`end`, and :meth:`span`. Groups are numbered starting with 0. Group 0 is always present; it's the whole RE, so -:class:`MatchObject` methods all have group 0 as their default argument. Later -we'll see how to express groups that don't capture the span of text that they -match. :: +:ref:`match object <match-objects>` methods all have group 0 as their default +argument. Later we'll see how to express groups that don't capture the span +of text that they match. :: >>> p = re.compile('(a)b') >>> m = p.match('ab') @@ -908,10 +909,10 @@ numbers, groups can be referenced by a name. The syntax for a named group is one of the Python-specific extensions: ``(?P<name>...)``. *name* is, obviously, the name of the group. Named groups also behave exactly like capturing groups, and additionally associate a name -with a group. The :class:`MatchObject` methods that deal with capturing groups -all accept either integers that refer to the group by number or strings that -contain the desired group's name. Named groups are still given numbers, so you -can retrieve information about a group in two ways:: +with a group. The :ref:`match object <match-objects>` methods that deal with +capturing groups all accept either integers that refer to the group by number +or strings that contain the desired group's name. Named groups are still +given numbers, so you can retrieve information about a group in two ways:: >>> p = re.compile(r'(?P<word>\b\w+\b)') >>> m = p.search( '(((( Lots of punctuation )))' ) @@ -1175,11 +1176,11 @@ three variations of the replacement string. :: *replacement* can also be a function, which gives you even more control. If *replacement* is a function, the function is called for every non-overlapping -occurrence of *pattern*. On each call, the function is passed a -:class:`MatchObject` argument for the match and can use this information to -compute the desired replacement string and return it. +occurrence of *pattern*. On each call, the function is passed a +:ref:`match object <match-objects>` argument for the match and can use this +information to compute the desired replacement string and return it. -In the following example, the replacement function translates decimals into +In the following example, the replacement function translates decimals into hexadecimal:: >>> def hexrepl(match): diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 5273e9b..3c2b862 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1440,7 +1440,7 @@ Sub-commands different functions which require different kinds of command-line arguments. :class:`ArgumentParser` supports the creation of such sub-commands with the :meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally - called with no arguments and returns an special action object. This object + called with no arguments and returns a special action object. This object has a single method, :meth:`~ArgumentParser.add_parser`, which takes a command name and any :class:`ArgumentParser` constructor arguments, and returns an :class:`ArgumentParser` object that can be modified as usual. diff --git a/Doc/library/audioop.rst b/Doc/library/audioop.rst index 51391ef..c947608 100644 --- a/Doc/library/audioop.rst +++ b/Doc/library/audioop.rst @@ -7,7 +7,7 @@ The :mod:`audioop` module contains some useful operations on sound fragments. It operates on sound fragments consisting of signed integer samples 8, 16 or 32 -bits wide, stored in Python strings. All scalar items are integers, unless +bits wide, stored in bytes objects. All scalar items are integers, unless specified otherwise. .. index:: @@ -126,7 +126,7 @@ The module defines the following variables and functions: .. function:: lin2alaw(fragment, width) Convert samples in the audio fragment to a-LAW encoding and return this as a - Python string. a-LAW is an audio encoding format whereby you get a dynamic + bytes object. a-LAW is an audio encoding format whereby you get a dynamic range of about 13 bits using only 8 bit samples. It is used by the Sun audio hardware, among others. @@ -151,7 +151,7 @@ The module defines the following variables and functions: .. function:: lin2ulaw(fragment, width) Convert samples in the audio fragment to u-LAW encoding and return this as a - Python string. u-LAW is an audio encoding format whereby you get a dynamic + bytes object. u-LAW is an audio encoding format whereby you get a dynamic range of about 14 bits using only 8 bit samples. It is used by the Sun audio hardware, among others. diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index 958375b..0b8212c 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -389,7 +389,13 @@ However, there are a few differences that should be taken into account: the default value to be visible again. Trying to delete a default value causes a ``KeyError``. -* Trying to delete the ``DEFAULTSECT`` raises ``ValueError``. +* ``DEFAULTSECT`` cannot be removed from the parser: + + * trying to delete it raises ``ValueError``, + + * ``parser.clear()`` leaves it intact, + + * ``parser.popitem()`` never returns it. * ``parser.get(section, option, **kwargs)`` - the second argument is **not** a fallback value. Note however that the section-level ``get()`` methods are diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index a669b1b..3274f19 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -377,10 +377,10 @@ followed by ``lines`` for the text version or ``binary`` for the binary version. .. method:: FTP.close() Close the connection unilaterally. This should not be applied to an already - closed connection such as after a successful call to :meth:`quit`. After this - call the :class:`FTP` instance should not be used any more (after a call to - :meth:`close` or :meth:`quit` you cannot reopen the connection by issuing - another :meth:`login` method). + closed connection such as after a successful call to :meth:`~FTP.quit`. + After this call the :class:`FTP` instance should not be used any more (after + a call to :meth:`close` or :meth:`~FTP.quit` you cannot reopen the + connection by issuing another :meth:`login` method). FTP_TLS Objects diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index a1f9af2..e250dcf 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -367,8 +367,9 @@ The following types can be pickled: * classes that are defined at the top level of a module -* instances of such classes whose :attr:`__dict__` or :meth:`__setstate__` is - picklable (see section :ref:`pickle-inst` for details) +* instances of such classes whose :attr:`__dict__` or the result of calling + :meth:`__getstate__` is picklable (see section :ref:`pickle-inst` for + details). Attempts to pickle unpicklable objects will raise the :exc:`PicklingError` exception; when this happens, an unspecified number of bytes may have already @@ -379,8 +380,8 @@ raised in this case. You can carefully raise this limit with Note that functions (built-in and user-defined) are pickled by "fully qualified" name reference, not by value. This means that only the function name is -pickled, along with the name of the module the function is defined in. Neither the -function's code, nor any of its function attributes are pickled. Thus the +pickled, along with the name of the module the function is defined in. Neither +the function's code, nor any of its function attributes are pickled. Thus the defining module must be importable in the unpickling environment, and the module must contain the named object, otherwise an exception will be raised. [#]_ diff --git a/Doc/library/poplib.rst b/Doc/library/poplib.rst index 01f680e..b4080d6 100644 --- a/Doc/library/poplib.rst +++ b/Doc/library/poplib.rst @@ -105,7 +105,7 @@ An :class:`POP3` instance has the following methods: .. method:: POP3.pass_(password) Send password, response includes message count and mailbox size. Note: the - mailbox on the server is locked until :meth:`quit` is called. + mailbox on the server is locked until :meth:`~poplib.quit` is called. .. method:: POP3.apop(user, secret) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 3101ab7..4a539fc 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -32,7 +32,8 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). setting will be used). For normal use, you should only require the initialization/connect, - :meth:`sendmail`, and :meth:`quit` methods. An example is included below. + :meth:`sendmail`, and :meth:`~smtplib.quit` methods. + An example is included below. .. class:: SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, certfile=None[, timeout]) diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst index 5287f17..4f22347 100644 --- a/Doc/library/socketserver.rst +++ b/Doc/library/socketserver.rst @@ -299,8 +299,8 @@ request. .. method:: RequestHandler.finish() Called after the :meth:`handle` method to perform any clean-up actions - required. The default implementation does nothing. If :meth:`setup` or - :meth:`handle` raise an exception, this function will not be called. + required. The default implementation does nothing. If :meth:`setup` + raises an exception, this function will not be called. .. method:: RequestHandler.handle() diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 6889176..d0d0646 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -417,6 +417,9 @@ is equivalent to :: statement. +.. index:: + single: parameter; function definition + .. _function: .. _def: @@ -478,11 +481,14 @@ is equivalent to :: def func(): pass func = f1(arg)(f2(func)) -.. index:: triple: default; parameter; value +.. index:: + triple: default; parameter; value + single: argument; function definition -When one or more parameters have the form *parameter* ``=`` *expression*, the -function is said to have "default parameter values." For a parameter with a -default value, the corresponding argument may be omitted from a call, in which +When one or more :term:`parameters <parameter>` have the form *parameter* ``=`` +*expression*, the function is said to have "default parameter values." For a +parameter with a default value, the corresponding :term:`argument` may be +omitted from a call, in which case the parameter's default value is substituted. If a parameter has a default value, all following parameters up until the "``*``" must also have a default value --- this is a syntactic restriction that is not expressed by the grammar. diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 2c6acb6..68de3c8 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -600,17 +600,18 @@ upper bound and stride, respectively, substituting ``None`` for missing expressions. +.. index:: + object: callable + single: call + single: argument; call semantics + .. _calls: Calls ----- -.. index:: single: call - -.. index:: object: callable - -A call calls a callable object (e.g., a function) with a possibly empty series -of arguments: +A call calls a callable object (e.g., a :term:`function`) with a possibly empty +series of :term:`arguments <argument>`: .. productionlist:: call: `primary` "(" [`argument_list` [","] | `comprehension`] ")" @@ -628,11 +629,14 @@ of arguments: A trailing comma may be present after the positional and keyword arguments but does not affect the semantics. +.. index:: + single: parameter; call semantics + The primary must evaluate to a callable object (user-defined functions, built-in functions, methods of built-in objects, class objects, methods of class instances, and all objects having a :meth:`__call__` method are callable). All argument expressions are evaluated before the call is attempted. Please refer -to section :ref:`function` for the syntax of formal parameter lists. +to section :ref:`function` for the syntax of formal :term:`parameter` lists. .. XXX update with kwonly args PEP @@ -1266,8 +1270,8 @@ their suffixes:: .. _operator-summary: -Summary -======= +Operator precedence +=================== .. index:: pair: operator; precedence @@ -1291,9 +1295,9 @@ groups from right to left). +-----------------------------------------------+-------------------------------------+ | :keyword:`and` | Boolean AND | +-----------------------------------------------+-------------------------------------+ -| :keyword:`not` *x* | Boolean NOT | +| :keyword:`not` ``x`` | Boolean NOT | +-----------------------------------------------+-------------------------------------+ -| :keyword:`in`, :keyword:`not` :keyword:`in`, | Comparisons, including membership | +| :keyword:`in`, :keyword:`not in`, | Comparisons, including membership | | :keyword:`is`, :keyword:`is not`, ``<``, | tests and identity tests, | | ``<=``, ``>``, ``>=``, ``!=``, ``==`` | | +-----------------------------------------------+-------------------------------------+ @@ -1319,7 +1323,7 @@ groups from right to left). +-----------------------------------------------+-------------------------------------+ | ``(expressions...)``, | Binding or tuple display, | | ``[expressions...]``, | list display, | -| ``{key:datum...}``, | dictionary display, | +| ``{key: value...}``, | dictionary display, | | ``{expressions...}`` | set display | +-----------------------------------------------+-------------------------------------+ diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index 742a290..c85afd2 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -82,6 +82,8 @@ In order to run Python flawlessly, you might have to change certain environment settings in Windows. +.. _setting-envvars: + Excursus: Setting environment variables --------------------------------------- |