ENH: Add pagemeta subcommand (#17)

* Remove a Flake8-Plugin
* Cleanup ruff
* Update README

Author: MartinThoma

.pre-commit-config.yaml

@@ -35,6 +35,7 @@ repos:
     rev: 'v0.0.254'
     hooks:
     -   id: ruff
+        args: [--fix]
 -   repo: https://github.com/asottile/pyupgrade
     rev: v3.3.1
     hooks:

README.md

@@ -19,40 +19,42 @@ As `pdfly` is an application, you might want to install it with [`pipx`](https:/
 
 ```console
 $ pdfly --help
-Usage: pdfly [OPTIONS] COMMAND [ARGS]...
-
-  pdfly is a pure-python cli application for manipulating PDF files.
-
-Options:
-  --version
-  --help     Show this message and exit.
-
-Commands:
-  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.
-  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
 
+ Usage: pdfly [OPTIONS] COMMAND [ARGS]...
+
+ pdfly is a pure-python cli application for manipulating PDF files.
+
+╭─ Options ───────────────────────────────────────────────────────────────────╮
+│ --version                                                                   │
+│ --help             Show this message and exit.                              │
+╰─────────────────────────────────────────────────────────────────────────────╯
+╭─ Commands ──────────────────────────────────────────────────────────────────╮
+│ 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.                                            │
+│ 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.                          │
+╰─────────────────────────────────────────────────────────────────────────────╯
 ```
 
 You can see the help of every subcommand by typing:
 
 ```console
 $ pdfly 2-up --help
-Usage: pdfly 2-up [OPTIONS] PDF OUT
-
-  Create a booklet-style PDF from a single input.
-
-  Pairs of two pages will be put on one page (left and right)
 
-  usage: python 2-up.py input_file output_file
+ Usage: pdfly 2-up [OPTIONS] PDF OUT
 
-Arguments:
-  PDF  [required]
-  OUT  [required]
+ Create a booklet-style PDF from a single input.
+ Pairs of two pages will be put on one page (left and right)
+ usage: python 2-up.py input_file output_file
 
-Options:
-  --help  Show this message and exit.
+╭─ Arguments ─────────────────────────────────────────────────────────────────╮
+│ *    pdf      PATH  [default: None] [required]                              │
+│ *    out      PATH  [default: None] [required]                              │
+╰─────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ───────────────────────────────────────────────────────────────────╮
+│ --help          Show this message and exit.                                 │
+╰─────────────────────────────────────────────────────────────────────────────╯
 ```

pdfly/__init__.py

@@ -1,3 +1,4 @@
+"""pdfly is a command line utility for manipulating PDFs and getting information about them."""
 from ._version import __version__
 
 __all__ = [

pdfly/_utils.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class OutputOptions(Enum):
+    json = "json"
+    text = "text"

pdfly/cat.py

@@ -1,4 +1,3 @@
-#!/usr/bin/env python
 """
 Concatenate pages from PDF files into a single PDF file.
 
@@ -23,8 +22,7 @@
             1:10:2    1 3 5 7 9                2::-1     2 1 0.
             ::-1      all pages in reverse order.
 
-EXAMPLES
-
+Examples
     pdfcat -o output.pdf head.pdf content.pdf :6 7: tail.pdf -1
 
         Concatenate all of head.pdf, all but page seven of content.pdf,
@@ -53,7 +51,9 @@
 from pypdf import PdfMerger, parse_filename_page_ranges
 
 
-def main(filename: Path, fn_pgrgs: List[str], output: Path, verbose: bool) -> None:
+def main(
+    filename: Path, fn_pgrgs: List[str], output: Path, verbose: bool
+) -> None:
     fn_pgrgs_l = list(fn_pgrgs)
     fn_pgrgs_l.insert(0, str(filename))
     filename_page_ranges = parse_filename_page_ranges(fn_pgrgs_l)  # type: ignore

pdfly/cli.py

@@ -1,3 +1,9 @@
+"""
+Define how the CLI should behave.
+
+Subcommands are added here.
+"""
+
 from pathlib import Path
 from typing import List
 
@@ -7,25 +13,30 @@
 import pdfly.compress
 import pdfly.extract_images
 import pdfly.metadata
+import pdfly.pagemeta
 import pdfly.up2
 
 
 def version_callback(value: bool) -> None:
     if value:
         typer.echo(f"pdfly {pdfly.__version__}")
-        raise typer.Exit()
+        raise typer.Exit
 
 
 entry_point = typer.Typer(
     add_completion=False,
-    help=("pdfly is a pure-python cli application for manipulating PDF files."),
+    help=(
+        "pdfly is a pure-python cli application for manipulating PDF files."
+    ),
 )
 
 
 @entry_point.callback()  # type: ignore[misc]
 def common(
     ctx: typer.Context,
-    version: bool = typer.Option(None, "--version", callback=version_callback),  # noqa
+    version: bool = typer.Option(  # noqa: B008
+        None, "--version", callback=version_callback
+    ),
 ) -> None:
     pass
 
@@ -68,8 +79,27 @@ def metadata(
     pdfly.metadata.main(pdf, output)
 
 
+@entry_point.command(name="pagemeta")  # type: ignore[misc]
+def pagemeta(
+    pdf: Path,
+    page_index: int,
+    output: pdfly.metadata.OutputOptions = typer.Option(  # noqa
+        pdfly.metadata.OutputOptions.text.value,
+        "--output",
+        "-o",
+        help="output format",
+        show_default=True,
+    ),
+) -> None:
+    pdfly.pagemeta.main(
+        pdf,
+        page_index,
+        output,
+    )
+
+
 @entry_point.command(name="extract-text")  # type: ignore[misc]
-def extract_text(pdf: Path):
+def extract_text(pdf: Path) -> None:
     """Extract text from a PDF file."""
     from pypdf import PdfReader
 
@@ -79,12 +109,13 @@ def extract_text(pdf: Path):
 
 
 @entry_point.command(name="compress")  # type: ignore[misc]
-def compress(pdf: Path, output: Path):
+def compress(pdf: Path, output: Path) -> None:
     pdfly.compress.main(pdf, output)
 
 
 up2.__doc__ = pdfly.up2.__doc__
 extract_images.__doc__ = pdfly.extract_images.__doc__
 cat.__doc__ = pdfly.cat.__doc__
 metadata.__doc__ = pdfly.metadata.__doc__
+pagemeta.__doc__ = pdfly.pagemeta.__doc__
 compress.__doc__ = pdfly.compress.__doc__

pdfly/compress.py

@@ -6,7 +6,7 @@
 from pypdf import PdfReader, PdfWriter
 
 
-def main(pdf: Path, output: Path):
+def main(pdf: Path, output: Path) -> None:
     reader = PdfReader(pdf)
     writer = PdfWriter()
     for page in reader.pages:

pdfly/metadata.py

@@ -2,21 +2,21 @@
 
 import stat
 from datetime import datetime
-from enum import Enum
 from pathlib import Path
-from typing import Optional, Set, Tuple
+from typing import Optional, Set
 
 from pydantic import BaseModel
 from pypdf import PdfReader
 
+from ._utils import OutputOptions
+
 
 class MetaInfo(BaseModel):
     title: Optional[str] = None
     producer: Optional[str] = None
     author: Optional[str] = None
     pages: int
     encrypted: bool
-    page_size: Tuple[float, float]  # (width, height)
     pdf_file_version: str
     page_mode: Optional[str]
     page_layout: Optional[str]
@@ -29,23 +29,16 @@ class MetaInfo(BaseModel):
     access_time: datetime
 
 
-class OutputOptions(Enum):
-    json = "json"
-    text = "text"
-
-
 def main(pdf: Path, output: OutputOptions) -> None:
     reader = PdfReader(str(pdf))
     info = reader.metadata
-    x1, y1, x2, y2 = reader.pages[0].mediabox
 
     reader.stream.seek(0)
     pdf_file_version = reader.stream.read(8).decode("utf-8")
     pdf_stat = pdf.stat()
     meta = MetaInfo(
         pages=len(reader.pages),
         encrypted=reader.is_encrypted,
-        page_size=(x2 - x1, y2 - y1),
         page_mode=reader.page_mode,
         pdf_file_version=pdf_file_version,
         page_layout=reader.page_layout,
@@ -68,17 +61,16 @@ def main(pdf: Path, output: OutputOptions) -> None:
         from rich.table import Table
 
         table = Table(title="PDF Data")
-        table.add_column("Attribute", justify="right", style="cyan", no_wrap=True)
+        table.add_column(
+            "Attribute", justify="right", style="cyan", no_wrap=True
+        )
         table.add_column("Value", style="white")
 
         table.add_row("Title", meta.title)
         table.add_row("Producer", meta.producer)
         table.add_row("Author", meta.author)
         table.add_row("Pages", f"{meta.pages:,}")
         table.add_row("Encrypted", f"{meta.encrypted}")
-        table.add_row(
-            "Page size", f"{meta.page_size[0]} x {meta.page_size[1]} pts (w x h)"
-        )
         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)
@@ -92,17 +84,26 @@ def main(pdf: Path, output: OutputOptions) -> None:
         table.add_row("Fonts (embedded)", ", ".join(sorted(embedded_fonts)))
 
         os_table = Table(title="Operating System Data")
-        os_table.add_column("Attribute", justify="right", style="cyan", no_wrap=True)
+        os_table.add_column(
+            "Attribute", justify="right", style="cyan", no_wrap=True
+        )
         os_table.add_column("Value", style="white")
         os_table.add_row("File Name", f"{pdf}")
         os_table.add_row("File Permissions", f"{meta.file_permissions}")
         os_table.add_row("File Size", f"{meta.file_size:,} bytes")
-        os_table.add_row("Creation Time", f"{meta.creation_time:%Y-%m-%d %H:%M:%S}")
+        os_table.add_row(
+            "Creation Time", f"{meta.creation_time:%Y-%m-%d %H:%M:%S}"
+        )
         os_table.add_row(
             "Modification Time", f"{meta.modification_time:%Y-%m-%d %H:%M:%S}"
         )
-        os_table.add_row("Access Time", f"{meta.access_time:%Y-%m-%d %H:%M:%S}")
+        os_table.add_row(
+            "Access Time", f"{meta.access_time:%Y-%m-%d %H:%M:%S}"
+        )
 
         console = Console()
         console.print(os_table)
         console.print(table)
+        console.print(
+            "Use the 'pagemeta' subcommand to get details about a single page"
+        )

pdfly/pagemeta.py

@@ -0,0 +1,79 @@
+"""Give details about a single page."""
+
+from pathlib import Path
+from typing import Tuple
+
+from pydantic import BaseModel
+from pypdf import PdfReader
+
+from ._utils import OutputOptions
+
+
+class PageMeta(BaseModel):
+    mediabox: Tuple[int, int, int, int]
+    cropbox: Tuple[int, int, int, int]
+    artbox: Tuple[int, int, int, int]
+    bleedbox: Tuple[int, int, int, int]
+    annotations: int
+
+
+def main(pdf: Path, page_index: int, output: OutputOptions) -> None:
+    reader = PdfReader(pdf)
+    page = reader.pages[page_index]
+    meta = PageMeta(
+        mediabox=page.mediabox,
+        cropbox=page.cropbox,
+        artbox=page.artbox,
+        bleedbox=page.bleedbox,
+        annotations=len(page.annotations) if page.annotations else 0,
+    )
+
+    if output == OutputOptions.json:
+        print(meta.json())
+    else:
+        from rich.console import Console
+        from rich.markdown import Markdown
+        from rich.table import Table
+
+        console = Console()
+
+        table = Table(title=f"{pdf}, page index {page_index}")
+        table.add_column(
+            "Attribute", justify="right", style="cyan", no_wrap=True
+        )
+        table.add_column("Value", style="white")
+
+        table.add_row(
+            "mediabox",
+            f"{meta.mediabox}: "
+            f"with={meta.mediabox[2] - meta.mediabox[0]} "
+            f"x height={meta.mediabox[3] - meta.mediabox[1]}",
+        )
+        table.add_row(
+            "cropbox",
+            f"{meta.cropbox}: "
+            f"with={meta.cropbox[2] - meta.cropbox[0]} "
+            f"x height={meta.cropbox[3] - meta.cropbox[1]}",
+        )
+        table.add_row(
+            "artbox",
+            f"{meta.artbox}: "
+            f"with={meta.artbox[2] - meta.artbox[0]} "
+            f"x height={meta.artbox[3] - meta.artbox[1]}",
+        )
+        table.add_row(
+            "bleedbox",
+            f"{meta.bleedbox}: "
+            f"with={meta.bleedbox[2] - meta.bleedbox[0]} "
+            f"x height={meta.bleedbox[3] - meta.bleedbox[1]}",
+        )
+
+        table.add_row("annotations", str(meta.annotations))
+
+        console.print(table)
+
+        if page.annotations:
+            console.print(Markdown("**All annotations:**"))
+            for i, annot in enumerate(page.annotations, start=1):
+                obj = annot.get_object()
+                console.print(f"{i}. {obj['/Subtype']} at {obj['/Rect']}")