Stapler: где скачать и как пользоваться

Stapler: управление страницами PDF из командной строки

Stapler — компактная утилита для тех, кому удобнее управлять страницами PDF командами, а не мышью. На странице Xeon Live можно скачать Stapler бесплатно, а ниже разобраны установка, синтаксис диапазонов, выбор и удаление страниц, повороты, разбиение, чередование, наложение, защита результата и проверка типичных ошибок.

Что представляет собой Stapler и где он полезен

Stapler работает в терминале и собирает новый PDF из страниц исходных документов. В его диспетчере доступны режимы sel и его синоним cat, del, split и burst, zip, background, info, list-log и list-logical. Такой набор рассчитан не на визуальное редактирование текста, а на воспроизводимые операции со структурой страниц: отобрать нужные листы, удалить лишние, поменять порядок, повернуть диапазон, разнести документ на отдельные файлы, чередовать два потока страниц или наложить один PDF поверх другого.

Справка Stapler со списком режимов командной строки
Справка показывает полный набор основных режимов Stapler.

Поэтому программу удобнее воспринимать как маленький инструмент автоматизации, а не как настольный PDF-редактор. Она особенно уместна в повторяемых задачах: подготовить приложение к договору из нескольких диапазонов, собрать нечётные и чётные сканы, удалить один и тот же набор листов из файлов, построить последовательность операций в shell-скрипте. Для общего понимания формата полезен материал Xeon Live о структуре и практической работе с PDF.

Командная модель и нумерация страниц

Команда строится вокруг режима: сначала идут общие параметры, затем sel, del, split, zip или другой режим, после него — PDF-файлы, диапазоны и имя результата. Нумерация страниц в аргументах начинается с единицы. Диапазон 2-6 включает обе границы, запись 6-2 разворачивает порядок, слово end означает последнюю страницу. К диапазону добавляется один суффикс поворота: R — 90 градусов по часовой стрелке, D — 180 градусов, L — 90 градусов против часовой стрелки. Синоним cat вызывает тот же обработчик, что и sel.

Команда Stapler cat как синоним режима sel
cat и sel выполняют одну и ту же операцию выбора страниц.

Для переключения между несколькими входными файлами Stapler поддерживает однобуквенные дескрипторы. Запись A=report.pdf связывает файл с буквой A, а A1-3 выбирает из него первые три страницы. Дескриптор должен быть одной заглавной латинской буквой. Такая схема полезна в сложной сборке, где страницы из двух или трёх файлов нужно брать не блоками, а в конкретной последовательности.

Графического окна, дерева страниц, предпросмотра миниатюр, OCR и редактора текста в Stapler нет. Контроль выполняется через команды, вывод с параметром -v и последующую проверку готового PDF. Это важное ограничение: программа выигрывает там, где порядок страниц известен заранее и должен повторяться, но она неудобна при визуальной сортировке большого скана с неочевидным содержимым.

Как подготовить среду и проверить исходный PDF

Практическую работу стоит начинать с отдельного Python-окружения. На PyPI опубликован Stapler 1.0.0 от 6 марта 2020 года; пакет объявляет Python 3.4 и новее до ветки 4.0 и зависимость PyPDF2 не ниже 1.26. При этом исходник 1.0.0 использует старые имена PdfFileReader, PdfFileWriter, getNumPages, getPage, rotateClockwise и mergePage. В PyPDF2 3.0.0 этот интерфейс удалён, поэтому воспроизводимая установка требует зафиксировать совместимую ветку PyPDF2 1.x.

Команда Stapler info с метаданными PDF
info читает документные метаданные и помогает быстро убедиться, что выбран нужный файл.

Установка в изолированное Python-окружение

Создайте отдельное окружение командой python -m venv stapler-env. В Windows PowerShell активируйте его через .\stapler-env\Scripts\Activate.ps1, в macOS и Linux — через source stapler-env/bin/activate. После активации установите обе версии одной командой: python -m pip install "stapler==1.0.0" "PyPDF2==1.28.6". PyPDF2 1.28.6 сохраняет старые имена API, на которых построен Stapler, поэтому такая фиксация устраняет конфликт с PyPDF2 3.x.

