feat: add pdf_to_title and pdf_to_metadata functions for enhanced PDF metadata extraction

Author: thorwhalen

pdfdol/__init__.py

@@ -5,7 +5,7 @@
 >>> folder_path = get_test_pdf_folder()
 >>> s = PdfFilesReader(folder_path)
 >>> sorted(s)
-['sample_pdf_1', 'sample_pdf_2']
+['sample_pdf_1', 'sample_pdf_2', 'sample_with_title']
 >>> assert s['sample_pdf_2'] == [
 ...     'Page 1\nThis is a sample text for testing Python PDF tools.'
 ... ]
@@ -24,4 +24,5 @@
 from pdfdol.util import concat_pdfs  # concatenate pdfs
 from pdfdol.tools import (
     get_pdf,  # Convert the given source to a PDF (bytes) and process it using the specified egress.
+    pdf_to_title,  # Extract the title from a PDF file's metadata.
 )

pdfdol/tests/data/some_pdfs/sample_with_title.pdf

@@ -1,5 +1,7 @@
 """Test the base.py module"""
 
+from pathlib import Path
+from pypdf import PdfReader
 from pdfdol.base import PdfFilesReader
 from pdfdol.tests.utils_for_testing import get_test_pdf_folder
 
@@ -8,7 +10,90 @@ def test_pdf_files_reader():
     test_pdf_folder = get_test_pdf_folder()
     s = PdfFilesReader(str(test_pdf_folder))
 
-    assert sorted(s) == ["sample_pdf_1", "sample_pdf_2"]
+    assert sorted(s) == ["sample_pdf_1", "sample_pdf_2", "sample_with_title"]
     assert s["sample_pdf_2"] == [
         "Page 1\nThis is a sample text for testing Python PDF tools."
     ]
+
+
+def test_pdf_to_title_with_filepath():
+    """Test pdf_to_title with a file path"""
+    from pdfdol.tools import pdf_to_title
+
+    test_pdf_folder = get_test_pdf_folder()
+    pdf_path = Path(test_pdf_folder) / "sample_with_title.pdf"
+
+    title = pdf_to_title(str(pdf_path))
+    assert title == "Sample PDF with Title"
+
+
+def test_pdf_to_title_with_bytes():
+    """Test pdf_to_title with PDF bytes"""
+    from pdfdol.tools import pdf_to_title
+
+    test_pdf_folder = get_test_pdf_folder()
+    pdf_path = Path(test_pdf_folder) / "sample_with_title.pdf"
+    pdf_bytes = pdf_path.read_bytes()
+
+    title = pdf_to_title(pdf_bytes)
+    assert title == "Sample PDF with Title"
+
+
+def test_pdf_to_title_with_pdf_reader():
+    """Test pdf_to_title with a PdfReader object"""
+    from pdfdol.tools import pdf_to_title
+
+    test_pdf_folder = get_test_pdf_folder()
+    pdf_path = Path(test_pdf_folder) / "sample_with_title.pdf"
+    reader = PdfReader(str(pdf_path))
+
+    title = pdf_to_title(reader)
+    assert title == "Sample PDF with Title"
+
+
+def test_pdf_to_title_no_title():
+    """Test pdf_to_title when PDF has no title metadata"""
+    from pdfdol.tools import pdf_to_title
+
+    test_pdf_folder = get_test_pdf_folder()
+    pdf_path = Path(test_pdf_folder) / "sample_pdf_1.pdf"
+
+    title = pdf_to_title(str(pdf_path))
+    assert title is None
+
+
+def test_pdf_to_title_nonexistent_file():
+    """Test pdf_to_title with non-existent file"""
+    from pdfdol.tools import pdf_to_title
+
+    title = pdf_to_title("/nonexistent/path/to/file.pdf")
+    assert title is None
+
+
+def test_pdf_to_metadata():
+    """Test pdf_to_metadata function"""
+    from pdfdol.tools import pdf_to_metadata
+
+    test_pdf_folder = get_test_pdf_folder()
+    pdf_path = Path(test_pdf_folder) / "sample_with_title.pdf"
+
+    # Test with filepath
+    metadata = pdf_to_metadata(str(pdf_path))
+    assert metadata['Title'] == "Sample PDF with Title"
+    assert metadata['Author'] == "Test Author"
+    assert metadata['Subject'] == "Testing PDF metadata extraction"
+
+    # Test with bytes
+    pdf_bytes = pdf_path.read_bytes()
+    metadata = pdf_to_metadata(pdf_bytes)
+    assert metadata['Title'] == "Sample PDF with Title"
+
+    # Test with PdfReader
+    reader = PdfReader(str(pdf_path))
+    metadata = pdf_to_metadata(reader)
+    assert metadata['Title'] == "Sample PDF with Title"
+
+    # Test with PDF without metadata
+    pdf_path_no_meta = Path(test_pdf_folder) / "sample_pdf_1.pdf"
+    metadata = pdf_to_metadata(str(pdf_path_no_meta))
+    assert isinstance(metadata, dict)  # Should return empty dict, not None

pdfdol/tests/test_base.py

@@ -8,6 +8,7 @@
 
 import markdown
 import pdfkit
+import pypdf
 
 from dol import Pipe
 
@@ -351,3 +352,140 @@ def _image_to_pdf_bytes(src_item):
     # Resolve the egress processing function and apply it.
     egress_func = _resolve_bytes_egress(egress)
     return egress_func(pdf_bytes)
