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

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

Работа строится вокруг режима, входных PDF, диапазонов страниц и имени результата. Режим задаёт операцию, диапазоны определяют физические страницы и их порядок, суффиксы R, L и D задают поворот, а параметры вывода позволяют выбрать каталог, разрешить перезапись и при необходимости защитить полученный PDF паролями. При этом Stapler не показывает миниатюры страниц и не предоставляет инструменты правки текста, поэтому перед сложной командой полезно отдельно проверить нумерацию документа.

Что именно делает Stapler с PDF

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

Для выходного документа код создаёт новый PDF writer и добавляет в него страницы входных файлов. Из этого следует важная практическая граница: Stapler не предоставляет отдельной команды для исправления абзаца, шрифта, встроенного изображения, аннотации или поля формы. Задача вида взять страницы 2–5 из первого файла, страницу 1 из второго, повернуть один лист и сохранить всё в новый PDF соответствует его модели; задача исправить слово на странице — нет.

Дополнительные режимы используют ту же страничную модель по-разному. split создаёт отдельный PDF для каждой страницы, zip берёт очередную страницу из каждого подготовленного набора, background объединяет содержимое страниц одной позиции, info печатает словарь documentInfo, а list-logical сопоставляет логические метки страниц с физическими позициями. Благодаря этому основные сценарии можно строить из небольшого числа понятных операций.

Командный интерфейс и схема вызова

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

stapler [options] mode arguments

Из общих параметров предусмотрены -v для подробного вывода, -f для разрешения перезаписи и -d для каталога назначения. -o и -u задают соответственно пароль владельца и пользователя при шифровании выходного PDF. Сами диапазоны остаются позиционными аргументами. Такая схема компактна, но требует аккуратности: визуального окна, которое показывало бы итоговый порядок страниц до записи, в Stapler нет.

Справка одновременно фиксирует синтаксис диапазонов. Одиночный номер выбирает одну страницу, n-m — включительный диапазон, обратный диапазон меняет последовательность, end означает последнюю страницу конкретного входа, а R, L и D после номера или диапазона задают поворот. Эти правила используются там, где режим принимает страницы, поэтому однажды проверенный синтаксис переносится между sel, zip и background.

Выбор страниц и сборка нового файла: sel и cat

Режим sel — главный конструктор нового документа. Он читает один или несколько PDF и добавляет выбранные страницы в новый writer в том порядке, который получился после разбора аргументов. Имя cat является псевдонимом той же операции. Если для входного PDF не задан диапазон, используется весь файл; если диапазоны есть, берутся только перечисленные физические страницы.

Порядок пользователя сохраняется буквально. Можно взять первую страницу alpha.pdf, затем страницы 3–5 того же файла с поворотом вправо и после этого страницы 2–4 beta.pdf. Stapler не сортирует выбор по исходной нумерации и не пытается исправить последовательность автоматически. Это даёт полный контроль над структурой, но именно пользователь отвечает за то, что перечисление соответствует желаемому результату.

stapler -v -d out sel A=alpha.pdf B=beta.pdf A1 A3-5R B2-end selected.pdf

Флаг -v особенно полезен при отладке sel. Для каждого входа печатается имя файла, затем физический номер каждой используемой страницы и применяемый угол. По этим строкам можно проверить, как команда развернула диапазоны, ещё до детального просмотра результата. В регулярном процессе такой вывод удобно сохранять в журнал задания.

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

Обратные диапазоны

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

Например, если первые восемь страниц скана идут правильно, а блок 9–14 получен в обратном порядке, в sel можно использовать 1-8 и 14-9. Если сам блок ещё и лежит боком, к обратному диапазону добавляется соответствующий суффикс поворота. Такое сочетание полезно для сканов, но его разумно сначала проверить на нескольких листах с -v.

Слово end в диапазонах

end заменяется номером последней страницы текущего PDF во время разбора команды. 3-end означает страницы с третьей до последней, end-1 — весь документ от конца к началу. Это удобно в сценариях, где количество страниц меняется от файла к файлу, но правило обработки должно оставаться общим.

У каждого входа собственное значение end. В одной команде A2-end и B2-end вычисляются относительно разных PDF. Поэтому end уменьшает жёсткую привязку к размеру документа, но не несёт смысловой информации: программа не знает, где закончился раздел, приложение или глава, и просто использует последнюю физическую страницу.

Повороты R, L и D

Суффикс R задаёт 90 градусов по часовой стрелке, L — 270 градусов по часовой стрелке, то есть поворот на 90 градусов влево, D — 180 градусов. Записи 4R, 2-6L и 8D применяют один угол к указанной странице или ко всему диапазону. В подробном выводе рассчитанный угол показывается рядом с каждым физическим номером.

Поворот выполняется при добавлении страницы в новый writer. Это позволяет одновременно извлечь нужный фрагмент и исправить ориентацию отдельных листов. Если требуется только изменить порядок, суффикс не нужен; если требуется только изменить ориентацию, порядок диапазона оставляют прямым. Раздельное понимание этих двух механизмов заметно упрощает сложные команды.

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

