Stapler: возможности, ограничения и актуальный статус PDF-утилиты

Stapler — небольшая консольная утилита на Python для структурных операций с PDF: объединения файлов, выбора и удаления страниц, разбиения документа, чередования листов из нескольких источников, наложения страниц и чтения метаданных. Важно сразу отделить её от одноимённых продуктов: здесь рассматривается проект hellerbarde/stapler, изначально созданный Филипом Старком и позже существенно переработанный Фредом Вензелем. Это не PDF Stapler с SourceForge, не современное браузерное расширение Stapler и не macOS-приложение с таким же названием.

По состоянию на 12 сентября 2026 года последним опубликованным пакетом остаётся Stapler 1.0.0 от 6 марта 2020 года. Репозиторий не архивирован, но последний коммит master датирован 30 марта 2022 года, а в 2026 году открыт вопрос о том, поддерживается ли проект. Поэтому Stapler доступен, но фактически неактивен upstream: использовать его разумно в закреплённом окружении или в дистрибутиве с патчами.

ПараметрStapler
ТипКонсольная утилита для манипуляций с PDF
Последний релиз1.0.0, 6 марта 2020 года
АвторыPhilip Stark, Fred Wenzel; пакет сопровождается аккаунтами hellerbarde и oddshocks
ИнтерфейсКомандная строка, без графического интерфейса
Основной форматPDF на входе и PDF на выходе
ЛицензияBSD-3-Clause
Аккаунт и облакоНе требуются; операции выполняются с локальными файлами
Ключевые зависимостиPyPDF2 и more-itertools; релиз 1.0.0 использует старый API PyPDF2 и ограничивает more-itertools версией ниже 6
Текущий рискНесовместимость с PyPDF2 3.0.0 без патчей

Скачать Stapler

Бесплатно
В реестре российского ПО
Чистая установка

Новейшая версия для Виндовс, macOS и Линукс. Удобный редактор PDF под российские реалии.

⬇ Скачать PDF Commander бесплатно

⬇ Скачать Stapler

Безопасный источник опубликованной версии — страница пакета stapler в PyPI: там по-прежнему доступны исходный архив и универсальный wheel Stapler 1.0.0. Исходный код и история разработки находятся в публичном репозитории hellerbarde/stapler на GitHub. Случайные каталоги загрузок и сайты с «готовыми EXE» лучше исключить из маршрута: upstream не выпускает официальный Windows-инсталлятор или отдельный исполняемый файл для macOS, а под именем Stapler существуют другие продукты.

Релиз 1.0.0 и master не идентичны: после публикации пакета в репозиторий добавили, среди прочего, Dockerfile и нормализацию путей, но нового релиза не выпустили. Для повторяемости фиксируйте либо пакет 1.0.0, либо конкретный commit.

На новых системах одного pip install stapler недостаточно: релиз разрешает PyPDF2 от 1.26 без верхней границы, хотя PyPDF2 3.0.0 ломает используемый API, и одновременно требует more-itertools не ниже 2.2, но ниже 6. Это набор зависимостей эпохи релиза 2020 года. Ниже поэтому используется изолированное окружение; если текущий Python не может корректно разрешить эту связку, безопаснее выбрать пакет дистрибутива с патчами или современную альтернативу, а не отключать проверку зависимостей.

Что такое Stapler

Stapler появился как чисто Python-альтернатива PDFtk для тех, кому нужны программируемые операции над страницами PDF из командной строки. Версия 0.2 была написана Philip Stark в 2009 году, а ветка 0.3 получила серьёзную переработку от Fred Wenzel. В 1.0.0 проект был переведён на Python 3 и получил argparse вместо старого OptionParser. В метаданных PyPI заявлено назначение «Manipulate PDF documents from the command line», что точно отражает продукт: это не просмотрщик, не полноценный редактор содержимого и не OCR-система.

Пользователь передаёт режим, PDF, диапазоны страниц и путь результата. Stapler читает файлы через PyPDF2 и записывает новый PDF локально; аккаунт, браузер и серверная обработка не нужны. GUI с миниатюрами и перетаскиванием страниц отсутствует.

Одноимённые продукты не относятся к этому обзору. PDF Stapler на SourceForge — отдельная Windows-программа, обновлявшаяся последний раз в 2015 году; существуют также Chrome-расширение Stapler и независимое macOS-приложение. Их функции и версии к Python-пакету неприменимы.

Хронология развития и поддержки

