[MRG + 1] Add basic support for encrypted PDF files (#180)

* [MRG] Add basic support for encrypted PDF files

Update API and CLI to accept ASCII passwords to decrypt PDFs
encrypted by algorithm code 1 or 2 (limited by support from PyPDF2).
Update documentation and unit tests accordingly.

Example document health_protected.pdf generated as follows:
qpdf --encrypt userpass ownerpass 128 -- health.pdf health_protected.pdf

Issue #162

* Support encrypted PDF files in python3

Issue #162

* Address review comments

Explicitly check passwords for None rather than falsey.
Correct read_pdf documentation for Owner/User password.

Issue #162

* Correct API documentation changes for consistency

Issue #162

* Move error tests from test_common to test_errors

Issue #162

* Add qpdf example

* Remove password is not None check

* Fix merge conflict

* Fix pages example

docs/user/cli.rst

@@ -9,26 +9,28 @@ You can print the help for the interface by typing ``camelot --help`` in your fa
 
 ::
 
-  Usage: camelot [OPTIONS] COMMAND [ARGS]...
+Usage: camelot [OPTIONS] COMMAND [ARGS]...
 
   Camelot: PDF Table Extraction for Humans
 
-  Options:
-    --version                       Show the version and exit.
-    -p, --pages TEXT                Comma-separated page numbers. Example: 1,3,4
-                                    or 1,4-end.
-    -o, --output TEXT               Output file path.
-    -f, --format [csv|json|excel|html]
-                                    Output file format.
-    -z, --zip                       Create ZIP archive.
-    -split, --split_text            Split text that spans across multiple cells.
-    -flag, --flag_size              Flag text based on font size. Useful to
-                                    detect super/subscripts.
-    -M, --margins <FLOAT FLOAT FLOAT>...
-                                    PDFMiner char_margin, line_margin and
-                                    word_margin.
-    --help                          Show this message and exit.
+Options:
+  --version                       Show the version and exit.
+  -p, --pages TEXT                Comma-separated page numbers. Example: 1,3,4
+                                  or 1,4-end.
+  -pw, --password TEXT            Password for decryption.
+  -o, --output TEXT               Output file path.
+  -f, --format [csv|json|excel|html]
+                                  Output file format.
+  -z, --zip                       Create ZIP archive.
+  -split, --split_text            Split text that spans across multiple cells.
+  -flag, --flag_size              Flag text based on font size. Useful to
+                                  detect super/subscripts.
+  -M, --margins <FLOAT FLOAT FLOAT>...
+                                  PDFMiner char_margin, line_margin and
+                                  word_margin.
+  -q, --quiet                     Suppress warnings.
+  --help                          Show this message and exit.
 
-  Commands:
-    lattice  Use lines between text to parse the table.
-    stream   Use spaces between text to parse the table.
+Commands:
+  lattice  Use lines between text to parse the table.
+  stream   Use spaces between text to parse the table.

docs/user/quickstart.rst

@@ -87,6 +87,28 @@ By default, Camelot only uses the first page of the PDF to extract tables. To sp
 
 The ``pages`` keyword argument accepts pages as comma-separated string of page numbers. You can also specify page ranges — for example, ``pages=1,4-10,20-30`` or ``pages=1,4-10,20-end``.
 
-------------------------
+Reading encrypted PDFs
+----------------------
 
-Ready for more? Check out the :ref:`advanced <advanced>` section.
+To extract tables from encrypted PDF files you must provide a password when calling :meth:`read_pdf() <camelot.read_pdf>`.
+
+::
+
+    >>> tables = camelot.read_pdf('foo.pdf', password='userpass')
+    >>> tables
+    <TableList n=1>
+
+Currently Camelot only supports PDFs encrypted with ASCII passwords and algorithm `code 1 or 2`_. An exception is thrown if the PDF cannot be read. This may be due to no password being provided, an incorrect password, or an unsupported encryption algorithm.
+
+Further encryption support may be added in future, however in the meantime if your PDF files are using unsupported encryption algorithms you are advised to remove encryption before calling :meth:`read_pdf() <camelot.read_pdf>`. This can been successfully achieved with third-party tools such as `QPDF`_.
+
+::
+
+    $ qpdf --password=<PASSWORD> --decrypt input.pdf output.pdf
+
+.. _code 1 or 2: https://github.com/mstamy2/PyPDF2/issues/378
+.. _QPDF: https://www.github.com/qpdf/qpdf
+
+----
+
+Ready for more? Check out the :ref:`advanced <advanced>` section.