diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/init.rst | 2 | ||||
| -rw-r--r-- | Doc/library/argparse.rst | 42 | ||||
| -rw-r--r-- | Doc/library/email.header.rst | 14 | ||||
| -rw-r--r-- | Doc/library/json.rst | 7 | ||||
| -rw-r--r-- | Doc/library/logging.config.rst | 23 |
5 files changed, 54 insertions, 34 deletions
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 623bd7c..535bf12 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -908,7 +908,7 @@ a worker thread and the actual call than made at the earliest convenience by the main thread where it has possession of the global interpreter lock and can perform any Python API calls. -.. c:function:: void Py_AddPendingCall( int (*func)(void *, void *arg) ) +.. c:function:: void Py_AddPendingCall(int (*func)(void *), void *arg) .. index:: single: Py_AddPendingCall() diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 2164ec0..0e05b49 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1,8 +1,8 @@ -:mod:`argparse` --- Parser for command line options, arguments and sub-commands +:mod:`argparse` --- Parser for command-line options, arguments and sub-commands =============================================================================== .. module:: argparse - :synopsis: Command-line option and argument parsing library. + :synopsis: Command-line option and argument-parsing library. .. moduleauthor:: Steven Bethard <steven.bethard@gmail.com> .. sectionauthor:: Steven Bethard <steven.bethard@gmail.com> @@ -12,7 +12,7 @@ -------------- -The :mod:`argparse` module makes it easy to write user friendly command line +The :mod:`argparse` module makes it easy to write user-friendly command-line interfaces. The program defines what arguments it requires, and :mod:`argparse` will figure out how to parse those out of :data:`sys.argv`. The :mod:`argparse` module also automatically generates help and usage messages and issues errors @@ -108,10 +108,10 @@ Parsing arguments ^^^^^^^^^^^^^^^^^ :class:`ArgumentParser` parses args through the -:meth:`~ArgumentParser.parse_args` method. This will inspect the command-line, +:meth:`~ArgumentParser.parse_args` method. This will inspect the command line, convert each arg to the appropriate type and then invoke the appropriate action. In most cases, this means a simple namespace object will be built up from -attributes parsed out of the command-line:: +attributes parsed out of the command line:: >>> parser.parse_args(['--sum', '7', '-1', '42']) Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42]) @@ -221,7 +221,7 @@ the parser's help message. For example, consider a file named parser.add_argument('--foo', help='foo help') args = parser.parse_args() -If ``-h`` or ``--help`` is supplied is at the command-line, the ArgumentParser +If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser help will be printed:: $ python myprogram.py --help @@ -578,23 +578,23 @@ The add_argument() method [const], [default], [type], [choices], [required], \ [help], [metavar], [dest]) - Define how a single command line argument should be parsed. Each parameter + Define how a single command-line argument should be parsed. Each parameter has its own more detailed description below, but in short they are: * `name or flags`_ - Either a name or a list of option strings, e.g. ``foo`` or ``-f, --foo`` * action_ - The basic type of action to be taken when this argument is - encountered at the command-line. + encountered at the command line. * nargs_ - The number of command-line arguments that should be consumed. * const_ - A constant value required by some action_ and nargs_ selections. * default_ - The value produced if the argument is absent from the - command-line. + command line. - * type_ - The type to which the command-line arg should be converted. + * type_ - The type to which the command-line argument should be converted. * choices_ - A container of the allowable values for the argument. @@ -752,7 +752,7 @@ single action to be taken. The ``nargs`` keyword argument associates a different number of command-line arguments with a single action.. The supported values are: -* N (an integer). N args from the command-line will be gathered together into a +* N (an integer). N args from the command line will be gathered together into a list. For example:: >>> parser = argparse.ArgumentParser() @@ -764,7 +764,7 @@ values are: Note that ``nargs=1`` produces a list of one item. This is different from the default, in which the item is produced by itself. -* ``'?'``. One arg will be consumed from the command-line if possible, and +* ``'?'``. One arg will be consumed from the command line if possible, and produced as a single item. If no command-line arg is present, the value from default_ will be produced. Note that for optional arguments, there is an additional case - the option string is present but not followed by a @@ -839,7 +839,7 @@ ArgumentParser actions. The two most common uses of it are: * When :meth:`add_argument` is called with option strings (like ``-f`` or ``--foo``) and ``nargs='?'``. This creates an optional argument that can be - followed by zero or one command-line args. When parsing the command-line, if + followed by zero or one command-line args. When parsing the command line, if the option string is encountered with no command-line arg following it, the value of ``const`` will be assumed instead. See the nargs_ description for examples. @@ -851,7 +851,7 @@ default ^^^^^^^ All optional arguments and some positional arguments may be omitted at the -command-line. The ``default`` keyword argument of :meth:`add_argument`, whose +command line. The ``default`` keyword argument of :meth:`add_argument`, whose value defaults to ``None``, specifies what value should be used if the command-line arg is not present. For optional arguments, the ``default`` value is used when the option string was not present at the command line:: @@ -949,7 +949,7 @@ choices Some command-line args should be selected from a restricted set of values. These can be handled by passing a container object as the ``choices`` keyword -argument to :meth:`add_argument`. When the command-line is parsed, arg values +argument to :meth:`add_argument`. When the command line is parsed, arg values will be checked, and an error message will be displayed if the arg was not one of the acceptable values:: @@ -982,7 +982,7 @@ required ^^^^^^^^ In general, the argparse module assumes that flags like ``-f`` and ``--bar`` -indicate *optional* arguments, which can always be omitted at the command-line. +indicate *optional* arguments, which can always be omitted at the command line. To make an option *required*, ``True`` can be specified for the ``required=`` keyword argument to :meth:`add_argument`:: @@ -1008,7 +1008,7 @@ help The ``help`` value is a string containing a brief description of the argument. When a user requests help (usually by using ``-h`` or ``--help`` at the -command-line), these ``help`` descriptions will be displayed with each +command line), these ``help`` descriptions will be displayed with each argument:: >>> parser = argparse.ArgumentParser(prog='frobble') @@ -1179,7 +1179,7 @@ passed as two separate arguments:: Namespace(foo='FOO', x=None) For long options (options with names longer than a single character), the option -and value can also be passed as a single command line argument, using ``=`` to +and value can also be passed as a single command-line argument, using ``=`` to separate them:: >>> parser.parse_args('--foo=FOO'.split()) @@ -1205,7 +1205,7 @@ as long as only the last option (or none of them) requires a value:: Invalid arguments ^^^^^^^^^^^^^^^^^ -While parsing the command-line, ``parse_args`` checks for a variety of errors, +While parsing the command line, ``parse_args`` checks for a variety of errors, including ambiguous options, invalid types, invalid options, wrong number of positional arguments, etc. When it encounters such an error, it exits and prints the error along with a usage message:: @@ -1641,7 +1641,7 @@ Parser defaults Most of the time, the attributes of the object returned by :meth:`parse_args` will be fully determined by inspecting the command-line args and the argument actions. :meth:`ArgumentParser.set_defaults` allows some additional - attributes that are determined without any inspection of the command-line to + attributes that are determined without any inspection of the command line to be added:: >>> parser = argparse.ArgumentParser() @@ -1712,7 +1712,7 @@ Partial parsing .. method:: ArgumentParser.parse_known_args(args=None, namespace=None) -Sometimes a script may only parse a few of the command line arguments, passing +Sometimes a script may only parse a few of the command-line arguments, passing the remaining arguments on to another script or program. In these cases, the :meth:`parse_known_args` method can be useful. It works much like :meth:`~ArgumentParser.parse_args` except that it does not produce an error when diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst index 29752c4..c385cf3 100644 --- a/Doc/library/email.header.rst +++ b/Doc/library/email.header.rst @@ -109,9 +109,17 @@ Here is the :class:`Header` class description: Encode a message header into an RFC-compliant format, possibly wrapping long lines and encapsulating non-ASCII parts in base64 or quoted-printable - encodings. Optional *splitchars* is a string containing characters to - split long ASCII lines on, in rough support of :rfc:`2822`'s *highest - level syntactic breaks*. This doesn't affect :rfc:`2047` encoded lines. + encodings. + + Optional *splitchars* is a string containing characters which should be + given extra weight by the splitting algorithm during normal header + wrapping. This is in very rough support of :RFC:`2822`\'s 'higher level + syntactic breaks': split points preceded by a splitchar are preferred + during line splitting, with the characters preferred in the order in + which they appear in the string. Space and tab may be included in the + string to indicate whether preference should be given to one over the + other as a split point when other split chars do not appear in the line + being split. Splitchars does not affect :RFC:`2047` encoded lines. *maxlinelen*, if given, overrides the instance's value for the maximum line length. diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 0db86be..dcd6973 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -160,9 +160,10 @@ Basic Usage .. note:: - Unlike :mod:`pickle` and :mod:`marshal`, JSON is not a framed protocol so - trying to serialize more objects with repeated calls to :func:`dump` and - the same *fp* will result in an invalid JSON file. + Unlike :mod:`pickle` and :mod:`marshal`, JSON is not a framed protocol, + so trying to serialize multiple objects with repeated calls to + :func:`dump` using the same *fp* will result in an invalid JSON file. + .. function:: load(fp, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw) diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst index 143916f..bb80a7f 100644 --- a/Doc/library/logging.config.rst +++ b/Doc/library/logging.config.rst @@ -74,14 +74,25 @@ in :mod:`logging` itself) and defining handlers which are declared either in .. versionadded:: 3.2 -.. function:: fileConfig(fname[, defaults]) +.. function:: fileConfig(fname, defaults=None, disable_existing_loggers=True) - Reads the logging configuration from a :mod:`configparser`\-format file named - *fname*. This function can be called several times from an application, - allowing an end user to select from various pre-canned + Reads the logging configuration from a :mod:`configparser`\-format file + named *fname*. This function can be called several times from an + application, allowing an end user to select from various pre-canned configurations (if the developer provides a mechanism to present the choices - and load the chosen configuration). Defaults to be passed to the ConfigParser - can be specified in the *defaults* argument. + and load the chosen configuration). + + :param defaults: Defaults to be passed to the ConfigParser can be specified + in this argument. + + :param disable_existing_loggers: If specified as ``False``, loggers which + exist when this call is made are left + alone. The default is ``True`` because this + enables old behaviour in a backward- + compatible way. This behaviour is to + disable any existing loggers unless they or + their ancestors are explicitly named in the + logging configuration. .. function:: listen(port=DEFAULT_LOGGING_CONFIG_PORT) |