The PEP 668 expects an override mechanism to ease the transition.
This provides an override.
---------
Co-authored-by: Pradyun Gedam <pradyunsg@gmail.com>
Windows does not implement LC_MESSAGES, and since PEP 668 is mainly
designed for Linux distributions, we simply take the easier way out
until someone wants an equivalent on Windows.
This is a less disruptive mode of operation, and helps ensure that users
who are using documents that don't declare the doctype are presented
with a warning; instead of getting a hard-failure.
This is only necessary on messages which may contain `[`, which needs to
be escaped before printing with rich, since rich treats them as output
formats.
This makes it possible to present output with rich markup, within the
constraints of our logging infrastructure.
Further, diagnostic errors can now by presented using rich, using their
own special "[present-diagnostic]" marker string, since those need to be
handled differently from regular log messages and passed directly
through to rich's console object, after an indentation wrapper.
Borrow error presentation logic from sphinx-theme-builder, and
exhaustively test both the unicode and non-unicode presentation.
Utilise rich for colours and presentation logic handling, with tests to
ensure that colour degradation happens cleanly, and that the content is
stylized exactly as expected.
Catch diagnostic errors eagerly, and present them using rich. While this
won't include the pretty presentation in user logs, those files will
contain the entire traceback upto that line.
This introduces an exception and presentation model, for providing
better errors messages. The motivating idea is that the better error
messages contain clear wording and provide additional context to users
to better understand what is happening.
The `DiagnosticPipError` class introduces a structured framework in our
exception model, for code authors to write their error messages. The
usage explicitly requires passing "context" and a "hint" (which accept
None values). This should nudge code authors to explicitly think about
what additional information can/should be presented to the user, and
to provide relevant hints to them whenever possible. It also makes it
straightforward to identify cases where we don't do this, which may
serve as clear areas for improvement in the future.
The initial implementation is intentionally basic and doesn't do much;
however we should be able to introduce better usage of terminal colors
and other features (eg: hyperlinks!) to further improve the presentation
of these errors. It does improve the presentation style by a bit, even
though there are significant presentation-related improvements to be
made.
Additionally, having a structured framework means that these would be
improvements in presentation of *all* the errors that are within this
framework -- increasing the benefits of investing in the presentation
of these errors.
The typing module has been available since Python 3.5. Guarding the
import has been unnecessary since dropping Python 2.
Some guards remain to either:
- Avoid circular imports
- Importing objects that are also guarded by typing.TYPE_CHECKING
- Avoid mypy_extensions dependency
The stdlib module has been available since Python 3.5 and the
TYPE_CHECKING constant has been available since 3.5.2.
By using stdlib, this removes the need for pip to maintain its own
Python 2 typing compatibility shim.
Use pyupgrade to convert simple string formatting to use f-string
syntax. pyupgrade is intentionally timid and will not create an f-string
if it would make the expression longer or if the substitution parameters
are anything but simple names or dotted names.
Using typing.Text is unnecessary since dropping Python 2 support.
In Python 3, typing.Text is a simple alias of str. It exists as a
backward compatibility shim for Python 2.
Damian Shaw
Stéphane Bidoul
Stefano Rivera
Tzu-ping Chung
Danny McClanahan
hauntsaninja
q0w
Pradyun Gedam
Pradyun Gedam
Lukas Juhrich
harupy
Jon Dufresne
Pradyun Gedam
Hugo van Kemenade