Stapler позволяет связать входной файл с одной заглавной латинской буквой. Аргумент вида A=input.pdf создаёт дескриптор A, после чего к этому PDF можно обращаться как A1, A4-9, Aend-2 или с суффиксом поворота. Распознаватель ожидает именно одну заглавную букву, поэтому строчные дескрипторы не следует считать эквивалентными.

Дескрипторы особенно полезны, когда один источник участвует в нескольких местах результата или когда несколько файлов чередуются. Вместо повторения длинного пути команда становится короче и легче проверяется глазами. Практически разумно назначать буквы по роли источника: A — основа, B — второй поток, C — дополнительный файл. Тогда логика строки остаётся понятной даже спустя время.

Диапазон с буквой явно переключает контекст на соответствующий вход. Если буква ранее не определена, Stapler завершает команду сообщением о несуществующем filehandle. Это полезная защита от опечатки: программа не пытается угадать, к какому файлу относился диапазон. В длинных командах первый диапазон каждого нового блока лучше писать с буквой даже тогда, когда соседний контекст кажется очевидным.

Удаление страниц: режим del

del использует тот же механизм разбора файлов и диапазонов, что и sel, но затем строит дополнение: в выход попадают все страницы, чьи физические номера не были перечислены. Для шестистраничного файла исключение 1 и 6 создаёт документ из страниц 2, 3, 4 и 5. Это удобнее sel, когда удалить нужно несколько листов, а основную массу документа требуется оставить в прежней последовательности.

stapler -v -d out del alpha.pdf 1 6 trimmed.pdf

Подробный вывод del показывает уже фактически используемые страницы, а не перечень исключений. Поэтому после команды выше в журнале видны 2, 3, 4 и 5. Такой вывод помогает быстро проверить дополнение к диапазону и заметить ошибку физической нумерации без ручного пересчёта всего документа.

Поворотные суффиксы в списке исключаемых страниц не дают полезного эффекта: обратная ветка select формирует номера для исключения, а оставшиеся страницы добавляет с нулевым поворотом. Если требуется одновременно удалить одни листы и развернуть другие, понятнее перейти к sel и явно описать оставляемые диапазоны с нужными R, L или D либо сделать две контролируемые операции.

Разбиение документа: split и burst

Режим split создаёт отдельный PDF для каждой страницы каждого переданного входного файла. Псевдоним burst вызывает ту же функцию. Имя результата формируется из базового имени источника, подчёркивания, номера страницы и расширения. В проверочном четырёхстраничном beta.pdf были созданы beta_1.pdf, beta_2.pdf, beta_3.pdf и beta_4.pdf.

stapler -v -d out split beta.pdf

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

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

split не превращает страницы в PNG, JPEG, TIFF или текст. Каждый результат остаётся PDF с одной страницей. Если следующему этапу нужны изображения или OCR-текст, потребуется отдельный инструмент. Это принципиальная граница функции: Stapler разделяет PDF на PDF, а не является конвертером содержимого.

Чередование страниц: режим zip

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

stapler -v -d out zip alpha.pdf 1-3 beta.pdf 1-2 interleaved.pdf

Такой алгоритм хорошо подходит для восстановления порядка после одностороннего сканирования двустороннего оригинала. Первый PDF может содержать нечётные стороны, второй — чётные. Если второй поток был получен после переворота стопки и идёт от конца к началу, диапазон можно записать как end-1. Тогда обратная последовательность и само чередование выполняются одним вызовом.

Порядок входов влияет на каждый цикл. Если первым указан поток чётных страниц, именно он будет стоять перед соответствующей нечётной страницей. Stapler не читает напечатанные номера, не распознаёт изображение и не пытается определить, какой поток логически должен быть первым. Команда является полным описанием порядка.

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

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

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

stapler -v -d out background alpha.pdf 1-3 overlay.pdf 1-3 overlaid.pdf

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

Практическая область применения — заранее созданный бланк, рамка или иной подготовленный слой. Если размеры страниц источников не совпадают, программа не выдаёт отдельного диалога исправления геометрии. Результат нужно проверять визуально, особенно по краям листа. Если требуется сдвиг, масштабирование или прозрачность, эти преобразования должны быть выполнены до Stapler либо другим инструментом.

Как и zip, background проходит до максимальной длины наборов. Если на очередной позиции есть только одна страница, она станет результатом без второго слоя. Более короткий файл наложения поэтому не вызывает предупреждения о том, что слой закончился раньше. Для повторяемого процесса длину overlay стоит проверять как входное условие.

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

info открывает PDF, читает documentInfo и печатает найденные пары ключ–значение. В тестовом документе выводились Producer, Title, Author, Subject и Keywords. Если словарь метаданных отсутствует, Stapler явно сообщает, что метаданные не найдены. Новый PDF в этом режиме не создаётся.

stapler info alpha.pdf

info является режимом чтения, а не редактором метаданных. В списке команд нет операции, которая меняла бы Title, Author или другие поля documentInfo. Поэтому его удобно использовать для диагностики перед сборкой или для быстрого сравнения нескольких документов, но не для нормализации свойств итогового файла.

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

Логические метки страниц: list-logical