+
+
+# ---------------------------------------------------------------------------------
+# PDF metadata extraction
+
+from typing import Union
+
+
+def _resolve_pdf_src_to_reader(
+    pdf_src: Union[str, bytes, pypdf.PdfReader],
+) -> pypdf.PdfReader:
+    """
+    Convert various PDF source types to a PdfReader object.
+
+    Args:
+        pdf_src: Can be a file path (str), PDF bytes, or a PdfReader object
+
+    Returns:
+        pypdf.PdfReader: A PdfReader object
+
+    Raises:
+        ValueError: If pdf_src type is not supported or file doesn't exist
+
+    Examples:
+        >>> import tempfile
+        >>> from pypdf import PdfWriter
+        >>> # Create a temp PDF
+        >>> writer = PdfWriter()
+        >>> _ = writer.add_blank_page(width=200, height=200)
+        >>> with tempfile.NamedTemporaryFile(suffix='.pdf', delete=False) as tmp:  # doctest: +ELLIPSIS
+        ...     _ = writer.write(tmp)
+        ...     tmp_path = tmp.name
+        >>> # Test with filepath
+        >>> reader = _resolve_pdf_src_to_reader(tmp_path)
+        >>> isinstance(reader, pypdf.PdfReader)
+        True
+        >>> # Test with bytes
+        >>> with open(tmp_path, 'rb') as f:
+        ...     pdf_bytes = f.read()
+        >>> reader = _resolve_pdf_src_to_reader(pdf_bytes)
+        >>> isinstance(reader, pypdf.PdfReader)
+        True
+        >>> # Test with PdfReader
+        >>> reader_in = pypdf.PdfReader(tmp_path)
+        >>> reader = _resolve_pdf_src_to_reader(reader_in)
+        >>> reader is reader_in
+        True
+        >>> import os
+        >>> os.remove(tmp_path)
+    """
+    if isinstance(pdf_src, pypdf.PdfReader):
+        return pdf_src
+    elif isinstance(pdf_src, bytes):
+        from pdfdol.base import bytes_to_pdf_reader_obj
+
+        return bytes_to_pdf_reader_obj(pdf_src)
+    elif isinstance(pdf_src, str):
+        if not os.path.exists(pdf_src):
+            raise ValueError(f"File not found: {pdf_src}")
+        return pypdf.PdfReader(pdf_src)
+    else:
+        raise ValueError(
+            f"pdf_src must be a file path (str), bytes, or PdfReader object, not {type(pdf_src)}"
+        )
+
+
+def pdf_to_metadata(pdf_src: Union[str, bytes, pypdf.PdfReader]) -> dict:
+    """
+    Extract metadata from a PDF source.
+
+    Args:
+        pdf_src: Can be a file path (str), PDF bytes, or a PdfReader object
+
+    Returns:
+        dict: Dictionary containing metadata fields (title, author, subject, etc.)
+              Returns empty dict if no metadata or an error occurs.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> from pdfdol.tests.utils_for_testing import get_test_pdf_folder
+        >>> test_folder = Path(get_test_pdf_folder())
+        >>> pdf_path = test_folder / "sample_with_title.pdf"
+        >>> metadata = pdf_to_metadata(str(pdf_path))
+        >>> metadata.get('Title')
+        'Sample PDF with Title'
+        >>> metadata.get('Author')
+        'Test Author'
+    """
+    try:
+        reader = _resolve_pdf_src_to_reader(pdf_src)
+        if reader.metadata:
+            # Convert pypdf DocumentInformation to a regular dict
+            # and normalize the keys (remove leading slash)
+            return {key.lstrip('/'): value for key, value in reader.metadata.items()}
+        return {}
+    except Exception as e:
+        # Optionally log the error instead of printing
+        # For now, return empty dict on error
+        return {}
+
+
+def pdf_to_title(pdf_src: Union[str, bytes, pypdf.PdfReader]) -> str | None:
+    """
+    Extract the document title from a PDF source.
+
+    Args:
+        pdf_src: Can be a file path (str), PDF bytes, or a PdfReader object
+
+    Returns:
+        str | None: The title from the metadata, or None if not found or an error occurs.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> from pdfdol.tests.utils_for_testing import get_test_pdf_folder
+        >>> test_folder = Path(get_test_pdf_folder())
+        >>> # Test with file path
+        >>> pdf_path = test_folder / "sample_with_title.pdf"
+        >>> pdf_to_title(str(pdf_path))
+        'Sample PDF with Title'
+        >>> # Test with bytes
+        >>> pdf_bytes = pdf_path.read_bytes()
+        >>> pdf_to_title(pdf_bytes)
+        'Sample PDF with Title'
+        >>> # Test with PdfReader
+        >>> reader = pypdf.PdfReader(str(pdf_path))
+        >>> pdf_to_title(reader)
+        'Sample PDF with Title'
+        >>> # Test with no title
+        >>> pdf_path_no_title = test_folder / "sample_pdf_1.pdf"
+        >>> pdf_to_title(str(pdf_path_no_title)) is None
+        True
+    """
+    metadata = pdf_to_metadata(pdf_src)
+    title = metadata.get('title') or metadata.get('Title')
+    if title:
+        return title.strip()
+    return None

pdfdol/tools.py

@@ -190,7 +190,6 @@ def html_to_pdf(*args, **kwargs):
             "You need to have either weasyprint or pdfkit installed to use html_to_pdf"
         )
 
-
 # ---------------------------------------------------------------------------------
 # Pdf concatenation
 # TODO: Add some functionality to prefix/suffix pdf pages (useful when concatenating)