Merge branch 'main' into issue-64

Author: MartinThoma

.github/scripts/check_pr_title.py

@@ -0,0 +1,36 @@
+"""Check that all PR titles follow the desired scheme."""
+
+import os
+import sys
+
+KNOWN_PREFIXES = (
+    "SEC: ",
+    "BUG: ",
+    "ENH: ",
+    "DEP: ",
+    "PI: ",
+    "ROB: ",
+    "DOC: ",
+    "TST: ",
+    "DEV: ",
+    "STY: ",
+    "MAINT: ",
+    "REL: ",
+)
+PR_TITLE = os.getenv("PR_TITLE", "")
+
+if (
+    not PR_TITLE.startswith(KNOWN_PREFIXES)
+    or not PR_TITLE.split(": ", maxsplit=1)[1]
+):
+    sys.stderr.write(
+        f"The PR title '{PR_TITLE}' does not follow the projects naming scheme: "
+        "https://pdfly.readthedocs.io/en/latest/dev/intro.html#commit-messages\n",
+    )
+    sys.stderr.write(
+        "If you do not know which one to choose or if multiple apply, make a best guess. "
+        "Nobody will complain if it does not quite fit :-)\n",
+    )
+    sys.exit(1)
+else:
+    sys.stdout.write(f"PR title '{PR_TITLE}' appears to be valid.\n")

.github/workflows/check-gitignored-files.yml

@@ -0,0 +1,30 @@
+name: Check for Gitignored Files
+
+on:
+  push:
+    branches:
+      - '**' # Run on all branches
+  pull_request:
+
+jobs:
+  check-gitignored-files:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Check for gitignored files in commit
+        run: |
+          # List all files in the commit
+          git diff --name-only --cached > committed_files.txt
+
+          # Check if any of the committed files are ignored by .gitignore
+          git check-ignore -v $(cat committed_files.txt) > ignored_files.txt || true
+
+          # Fail if there are any ignored files
+          if [[ -s ignored_files.txt ]]; then
+            echo "The following files are gitignored but committed:"
+            cat ignored_files.txt
+            exit 1
+          fi

.github/workflows/github-ci.yaml

@@ -22,7 +22,7 @@ jobs:
     runs-on: ubuntu-20.04
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
     - name: Checkout Code
@@ -73,7 +73,7 @@ jobs:
     - name: Test with ruff
       run: |
         echo `ruff --version`
-        ruff pdfly/
+        ruff check pdfly/
 
   package:
     name: Build & verify package

.github/workflows/title-check.yml

@@ -0,0 +1,20 @@
+name: 'PR Title Check'
+on:
+  pull_request:
+    # check when PR
+    # * is created,
+    # * title is edited, and
+    # * new commits are added (to ensure failing title blocks merging)
+    types: [opened, reopened, edited, synchronize]
+
+jobs:
+  title-check:
+    name: Title check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+      - name: Check PR title
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: python .github/scripts/check_pr_title.py

.gitignore

@@ -114,6 +114,9 @@ venv.bak/
 .spyderproject
 .spyproject
 
+# IntelliJ
+.idea
+
 # Rope project settings
 .ropeproject
 

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 # pre-commit run --all-files
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v5.0.0
     hooks:
     -   id: check-ast
     -   id: check-byte-order-marker
@@ -18,34 +18,34 @@ repos:
     -   id: check-added-large-files
         args: ['--maxkb=1000']
 -   repo: https://github.com/psf/black
-    rev: 23.12.0
+    rev: 24.10.0
     hooks:
     -   id: black
         args: [--target-version, py36]
 -   repo: https://github.com/asottile/blacken-docs
-    rev: 1.16.0
+    rev: 1.19.1
     hooks:
     -   id: blacken-docs
         additional_dependencies: [black==22.1.0]
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.8
+    rev: v0.7.4
     hooks:
     -   id: ruff
         args: ['--fix']
         exclude: "tests/"
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.15.0
+    rev: v3.19.0
     hooks:
     -   id: pyupgrade
         args: [--py36-plus]
 -   repo: https://github.com/pycqa/flake8
-    rev: 6.1.0
+    rev: 7.1.1
     hooks:
     -   id: flake8
         args: ["--ignore", "E,W,F"]
 
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 'v1.7.1'
+    rev: 'v1.13.0'
     hooks:
       - id: mypy
         files: ^pdfly/.*

.readthedocs.yaml

@@ -5,7 +5,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

CHANGELOG.md

@@ -1,11 +1,28 @@
 # CHANGELOG
 