PDF может хранить PageLabels, из-за которых подпись страницы в просмотрщике отличается от её физической позиции. Вступление бывает пронумеровано римскими числами, затем основная часть начинается с 1, а приложения получают буквенный префикс. list-logical читает эту структуру и печатает логическую метку рядом с физическим номером. Псевдоним list-log ведёт к той же функции.

stapler list-logical alpha.pdf

В реализации поддерживаются десятичная нумерация, латинские буквы верхнего и нижнего регистра, римские числа обоих регистров, а также префикс и стартовое значение раздела. Если PageLabels нет, программа возвращается к обычной последовательности 1, 2, 3 и далее. Поэтому команду можно использовать как безопасную карту физических позиций даже у простого документа.

Это особенно важно перед sel или del. Диапазоны этих режимов адресуют физические страницы, а не логические подписи. Если просмотрщик показывает Intro-ii или A-3, list-logical помогает определить число, которое действительно нужно передать Stapler. Напечатанная цифра внутри изображения страницы при этом не анализируется: команда читает только структуру PDF.

Повреждённый PageLabels может привести к диагностической ошибке. Код отдельно ожидает массив Nums и распознаваемый стиль нумерации. Если структура заявлена, но необходимые элементы отсутствуют, Stapler не пытается угадать нумерацию. Такой PDF следует проверять или исправлять отдельным средством, а физические позиции временно определять независимым просмотрщиком.

Диапазоны страниц без скрытой магии

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

Одиночная запись 5 превращается в последовательность из одной страницы. 2-7 разворачивается в 2, 3, 4, 5, 6, 7; 7-2 — в 7, 6, 5, 4, 3, 2. Один суффикс поворота прикрепляется ко всем страницам сформированного диапазона. Благодаря этому один короткий аргумент описывает сразу и порядок, и ориентацию блока.

Контекст диапазона задаётся текущим входным файлом. Имя PDF начинает новую операцию, а следующие диапазоны относятся к нему, пока не появится другой вход или диапазон с дескриптором. В больших командах это экономит текст, но может усложнить чтение. Явное использование A, B и C перед первым диапазоном каждого блока делает строку устойчивее к человеческим ошибкам.

Что происходит при ошибочном диапазоне

Если диапазон выходит за пределы документа, сообщение содержит фактические границы запроса, максимальный номер и имя файла. В проверочном шестистраничном PDF запрос 2-99 был отклонён с указанием максимальной страницы 6. Результат не создаётся. Для автоматизации это важнее, чем молчаливое использование только существующей части диапазона: ошибка входных предпосылок становится заметной.

stapler -d out sel alpha.pdf 2-99 bad.pdf

Неизвестный дескриптор также вызывает ошибку. Аргумент, который не распознаётся как PDF или допустимый диапазон, получает диагноз Invalid range. Отсутствие требуемых позиционных аргументов приводит к сообщению конкретного режима. Поэтому надёжный вызывающий сценарий должен анализировать код завершения, а не только проверять, появился ли какой-либо файл с ожидаемым именем.

Практически безопасный порядок таков: проверить входы, создать каталог назначения, выполнить команду без -f, проверить код завершения и только затем передавать результат следующему этапу. При повторном запуске старый результат лучше удалять контролируемо или менять имя. Автоматическое добавление -f ко всем операциям лишает процесс полезной защиты от случайной замены.

Каталог назначения и перезапись

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

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

Если выходное имя является абсолютным путём, оно используется напрямую. Если имя относительное, к нему добавляется каталог -d. split также пишет все одностраничные файлы в каталог назначения. В автоматическом процессе лучше выбрать одно соглашение — либо всегда абсолютные пути, либо рабочий каталог плюс -d, — чтобы место записи не зависело от случайного текущего каталога процесса.

Подробный режим -v как средство контроля

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

В сложной сборке журнал помогает восстановить причину ошибки. Если в результате обнаружена неправильная страница, можно найти соответствующую строку Using page и понять, из какого блока аргументов она появилась. Это особенно полезно с end, обратными диапазонами и несколькими дескрипторами, где короткая команда разворачивается в длинную физическую последовательность.

Сам Stapler не создаёт отдельный log-файл и не предлагает уровни журналирования. Вывод идёт в стандартные потоки процесса. Сохранение журнала, отметки времени, идентификатора задания и ротация файлов относятся к оболочке или системе автоматизации. Для регулярной обработки это даже удобно: журнал Stapler можно объединить с логами остальных этапов.

Работа с защищёнными входными PDF

При чтении PDF Stapler проверяет признак шифрования. Если документ защищён, программа запрашивает пароль в терминале и передаёт его библиотеке. При неверном значении выводится сообщение The password did not match, затем запрос повторяется. Ввод пароля скрыт. Пользователь может прервать запрос, после чего процесс завершается отдельным кодом.

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

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

Пароли для выходного файла

Параметры -u и -o применяются при записи нового PDF. -u задаёт user password, -o — owner password. Если указан хотя бы один параметр, writer вызывает функцию encrypt. Если задан только пароль владельца, пользовательский пароль передаётся как пустая строка. Эти параметры относятся ко всему выходному документу независимо от того, был он создан через sel, del, zip или background.

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