2009–2010. Philip Stark создаёт раннюю версию Stapler, после чего Fred Wenzel перерабатывает код и добавляет тесты. Проект ориентируется на знакомую пользователям PDFtk модель командной обработки документов.

2013–2015. Ветка 0.3 переходит на PyPDF2, затем выходят 0.3.1–0.3.3. Классификатор Python 2 у 0.3.3 относится к старому релизу и не означает актуальную поддержку Python 2.

2020. После beta 1.0.0b1 выходит Stapler 1.0.0. Главные изменения — переход на Python 3 и современный для того времени argparse. Метаданные пакета заявляют Python от 3.4 до версии ниже 4.0, а классификаторы перечисляют Python 3.4–3.8.

2021–2022. В master появляются Dockerfile и другие правки; последний коммит датирован 30 марта 2022 года. PyPDF2 3.0.0 затем ломает старые классы PdfFileReader/PdfFileWriter, и проблема остаётся открытой; современные Linux-пакеты применяют патчи.

2026. Репозиторий остаётся публичным и неархивированным, но в феврале открыт issue с прямым вопросом о поддержке. Ответа maintainer о возобновлении разработки в обсуждении нет. Формально проект не объявлен закрытым, практически рассчитывать на быстрые upstream-исправления не стоит.

Основные функции Stapler

Выбор, объединение и удаление страниц

Режимы sel и cat собирают новый PDF из выбранных страниц. Поддерживаются числа, интервалы, end и обратные диапазоны вроде 9-6. Для нескольких файлов можно назначать однобуквенные handles и привязывать к ним диапазоны.

Суффиксы R, L и D поворачивают диапазон на 90 градусов вправо, влево или на 180 градусов. del использует ту же модель, но исключает перечисленные страницы.

Разбиение PDF на отдельные страницы

split и burst создают по PDF на каждую страницу. Имена строятся из исходного имени и номера с ведущими нулями; можно обработать несколько входных файлов за запуск.

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

Чередование страниц из нескольких файлов

zip берёт страницы входных файлов по очереди. Это полезно для сведения нечётных и чётных проходов одностороннего сканера. Диапазоны и поворот поддерживаются; если один источник короче, оставшиеся страницы других файлов всё равно добавляются.

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

Команда background объединяет соответствующие страницы нескольких PDF не последовательностью, а наложением содержимого в одну страницу. В реализации используется операция mergePage старого PyPDF2. Это подходит для простых фонов, бланков и отдельных слоёв, но результат зависит от геометрии страниц, их rotation и особенностей PDF-контента. В трекере есть старые сообщения о проблемах ориентации, поэтому критические документы после операции нужно визуально проверять в независимом просмотрщике.

Метаданные и логические номера

Режим info выводит имеющиеся поля documentInfo: заголовок, автора, производителя, даты и другие пары, если они присутствуют. Это функция чтения, а не редактор метаданных. Отдельная команда list-logical или list-log сопоставляет логические метки страниц из структуры PageLabels с физическими порядковыми номерами. Она полезна для документов, где нумерация начинается римскими цифрами, имеет буквенные префиксы или сбрасывается по разделам.

Пароли, выходной каталог и защита от перезаписи

При чтении PDF, который библиотека считает зашифрованным, Stapler запрашивает пароль в терминале, скрывая ввод. Для создаваемого файла предусмотрены параметры user password и owner password. По умолчанию существующий output не перезаписывается: утилита завершает работу ошибкой «File already exists». Принудительная перезапись включается отдельным параметром force. Также можно задать каталог назначения, что полезно в пакетных сценариях и при разбиении документа на множество страниц.

Интерфейс и удобство использования

Stapler работает только в терминале: нет окна проекта, миниатюр, drag-and-drop и предпросмотра. Команды удобно сохранять в bat, PowerShell или shell-скриптах, но для ручной визуальной сортировки страниц порог освоения выше, чем у GUI-программ.

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

Строки справки и сообщения исходного кода написаны на английском. Механизма локализованного GUI у проекта нет, поэтому вопрос языка интерфейса сводится к чтению английских имён режимов и диагностических сообщений. Специальная регистрация пользователя или первичная настройка профиля отсутствуют.

Поддерживаемые форматы и совместимость