После установки выполните stapler --help. В справке должны присутствовать режимы cat/sel, del, burst/split, zip, background, info и list-logical. Параметры -v, -f, -d, -u и -o относятся ко всей команде: -v показывает обработанные страницы и повороты, -f разрешает перезапись результата, -d задаёт каталог вывода, -u задаёт пароль пользователя для нового PDF, -o — пароль владельца. Репозиторий содержит Dockerfile, но он ставит PyPDF2 без фиксации версии; для воспроизводимой сборки в контейнере зависимость также нужно фиксировать.

Проверка метаданных через info

Перед изменением документа перейдите в каталог с файлами и выполните stapler info input.pdf. Команда читает словарь метаданных и выводит найденные поля: автор, заголовок, создатель, производитель, даты и другие записи, которые присутствуют в конкретном PDF. Это не редактор метаданных: режим только показывает значения. Используйте вывод как контрольную точку перед обработкой и повторите его для готового файла, когда документные свойства имеют значение.

Файлы лучше называть без неоднозначных пробелов и специальных символов либо всегда заключать путь в кавычки. Stapler принимает обычный путь к PDF, а проверка существования выполняется до чтения. Отсутствующий файл заканчивается сообщением об ошибке, поэтому в автоматизации такая проблема обнаруживается сразу. Для рабочего каталога заранее создайте отдельную папку результата: так исходники и созданные PDF не смешиваются.

Проверка логических меток страниц

PDF хранит логическую метку страницы через PageLabels, когда она задана в документе: например A-1, C-1, D-1, D-2. Команда stapler list-logical input.pdf печатает логическую метку рядом с физической позицией. Когда PageLabels отсутствуют, Stapler перечисляет обычные номера от 1 до количества страниц. Такой просмотр особенно полезен для отчётов и книг, где обложка, введение и основная часть имеют разные схемы нумерации.

Stapler list-logical с логическими и физическими номерами страниц
list-logical сопоставляет метку PageLabels с физической позицией страницы.

Сохраните результат list-logical перед сложной выборкой. Команды sel и del работают с физическими позициями страниц, поэтому логическая подпись в просмотрщике не заменяет номер аргумента. В документе с римскими номерами введения и арабской нумерацией основной части сначала найдите соответствие list-logical, затем используйте физические позиции. Так исключается типичная ошибка, когда пользователь ориентируется на цифру, напечатанную в колонтитуле, а Stapler получает другой номер.

Как собрать новый PDF из выбранных страниц

Основной режим Stapler — sel. Он создаёт новый PdfFileWriter и последовательно добавляет страницы, перечисленные в аргументах. Без диапазона после имени файла берутся все его страницы. Диапазоны можно смешивать с одиночными номерами, несколькими файлами, дескрипторами, обратным порядком и поворотами. Для задач перестановки также полезна отдельная инструкция Xeon Live по изменению порядка листов в PDF.

Выбор страниц и работа с дескрипторами

Допустим, из восьмистраничного manual.pdf нужно получить страницы 1, 3, 4 и 5. Команда stapler -v sel A=manual.pdf A1 A3-5 result.pdf сначала связывает manual.pdf с A, затем добавляет A1 и диапазон A3-5. Параметр -v печатает каждую использованную страницу. После завершения откройте result.pdf и проверьте, что в нём четыре страницы в порядке 1, 3, 4, 5.

Stapler sel выбирает отдельную страницу и диапазон через handle A
Verbose-режим показывает фактически добавленные страницы 1, 3, 4 и 5.

При сборке из нескольких файлов назначьте каждому входу отдельную букву: A=contract.pdf B=appendix.pdf. Затем задайте последовательность A1-2 B1 A5 B2-4 output.pdf. Stapler при встрече A или B переключает текущий источник и добавляет соответствующий диапазон. Такой синтаксис короче повторения длинных путей и заметно снижает риск перепутать исходники в команде.

Для выбора хвоста документа применяйте end: например A5-end. Обе границы входят в диапазон. Перед запуском проверьте число страниц через list-logical либо в просмотрщике: диапазон, выходящий за максимальную страницу, считается ошибкой и файл результата не создаётся. В сценариях автоматизации сохраняйте -v в журнал выполнения — это готовая трассировка того, какие страницы действительно попали в сборку.