Пароль, записанный прямо в командной строке, потенциально может оказаться в истории оболочки или быть видимым средствам операционной системы. Это свойство способа запуска, а не специальная функция Stapler, но его нельзя игнорировать. Секреты не стоит хранить в общедоступных скриптах и логах; если нужна интеграция с хранилищем секретов, штатный CLI Stapler сам её не предоставляет.

Форматы и границы совместимости

Распознаватель входов принимает имена, заканчивающиеся на .pdf без учёта регистра. Выходные операции также создают PDF. В списке режимов отсутствует импорт Word, Excel, изображений, PostScript или HTML, а split не экспортирует страницы в растровый формат. Следовательно, Stapler предназначен для перестройки PDF, а не для конвертации разных типов документов.

Опубликованный пакет 1.0.0 имеет wheel с тегом py3-none-any. В метаданных проекта указан Python не ниже 3.4 и ниже 4.0, зависимость — PyPDF2 не ниже 1.26. Тег none-any показывает, что сам wheel не привязан к процессорной архитектуре, но реальная совместимость зависит от Python и PDF-библиотеки. Для стабильного процесса разумно фиксировать проверенную комбинацию зависимостей.

В pyproject зарегистрированы две консольные точки входа: stapler и pdf-stapler. Они ведут к одной функции запуска. В примерах используется короткое имя stapler, поскольку оно же фигурирует в основной документации. Если после установки команда не находится, следует проверить каталог скриптов выбранной Python-среды и то, какая точка входа фактически добавлена в PATH.

Каталог Fedora содержит пакет pdf-stapler, связанный с тем же upstream-репозиторием. Это дополнительное подтверждение идентичности Linux-пакета, но статья не смешивает его с одноимёнными GUI-программами. Для скачивания в пакете материалов выбран официальный PyPI wheel, потому что он прямо относится к версии проекта и не зависит от конкретного менеджера пакетов дистрибутива.

Сохранность свойств документа при пересборке

Страничная сборка не равна полному копированию каталога исходного PDF. В sel создаётся новый writer и в него добавляются выбранные Page-объекты. Явного переноса documentInfo, дерева закладок или PageLabels в этой функции нет. Поэтому нельзя обещать автоматическое сохранение всех свойств уровня документа только на основании того, что видимое содержимое страниц выглядит правильно.

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

Цифровые подписи требуют особого внимания. Создание нового документа с изменённой структурой не является сохранением криптографически подписанного байтового состояния исходника. Stapler не выполняет валидацию сертификатов и не позиционируется как средство электронной подписи. Юридически значимые документы следует обрабатывать только в рамках принятой процедуры и отдельно контролировать статус подписей.

Известное ограничение повторного выбора одной страницы с разными поворотами

В TODO проекта отдельно отмечен случай, когда одна и та же страница одного PDF добавляется несколько раз с различными поворотами, например 1R и затем 1D. Поворот изменяет используемый Page-объект, поэтому повторное обращение способно дать накопленный результат, отличный от ожидаемых независимых копий. Такой сценарий нельзя считать надёжным без проверки.

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

Сценарий: собрать обложку, основную часть и приложение

Представим три PDF: cover.pdf с обложкой, body.pdf с основной частью и appendix.pdf с приложением. Если порядок заранее известен, sel может собрать их без промежуточного графического редактора. Для каждого источника задаются нужные физические страницы, после чего последний аргумент становится именем результата. Если часть body.pdf не нужна, проще не включать её в диапазон, чем создавать лишний промежуточный файл только ради удаления.

stapler sel A=cover.pdf B=body.pdf C=appendix.pdf A1 Bend-1 C1-end result.pdf

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

Если внутри основной части отдельный блок нужно повернуть, его разбивают на соседние диапазоны: до проблемного места, диапазон с R/L/D и оставшийся хвост. Это позволяет выполнить перестановку и коррекцию ориентации одной сборкой. Чем больше таких фрагментов, тем важнее использовать дескрипторы и сохранять исходную команду рядом с результатом.

Сценарий: удалить титульный лист и служебные страницы

Когда документ почти целиком нужен в исходном порядке, del обычно короче sel. Для двадцатистраничного файла можно исключить, например, 1, 8, 12 и 20, а Stapler автоматически добавит остальные физические страницы. Такой способ хорошо подходит к документам с несколькими заранее известными пустыми, титульными или служебными листами.

stapler -v del report.pdf 1 8 12 20 report-clean.pdf

Stapler сам не определяет, что страница пустая или служебная. Он не анализирует количество текста, белый фон или смысл содержимого. Номера должны быть известны из просмотра, результатов другого анализатора или бизнес-правила. Поэтому del является исполнителем решения, а не средством автоматической классификации страниц.

После удаления физические позиции оставшихся страниц меняются. Если следующий этап также использует диапазоны, рассчитанные для исходного PDF, они могут стать неверными. Либо объединяйте понятные действия в один sel, либо пересчитывайте номера относительно непосредственного промежуточного файла. Это особенно важно, если второй этап удаляет страницы по номерам из документации к исходнику.

Сценарий: восстановить двусторонний порядок после сканирования

Один из наиболее естественных случаев для zip — два файла, полученных односторонним автоподатчиком из двустороннего оригинала. В первом находятся нечётные стороны, во втором — чётные. После переворота стопки второй поток часто получается в обратном порядке, поэтому его можно передать как end-1. Затем zip берёт по одной странице из каждого списка.

