mstamy2/PyPDF2 — pull request #56 by switham (2014-01-09 22:02:19+00:00)
Title: pdfcat and pagerange.py

### The main new files

**Sample_Code/pdfcat**
```
pdfcat foo.pdf 0:3 bar.pdf >output.pdf or pdfcat -o output.pdf foo.pdf 0:3 bar.pdf
```

Is a Unix-style command-line utility that combines (pages from) pdf files into one pdf file. It uses **PdfFileMerger** to do the combining. pdfcat has a pretty thorough --help (that borrows the page-range syntax help from the pagerange module (next)). If output is via stdout, I reopen in binary mode, but I haven't tested that feature in Windows.

**PyPDF2/pagerange.py** is a new module that includes the **PageRange** class to handle the parsing of page range expressions that are like what you would see inside a Python slice (including starting at index 0). A single int means a range of one page. It handles all the minus signs, colons, combinations of missing numbers, and step sizes. The **parse_filename_page_ranges()** function takes a list of filenames and optional multiple page range expressions, like the arguments to pdfcat, e.g.
```
["no_range.pdf", "foo.pdf", "1", "2", "12", "32:", "bar.pdf", ":4", "-1", "last_file.pdf"]
```
and handles the fact that all page ranges go with the filename before them, and when a filename has no page range it means the whole file.

### Modifications to existing files

**LICENSE**: I put a "some stuff by Steve Witham" line in. I have read that it's good for a project to have a file of all of the relevant copyrights, it looked like it was already started in LICENSE.

**PyPDF2/\__init__.py**: Included two things from pagerange.

**PyPDF2/merger.py**: Made the PdfFileMerger .append() and .merge() methods accept a PageRange object for the "pages" parameter. If given, it converts to a tuple. Also changed the docstrings and error messages to reflect that the third, optional step parameter works if "pages" is a tuple--partly to remind developers to keep that feature working (it already did). I have not tested, e.g., reversing the pages of a file with table-of-contents links.

### Less important new files

**Sample_Code/makesimple.py** and **Sample_Code/makesimple.sh**: These both produce three multiple-page pdf files with the same three names, but by different methods. The file pages say, e.g., "simple2.pdf page 3 of 11." I was using them to generate test files, so I thought people might like to have them. (Note: github's display of makesimple.sh doesn't show the ^L (formfeed--new page) character in one of the echo statements.)