Обратный порядок внутри диапазона

Stapler разворачивает диапазон, когда первая граница больше второй. Команда stapler -v sel manual.pdf 1-2 6-3 8 result.pdf создаёт последовательность 1, 2, 6, 5, 4, 3, 8. Это удобно для сканов, полученных из двусторонней подачи в обратном порядке, а также для перестановки небольшого блока без ручного перечисления каждого номера. Разворот действует только на указанный диапазон и не меняет остальные аргументы.

Stapler sel с обратным диапазоном 6-3
В verbose-выводе видна последовательность 6, 5, 4, 3.

Проверяйте обратные диапазоны по журналу до отправки документа дальше. Запись 6-3 и запись 3-6 дают разные результаты, хотя охватывают одинаковые физические листы. Для длинных сборок удобнее разбить команду на смысловые сегменты и оставить между ними дескрипторы источников: тогда последовательность читается как маршрут страниц, а не как длинная строка чисел.

Поворот выбранных страниц

Суффикс R поворачивает выбранную страницу или диапазон на 90 градусов по часовой стрелке, D — на 180 градусов, L — на 90 градусов против часовой стрелки. Пример stapler -v sel manual.pdf 1 2R 3D 4L result.pdf оставляет первую страницу без изменения, вторую поворачивает на 90 градусов, третью — на 180, четвёртую — на 270 градусов по часовой стрелке, что соответствует повороту влево.

Stapler sel с суффиксами R D L для поворота страниц
Verbose-вывод показывает углы 90, 180 и 270 градусов.

Поворот применяется одновременно с выбором, поэтому отдельный проход не нужен. После команды откройте итоговый PDF в независимом просмотрщике и пролистайте все изменённые листы. У PDF различаются геометрия страницы и визуальный флаг поворота; Stapler использует механизм PyPDF2 rotateClockwise. Для дальнейшего наложения через background особенно важно убедиться, что ориентация базового документа и накладываемого PDF совпадает.

Результат выборки страниц Stapler
Первая страница нового PDF после sel.
Результат чередования страниц Stapler
Страница из потока even после zip.
Результат наложения страниц Stapler
Базовая страница с наложенным PDF через background.

Как удалить страницы и разделить документ

Режим del использует тот же механизм диапазонов, что и sel, но инвертирует выбор: указанные страницы исключаются, все остальные добавляются в новый PDF. Режим split, он же burst, выполняет обратную по смыслу задачу — создаёт отдельный PDF для каждой страницы входного документа. Эти операции закрывают два типовых сценария подготовки архивов: очистить документ и разложить его на листы.

Удаление страниц через del

Чтобы удалить страницы 2 и 5 из manual.pdf, выполните stapler -v del manual.pdf 2 5 cleaned.pdf. В verbose-выводе появятся страницы 1, 3, 4, 6, 7 и 8 — именно они будут записаны в cleaned.pdf. Это важная деталь: журнал показывает не удалённые, а использованные страницы. После завершения проверьте количество листов и соседство страниц вокруг мест удаления.

Stapler del исключает страницы 2 и 5
Verbose-режим перечисляет страницы, оставшиеся в новом PDF.

Для удаления непрерывного блока используйте один диапазон: stapler del input.pdf 4-9 output.pdf. Несколько диапазонов и одиночных номеров можно комбинировать. В сложном документе сначала сохраните копию исходника; Stapler по умолчанию не перезаписывает существующий результат, но режим -f снимает эту защиту. Дополнительные способы удаления описаны в материале Xeon Live об удалении страниц из PDF.

После del отдельно проверяйте ссылки, закладки, формы и цифровые подписи. Код команды создаёт новый writer и переносит выбранные PageObject, но не содержит отдельной процедуры копирования documentInfo или дерева закладок. Для юридически значимых и интерактивных PDF нужен контроль в профильном инструменте, потому что задача Stapler — перестройка страниц, а не сохранение всех объектов верхнего уровня документа.