stapler zip A=odd.pdf B=even.pdf A1-end Bend-1 collated.pdf

Перед запуском важно определить, с какой стороны начинается второй скан и есть ли пустая оборотная страница в конце. zip не потребует одинаковой длины потоков и просто допишет остаток длинного списка. Поэтому итоговое число страниц и последнюю пару обязательно стоит проверить. Это позволяет отличить нормальный дополнительный хвост от пропущенного скана.

Если один поток получен боком, к его диапазону можно добавить R или L. Тогда все выбранные страницы будут развернуты ещё до чередования. Такой вариант уменьшает число этапов, но первая проверка должна охватывать начало, середину и конец документа, чтобы убедиться, что направление поворота выбрано верно для всей партии.

Сценарий: наложить подготовленный бланк

background полезен, если нужно совместить основное содержимое с заранее созданным PDF-слоем. Основной документ указывается первым, подготовленный бланк — следующим. Страницы с одинаковой позицией объединяются. Если оба файла имеют одинаковую длину и геометрию, получится последовательность страниц с совмещённым содержимым.

Одностраничный бланк Stapler не тиражирует автоматически на все страницы основного PDF. В коде нет режима повторять первую страницу слоя до конца. Для такого процесса слой нужно заранее размножить до нужной длины либо выбрать другой инструмент, который умеет циклическое применение watermark/overlay. Это важное ограничение, чтобы не ожидать от background лишней логики.

Наложение не содержит настройки прозрачности, масштаба, отступов и координат. Если слой после mergePage оказывается смещён или обрезан, исправлять следует исходную геометрию overlay. Проверяйте размеры MediaBox/CropBox независимым инструментом и делайте тест на одной-двух страницах перед обработкой большого документа.

Сценарий: извлечь раздел и исправить ориентацию

Предположим, из большого скана нужны страницы 40–57, а листы 44–46 лежат боком. sel позволяет разбить диапазон на три части: 40–43 без поворота, 44–46 с R или L и 47–57 без поворота. Итогом становится один PDF только с нужным разделом, где проблемные страницы уже имеют заданную ориентацию.

stapler sel scan.pdf 40-43 44-46R 47-57 excerpt.pdf

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

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

Сценарий: разделить архив на одностраничные PDF

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

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

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

Сценарий: проверить нумерацию перед удалением

Книги, руководства и отчёты часто имеют обложку и вводную часть, из-за которых физический номер не совпадает с видимой нумерацией. Просмотрщик может показывать iii, затем 1, 2, 3, тогда как физически это страницы 3, 4, 5 и 6. del 3 удалит именно третью Page-позицию, а не лист, помеченный логической цифрой 3.

list-logical даёт карту между PageLabels и физическими номерами. По ней можно перевести редакционное требование удалить A-3 в конкретное число для sel или del. Такой шаг особенно важен, если в документе несколько секций с разными префиксами. Если PageLabels отсутствуют, команда всё равно выводит последовательность физических номеров.

Напечатанные номера внутри изображения или текста страницы не участвуют в этой логике. Если автор PDF не настроил PageLabels, а номер виден только в колонтитуле, понадобится просмотр документа или OCR другим средством. Stapler не делает вывод о физической позиции по содержимому.

Сценарий: инвентаризация метаданных серии PDF

info принимает несколько входов, поэтому им удобно быстро просмотреть служебные поля перед объединением партии. Если Title, Author или Producer различаются, это видно в последовательных секциях консольного вывода. Такой аудит помогает решить, потребуется ли после страничной сборки отдельная нормализация метаданных.

Вывод можно перенаправить в текстовый файл средствами оболочки, но сам Stapler не создаёт структурированный отчёт. У разных PDF набор ключей documentInfo может отличаться, а порядок полей зависит от данных библиотеки. Для строгой машинной проверки лучше использовать PDF-инспектор или Python-код, а info оставить как быстрый диагностический режим.

Пустой documentInfo не означает, что документ лишён всей служебной структуры. В каталоге PDF могут находиться PageLabels, outlines, формы и другие объекты, которые info не перечисляет. Поэтому команду нельзя считать полным техническим аудитом PDF. Она отвечает на более узкий вопрос: какие пары documentInfo доступны библиотеке.

Типичная ошибка: входной файл не найден

read_pdf сначала проверяет существование пути. Если файл отсутствует, команда завершается сообщением с его именем. Чаще всего причина — неверный рабочий каталог, опечатка или неправильные кавычки вокруг пути с пробелами. Stapler не ищет файл в соседних папках и не исправляет имя автоматически.

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

Типичная ошибка: каталога после -d нет

Каталог назначения должен существовать до разбора режима. Если указан несуществующий путь, Stapler прекращает выполнение. Это особенно часто встречается с временными директориями, которые очищаются между заданиями. Создайте каталог средствами оболочки и только затем запускайте команду.

Не стоит путать отсутствие каталога с запретом на запись. Если папка существует, но процесс не имеет достаточных прав, ошибка возникнет уже при открытии выходного файла. Такие права настраиваются средствами операционной среды; у Stapler нет собственного менеджера разрешений файловой системы.

