From aee112f3c545bb45f13ad82a8bd88afb8a20860f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Delfino?= Date: Fri, 22 Jun 2018 12:46:16 -0300 Subject: [PATCH 1/4] bpo-33943: Add references to logging.basicConfig --- Doc/library/functions.rst | 5 +++++ Doc/library/logging.rst | 16 ++++++++++------ 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 457e1c34ec9a26..7b1b0caa11abbe 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -971,6 +971,11 @@ are always available. They are listed here in alphabetical order. encoding. (For reading and writing raw bytes use binary mode and leave *encoding* unspecified.) The available modes are: + .. _filemodes: + + .. index:: + pair: file; modes + ========= =============================================================== Character Meaning ========= =============================================================== diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 774bd83f41035c..3f1efae72648fd 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1151,23 +1151,27 @@ functions. | | using the specified filename, rather than a | | | StreamHandler. | +--------------+---------------------------------------------+ - | ``filemode`` | Specifies the mode to open the file, if | - | | filename is specified (if filemode is | - | | unspecified, it defaults to 'a'). | + | ``filemode`` | Specifies the :ref:`mode ` to | + | | open the file, if | + | | filename is specified. Defaults to | + | | ``'a'``. | +--------------+---------------------------------------------+ | ``format`` | Use the specified format string for the | | | handler. | +--------------+---------------------------------------------+ - | ``datefmt`` | Use the specified date/time format. | + | ``datefmt`` | Use the specified :func:`time.strftime` | + | | style date/time format. | +--------------+---------------------------------------------+ | ``style`` | If ``format`` is specified, use this style | | | for the format string. One of '%', '{' or | - | | '$' for %-formatting, :meth:`str.format` or | + | | '$' for :ref:`printf-style | + | | `, | + | | :meth:`str.format` or | | | :class:`string.Template` respectively, and | | | defaulting to '%' if not specified. | +--------------+---------------------------------------------+ | ``level`` | Set the root logger level to the specified | - | | level. | + | | :ref:`level `. | +--------------+---------------------------------------------+ | ``stream`` | Use the specified stream to initialize the | | | StreamHandler. Note that this argument is | From e6470c8afc9de22a2435c5d55357236e7facbacb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Delfino?= Date: Sat, 23 Jun 2018 10:49:23 -0300 Subject: [PATCH 2/4] Minor changes --- Doc/library/logging.rst | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 3f1efae72648fd..ec924f30bf240f 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1151,10 +1151,9 @@ functions. | | using the specified filename, rather than a | | | StreamHandler. | +--------------+---------------------------------------------+ - | ``filemode`` | Specifies the :ref:`mode ` to | - | | open the file, if | - | | filename is specified. Defaults to | - | | ``'a'``. | + | ``filemode`` | If ``filename`` is specified, use this | + | | in this :ref:`mode `. Defaults | + | | to ``'a'``. | +--------------+---------------------------------------------+ | ``format`` | Use the specified format string for the | | | handler. | @@ -1163,20 +1162,20 @@ functions. | | style date/time format. | +--------------+---------------------------------------------+ | ``style`` | If ``format`` is specified, use this style | - | | for the format string. One of '%', '{' or | - | | '$' for :ref:`printf-style | + | | for the format string. One of ``'%'``, | + | | ``'{'`` or ``'$'`` for :ref:`printf-style | | | `, | | | :meth:`str.format` or | - | | :class:`string.Template` respectively, and | - | | defaulting to '%' if not specified. | + | | :class:`string.Template` respectively. | + | | Defaults to ``'%'`` | +--------------+---------------------------------------------+ | ``level`` | Set the root logger level to the specified | | | :ref:`level `. | +--------------+---------------------------------------------+ | ``stream`` | Use the specified stream to initialize the | | | StreamHandler. Note that this argument is | - | | incompatible with 'filename' - if both are | - | | present, a ``ValueError`` is raised. | + | | incompatible with ``filename`` - if both | + | | are present, a ``ValueError`` is raised. | +--------------+---------------------------------------------+ | ``handlers`` | If specified, this should be an iterable of | | | already created handlers to add to the root | @@ -1184,8 +1183,8 @@ functions. | | have a formatter set will be assigned the | | | default formatter created in this function. | | | Note that this argument is incompatible | - | | with 'filename' or 'stream' - if both are | - | | present, a ``ValueError`` is raised. | + | | with ``filename`` or ``stream`` - if both | + | | are present, a ``ValueError`` is raised. | +--------------+---------------------------------------------+ .. versionchanged:: 3.2 From 5f82462bb705a8d29caff3800af58b06c18c05c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Delfino?= Date: Sat, 23 Jun 2018 10:51:00 -0300 Subject: [PATCH 3/4] Fix --- Doc/library/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index ec924f30bf240f..90bc79b58d956a 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1151,7 +1151,7 @@ functions. | | using the specified filename, rather than a | | | StreamHandler. | +--------------+---------------------------------------------+ - | ``filemode`` | If ``filename`` is specified, use this | + | ``filemode`` | If ``filename`` is specified, open the file | | | in this :ref:`mode `. Defaults | | | to ``'a'``. | +--------------+---------------------------------------------+ From 01e0c9bf5a7dab3d9a1b5fb72ee7b447a16f7ec7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Delfino?= Date: Sun, 24 Jun 2018 09:16:33 -0300 Subject: [PATCH 4/4] Address Tal's comments --- Doc/library/logging.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 90bc79b58d956a..212abf9dee5497 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1147,43 +1147,43 @@ functions. +--------------+---------------------------------------------+ | Format | Description | +==============+=============================================+ - | ``filename`` | Specifies that a FileHandler be created, | + | *filename* | Specifies that a FileHandler be created, | | | using the specified filename, rather than a | | | StreamHandler. | +--------------+---------------------------------------------+ - | ``filemode`` | If ``filename`` is specified, open the file | + | *filemode* | If *filename* is specified, open the file | | | in this :ref:`mode `. Defaults | | | to ``'a'``. | +--------------+---------------------------------------------+ - | ``format`` | Use the specified format string for the | + | *format* | Use the specified format string for the | | | handler. | +--------------+---------------------------------------------+ - | ``datefmt`` | Use the specified :func:`time.strftime` | - | | style date/time format. | + | *datefmt* | Use the specified date/time format, as | + | | accepted by :func:`time.strftime`. | +--------------+---------------------------------------------+ - | ``style`` | If ``format`` is specified, use this style | + | *style* | If *format* is specified, use this style | | | for the format string. One of ``'%'``, | | | ``'{'`` or ``'$'`` for :ref:`printf-style | | | `, | | | :meth:`str.format` or | | | :class:`string.Template` respectively. | - | | Defaults to ``'%'`` | + | | Defaults to ``'%'``. | +--------------+---------------------------------------------+ - | ``level`` | Set the root logger level to the specified | + | *level* | Set the root logger level to the specified | | | :ref:`level `. | +--------------+---------------------------------------------+ - | ``stream`` | Use the specified stream to initialize the | + | *stream* | Use the specified stream to initialize the | | | StreamHandler. Note that this argument is | - | | incompatible with ``filename`` - if both | + | | incompatible with *filename* - if both | | | are present, a ``ValueError`` is raised. | +--------------+---------------------------------------------+ - | ``handlers`` | If specified, this should be an iterable of | + | *handlers* | If specified, this should be an iterable of | | | already created handlers to add to the root | | | logger. Any handlers which don't already | | | have a formatter set will be assigned the | | | default formatter created in this function. | | | Note that this argument is incompatible | - | | with ``filename`` or ``stream`` - if both | + | | with *filename* or *stream* - if both | | | are present, a ``ValueError`` is raised. | +--------------+---------------------------------------------+