pdf-compressor 0.4.0__py3-none-any.whl

pdf_compressor/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from pdf_compressor.ilovepdf import Compress, ILovePDF, Task
+from pdf_compressor.main import DEFAULT_SUFFIX, compress, main
+from pdf_compressor.utils import si_fmt
+
+try:
+    __version__ = version(__name__)
+except PackageNotFoundError:
+    pass  # package not installed

pdf_compressor/ilovepdf.py

@@ -0,0 +1,348 @@
+"""Code in this file was adapted from Andrea Bruschi's pylovepdf.
+
+https://github.com/AndyCyberSec/pylovepdf
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from typing import Any, BinaryIO, Literal, TypedDict
+
+import requests
+from requests import Response
+
+
+class ProcessResponse(TypedDict):
+    """Type of ILovePDF.process() return value."""
+
+    timer: str
+    status: str
+    download_filename: str
+    filesize: int
+    output_filesize: int
+    output_filenumber: int
+    output_extensions: list[str]
+
+
+class ILovePDF:
+    """Communicates with the iLovePDF API."""
+
+    def __init__(self, public_key: str, *, debug: bool = False) -> None:
+        """Creates a new iLovePDF object to interact with the API.
+
+        Args:
+            public_key (str): iLovePDF API key. Get yours by signing up at
+                https://developer.ilovepdf.com/signup.
+            debug (bool, optional): Whether to perform real API requests (consumes
+                quota) or just report what would happen. Defaults to False.
+        """
+        self.public_key = public_key
+
+        self.api_version = "v1"
+        self.start_server = "api.ilovepdf.com"
+        self.working_server = ""
+        # Any resource can be called with a debug option. When true, iLovePDF won't
+        # process the request but will output the parameters received by the server.
+        self.debug = debug  # https://developer.ilovepdf.com/docs/api-reference#testing
+
+        # header will contain authorization token to be sent with every task
+        self.headers: dict[str, str] | None = None
+
+        self.auth()
+
+    def auth(self) -> None:
+        """Get iLovePDF API session token."""
+        payload = {"public_key": self.public_key}
+
+        response = self._send_request("post", endpoint="auth", payload=payload)
+
+        self.headers = {"Authorization": f"Bearer {response.json()['token']}"}
+
+    def get_quota(self) -> int:
+        """Response has only one key: {'remaining_credits': int}.
+
+        Returns:
+            int: Number of remaining files that can be processed by the API in the
+                current billing cycle.
+        """
+        try:
+            response = json.loads(self._send_request("get", "info").text)
+
+            return response["remaining_credits"]
+        except Exception as exc:
+            exc.add_note(f"{locals()=}")
+            raise
+
+    def _send_request(
+        self,
+        method: Literal["get", "post", "delete"],
+        endpoint: str,
+        *,
+        payload: dict[str, Any] | None = None,
+        files: dict[str, BinaryIO] | None = None,
+        stream: bool = False,
+    ) -> Response:
+        # continue to use old server if task was already assigned one, else connect to
+        # new server
+        server = self.working_server or self.start_server
+        payload = payload or {}
+
+        url = f"https://{server}/{self.api_version}/{endpoint}"
+
+        if self.debug:
+            payload["debug"] = True
+
+        response = getattr(requests, method)(
+            url, data=payload, headers=self.headers, files=files, stream=stream
+        )
+
+        if not response.ok:
+            raise ValueError(
+                f"Error: {response.url} returned status code {response.status_code}, "
+                f"reason: '{response.reason}'. Full response text is: '{response.text}'"
+            )
+
+        return response
+
+
+class Task(ILovePDF):
+    """Class for interacting with the iLovePDF request workflow.
+
+    https://developer.ilovepdf.com/docs/api-reference#request-workflow
+    """
+
+    def __init__(
+        self,
+        public_key: str,
+        tool: str,
+        *,
+        verbose: bool = False,
+        password: str = "",
+        **kwargs: Any,
+    ) -> None:
+        """Creates a new task object to interact with the API.
+
+        Args:
+            public_key (str): iLovePDF API key.
+            tool (str): The desired API tool you wish to access. Possible values: merge,
+                split, compress, pdfjpg, imagepdf, unlock, pagenumber, watermark, pdfa,
+                officepdf, repair, rotate, protect, validatepdfa, htmlpdf, extract.
+                pdf-compressor only supports 'compress'. Might change in the future.
+                https://developer.ilovepdf.com/docs/api-reference#process.
+            verbose (bool, optional): Whether to print progress messages while uploading
+                and processing files. Defaults to False.
+            password (str, optional): Password to open PDFs in case they have one.
+                Defaults to "".
+            **kwargs: Additional keyword arguments to pass to ILovePDF.__init__().
+        """
+        super().__init__(public_key, **kwargs)
+
+        self.files: dict[str, str] = {}
+        self._task_id = ""
+        self._process_response: ProcessResponse | None = None
+
+        self.verbose = verbose
+        self.tool = tool
+        self.password = password
+
+        # API options https://developer.ilovepdf.com/docs/api-reference#process
+        # placeholders like {app}, {n}, {filename} in output/packaged_filename will be
+        # inserted by iLovePDF.
+        # See https://developer.ilovepdf.com/docs/api-reference#output_filename
+        self.process_params = {
+            "tool": tool,
+            "ignore_password": True,
+            # important to keep {n} in front as sort order is used to match existing
+            # to downloaded files
+            "output_filename": "{n}-{filename}-{app}",
+            "packaged_filename": "{app}ed-PDFs",
+        }
+
+        self.start()
+
+    def start(self) -> None:
+        """Initiate contact with iLovePDF API to get assigned a working server that will
+        handle ensuing requests.
+        """
+        response = self._send_request("get", f"start/{self.tool}").json()
+
+        if response:
+            self.working_server = response["server"]
+
+            self._task_id = response["task"]
+
+        else:
+            print(
+                "Warning: Starting this task returned empty JSON response. "
+                "Was likely already started."
+            )
+
+    def add_file(self, file_path: str) -> None:
+        """Add a file to the task.
+
+        Args:
+            file_path (str): Path of file to be added.
+
+        Raises:
+            FileNotFoundError: If file does not exist.
+        """
+        if not os.path.isfile(file_path):
+            raise FileNotFoundError(f"'{file_path}' does not exist")
+
+        if file_path in self.files:
+            print(f"Warning: File '{file_path}' was already added to this task.")
+
+        self.files[file_path] = ""
+
+    def upload(self) -> dict[str, str]:
+        """Second step of the task is where the PDFs files to be processed are uploaded
+        to iLovePDF servers.
+
+        Returns:
+            dict[str, str]: Map from local filenames to corresponding filenames on the
+                server.
+        """
+        payload = {"task": self._task_id}
+
+        for filename in self.files:
+            with open(filename, "rb") as file:
+                response = self._send_request(
+                    "post", "upload", payload=payload, files={"file": file}
+                ).json()
+
+            # server_filename is the only key in the JSON response
+            self.files[filename] = response["server_filename"]
+
+        return self.files
+
+    def process(self) -> ProcessResponse:
+        """Uploads and then processes files added to this Task. Files will be processed
+        in the same order as iterating over self.files.items().
+
+        Returns:
+            ProcessResponse: The post-processing JSON response.
+
+        Raises:
+            ValueError: If the task ID is invalid.
+        """
+        if self.verbose:
+            print("Uploading file(s)...")
+
+        self.upload()
+
+        payload = self.process_params.copy()
+        payload["task"] = self._task_id
+
+        for idx, (filename, server_filename) in enumerate(self.files.items()):
+            payload[f"files[{idx}][filename]"] = filename
+            payload[f"files[{idx}][server_filename]"] = server_filename
+            payload[f"files[{idx}][password]"] = self.password
+
+        response: ProcessResponse = self._send_request(
+            "post", "process", payload=payload
+        ).json()
+
+        self._process_response = response
+        n_files = response["output_filenumber"]
+
+        if len(self.files) != response["output_filenumber"]:
+            raise ValueError(
+                f"Unexpected file count mismatch: task received {len(self.files)} files"
+                f" for processing, but only {n_files} were downloaded from server."
+            )
+
+        if self.verbose:
+            print(f"File(s) uploaded and processed!\n{response = }")
+
+        return response
+
+    def download(self, save_to_dir: str | None = None) -> str:
+        """Download this task's output file(s) for the given task. Should not be called
+        until after task.process(). In case of a single output file, it is saved to disk
+        as a PDF. Multiple files are saved in a compressed ZIP folder.
+
+        Raises:
+            ValueError: If task.download() is called in absence of downloadable files,
+                usually because task.process() wasn't called yet.
+
+        Returns:
+            str: Path to the newly downloaded file.
+        """
+        if not self._process_response:
+            raise ValueError(
+                "You called task.download() but there are no files to download"
+            )
+
+        endpoint = f"download/{self._task_id}"
+
+        response = self._send_request("get", endpoint, stream=True)
+
+        if not save_to_dir:  # save_to_dir is None or ''
+            save_to_dir = tempfile.mkdtemp()
+
+        file_path = os.path.join(
+            save_to_dir, self._process_response["download_filename"]
+        )
+
+        # create parent dir (we use download_filename instead of save_to_dir because it
+        # may contain subdirs)
+        os.makedirs(os.path.dirname(file_path), exist_ok=True)
+
+        # response.content is PDF file or ZIP archive, either way, we save as binary
+        with open(file_path, mode="wb") as file:
+            file.write(response.content)
+
+        return file_path
+
+    def delete_current_task(self) -> None:
+        """Delete the current task from iLovePDF servers.
+
+        https://developer.ilovepdf.com/docs/api-reference#task
+        """
+        if not self._task_id:
+            print("Warning: You're trying to delete a task that was never started")
+            return
+
+        self._send_request("delete", f"task/{self._task_id}")
+        self._task_id = ""
+        self._process_response = None
+
+
+class Compress(Task):
+    """Use the iLovePDF compression tool.
+
+    Example:
+        from pdf_compressor import Compress
+
+        task = Compress("public_key")
+        task.add_file("pdf_file")
+        task.process()
+        task.download("output/dir")
+        task.delete_current_task()
+    """
+
+    def __init__(
+        self, public_key: str, compression_level: str = "recommended", **kwargs: Any
+    ) -> None:
+        """Subclass of Task for using the iLovePDF compression tool.
+
+        Args:
+            public_key (str): iLovePDF public API key. Get yours by signing up at
+                https://developer.ilovepdf.com/signup.
+            compression_level (str, optional): How hard to squeeze the file size.
+                'extreme' noticeably degrades image quality. Defaults to 'recommended'.
+            **kwargs: Additional keyword arguments to pass to Task.__init__().
+
+        Raises:
+            ValueError: If the compression level is invalid.
+        """
+        super().__init__(public_key, tool="compress", **kwargs)
+
+        if compression_level not in (valid_levels := ("low", "recommended", "extreme")):
+            raise ValueError(
+                f"Invalid {compression_level=}, must be one of {valid_levels}"
+            )
+
+        self.process_params["compression_level"] = compression_level

pdf_compressor/main.py

@@ -0,0 +1,331 @@
+from __future__ import annotations
+
+import os
+import re
+from argparse import ArgumentParser
+from glob import glob
+from importlib.metadata import version
+from typing import TYPE_CHECKING, Any
+
+from pdf_compressor.ilovepdf import Compress, ILovePDF
+from pdf_compressor.utils import ROOT, del_or_keep_compressed, load_dotenv
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+DEFAULT_SUFFIX = "-compressed"
+API_KEY_KEY = "ILOVEPDF_PUBLIC_KEY"
+MISSING_API_KEY_ERR = KeyError(
+    "pdf-compressor needs an iLovePDF public key to access its API. Set one "
+    "with pdf-compressor --set-api-key project_public_7af905e... or as environment "
+    f"variable {API_KEY_KEY}"
+)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Compress PDFs using iLovePDF's API.
+
+    Args:
+        argv (Sequence[str] | None): Command line arguments.
+
+    Returns:
+        int: 0 if successful, else error code.
+
+    Raises:
+        ValueError: If the API key is invalid.
+    """
+    parser = ArgumentParser(
+        description="Batch compress PDFs on the command line. Powered by iLovePDF.com.",
+        allow_abbrev=False,
+    )
+
+    parser.add_argument("filenames", nargs="*", help="List of PDF files to compress.")
+
+    parser.add_argument(
+        "--set-api-key",
+        help="Set the public key needed to authenticate with the iLovePDF API. Exits "
+        "immediately afterwards ignoring all other flags.",
+    )
+
+    parser.add_argument(
+        "--password",
+        type=str,
+        default="",
+        help="Password for protected PDF files. All files will use the same password. "
+        "Protected PDFs with different passwords must be compressed one by one.",
+    )
+    group = parser.add_mutually_exclusive_group()
+
+    group.add_argument(
+        "-i",
+        "--inplace",
+        action="store_true",
+        help="Whether to compress PDFs in place. Defaults to False.",
+    )
+    parser.add_argument(
+        "-o",
+        "--outdir",
+        type=str,
+        default="",
+        help="Output directory for compressed PDFs. Defaults to the current working "
+        "directory.",
+    )
+
+    group.add_argument(
+        "-s",
+        "--suffix",
+        default=DEFAULT_SUFFIX,
+        help="String to append to the filename of compressed PDFs. Mutually exclusive "
+        "with --inplace flag.",
+    )
+
+    parser.add_argument(
+        "--report-quota",
+        action="store_true",
+        help="Report how much of the monthly quota for the current API key has been "
+        "used up.",
+    )
+
+    parser.add_argument(
+        "--compression-level",
+        "--cl",
+        choices=("low", "recommended", "extreme"),
+        default="recommended",
+        help="How hard to squeeze the file size. 'extreme' noticeably degrades image "
+        "quality. Defaults to 'recommended'.",
+    )
+
+    parser.add_argument(
+        "--min-size-reduction",
+        "--min-red",
+        type=int,
+        choices=range(101),
+        metavar="[0-100]",  # prevents long list in argparse help message
+        help="How much compressed files need to be smaller than originals (in percent) "
+        "for them to be kept. Defaults to 10 when also passing -i/--inplace, else 0."
+        "For example, when compressing files in-place and only achieving 5%% file size "
+        "reduction, the compressed file will be discarded.",
+    )
+
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="When true, iLovePDF won't process the request but will output the "
+        "parameters received by the server. Defaults to False.",
+    )
+
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="When true, progress will be reported while tasks are running. Also prints"
+        " full file paths to compressed files instead of file name only. Defaults "
+        "to False.",
+    )
+
+    parser.add_argument(
+        "--on-no-files",
+        choices=("error", "ignore"),
+        default="ignore",
+        help="What to do when no input PDFs received. One of 'ignore' or 'error', "
+        "former exits 0, latter throws ValueError. Can be useful when using "
+        "pdf-compressor in shell scripts. Defaults to 'ignore'.",
+    )
+
+    parser.add_argument(
+        "--on-bad-files",
+        choices=("error", "warn", "ignore"),
+        default="error",
+        help="How to behave when receiving input files that don't appear to be PDFs. "
+        "One of 'error', 'warn', 'ignore'. Error will be TypeError. "
+        "Defaults to 'error'.",
+    )
+
+    parser.add_argument(
+        "--write-stats-path",
+        type=str,
+        default="",
+        help="File path to write a CSV, Excel or other pandas supported file format "
+        "with original vs compressed file sizes and actions taken on each input file",
+    )
+
+    pkg_version = version(pkg_name := "pdf-compressor")
+    parser.add_argument(
+        "-v", "--version", action="version", version=f"{pkg_name} v{pkg_version}"
+    )
+    args, _unknown_args = parser.parse_known_args(argv)
+
+    if new_key := args.set_api_key:
+        if not new_key.startswith("project_public_"):
+            raise ValueError(
+                f"invalid API key, must start with 'project_public_', got {new_key=}"
+            )
+
+        with open(f"{ROOT}/.env", mode="w+", encoding="utf8") as file:
+            file.write(f"ILOVEPDF_PUBLIC_KEY={new_key}\n")
+
+        return 0
+
+    load_dotenv()
+    if not (api_key := os.environ[API_KEY_KEY]):
+        raise MISSING_API_KEY_ERR
+
+    if args.report_quota:
+        remaining_credits = ILovePDF(api_key).get_quota()
+
+        print(f"Remaining files in this billing cycle: {remaining_credits:,}")
+
+        return 0
+
+    return compress(**vars(args))  # ty: ignore[missing-argument]
+
+
+def compress(
+    filenames: Sequence[str],
+    *,
+    inplace: bool = False,
+    outdir: str = "",
+    suffix: str = DEFAULT_SUFFIX,
+    compression_level: str = "recommended",
+    min_size_reduction: int | None = None,
+    debug: bool = False,
+    verbose: bool = False,
+    on_no_files: str = "ignore",
+    on_bad_files: str = "error",
+    write_stats_path: str = "",
+    password: str = "",
+    **kwargs: Any,  # noqa: ARG001
+) -> int:
+    """Compress PDFs using iLovePDF's API.
+
+    Args:
+        filenames (list[str]): List of PDF files to compress.
+        inplace (bool): Whether to compress PDFs in place.
+        outdir (str): Output directory for compressed PDFs. Defaults to the current
+            working directory.
+        suffix (str): String to append to the filename of compressed PDFs.
+        compression_level (str): How hard to squeeze the file size.
+        min_size_reduction (int): How much compressed files need to be smaller than
+            originals (in percent) for them to be kept.
+        debug (bool): When true, iLovePDF won't process the request but will output the
+            parameters received by the server.
+        verbose (bool): When true, progress will be reported while tasks are running.
+        on_no_files (str): What to do when no input PDFs received.
+        on_bad_files (str): How to behave when receiving input files that don't appear
+            to be PDFs.
+        write_stats_path (str): File path to write a CSV, Excel or other pandas
+            supported file format with original vs compressed file sizes and actions
+            taken on each input file
+        password (str): Password to open PDFs in case they have one. Defaults to "".
+            TODO There's currently no way of passing different passwords for different
+            files. PDFs with different passwords must be compressed one by one.
+        **kwargs: Additional keywords are ignored.
+
+    Returns:
+        int: 0 if successful, else error code.
+
+    Raises:
+        ImportError: If pandas is not installed.
+        ValueError: If the API key is invalid.
+    """
+    if min_size_reduction is None:
+        min_size_reduction = 10 if inplace else 0
+
+    load_dotenv()
+    if not (api_key := os.environ[API_KEY_KEY]):
+        raise MISSING_API_KEY_ERR
+
+    if not (inplace or suffix):
+        raise ValueError(
+            "Files must either be compressed in-place (--inplace) or you must specify a"
+            " non-empty suffix to append to the name of compressed files."
+        )
+
+    # use set() to ensure no duplicate files
+    uniq_files: list[str] = sorted({fn.replace("\\", "/").strip() for fn in filenames})
+    # for each directory received glob for all PDFs in it
+    file_paths = []
+    for file_path in uniq_files:
+        if os.path.isdir(file_path):
+            file_paths += glob(os.path.join(file_path, "**", "*.pdf*"), recursive=True)
+        else:
+            file_paths += [file_path]
+
+    # match files case insensitively ending with .pdf(,a,x) and possible white space
+    pdf_paths = [f for f in file_paths if re.match(r".*\.pdf[ax]?\s*$", f.lower())]
+    not_pdf_paths = {*file_paths} - {*pdf_paths}
+
+    if on_bad_files == "error" and len(not_pdf_paths) > 0:
+        raise ValueError(
+            f"Input files must be PDFs, got {len(not_pdf_paths):,} files with "
+            f"unexpected extension: {', '.join(not_pdf_paths)}"
+        )
+    if on_bad_files == "warn" and len(not_pdf_paths) > 0:
+        print(
+            f"Warning: Got {len(not_pdf_paths):,} input files without '.pdf' "
+            f"extension: {', '.join(not_pdf_paths)}"
+        )
+
+    if verbose:
+        if len(pdf_paths) > 0:
+            print(f"PDFs to be compressed with iLovePDF: {len(pdf_paths):,}")
+        else:
+            print("Nothing to do: received no input PDF files.")
+
+    if len(pdf_paths) == 0:
+        if on_no_files == "error":
+            raise ValueError("No input files provided")
+        return 0
+
+    task = Compress(
+        api_key, compression_level=compression_level, debug=debug, password=password
+    )
+    task.verbose = verbose
+
+    for pdf in pdf_paths:
+        task.add_file(pdf)
+
+    task.process()
+
+    downloaded_file = task.download(save_to_dir=outdir)
+
+    task.delete_current_task()
+
+    min_size_red = min_size_reduction or (10 if inplace else 0)
+
+    if debug:
+        stats = {}
+    else:
+        stats = del_or_keep_compressed(
+            pdf_paths,
+            downloaded_file,
+            inplace=inplace,
+            suffix=suffix,
+            min_size_reduction=min_size_red,
+            verbose=verbose,
+        )
+
+    if write_stats_path:
+        try:
+            import pandas as pd  # noqa: PLC0415
+        except ImportError:
+            err_msg = "To write stats to file, install pandas: pip install pandas"
+            raise ImportError(err_msg) from None
+
+        df_stats = pd.DataFrame(stats).T
+        df_stats.index.name = "file"
+        stats_path_lower = write_stats_path.strip().lower()
+
+        if ".csv" in stats_path_lower:
+            df_stats.to_csv(write_stats_path, float_format="%.4f")
+        elif ".xlsx" in stats_path_lower or ".xls" in stats_path_lower:
+            df_stats.to_excel(write_stats_path, float_format="%.4f")
+        elif ".json" in stats_path_lower:
+            df_stats.to_json(write_stats_path)
+        elif ".html" in stats_path_lower:
+            df_stats.to_html(write_stats_path, float_format="%.4f")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pdf_compressor/utils.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from os.path import abspath, basename, dirname, expanduser, getsize, isfile, splitext
+from typing import TYPE_CHECKING
+from zipfile import ZipFile
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+ROOT = dirname(dirname(abspath(__file__)))
+
+
+def si_fmt(val: float, *, binary: bool = True, fmt: str = ".1f", sep: str = "") -> str:
+    """Convert large numbers into human readable format using SI prefixes in binary
+    (1024) or metric (1000) mode.
+
+    https://nist.gov/pml/weights-and-measures/metric-si-prefixes
+
+    Args:
+        val (int | float): Some numerical value to format.
+        binary (bool, optional): If True, scaling factor is 2^10 = 1024 else 1000.
+            Defaults to True.
+        fmt (str): f-string format specifier. Configure precision and left/right
+            padding in returned string. Defaults to ".1f". Can be used to ensure leading
+            or trailing whitespace for shorter numbers. Ex.1: ">10.2f" has 2 decimal
+            places and is at least 10 characters long with leading spaces if necessary.
+            Ex.2: "<20.3g" uses 3 significant digits (g: scientific notation on large
+            numbers) with at least 20 chars through trailing space.
+        sep (str): Separator between number and postfix. Defaults to "".
+
+    Returns:
+        str: Formatted number.
+    """
+    factor = 1024 if binary else 1000
+    _scale = ""
+
+    if abs(val) >= 1:
+        # 1, Kilo, Mega, Giga, Tera, Peta, Exa, Zetta, Yotta
+        for _scale in ("", "K", "M", "G", "T", "P", "E", "Z", "Y"):
+            if abs(val) < factor:
+                break
+            val /= factor
+    else:
+        mu_unicode = "\u03bc"
+        # milli, micro, nano, pico, femto, atto, zepto, yocto
+        for _scale in ("", "m", mu_unicode, "n", "p", "f", "a", "z", "y"):
+            if abs(val) > 1:
+                break
+            val *= factor
+
+    return f"{val:{fmt}}{sep}{_scale}"
+
+
+def load_dotenv(filepath: str | None = None) -> None:
+    """Parse environment variables in .env into os.environ.
+
+    Args:
+        filepath (str, optional): Path to .env file. Defaults to './.env'.
+    """
+    if filepath is None:
+        filepath = os.path.join(f"{ROOT}", ".env")
+
+    if isfile(filepath):
+        with open(filepath, encoding="utf8") as dotenv:
+            for line in dotenv:
+                if line.startswith("#"):
+                    continue
+
+                key, val = line.replace("\n", "").split("=")
+                os.environ[key] = val
+
+
+def del_or_keep_compressed(
+    pdfs: Sequence[str],
+    downloaded_file: str,
+    *,
+    inplace: bool,
+    suffix: str,
+    min_size_reduction: int,
+    verbose: bool = False,
+) -> dict[str, dict[str, object]]:
+    """Check whether compressed PDFs are smaller than original. If so, relocate each
+    compressed file to same directory as the original either with suffix appended to
+    file name or overwriting the original if inplace=True.
+
+    Args:
+        pdfs (list[str]): File paths to PDFs uploaded to iLovePDF.
+        downloaded_file (str): Path to file downloaded from iLovePDF servers. Will be
+            PDF or ZIP depending on if single or multiple files were uploaded.
+        inplace (bool): Whether to overwrite original PDFs with compressed ones if
+            smaller.
+        suffix (str): String to insert after filename and before extension of compressed
+            PDFs. Used only if inplace=False.
+        min_size_reduction (int): How much compressed files need to be smaller than
+            originals (in percent) for them to be kept.
+        verbose (bool): Whether to print file names or full file paths. Defaults to
+            False.
+
+    Returns:
+        pd.DataFrame: Table with original and compressed file sizes.
+    """  # noqa: DOC501
+    if (n_files := len(pdfs)) == 1:
+        compressed_files = [downloaded_file]
+    else:  # if multiple files were uploaded, downloaded_file is a ZIP archive
+        with ZipFile(downloaded_file) as archive:
+            # sort compressed_files since pdfs were also sorted
+            compressed_files = sorted(archive.namelist())
+            archive.extractall()
+
+    total_orig_size = total_compressed_size = 0
+
+    stats = {}
+
+    for idx, orig_path in enumerate(pdfs):
+        if n_files > 1:
+            compressed_path = next(
+                filename
+                for filename in compressed_files
+                if os.path.basename(filename).startswith(f"{idx}-")
+            )
+        else:
+            compressed_path = compressed_files[0]
+        orig_size = getsize(orig_path)
+        compressed_size = getsize(compressed_path)
+
+        total_orig_size += orig_size
+        total_compressed_size += compressed_size
+
+        diff = orig_size - compressed_size
+        counter = f"\n{idx + 1} " if n_files > 1 else ""
+
+        # check if size reduction is large enough to keep compressed file and
+        # optionally move original to trash if inplace=True
+        if diff / orig_size > min_size_reduction / 100:
+            filepath = orig_path if verbose else basename(orig_path)
+            print(
+                f"{counter}'{filepath}': {si_fmt(orig_size)}B -> "
+                f"{si_fmt(compressed_size)}B which is {si_fmt(diff)}B = "
+                f"{diff / orig_size:.0%} smaller."
+            )
+
+            if inplace:
+                if sys.platform == "darwin":
+                    # move original PDF to trash on macOS, for later retrieval if needed
+                    print("Old file moved to trash.")
+                    orig_file_name = os.path.split(orig_path)[1]
+
+                    trash_path = f"{expanduser('~')}/.Trash/{orig_file_name}"
+                    if isfile(trash_path):  # if file with same name already in trash,
+                        # delete it to avoid PermissionError: [Errno 1] Operation not
+                        # permitted
+                        os.remove(trash_path)
+                    os.rename(orig_path, trash_path)
+                else:
+                    # on other platforms, simply let shutil.move() below overwrite
+                    # existing PDF
+                    print("Old file deleted.")
+
+                # don't use os.(rename|replace)() on Windows, both error if src and
+                # dest are on different drives, former also if destination file already
+                # exists
+                shutil.move(compressed_path, orig_path)
+                action = "replaced original"
+
+            elif suffix:
+                base_name, ext = splitext(orig_path)
+                new_path = f"{base_name}{suffix}{ext}"
+
+                shutil.move(compressed_path, new_path)
+                action = f"saved as {basename(new_path)}"
+
+            else:
+                raise RuntimeError("This case should be not be reached")
+        else:
+            not_enough_reduction = "no" if diff == 0 else f"only {diff / orig_size:.1%}"
+            print(
+                f"{counter}'{orig_path}' {not_enough_reduction} smaller than original "
+                "file. Keeping original."
+            )
+            os.remove(compressed_path)
+            action = "kept original"
+
+        stats[basename(orig_path)] = {
+            "original size (B)": orig_size,
+            "compressed size (B)": compressed_size,
+            "size reduction (B)": diff,
+            "size reduction (%)": diff / orig_size,
+            "action": action,
+        }
+
+    # remove ZIP archive and unused compressed PDFs
+    for filename in (*compressed_files, downloaded_file):
+        try:
+            os.remove(filename)
+        except OSError:
+            pass
+
+    # print overall size reduction if >= 2 file
+    overall_reduction = total_orig_size - total_compressed_size
+    show_summary_above_n_files = 2
+    if n_files > show_summary_above_n_files and overall_reduction > 0:
+        print(
+            f"Overall size reduction in {n_files} files: {si_fmt(overall_reduction)}B, "
+            f"from {si_fmt(total_orig_size)}B to {si_fmt(total_compressed_size)}B"
+        )
+
+    return stats

