Shift to making pdfplumber.open the sole loader

- .from_path is now removed
- .load is marked as deprecated, to be removed in 0.6.0

README.md

@@ -59,12 +59,13 @@ with pdfplumber.open("path/to/file.pdf") as pdf:
 
 ### Loading a PDF
 
-`pdfplumber` provides two main ways to load a PDF:
+To start working with a PDF, call `pdfplumber.open(x)`, where `x` can be a:
 
-- `pdfplumber.open("path/to/file.pdf")`
-- `pdfplumber.load(file_like_object)`
+- path to your PDF file
+- file object, loaded as bytes
+- file-like object, loaded as bytes
 
-Both methods return an instance of the `pdfplumber.PDF` class.
+The `open` method returns 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")`.
 

pdfplumber/__init__.py

@@ -1,18 +1,26 @@
+__all__ = [
+    "__version__",
+    "utils",
+    "pdfminer",
+    "open",
+    "set_debug",
+]
+
+from ._version import __version__
 from .pdf import PDF
 from . import utils
 import pdfminer
 import pdfminer.pdftypes
-from ._version import __version__
+import sys
 
 pdfminer.pdftypes.STRICT = False
 pdfminer.pdfinterp.STRICT = False
 
-def load(file_or_buffer, **kwargs):
-    return PDF(file_or_buffer, **kwargs)
-
 open = PDF.open
-# Old idiom
-from_path = PDF.open 
+
+def load(file_or_buffer, **kwargs):
+    sys.stderr.write("Warning: pdfplumber.load is deprecated. Please use pdfplumber.open (with same arguments) instead.\n")
+    return PDF(file_or_buffer, **kwargs)
 
 def set_debug(debug=0):
     pdfminer.debug = debug

pdfplumber/cli.py

@@ -93,7 +93,7 @@ def to_json(pdf, types, encoding):
 
 def main():
     args = parse_args()
-    pdf = pdfplumber.load(args.infile, pages=args.pages)
+    pdf = pdfplumber.open(args.infile, pages=args.pages)
     if args.format == "csv":
         to_csv(pdf, args.types, args.encoding)
     else:

pdfplumber/pdf.py

@@ -2,6 +2,7 @@ from .container import Container
 from .page import Page
 from .utils import decode_text
 
+import pathlib
 from pdfminer.pdfparser import PDFParser
 from pdfminer.pdfdocument import PDFDocument
 from pdfminer.pdfpage import PDFPage
@@ -44,8 +45,11 @@ class PDF(Container):
         self.interpreter = PDFPageInterpreter(rsrcmgr, self.device)
 
     @classmethod
-    def open(cls, path, **kwargs):
-        return cls(open(path, "rb"), **kwargs)
+    def open(cls, path_or_fp, **kwargs):
+        if isinstance(path_or_fp, (str, pathlib.Path)):
+            return cls(open(path_or_fp, "rb"), **kwargs)
+        else:
+            return cls(path_or_fp, **kwargs)
 
     def process_page(self, page):
         self.interpreter.process_page(page)

tests/test_basics.py

@@ -12,9 +12,14 @@ HERE = os.path.abspath(os.path.dirname(__file__))
 
 class Test(unittest.TestCase):
 
-    def setUp(self):
+    @classmethod
+    def setup_class(self):
         path = os.path.join(HERE, "pdfs/nics-background-checks-2015-11.pdf")
-        self.pdf = pdfplumber.from_path(path)
+        self.pdf = pdfplumber.open(path)
+
+    @classmethod
+    def teardown_class(self):
+        self.pdf.close()
 
     def test_metadata(self):
         metadata = self.pdf.metadata
@@ -39,17 +44,15 @@ class Test(unittest.TestCase):
         assert(len(step_2.rects) == 0)
 
     def test_rotation(self):
-        rotated = pdfplumber.from_path(
-            os.path.join(HERE, "pdfs/nics-background-checks-2015-11-rotated.pdf")
-        )
         assert(self.pdf.pages[0].width == 1008)
         assert(self.pdf.pages[0].height == 612)
+        path = os.path.join(HERE, "pdfs/nics-background-checks-2015-11-rotated.pdf")
+        with pdfplumber.open(path) as rotated:
+            assert(rotated.pages[0].width == 612)
+            assert(rotated.pages[0].height == 1008)
 
-        assert(rotated.pages[0].width == 612)
-        assert(rotated.pages[0].height == 1008)
-
-        assert(rotated.pages[0].cropbox == self.pdf.pages[0].cropbox)
-        assert(rotated.pages[0].bbox != self.pdf.pages[0].bbox)
+            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")

tests/test_ca_warn_report.py

@@ -16,11 +16,16 @@ def fix_row_spaces(row):
 
 class Test(unittest.TestCase):
 
-    def setUp(self):
+    @classmethod
+    def setup_class(self):
         path = os.path.join(HERE, "pdfs/WARN-Report-for-7-1-2015-to-03-25-2016.pdf")