Типичная ошибка: результат уже существует

Без -f существующий выход защищён от перезаписи. Это поведение полезно считать сигналом для проверки, а не неудобством, которое всегда нужно подавлять. Совпадение имени может означать повторный запуск, неверно вычисленный путь или то, что в каталоге остался результат другой партии.

Если замена действительно требуется, добавьте -f осознанно. Для регулярного процесса безопаснее писать во временное новое имя, проверить результат и затем заменить рабочий файл отдельной операцией. Особенно аккуратно используйте -f со split, где один вызов создаёт много файлов и способен заменить целую серию совпадающих имён.

Типичная ошибка: неверный дескриптор

Диапазон A3-8 допустим только после того, как A был связан с файлом аргументом вида A=input.pdf. Если дескриптор не существует, программа сообщает об ошибке. Проверяйте регистр: шаблон использует заглавную букву. В очень длинной строке проще определить дескрипторы в начале логического блока, чем полагаться на память о ранее заданных связях.

Не переиспользуйте одну букву для разных файлов без необходимости. Внутренний словарь дескрипторов обновит связь, и дальнейшие диапазоны будут относиться уже к новому значению. Технически это возможно, но резко ухудшает читаемость и усложняет анализ журнала. Одно стабильное обозначение на один источник — лучший практический стиль.

Типичная ошибка: защищённый PDF ждёт пароль

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

Не пытайтесь решить эту проблему параметрами -u или -o: они задают защиту нового файла. Штатного input password аргумента у Stapler нет. Для автоматизированного потока либо входы должны быть подготовлены заранее, либо следует выбрать инструмент с подходящим механизмом безопасной передачи пароля.

Типичная ошибка: слой background смещён

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

Затем проверьте порядок входов. Если файл бланка указан первым, именно его страница станет базовой, а основной документ будет добавлен поверх. Иногда видимый результат похож, но CropBox или размеры могут отличаться от ожидаемых. Для стабильной схемы роль каждого источника нужно зафиксировать и проверить на контрольной странице.

Типичная ошибка: zip даёт неправильную последовательность

Разложите первые три позиции каждого входного списка вручную. Если A = A1, A2, A3, а B = B4, B3, B2, итог должен начинаться A1, B4, A2, B3, A3, B2. Если ожидается другой порядок, поменяйте порядок источников или направление диапазона. zip не сортирует страницы по меткам.

Поворот применяется при подготовке списков, до чередования. Поэтому B4-2R означает B4R, B3R, B2R, которые затем занимают свои места между страницами A. -v показывает использованные страницы и углы по каждому входу, но не печатает отдельный итоговый список чередования, поэтому контрольную последовательность лучше выписать заранее.

Как безопасно проектировать длинную команду

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

1. Проверьте число физических страниц каждого источника и, если есть сложные PageLabels, выполните list-logical.
2. Опишите нужную последовательность без сокращений: какие страницы какого файла должны идти первыми, какие дальше.
3. Отдельно отметьте R, L и D, чтобы не смешивать ориентацию листа с обратным порядком диапазона.
4. Создайте пустой каталог назначения и первый запуск выполняйте без -f.
5. Сохраните подробный вывод и сверяйте строки Using page с подготовленным планом.
6. Откройте результат независимым PDF-просмотрщиком и проверьте переходы между блоками, повороты и количество страниц.
7. Только после успешного теста переносите команду в регулярный сценарий и решайте, нужна ли автоматическая перезапись.

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

Автоматизация и код завершения

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

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

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

Чего Stapler не делает

• Не предоставляет окно с миниатюрами и перетаскиванием страниц мышью.
• Не редактирует текстовые блоки, шрифты и изображения внутри страницы.
• Не выполняет OCR и не определяет напечатанные номера страниц по содержимому.
• Не конвертирует DOCX, XLSX, изображения или HTML в PDF.
• Не экспортирует страницы split в PNG, JPEG или TIFF.
• Не имеет команды изменения documentInfo: info только читает его.
• Не задаёт масштаб, координаты и прозрачность для background.
• Не создаёт отсутствующий каталог назначения автоматически.
• Не имеет отдельного аргумента пароля для зашифрованного входного PDF.
• Не проверяет цифровые подписи и сертификаты.

Эти границы определяют правильную нишу программы. Stapler особенно уместен, когда задача сводится к точному правилу какие физические страницы взять, в каком порядке их записать и какие из них повернуть. Если решение зависит от визуального содержимого страницы или от редактирования объектов внутри неё, лучше выбрать другой класс программ.

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

Программа	Лучше подходит для	Главное ограничение
Stapler	Скриптового выбора, удаления, чередования и наложения страниц PDF	Нет графического предпросмотра и правки содержимого страницы
PDFtk Server	Командной обработки PDF с объединением, разбиением и shuffle	Требует точного командного синтаксиса и не является визуальным редактором
qpdf	Глубокой структурной обработки, выбора страниц, шифрования, overlay и underlay	Технический CLI сложнее для разовой ручной перестановки страниц
PDFsam Basic	Визуального объединения, разделения, извлечения, поворота и смешивания страниц	Основной рабочий процесс ориентирован на графические модули, а не на короткие Stapler-команды
pdfunite + pdfseparate	Простого объединения PDF и разбиения на отдельные страницы	Набор страничных операций уже и не заменяет единые zip/background Stapler

