Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

PEP 282: Improve upon colloquial phrasing #2667

Merged
merged 4 commits into from
Aug 3, 2022
Merged

PEP 282: Improve upon colloquial phrasing #2667

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6c63165
Colloquial phrasing messed with highlighting
Kebap Jun 24, 2022
abe374e
undo last commit
Kebap Aug 2, 2022
15a666f
include feedback from review
Kebap Aug 2, 2022
0da1406
Retain literal markup.
vsajip Aug 3, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 18 additions & 14 deletions pep-0282.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ Simple Example
This shows a very simple example of how the logging package can be
used to generate simple logging output on stderr.

::
.. code-block:: python

--------- mymodule.py -------------------------------
import logging
Expand All @@ -76,6 +76,8 @@ used to generate simple logging output on stderr.
raise TypeError, "Bogus type error for testing"
-----------------------------------------------------

.. code-block:: python

--------- myapp.py ----------------------------------
import mymodule, logging

Expand All @@ -91,7 +93,9 @@ used to generate simple logging output on stderr.
log.info("Ending my app")
-----------------------------------------------------

% python myapp.py
.. code-block:: console

$ python myapp.py

INFO:MyApp: Starting my app
DEBUG:MyModule: Doin' stuff...
Expand All @@ -107,7 +111,9 @@ used to generate simple logging output on stderr.

The above example shows the default output format. All
aspects of the output format should be configurable, so that
you could have output formatted like this::
you could have output formatted like this:

.. code-block:: text

2002-04-19 07:56:58,174 MyModule DEBUG - Doin' stuff...

Expand All @@ -127,11 +133,9 @@ Logger names fit into a "dotted name" namespace, with dots
(periods) indicating sub-namespaces. The namespace of logger
objects therefore corresponds to a single tree data structure.

::

"" is the root of the namespace
"Zope" would be a child node of the root
"Zope.ZODB" would be a child node of "Zope"
* ``""`` is the root of the namespace
* ``"Zope"`` would be a child node of the root
* ``"Zope.ZODB"`` would be a child node of ``"Zope"``

These Logger objects create **LogRecord** objects which are passed
to **Handler** objects for output. Both Loggers and Handlers may
Expand Down Expand Up @@ -170,13 +174,13 @@ This is done through a module-level function::
Levels
======

The logging levels, in increasing order of importance, are::
The logging levels, in increasing order of importance, are:

DEBUG
INFO
WARN
ERROR
CRITICAL
* DEBUG
* INFO
* WARN
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After the PEP was written, WARN was replaced by WARNING as preferable.though WARN remains as an alias. Perhaps this should be reflected here too?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can defer to your judgement as PEP author, but per PEP 1,

In general, PEPs are no longer substantially modified after they have reached the Accepted, Final, Rejected or Superseded state. Once resolution is reached, a PEP is considered a historical document rather than a living specification. Formal documentation of the expected behavior should be maintained elsewhere, such as the Language Reference for core features, the Library Reference for standard library modules or the PyPA Specifications for packaging.

Presumably there are other things that are out of date here too, so IMO there isn't a need to update this just because it happened to be touched in a syntax update to ensure the PEP renders as intended.

I just merged #2702 which adds a new banner to point readers to where they can find the up to date, canonical documentation for the feature proposed by the PEP once its Final, which we could use to add a prominent link directing readers to the stdlib logging module reference.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed.

* ERROR
* CRITICAL

The term CRITICAL is used in preference to FATAL, which is used by
log4j. The levels are conceptually the same - that of a serious,
Expand Down