-        self.pdf = pdfplumber.from_path(path)
+        self.pdf = pdfplumber.open(path)
         self.PDF_WIDTH = self.pdf.pages[0].width
 
+    @classmethod
+    def teardown_class(self):
+        self.pdf.close()
+
     def test_pandas(self):
 
         rect_x0_clusters = utils.cluster_list([ r["x0"]

tests/test_display.py

@@ -11,11 +11,16 @@ HERE = os.path.abspath(os.path.dirname(__file__))
 
 class Test(unittest.TestCase):
 
-    def setUp(self):
+    @classmethod
+    def setup_class(self):
         path = os.path.join(HERE, "pdfs/nics-background-checks-2015-11.pdf")
         self.pdf = pdfplumber.open(path)
         self.im = self.pdf.pages[0].to_image()
 
+    @classmethod
+    def teardown_class(self):
+        self.pdf.close()
+
     def test_basic_conversion(self):
         self.im.reset()
         self.im.draw_rect(self.im.page.rects[0])

tests/test_issues.py

@@ -16,7 +16,7 @@ class Test(unittest.TestCase):
         """
         Test slightly simplified from gist here: https://github.com/jsvine/pdfplumber/issues/13
         """
-        pdf = pdfplumber.from_path(
+        pdf = pdfplumber.open(
             os.path.join(HERE, "pdfs/issue-13-151201DSP-Fond-581-90D.pdf")
         )
 
@@ -72,36 +72,42 @@ class Test(unittest.TestCase):
             for rect in rects ])
 
         assert(n_checked == 5)
+        pdf.close()
 
     def test_issue_14(self):
-        pdf = pdfplumber.from_path(
+        pdf = pdfplumber.open(
             os.path.join(HERE, "pdfs/cupertino_usd_4-6-16.pdf")
         )
         assert len(pdf.objects)
+        pdf.close()
 
     def test_issue_21(self):
-        pdf = pdfplumber.from_path(
+        pdf = pdfplumber.open(
             os.path.join(HERE, "pdfs/150109DSP-Milw-505-90D.pdf")
         )
         assert len(pdf.objects)
+        pdf.close()
 
     def test_issue_33(self):
-        pdf = pdfplumber.from_path(
+        pdf = pdfplumber.open(
             os.path.join(HERE, "pdfs/issue-33-lorem-ipsum.pdf")
         )
         assert len(pdf.metadata.keys())
+        pdf.close()
         
     def test_issue_53(self):
-        pdf = pdfplumber.from_path(
+        pdf = pdfplumber.open(
             os.path.join(HERE, "pdfs/issue-53-example.pdf")
         )
         assert len(pdf.objects)
+        pdf.close()
 
     def test_issue_67(self):
-        pdf = pdfplumber.from_path(
+        pdf = pdfplumber.open(
             os.path.join(HERE, "pdfs/issue-67-example.pdf")
         )
         assert len(pdf.metadata.keys())
+        pdf.close()
 
     def test_pr_77(self):
         # via https://github.com/jsvine/pdfplumber/pull/77

tests/test_la_precinct_bulletin.py

@@ -100,12 +100,16 @@ class PrecinctPage(object):
         }
 
 class Test(unittest.TestCase):
-
-    def setUp(self):
+    @classmethod
+    def setup_class(self):
         path = os.path.join(HERE, "pdfs/la-precinct-bulletin-2014-p1.pdf")
-        self.pdf = pdfplumber.from_path(path)
+        self.pdf = pdfplumber.open(path)
         self.PDF_WIDTH = self.pdf.pages[0].width
 
+    @classmethod
+    def teardown_class(self):
+        self.pdf.close()
+
     def test_pandas(self):
         p1 = PrecinctPage(self.pdf.pages[0]).to_dict()
         assert(p1["registered_voters"] == 1100)

tests/test_list_metadata.py

@@ -12,4 +12,5 @@ class Test(unittest.TestCase):
 
     def test_load(self):
         path = os.path.join(HERE, "pdfs/cupertino_usd_4-6-16.pdf")
-        pdf = pdfplumber.from_path(path)
+        with pdfplumber.open(path) as pdf:
+            assert len(pdf.metadata)

tests/test_nics_report.py

@@ -40,12 +40,16 @@ COLUMNS = [
 ]
 
 class Test(unittest.TestCase):
-
-    def setUp(self):
+    @classmethod
+    def setup_class(self):
         path = os.path.join(HERE, "pdfs/nics-background-checks-2015-11.pdf")
-        self.pdf = pdfplumber.from_path(path)
+        self.pdf = pdfplumber.open(path)
         self.PDF_WIDTH = self.pdf.pages[0].width
 
+    @classmethod
+    def teardown_class(self):
+        self.pdf.close()
+
     def test_plain(self):
         page = self.pdf.pages[0]
         cropped = page.crop((0, 80, self.PDF_WIDTH, 485))