Если нужна повторяемая команда с диапазонами, обратным порядком, поворотами и особенно восстановлением чередования сканов, Stapler остаётся компактным решением. qpdf лучше подходит для более глубокой структурной обработки и богатых параметров PDF; PDFtk Server близок по командной модели и имеет более широкий классический инструментарий; PDFsam Basic удобнее там, где оператор должен работать визуально; pdfunite и pdfseparate хороши для простых merge/split без сложной логики. Выбирать стоит по конкретной операции, а не по общему ярлыку редактор PDF.

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

Stapler и PDFtk Server

Официальный проект прямо называет Stapler Python-альтернативой PDFtk, что объясняет сходство терминов cat, burst и модели диапазонов. PDFtk Server также является командным инструментом и умеет merge, split и shuffle. Однако Stapler нельзя считать полной реализацией всех команд PDFtk: его допустимые режимы перечислены в собственном parser и документации, и за пределами этого списка функции не следует предполагать.

При переносе старого сценария нужно проверять каждую операцию отдельно. Выбор страниц и перестановка обычно переводятся естественно; чередование сканов соответствует zip/shuffle по смыслу. Но функции PDFtk для форм, вложений или других специальных структур нельзя автоматически приписывать Stapler только из-за общей идеи проекта. Сходство назначения не равно полной совместимости CLI.

Stapler и qpdf

qpdf предоставляет современный командный инструментарий для структурных преобразований PDF: выбор страниц, overlay/underlay, шифрование, диагностику и другие операции. Stapler проще: его модель сосредоточена на нескольких страничных режимах. Если задача уже коротко выражается через sel, del, zip или background, простота может быть преимуществом. Если требуется тонкая работа со структурой PDF, qpdf предлагает больше специализированных средств.

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

Stapler и PDFsam Basic

PDFsam Basic предлагает графические модули для объединения, разделения, извлечения, поворота и смешивания страниц. Когда порядок определяется по содержимому и оператору нужно видеть настройки и списки файлов, такой интерфейс удобнее терминала. Stapler лучше раскрывается в противоположном случае: правило известно заранее и должно выполняться одинаково без ручного кликанья.

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

Stapler и pdfunite/pdfseparate

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

Если процесс состоит только из соединить три PDF целиком или разбить документ на страницы, более узкая утилита может быть проще. Если приходится восстанавливать порядок сканов, разворачивать отдельные диапазоны и комбинировать страницы разных файлов в одной команде, преимущества Stapler становятся заметнее.

Контроль результата после sel и del

После sel проверьте количество страниц и границы каждого логического блока. Особенно внимательно смотрите места, где меняется источник, направление диапазона или угол. Если результат содержит страницы из нескольких PDF, первые и последние листы каждого источника являются хорошими контрольными точками. -v помогает связать их с физическими номерами.

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

Контроль результата после zip

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

Если оба потока должны иметь одинаковую длину, внешняя проверка этого условия лучше, чем надежда на ошибку Stapler. Алгоритм специально допускает разные размеры. В сценарии можно сначала узнать число страниц каждого PDF, проверить ожидаемое соотношение и только затем запускать zip.

Контроль результата после background

Для background первым делом смотрите геометрию. Слой должен совпадать с основной страницей по ожидаемому формату и положению. Затем проверяйте порядок наложения: первая страница позиции является базовой, последующие объединяются с ней. Тестовый слой с заметной контрольной отметкой помогает быстро убедиться, какой вход находится сверху.

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

Контроль результата после split

Количество созданных файлов должно совпадать с суммарным числом страниц входов. -v сообщает счётчики, но полезно также проверить фактическое содержимое каталога. Особое внимание — одинаковым basename из разных директорий: имена одностраничных результатов строятся именно из basename, поэтому два report.pdf способны конфликтовать.

Лексикографическая сортировка имён зависит от того, как сформированы номера одностраничных файлов. Stapler строит имя автоматически и не предлагает отдельный пользовательский шаблон. Если дальнейший процесс строго полагается на порядок имён, проверьте его на документе реального размера и при необходимости сортируйте результаты по числовому номеру страницы, а не только как обычные строки.

Практическая памятка по синтаксису

Элемент	Пример	Смысл
Одиночная страница	5	Пятая физическая страница
Прямой диапазон	2-7	Страницы со 2 по 7 включительно
Обратный диапазон	7-2	Страницы 7, 6, 5, 4, 3, 2
До конца	3-end	От третьей до последней страницы
От конца назад	end-1	Все страницы в обратной последовательности
Поворот вправо	4R	Поворот страницы на 90° по часовой стрелке
Поворот влево	4L	Поворот страницы на 90° влево
Разворот	4D	Поворот страницы на 180°
Дескриптор	A=file.pdf	Связать PDF с буквой A
Диапазон дескриптора	A2-endR	Страницы A со второй до конца с поворотом вправо