Разбиение документа через split

Для разбиения выполните stapler -v -d pages split manual.pdf. Каталог pages должен существовать до запуска. Stapler создаёт по одному PDF на страницу и формирует имя из исходного basename и номера листа. В нашем восьмистраничном примере получаются manual_1.pdf … manual_8.pdf, а verbose-режим завершает работу строкой с количеством обработанных страниц и файлов.

Stapler split создаёт отдельный PDF для каждой страницы
Восьмистраничный документ разложен на восемь отдельных файлов.

Перед split создайте пустую папку назначения. Команда не очищает существующий каталог и применяет общую защиту от перезаписи: совпадение имени останавливает запись, пока не добавлен -f. Для массового разбора архива лучше выдавать каждому исходнику отдельную папку, иначе одинаковые basename из разных директорий создадут конфликт. Подробный общий сценарий разбивки есть в инструкции Xeon Live по разбиению PDF на страницы.

Проверка после split простая: число созданных PDF должно совпадать с числом физических страниц, а каждый файл должен содержать один лист. Для больших документов не ориентируйтесь только на список имён в файловом менеджере; подсчитайте файлы командой shell и выборочно откройте начало, середину и конец набора. Это быстрее обнаруживает пропуск, конфликт имени или неожиданную нумерацию.

Как чередовать страницы и накладывать PDF

Два режима Stapler работают сразу с несколькими источниками. zip берёт по одной странице из каждого набора и чередует их, а background объединяет соответствующие страницы в один PageObject. Оба режима принимают те же диапазоны и повороты, что и sel, поэтому сначала можно ограничить нужные страницы, а затем выполнить объединение за один запуск.

Сборка нечётных и чётных сканов через zip

Классический сценарий — два PDF после сканирования стопки: odd.pdf содержит страницы 1, 3, 5, а even.pdf — 2, 4, 6. Выполните stapler -v zip odd.pdf even.pdf output.pdf. Stapler сначала собирает страницы каждого входа, затем проходит по одинаковым позициям и добавляет по одной странице из каждого списка. Итоговая последовательность будет odd1, even1, odd2, even2, odd3, even3.

Stapler zip чередует страницы odd.pdf и even.pdf
zip готовит два списка страниц и собирает их поочерёдно.

При разной длине источников реализация продолжает добавлять страницы из оставшегося списка, поэтому хвост длинного документа не отбрасывается. Перед запуском убедитесь, что порядок внутри каждого исходника правильный. Частая ситуация со сканером: второй проход получается в обратном направлении; тогда задайте для одного файла обратный диапазон, например even.pdf 6-1, и только затем выполняйте чередование.

После zip сравните первые несколько пар, одну пару из середины и последнюю страницу. Для документов с сотнями листов такая выборочная проверка быстрее полного чтения и хорошо ловит сдвиг на одну страницу. Когда требуется обычное последовательное объединение файлов без чередования, используйте sel без диапазонов: stapler sel first.pdf second.pdf merged.pdf. Общие методы объединения разобраны в материале Xeon Live о соединении нескольких PDF.

Наложение страниц через background

Команда stapler -v background base.pdf stamp.pdf output.pdf объединяет содержимое соответствующих страниц двух документов. Первый доступный PageObject становится основой, следующий mergePage добавляется поверх него. Несмотря на название background, реализация Stapler фактически использует операцию слияния содержимого страницы и не предоставляет отдельный переключатель порядка слоя. Поэтому базовый файл и файл наложения подготавливайте заранее в нужной геометрии.

Stapler background объединяет соответствующие страницы двух PDF
Команда обрабатывает страницы base.pdf и stamp.pdf по одинаковым позициям.

Для водяного знака подготовьте PDF с прозрачным фоном и тем же размером листа. Для бланка — убедитесь, что координаты элементов совпадают с документом. Затем выполните background и отрендерите несколько страниц либо откройте их в просмотрщике. Наложение особенно чувствительно к поворотам, CropBox и MediaBox: визуальная проверка обязательна, даже когда команда завершилась без ошибки.