Stapler работает с PDF. Парсер диапазонов распознаёт входные имена, оканчивающиеся на .pdf, а все основные операции строятся вокруг PdfFileReader и PdfFileWriter. Импорта DOCX, EPUB, DjVu, изображений, HTML или сканов как растровых файлов нет; экспорта в Word, Excel, JPEG или текст также нет. Если исходный документ находится в другом формате, его нужно заранее преобразовать другим инструментом.

Поддержка конкретных PDF-записей определяется PyPDF2. У Stapler нет собственного рендерера, OCR или восстановителя повреждённых файлов. Зашифрованные документы идут через decrypt PyPDF2; открытый issue показывает проблемы с отдельными схемами шифрования, поэтому парольная поддержка не универсальна.

Пакет 1.0.0 опубликован как универсальный wheel py3-none-any, то есть он не привязан к Windows, macOS или конкретной архитектуре процессора на уровне бинарного файла. Однако upstream не публикует современную матрицу ОС и Python. Практически Stapler запускался и пакетировался в Linux, а чистая Python-архитектура позволяет использовать его и на Windows/macOS при наличии совместимой среды. Это отличается от официально заявленной поддержки конкретных версий ОС, которой у проекта нет.

Производительность и стабильность

У Stapler нет опубликованных официальных бенчмарков, поэтому корректно говорить не о «быстрой работе», а о характере нагрузки. Утилита не рендерит страницы в изображения: большинство операций копирует и перестраивает PDF-объекты через PyPDF2. На простых документах это обычно экономичнее полноценного графического редактора, но фактическое время и память зависят от размера PDF, количества страниц, сложности ресурсов, шифрования и поведения версии библиотеки.

Гарантий постоянного расхода памяти, максимального размера файла или числа страниц нет. Код собирает результат через PdfFileWriter, поэтому перед массовой обработкой крупных архивов стоит испытать команду на типовой копии.

Главное ограничение стабильности в 2026 году — не размер PDF, а устаревшая связка API. Stapler 1.0.0 импортирует PdfFileReader и PdfFileWriter, а PyPDF2 3.0.0 переводит старые имена в состояние, при котором вызов заканчивается DeprecationError. В открытом issue Stapler это обозначено как несовместимость. Gentoo-пакет, поддерживаемый в более новых Python, накладывает отдельные патчи для PyPDF2 2.x, 3.0.0 и переезда на pypdf, что подтверждает: «современная совместимость» достигается downstream-адаптацией, а не исходным релизом 1.0.0.

Есть и функциональные потери. В открытом issue задокументировано, что простой cat может не сохранить outline/закладки и часть метаданных исходного PDF. Это не редкая косметика: если документ передаётся как техническое руководство или отчёт с оглавлением, структура навигации может быть важнее самого факта успешного объединения страниц. Поэтому успешное завершение команды ещё не является достаточной проверкой качества результата.

Карта критических зависимостей

ЗависимостьНужна для работыПрактический риск
PythonДаUpstream указывает диапазон от 3.4 до версии ниже 4.0, но тестирование новых веток Python не подтверждено
PyPDF2ДаВерсия 3.0.0 несовместима с опубликованным Stapler 1.0.0 без исправлений
more-itertoolsДа для релиза 1.0.0PyPI-релиз фиксирует диапазон от 2.2 до версии ниже 6; в master эту зависимость позднее убрали, но новый пакет не выпускали
ИнтернетТолько для получения пакетовПосле установки обычные операции выполняются с локальными файлами
Аккаунт или сервер StaplerНетНет зависимости от авторизации и доступности облачного сервиса
GUI-компонентыНетВизуальной проверки результата внутри Stapler не существует
Сторонний просмотрщикНе обязателен для команды, но практически нуженБез него труднее проверить порядок, поворот, закладки и наложение

Главный риск — несогласованность старого пакета с современным окружением: слишком новый PyPDF2 ломает API, а опубликованный Stapler одновременно тянет старую ветку more-itertools. Для воспроизводимости фиксируйте весь набор зависимостей и храните контрольный PDF с проверкой ожидаемого числа страниц.

Лицензирование и версии

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

Актуальной опубликованной редакцией остаётся 1.0.0. PyPI также хранит beta 1.0.0b1 и старые версии 0.3.x. Выбирать 0.3.x ради «старой стабильности» обычно нет смысла: они относятся к эпохе Python 2 или переходным состояниям, тогда как 1.0.0 специально переносит утилиту на Python 3. При этом master после 1.0.0 содержит несколько нерелизованных изменений, поэтому слово «последняя» нужно уточнять: последний пакет — 1.0.0, последний код upstream — master 2022 года.