Диапазон без буквы относится к последнему активному входу, а запись с A, B или другой определённой буквой явно переключает контекст. В короткой команде неявный контекст экономит символы; в длинной явный дескриптор часто лучше, потому что облегчает проверку человеком и снижает риск случайно применить диапазон к предыдущему файлу.

Как выбирать между sel, del, zip и background

sel отвечает на вопрос какие страницы и в каком порядке должны стать отдельными страницами результата. del удобнее, когда проще перечислить то, что нужно убрать. zip нужен, когда несколько последовательностей следует чередовать. background решает другую задачу: страницы одинаковой позиции должны стать одним визуальным листом с объединённым содержимым.

• Выбирайте sel для произвольной сборки из диапазонов одного или нескольких PDF.
• Выбирайте del, когда список исключений значительно короче списка сохраняемых страниц.
• Выбирайте zip для потоков A1, B1, A2, B2 и аналогичных схем.
• Выбирайте background, когда A1 и B1 должны объединиться в одну страницу, а не идти рядом.
• Выбирайте split, когда каждой физической странице нужен отдельный PDF.
• Запускайте info или list-logical до изменения файла, если сначала нужны служебные данные для правильного правила.

Если задача сочетает две модели, лучше сделать два понятных этапа. Например, zip сначала восстанавливает двусторонний порядок скана, после чего sel извлекает раздел и разворачивает отдельные листы. Промежуточный результат увеличивает число файлов, но делает проверку проще и позволяет локализовать ошибку.

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

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

split по очереди создаёт writer для каждой страницы; sel и zip накапливают один writer результата; background дополнительно выполняет mergePage для слоёв. Это разные по стоимости операции, поэтому время нельзя оценивать только по числу страниц. -v не показывает проценты, но последовательные сообщения дают грубое представление о продвижении.

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

Имена файлов, пробелы и командная оболочка

Stapler получает аргументы уже после обработки их командной оболочкой. Если путь содержит пробелы, кавычки должны быть расставлены по правилам конкретной среды. Это относится и к записи A=путь: вся связь должна попасть в программу одним аргументом. Иначе отдельные части пути могут быть ошибочно восприняты как диапазоны или новые входы.

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

Выходному файлу лучше давать имя, отличающее его от источника: selected, trimmed, collated или overlaid. Даже при наличии -f запись поверх оригинала ухудшает проверяемость процесса. Новый файл можно открыть, сравнить с исходником и только после этого заменить рабочую версию отдельным контролируемым шагом.

Почему физическая нумерация важнее текста на странице

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

Перед массовой обработкой по номеру из редакционного задания полезно сопоставить несколько контрольных точек: начало раздела, середину и конец. Если PageLabels корректны, list-logical ускоряет перевод. Если их нет, потребуется просмотр. Это особенно важно для del, где ошибка физического номера приводит к удалению не той страницы.

После первого этапа физические номера могут измениться. Если сначала удалены несколько листов, второй этап должен рассчитывать диапазоны относительно нового PDF. Нельзя автоматически переносить номера исходника на промежуточный результат. При возможности объединяйте простые связанные действия в один sel, чтобы избежать повторного пересчёта.

Повторяемость как главное преимущество

В графической программе перестановка часто существует только как история ручных действий и итоговый файл. В Stapler сама команда является формальным описанием преобразования. Её можно хранить в сценарии, передавать коллегам, помещать под контроль версий и повторять для новой партии с теми же правилами. Это удобно для технических процессов, где важна воспроизводимость.

Повторяемость не отменяет контроль входных предпосылок. Если новый PDF получил дополнительную обложку или изменил число страниц, прежний диапазон может стать неверным. end помогает там, где правило действительно зависит от конца файла, но не умеет определить смысловую границу раздела. Хороший сценарий проверяет ожидаемые свойства входа до запуска.

Рядом с командой полезно хранить объяснение бизнес-правила: почему удаляется первый лист, почему второй поток идёт end-1, почему определённый диапазон разворачивается. Эти комментарии не относятся к синтаксису Stapler, зато делают автоматизацию сопровождаемой и уменьшают риск ошибочного изменения рабочей строки.

Финальная проверка перед использованием результата

Перед передачей результата дальше убедитесь, что текущий запуск завершился успешно, создан именно новый файл, число страниц соответствует плану, а все места смены источника или диапазона проверены. Для zip дополнительно контролируйте хвост более длинного потока, для background — границу слоя, для split — число созданных файлов и отсутствие конфликтов имён.

Если документ содержит формы, закладки, аннотации, ссылки или подписи, добавьте эти свойства в отдельный чек-лист. Страничная сборка Stapler не является гарантией сохранения всех документных структур. Для архивных и печатных процессов полезно запускать профильный валидатор, принятый в организации, уже после создания итогового PDF.

После изменения Python-среды разумно прогнать небольшой регрессионный набор: прямой и обратный диапазон, end, один поворот, del, split, zip, background, info, list-logical и ошибочный номер страницы. Такой тест быстрее обнаружит несовместимость зависимостей, чем случайная проблема в большой рабочей партии.

Итоговый критерий прост: команда должна быть понятна без догадок, фактически использованные страницы должны совпадать с планом, а созданный PDF — пройти проверку тех свойств, которые важны именно в вашем процессе.