pdf_compressor-0.4.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: pdf-compressor
+Version: 0.4.0
+Summary: CLI + Python API for batch compressing PDFs with iLovePDF.com
+Author-email: Janosh Riebesell <janosh.riebesell@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2021 Janosh Riebesell
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        The software is provided "as is", without warranty of any kind, express or
+        implied, including but not limited to the warranties of merchantability,
+        fitness for a particular purpose and noninfringement. In no event shall the
+        authors or copyright holders be liable for any claim, damages or other
+        liability, whether in an action of contract, tort or otherwise, arising from,
+        out of or in connection with the software or the use or other dealings in the
+        software.
+        
+Project-URL: Homepage, https://github.com/janosh/pdf-compressor
+Project-URL: Package, https://pypi.org/project/pdf-compressor
+Keywords: cli,compression,ilovepdf,pdf
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: stats
+Requires-Dist: pandas; extra == "stats"
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/janosh/pdf-compressor/main/assets/pdf-compressor.svg" alt="PDF Compressor" height=150>
+</p>
+
+<h3 align="center">
+
+[![Tests](https://github.com/janosh/pdf-compressor/workflows/Tests/badge.svg)](https://github.com/janosh/pdf-compressor/actions)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/janosh/pdf-compressor/main.svg)](https://results.pre-commit.ci/latest/github/janosh/pdf-compressor/main)
+[![PyPI](https://img.shields.io/pypi/v/pdf-compressor?logo=pypi&logoColor=white)](https://pypi.org/project/pdf-compressor)
+[![Requires Python 3.11+](https://img.shields.io/badge/Python-3.11+-blue.svg?logo=python&logoColor=white)](https://python.org/downloads)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/pdf-compressor?logo=icloud&logoColor=white)](https://pypistats.org/packages/pdf-compressor)
+
+</h3>
+
+Command line PDF compression powered by the free [iLovePDF API](https://developer.ilovepdf.com).
+
+**Why?** iLovePDF delivers the best PDF compression I've seen but their web UI doesn't support automation and can be cumbersome when dealing with many files.
+
+## Installation
+
+```sh
+pip install pdf-compressor
+```
+
+## Usage
+
+First, tell `pdf-compressor` your iLovePDF API key (if you haven't yet, get one by signing up at <https://developer.ilovepdf.com/signup>):
+
+```sh
+pdf-compressor --set-api-key project_public_7c854a9db0...
+```
+
+Then start compressing!
+
+```sh
+pdf-compressor **/*.pdf
+```
+
+## Options
+
+| Flags                      | Default         | Description                                                                                                                                                                                                                 |
+| -------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-i/--inplace`             | `False`         | Whether to compress PDFs in place.                                                                                                                                                                                          |
+| `-s/--suffix`              | `'-compressed'` | String to append to the filename of compressed PDFs. Mutually exclusive with `--inplace`.                                                                                                                                   |
+| `--cl/--compression-level` | `'recommended'` | How hard to squeeze the file size. One of `'low'`, `'recommended'`, `'extreme'`. `'extreme'` noticeably degrades quality of embedded bitmap images.                                                                         |
+| `--set-api-key`            |                 | Set the public key needed to authenticate with the iLovePDF API. You only need to do this once to start using.                                                                                                              |
+| `--report-quota`           |                 | Report the number of remaining file operations in the current billing cycle for the stored iLovePDF API key.                                                                                                                |
+| `--debug`                  | `False`         | When true, iLovePDF won't process the request but only reports the parameters that would have been sent to the server.                                                                                                      |
+| `--verbose`                | `False`         | When true, progress will be reported while tasks are running.                                                                                                                                                               |
+| `-v/--version`             |                 | Get the version number of `pdf-compressor`.                                                                                                                                                                                 |
+| `--on-no-files`            | `'ignore'`      | What to do when no input PDFs received. One of `'ignore'` or `'error'`, former exits 0, latter raises `ValueError`. Can be useful when using `pdf-compressor` in shell scripts.                                             |
+| `--on-bad-files`           | `'error'`       | How to behave when receiving input files that don't appear to be PDFs. One of `'error'`, `'warn'`, `'ignore'`. Error type will be `ValueError`. Code used to check if something is PDF: `filepath.lower().endswith(".pdf")` |

pdf_compressor-0.4.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pdf_compressor/__init__.py,sha256=sLqwhVZfWzCGfayiRBLS1c4BxVDI-6Y-yaSB3Ceew4s,331
+pdf_compressor/ilovepdf.py,sha256=ORJ6xkMiMml5_EgFce5LuqcJQOnhd84aWqcLm2jHdCs,11929
+pdf_compressor/main.py,sha256=Y5wj0XbRkQzVwoUQB8tmIe_rvyt7O6R5694x7dn52Iw,11236
+pdf_compressor/utils.py,sha256=JgoGzbDErRkw12eR-L9ghUJF-LhIuWwu_03laLH-HKs,8083
+pdf_compressor-0.4.0.dist-info/METADATA,sha256=drEIXQ0qBs8EL2InntTzWF_msegcZ0b8_Bos8-HK1uM,6972
+pdf_compressor-0.4.0.dist-info/WHEEL,sha256=JNWh1Fm1UdwIQV075glCn4MVuCRs0sotJIq-J6rbxCU,109
+pdf_compressor-0.4.0.dist-info/entry_points.txt,sha256=NPlZlhyjfB1Ut_-twe-BdIKm4_VokXGxqM1wj2oskMs,55
+pdf_compressor-0.4.0.dist-info/top_level.txt,sha256=06mKqczyFT7D3p3ZhfvR4wRFglo3E3ycL4n-V2ychbA,15
+pdf_compressor-0.4.0.dist-info/RECORD,,

pdf_compressor-0.4.0.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any
+

pdf_compressor-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdf-compressor = pdf_compressor:main

pdf_compressor-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pdf_compressor