Практические затраты связаны не с лицензией, а с фиксацией зависимостей и проверкой после обновлений Python. Для новой автоматизации это важнее нулевой цены продукта.

Системные требования

Требования опубликованного пакета

  • Python версии не ниже 3.4 и ниже 4.0 согласно метаданным PyPI 1.0.0.
  • PyPDF2 версии от 1.26 согласно pyproject.toml; для неизменённого Stapler 1.0.0 следует избегать ветки 3.0.0, с которой зафиксирована несовместимость.
  • more-itertools версии не ниже 2.2 и ниже 6.0.0 в опубликованном релизе 1.0.0. После релиза зависимость удалили из master, однако отдельного нового пакета с этим изменением нет.
  • Доступ к командной строке и файловой системе для чтения входных PDF и записи результата.
  • Дополнительные требования к оперативной памяти, месту на диске, процессору и минимальной версии Windows/macOS upstream не публикует.

Операционные системы

Официальной таблицы «Windows 10/11, macOS такой-то версии, Ubuntu такой-то версии» у Stapler нет. Wheel 1.0.0 не содержит нативных бинарников и имеет пометку py3-none-any, поэтому ограничение задаётся Python и зависимостями. Linux-дистрибутивы действительно пакетировали Stapler: существуют пакеты для Mageia и AUR, а Gentoo продолжает собирать код с патчами для современных pypdf/Python. Для Windows и macOS наиболее предсказуемый путь — отдельное виртуальное окружение Python, а не поиск неофициального установщика.

Преимущества и недостатки Stapler

Плюсы и минусы

Плюсы ✔️
  • Локальная обработка. Для выполнения команд не нужен аккаунт или загрузка документов в веб-сервис.
  • Автоматизация. Консольный синтаксис легко включать в скрипты, пакетные задания и повторяемые цепочки обработки.
  • Выразительные диапазоны. Поддерживаются выбор страниц, обратный порядок, end, повороты и handles для нескольких PDF.
  • Полезный режим zip. Чередование нечётных и чётных сканов решается одной операцией.
  • Свободная BSD-лицензия. Нет платных функций, водяных знаков и искусственных лимитов Stapler.
  • Защита от случайного перезаписывания. Существующий output по умолчанию не заменяется без явного force.
Минусы ❌
  • Неактивный upstream. Последний релиз относится к 2020 году, последний коммит master — к 2022-му.
  • Проблема современной зависимости. PyPDF2 3.0.0 ломает старый API, используемый Stapler 1.0.0.
  • Нет GUI. Нельзя визуально перетаскивать страницы или просматривать результат перед сохранением.
  • Только PDF-операции. Нет OCR, преобразования Office, экспорта изображений, полноценного редактирования текста и аннотаций.
  • Возможна потеря структуры. Открытый issue фиксирует исчезновение outline/закладок и некоторых метаданных после cat.
  • Нет современной матрицы поддержки. Upstream не подтверждает текущие версии ОС и Python как протестированные.

Сравнение с аналогами

Stapler уместно сравнивать не со всеми PDF-программами подряд, а по роли. Его прямые конкуренты — другие локальные инструменты структурной обработки PDF; просмотрщики вроде Sumatra PDF решают другую задачу. В таблице ниже критерии одинаковы: интерфейс, сценарий, платформенность, активность и ограничения.

ИнструментИнтерфейсЛучший сценарийСостояние относительно Stapler
StaplerCLI, PythonВыбор, удаление, split, interleave, overlay в скриптахКомпактный, но upstream давно не обновлялся и требует контроля PyPDF2
qpdfCLI и C++ libraryНизкоуровневые преобразования PDF, merge/split, шифрование, инспекция структурыБолее современный и активно развиваемый выбор для новой CLI-автоматизации
PDFsam BasicГрафическое desktop-приложениеРучное объединение, разделение, поворот, извлечение и mixЛучше для пользователей без shell; активно поддерживается на Windows, macOS и Linux
Sumatra PDFWindows GUI плюс развивающиеся CLI-toolsЧтение PDF и многих других форматов; в pre-release 3.7 есть команды для PDF-операцийНе прямой заменитель Stapler: прежде всего просмотрщик, но современная ветка уже закрывает часть CLI-задач
PDF-XChange EditorПолноценный Windows GUIПросмотр, аннотации и более глубокое редактирование PDFЗначительно шире по функциям, но тяжелее и не является минимальной консольной утилитой