+## Version 0.4.0, 2024-12-08
+
+### New Features (ENH)
+- New `booklet` command to adjust offsets and lengths ([PR #77](https://github.com/py-pdf/pdfly/pull/77))
+- New `uncompress` command ([PR #75](https://github.com/py-pdf/pdfly/pull/75))
+- New `update-offsets` command to adjust offsets and lengths ([PR #15](https://github.com/py-pdf/pdfly/pull/15))
+- New `rm` command ([PR #59](https://github.com/py-pdf/pdfly/pull/59))
+- `metadata`: now also displaying CreationDate, Creator, Keywords & Subject ([PR #73](https://github.com/py-pdf/pdfly/pull/73))
+- Add warning for out-of-bounds page range in pdfly `cat` command ([PR #58](https://github.com/py-pdf/pdfly/pull/58))
+
+### Bug Fixes (BUG)
+- `2-up` command, that only showed one page per sheet, on the left side, with blank space on the right ([PR #78](https://github.com/py-pdf/pdfly/pull/78))
+
+[Full Changelog](https://github.com/py-pdf/pdfly/compare/0.3.3...0.4.0)
+
+
 ## Version 0.3.3, 2024-04-14
 
 ### Developer Experience (DEV)
 -  Chain workflows
 
-[Full Changelog](https://github.com/py-pdf/pdfly/compare/0.3.1...0.3.2)
+[Full Changelog](https://github.com/py-pdf/pdfly/compare/0.3.2...0.3.3)
+
 
 ## Version 0.3.2, 2024-04-14
 

Makefile

@@ -15,10 +15,10 @@ upload:
 clean:
 	python setup.py clean --all
 	pyclean .
-	rm -rf Tests/__pycache__ pypdf/__pycache__ Image9.png htmlcov docs/_build dist dont_commit_merged.pdf dont_commit_writer.pdf pypdf.egg-info pypdf_pdfLocation.txt
+	rm -rf tests/__pycache__ pdfly/__pycache__ Image9.png htmlcov docs/_build dist dont_commit_merged.pdf dont_commit_writer.pdf pdfly.egg-info
 
 test:
-	pytest Tests --cov --cov-report term-missing -vv --cov-report html --durations=3 --timeout=30
+	pytest tests --cov --cov-report term-missing -vv --cov-report html --durations=3 --timeout=30
 
 mutation-test:
 	mutmut run

README.md

@@ -34,10 +34,13 @@ $ pdfly --help
 │ 2-up             Create a booklet-style PDF from a single input.            │
 │ cat              Concatenate pages from PDF files into a single PDF file.   │
 │ compress         Compress a PDF.                                            │
+| uncompress       Uncompresses a PDF.                                        │
 │ extract-images   Extract images from PDF without resampling or altering.    │
 │ extract-text     Extract text from a PDF file.                              │
 │ meta             Show metadata of a PDF file                                │
 │ pagemeta         Give details about a single page.                          │
+│ rm               Remove pages from PDF files.                               │
+│ update-offsets   Updates offsets and lengths in a simple PDF file.          │
 │ x2pdf            Convert one or more files to PDF. Each file is a page.     │
 ╰─────────────────────────────────────────────────────────────────────────────╯
 ```

docs/conf.py

@@ -5,6 +5,7 @@
 For a full list see the documentation:
 https://www.sphinx-doc.org/en/master/usage/configuration.html
 """
+
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,

docs/dev/intro.md

@@ -0,0 +1,79 @@
+# Developer Intro
+
+pdfly is an application and thus non-developers
+might also use it.
+
+## Installing Requirements
+
+```
+pip install -r requirements/dev.txt
+```
+
+## Running Tests
+
+See [testing pdfly with pytest](testing.md)
+
+## Tools: git and pre-commit
+
+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 pdfly project is hosted. While git is free and
+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
+that uses git hooks to automatically execute code. This allows you to avoid
+style issues and other code quality issues. After you entered `pre-commit install`
+once in your local copy of pdfly, it will automatically be executed when
+you `git commit`.
+
+## Commit Messages
+
+Having a clean commit message helps people to quickly understand what the commit
+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/pdfly/blob/main/make_release.py).
+For this reason, the format should be:
+
+```
+PREFIX: DESCRIPTION
+
+BODY
+```
+
+The `PREFIX` can be:
+
+* `SEC`: Security improvements. Typically an infinite loop that was possible.
+* `BUG`: A bug was fixed. Likely there is one or multiple issues. Then write in
+   the `BODY`: `Closes #123` where 123 is the issue number on GitHub.
+   It would be absolutely amazing if you could write a regression test in those
+   cases. That is a test that would fail without the fix.
+   A bug is always an issue for pdfly 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"
+   or actually removing it.
+* `PI`: A performance improvement. This could also be a reduction in the
+        file size of PDF files generated by pdfly.
+* `ROB`: A robustness change. Dealing better with broken PDF files.
+* `DOC`: A documentation change.
+* `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 pdfly code more consistent.
+         Typically a small change. It could also be better error messages for
+         end users.
+
+The prefix is used to generate the CHANGELOG. Every PR must have exactly one -
+if you feel like several match, take the top one from this list that matches for
+your PR.
+
+## Pull Request Size
+
+Smaller Pull Requests (PRs) are preferred as it's typically easier to merge
+them. For example, if you have some typos, a few code-style changes, a new
+feature, and a bug-fix, that could be 3 or 4 PRs.
+
+A PR must be complete. That means if you introduce a new feature it must be
+finished within the PR and have a test for that feature.

docs/dev/testing.md

@@ -0,0 +1,5 @@
+# Testing
+
+pdfly uses [`pytest`](https://docs.pytest.org/en/latest/) for testing.
+
+To run the tests you need to install the CI (Continuous Integration) requirements by running `pip install -r requirements/ci.txt`.

docs/index.rst

@@ -19,7 +19,14 @@ pdfly is a command line tool to get informaiton about PDF documents and to manip
 
 
 .. toctree::
-   :caption: About pypdf
+   :caption: Developer Guide
+   :maxdepth: 1
+
+   dev/intro
+   dev/testing
+
+.. toctree::
+   :caption: About pdfly
    :maxdepth: 1
 
    meta/CHANGELOG

docs/user/installation.md

@@ -7,14 +7,14 @@ There are several ways to install pdfly. The most common option is to use pip.
 pdfly requires Python 3.6+ to run.
 
 Typically Python comes with `pip`, a package installer. Using it you can
-install pypdf:
+install pdfly:
 
 ```bash
 pip install pdfly
 ```
 
 If you are not a super-user (a system administrator / root), you can also just
-install pypdf for your current user:
+install pdfly for your current user:
 
 ```bash
 pip install --user pdfly