Когда количество страниц различается, Stapler проходит до длины самого длинного списка. На позиции, где остаётся только один источник, в итог добавляется его страница без второго слоя. Это поведение отличается от инструментов, которые повторяют последнюю страницу штампа, поэтому для многостраничного бланка заранее подготовьте столько страниц, сколько требуется документу.

Как настроить вывод, перезапись, пароли и автоматизацию

Общие параметры Stapler применяются до выбранного режима и позволяют сделать команду пригодной для повторяемого процесса. Самые важные — -d для каталога назначения, -f для перезаписи, -v для трассировки, -u и -o для паролей результата. Они не являются пресетами: Stapler не хранит профили, поэтому воспроизводимость достигается сохранением самой команды в shell-скрипте, Makefile, CI-задаче или другом оркестраторе.

Каталог назначения и защита от случайной перезаписи

Создайте папку results и выполните stapler -v -d results sel manual.pdf 1-2 pick.pdf. Для относительного имени результата Stapler добавит каталог -d и сохранит файл как results/pick.pdf. Абсолютный путь в имени выходного PDF имеет приоритет и записывается напрямую. Режим split также кладёт созданные страницы в каталог, заданный -d.

Stapler сохраняет относительный результат в каталог из параметра -d
Параметр -d отделяет итоговые PDF от исходных файлов.

По умолчанию существующий выходной файл защищён от перезаписи: Stapler завершает команду сообщением File already exists. Это полезное поведение для пакетных процессов, потому что ошибочное повторение не уничтожает результат предыдущего запуска. Параметр -f снимает защиту. В автоматизации включайте -f только там, где выходной путь формируется однозначно и предыдущая версия действительно должна заменяться.

Stapler останавливается при совпадении имени результата
Без -f существующий выходной PDF не перезаписывается.

Пароли пользователя и владельца

Для нового PDF Stapler принимает -u или --userpw и -o или --ownerpw. Команда stapler -u reader -o owner sel input.pdf 1-2 secure.pdf перед записью вызывает шифрование writer и создаёт защищённый результат. Пароль пользователя нужен для открытия документа, пароль владельца управляет полным доступом. Когда задан только ownerpw, код передаёт пустой user password. После создания проверьте, что файл действительно открывается ожидаемым паролем.

Stapler создаёт зашифрованный PDF с user и owner password
После команды отдельная проверка подтверждает, что PDF зашифрован и открывается паролем пользователя.

Для зашифрованного входного PDF Stapler проверяет isEncrypted и просит пароль интерактивно. Неверный пароль приводит к повторному приглашению, Ctrl+C завершает процесс. Такой режим неудобен в полностью безнадзорной обработке большого набора защищённых файлов: команда не имеет отдельного аргумента пароля входа. Для автоматизации защищённых источников практичнее использовать инструмент с параметризуемым входным паролем либо предварительно готовить доступный рабочий набор в контролируемой среде.

Пакетная обработка через shell

Встроенной очереди заданий и сохранённых профилей нет, но обычный shell превращает Stapler в пакетный инструмент. Для чтения метаданных набора файлов подойдёт цикл for f in *.pdf; do stapler info "$f"; done. Для одинакового удаления обложки можно создать папку out и в цикле вызывать stapler -d out del "$f" 1 с заранее рассчитанным уникальным именем результата. В PowerShell применяется та же схема через Get-ChildItem и ForEach-Object.

Stapler вызывается в shell-цикле для нескольких PDF
Команда info последовательно обрабатывает два PDF в одном shell-сценарии.

Для надёжной автоматизации используйте три правила. Первое: запускайте с -v и сохраняйте stdout/stderr в журнал. Второе: держите исходники только для чтения, а результат направляйте в отдельный каталог. Третье: после каждого критичного шага проверяйте наличие файла и ожидаемое число страниц. Stapler возвращает ненулевой код при собственных ошибках, поэтому shell с режимом остановки при ошибке не продолжит цепочку после неправильного диапазона или отсутствующего файла.

Типичные ошибки и проверка результата