qpdf логичнее для нового CLI-проекта: он активно поддерживается, умеет split/merge, шифрование, линейризацию и инспекцию PDF. Stapler проще в некоторых сценариях диапазонов и interleave, но проигрывает в актуальности зависимостей.

PDFsam Basic близок по повседневным операциям, но предлагает GUI и официальный кроссплатформенный desktop-релиз. Для ручной обработки это обычно удобнее.

Sumatra PDF — не прямой конкурент: это прежде всего Windows-просмотрщик многих форматов. В pre-release 3.7 появились CLI-tools вроде merge, clean и extract. Для чтения и проверки результата Sumatra PDF удобнее; Stapler ценен именно старым скриптовым синтаксисом ranges и interleave.

Для Linux-пользователя, которому нужна прежде всего визуальная проверка документов, можно также рассмотреть Okular. Это не замена Stapler как batch-processor, но хороший пример того, почему обработчик и просмотрщик лучше разделять: один инструмент перестраивает файл, второй проверяет навигацию и внешний вид.

Паспорт обратимости операций

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

ОперацияЧто сохраняетсяКак откатитьОсновной риск
sel/catВыбранные страницы и заданные поворотыУдалить результат и вернуться к исходникамЗакладки и часть документных метаданных могут не сохраниться
delВсе страницы, кроме исключённыхИспользовать оригинал или собрать новый файл зановоОшибка диапазона может удалить не ту страницу из результата
split/burstСодержимое отдельных страницИсходный файл остаётся основным эталономДокументные структуры верхнего уровня не обязаны переноситься
zipСтраницы входных файлов в чередующемся порядкеПовторить команду с исправленными диапазонамиОшибочный порядок odd/even становится заметен только при просмотре
backgroundВизуально совмещённое содержимое страницВернуться к исходным слоямПосле слияния слои нельзя штатно разъединить Stapler
info/list-logicalФайлы не изменяютсяОткат не нуженВывод предназначен для диагностики, а не редактирования

Для важных документов результат должен оставаться производным артефактом, а исходники — эталоном. При цифровых подписях, формах, закладках или архивных требованиях одного сравнения числа страниц недостаточно.

Инструкция по установке

Неизменённый Stapler 1.0.0 — пакет с зависимостями 2020 года: PyPDF2 задан как версия от 1.26 без верхней границы, а more-itertools ограничен веткой ниже 6. Upstream не публикует современную матрицу совместимости Python и ОС. Поэтому приведённая последовательность предназначена только для отдельного compatibility-окружения; она не означает, что релиз подтверждён на любой актуальной версии Python.

Windows

  1. Используйте отдельную установку Python, а не системное окружение для других приложений. Метаданные Stapler заявляют Python от 3.4 до версии ниже 4.0, но это не является подтверждением работы на современных ветках Python.
  2. В отдельной рабочей папке создайте окружение командой py -m venv .venv.
  3. Активируйте его через .venv\Scripts\Activate.ps1 в PowerShell либо соответствующий activate-скрипт в cmd.
  4. Установите релиз с ограничениями, соответствующими его зависимостям и известной несовместимости: python -m pip install «PyPDF2>=1.26,<3» «more-itertools>=2.2,<6» «stapler==1.0.0». Если resolver сообщает, что эта связка несовместима с выбранным Python, не применяйте —no-deps: используйте другое изолированное совместимое окружение либо современную альтернативу.
  5. Проверьте, что entry point виден: stapler —help. В списке должны присутствовать режимы cat/sel, del, split/burst, zip, background, info и list-logical.
  6. Не связывайте Stapler с открытием PDF по двойному клику: это не просмотрщик и не должен становиться приложением по умолчанию.

macOS и Linux

  1. Сначала проверьте, нет ли Stapler в репозитории Linux-дистрибутива: такой пакет может содержать необходимые патчи. Для исходного PyPI-релиза используйте отдельные python3 и venv; в Linux название пакета venv зависит от дистрибутива.
  2. Создайте окружение: python3 -m venv .venv, затем активируйте его командой source .venv/bin/activate.
  3. Для неизменённого PyPI-релиза установите через python -m pip ограничения PyPDF2>=1.26,<3, more-itertools>=2.2,<6 и stapler==1.0.0. При ошибке разрешения зависимостей не обходите её принудительно.
  4. Запустите stapler —help и пробную команду только на копии PDF. Не смешивайте pip-окружение с системным пакетом Stapler из репозитория дистрибутива: последний может содержать собственные патчи и другие зависимости.

