From 27200fbbc496751d8d73d558054536ce565c822a Mon Sep 17 00:00:00 2001 From: j-t-1 <120829237+j-t-1@users.noreply.github.com> Date: Tue, 5 Mar 2024 12:07:48 +0000 Subject: [PATCH 1/2] DOC: Minor improvements, including renaming pip to pip3 --- docs/dev/deprecations.md | 2 +- docs/dev/intro.md | 10 +++++----- docs/dev/releasing.md | 8 ++++---- docs/dev/testing.md | 6 +++--- docs/user/add-watermark.md | 4 ++-- docs/user/adding-pdf-annotations.md | 2 +- docs/user/installation.md | 14 +++++++------- docs/user/merging-pdfs.md | 4 ++-- docs/user/reading-pdf-annotations.md | 2 +- docs/user/streaming-data.md | 2 +- docs/user/viewer-preferences.md | 8 ++++---- 11 files changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/dev/deprecations.md b/docs/dev/deprecations.md index 63edccb48..422da83e8 100644 --- a/docs/dev/deprecations.md +++ b/docs/dev/deprecations.md @@ -4,7 +4,7 @@ pypdf strives to be an excellent library for its current users and for new ones. We are careful with introducing potentially breaking changes, but we will do them if they provide value for the community on the long run. -We hope and think that deprecations will not happen soon again. If they do, +We hope and think that deprecations will not happen frequently. If they do, users can rely on the following procedure. ## Semantic Versioning diff --git a/docs/dev/intro.md b/docs/dev/intro.md index 6765b4a44..8b84a8a00 100644 --- a/docs/dev/intro.md +++ b/docs/dev/intro.md @@ -35,7 +35,7 @@ Git is a command line application for version control. If you don't know it, you can [play ohmygit](https://ohmygit.org/) to learn it. GitHub is the service where the pypdf project is hosted. While git is free and -open source, GitHub is a paid service by Microsoft - but for free in lot of +open source, GitHub is a paid service by Microsoft, but free in a lot of cases. [pre-commit](https://pypi.org/project/pre-commit/) is a command line application @@ -47,7 +47,7 @@ you `git commit`. ## Commit Messages Having a clean commit message helps people to quickly understand what the commit -was about, without actually looking at the changes. The first line of the +is about, without actually looking at the changes. The first line of the commit message is used to [auto-generate the CHANGELOG](https://github.com/py-pdf/pypdf/blob/main/make_release.py). For this reason, the format should be: @@ -67,14 +67,14 @@ The `PREFIX` can be: A bug is always an issue for pypdf users - test code or CI that was fixed is not considered a bug here. * `ENH`: A new feature! Describe in the body what it can be used for. -* `DEP`: A deprecation - either marking something as "this is going to be removed" +* `DEP`: A deprecation. Either marking something as "this is going to be removed" or actually removing it. * `PI`: A performance improvement. This could also be a reduction in the file size of PDF files generated by pypdf. * `ROB`: A robustness change. Dealing better with broken PDF files. * `DOC`: A documentation change. -* `TST`: Adding / adjusting tests. -* `DEV`: Developer experience improvements - e.g. pre-commit or setting up CI +* `TST`: Adding or adjusting tests. +* `DEV`: Developer experience improvements, e.g. pre-commit or setting up CI. * `MAINT`: Quite a lot of different stuff. Performance improvements are for sure the most interesting changes in here. Refactorings as well. * `STY`: A style change. Something that makes pypdf code more consistent. diff --git a/docs/dev/releasing.md b/docs/dev/releasing.md index 0310b22db..4de1c14d6 100644 --- a/docs/dev/releasing.md +++ b/docs/dev/releasing.md @@ -13,7 +13,7 @@ A `pypdf` release contains the following artifacts: `pypdf` should typically only be released by one of the core maintainers / the core maintainer. At the moment, this is Martin Thoma. -Any owner of the py-pdf organization has also the technical permissions to +Any owner of the py-pdf organization also has the technical permissions to release. ## How is it done? @@ -21,10 +21,10 @@ release. The release contains the following steps: 1. Update the CHANGELOG.md and the _version.py via `python make_release.py`. - This also prepares the release commit message + This also prepares the release commit message. 2. Create a release commit: `git commit -eF RELEASE_COMMIT_MSG.md`. 3. Tag that commit: `git tag -s {{version}} -eF RELEASE_TAG_MSG.md`. -4. Push both: `git push && git push --tags` +4. Push both: `git push && git push --tags`. 5. CI now builds a source and a wheels package which it pushes to PyPI. It also creates a GitHub release. @@ -33,7 +33,7 @@ The release contains the following steps: ### The Release Tag * Use the release version as the tag name. No need for a leading "v". -* Use the changelog entry as the body +* Use the changelog entry as the body. ## When are releases done? diff --git a/docs/dev/testing.md b/docs/dev/testing.md index c07ef6440..1bf18b92f 100644 --- a/docs/dev/testing.md +++ b/docs/dev/testing.md @@ -5,11 +5,11 @@ pypdf uses [`pytest`](https://docs.pytest.org/en/7.1.x/) for testing. To run the tests you need to install the CI (Continuous Integration) requirements by running `pip install -r requirements/ci.txt` or `pip install -r requirements/ci-3.11.txt` if running Python ≥ 3.11. -## De-selecting groups of tests +## Deselecting groups of tests pypdf makes use of the following pytest markers: -* `slow`: Tests that require more than 5 seconds +* `slow`: Tests that require more than 5 seconds. * `samples`: Tests that require the [the `sample-files` git submodule](https://github.com/py-pdf/sample-files) to be initialized. As of October 2022, this is about 25 MB. * `enable_socket`: Tests that download PDF documents. They are stored locally and thus only need to be downloaded once. As of October 2022, this is about 200 MB. * To successfully run the tests, please download most of the documents beforehand: `python -c "from tests import download_test_pdfs; download_test_pdfs()"` @@ -73,5 +73,5 @@ b) you can then install the version using pip from git: Example: ``` -pip install git+https://github.com/pubpub-zz/pypdf.git@iss2200 +pip3 install git+https://github.com/pubpub-zz/pypdf.git@iss2200 ``` diff --git a/docs/user/add-watermark.md b/docs/user/add-watermark.md index f8be962ff..2491fad7f 100644 --- a/docs/user/add-watermark.md +++ b/docs/user/add-watermark.md @@ -1,4 +1,4 @@ -# Adding a Stamp/Watermark to a PDF +# Adding a Stamp or Watermark to a PDF Adding stamps or watermarks are two common ways to manipulate PDF files. A stamp is adding something on top of the document, a watermark is in the @@ -21,7 +21,7 @@ for page in writer.pages: writer.write("out.pdf") ``` -Else use `merge_transformed_page()` with `Transformation()` if you need to translate, rotate, scale, etc. the stamp before merging it to the content page. +Otherwise use `merge_transformed_page()` with `Transformation()` if you need to translate, rotate, scale, etc. the stamp before merging it to the content page. ```python from pathlib import Path diff --git a/docs/user/adding-pdf-annotations.md b/docs/user/adding-pdf-annotations.md index d075d83e1..a8a93256b 100644 --- a/docs/user/adding-pdf-annotations.md +++ b/docs/user/adding-pdf-annotations.md @@ -304,7 +304,7 @@ with open("annotated-pdf.pdf", "wb") as fp: Text markup annotations refer to a specific piece of text within the document. Those are a bit more complicated as you need to know exactly where the text -is. Those are the "Quad points". +is, the so-called the "Quad points". ### Highlighting diff --git a/docs/user/installation.md b/docs/user/installation.md index d50578743..1536d0c21 100644 --- a/docs/user/installation.md +++ b/docs/user/installation.md @@ -6,18 +6,18 @@ There are several ways to install pypdf. The most common option is to use pip. pypdf requires Python 3.7+ to run. -Typically Python comes with `pip`, a package installer. Using it you can +Typically Python comes with `pip3`, a package installer. Using it you can install pypdf: ```bash -pip install pypdf +pip3 install pypdf ``` If you are not a super-user (a system administrator / root), you can also just install pypdf for your current user: ```bash -pip install --user pypdf +pip3 install --user pypdf ``` ### Optional dependencies @@ -29,7 +29,7 @@ case for cryptography and image formats. If you simply want to install all optional dependencies, run: ``` -pip install pypdf[full] +pip3 install pypdf[full] ``` Alternatively, you can install just some: @@ -39,13 +39,13 @@ will need to install some extra dependencies. Encryption using RC4 is supported using the regular installation. ``` -pip install pypdf[crypto] +pip3 install pypdf[crypto] ``` If you plan to use image extraction, you need Pillow: ``` -pip install pypdf[image] +pip3 install pypdf[image] ``` ## Python Version Support @@ -69,5 +69,5 @@ Anaconda users can [install pypdf via conda-forge](https://anaconda.org/conda-fo In case you want to use the current version under development: ```bash -pip install git+https://github.com/py-pdf/pypdf.git +pip3 install git+https://github.com/py-pdf/pypdf.git ``` diff --git a/docs/user/merging-pdfs.md b/docs/user/merging-pdfs.md index ca01fa985..a0f4314da 100644 --- a/docs/user/merging-pdfs.md +++ b/docs/user/merging-pdfs.md @@ -63,7 +63,7 @@ writer.append(reader, "page 1 and 10", [0, 9]) During merging, the relevant named destination will also imported. -If you want to insert pages in the middle of the destination, use `merge` (which provides (insertion) position). +If you want to insert pages in the middle of the destination, use `merge` (which provides an insertion position). You can insert the same page multiple times, if necessary even using a list-based syntax: ```python @@ -126,7 +126,7 @@ Please note that if you clone an object, you will clone all the objects below as including the objects pointed by *IndirectObject*. Due to this, if you clone a page that includes some articles (`"/B"`), not only the first article, but also all the chained articles and the pages where those articles can be read will be copied. -It means that you may copy lots of objects which will be saved in the output PDF as well. +This means that you may copy lots of objects which will be saved in the output PDF as well. In order to prevent this, you can provide the list of fields in the dictionaries to be ignored: diff --git a/docs/user/reading-pdf-annotations.md b/docs/user/reading-pdf-annotations.md index 959dbe8a0..4aec76828 100644 --- a/docs/user/reading-pdf-annotations.md +++ b/docs/user/reading-pdf-annotations.md @@ -31,7 +31,7 @@ for page in reader.pages: print(annotation) ``` -Reading the most common ones is described here. +Examples of reading three of the most common annotations: ## Text diff --git a/docs/user/streaming-data.md b/docs/user/streaming-data.md index 8c9ac3a8c..9a0032f08 100644 --- a/docs/user/streaming-data.md +++ b/docs/user/streaming-data.md @@ -3,7 +3,7 @@ In some cases you might want to avoid saving things explicitly as a file to disk, e.g. when you want to store the PDF in a database or AWS S3. -pypdf supports streaming data to a file-like object and here is how. +pypdf supports streaming data to a file-like object: ```python from io import BytesIO diff --git a/docs/user/viewer-preferences.md b/docs/user/viewer-preferences.md index 01fd8ad5c..bda3970ab 100644 --- a/docs/user/viewer-preferences.md +++ b/docs/user/viewer-preferences.md @@ -1,6 +1,6 @@ # Adding Viewer Preferences -It is possible to set viewer preferences of the PDF file. +It is possible to set viewer preferences of a PDF file. These properties are described in Section 12.2 of the [PDF 1.7 specification](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf). Note that the `/ViewerPreferences` dictionary does not exist by default. @@ -8,7 +8,7 @@ If it's not already present, it must be created by calling the `create_viewer_pr of the `PdfWriter` object. If viewer preferences exist in a PDF file being read with `PdfReader`, -you can access them as properties of the `viewer_preferences` properties. +you can access them as properties of `viewer_preferences`. Otherwise, the `viewer_preferences` property will be set to `None`. ## Example @@ -78,6 +78,6 @@ with open("output.pdf", "wb") as output_stream: writer.write(output_stream) ``` -(The names beginning with a slash character are part of the PDF file format. They are +The names beginning with a slash character are part of the PDF file format. They are included here to aid to anyone searching pypdf documentation -for these names from the PDF specification.) +for these names from the PDF specification. From 87b3728e823b9707fb9c84213b30e1c2d72c9d34 Mon Sep 17 00:00:00 2001 From: j-t-1 <120829237+j-t-1@users.noreply.github.com> Date: Tue, 5 Mar 2024 13:37:37 +0000 Subject: [PATCH 2/2] DOC: Minor improvements --- docs/dev/testing.md | 2 +- docs/user/adding-pdf-annotations.md | 2 +- docs/user/installation.md | 14 +++++++------- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/dev/testing.md b/docs/dev/testing.md index 1bf18b92f..99e5e3cc0 100644 --- a/docs/dev/testing.md +++ b/docs/dev/testing.md @@ -73,5 +73,5 @@ b) you can then install the version using pip from git: Example: ``` -pip3 install git+https://github.com/pubpub-zz/pypdf.git@iss2200 +pip install git+https://github.com/pubpub-zz/pypdf.git@iss2200 ``` diff --git a/docs/user/adding-pdf-annotations.md b/docs/user/adding-pdf-annotations.md index a8a93256b..b22e735d1 100644 --- a/docs/user/adding-pdf-annotations.md +++ b/docs/user/adding-pdf-annotations.md @@ -304,7 +304,7 @@ with open("annotated-pdf.pdf", "wb") as fp: Text markup annotations refer to a specific piece of text within the document. Those are a bit more complicated as you need to know exactly where the text -is, the so-called the "Quad points". +is, the so-called "Quad points". ### Highlighting diff --git a/docs/user/installation.md b/docs/user/installation.md index 1536d0c21..d50578743 100644 --- a/docs/user/installation.md +++ b/docs/user/installation.md @@ -6,18 +6,18 @@ There are several ways to install pypdf. The most common option is to use pip. pypdf requires Python 3.7+ to run. -Typically Python comes with `pip3`, a package installer. Using it you can +Typically Python comes with `pip`, a package installer. Using it you can install pypdf: ```bash -pip3 install pypdf +pip install pypdf ``` If you are not a super-user (a system administrator / root), you can also just install pypdf for your current user: ```bash -pip3 install --user pypdf +pip install --user pypdf ``` ### Optional dependencies @@ -29,7 +29,7 @@ case for cryptography and image formats. If you simply want to install all optional dependencies, run: ``` -pip3 install pypdf[full] +pip install pypdf[full] ``` Alternatively, you can install just some: @@ -39,13 +39,13 @@ will need to install some extra dependencies. Encryption using RC4 is supported using the regular installation. ``` -pip3 install pypdf[crypto] +pip install pypdf[crypto] ``` If you plan to use image extraction, you need Pillow: ``` -pip3 install pypdf[image] +pip install pypdf[image] ``` ## Python Version Support @@ -69,5 +69,5 @@ Anaconda users can [install pypdf via conda-forge](https://anaconda.org/conda-fo In case you want to use the current version under development: ```bash -pip3 install git+https://github.com/py-pdf/pypdf.git +pip install git+https://github.com/py-pdf/pypdf.git ```