|
1 | 1 | # Exceptions, Warnings, and Log messages |
2 | 2 |
|
3 | | -pypdf makes use of 3 mechanisms to show that something went wrong: |
| 3 | +pypdf makes use of three mechanisms to show if something went wrong: |
4 | 4 |
|
5 | | -* **Log messages** are informative messages that can be used for post-mortem |
6 | | - analysis. Most of the time, users can ignore them. They come in different |
7 | | - *levels*, such as info / warning / error indicating the severity. |
8 | | - Examples are non-standard compliant PDF files which pypdf can deal with or |
9 | | - a missing implementation that leads to a part of the text not being extracted. |
| 5 | +* **Exceptions** are error cases that pypdf users should explicitly handle. |
| 6 | + In the `strict=True` mode, most log messages with the warning level will |
| 7 | + become exceptions. This can be useful in applications where you can require |
| 8 | + a user to fix the broken PDF. |
10 | 9 | * **Warnings** are avoidable issues, such as using deprecated classes / |
11 | 10 | functions / parameters. Another example is missing capabilities of pypdf. |
12 | 11 | In those cases, pypdf users should adjust their code. Warnings |
13 | 12 | are issued by the `warnings` module - those are different from the log-level |
14 | 13 | "warning". |
15 | | -* **Exceptions** are error-cases that pypdf users should explicitly handle. |
16 | | - In the `strict=True` mode, most log messages with the warning level will |
17 | | - become exceptions. This can be useful in applications where you can require |
18 | | - a user to fix the broken PDF. |
| 14 | +* **Log messages** are informative messages that can be used for post-mortem |
| 15 | + analysis. Most of the time, users can ignore them. They come in different |
| 16 | + *levels*, such as info / warning / error indicating the severity. |
| 17 | + Examples are non-standard compliant PDF files which pypdf can deal with or |
| 18 | + a missing implementation that leads to a part of the text not being extracted. |
19 | 19 |
|
20 | 20 |
|
21 | 21 | ## Exceptions |
22 | 22 |
|
23 | 23 | Exceptions need to be caught if you want to handle them. For example, you could |
24 | 24 | want to read the text from a PDF as a part of a search function. |
25 | 25 |
|
26 | | -Most PDF files don't follow the specifications. In this case pypdf needs to |
| 26 | +Most PDF files do not follow the specification. In this case pypdf needs to |
27 | 27 | guess which kinds of mistakes were potentially done when the PDF file was created. |
28 | 28 | See [the robustness page](robustness.md) for the related issues. |
29 | 29 |
|
30 | | -As a users, you likely don't care about it. If it's readable in any way, you |
| 30 | +As a user, you likely do not care about it. If it is readable in any way, you |
31 | 31 | want the text. You might use pdfminer.six as a fallback and do this: |
32 | 32 |
|
33 | 33 | ```python |
@@ -62,7 +62,7 @@ see all warnings. This is especially true for Continuous Integration (CI). |
62 | 62 |
|
63 | 63 | ## Log messages |
64 | 64 |
|
65 | | -Log messages can be noisy in some cases. pypdf hopefully is having a reasonable |
| 65 | +Log messages can be noisy in some cases. pypdf hopefully has a reasonable |
66 | 66 | level of log messages, but you can reduce which types of messages you want to |
67 | 67 | see: |
68 | 68 |
|
|
0 commit comments