Если Linux-дистрибутив предлагает свой Stapler, следуйте его правилам: пакет может уже содержать патчи для pypdf и отличаться от PyPI 1.0.0.

Первый запуск и безопасное удаление

Первый запуск лучше сделать командой info или split на копии небольшого PDF. Если Stapler установлен только в virtualenv, для удаления достаточно деактивировать окружение и удалить .venv: так не затрагиваются зависимости других программ. Системный пакет удаляется менеджером пакетов ОС. Установка Stapler в общий Python нежелательна именно из-за старых ограничений зависимостей.

Практические кейсы

Собрать итоговый PDF из отдельных диапазонов

Цель: собрать титул, основной раздел и приложение из разных файлов. Подготовка: запишите физические номера страниц. Шаги: используйте sel/cat в требуемом порядке; повторным источникам назначьте handle, а поворот задавайте R, L или D.

Проверка: сверьте число страниц, границы разделов и ориентацию. Ограничение: закладки и метаданные могут быть потеряны.

Удалить ненужные страницы, сохранив оригинал

Цель: убрать пустые или ошибочные страницы из скана. Подготовка: определите номера в физическом порядке, а не только по напечатанной нумерации. Шаги: режим del получает исходный PDF, диапазоны исключения и новое имя output. Не включайте force без необходимости. Проверка: сравните количество страниц с ожидаемым и просмотрите места вокруг каждого удаления. Ограничение: команда не понимает смысл страницы, поэтому ошибочно указанный номер будет исполнен буквально.

Свести нечётные и чётные страницы со сканера

Цель: получить один двусторонний документ из двух проходов одностороннего сканера. Подготовка: первый PDF должен содержать одну последовательность страниц, второй — противоположную; если второй проход идёт в обратном порядке, подготовьте обратный диапазон. Шаги: примените zip к двум файлам и при необходимости используйте диапазон от последней страницы к первой. Проверка: просмотрите как минимум первые, средние и последние развороты. Ограничение: Stapler не анализирует содержимое и не определяет автоматически, какой файл содержит нечётные страницы.

Наложить бланк или фоновый слой

Цель: совместить страницы двух PDF. Подготовка: проверьте одинаковый размер, ориентацию и предполагаемое положение содержимого. Шаги: используйте background, передав базовый и накладываемый PDF; диапазоны позволяют ограничить набор страниц. Проверка: сравните визуальное положение элементов и откройте итог в другом рендерере. Ограничение: это не интерактивная композиция и не система слоёв: после записи Stapler не предлагает разъединить наложенные элементы.

Навигатор по сбоям

  • Симптом: DeprecationError про PdfFileReader/PdfFileWriter. Проверьте версию PyPDF2. Для неизменённого Stapler 1.0.0 ветка 3.0.0 несовместима; восстановите изолированное окружение с PyPDF2 ниже 3 либо используйте пакет дистрибутива с патчами. Контроль — команда info на тестовом PDF завершается без traceback.
  • Симптом: «File already exists». Это штатная защита. Укажите новое имя либо сознательно добавьте force только после проверки, что старый output можно потерять. Контроль — исходные документы остаются неизменными.
  • Симптом: запрос пароля для неожиданного файла. PyPDF2 считает документ зашифрованным. Проверьте свойства PDF другим инструментом; старые алгоритмы библиотеки поддерживаются не универсально. Не подбирайте пароль и не перезаписывайте исходник.
  • Симптом: «Page not found» или Invalid range. Сверьте физическое число страниц и синтаксис диапазона. Если в документе логическая нумерация отличается от физической, сначала используйте list-logical.
  • Симптом: результат открывается, но пропало оглавление. Это соответствует известному ограничению cat. Вернитесь к оригиналу и выберите инструмент, который явно сохраняет bookmarks/outline, если навигация обязательна.

Контроль перед сохранением и передачей

  • Сохранён исходный PDF и не использован как output-путь.
  • Количество страниц соответствует плану, а диапазоны не сместились после удаления.
  • Первые, последние и пограничные страницы открываются без ошибок.
  • Поворот страниц правильный, особенно после R/L/D и zip.
  • Закладки, логические номера и метаданные проверены, если они важны получателю.
  • Для background проверены размеры страниц и визуальное совмещение слоёв.
  • Если задан пароль на output, файл повторно открыт корректными учётными данными.
  • Итоговый PDF проверен хотя бы в одном независимом рендерере перед отправкой.

