Plumb a PDF for detailed information about each text character, rectangle, and line. Plus: Easily extract data from tables trapped in PDFs.
Works best on machine-generated, rather than scanned, PDFs. Built on [`pdfminer`](https://github.com/euske/pdfminer) and [`pdfminer.six`](https://github.com/goulu/pdfminer).
-`--pages [list of pages]`: A space-delimited, `1`-indexed list of pages or hyphenated page ranges. E.g., `1, 11-15`, which would return data for pages 1, 11, 12, 13, 14, and 15.
The top-level `pdfplumber.PDF` class represents a single PDF and has two main properties:
-`.metadata`: A dictionary of metadata key/value pairs, drawn from the PDF's `Info` trailers. Typically includes "CreationDate," "ModDate," "Producer," et cetera.
-`.pages`: A list containing one `pdfplumber.Page` instance per page loaded.
### The `pdfplumber.Page` class
The `pdfplumber.Page` class is at the core of `pdfplumber`. Most things you'll do with `pdfplumber` will revolve around this class. It has these main methods and properties:
-`.objects` / `.chars` / `.lines` / `.rects`: Each of these properties is a list, and each list contains one dictionary for each such object embedded on the page. For more detail, see "[Objects](#objects)" below.
-`.crop(bounding_box, strict=False)`: Returns a version of the page cropped to the bounding box, which should be expressed as 4-tuple with the values `(x0, top, x1, bottom)`.
- By default, the cropped page retains objects that fall at least partly within the bounding box. If an object falls only partly within the box, its dimensions are sliced to fit the bounding box.
- Calling `.crop` with `strict=True`, however, retains only objects that fall *entirely* within the bounding box.
-`.extract_text(x_tolerance=0, y_tolerance=0)`: Collates all of the page's character objects into a single string. Adds spaces where the difference between the `x1` of one character and the `x0` of the next is greater than `x_tolerance`. Adds newline characters where the difference between the `doctop` of one character and the `doctop` of the next is greater than `y_tolerance`.
-`.extract_words(x_tolerance=0, y_tolerance=0)`: Returns a list of all word-looking things and their bounding boxes. Words are considered to be sequences of characters where the difference between the `x1` of one character and the `x0` of the next is less than or equal to `x_tolerance`*and* where the `doctop` of one character and the `doctop` of the next is less than or equal to `y_tolerance`.
Each instance of `pdfplumber.PDF` and `pdfplumber.Page` provides access to four types of PDF objects. The following properties each return a Python list of the matching objects:
Additionally, both `pdfplumber.PDF` and `pdfplumber.Page` provide access to two derived lists of objects: `.rect_edges` (which decomposes each rectangle into its four lines) and `.edges` (which combines `.rect_edges` with `.lines`).
## Extracting Tables
You can think of `Page.extract_table(...)` as a sort of scriptable [Tablula](http://tabula.technology/). Given a page or cropped page, this method will return a list of lists representing the extracted table. By default, `extract_table` uses the page's vertical and horizontal lines (or rectangle edges) as cell-separators. But the method is highly customizable via these keyword arguments:
-`v=[strategy_name]`: Strategy for locating vertical dividers. Defaults to "lines," which uses lines and rectangle edges. Other options: "lines_strict," which only uses lines (and not rectangle edges), and "gutters," which looks for vertical sections of the document with no text in them.
-`h=[strategy_name]`: Strategy for locating horizontal dividers. Same defaults/options as `v`.
-`line_min_height=[number]`: The minimum height a line must be before being used in the vertical "lines" strategy. Defaults to `1`.
-`line_min_width=[number]`: The minimum width a line must be before being used in the horizontal "lines" strategy. Defaults to `1`.
-`gutter_min_width=[number]`: Minimum size of a character "gutter" to be used in the horizontal "gutters" strategy. Defaults to `5`.
-`x_tolerance=[number]`: The maximum horizontal distance between two consecutive characters to consider them part of the same word. (Otherwise, a space is inserted between them.) Defaults to `5`.
-`x_tolerance=[number]`: The maximum vertical distance between two consecutive characters to consider them part of the same line. (Otherwise, a newline is inserted between them.) Defaults to `5`.
Support for Python 3 is decent, but rough around the edges and largely dependent on the progress of [`pdfminer.six`](https://github.com/goulu/pdfminer).
Currently [tested](tests/) on [Python 2.7, 3.1, 3.3, 3.4, and 3.5](tox.ini).
