Merge remote-tracking branch 'upstream/master'

Add mode ``sele``. It inserts an empty page at the end of each input
file if necessary to make sure each input file has an even number of
pages in the generated output file. This is good for people reading in
double-page layout or if they want to print the generated pdf file.

Author: cykerway

.gitignore

@@ -0,0 +1,7 @@
+*.py[co]
+pip-log.txt
+build
+dist
+*egg-info*
+/venv
+/.idea

CONTRIBUTORS

@@ -0,0 +1,5 @@
+Philip Stark <heller.barde at gmail dot com>
+Fred Wenzel <fwenzel at mozilla dot coms>
+Emanuele Santoro <manu at santoro dot tk>
+David Gay <oddshocks at gmail dot com>
+Carlchristian Eckert <Carli-Eckert at gmx dot de>

COPYING

@@ -1,4 +1,4 @@
-# Copyright (c) 2009, Philip Stark
+# Copyright (c) 2009, Philip Stark, Fred Wenzel
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without

LICENSE

@@ -0,0 +1,174 @@
+Stapler
+=======
+
+Stapler is a pure Python alternative to
+`PDFtk <http://www.pdfhacks.com/pdftk/>`__, a tool for manipulating PDF
+documents from the command line.
+
+History
+-------
+
+PDFtk was written in Java and C++, and is natively compiled with gcj.
+Sadly, it has been discontinued a few years ago and bitrot is setting in
+(e.g., it does not compile easily on a number of platforms).
+
+Philip Stark decided to look for an alternative and found pypdf, a PDF
+library written in pure Python. He couldn't find a tool which actually
+used the library, so he started writing his own.
+
+Version 0.3 of stapler was completely refactored by Fred Wenzel. He also
+added tests and awesome functionality.
+
+Like pdftk, stapler is a command-line tool. If you would like to add a
+GUI, compile it into a binary for your favorite platform, or contribute
+anything else, feel free to fork and send a pull request.
+
+Contributors and Authorship
+---------------------------
+
+Stapler version 0.2 was written in 2009 by Philip Stark. Stapler version
+0.3 was written in 2010 by Fred Wenzel.
+
+For a list of contributors, check the ``CONTRIBUTORS`` file.
+
+Change log (sorta)
+------------------
+
+- **0.3.3** include try-except blocks for supporting legacy pyPdf
+  if needed. Also fixes some PyPI issues like the missing License Trove
+  classifier and some dependencies.
+
+- **0.3.0** Refactoring by Fred Wenzel and now using PyPDF2
+
+- **0.2.0** Feature completeness using original pyPdf
+
+License
+-------
+
+Stapler is distributed under a BSD license. A copy of the BSD Style
+License used can be found in the file ``LICENSE``.
+
+Usage
+-----
+
+There are the following modes in Stapler:
+
+select/delete (called with ``sel`` and ``del``, respectively)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``sel`` is also available as ``cat`` for compatibility with my
+personal muscle memory. :)
+
+With select, you can cherry-pick pages from pdfs and concatenate them
+into a new pdf file.
+
+Syntax:
+
+::
+
+    stapler sel input1 page_or_range [page_or_range ...] [input2 p_o_r ...]
+
+Examples:
+
+::
+
+    # concatenate a and b into output.pdf
+    stapler sel a.pdf b.pdf output.pdf
+
+    # generate a pdf file called output.pdf with the following pages:
+    # 1, 4-8 in 180° (D for down), 20-40 from a.pdf, 1-5 from b.pdf in 
+    # this order
+    stapler sel a.pdf 1 4-8D 20-40 b.pdf 1-5 output.pdf
+
+    # reverse some of the pages in a.pdf by specifying a negative range
+    stapler sel a.pdf 1-3 9-6 10 output.pdf
+
+The ``sele`` command is an extension of ``sel``. The usage is the same as that
+of ``sel``, but ``sele`` inserts an empty page after each input file if that
+input file has an odd number of pages so that each input file starts with an
+even page number in the generated output. The empty page shall have the same
+size as the page previous to it. You may find this mode useful if you read in
+double-page layout or if you want to print the concatenated output.
+
+The delete command works almost exactly the same as select, but inverse.
+It uses the pages and ranges which you *didn't* specify.
+
+
+split/burst:
+~~~~~~~~~~~~
+
+Splits the specified pdf files into their single pages and writes each
+page into it's own pdf file with this naming scheme:
+
+::
+
+    ${origname}_${zero-padded page no}.pdf
+
+Syntax:
+
+::
+
+    stapler split input1 [input2 input3 ...]
+
+Example for a file foobar.pdf with 20 pages:
+
+::
+
+    $ stapler split foobar.pdf
+    $ ls
+    foobar_01.pdf foobar_02.pdf ... foobar_19.pdf foobar_20.pdf
+
+Multiple files can be specified, they will be processed as if you called
+single instances of stapler.
+
+zip:
+~~~~
+
+With zip, you can cherry-pick pages from pdfs (like select). The pages
+from each pdf are merged together in an interleaving manner. This can be
+used to collate a pdf with odd pages and a pdf with even pages into a
+single file.
+
+Syntax: stapler zip input1 [range[rotation]] [range ...] [input2
+[range...] ...] out
+
+Examples:
+
+::
+
+    # combine a pdf with odd pages and a pdf with even pages into output.pdf
+    stapler zip odd.pdf even.pdf output.pdf
+
+    # combine a.pdf b.pdf and c.pdf, but use only some pages of c.pdf and
+    #  rotate b.pdf right (90° clockwise) and rotate c.pdf left (90° counter-
+    # clockwise)
+    stapler zip a.pdf b.pdf 1-endR c.pdf 1-3L output.pdf
+
+If one of the ranges is shorter than the others, stapler will continue
+to merge the remaining pages.
+
+info:
+~~~~~
+
+Shows information on the metadata stored inside a PDF file.
+
+Syntax:
+
+::
+
+    stapler info foo.pdf
+
+Example output:
+
+::
+
+    \*\*\* Metadata for foo.pdf
+
+    /ModDate:  D:20100313082451+01'00'
+    /CreationDate:  D:20100313082451+01'00'
+    /Producer:  GPL Ghostscript 8.70
+    /Title:  foo.pdf
+    /Creator:  PDFCreator Version 0.9.9
+    /Keywords:
+    /Author:  John Doe
+    /Subject:

README

@@ -0,0 +1,23 @@
+Comparison with pdftk features:
+[x] = done, [?] = maybe, [ ] = to do
+
+[ ] Python 3 Support (pypdf can do it, I think)
+[x] Merge PDF Documents
+[x] Split PDF Pages into a New Document
+[x] Rotate PDF Pages or Documents
+[x] Decrypt Input as Necessary (Password Required)
+[x] Encrypt Output as Desired
+[?] Fill PDF Forms with FDF Data or XFDF Data and/or Flatten Forms
+[?] Apply a Background Watermark or a Foreground Stamp
+[ ] Report on PDF Metrics such as Metadata, Bookmarks, and Page Labels
+[?] Update PDF Metadata
+[?] Attach Files to PDF Pages or the PDF Document
+[?] Unpack PDF Attachments
+[x] Burst a PDF Document into Single Pages
+[ ] Uncompress and Re-Compress Page Streams
+[x] Repair Corrupted PDF (Where Possible)
+
+Known issues:
+- The same page of the same input file cannot be added to the output twice
+  with two different rotations (e.g., ``cat foo.pdf 1R 1D`` won't do what
+  you'd hope).

README.rst

@@ -0,0 +1,35 @@
+from setuptools import setup, find_packages
+
+version = "0.3.3"
+
+setup(name="stapler",
+    version=version,
+    description="Manipulate PDF documents from the command line",
+    keywords="pdf utility cli concatenate tool",
+    
+    author="Philip Stark, Fred Wenzel",
+    author_email="git@codechaos.ch",
+    url="https://github.com/hellerbarde/stapler",
+
+    install_requires = [
+        "PyPDF>=1.12",
+        #"PyPDF2>=1.24",
+    ],
+
+    #include_package_data=True,
+    packages=find_packages(),
+    package_data={"": ["LICENSE", "CONTRIBUTORS", "README.md", ]},
+    entry_points="""
+    [console_scripts]
+    stapler = staplelib:main
+    pdf-stapler = staplelib:main
+    """,
+
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Programming Language :: Python :: 2",
+        "Intended Audience :: Science/Research",
+        "Topic :: Utilities",
+        "License :: OSI Approved :: BSD License"
+    ],
+)

TODO

@@ -0,0 +1,4 @@
+--index-url https://pypi.python.org/simple/
+
+-e .
+

legacy-pypdf-setup.py

@@ -0,0 +1,35 @@
+from setuptools import setup, find_packages
+
+version = "0.3.3"
+
+setup(name="stapler",
+    version=version,
+    description="Manipulate PDF documents from the command line",
+    keywords="pdf utility cli concatenate tool",
+    
+    author="Philip Stark, Fred Wenzel",
+    author_email="git@codechaos.ch",
+    url="https://github.com/hellerbarde/stapler",
+
+    install_requires = [
+        "PyPDF2>=1.24",
+        "more-itertools>=2.2"
+    ],
+
+    #include_package_data=True,
+    packages=find_packages(),
+    package_data={"": ["LICENSE", "CONTRIBUTORS", "README.md", ]},
+    entry_points="""
+    [console_scripts]
+    stapler = staplelib:main
+    pdf-stapler = staplelib:main
+    """,
+
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Programming Language :: Python :: 2",
+        "Intended Audience :: Science/Research",
+        "Topic :: Utilities",
+        "License :: OSI Approved :: BSD License"
+    ],
+)