Skip to content

Commit

Permalink
DOC: Make ordering on warnings page consistent (#2616)
Browse files Browse the repository at this point in the history
Put exceptions, warnings, and log messages in a consistent order
  • Loading branch information
j-t-1 authored May 1, 2024
1 parent b1b55e6 commit d9bf67f
Showing 1 changed file with 13 additions and 13 deletions.
26 changes: 13 additions & 13 deletions docs/user/suppress-warnings.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,33 @@
# Exceptions, Warnings, and Log messages

pypdf makes use of 3 mechanisms to show that something went wrong:
pypdf makes use of three mechanisms to show if something went wrong:

* **Log messages** are informative messages that can be used for post-mortem
analysis. Most of the time, users can ignore them. They come in different
*levels*, such as info / warning / error indicating the severity.
Examples are non-standard compliant PDF files which pypdf can deal with or
a missing implementation that leads to a part of the text not being extracted.
* **Exceptions** are error cases that pypdf users should explicitly handle.
In the `strict=True` mode, most log messages with the warning level will
become exceptions. This can be useful in applications where you can require
a user to fix the broken PDF.
* **Warnings** are avoidable issues, such as using deprecated classes /
functions / parameters. Another example is missing capabilities of pypdf.
In those cases, pypdf users should adjust their code. Warnings
are issued by the `warnings` module - those are different from the log-level
"warning".
* **Exceptions** are error-cases that pypdf users should explicitly handle.
In the `strict=True` mode, most log messages with the warning level will
become exceptions. This can be useful in applications where you can require
a user to fix the broken PDF.
* **Log messages** are informative messages that can be used for post-mortem
analysis. Most of the time, users can ignore them. They come in different
*levels*, such as info / warning / error indicating the severity.
Examples are non-standard compliant PDF files which pypdf can deal with or
a missing implementation that leads to a part of the text not being extracted.


## Exceptions

Exceptions need to be caught if you want to handle them. For example, you could
want to read the text from a PDF as a part of a search function.

Most PDF files don't follow the specifications. In this case pypdf needs to
Most PDF files do not follow the specification. In this case pypdf needs to
guess which kinds of mistakes were potentially done when the PDF file was created.
See [the robustness page](robustness.md) for the related issues.

As a users, you likely don't care about it. If it's readable in any way, you
As a user, you likely do not care about it. If it is readable in any way, you
want the text. You might use pdfminer.six as a fallback and do this:

```python
Expand Down Expand Up @@ -62,7 +62,7 @@ see all warnings. This is especially true for Continuous Integration (CI).

## Log messages

Log messages can be noisy in some cases. pypdf hopefully is having a reasonable
Log messages can be noisy in some cases. pypdf hopefully has a reasonable
level of log messages, but you can reduce which types of messages you want to
see:

Expand Down

0 comments on commit d9bf67f

Please sign in to comment.