Если нужен похожий набор задач без командной строки, на Windows можно рассмотреть PDF24 Creator: он относится к другому классу продукта, но подходит пользователям, которым важнее визуальные инструменты и готовая desktop-оболочка, чем встраивание команд в сценарии.

Часто задаваемые вопросы

Stapler всё ещё поддерживается?

Официального объявления о закрытии нет, репозиторий не архивирован. Но релизов нет с 2020 года, коммитов master — с 2022-го, а вопрос о поддержке, открытый в 2026 году, не подтверждает возобновление разработки. Практически upstream неактивен.

Можно ли установить Stapler на Windows 11?

Официального Windows 11-инсталлятора нет. Утилита является Python-пакетом, но upstream не публикует матрицу тестирования Windows 11 и актуальных Python; кроме PyPDF2 нужно учитывать ограничение more-itertools ниже 6. Поэтому работоспособность исходного релиза на конкретной современной установке нельзя считать подтверждённой заранее.

Нужен ли интернет для обработки PDF?

Нет обязательного облачного сервиса или аккаунта Stapler. Интернет нужен, если пакеты скачиваются из PyPI или репозитория; сами команды читают локальные файлы и записывают локальный результат. Это удобно для документов, которые нельзя отправлять в онлайн-конвертер.

Есть ли у Stapler OCR?

Нет. Утилита не распознаёт текст на сканах и не добавляет текстовый слой. Для OCR потребуется отдельное решение. Если после распознавания получены два PDF-слоя, их теоретически можно объединять через background, но это не превращает Stapler в OCR-систему и требует проверки геометрии.

Может ли Stapler редактировать текст внутри PDF?

Нет. Его операции работают на уровне страниц и контейнера: выбрать, удалить, повернуть, разделить, чередовать, наложить, вывести метаданные. Для изменения фраз, шрифтов, изображений и интерактивных объектов нужен PDF-редактор, например Adobe Acrobat Pro или другой инструмент соответствующего класса.

Сохраняет ли Stapler закладки и метаданные?

Нельзя рассчитывать на полное сохранение. В открытом issue показано, что после cat может исчезнуть outline и meta title. Команда info умеет читать documentInfo, но функции штатного редактирования метаданных в наборе режимов нет. Если структура документа критична, проверяйте её после каждой трансформации.

Что выбрать для нового скрипта: Stapler или qpdf?

Для нового долгоживущего проекта qpdf безопаснее по состоянию сопровождения. Stapler оправдан, если уже есть рабочий сценарий с его синтаксисом или нужен zip; миграцию проверяйте на контрольных PDF.

Почему не использовать только Sumatra PDF?

Если задача — чтение и проверка PDF, Sumatra PDF рациональнее и удобнее. Если нужна автоматизированная перестройка страниц, Stapler исторически специализирован именно на этом. При этом актуальная pre-release ветка Sumatra PDF 3.7 уже содержит набор командных PDF-tools, поэтому для Windows имеет смысл сначала проверить, закрывают ли они нужный сценарий без отдельной старой Python-зависимости.

Вывод

Stapler остаётся интересным компактным инструментом для тех, кому нужен понятный CLI-синтаксис выбора, удаления, разбиения, чередования и наложения страниц PDF. Его сильные стороны — локальная обработка, свободная BSD-лицензия, отсутствие аккаунта, удобные page ranges и возможность встраивать команды в повторяемые сценарии. Для старого стабильного workflow, где версии Python и PyPDF2 уже зафиксированы, миграция может быть необязательной.

Для новой установки в 2026 году картина иная. Upstream давно не выпускал релизы, старый API конфликтует с PyPDF2 3.0.0, современная совместимость обеспечивается в основном downstream-патчами, а полное сохранение закладок и метаданных не гарантируется. Если нужен активно сопровождаемый CLI-процессор, логичнее начать с qpdf. Если операции выполняются вручную, PDFsam Basic даст более безопасный визуальный процесс. Для чтения и контроля результата на Windows разумнее Sumatra PDF. Stapler имеет смысл выбирать осознанно — как узкую, воспроизводимо закреплённую утилиту, а не как универсальный актуальный PDF-комбайн.


Ваш адрес email не будет опубликован. Обязательные поля помечены *