pdf-helper 0.1.0__tar.gz

pdf_helper-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.3
+Name: pdf-helper
+Version: 0.1.0
+Summary: A simple python script that helps with doing simple stuff with PDFs.
+Author: CodeWriter21(Mehrad Pooryoussof)
+Author-email: CodeWriter21(Mehrad Pooryoussof) <CodeWriter21@gmail.com>
+License: MIT
+Requires-Dist: log21>=3.0.0
+Requires-Dist: pypdfium2>=4.30.0
+Requires-Dist: pillow>=11.0.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+PDF-Helper
+==========
+
+A simple python package that helps with doing simple stuff with PDFs.
+
+Features
+--------
+
++ [x] **Merge PDFs**: Merge multiple PDFs into one PDF
++ [x] **Split PDFs**: Split a PDF into multiple PDFs, each containing a range of pages from
+      the original PDF
++ [x] **Export as image**: Export designated pages from a PDF as image files
++ [x] **Remove pages**: Remove designated pages from a PDF
++ [ ] Encrypt a PDF
++ [ ] Decrypt a PDF
++ [ ] Add watermark to a PDF
++ [ ] Extract images from a PDF
++ [x] **Extract text**: Export text from a PDF file and optionally save it to a text file
++ [ ] Extract links from a PDF
++ [x] **Image to PDF**: Export one or multiple images as a PDF file
+
+If you want any other feature to be added, feel free to open an [issue](https://github.com/MPCodeWriter21/PDF-To-Image/issues)
+or fork the repo and make a [pull request](https://github.com/MPCodeWriter21/PDF-To-Image/pulls)
+after adding your contribution.
+
+Usage
+-----
+
+### Installation
+
+You can install PDF-Helper via pip:
+
+```bash
+pip install pdf-helper
+```
+
+And run it using the command line:
+
+```bash
+pdf-helper <command> [options]
+```
+
+Or you can use uvx to run the package without installing it in a specific python environment:
+
+```bash
+uvx pdf-helper <command> [options]
+```
+
+You can also clone the repository and use `uv run`:
+
+```bash
+git clone https://github.com/MPCodeWriter21/PDF-Helper.git
+cd PDF-Helper
+uv run pdf-helper <command> [options]
+```
+
+### Merge PDFs
+
+Merge multiple PDFs into one PDF:
+
+```bash
+pdf-helper merge -i <input_file_1> <input_file_2>... <input_file_n> -o <output_file>
+
+# E.g. Merge PDFs 1, 2 and 3 into a new PDF
+pdf-helper merge -i 1.pdf 2.pdf 3.pdf -o new.pdf
+```
+
+### Split PDFs
+
+Split a PDF into multiple PDFs, each containing a range of pages:
+
+```bash
+pdf-helper split -i <input_file> -o <output_folder> -s <split_point_1>,<split_point_2>
+
+# E.g. Split a PDF into three PDFs, one with pages 1-10, the second with pages 11-20 and
+# the third with pages 21-end
+pdf-helper split -i my-pdf.pdf -o my-split-pdfs -s 10,20
+
+# E.g. Split a PDF into PDFs each containing one page
+pdf-helper split -i my-pdf.pdf -o my-split-pdfs  # No need to specify split points
+```
+
+### Export PDF pages as image files
+
+Export PDF pages as image files:
+
+```bash
+pdf-helper to-image -i <input_file> -o <output_folder> \
+        -p <page_number_1>,<page_number_2>,...,<page_number_n> -s <scale_factor>
+
+# E.g. Export pages 1, 2, 3 and 6 from a PDF with scale factor 1
+pdf-helper to-image -i 1.pdf -o images -p 1-3,6 -s 1
+
+# E.g. Export all pages from a PDF with scale 2
+pdf-helper to-image -i my-pdf.pdf -o my-images
+```
+
+### Remove pages from a PDF
+
+Remove pages from a PDF:
+
+```bash
+pdf-helper remove-pages -i <input_file> -o <output_file> -p <page_number_1>,<page_number_2>,...,<page_number_n>
+
+# E.g. Remove pages 1, 2, 3 and 6 from a PDF
+pdf-helper remove-pages -i 1.pdf -o new.pdf -p 1-3,6
+```
+
+### Export text from a PDF
+
+To extract text from a PDF file and export them to text files you can do as follows:
+
+```bash
+pdf-helper extract-text -i <input_file> -o <output_file_name>
+
+# E.g. Extract text from a PDF named my-pdf.pdf and save it to my-text.txt
+pdf-helper extract-text -i my-pdf.pdf -o my-text.txt
+```
+
+### Export one or multiple images as a PDF file
+
+You simply provide the script with your images, and it will create a PDF file with them:
+
+```bash
+pdf-helper image-to-pdf -i <image_1> <image_2> <image_3> ... -o <output_file>
+
+# E.g. Take 1.png, 2.jpg, and 3.png and create a PDF named 123.pdf and override
+# if already exists
+pdf-helper image-to-pdf -i 1.png 2.jpg 3.png -o 123.pdf -f
+```
+
+About
+-----
+
+Author: [CodeWriter21](https://github.com/MPCodeWriter21)
+
+GitHub: [MPCodeWriter21/PDF-Helper](https://github.com/MPCodeWriter21/PDF-Helper)
+
+Donations
+---------
+
+Your donations are very welcome: [nowpayments.io](https://nowpayments.io/donation/MehradP21)
+
+You can also consider donating a
+[Star](https://github.com/MPCodeWriter21/PDF-Helper) to the repo.
+
+License
+-------
+
+This project is licensed under the MIT License.
+
+See the [LICENSE](LICENSE)
+
+References
+----------
+
++ [pypdfium2](https://pypdfium2.readthedocs.io/en/stable/readme.html)
++ [PILlow](https://pillow.readthedocs.io/en/stable/)
++ [log21](https://GitHub.com/MPCodeWriter21/log21)

pdf_helper-0.1.0/README.md

@@ -0,0 +1,159 @@
+PDF-Helper
+==========
+
+A simple python package that helps with doing simple stuff with PDFs.
+
+Features
+--------
+
++ [x] **Merge PDFs**: Merge multiple PDFs into one PDF
++ [x] **Split PDFs**: Split a PDF into multiple PDFs, each containing a range of pages from
+      the original PDF
++ [x] **Export as image**: Export designated pages from a PDF as image files
++ [x] **Remove pages**: Remove designated pages from a PDF
++ [ ] Encrypt a PDF
++ [ ] Decrypt a PDF
++ [ ] Add watermark to a PDF
++ [ ] Extract images from a PDF
++ [x] **Extract text**: Export text from a PDF file and optionally save it to a text file
++ [ ] Extract links from a PDF
++ [x] **Image to PDF**: Export one or multiple images as a PDF file
+
+If you want any other feature to be added, feel free to open an [issue](https://github.com/MPCodeWriter21/PDF-To-Image/issues)
+or fork the repo and make a [pull request](https://github.com/MPCodeWriter21/PDF-To-Image/pulls)
+after adding your contribution.
+
+Usage
+-----
+
+### Installation
+
+You can install PDF-Helper via pip:
+
+```bash
+pip install pdf-helper
+```
+
+And run it using the command line:
+
+```bash
+pdf-helper <command> [options]
+```
+
+Or you can use uvx to run the package without installing it in a specific python environment:
+
+```bash
+uvx pdf-helper <command> [options]
+```
+
+You can also clone the repository and use `uv run`:
+
+```bash
+git clone https://github.com/MPCodeWriter21/PDF-Helper.git
+cd PDF-Helper
+uv run pdf-helper <command> [options]
+```
+
+### Merge PDFs
+
+Merge multiple PDFs into one PDF:
+
+```bash
+pdf-helper merge -i <input_file_1> <input_file_2>... <input_file_n> -o <output_file>
+
+# E.g. Merge PDFs 1, 2 and 3 into a new PDF
+pdf-helper merge -i 1.pdf 2.pdf 3.pdf -o new.pdf
+```
+
+### Split PDFs
+
+Split a PDF into multiple PDFs, each containing a range of pages:
+
+```bash
+pdf-helper split -i <input_file> -o <output_folder> -s <split_point_1>,<split_point_2>
+
+# E.g. Split a PDF into three PDFs, one with pages 1-10, the second with pages 11-20 and
+# the third with pages 21-end
+pdf-helper split -i my-pdf.pdf -o my-split-pdfs -s 10,20
+
+# E.g. Split a PDF into PDFs each containing one page
+pdf-helper split -i my-pdf.pdf -o my-split-pdfs  # No need to specify split points
+```
+
+### Export PDF pages as image files
+
+Export PDF pages as image files:
+
+```bash
+pdf-helper to-image -i <input_file> -o <output_folder> \
+        -p <page_number_1>,<page_number_2>,...,<page_number_n> -s <scale_factor>
+
+# E.g. Export pages 1, 2, 3 and 6 from a PDF with scale factor 1
+pdf-helper to-image -i 1.pdf -o images -p 1-3,6 -s 1
+
+# E.g. Export all pages from a PDF with scale 2
+pdf-helper to-image -i my-pdf.pdf -o my-images
+```
+
+### Remove pages from a PDF
+
+Remove pages from a PDF:
+
+```bash
+pdf-helper remove-pages -i <input_file> -o <output_file> -p <page_number_1>,<page_number_2>,...,<page_number_n>
+
+# E.g. Remove pages 1, 2, 3 and 6 from a PDF
+pdf-helper remove-pages -i 1.pdf -o new.pdf -p 1-3,6
+```
+
+### Export text from a PDF
+
+To extract text from a PDF file and export them to text files you can do as follows:
+
+```bash
+pdf-helper extract-text -i <input_file> -o <output_file_name>
+
+# E.g. Extract text from a PDF named my-pdf.pdf and save it to my-text.txt
+pdf-helper extract-text -i my-pdf.pdf -o my-text.txt
+```
+
+### Export one or multiple images as a PDF file
+
+You simply provide the script with your images, and it will create a PDF file with them:
+
+```bash
+pdf-helper image-to-pdf -i <image_1> <image_2> <image_3> ... -o <output_file>
+
+# E.g. Take 1.png, 2.jpg, and 3.png and create a PDF named 123.pdf and override
+# if already exists
+pdf-helper image-to-pdf -i 1.png 2.jpg 3.png -o 123.pdf -f
+```
+
+About
+-----
+
+Author: [CodeWriter21](https://github.com/MPCodeWriter21)
+
+GitHub: [MPCodeWriter21/PDF-Helper](https://github.com/MPCodeWriter21/PDF-Helper)
+
+Donations
+---------
+
+Your donations are very welcome: [nowpayments.io](https://nowpayments.io/donation/MehradP21)
+
+You can also consider donating a
+[Star](https://github.com/MPCodeWriter21/PDF-Helper) to the repo.
+
+License
+-------
+
+This project is licensed under the MIT License.
+
+See the [LICENSE](LICENSE)
+
+References
+----------
+
++ [pypdfium2](https://pypdfium2.readthedocs.io/en/stable/readme.html)
++ [PILlow](https://pillow.readthedocs.io/en/stable/)
++ [log21](https://GitHub.com/MPCodeWriter21/log21)

pdf_helper-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "PDF-Helper"
+version = "0.1.0"
+authors = [
+  {name = "CodeWriter21(Mehrad Pooryoussof)", email = "CodeWriter21@gmail.com"}
+]
+description = "A simple python script that helps with doing simple stuff with PDFs."
+readme = {file = "README.md", content-type = "text/markdown"}
+license = {text = "MIT", file = "LICENSE"}
+requires-python = ">=3.9"
+dependencies = [
+    "log21>=3.0.0",
+    "pypdfium2>=4.30.0",
+    "Pillow>=11.0.0"
+]
+
+[project.scripts]
+pdf-helper = "pdf_helper:__main__.main"
+
+[build-system]
+requires = ["uv_build>=0.8.22,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.yapf]
+column_limit = 88
+split_before_dot = true
+split_before_first_argument = true
+dedent_closing_brackets = true
+
+[tool.isort]
+line_length = 88
+combine_as_imports = true
+length_sort = true
+order_by_type = true
+
+[tool.docformatter]
+recursive = true
+wrap-summaries = 88
+wrap-descriptions = 88
+
+[tool.ruff]
+show-fixes = true
+exclude = ["migrations"]
+target-version = "py39"
+line-length = 88
+
+[tool.ruff.lint]
+extend-select = ["C4", "SIM", "TCH", "ANN", "N", "B"]

pdf_helper-0.1.0/src/pdf_helper/__init__.py

@@ -0,0 +1,294 @@
+# PDF-Helper
+
+import io
+import os
+import sys
+from typing import Optional, Sequence, Collection
+from pathlib import Path
+
+import log21
+import pypdfium2 as pdfium
+from PIL import Image
+from pypdfium2 import PdfImage, PdfBitmap, PdfDocument
+
+__all__ = [
+    'merge_pdfs', 'remove_pages', 'pdf_to_image', 'extract_text', 'image_to_pdf',
+    'split_pdf', 'watermark_pdf'
+]
+
+
+def merge_pdfs(
+    input_files: Sequence[str | Path | io.TextIOWrapper],
+    output_stream: str | Path | io.BytesIO | io.BufferedWriter
+) -> int:
+    """Merge PDF files.
+
+    :param input_files: List of PDF files to concatenate.
+    :param output_stream: Output stream to write to.
+    :return: Number of pages of the merged PDF.
+    """
+    writer = PdfDocument.new()
+    for input_file in input_files:
+        log21.info(f'Adding {input_file}...')
+        reader = PdfDocument(input_file)
+        writer.import_pages(reader)
+    writer.save(output_stream)
+    return len(writer)
+
+
+def remove_pages(
+    input_file: str | Path | io.BytesIO | io.TextIOWrapper,
+    pages_to_remove: Collection[int],
+    output_stream: str | Path | io.BytesIO | io.BufferedWriter
+) -> int:
+    """Remove pages from a PDF file.
+
+    :param input_file: PDF file to remove pages from.
+    :param pages_to_remove: List of pages to remove. A one based collection of indices.
+    :param output_stream: Output stream to write to.
+    :return: Number of pages removed.
+    """
+    writer = PdfDocument.new()
+    reader = PdfDocument(input_file)
+    pages_to_remove = tuple((i - 1 for i in pages_to_remove))
+    pages_to_add = [i for i in range(len(reader)) if i not in pages_to_remove]
+    writer.import_pages(reader, pages_to_add)
+    writer.save(output_stream, version=reader.get_version())
+    return len(reader) - len(pages_to_add)
+
+
+def pdf_to_image(
+    input_file: str | Path,
+    output_directory: str | Path,
+    pages_to_convert: Optional[Collection[int]] = None,
+    scale: int = 2
+) -> int:
+    """Convert a PDF file to a series of images.
+
+    :param input_file: PDF file to convert.
+    :param output_directory: Directory to write images to.
+    :param scale: Scale of each image.
+    :return: Number of pages converted to image
+    """
+    if isinstance(input_file, str):
+        input_file = Path(input_file)
+    if isinstance(output_directory, str):
+        output_directory = Path(output_directory)
+    if not output_directory.exists():
+        output_directory.mkdir(parents=True)
+
+    pdf = pdfium.PdfDocument(input_file)
+    name = input_file.name.rsplit('.', maxsplit=1)[0]
+    # Number of digits each number in the filename should have
+    length = len(str(len(pdf)))
+    if not pages_to_convert:
+        for i, page in enumerate(pdf, start=1):
+            log21.info(f'Converting page {i}...', end='\r')
+            image = page.render(scale=scale).to_pil()
+            image.save(output_directory / f'{name}-{i:0>{length}}.png')
+        return len(pdf)
+    for i, page in enumerate(pdf, start=1):
+        if i not in pages_to_convert:
+            continue
+        log21.info(f'Converting page {i}...', end='\r')
+        image = page.render(scale=scale).to_pil()
+        image.save(output_directory / f'{name}-{i:0>{length}}.png')
+    return len(pages_to_convert)
+
+
+def extract_text(
+    input_file: str | Path | io.BytesIO | io.TextIOWrapper,
+    pages_to_extract_from: Optional[Collection[int]] = None,
+    max_number_of_characters: int = -1,
+    reverse_lines: bool = False
+) -> str:
+    """Extract text from a PDF file.
+
+    :param input_file: PDF file to extract text from.
+    :param pages_to_extract_from: Pages to extract text from.
+    :param max_number_of_characters: Maximum number of characters to extract in total.
+    :param reverse_lines: Reverse the characters in each line (Useful for Persian text)
+    :return: Extracted text.
+    """
+    pdf = pdfium.PdfDocument(input_file)
+    text = ''
+    if pages_to_extract_from:
+        pages_to_extract_from = sorted(pages_to_extract_from)
+        if pages_to_extract_from[0] < 1:
+            log21.critical('Pages must be >= 1')
+            sys.exit(1)
+        if pages_to_extract_from[-1] > len(pdf):
+            log21.critical(
+                f'Page {pages_to_extract_from[-1]} does not exist in `{input_file}`'
+            )
+            sys.exit(1)
+        log21.info(
+            f'Extracting text from {len(pages_to_extract_from)} page' +
+            ('s' if len(pages_to_extract_from) > 1 else '') + f' from `{input_file}`...'
+        )
+        count = max_number_of_characters
+        for i, page in enumerate(pdf):
+            i = i + 1
+            if i not in pages_to_extract_from:
+                continue
+            log21.info(f'Extracting text from page {i}...', end='\r')
+            text += page.get_textpage().get_text_range(count=count)
+            if count == 0:
+                break
+            if count > 0:
+                count = max_number_of_characters - len(text)
+    else:
+        count = max_number_of_characters
+        for page in pdf:
+            text += page.get_textpage().get_text_range(count=count)
+            if count == 0:
+                break
+            if count > 0:
+                count = max_number_of_characters - len(text)
+            text += '\n'
+    log21.info('\rDone!')
+
+    if reverse_lines:
+        reversed_text = ''
+        log21.info('Reversing the lines...', end='\r')
+        for i, line in enumerate(text.split(os.linesep), start=1):
+            log21.info('Reversing line %d...', args=(i, ), end='\r')
+            reversed_text += ''.join(reversed(line)) + os.linesep
+        log21.info('\rReversed every line!')
+        text = reversed_text
+
+    return text
+
+
+def image_to_pdf(
+    input_files: Sequence[str | bytes | Path | os.PathLike[str] | io.BytesIO],
+    output_stream: str | Path | io.BytesIO | io.BufferedWriter
+) -> int:
+    """Convert images to a PDF file.
+
+    :param input_files: List of images to convert.
+    :param output_stream: Output stream to write to.
+    :return: Number of pages in the output PDF
+    """
+    writer = PdfDocument.new()
+    for input_file in input_files:
+        log21.info(f'Adding {input_file}...')
+        # Open the image file
+        image = Image.open(input_file)
+        # Create a bitmap from the image
+        bitmap = PdfBitmap.from_pil(image)
+        # Create a PdfImage object from the bitmap
+        pdf_image = PdfImage.new(writer)
+        pdf_image.set_bitmap(bitmap)
+        matrix = pdfium.PdfMatrix().scale(bitmap.width, bitmap.height)
+        pdf_image.set_matrix(matrix)
+        # Create a new page and insert the PdfImage object
+        page = writer.new_page(bitmap.width, bitmap.height)
+        page.insert_obj(pdf_image)
+        page.gen_content()
+        # Close the objects
+        page.close()
+        pdf_image.close()
+        bitmap.close()
+        image.close()
+    writer.save(output_stream)
+    return len(writer)
+
+
+def split_pdf(
+    input_file: str | Path,
+    output_directory: str | Path,
+    split_points: Optional[Collection[int]] = None
+) -> int:
+    """Split a PDF file into multiple files.
+
+    :param input_file: PDF file to split.
+    :param output_directory: Directory to write split files to.
+    :param split_points: Pages to split. If None, splits every page into a separate
+        file.
+    :return: Number of pages split.
+    """
+    if isinstance(input_file, str):
+        input_file = Path(input_file)
+    if isinstance(output_directory, str):
+        output_directory = Path(output_directory)
+    if not output_directory.exists():
+        output_directory.mkdir(parents=True)
+
+    pdf = pdfium.PdfDocument(input_file)
+    if not split_points:
+        split_points = range(1, len(pdf) - 1)
+    split_points = [0] + sorted(set(split_points)) + [len(pdf)]
+
+    for i in range(len(split_points) - 1):
+        start = split_points[i]
+        end = split_points[i + 1]
+        if start < 0 or end > len(pdf):
+            log21.warning(
+                f'Split points {start + 1} to {end} are out of bounds for '
+                f'input file `{input_file}`.'
+            )
+            continue
+
+        log21.info(f'Splitting pages {start + 1} to {end}...')
+        writer = PdfDocument.new()
+        writer.import_pages(pdf, range(start, end))
+        output_file = output_directory / f'{input_file.stem}_part_{i + 1}.pdf'
+        try:
+            writer.save(output_file)
+            log21.info(f'Saved split file to {output_file}')
+        except PermissionError:
+            log21.critical(
+                f'Cannot write to output file `{output_file}`.\n'
+                'Check the file permissions and close any applications that may be '
+                'using the file, then try again.'
+            )
+            sys.exit(1)
+        finally:
+            writer.close()
+
+    return len(split_points) - 1
+
+
+def watermark_pdf(
+    input_file: str | Path | io.BytesIO | io.TextIOWrapper,
+    output_file: str | Path,
+    watermark_text: str,
+    position: str = 'center',
+    font_size: int = 36,
+    opacity: float = 0.1,
+    rotation: float = 45.0
+) -> int:
+    """Split a PDF file into multiple files.
+
+    :param input_file: PDF file to split.
+    :param output_file:
+    :param watermark_text: Text to use as watermark.
+    :param position: Position of watermark. One of 'center' or '50% 50%', 'top-left' or
+        '0% 0%', 'top-right' or '100% 0%', 'bottom-left' or '0% 100%', etc.
+        You can also use absolute values like '100 100'.
+        Note: The position is relative to the center of the watermark text.
+    :param font_size: Font size of watermark text.
+    :param opacity: Opacity of watermark text. Between 0.0 and 1.0.
+    :param rotation: Rotation of watermark text in degrees.
+    :return: Number of pages split.
+    """
+    if isinstance(input_file, str):
+        input_file = Path(input_file)
+    if isinstance(output_file, str):
+        output_file = Path(output_file)
+    if len(watermark_text) == 0:
+        raise ValueError('Watermark text cannot be empty.')
+    if font_size < 1:
+        raise ValueError('Font size must be at least 1.')
+    if opacity < 0.0 or opacity > 1.0:
+        raise ValueError('Opacity must be between 0.0 and 1.0.')
+
+    pdf = pdfium.PdfDocument(input_file)
+    watermark = pdfium.PdfDocument.new()
+    _page = watermark.new_page(512, 512)
+    for i, _page in enumerate(pdf):
+        log21.info(f'Adding watermark to page {i + 1}...', end='\r')
+    log21.info('\rDone!')
+    pdf.save(output_file)
+    return len(pdf)

pdf_helper-0.1.0/src/pdf_helper/__main__.py

@@ -0,0 +1,422 @@
+#!/usr/bin/env python3
+
+# yapf: disable
+
+import os
+import sys
+import importlib.util
+from typing import Optional, Sequence
+from pathlib import Path
+
+import log21
+from log21.colors import RED, GREEN, RESET
+
+from . import (split_pdf, merge_pdfs, extract_text, image_to_pdf, pdf_to_image,
+               remove_pages, watermark_pdf)
+from .utils import parse_pages
+
+# yapf: ensable
+
+def merge_pdfs_entry_point(
+    input_paths: Sequence[Path],
+    output_path: Path,
+    /,
+    force: bool = False,
+    verbose: bool = False
+) -> None:
+    """Merge PDF files.
+
+    :param output_path: Path to write concatenated PDF file to.
+    :param input_paths: List of PDF files to concatenate.
+    :param force: Force overwrite of output file.
+    :param verbose: Print verbose output.
+    """
+    if len(input_paths) < 2:
+        log21.critical('Must provide at least two input files.')
+        sys.exit(1)
+    if output_path.exists() and not force:
+        log21.critical('Output file already exists.')
+        sys.exit(1)
+    if output_path.absolute() in (path.absolute() for path in input_paths):
+        log21.critical('Input and output files cannot be the same.')
+        sys.exit(1)
+    if verbose:
+        log21.basic_config(level=log21.INFO)
+
+    for path in input_paths:
+        if not path.exists():
+            log21.critical(f'Input file `{path}` does not exist.')
+            sys.exit(1)
+
+    log21.info(f'Concatenating {len(input_paths)} files to {output_path}')
+    try:
+        with open(output_path, 'wb') as output_file:
+            merge_pdfs(input_paths, output_file)
+    except PermissionError:
+        log21.critical(
+            f'Cannot write to output file `{output_path}`.\n'
+            'Check the file permissions and close any applications that may be using '
+            'the file, then try again.'
+        )
+        sys.exit(1)
+
+
+def remove_pages_entry_point(
+    input_path: Path,
+    output_path: Path,
+    pages_to_remove: str,
+    /,
+    force: bool = False,
+    verbose: bool = False
+) -> None:
+    """Remove pages from a PDF file.
+
+    :param input_path: Path to PDF file to remove pages from.
+    :param output_path: Path to write PDF file to.
+    :param pages_to_remove: Comma-separated list of pages to remove.
+        Example: '1-5,7,9-11'
+    :param force: Force overwrite of output file.
+    :param verbose: Print verbose output.
+    """
+    if not input_path.exists():
+        log21.critical(f'Input file `{input_path}` does not exist.')
+        sys.exit(1)
+    if output_path.exists() and not force:
+        log21.critical('Output file already exists.')
+        sys.exit(1)
+    if input_path.absolute() == output_path.absolute():
+        log21.critical('Input and output files cannot be the same.')
+        sys.exit(1)
+    if verbose:
+        log21.basic_config(level=log21.INFO)
+
+    try:
+        pages_to_remove_ = parse_pages(pages_to_remove)
+    except ValueError:
+        log21.critical(f'Invalid pages string: `{pages_to_remove}`')
+        sys.exit(1)
+
+    log21.info(
+        f'Removing {len(pages_to_remove_)} page' + (
+            's: ' + ', '.join(str(page) for page in pages_to_remove_[:-1]) +
+            ' and' if len(pages_to_remove_) > 2 else ':'
+        ) + f' {pages_to_remove_[-1]} from `{input_path}`'
+    )
+    try:
+        with open(output_path, 'wb') as output_file:
+            number_of_removed_pages = remove_pages(
+                input_path, pages_to_remove_, output_file
+            )
+            log21.info(
+                f'Removed {number_of_removed_pages} page' +
+                ('s' if number_of_removed_pages > 1 else '') + '!'
+            )
+    except PermissionError:
+        log21.critical(
+            f'Cannot write to output file `{output_path}`.\n'
+            'Check the file permissions and close any applications that may be using '
+            'the file, then try again.'
+        )
+        sys.exit(1)
+
+
+def pdf_to_image_entry_point(
+    input_path: Path,
+    output_directory: Path,
+    /,
+    pages_to_convert: Optional[str] = None,
+    scale: int = 2,
+    force: bool = False,
+    verbose: bool = False
+) -> None:
+    """Convert a PDF file to a series of images.
+
+    :param input_path: Path to PDF file to convert.
+    :param output_directory: Path to directory to write images to.
+    :param pages_to_convert: Comma-separated list of pages to convert.
+        Example: '1-5,7,9-11'
+    :param scale: Scale of each image.
+    :param force: Force overwrite of output directory.
+    :param verbose: Print verbose output.
+    """
+    if importlib.util.find_spec('PIL') is None:
+        log21.error('PIL must be installed to use this feature.')
+        cmd = 'python -m pip install "Pillow>=10.1.0"'
+        answer = log21.input(
+            f'[{RED}?{RESET}] Do you want to install it? ({GREEN}{cmd}{RESET})'
+        )
+        if answer.lower().startswith('y'):
+            log21.print(f'[{GREEN}+{RESET}] Installing Pillow...')
+            os.system(cmd)
+        sys.exit(1)
+    if not input_path.exists():
+        log21.critical(f'Input file `{input_path}` does not exist.')
+        sys.exit(1)
+    if output_directory.exists() and not output_directory.is_dir():
+        log21.critical(f'Output path `{output_directory}` is not a directory.')
+        sys.exit(1)
+    if output_directory.exists() and os.listdir(output_directory) and not force:
+        log21.critical(f'Output directory `{output_directory}` already exists.')
+        sys.exit(1)
+    if verbose:
+        log21.basic_config(level=log21.INFO)
+
+    pages_to_convert_ = None
+    if pages_to_convert:
+        try:
+            pages_to_convert_ = parse_pages(pages_to_convert)
+        except ValueError:
+            log21.critical(f'Invalid pages string: `{pages_to_convert}`')
+            sys.exit(1)
+        log21.info(
+            f'Converting {len(pages_to_convert_)} page' +
+            ('s' if len(pages_to_convert_) > 2 else '') +
+            f' from `{input_path}` to image...'
+        )
+    else:
+        log21.info(f'Converting `{input_path}` to images...')
+
+    pdf_to_image(input_path, output_directory, pages_to_convert_, scale)
+    log21.info('\rDone!')
+
+
+def extract_text_entry_point(
+    input_path: Path,
+    /,
+    output_path: Optional[Path] = None,
+    pages_to_extract_from: Optional[str] = None,
+    max_number_of_characters: int = -1,
+    characters_to_split: int = 0,
+    reverse_lines: bool = False,
+    force: bool = False,
+    verbose: bool = False
+) -> None:
+    """Extract text from a PDF file.
+
+    :param input_path: Path to PDF file to extract text from.
+    :param output_path: Path to write extracted text to. (Writes to stdout if not
+        provided)
+    :param pages_to_extract_from: Pages to extract text from. Example: '1-5,7,9-11'
+    :param max_number_of_characters: Maximum number of characters to extract in total.
+    :param characters_to_split: Create a new file if the number of characters in the
+        extracted text exceeds this value.
+    :param reverse_lines: Reverse the characters in each line (Useful for Persian text)
+    :param force: Force overwrite of output file.
+    :param verbose: Print verbose output.
+    """
+    if not input_path.exists():
+        log21.critical(f'Input file `{input_path}` does not exist.')
+        sys.exit(1)
+    if output_path and output_path.exists() and not force:
+        log21.critical(f'Output `{output_path}` already exists.')
+        sys.exit(1)
+    if verbose:
+        log21.basic_config(level=log21.INFO)
+
+    pages_to_extract_from_ = None
+    if pages_to_extract_from:
+        try:
+            pages_to_extract_from_ = parse_pages(pages_to_extract_from)
+        except ValueError:
+            log21.critical(f'Invalid pages string: `{pages_to_extract_from}`')
+            sys.exit(1)
+        log21.info(
+            f'Extracting text from {len(pages_to_extract_from_)} page' +
+            ('s' if len(pages_to_extract_from_) > 2 else '') +
+            f' from `{input_path}`...'
+        )
+    else:
+        log21.info(f'Extracting text from `{input_path}`...')
+
+    text = extract_text(
+        input_path, pages_to_extract_from_, max_number_of_characters, reverse_lines
+    )
+    if output_path:
+        if not characters_to_split:
+            with output_path.open('w', encoding='utf-8') as file:
+                file.write(text)
+            return
+        i = 1
+        stem = output_path.stem
+        while len(text) > characters_to_split:
+            output_path_ = output_path.with_name(stem + f'_{i}{output_path.suffix}')
+            with output_path_.open('w', encoding='utf-8') as file:
+                file.write(text[:characters_to_split])
+            text = text[characters_to_split:]
+            output_path = output_path_
+            i += 1
+        with output_path.open('w', encoding='utf-8') as file:
+            file.write(text)
+    else:
+        print(text)
+    log21.info('\rDone!')
+
+
+def image_to_pdf_entry_point(
+    input_paths: Sequence[Path],
+    output_path: Path,
+    /,
+    force: bool = False,
+    verbose: bool = False
+) -> None:
+    """Convert images to a PDF file.
+
+    :param input_paths: List of images to convert.
+    :param output_path: Path to write PDF file to.
+    :param force: Force overwrite of output file.
+    :param verbose: Print verbose output.
+    """
+    if len(input_paths) < 1:
+        log21.critical('Must provide at least one input file.')
+        sys.exit(1)
+    if output_path.exists() and not force:
+        log21.critical('Output file already exists.')
+        sys.exit(1)
+    if verbose:
+        log21.basic_config(level=log21.INFO)
+
+    for path in input_paths:
+        if not path.exists():
+            log21.critical(f'Input file `{path}` does not exist.')
+            sys.exit(1)
+
+    log21.info(f'Converting {len(input_paths)} images to `{output_path}`...')
+    try:
+        with open(output_path, 'wb') as output_file:
+            image_to_pdf(input_paths, output_file)
+    except PermissionError:
+        log21.critical(
+            f'Cannot write to output file `{output_path}`.\n'
+            'Check the file permissions and close any applications that may be using '
+            'the file, then try again.'
+        )
+        sys.exit(1)
+
+
+def split_pdf_entry_point(
+    input_path: Path,
+    output_directory: Path,
+    /,
+    split_points: Optional[str] = None,
+    force: bool = False,
+    verbose: bool = False
+) -> None:
+    """Split a PDF file into multiple files.
+
+    :param input_path: Path to PDF file to split.
+    :param output_directory: Path to directory to write split files to.
+    :param split_points: Comma-separated list of pages to split. Example: '5,7,9'
+    :param force: Force overwrite of output directory.
+    :param verbose: Print verbose output.
+    """
+    if not input_path.exists():
+        log21.critical(f'Input file `{input_path}` does not exist.')
+        sys.exit(1)
+    if output_directory.exists() and not output_directory.is_dir():
+        log21.critical(f'Output path `{output_directory}` is not a directory.')
+        sys.exit(1)
+    if output_directory.exists() and os.listdir(output_directory) and not force:
+        log21.critical(f'Output directory `{output_directory}` already exists.')
+        sys.exit(1)
+    if verbose:
+        log21.basic_config(level=log21.INFO)
+
+    split_points_ = None
+    if split_points:
+        try:
+            split_points_ = parse_pages(split_points)
+        except ValueError:
+            log21.critical(f'Invalid pages string: `{split_points}`')
+            sys.exit(1)
+
+    log21.info(f'Splitting `{input_path}`...')
+    number_of_pdfs = split_pdf(input_path, output_directory, split_points_)
+    if number_of_pdfs > 1:
+        log21.info(f'Split {input_path} to {number_of_pdfs} PDF files!')
+
+
+def watermark_pdf_entry_point(
+    input_path: Path,
+    output_path: Path,
+    watermark_text: str,
+    /,
+    position: str = 'center',
+    font_size: int = 36,
+    opacity: float = 0.1,
+    rotation: float = 45.0,
+    force: bool = False,
+    verbose: bool = False
+) -> None:
+    """Add a watermark to a PDF file.
+
+    :param input_path: Path to PDF file to add watermark to.
+    :param output_path: Path to write watermarked PDF file to.
+    :param watermark_text: Text to use as watermark.
+    :param position: Position of watermark. One of 'center' or '50% 50%', 'top-left' or
+        '0% 0%', 'top-right' or '100% 0%', 'bottom-left' or '0% 100%', etc.
+        You can also use absolute values like '100 100'.
+        Note: The position is relative to the center of the watermark text.
+    :param font_size: Font size of watermark text.
+    :param opacity: Opacity of watermark text. Between 0.0 and 1.0.
+    :param rotation: Rotation of watermark text in degrees.
+    :param force: Force overwrite of output file.
+    :param verbose: Print verbose output.
+    """
+    if not input_path.exists():
+        log21.critical(f'Input file `{input_path}` does not exist.')
+        sys.exit(1)
+    if output_path.exists() and not force:
+        log21.critical('Output file already exists.')
+        sys.exit(1)
+    if input_path.absolute() == output_path.absolute():
+        log21.critical('Input and output files cannot be the same.')
+        sys.exit(1)
+    if verbose:
+        log21.basic_config(level=log21.INFO)
+
+    log21.info(f'Adding watermark to `{input_path}`...')
+    try:
+        number_of_pages = watermark_pdf(
+            input_path, output_path, watermark_text, position, font_size, opacity,
+            rotation
+        )
+        log21.info(
+            f'Added watermark to {number_of_pages} page' +
+            ('s' if number_of_pages > 1 else '') + '!'
+        )
+    except PermissionError:
+        log21.critical(
+            f'Cannot write to output file `{output_path}`.\n'
+            'Check the file permissions and close any applications that may be using '
+            'the file, then try again.'
+        )
+        sys.exit(1)
+    except ValueError as e:
+        log21.critical(str(e))
+        sys.exit(1)
+
+
+def main() -> None:
+    try:
+        if sys.platform == 'win32':
+            import msvcrt
+            msvcrt.setmode(sys.stdout.fileno(), os.O_BINARY)
+        log21.basic_config(level=log21.ERROR)
+        log21.argumentify(
+            {
+                'merge': merge_pdfs_entry_point,
+                'remove-pages': remove_pages_entry_point,
+                'to-image': pdf_to_image_entry_point,
+                'add-watermark': watermark_pdf_entry_point,
+                'extract-text': extract_text_entry_point,
+                'image-to-pdf': image_to_pdf_entry_point,
+                'split': split_pdf_entry_point
+            }
+        )
+    except KeyboardInterrupt:
+        log21.critical('\nKeyboardInterrupt: Exiting...')
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

pdf_helper-0.1.0/src/pdf_helper/utils.py

@@ -0,0 +1,94 @@
+import re
+
+POSITION_PATTERN = re.compile(
+    r'^(top|bottom|center|left|right|\d{1,3}%?)\s+(top|bottom|center|left|right|\d{1,3}%?)?$'
+)
+
+
+def parse_pages(pages: str) -> list[int]:
+    """Parses the pages string into a list of pages.
+
+    :param pages: The pages string
+        Example: '1-5,7,9-11'
+    :return: A list of pages
+        Example: [1, 2, 3, 4, 5, 7, 9, 10, 11]
+    """
+    pages_ = pages.replace(' ', '')
+    pages_ = pages_.split(',')
+    pages_ = [x.split('-') for x in pages_]
+    pages_ = [x if len(x) == 1 else range(int(x[0]), int(x[1]) + 1) for x in pages_]
+    pages_ = [int(x) for y in pages_ for x in y]
+    return pages_
+
+
+def parse_position(
+    position: str, page_width: float, page_height: float, text_width: float,
+    text_height: float
+) -> tuple[float, float]:
+    """Parse position string into x and y coordinates.
+
+    :param position: Position string.
+    :param page_width: Width of the page.
+    :param page_height: Height of the page.
+    :param text_width: Width of the text.
+    :param text_height: Height of the text.
+    :return: x and y coordinates.
+    """
+    position = position.lower().strip()
+    match = POSITION_PATTERN.match(position)
+    if not match:
+        raise ValueError(f'Invalid position string: {position}')
+
+    groups = match.groups()
+    if len(groups) == 1:
+        value = groups[0]
+        if value == 'center':
+            return (page_width - text_width) / 2, (page_height - text_height) / 2
+        elif value == 'top':
+            return (page_width - text_width) / 2, 0
+        elif value == 'bottom':
+            return (page_width - text_width) / 2, page_height - text_height
+        elif value == 'left':
+            return 0, (page_height - text_height) / 2
+        elif value == 'right':
+            return page_width - text_width, (page_height - text_height) / 2
+        elif value.endswith('%'):
+            percent = float(value[:-1]) / 100.0
+            return (page_width -
+                    text_width) * percent, (page_height - text_height) * percent
+        else:
+            absolute = float(value)
+            return absolute, absolute
+    elif len(groups) == 2:
+        x_value, y_value = groups
+        if x_value == 'center':
+            x = (page_width - text_width) / 2
+        elif x_value == 'top' or x_value == 'bottom':
+            raise ValueError(f'Invalid x position: {x_value}')
+        elif x_value == 'left':
+            x = 0
+        elif x_value == 'right':
+            x = page_width - text_width
+        elif x_value.endswith('%'):
+            percent = float(x_value[:-1]) / 100.0
+            x = (page_width - text_width) * percent
+        else:
+            x = float(x_value)
+
+        if y_value == 'center':
+            y = (page_height - text_height) / 2
+        elif y_value == 'left' or y_value == 'right':
+            raise ValueError(f'Invalid y position: {y_value}')
+        elif y_value == 'top':
+            y = 0
+        elif y_value == 'bottom':
+            y = page_height - text_height
+        elif y_value.endswith('%'):
+            percent = float(y_value[:-1]) / 100.0
+            y = (page_height - text_height) * percent
+        else:
+            y = float(y_value)
+
+        return x, y
+    else:
+        raise ValueError(f'Invalid position string: {position}')