feat: Add support for BrotliDecode filter (PDF 2.0)

Implements the BrotliDecode filter as specified in ISO 32000-2:2020,
Section 7.4.11. Adds necessary constants, integrates the filter into
the decoding logic, includes brotli as an optional dependency, adds
unit tests, and updates documentation.

Closes #3223

Author: ash01ish

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## Unreleased
+
+### New Features (ENH)
+- Add support for BrotliDecode filter (PDF 2.0) (#3223)
+
 ## Version 5.4.0, 2025-03-16
 
 ### New Features (ENH)
@@ -1680,7 +1685,7 @@ e.g. Russian / Chinese / Japanese / Korean / Arabic.
 ### Documentation (DOC)
 -  Notes on annotations (#982)
 -  Who uses PyPDF2
--  intendet \xe2\x9e\x94 in robustness page  (#958)
+-  inteted \xe2\x9e\x94 in robustness page  (#958)
 
 ### Maintenance (MAINT)
 -  pre-commit / requirements.txt updates (#977)

docs/modules/constants.rst

@@ -1,6 +1,11 @@
 Constants
 ---------
 
+.. autoclass:: pypdf.constants.StrEnum
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 .. autoclass:: pypdf.constants.AnnotationFlag
     :members:
     :undoc-members:
@@ -26,3 +31,13 @@ Constants
        :undoc-members:
        :exclude-members: FT, Parent, Kids, T, TU, TM, V, DV, AA, Opt, attributes, attributes_dict
        :show-inheritance:
+
+.. autoclass:: pypdf.constants.FilterTypes
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pypdf.constants.FilterTypeAbbreviations
+    :members:
+    :undoc-members:
+    :show-inheritance:

pypdf/constants.py

@@ -245,6 +245,7 @@ class FilterTypes(StrEnum):
     CCITT_FAX_DECODE = "/CCITTFaxDecode"  # abbreviation: CCF
     DCT_DECODE = "/DCTDecode"  # abbreviation: DCT
     JPX_DECODE = "/JPXDecode"
+    BROTLI_DECODE = "/BrotliDecode" # abbreviation: Br, PDF 2.0
 
 
 class FilterTypeAbbreviations:
@@ -257,6 +258,7 @@ class FilterTypeAbbreviations:
     RL = "/RL"
     CCF = "/CCF"
     DCT = "/DCT"
+    BR = "/Br" # BrotliDecode
 
 
 class LzwFilterParameters:

pypdf/filters.py

@@ -65,6 +65,11 @@
     NullObject,
 )
 
+try:
+    import brotli
+except ImportError:
+    brotli = None
+
 
 def decompress(data: bytes) -> bytes:
     """
@@ -481,6 +486,50 @@ def decode(
         return data
 
 
+class BrotliDecode:
+    """Decodes Brotli-compressed data."""
+    @staticmethod
+    def decode(
+        data: bytes,
+        decode_parms: Optional[DictionaryObject] = None,
+        **kwargs: Any,
+    ) -> bytes:
+        """
+        Decode Brotli-compressed data.
+
+        Args:
+            data: Brotli-compressed data.
+            decode_parms: Optional parameters (unused).
+
+        Returns:
+            Decompressed data.
+
+        Raises:
+            PdfStreamError: If brotli library is not installed.
+        """
+        if brotli is None:
+            raise PdfStreamError("Brotli library not installed. Required for BrotliDecode filter.")
+        return brotli.decompress(data)
+
+    @staticmethod
+    def encode(data: bytes, **kwargs: Any) -> bytes:
+        """
+        Encode data using Brotli compression.
+
+        Args:
+            data: Data to compress.
+
+        Returns:
+            Compressed data.
+
+        Raises:
+            PdfStreamError: If brotli library is not installed.
+        """
+        if brotli is None:
+            raise PdfStreamError("Brotli library not installed. Required for BrotliDecode filter.")
+        return brotli.compress(data)
+
+
 @dataclass
 class CCITTParameters:
     """§7.4.6, optional parameters for the CCITTFaxDecode filter."""
@@ -666,6 +715,8 @@ def decode_stream_data(stream: Any) -> bytes:
             data = DCTDecode.decode(data)
         elif filter_name == FT.JPX_DECODE:
             data = JPXDecode.decode(data)
+        elif filter_name == FT.BROTLI_DECODE: # Add BrotliDecode
+            data = BrotliDecode.decode(data)
         elif filter_name == "/Crypt":
             if "/Name" in params or "/Type" in params:
                 raise NotImplementedError(

pyproject.toml

@@ -42,9 +42,11 @@ Source = "https://github.com/py-pdf/pypdf"
 crypto = ["cryptography"]
 cryptodome = ["PyCryptodome"]
 image = ["Pillow>=8.0.0"]
+brotli = ["Brotli"] # Add brotli dependency
 full = [
     "cryptography",
-    "Pillow>=8.0.0"
+    "Pillow>=8.0.0",
+    "Brotli", # Add brotli to full dependencies
 ]
 dev = [
     "black",

requirements/ci-3.11.txt

@@ -4,6 +4,8 @@
 #
 #    pip-compile --output-file=requirements/ci-3.11.txt requirements/ci.in
 #
+brotli==1.1.0
+    # via -r requirements/ci.in
 cffi==1.17.1
     # via cryptography
 coverage[toml]==7.6.4
@@ -36,6 +38,13 @@ pillow==11.0.0
     #   fpdf2
 pluggy==1.5.0
     # via pytest
+ruff==0.11.0
+    # via -r requirements/ci.in
+tomli==2.0.2
+    # via
+    #   coverage
+    #   mypy
+    #   pytest
 py-cpuinfo==9.0.0
     # via pytest-benchmark
 pycparser==2.22
@@ -60,13 +69,6 @@ pytest-xdist==3.6.1
     # via -r requirements/ci.in
 pyyaml==6.0.2
     # via -r requirements/ci.in
-ruff==0.11.0
-    # via -r requirements/ci.in
-tomli==2.0.2
-    # via
-    #   coverage
-    #   mypy
-    #   pytest
 typeguard==4.3.0
     # via -r requirements/ci.in
 types-pillow==10.2.0.20240822

requirements/ci.in

@@ -13,3 +13,4 @@ pytest-cov
 typeguard
 types-Pillow
 pyyaml
+brotli

requirements/ci.txt

@@ -1,9 +1,11 @@
 #
-# This file is autogenerated by pip-compile with Python 3.8
+# This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
-#    pip-compile requirements/ci.in
+#    pip-compile --output-file=requirements/ci.txt requirements/ci.in
 #
+brotli==1.1.0
+    # via -r requirements/ci.in
 cffi==1.17.1
     # via cryptography
 coverage[toml]==7.6.1
@@ -14,16 +16,12 @@ cryptography==44.0.1
     # via -r requirements/ci.in
 defusedxml==0.7.1
     # via fpdf2
-exceptiongroup==1.2.2
-    # via pytest
 execnet==2.1.1
     # via pytest-xdist
 fonttools==4.54.1
     # via fpdf2
 fpdf2==2.8.1
     # via -r requirements/ci.in
-importlib-metadata==8.5.0
-    # via typeguard
 iniconfig==2.0.0
     # via pytest
 mypy==1.13.0
@@ -62,11 +60,6 @@ pytest-xdist==3.6.1
     # via -r requirements/ci.in
 pyyaml==6.0.2
     # via -r requirements/ci.in
-tomli==2.0.2
-    # via
-    #   coverage
-    #   mypy
-    #   pytest
 typeguard==4.3.0
     # via -r requirements/ci.in
 types-pillow==10.2.0.20240822
@@ -75,5 +68,3 @@ typing-extensions==4.12.2
     # via
     #   mypy
     #   typeguard
-zipp==3.20.2
-    # via importlib-metadata

requirements/dev.in

@@ -4,3 +4,4 @@ pre-commit
 pytest-cov
 flit
 wheel
+brotli

requirements/dev.txt

@@ -1,9 +1,11 @@
 #
-# This file is autogenerated by pip-compile with Python 3.8
+# This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
-#    pip-compile requirements/dev.in
+#    pip-compile --output-file=requirements/dev.txt requirements/dev.in
 #
+brotli==1.1.0
+    # via -r requirements/dev.in
 build==1.2.2.post1
     # via pip-tools
 certifi==2024.8.30
@@ -20,8 +22,6 @@ distlib==0.3.9
     # via virtualenv
 docutils==0.20.1
     # via flit
-exceptiongroup==1.2.2
-    # via pytest
 filelock==3.16.1
     # via virtualenv
 flit==3.9.0
@@ -32,8 +32,6 @@ identify==2.6.1
     # via pre-commit
 idna==3.10
     # via requests
-importlib-metadata==8.5.0
-    # via build
 iniconfig==2.0.0
     # via pytest
 nodeenv==1.9.1
@@ -64,12 +62,6 @@ pyyaml==6.0.2
     # via pre-commit
 requests==2.32.3
     # via flit
-tomli==2.0.2
-    # via
-    #   build
-    #   coverage
-    #   pip-tools
-    #   pytest
 tomli-w==1.0.0
     # via flit
 urllib3==2.2.3
@@ -80,8 +72,6 @@ wheel==0.44.0
     # via
     #   -r requirements/dev.in
     #   pip-tools
-zipp==3.20.2
-    # via importlib-metadata
 
 # The following packages are considered to be unsafe in a requirements file:
 # pip

tests/test_filters.py

@@ -7,6 +7,7 @@
 from itertools import product as cartesian_product
 from pathlib import Path
 
+import brotli  # noqa: F401
 import pytest
 from PIL import Image, ImageOps
 
@@ -15,6 +16,7 @@
 from pypdf.filters import (
     ASCII85Decode,
     ASCIIHexDecode,
+    BrotliDecode,  # Add BrotliDecode
     CCITParameters,
     CCITTFaxDecode,
     CCITTParameters,
@@ -52,6 +54,29 @@ def test_flate_decode_encode(predictor, s):
     assert codec.decode(encoded, DictionaryObject({"/Predictor": predictor})) == s
 
 
+@pytest.mark.parametrize("s", filter_inputs)
+def test_brotli_decode_encode(s):
+    """BrotliDecode encode() and decode() methods work as expected."""
+    codec = BrotliDecode()
+    s_bytes = s.encode()
+    encoded = codec.encode(s_bytes)
+    assert encoded != s_bytes  # Ensure encoding actually happened
+    decoded = codec.decode(encoded)
+    assert decoded == s_bytes
+
+
+def test_brotli_decode_without_brotli_installed(monkeypatch):
+    """Verify BrotliDecode raises PdfReadError if brotli is not installed."""
+    # Simulate brotli not being installed within the filters module
+    monkeypatch.setattr("pypdf.filters.brotli", None)
+
+    codec = BrotliDecode()
+    with pytest.raises(PdfReadError) as exc_info:
+        codec.decode(b"test data")
+
+    assert "Brotli library not installed. Required for BrotliDecode filter." in str(exc_info.value)
+
+
 def test_flatedecode_unsupported_predictor():
     """
     FlateDecode raises PdfReadError for unsupported predictors.