Add support for parsing password-protected PDFs

Thanks to @nikhilbhawsinka for raising the question in
jsvine#101

Test PDF via https://www.novapdf.com/pdf-example-files-created-with-novapdf-kb.html

README.md

@@ -65,6 +65,8 @@ with pdfplumber.open("path/to/file.pdf") as pdf:
 
 Both methods return an instance of the `pdfplumber.PDF` class.
 
+To load a password-protected PDF, pass the `password` keyword argument, e.g., `pdfplumber.open("file.pdf", password = "test")`.
+
 ### The `pdfplumber.PDF` class
 
 The top-level `pdfplumber.PDF` class represents a single PDF and has two main properties:

pdfplumber/pdf.py

@@ -13,13 +13,19 @@
 class PDF(Container):
     cached_properties = Container.cached_properties + [ "_pages" ]
 
-    def __init__(self, stream, pages=None, laparams=None, precision=0.001):
+    def __init__(self,
+        stream,
+        pages = None,
+        laparams = None,
+        precision = 0.001,
+        password = b""
+    ):
         self.laparams = None if laparams == None else LAParams(**laparams)
         self.stream = stream
         self.pages_to_parse = pages
         self.precision = precision
         rsrcmgr = PDFResourceManager()
-        self.doc = PDFDocument(PDFParser(stream))
+        self.doc = PDFDocument(PDFParser(stream), password = password)
         self.metadata = {}
         for info in self.doc.info:
             self.metadata.update(info)

tests/test-basics.py

@@ -50,3 +50,9 @@ def test_rotation(self):
 
         assert(rotated.pages[0].cropbox == self.pdf.pages[0].cropbox)
         assert(rotated.pages[0].bbox != self.pdf.pages[0].bbox)
+
+    def test_password(self):
+        path = os.path.join(HERE, "pdfs/password-example.pdf")
+        pdf = pdfplumber.open(path, password = "test")
+        assert(len(pdf.chars) > 0)
+        pdf.close()