Stapler сообщает о большинстве ошибок до записи или в момент разбора аргументов. Для рабочих сценариев важны четыре проверки: диапазон не выходит за число страниц, дескриптор определён до использования, каталог -d существует, выходное имя не занято. Отдельно контролируйте визуальный результат после поворота и background: формально корректный PDF не гарантирует правильную ориентацию и наложение.

Диапазон выходит за пределы документа

Команда stapler sel manual.pdf 1-99 invalid.pdf для восьмистраничного файла останавливается с сообщением Range 1-99 exceeds maximum page number 8. Исправление начинается с фактического количества страниц: выполните list-logical или откройте документ в просмотрщике, затем сократите диапазон. Для выбора до конца документа используйте end, например 5-end, вместо вручную введённого большого номера.

Ошибка Stapler при диапазоне за пределами документа
Stapler показывает максимальный номер страницы, что упрощает исправление команды.

Не пытайтесь обходить проверку через заведомо большой диапазон. Парсер сравнивает обе границы с getNumPages и завершает операцию до сборки. В автоматических сценариях формируйте диапазоны из заранее проверенных параметров и сохраняйте входной файл вместе с журналом -v — это даёт воспроизводимую диагностику без повторного угадывания, какие страницы использовались.

Неизвестный дескриптор файла

Запись B1-2 допустима только после определения B=имя.pdf в той же команде. При обращении к несуществующему handle Stapler выводит Filehandle B does not exist in page range B1-2. Исправление — добавить B=... перед первым диапазоном B либо заменить диапазон на физическое имя файла и следующие номера страниц. Дескрипторы чувствительны к регистру и ограничены одной заглавной буквой.

Ошибка Stapler для неопределённого handle B
Дескриптор должен быть определён до первого диапазона с этой буквой.

Контроль готового PDF после успешной команды

Успешное завершение означает, что writer записал PDF, но не заменяет содержательную проверку. Для sel и del сравните verbose-журнал с планом страниц. Для split пересчитайте созданные файлы. Для zip проверьте первые, средние и последние пары. Для background откройте несколько страниц на разных позициях и убедитесь, что слой не смещён. Для защищённого результата закройте просмотрщик и заново откройте файл паролем пользователя.

Метаданные и элементы уровня документа проверяйте отдельно. В командах выбора Stapler создаёт новый writer и добавляет в него PageObject, но исходный documentInfo явно не копируется. Поэтому после преобразования снова выполните info и сравните поля с требованиями процесса. Закладки, формы, вложения, подписи и другие сложные структуры не входят в заявленный набор команд Stapler; важные документы нужно проверять в профильном просмотрщике или валидаторе.

Stapler установлен, но падает на PdfFileReader

Исходник 1.0.0 использует интерфейс PyPDF2 1.x. Создайте отдельное окружение и установите Stapler вместе с PyPDF2 1.28.6, затем снова проверьте stapler --help.

Результат уже существует

Без -f Stapler не перезаписывает выходной файл. Укажите новое имя или осознанно добавьте -f для замены существующего результата.

Диапазон больше числа страниц

Проверьте физические позиции через list-logical. Для диапазона до последнего листа применяйте end, например 5-end.

Логический номер не совпадает с физическим

list-logical показывает соответствие PageLabels и позиции. В аргументах sel и del используйте физический номер страницы.

background даёт визуально неверный слой

Проверьте размер листа, ориентацию, CropBox и MediaBox обоих PDF. Подготовьте файл наложения с правильной геометрией и повторите визуальную проверку.

Нужно обработать десятки файлов

Вызовите Stapler из shell или PowerShell цикла, направляйте результат в отдельную папку и сохраняйте verbose-вывод в журнал.

Ограничения, альтернативы, плюсы и практические рекомендации

Stapler остаётся узким инструментом с понятной моделью: входные PDF, диапазоны страниц и новый PDF на выходе. Пакет не заменяет современный редактор, а опубликованная версия 1.0.0 опирается на старый интерфейс PyPDF2. Репозиторий не архивирован, но последний push в основной репозиторий датирован 30 июня 2023 года, а последняя версия на PyPI — 1.0.0 от 6 марта 2020 года. Для нового инфраструктурного проекта эту историю обслуживания нужно учитывать заранее.

