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 py-pdf#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/dev.in

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

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.