Stapler cat собирает страницы из нескольких PDF
Синтаксис короткий и удобный для сценариев, но остаётся полностью терминальным.

Из реальных альтернатив ближе всего PDFtk Server, qpdf и прямое использование pypdf. PDFtk Server предлагает более широкий набор команд: cat, shuffle, burst, rotate, background, stamp, операции с формами, вложениями и метаданными. qpdf активно развивается и поддерживает выбор страниц, overlay/underlay, шифрование и структурные преобразования. pypdf подходит разработчикам, которым нужна логика на Python вместо отдельного CLI. На Xeon Live есть отдельные материалы про PDFtk Server, qpdf и pypdf.

Выбор между ними определяется характером процесса. Stapler удобен для коротких команд и уже существующих сценариев на его синтаксисе. qpdf рациональнее для новой автоматизации, где важна актуальная поддержка формата и развитые структурные операции. PDFtk Server подходит командам, которым нужна знакомая модель cat/shuffle/burst и дополнительные функции вокруг форм и вложений. pypdf удобен, когда правила страниц зависят от данных приложения и проще выразить их в Python-коде.

Плюсы

  • Короткий и читаемый синтаксис для выбора, удаления, поворота и перестановки страниц.
  • Дескрипторы A=, B= упрощают сложную сборку из нескольких PDF.
  • Режимы zip и background закрывают полезные сценарии сканирования и наложения.
  • Есть verbose-вывод, защита от случайной перезаписи и отдельный каталог результата.
  • Чистая командная модель хорошо встраивается в shell-скрипты и повторяемые процессы.
  • Исходный код открыт и распространяется по BSD-3-Clause.

Минусы

  • Нет графического интерфейса и визуальной сортировки миниатюр.
  • Версия 1.0.0 использует устаревший интерфейс PyPDF2 и требует фиксированного совместимого окружения.
  • Нет OCR, редактирования текста, аннотаций и полноценной работы с формами.
  • Команды перестройки страниц не копируют documentInfo отдельной процедурой, поэтому метаданные нужно контролировать после обработки.
  • Для защищённых входных PDF пароль запрашивается интерактивно, что осложняет безнадзорную пакетную обработку.
  • Последний релиз Stapler на PyPI датирован 2020 годом, поэтому совместимость со старым PyPDF2 приходится контролировать отдельно.

Кому подойдёт

  • Администраторам и разработчикам, которым нужен небольшой CLI для известных операций со страницами.
  • Пользователям, которые поддерживают существующие скрипты на Stapler и готовы зафиксировать Python-окружение.
  • Операторам сканирования для сборки нечётных и чётных страниц через zip.
  • Техническим командам для воспроизводимой подготовки PDF в локальных процессах без визуального редактора.

Кому лучше выбрать другой инструмент

  • Тем, кто сортирует страницы визуально и постоянно работает мышью.
  • Тем, кому нужны OCR, правка текста, формы, подписи, аннотации или глубокое редактирование структуры.
  • Новым инфраструктурным проектам, где требуется актуальный CLI без фиксации старого PyPDF2; для них практичнее qpdf.
  • Python-разработчикам со сложной логикой документов; им удобнее строить процесс непосредственно на pypdf.

Для уже действующего сценария Stapler практический план простой: зафиксируйте Stapler 1.0.0 и PyPDF2 1.28.6 в отдельном окружении, храните исходники отдельно, включайте -v, направляйте результат через -d, не используйте -f без необходимости и проверяйте итоговый PDF после каждого структурного преобразования. Для новой автоматизации сначала сравните тот же процесс с qpdf и pypdf — так проще выбрать инструмент, который будет поддерживать цепочку без лишней совместимости с устаревшим API.

Stapler ценен не количеством функций, а предсказуемой логикой страниц. Когда задача формулируется как взять листы 1-3 из A, затем 7-4 из B, повернуть один диапазон, чередовать два скана или наложить готовый слой, синтаксис остаётся компактным. Когда задача выходит за уровень страниц и затрагивает содержимое, формы, OCR, подписи или сложную структуру документа, Stapler перестаёт быть подходящим уровнем инструмента.

xeonlive.ru
Профиль автора на Sostav