Bump version

[MRG] Add line_overlap and boxes_flow to LAParams

.deepsource.toml

@@ -1,12 +0,0 @@
-version = 1
-
-exclude_patterns = [
-  "camelot/ext/**"
-]
-
-[[analyzers]]
-name = "python"
-enabled = true
-
-[analyzers.meta]
-runtime_version = "3.x.x"

.editorconfig

@@ -1,10 +0,0 @@
-root = true
-
-[*]
-end_of_line = lf
-insert_final_newline = true
-
-[*.py]
-charset = utf-8
-indent_style = space
-indent_size = 4

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,48 @@
+---
+name: Bug report
+about: Please follow this template to submit bug reports.
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+<!-- Please read the filing issues section of the contributor's guide first: https://camelot-py.readthedocs.io/en/master/dev/contributing.html -->
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Steps to reproduce the bug**
+Steps used to install `camelot`:
+1. Add step here (you can add more steps too)
+
+Steps to reproduce the behavior:
+1. Add step here (you can add more steps too)
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Code**
+Add the Camelot code snippet that you used.
+```
+import camelot
+
+# add your code here
+```
+
+**PDF**
+Add the PDF file that you want to extract tables from.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment**
+ - OS: [e.g. MacOS]
+ - Python version:
+ - Numpy version:
+ - OpenCV version:
+ - Ghostscript version:
+ - Camelot version:
+
+**Additional context**
+Add any other context about the problem here.

.github/workflows/tests.yml

@@ -0,0 +1,23 @@
+name: tests
+
+on: [pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.6, 3.7, 3.8, 3.9]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install camelot with dependencies
+        run: |
+          make install
+      - name: Test with pytest
+        run: |
+          make test

.readthedocs.yml

@@ -21,4 +21,7 @@ formats:
 python:
   version: 3.8
   install:
-    - requirements: requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev

.travis.yml

@@ -1,29 +0,0 @@
-sudo: true
-language: python
-cache: pip
-addons:
-  apt:
-    update: true
-install:
-  - make install
-jobs:
-  include:
-    - stage: test
-      script:
-        - make test
-      python: '3.6'
-    - stage: test
-      script:
-        - make test
-      python: '3.7'
-      dist: xenial
-    - stage: test
-      script:
-        - make test
-      python: '3.8'
-      dist: xenial
-    - stage: coverage
-      python: '3.8'
-      script:
-        - make test
-        - codecov --verbose

HISTORY.md

@@ -4,6 +4,31 @@ Release History
 master
 ------
 
+0.9.0 (2021-06-15)
+------------------
+
+**Bugfixes**
+
+- Fix use of resolution argument to generate image with ghostscript. [#231](https://github.com/camelot-dev/camelot/pull/231) by [Tiago Samaha Cordeiro](https://github.com/tiagosamaha).
+- [#15](https://github.com/camelot-dev/camelot/issues/15) Fix duplicate strings being assigned to the same cell. [#206](https://github.com/camelot-dev/camelot/pull/206) by [Eduardo Gonzalez Lopez de Murillas](https://github.com/edugonza).
+- Save plot when filename is specified. [#121](https://github.com/camelot-dev/camelot/pull/121) by [Jens Diemer](https://github.com/jedie).
+- Close file streams explicitly. [#202](https://github.com/camelot-dev/camelot/pull/202) by [Martin Abente Lahaye](https://github.com/tchx84).
+- Use correct re.sub signature. [#186](https://github.com/camelot-dev/camelot/pull/186) by [pevisscher](https://github.com/pevisscher).
+- [#183](https://github.com/camelot-dev/camelot/issues/183) Fix UnicodeEncodeError when using Stream flavor by adding encoding kwarg to `to_html`. [#188](https://github.com/camelot-dev/camelot/pull/188) by [Stefano Fiorucci](https://github.com/anakin87).
+- [#179](https://github.com/camelot-dev/camelot/issues/179) Fix `max() arg is an empty sequence` error on PDFs with blank pages. [#189](https://github.com/camelot-dev/camelot/pull/189) by Vinayak Mehta.
+
+**Improvements**
+
+- Add `line_overlap` and `boxes_flow` to `LAParams`. [#219](https://github.com/camelot-dev/camelot/pull/219) by [Arnie97](https://github.com/Arnie97).
+- [Add bug report template.](https://github.com/camelot-dev/camelot/commit/0a3944e54d133b701edfe9c7546ff11289301ba8)
+- Move from [Travis to GitHub Actions](https://github.com/camelot-dev/camelot/pull/241).
+- Update `.readthedocs.yml` and [remove requirements.txt](https://github.com/camelot-dev/camelot/commit/7ab5db39d07baa4063f975e9e00f6073340e04c1#diff-cde814ef2f549dc093f5b8fc533b7e8f47e7b32a8081e0760e57d5c25a1139d9)
+
+**Documentation**
+
+- [#193](https://github.com/camelot-dev/camelot/issues/193) Add better checks to confirm proper installation of ghostscript. [#196](https://github.com/camelot-dev/camelot/pull/196) by [jimhall](https://github.com/jimhall).
+- Update `advanced.rst` plotting examples. [#119](https://github.com/camelot-dev/camelot/pull/119) by [Jens Diemer](https://github.com/jedie).
+
 0.8.2 (2020-07-27)
 ------------------
 

LICENSE

@@ -1,12 +1,7 @@
 MIT License
 
-Modifications:
-
-Copyright (c) 2019 Camelot Developers
-
-Original project:
-
-Copyright (c) 2018 Peeply Private Ltd (Singapore)
+Copyright (c) 2019-2021 Camelot Developers
+Copyright (c) 2018-2019 Peeply Private Ltd (Singapore)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -4,19 +4,18 @@
 
 # Camelot: PDF Table Extraction for Humans
 
-[![Build Status](https://travis-ci.org/camelot-dev/camelot.svg?branch=master)](https://travis-ci.org/camelot-dev/camelot) [![Documentation Status](https://readthedocs.org/projects/camelot-py/badge/?version=master)](https://camelot-py.readthedocs.io/en/master/)
+![Build Status](https://github.com/camelot-dev/camelot/actions/workflows/tests.yml/badge.svg) [![Documentation Status](https://readthedocs.org/projects/camelot-py/badge/?version=master)](https://camelot-py.readthedocs.io/en/master/)
  [![codecov.io](https://codecov.io/github/camelot-dev/camelot/badge.svg?branch=master&service=github)](https://codecov.io/github/camelot-dev/camelot?branch=master)
  [![image](https://img.shields.io/pypi/v/camelot-py.svg)](https://pypi.org/project/camelot-py/) [![image](https://img.shields.io/pypi/l/camelot-py.svg)](https://pypi.org/project/camelot-py/) [![image](https://img.shields.io/pypi/pyversions/camelot-py.svg)](https://pypi.org/project/camelot-py/) [![Gitter chat](https://badges.gitter.im/camelot-dev/Lobby.png)](https://gitter.im/camelot-dev/Lobby)
-[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) [![image](https://img.shields.io/badge/continous%20quality-deepsource-lightgrey)](https://deepsource.io/gh/camelot-dev/camelot/?ref=repository-badge)
+[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
+**Camelot** is a Python library that can help you extract tables from PDFs!
 
-**Camelot** is a Python library that makes it easy for *anyone* to extract tables from PDF files!
-
-**Note:** You can also check out [Excalibur](https://github.com/camelot-dev/excalibur), which is a web interface for Camelot!
+**Note:** You can also check out [Excalibur](https://github.com/camelot-dev/excalibur), the web interface to Camelot!
 
 ---
 
-**Here's how you can extract tables from PDF files.** Check out the PDF used in this example [here](https://github.com/camelot-dev/camelot/blob/master/docs/_static/pdf/foo.pdf).
+**Here's how you can extract tables from PDFs.** You can check out the PDF used in this example [here](https://github.com/camelot-dev/camelot/blob/master/docs/_static/pdf/foo.pdf).
 
 <pre>
 >>> import camelot
@@ -46,24 +45,27 @@
 | 2032_2     | 0.17      | 57.8          | 21.7%                | 0.3%            | 2.7%            | 1.2%           |
 | 4171_1     | 0.07      | 173.9         | 58.1%                | 1.6%            | 2.1%            | 0.5%           |
 
-There's a [command-line interface](https://camelot-py.readthedocs.io/en/master/user/cli.html) too!
+Camelot also comes packaged with a [command-line interface](https://camelot-py.readthedocs.io/en/master/user/cli.html)!
 
 **Note:** Camelot only works with text-based PDFs and not scanned documents. (As Tabula [explains](https://github.com/tabulapdf/tabula#why-tabula), "If you can click and drag to select text in your table in a PDF viewer, then your PDF is text-based".)
 
 ## Why Camelot?
 
-- **You are in control.**: Unlike other libraries and tools which either give a nice output or fail miserably (with no in-between), Camelot gives you the power to tweak table extraction. (This is important since everything in the real world, including PDF table extraction, is fuzzy.)
-- *Bad* tables can be discarded based on **metrics** like accuracy and whitespace, without ever having to manually look at each table.
-- Each table is a **pandas DataFrame**, which seamlessly integrates into [ETL and data analysis workflows](https://gist.github.com/vinayak-mehta/e5949f7c2410a0e12f25d3682dc9e873).
-- **Export** to multiple formats, including JSON, Excel, HTML and Sqlite.
+- **Configurability**: Camelot gives you control over the table extraction process with its [tweakable settings](https://camelot-py.readthedocs.io/en/master/user/advanced.html).
+- **Metrics**: Bad tables can be discarded based on metrics like accuracy and whitespace, without having to manually look at each table.
+- **Output**: Each table is extracted into a **pandas DataFrame**, which seamlessly integrates into [ETL and data analysis workflows](https://gist.github.com/vinayak-mehta/e5949f7c2410a0e12f25d3682dc9e873). You can also export tables to multiple formats, which include CSV, JSON, Excel, HTML and Sqlite.
 
-See [comparison with other PDF table extraction libraries and tools](https://github.com/camelot-dev/camelot/wiki/Comparison-with-other-PDF-Table-Extraction-libraries-and-tools).
+See [comparison with similar libraries and tools](https://github.com/camelot-dev/camelot/wiki/Comparison-with-other-PDF-Table-Extraction-libraries-and-tools).
+
+## Support the development
+
+If Camelot has helped you, please consider supporting its development with a one-time or monthly donation [on OpenCollective](https://opencollective.com/camelot).
 
 ## Installation
 
 ### Using conda
 
-The easiest way to install Camelot is to install it with [conda](https://conda.io/docs/), which is a package manager and  environment management system for the [Anaconda](http://docs.continuum.io/anaconda/) distribution.
+The easiest way to install Camelot is with [conda](https://conda.io/docs/), which is a package manager and environment management system for the [Anaconda](http://docs.continuum.io/anaconda/) distribution.
 
 <pre>
 $ conda install -c conda-forge camelot-py
@@ -71,7 +73,7 @@ $ conda install -c conda-forge camelot-py
 
 ### Using pip
 
-After [installing the dependencies](https://camelot-py.readthedocs.io/en/master/user/install-deps.html) ([tk](https://packages.ubuntu.com/bionic/python/python-tk) and [ghostscript](https://www.ghostscript.com/)), you can simply use pip to install Camelot:
+After [installing the dependencies](https://camelot-py.readthedocs.io/en/master/user/install-deps.html) ([tk](https://packages.ubuntu.com/bionic/python/python-tk) and [ghostscript](https://www.ghostscript.com/)), you can also just use pip to install Camelot:
 
 <pre>
 $ pip install "camelot-py[cv]"
@@ -94,40 +96,16 @@ $ pip install ".[cv]"
 
 ## Documentation
 
-Great documentation is available at [http://camelot-py.readthedocs.io/](http://camelot-py.readthedocs.io/).
-
-## Development
-
-The [Contributor's Guide](https://camelot-py.readthedocs.io/en/master/dev/contributing.html) has detailed information about contributing code, documentation, tests and more. We've included some basic information in this README.
-
-### Source code
-
-You can check the latest sources with:
-
-<pre>
-$ git clone https://www.github.com/camelot-dev/camelot
-</pre>
-
-### Setting up a development environment
-
-You can install the development dependencies easily, using pip:
-
-<pre>
-$ pip install "camelot-py[dev]"
-</pre>
-
-### Testing
-
-After installation, you can run tests using:
-
-<pre>
-$ python setup.py test
-</pre>
+The documentation is available at [http://camelot-py.readthedocs.io/](http://camelot-py.readthedocs.io/).
 
 ## Wrappers
 
 - [camelot-php](https://github.com/randomstate/camelot-php) provides a [PHP](https://www.php.net/) wrapper on Camelot.
 
+## Contributing
+
+The [Contributor's Guide](https://camelot-py.readthedocs.io/en/master/dev/contributing.html) has detailed information about contributing issues, documentation, code, and tests.
+
 ## Versioning
 
 Camelot uses [Semantic Versioning](https://semver.org/). For the available versions, see the tags on this repository. For the changelog, you can check out [HISTORY.md](https://github.com/camelot-dev/camelot/blob/master/HISTORY.md).
@@ -135,9 +113,3 @@ Camelot uses [Semantic Versioning](https://semver.org/). For the available versi
 ## License
 
 This project is licensed under the MIT License, see the [LICENSE](https://github.com/camelot-dev/camelot/blob/master/LICENSE) file for details.
-
-## Support the development
-
-You can support our work on Camelot with a one-time or monthly donation [on OpenCollective](https://opencollective.com/camelot). Organizations who use camelot can also sponsor the project for an acknowledgement on [our documentation site](https://camelot-py.readthedocs.io/en/master/) and this README.
-
-Special thanks to all the users, organizations and contributors that support Camelot!

camelot/__version__.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-VERSION = (0, 8, 2)
+VERSION = (0, 9, 0)
 PRERELEASE = None  # alpha, beta or rc
 REVISION = None
 

camelot/core.py

@@ -55,7 +55,9 @@ class TextEdge(object):
         x = round(self.x, 2)
         y0 = round(self.y0, 2)
         y1 = round(self.y1, 2)
-        return f"<TextEdge x={x} y0={y0} y1={y1} align={self.align} valid={self.is_valid}>"
+        return (
+            f"<TextEdge x={x} y0={y0} y1={y1} align={self.align} valid={self.is_valid}>"
+        )
 
     def update_coords(self, x, y0, edge_tol=50):
         """Updates the text edge's x and bottom y coordinates and sets
@@ -102,8 +104,7 @@ class TextEdges(object):
         return None
 
     def add(self, textline, align):
-        """Adds a new text edge to the current dict.
-        """
+        """Adds a new text edge to the current dict."""
         x = self.get_x_coord(textline, align)
         y0 = textline.y0
         y1 = textline.y1
@@ -111,8 +112,7 @@ class TextEdges(object):
         self._textedges[align].append(te)
 
     def update(self, textline):
-        """Updates an existing text edge in the current dict.
-        """
+        """Updates an existing text edge in the current dict."""
         for align in ["left", "right", "middle"]:
             x_coord = self.get_x_coord(textline, align)
             idx = self.find(x_coord, align)
@@ -304,8 +304,7 @@ class Cell(object):
 
     @property
     def bound(self):
-        """The number of sides on which the cell is bounded.
-        """
+        """The number of sides on which the cell is bounded."""
         return self.top + self.bottom + self.left + self.right
 
 
@@ -361,8 +360,7 @@ class Table(object):
 
     @property
     def data(self):
-        """Returns two-dimensional list of strings in table.
-        """
+        """Returns two-dimensional list of strings in table."""
         d = []
         for row in self.cells:
             d.append([cell.text.strip() for cell in row])
@@ -383,8 +381,7 @@ class Table(object):
         return report
 
     def set_all_edges(self):
-        """Sets all table edges to True.
-        """
+        """Sets all table edges to True."""
         for row in self.cells:
             for cell in row:
                 cell.left = cell.right = cell.top = cell.bottom = True
@@ -526,8 +523,7 @@ class Table(object):
         return self
 
     def set_border(self):
-        """Sets table border edges to True.
-        """
+        """Sets table border edges to True."""
         for r in range(len(self.rows)):
             self.cells[r][0].left = True
             self.cells[r][len(self.cols) - 1].right = True
@@ -631,7 +627,7 @@ class Table(object):
 
         """
         html_string = self.df.to_html(**kwargs)
-        with open(path, "w") as f:
+        with open(path, "w", encoding="utf-8") as f:
             f.write(html_string)
 
     def to_sqlite(self, path, **kwargs):

camelot/ext/ghostscript/__init__.py

@@ -81,8 +81,7 @@ class __Ghostscript(object):
 
 
 def Ghostscript(*args, **kwargs):
-    """Factory function for setting up a Ghostscript instance
-    """
+    """Factory function for setting up a Ghostscript instance"""
     global __instance__
     # Ghostscript only supports a single instance
     if __instance__ is None:

camelot/handlers.py

@@ -70,7 +70,8 @@ class PDFHandler(object):
         if pages == "1":
             page_numbers.append({"start": 1, "end": 1})
         else:
-            infile = PdfFileReader(open(filepath, "rb"), strict=False)
+            instream = open(filepath, "rb")
+            infile = PdfFileReader(instream, strict=False)
             if infile.isEncrypted:
                 infile.decrypt(self.password)
             if pages == "all":
@@ -84,6 +85,7 @@ class PDFHandler(object):
                         page_numbers.append({"start": int(a), "end": int(b)})
                     else:
                         page_numbers.append({"start": int(r), "end": int(r)})
+            instream.close()
         P = []
         for p in page_numbers:
             P.extend(range(p["start"], p["end"] + 1))
@@ -122,7 +124,8 @@ class PDFHandler(object):
             if rotation != "":
                 fpath_new = "".join([froot.replace("page", "p"), "_rotated", fext])
                 os.rename(fpath, fpath_new)
-                infile = PdfFileReader(open(fpath_new, "rb"), strict=False)
+                instream = open(fpath_new, "rb")
+                infile = PdfFileReader(instream, strict=False)
                 if infile.isEncrypted:
                     infile.decrypt(self.password)
                 outfile = PdfFileWriter()
@@ -134,6 +137,7 @@ class PDFHandler(object):
                 outfile.addPage(p)
                 with open(fpath, "wb") as f:
                     outfile.write(f)
+                instream.close()
 
     def parse(
         self, flavor="lattice", suppress_stdout=False, layout_kwargs={}, **kwargs
@@ -163,9 +167,7 @@ class PDFHandler(object):
         with TemporaryDirectory() as tempdir:
             for p in self.pages:
                 self._save_page(self.filepath, p, tempdir)
-            pages = [
-                os.path.join(tempdir, f"page-{p}.pdf") for p in self.pages
-            ]
+            pages = [os.path.join(tempdir, f"page-{p}.pdf") for p in self.pages]
             parser = Lattice(**kwargs) if flavor == "lattice" else Stream(**kwargs)
             for p in pages:
                 t = parser.extract_tables(

camelot/parsers/base.py

@@ -6,8 +6,7 @@ from ..utils import get_page_layout, get_text_objects
 
 
 class BaseParser(object):
-    """Defines a base parser.
-    """
+    """Defines a base parser."""
 
     def _generate_layout(self, filename, layout_kwargs):
         self.filename = filename

camelot/parsers/lattice.py

@@ -211,8 +211,8 @@ class Lattice(BaseParser):
         from ..ext.ghostscript import Ghostscript
 
         self.imagename = "".join([self.rootname, ".png"])
-        gs_call = "-q -sDEVICE=png16m -o {} -r300 {}".format(
-            self.imagename, self.filename
+        gs_call = "-q -sDEVICE=png16m -o {} -r{} {}".format(
+            self.imagename, self.resolution, self.filename
         )
         gs_call = gs_call.encode().split()
         null = open(os.devnull, "wb")

camelot/parsers/stream.py

@@ -65,7 +65,7 @@ class Stream(BaseParser):
         edge_tol=50,
         row_tol=2,
         column_tol=0,
-        **kwargs
+        **kwargs,
     ):
         self.table_regions = table_regions
         self.table_areas = table_areas
@@ -121,6 +121,7 @@ class Stream(BaseParser):
         row_y = 0
         rows = []
         temp = []
+
         for t in text:
             # is checking for upright necessary?
             # if t.get_text().strip() and all([obj.upright for obj in t._objs if
@@ -131,7 +132,9 @@ class Stream(BaseParser):
                     temp = []
                     row_y = t.y0
                 temp.append(t)
+
         rows.append(sorted(temp, key=lambda t: t.x0))
+        if len(rows) > 1:
             __ = rows.pop(0)  # TODO: hacky
         return rows
 
@@ -345,6 +348,9 @@ class Stream(BaseParser):
         else:
             # calculate mode of the list of number of elements in
             # each row to guess the number of columns
+            if not len(elements):
+                cols = [(text_x_min, text_x_max)]
+            else:
                 ncols = max(set(elements), key=elements.count)
                 if ncols == 1:
                     # if mode is 1, the page usually contains not tables
@@ -356,10 +362,10 @@ class Stream(BaseParser):
                     if len(elements):
                         ncols = max(set(elements), key=elements.count)
                     else:
-                    warnings.warn(
-                        f"No tables found in table area {table_idx + 1}"
-                    )
-            cols = [(t.x0, t.x1) for r in rows_grouped if len(r) == ncols for t in r]
+                        warnings.warn(f"No tables found in table area {table_idx + 1}")
+                cols = [
+                    (t.x0, t.x1) for r in rows_grouped if len(r) == ncols for t in r
+                ]
                 cols = self._merge_columns(sorted(cols), column_tol=self.column_tol)
                 inner_text = []
                 for i in range(1, len(cols)):

camelot/plotting.py

@@ -34,16 +34,18 @@ class PlotMethods(object):
             raise ImportError("matplotlib is required for plotting.")
 
         if table.flavor == "lattice" and kind in ["textedge"]:
-            raise NotImplementedError(
-                f"Lattice flavor does not support kind='{kind}'"
-            )
+            raise NotImplementedError(f"Lattice flavor does not support kind='{kind}'")
         elif table.flavor == "stream" and kind in ["joint", "line"]:
-            raise NotImplementedError(
-                f"Stream flavor does not support kind='{kind}'"
-            )
+            raise NotImplementedError(f"Stream flavor does not support kind='{kind}'")
 
         plot_method = getattr(self, kind)
-        return plot_method(table)
+        fig = plot_method(table)
+
+        if filename is not None:
+            fig.savefig(filename)
+            return None
+
+        return fig
 
     def text(self, table):
         """Generates a plot for all text elements present

camelot/utils.py

@@ -353,7 +353,7 @@ def text_in_bbox(bbox, text):
     Returns
     -------
     t_bbox : list
-        List of PDFMiner text objects that lie inside table.
+        List of PDFMiner text objects that lie inside table, discarding the overlapping ones
 
     """
     lb = (bbox[0], bbox[1])
@@ -364,7 +364,97 @@ def text_in_bbox(bbox, text):
         if lb[0] - 2 <= (t.x0 + t.x1) / 2.0 <= rt[0] + 2
         and lb[1] - 2 <= (t.y0 + t.y1) / 2.0 <= rt[1] + 2
     ]
-    return t_bbox
+
+    # Avoid duplicate text by discarding overlapping boxes
+    rest = {t for t in t_bbox}
+    for ba in t_bbox:
+        for bb in rest.copy():
+            if ba == bb:
+                continue
+            if bbox_intersect(ba, bb):
+                # if the intersection is larger than 80% of ba's size, we keep the longest
+                if (bbox_intersection_area(ba, bb) / bbox_area(ba)) > 0.8:
+                    if bbox_longer(bb, ba):
+                        rest.discard(ba)
+    unique_boxes = list(rest)
+
+    return unique_boxes
+
+
+def bbox_intersection_area(ba, bb) -> float:
+    """Returns area of the intersection of the bounding boxes of two PDFMiner objects.
+
+    Parameters
+    ----------
+    ba : PDFMiner text object
+    bb : PDFMiner text object
+
+    Returns
+    -------
+    intersection_area : float
+        Area of the intersection of the bounding boxes of both objects
+
+    """
+    x_left = max(ba.x0, bb.x0)
+    y_top = min(ba.y1, bb.y1)
+    x_right = min(ba.x1, bb.x1)
+    y_bottom = max(ba.y0, bb.y0)
+
+    if x_right < x_left or y_bottom > y_top:
+        return 0.0
+
+    intersection_area = (x_right - x_left) * (y_top - y_bottom)
+    return intersection_area
+
+
+def bbox_area(bb) -> float:
+    """Returns area of the bounding box of a PDFMiner object.
+
+    Parameters
+    ----------
+    bb : PDFMiner text object
+
+    Returns
+    -------
+    area : float
+        Area of the bounding box of the object
+
+    """
+    return (bb.x1 - bb.x0) * (bb.y1 - bb.y0)
+
+
+def bbox_intersect(ba, bb) -> bool:
+    """Returns True if the bounding boxes of two PDFMiner objects intersect.
+
+    Parameters
+    ----------
+    ba : PDFMiner text object
+    bb : PDFMiner text object
+
+    Returns
+    -------
+    overlaps : bool
+        True if the bounding boxes intersect
+
+    """
+    return ba.x1 >= bb.x0 and bb.x1 >= ba.x0 and ba.y1 >= bb.y0 and bb.y1 >= ba.y0
+
+
+def bbox_longer(ba, bb) -> bool:
+    """Returns True if the bounding box of the first PDFMiner object is longer or equal to the second.
+
+    Parameters
+    ----------
+    ba : PDFMiner text object
+    bb : PDFMiner text object
+
+    Returns
+    -------
+    longer : bool
+        True if the bounding box of the first object is longer or equal
+
+    """
+    return (ba.x1 - ba.x0) >= (bb.x1 - bb.x0)
 
 
 def merge_close_lines(ar, line_tol=2):
@@ -411,7 +501,7 @@ def text_strip(text, strip=""):
         return text
 
     stripped = re.sub(
-        fr"[{''.join(map(re.escape, strip))}]", "", text, re.UNICODE
+        fr"[{''.join(map(re.escape, strip))}]", "", text, flags=re.UNICODE
     )
     return stripped
 
@@ -748,23 +838,27 @@ def compute_whitespace(d):
 
 def get_page_layout(
     filename,
+    line_overlap=0.5,
     char_margin=1.0,
     line_margin=0.5,
     word_margin=0.1,
+    boxes_flow=0.5,
     detect_vertical=True,
     all_texts=True,
 ):
     """Returns a PDFMiner LTPage object and page dimension of a single
-    page pdf. See https://euske.github.io/pdfminer/ to get definitions
-    of kwargs.
+    page pdf. To get the definitions of kwargs, see
+    https://pdfminersix.rtfd.io/en/latest/reference/composable.html.
 
     Parameters
     ----------
     filename : string
         Path to pdf file.
+    line_overlap : float
     char_margin : float
     line_margin : float
     word_margin : float
+    boxes_flow : float
     detect_vertical : bool
     all_texts : bool
 
@@ -780,11 +874,15 @@ def get_page_layout(
         parser = PDFParser(f)
         document = PDFDocument(parser)
         if not document.is_extractable:
-            raise PDFTextExtractionNotAllowed(f"Text extraction is not allowed: {filename}")
+            raise PDFTextExtractionNotAllowed(
+                f"Text extraction is not allowed: {filename}"
+            )
         laparams = LAParams(
+            line_overlap=line_overlap,
             char_margin=char_margin,
             line_margin=line_margin,
             word_margin=word_margin,
+            boxes_flow=boxes_flow,
             detect_vertical=detect_vertical,
             all_texts=all_texts,
         )

docs/_themes/flask_theme_support.py

@@ -1,7 +1,19 @@
 # flasky pygments style based on tango style
 from pygments.style import Style
-from pygments.token import Keyword, Name, Comment, String, Error, \
-     Number, Operator, Generic, Whitespace, Punctuation, Other, Literal
+from pygments.token import (
+    Keyword,
+    Name,
+    Comment,
+    String,
+    Error,
+    Number,
+    Operator,
+    Generic,
+    Whitespace,
+    Punctuation,
+    Other,
+    Literal,
+)
 
 
 class FlaskyStyle(Style):
@@ -14,10 +26,8 @@ class FlaskyStyle(Style):
         Whitespace: "underline #f8f8f8",  # class: 'w'
         Error: "#a40000 border:#ef2929",  # class: 'err'
         Other: "#000000",  # class 'x'
-
         Comment: "italic #8f5902",  # class: 'c'
         Comment.Preproc: "noitalic",  # class: 'cp'
-
         Keyword: "bold #004461",  # class: 'k'
         Keyword.Constant: "bold #004461",  # class: 'kc'
         Keyword.Declaration: "bold #004461",  # class: 'kd'
@@ -25,12 +35,9 @@ class FlaskyStyle(Style):
         Keyword.Pseudo: "bold #004461",  # class: 'kp'
         Keyword.Reserved: "bold #004461",  # class: 'kr'
         Keyword.Type: "bold #004461",  # class: 'kt'
-
         Operator: "#582800",  # class: 'o'
         Operator.Word: "bold #004461",  # class: 'ow' - like keywords
-
         Punctuation: "bold #000000",  # class: 'p'
-
         # because special names such as Name.Class, Name.Function, etc.
         # are not recognized as such later in the parsing, we choose them
         # to look the same as ordinary variables.
@@ -53,12 +60,9 @@ class FlaskyStyle(Style):
         Name.Variable.Class: "#000000",  # class: 'vc' - to be revised
         Name.Variable.Global: "#000000",  # class: 'vg' - to be revised
         Name.Variable.Instance: "#000000",  # class: 'vi' - to be revised
-
         Number: "#990000",  # class: 'm'
-
         Literal: "#000000",  # class: 'l'
         Literal.Date: "#000000",  # class: 'ld'
-
         String: "#4e9a06",  # class: 's'
         String.Backtick: "#4e9a06",  # class: 'sb'
         String.Char: "#4e9a06",  # class: 'sc'
@@ -71,7 +75,6 @@ class FlaskyStyle(Style):
         String.Regex: "#4e9a06",  # class: 'sr'
         String.Single: "#4e9a06",  # class: 's1'
         String.Symbol: "#4e9a06",  # class: 'ss'
-
         Generic: "#000000",  # class: 'g'
         Generic.Deleted: "#a40000",  # class: 'gd'
         Generic.Emph: "italic #000000",  # class: 'ge'

docs/conf.py

@@ -22,8 +22,8 @@ import sys
 # sys.path.insert(0, os.path.abspath('..'))
 
 # Insert Camelot's path into the system.
-sys.path.insert(0, os.path.abspath('..'))
-sys.path.insert(0, os.path.abspath('_themes'))
+sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("_themes"))
 
 import camelot
 
@@ -38,33 +38,33 @@ import camelot
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
-    'sphinx.ext.viewcode',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The encoding of source files.
 #
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = u'Camelot'
-copyright = u'2019, Camelot Developers'
-author = u'Vinayak Mehta'
+project = u"Camelot"
+copyright = u"2021, Camelot Developers"
+author = u"Vinayak Mehta"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -94,7 +94,7 @@ language = None
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build']
+exclude_patterns = ["_build"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -114,7 +114,7 @@ add_module_names = True
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'flask_theme_support.FlaskyStyle'
+pygments_style = "flask_theme_support.FlaskyStyle"
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -130,18 +130,18 @@ todo_include_todos = True
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+html_theme = "alabaster"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-    'show_powered_by': False,
-    'github_user': 'camelot-dev',
-    'github_repo': 'camelot',
-    'github_banner': True,
-    'show_related': False,
-    'note_bg': '#FFF59C'
+    "show_powered_by": False,
+    "github_user": "camelot-dev",
+    "github_repo": "camelot",
+    "github_banner": True,
+    "show_related": False,
+    "note_bg": "#FFF59C",
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -164,12 +164,12 @@ html_theme_options = {
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = '_static/favicon.ico'
+html_favicon = "_static/favicon.ico"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -189,10 +189,21 @@ html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {
-    'index': ['sidebarintro.html', 'relations.html', 'sourcelink.html',
-              'searchbox.html', 'hacks.html'],
-    '**': ['sidebarlogo.html', 'localtoc.html', 'relations.html',
-           'sourcelink.html', 'searchbox.html', 'hacks.html']
+    "index": [
+        "sidebarintro.html",
+        "relations.html",
+        "sourcelink.html",
+        "searchbox.html",
+        "hacks.html",
+    ],
+    "**": [
+        "sidebarlogo.html",
+        "localtoc.html",
+        "relations.html",
+        "sourcelink.html",
+        "searchbox.html",
+        "hacks.html",
+    ],
 }
 
 # Additional templates that should be rendered to pages, maps page names to
@@ -249,7 +260,7 @@ html_show_copyright = True
 # html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Camelotdoc'
+htmlhelp_basename = "Camelotdoc"
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -257,15 +268,12 @@ latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -275,8 +283,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'Camelot.tex', u'Camelot Documentation',
-     u'Vinayak Mehta', 'manual'),
+    (master_doc, "Camelot.tex", u"Camelot Documentation", u"Vinayak Mehta", "manual"),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -316,10 +323,7 @@ latex_documents = [
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'Camelot', u'Camelot Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, "Camelot", u"Camelot Documentation", [author], 1)]
 
 # If true, show URL addresses after external links.
 #
@@ -332,9 +336,15 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'Camelot', u'Camelot Documentation',
-     author, 'Camelot', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "Camelot",
+        u"Camelot Documentation",
+        author,
+        "Camelot",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -356,6 +366,6 @@ texinfo_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'https://docs.python.org/2': None,
-    'http://pandas.pydata.org/pandas-docs/stable': None
+    "https://docs.python.org/2": None,
+    "http://pandas.pydata.org/pandas-docs/stable": None,
 }

docs/index.rst

@@ -36,15 +36,15 @@ Release v\ |version|. (:ref:`Installation <install>`)
 .. image:: https://img.shields.io/badge/continous%20quality-deepsource-lightgrey
     :target: https://deepsource.io/gh/camelot-dev/camelot/?ref=repository-badge
 
-**Camelot** is a Python library that makes it easy for *anyone* to extract tables from PDF files!
+**Camelot** is a Python library that can help you extract tables from PDFs!
 
-.. note:: You can also check out `Excalibur`_, which is a web interface for Camelot!
+.. note:: You can also check out `Excalibur`_, the web interface to Camelot!
 
 .. _Excalibur: https://github.com/camelot-dev/excalibur
 
 ----
 
-**Here's how you can extract tables from PDF files.** Check out the PDF used in this example `here`_.
+**Here's how you can extract tables from PDFs.** You can check out the PDF used in this example `here`_.
 
 .. _here: _static/pdf/foo.pdf
 
@@ -70,7 +70,7 @@ Release v\ |version|. (:ref:`Installation <install>`)
 .. csv-table::
   :file: _static/csv/foo.csv
 
-There's a :ref:`command-line interface <cli>` too!
+Camelot also comes packaged with a :ref:`command-line interface <cli>`!
 
 .. note:: Camelot only works with text-based PDFs and not scanned documents. (As Tabula `explains`_, "If you can click and drag to select text in your table in a PDF viewer, then your PDF is text-based".)
 
@@ -79,27 +79,27 @@ There's a :ref:`command-line interface <cli>` too!
 Why Camelot?
 ------------
 
-- **You are in control.** Unlike other libraries and tools which either give a nice output or fail miserably (with no in-between), Camelot gives you the power to tweak table extraction. (This is important since everything in the real world, including PDF table extraction, is fuzzy.)
-- *Bad* tables can be discarded based on **metrics** like accuracy and whitespace, without ever having to manually look at each table.
-- Each table is a **pandas DataFrame**, which seamlessly integrates into `ETL and data analysis workflows`_.
-- **Export** to multiple formats, including JSON, Excel and HTML.
-
-See `comparison with other PDF table extraction libraries and tools`_.
+- **Configurability**: Camelot gives you control over the table extraction process with its :ref:`tweakable settings <advanced>`.
+- **Metrics**: Bad tables can be discarded based on metrics like accuracy and whitespace, without having to manually look at each table.
+- **Output**: Each table is extracted into a **pandas DataFrame**, which seamlessly integrates into `ETL and data analysis workflows`_. You can also export tables to multiple formats, which include CSV, JSON, Excel, HTML and Sqlite.
 
 .. _ETL and data analysis workflows: https://gist.github.com/vinayak-mehta/e5949f7c2410a0e12f25d3682dc9e873
-.. _comparison with other PDF table extraction libraries and tools: https://github.com/camelot-dev/camelot/wiki/Comparison-with-other-PDF-Table-Extraction-libraries-and-tools
 
-Support us on OpenCollective
-----------------------------
+See `comparison with similar libraries and tools`_.
 
-If Camelot helped you extract tables from PDFs, please consider supporting its development by `becoming a backer or a sponsor on OpenCollective`_!
+.. _comparison with similar libraries and tools: https://github.com/camelot-dev/camelot/wiki/Comparison-with-other-PDF-Table-Extraction-libraries-and-tools
 
-.. _becoming a backer or a sponsor on OpenCollective: https://opencollective.com/camelot
+Support the development
+-----------------------
+
+If Camelot has helped you, please consider supporting its development with a one-time or monthly donation `on OpenCollective`_!
+
+.. _on OpenCollective: https://opencollective.com/camelot
 
 The User Guide
 --------------
 
-This part of the documentation begins with some background information about why Camelot was created, takes a small dip into the implementation details and then focuses on step-by-step instructions for getting the most out of Camelot.
+This part of the documentation begins with some background information about why Camelot was created, takes you through some implementation details, and then focuses on step-by-step instructions for getting the most out of Camelot.
 
 .. toctree::
    :maxdepth: 2
@@ -115,8 +115,7 @@ This part of the documentation begins with some background information about why
 The API Documentation/Guide
 ---------------------------
 
-If you are looking for information on a specific function, class, or method,
-this part of the documentation is for you.
+If you are looking for information on a specific function, class, or method, this part of the documentation is for you.
 
 .. toctree::
    :maxdepth: 2
@@ -126,8 +125,7 @@ this part of the documentation is for you.
 The Contributor Guide
 ---------------------
 
-If you want to contribute to the project, this part of the documentation is for
-you.
+If you want to contribute to the project, this part of the documentation is for you.
 
 .. toctree::
    :maxdepth: 2

docs/user/advanced.rst

@@ -66,8 +66,7 @@ Let's plot all the text present on the table's PDF page.
 
 ::
 
-    >>> camelot.plot(tables[0], kind='text')
-    >>> plt.show()
+    >>> camelot.plot(tables[0], kind='text').show()
 
 .. tip::
     Here's how you can do the same with the :ref:`command-line interface <cli>`.
@@ -93,8 +92,7 @@ Let's plot the table (to see if it was detected correctly or not). This plot typ
 
 ::
 
-    >>> camelot.plot(tables[0], kind='grid')
-    >>> plt.show()
+    >>> camelot.plot(tables[0], kind='grid').show()
 
 .. tip::
     Here's how you can do the same with the :ref:`command-line interface <cli>`.
@@ -118,8 +116,7 @@ Now, let's plot all table boundaries present on the table's PDF page.
 
 ::
 
-    >>> camelot.plot(tables[0], kind='contour')
-    >>> plt.show()
+    >>> camelot.plot(tables[0], kind='contour').show()
 
 .. tip::
     Here's how you can do the same with the :ref:`command-line interface <cli>`.
@@ -141,8 +138,7 @@ Cool, let's plot all line segments present on the table's PDF page.
 
 ::
 
-    >>> camelot.plot(tables[0], kind='line')
-    >>> plt.show()
+    >>> camelot.plot(tables[0], kind='line').show()
 
 .. tip::
     Here's how you can do the same with the :ref:`command-line interface <cli>`.
@@ -164,8 +160,7 @@ Finally, let's plot all line intersections present on the table's PDF page.
 
 ::
 
-    >>> camelot.plot(tables[0], kind='joint')
-    >>> plt.show()
+    >>> camelot.plot(tables[0], kind='joint').show()
 
 .. tip::
     Here's how you can do the same with the :ref:`command-line interface <cli>`.
@@ -187,8 +182,7 @@ You can also visualize the textedges found on a page by specifying ``kind='texte
 
 ::
 
-    >>> camelot.plot(tables[0], kind='textedge')
-    >>> plt.show()
+    >>> camelot.plot(tables[0], kind='textedge').show()
 
 .. tip::
     Here's how you can do the same with the :ref:`command-line interface <cli>`.
@@ -375,8 +369,7 @@ Let's see the table area that is detected by default.
 ::
 
     >>> tables = camelot.read_pdf('edge_tol.pdf', flavor='stream')
-    >>> camelot.plot(tables[0], kind='contour')
-    >>> plt.show()
+    >>> camelot.plot(tables[0], kind='contour').show()
 
 .. tip::
     Here's how you can do the same with the :ref:`command-line interface <cli>`.
@@ -396,8 +389,7 @@ To improve the detected area, you can increase the ``edge_tol`` (default: 50) va
 ::
 
     >>> tables = camelot.read_pdf('edge_tol.pdf', flavor='stream', edge_tol=500)
-    >>> camelot.plot(tables[0], kind='contour')
-    >>> plt.show()
+    >>> camelot.plot(tables[0], kind='contour').show()
 
 .. tip::
     Here's how you can do the same with the :ref:`command-line interface <cli>`.
@@ -472,8 +464,7 @@ Let's plot the table for this PDF.
 ::
 
     >>> tables = camelot.read_pdf('short_lines.pdf')
-    >>> camelot.plot(tables[0], kind='grid')
-    >>> plt.show()
+    >>> camelot.plot(tables[0], kind='grid').show()
 
 .. figure:: ../_static/png/short_lines_1.png
     :alt: A plot of the PDF table with short lines
@@ -484,8 +475,7 @@ Clearly, the smaller lines separating the headers, couldn't be detected. Let's t
 ::
 
     >>> tables = camelot.read_pdf('short_lines.pdf', line_scale=40)
-    >>> camelot.plot(tables[0], kind='grid')
-    >>> plt.show()
+    >>> camelot.plot(tables[0], kind='grid').show()
 
 .. tip::
     Here's how you can do the same with the :ref:`command-line interface <cli>`.
@@ -628,7 +618,7 @@ Tweak layout generation
 
 Camelot is built on top of PDFMiner's functionality of grouping characters on a page into words and sentences. In some cases (such as `#170 <https://github.com/camelot-dev/camelot/issues/170>`_ and `#215 <https://github.com/camelot-dev/camelot/issues/215>`_), PDFMiner can group characters that should belong to the same sentence into separate sentences.
 
-To deal with such cases, you can tweak PDFMiner's `LAParams kwargs <https://github.com/euske/pdfminer/blob/master/pdfminer/layout.py#L33>`_ to improve layout generation, by passing the keyword arguments as a dict using ``layout_kwargs`` in :meth:`read_pdf() <camelot.read_pdf>`. To know more about the parameters you can tweak, you can check out `PDFMiner docs <https://euske.github.io/pdfminer/>`_.
+To deal with such cases, you can tweak PDFMiner's `LAParams kwargs <https://github.com/euske/pdfminer/blob/master/pdfminer/layout.py#L33>`_ to improve layout generation, by passing the keyword arguments as a dict using ``layout_kwargs`` in :meth:`read_pdf() <camelot.read_pdf>`. To know more about the parameters you can tweak, you can check out `PDFMiner docs <https://pdfminersix.rtfd.io/en/latest/reference/composable.html>`_.
 
 ::
 

docs/user/how-it-works.rst

@@ -16,7 +16,7 @@ Stream can be used to parse tables that have whitespaces between cells to simula
 
 1. Words on the PDF page are grouped into text rows based on their *y* axis overlaps.
 
-2. Textedges are calculated and then used to guess interesting table areas on the PDF page. You can read `Anssi Nurminen's master's thesis <http://dspace.cc.tut.fi/dpub/bitstream/handle/123456789/21520/Nurminen.pdf?sequence=3>`_ to know more about this table detection technique. [See pages 20, 35 and 40]
+2. Textedges are calculated and then used to guess interesting table areas on the PDF page. You can read `Anssi Nurminen's master's thesis <https://pdfs.semanticscholar.org/a9b1/67a86fb189bfcd366c3839f33f0404db9c10.pdf>`_ to know more about this table detection technique. [See pages 20, 35 and 40]
 
 3. The number of columns inside each table area are then guessed. This is done by calculating the mode of number of words in each text row. Based on this mode, words in each text row are chosen to calculate a list of column *x* ranges.
 

docs/user/install-deps.rst

@@ -3,72 +3,59 @@
 Installation of dependencies
 ============================
 
-The dependencies `Tkinter`_ and `ghostscript`_ can be installed using your system's package manager. You can run one of the following, based on your OS.
-
-.. _Tkinter: https://wiki.python.org/moin/TkInter
-.. _ghostscript: https://www.ghostscript.com
+The dependencies `Ghostscript <https://www.ghostscript.com>`_ and `Tkinter <https://wiki.python.org/moin/TkInter>`_ can be installed using your system's package manager or by running their installer.
 
 OS-specific instructions
 ------------------------
 
-For Ubuntu
-^^^^^^^^^^
+Ubuntu
+^^^^^^
 ::
 
-    $ apt install python-tk ghostscript
+    $ apt install ghostscript python3-tk
 
-Or for Python 3::
-
-    $ apt install python3-tk ghostscript
-
-For macOS
-^^^^^^^^^
+MacOS
+^^^^^
 ::
 
-    $ brew install tcl-tk ghostscript
+    $ brew install ghostscript tcl-tk
 
-For Windows
-^^^^^^^^^^^
+Windows
+^^^^^^^
 
-For Tkinter, you can download the `ActiveTcl Community Edition`_ from ActiveState. For ghostscript, you can get the installer at the `ghostscript downloads page`_.
+For Ghostscript, you can get the installer at their `downloads page <https://www.ghostscript.com/download/gsdnld.html>`_. And for Tkinter, you can download the `ActiveTcl Community Edition <https://www.activestate.com/activetcl/downloads>`_ from ActiveState.
 
-.. _ActiveTcl Community Edition: https://www.activestate.com/activetcl/downloads
-.. _ghostscript downloads page: https://www.ghostscript.com/download/gsdnld.html
-.. _as shown here: https://java.com/en/download/help/path.xml
+Checks to see if dependencies are installed correctly
+-----------------------------------------------------
 
-Checks to see if dependencies were installed correctly
-------------------------------------------------------
+You can run the following checks to see if the dependencies were installed correctly.
 
-You can do the following checks to see if the dependencies were installed correctly.
+For Ghostscript
+^^^^^^^^^^^^^^^
+
+Open the Python REPL and run the following:
+
+For Ubuntu/MacOS::
+
+    >>> from ctypes.util import find_library
+    >>> find_library("gs")
+    "libgs.so.9"
+
+For Windows::
+
+    >>> from ctypes.util import find_library
+    >>> find_library("".join(("gsdll", str(ctypes.sizeof(ctypes.c_voidp) * 8), ".dll"))
+    <name-of-ghostscript-library-on-windows>
+
+**Check:** The output of the ``find_library`` function should not be empty.
+
+If the output is empty, then it's possible that the Ghostscript library is not available one of the ``LD_LIBRARY_PATH``/``DYLD_LIBRARY_PATH``/``PATH`` variables depending on your operating system. In this case, you may have to modify one of those path variables.
 
 For Tkinter
 ^^^^^^^^^^^
 
-Launch Python, and then at the prompt, type::
-
-    >>> import Tkinter
-
-Or in Python 3::
+Launch Python and then import Tkinter::
 
     >>> import tkinter
 
-If you have Tkinter, Python will not print an error message, and if not, you will see an ``ImportError``.
-
-For ghostscript
-^^^^^^^^^^^^^^^
-
-Run the following to check the ghostscript version.
-
-For Ubuntu/macOS::
-
-    $ gs -version
-
-For Windows::
-
-    C:\> gswin64c.exe -version
-
-Or for Windows 32-bit::
-
-    C:\> gswin32c.exe -version
-
-If you have ghostscript, you should see the ghostscript version and copyright information.
+**Check:** Importing ``tkinter`` should not raise an import error.

docs/user/install.rst

@@ -5,42 +5,35 @@ Installation of Camelot
 
 This part of the documentation covers the steps to install Camelot.
 
-Using conda
------------
+After :ref:`installing the dependencies <install_deps>`, which include `Ghostscript <https://www.ghostscript.com>`_ and `Tkinter <https://wiki.python.org/moin/TkInter>`_, you can use one of the following methods to install Camelot:
 
-The easiest way to install Camelot is to install it with `conda`_, which is a package manager and environment management system for the `Anaconda`_ distribution.
-::
+.. warning:: The ``lattice`` flavor will fail to run if Ghostscript is not installed. You may run into errors as shown in `issue #193 <https://github.com/camelot-dev/camelot/issues/193>`_.
 
-    $ conda install -c conda-forge camelot-py
+pip
+---
 
-.. note:: Camelot is available for Python 2.7, 3.5, 3.6 and 3.7 on Linux, macOS and Windows. For Windows, you will need to install ghostscript which you can get from their `downloads page`_.
-
-.. _conda: https://conda.io/docs/
-.. _Anaconda: http://docs.continuum.io/anaconda/
-.. _downloads page: https://www.ghostscript.com/download/gsdnld.html
-.. _conda-forge: https://conda-forge.org/
-
-Using pip
----------
-
-After :ref:`installing the dependencies <install_deps>`, which include `Tkinter`_ and `ghostscript`_, you can simply use pip to install Camelot::
+To install Camelot from PyPI using ``pip``, please include the extra ``cv`` requirement as shown::
 
     $ pip install "camelot-py[cv]"
 
-.. _Tkinter: https://wiki.python.org/moin/TkInter
-.. _ghostscript: https://www.ghostscript.com
+conda
+-----
+
+`conda`_ is a package manager and environment management system for the `Anaconda <https://anaconda.org>`_ distribution. It can be used to install Camelot from the ``conda-forge`` channel::
+
+    $ conda install -c conda-forge camelot-py
 
 From the source code
 --------------------
 
-After :ref:`installing the dependencies <install_deps>`, you can install from the source by:
+After :ref:`installing the dependencies <install_deps>`, you can install Camelot from source by:
 
 1. Cloning the GitHub repository.
 ::
 
     $ git clone https://www.github.com/camelot-dev/camelot
 
-2. Then simply using pip again.
+2. And then simply using pip again.
 ::
 
     $ cd camelot

requirements.txt

@@ -1,10 +0,0 @@
-chardet>=3.0.4
-click>=6.7
-matplotlib>=2.2.3
-numpy>=1.13.3
-opencv-python>=3.4.2.17
-openpyxl>=2.5.8
-pandas>=0.23.4
-pdfminer.six>=20200726
-PyPDF2>=1.26.0
-Sphinx>=3.1.2

setup.py

@@ -6,38 +6,36 @@ from setuptools import find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
 about = {}
-with open(os.path.join(here, 'camelot', '__version__.py'), 'r') as f:
+with open(os.path.join(here, "camelot", "__version__.py"), "r") as f:
     exec(f.read(), about)
 
-with open('README.md', 'r') as f:
+with open("README.md", "r") as f:
     readme = f.read()
 
 
 requires = [
-    'chardet>=3.0.4',
-    'click>=6.7',
-    'numpy>=1.13.3',
-    'openpyxl>=2.5.8',
-    'pandas>=0.23.4',
-    'pdfminer.six>=20200726',
-    'PyPDF2>=1.26.0'
+    "chardet>=3.0.4",
+    "click>=6.7",
+    "numpy>=1.13.3",
+    "openpyxl>=2.5.8",
+    "pandas>=0.23.4",
+    "pdfminer.six>=20200726",
+    "PyPDF2>=1.26.0",
 ]
 
-cv_requires = [
-    'opencv-python>=3.4.2.17'
-]
+cv_requires = ["opencv-python>=3.4.2.17"]
 
 plot_requires = [
-    'matplotlib>=2.2.3',
+    "matplotlib>=2.2.3",
 ]
 
 dev_requires = [
-    'codecov>=2.0.15',
-    'pytest>=5.4.3',
-    'pytest-cov>=2.10.0',
-    'pytest-mpl>=0.11',
-    'pytest-runner>=5.2',
-    'Sphinx>=3.1.2'
+    "codecov>=2.0.15",
+    "pytest>=5.4.3",
+    "pytest-cov>=2.10.0",
+    "pytest-mpl>=0.11",
+    "pytest-runner>=5.2",
+    "Sphinx>=3.1.2",
 ]
 
 all_requires = cv_requires + plot_requires
@@ -45,36 +43,39 @@ dev_requires = dev_requires + all_requires
 
 
 def setup_package():
-    metadata = dict(name=about['__title__'],
-                    version=about['__version__'],
-                    description=about['__description__'],
+    metadata = dict(
+        name=about["__title__"],
+        version=about["__version__"],
+        description=about["__description__"],
         long_description=readme,
         long_description_content_type="text/markdown",
-                    url=about['__url__'],
-                    author=about['__author__'],
-                    author_email=about['__author_email__'],
-                    license=about['__license__'],
-                    packages=find_packages(exclude=('tests',)),
+        url=about["__url__"],
+        author=about["__author__"],
+        author_email=about["__author_email__"],
+        license=about["__license__"],
+        packages=find_packages(exclude=("tests",)),
         install_requires=requires,
         extras_require={
-                        'all': all_requires,
-                        'cv': cv_requires,
-                        'dev': dev_requires,
-                        'plot': plot_requires
+            "all": all_requires,
+            "cv": cv_requires,
+            "dev": dev_requires,
+            "plot": plot_requires,
         },
         entry_points={
-                        'console_scripts': [
-                            'camelot = camelot.cli:cli',
+            "console_scripts": [
+                "camelot = camelot.cli:cli",
             ],
         },
         classifiers=[
             # Trove classifiers
             # Full list: https://pypi.python.org/pypi?%3Aaction=list_classifiers
-                        'License :: OSI Approved :: MIT License',
-                        'Programming Language :: Python :: 3.6',
-                        'Programming Language :: Python :: 3.7',
-                        'Programming Language :: Python :: 3.8'
-                    ])
+            "License :: OSI Approved :: MIT License",
+            "Programming Language :: Python :: 3.6",
+            "Programming Language :: Python :: 3.7",
+            "Programming Language :: Python :: 3.8",
+            "Programming Language :: Python :: 3.9",
+        ],
+    )
 
     try:
         from setuptools import setup
@@ -84,5 +85,5 @@ def setup_package():
     setup(**metadata)
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     setup_package()

tests/data.py

@@ -2798,3 +2798,469 @@ data_stream_layout_kwargs = [
     ["A.O.P Cornas", ""],
     ["Domaine Lionnet « Terre Brûlée » 2012", "15 €"],
 ]
+
+data_stream_duplicated_text = [
+    [
+        "",
+        "2012 BETTER VARIETIES Harvest Report for Minnesota Central  [ MNCE ]",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "ALL SEASON TEST",
+    ],
+    [
+        "",
+        "Doug Toreen, Renville County, MN 55310          [ BIRD ISLAND ]",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "1.3 - 2.0 MAT. GROUP",
+    ],
+    [
+        "PREV. CROP/HERB:",
+        "Corn / Surpass, Roundup",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "S2MNCE01",
+    ],
+    [
+        "SOIL DESCRIPTION:",
+        "",
+        "Canisteo clay loam, mod. well drained, non-irrigated",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+    ],
+    [
+        "SOIL CONDITIONS:",
+        "",
+        "High P, high K, 6.7 pH, 3.9% OM, Low SCN",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        '30" ROW SPACING',
+    ],
+    [
+        "TILLAGE/CULTIVATION:",
+        "conventional w/ fall till",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+    ],
+    ["PEST MANAGEMENT:", "Roundup twice", "", "", "", "", "", "", "", "", ""],
+    [
+        "SEEDED - RATE:",
+        "May 15",
+        "140 000 /A",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "TOP 30 for YIELD of 63 TESTED",
+        "",
+    ],
+    [
+        "HARVESTED - STAND:",
+        "Oct 3",
+        "122 921 /A",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "AVERAGE of (3) REPLICATIONS",
+        "",
+    ],
+    ["", "", "", "", "SCN", "Seed", "Yield", "Moisture", "Lodging", "Stand", "Gross"],
+    [
+        "Company/Brand",
+        "Product/Brand†",
+        "Technol.†",
+        "Mat.",
+        "Resist.",
+        "Trmt.†",
+        "Bu/A",
+        "%",
+        "%",
+        "(x 1000)",
+        "Income",
+    ],
+    [
+        "Kruger",
+        "K2 1901",
+        "RR2Y",
+        "1.9",
+        "R",
+        "Ac,PV",
+        "56.4",
+        "7.6",
+        "0",
+        "126.3",
+        "$846",
+    ],
+    [
+        "Stine",
+        "19RA02 §",
+        "RR2Y",
+        "1.9",
+        "R",
+        "CMB",
+        "55.3",
+        "7.6",
+        "0",
+        "120.0",
+        "$830",
+    ],
+    [
+        "Wensman",
+        "W 3190NR2",
+        "RR2Y",
+        "1.9",
+        "R",
+        "Ac",
+        "54.5",
+        "7.6",
+        "0",
+        "119.5",
+        "$818",
+    ],
+    ["Hefty", "H17Y12", "RR2Y", "1.7", "MR", "I", "53.7", "7.7", "0", "124.4", "$806"],
+    [
+        "Dyna-Gro",
+        "S15RY53",
+        "RR2Y",
+        "1.5",
+        "R",
+        "Ac",
+        "53.6",
+        "7.7",
+        "0",
+        "126.8",
+        "$804",
+    ],
+    [
+        "LG Seeds",
+        "C2050R2",
+        "RR2Y",
+        "2.1",
+        "R",
+        "Ac",
+        "53.6",
+        "7.7",
+        "0",
+        "123.9",
+        "$804",
+    ],
+    [
+        "Titan Pro",
+        "19M42",
+        "RR2Y",
+        "1.9",
+        "R",
+        "CMB",
+        "53.6",
+        "7.7",
+        "0",
+        "121.0",
+        "$804",
+    ],
+    [
+        "Stine",
+        "19RA02 (2) §",
+        "RR2Y",
+        "1.9",
+        "R",
+        "CMB",
+        "53.4",
+        "7.7",
+        "0",
+        "123.9",
+        "$801",
+    ],
+    [
+        "Asgrow",
+        "AG1832 §",
+        "RR2Y",
+        "1.8",
+        "MR",
+        "Ac,PV",
+        "52.9",
+        "7.7",
+        "0",
+        "122.0",
+        "$794",
+    ],
+    [
+        "Prairie Brand",
+        "PB-1566R2",
+        "RR2Y",
+        "1.5",
+        "R",
+        "CMB",
+        "52.8",
+        "7.7",
+        "0",
+        "122.9",
+        "$792",
+    ],
+    [
+        "Channel",
+        "1901R2",
+        "RR2Y",
+        "1.9",
+        "R",
+        "Ac,PV",
+        "52.8",
+        "7.6",
+        "0",
+        "123.4",
+        "$791",
+    ],
+    [
+        "Titan Pro",
+        "20M1",
+        "RR2Y",
+        "2.0",
+        "R",
+        "Am",
+        "52.5",
+        "7.5",
+        "0",
+        "124.4",
+        "$788",
+    ],
+    [
+        "Kruger",
+        "K2-2002",
+        "RR2Y",
+        "2.0",
+        "R",
+        "Ac,PV",
+        "52.4",
+        "7.9",
+        "0",
+        "125.4",
+        "$786",
+    ],
+    [
+        "Channel",
+        "1700R2",
+        "RR2Y",
+        "1.7",
+        "R",
+        "Ac,PV",
+        "52.3",
+        "7.9",
+        "0",
+        "123.9",
+        "$784",
+    ],
+    ["Hefty", "H16Y11", "RR2Y", "1.6", "MR", "I", "51.4", "7.6", "0", "123.9", "$771"],
+    [
+        "Anderson",
+        "162R2Y",
+        "RR2Y",
+        "1.6",
+        "R",
+        "None",
+        "51.3",
+        "7.5",
+        "0",
+        "119.5",
+        "$770",
+    ],
+    [
+        "Titan Pro",
+        "15M22",
+        "RR2Y",
+        "1.5",
+        "R",
+        "CMB",
+        "51.3",
+        "7.8",
+        "0",
+        "125.4",
+        "$769",
+    ],
+    [
+        "Dairyland",
+        "DSR-1710R2Y",
+        "RR2Y",
+        "1.7",
+        "R",
+        "CMB",
+        "51.3",
+        "7.7",
+        "0",
+        "122.0",
+        "$769",
+    ],
+    ["Hefty", "H20R3", "RR2Y", "2.0", "MR", "I", "50.5", "8.2", "0", "121.0", "$757"],
+    [
+        "Prairie Brand",
+        "PB 1743R2",
+        "RR2Y",
+        "1.7",
+        "R",
+        "CMB",
+        "50.2",
+        "7.7",
+        "0",
+        "125.8",
+        "$752",
+    ],
+    [
+        "Gold Country",
+        "1741",
+        "RR2Y",
+        "1.7",
+        "R",
+        "Ac",
+        "50.1",
+        "7.8",
+        "0",
+        "123.9",
+        "$751",
+    ],
+    [
+        "Trelay",
+        "20RR43",
+        "RR2Y",
+        "2.0",
+        "R",
+        "Ac,Ex",
+        "49.9",
+        "7.6",
+        "0",
+        "127.8",
+        "$749",
+    ],
+    ["Hefty", "H14R3", "RR2Y", "1.4", "MR", "I", "49.7", "7.7", "0", "122.9", "$746"],
+    [
+        "Prairie Brand",
+        "PB-2099NRR2",
+        "RR2Y",
+        "2.0",
+        "R",
+        "CMB",
+        "49.6",
+        "7.8",
+        "0",
+        "126.3",
+        "$743",
+    ],
+    [
+        "Wensman",
+        "W 3174NR2",
+        "RR2Y",
+        "1.7",
+        "R",
+        "Ac",
+        "49.3",
+        "7.6",
+        "0",
+        "122.5",
+        "$740",
+    ],
+    [
+        "Kruger",
+        "K2 1602",
+        "RR2Y",
+        "1.6",
+        "R",
+        "Ac,PV",
+        "48.7",
+        "7.6",
+        "0",
+        "125.4",
+        "$731",
+    ],
+    [
+        "NK Brand",
+        "S18-C2 §",
+        "RR2Y",
+        "1.8",
+        "R",
+        "CMB",
+        "48.7",
+        "7.7",
+        "0",
+        "126.8",
+        "$731",
+    ],
+    [
+        "Kruger",
+        "K2 1902",
+        "RR2Y",
+        "1.9",
+        "R",
+        "Ac,PV",
+        "48.7",
+        "7.5",
+        "0",
+        "124.4",
+        "$730",
+    ],
+    [
+        "Prairie Brand",
+        "PB-1823R2",
+        "RR2Y",
+        "1.8",
+        "R",
+        "None",
+        "48.5",
+        "7.6",
+        "0",
+        "121.0",
+        "$727",
+    ],
+    [
+        "Gold Country",
+        "1541",
+        "RR2Y",
+        "1.5",
+        "R",
+        "Ac",
+        "48.4",
+        "7.6",
+        "0",
+        "110.4",
+        "$726",
+    ],
+    ["", "", "", "", "", "Test Average  =", "47.6", "7.7", "0", "122.9", "$713"],
+    ["", "", "", "", "", "LSD (0.10)  =", "5.7", "0.3", "ns", "37.8", "566.4"],
+]

tests/test_cli.py

@@ -160,8 +160,8 @@ def test_cli_output_format():
 
 def test_cli_quiet():
     with TemporaryDirectory() as tempdir:
-        infile = os.path.join(testdir, "blank.pdf")
-        outfile = os.path.join(tempdir, "blank.csv")
+        infile = os.path.join(testdir, "empty.pdf")
+        outfile = os.path.join(tempdir, "empty.csv")
         runner = CliRunner()
 
         result = runner.invoke(

tests/test_common.py

@@ -314,3 +314,11 @@ def test_version_generation_with_prerelease_revision():
         generate_version(version, prerelease=prerelease, revision=revision)
         == "0.7.3-alpha.2"
     )
+
+
+def test_stream_duplicated_text():
+    df = pd.DataFrame(data_stream_duplicated_text)
+
+    filename = os.path.join(testdir, "birdisland.pdf")
+    tables = camelot.read_pdf(filename, flavor="stream")
+    assert_frame_equal(df, tables[0].df)

tests/test_errors.py

@@ -55,15 +55,33 @@ def test_image_warning():
             )
 
 
-def test_no_tables_found():
-    filename = os.path.join(testdir, "blank.pdf")
+def test_lattice_no_tables_on_page():
+    filename = os.path.join(testdir, "empty.pdf")
     with warnings.catch_warnings():
         warnings.simplefilter("error")
         with pytest.raises(UserWarning) as e:
-            tables = camelot.read_pdf(filename)
+            tables = camelot.read_pdf(filename, flavor="lattice")
         assert str(e.value) == "No tables found on page-1"
 
 
+def test_stream_no_tables_on_page():
+    filename = os.path.join(testdir, "empty.pdf")
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        with pytest.raises(UserWarning) as e:
+            tables = camelot.read_pdf(filename, flavor="stream")
+        assert str(e.value) == "No tables found on page-1"
+
+
+def test_stream_no_tables_in_area():
+    filename = os.path.join(testdir, "only_page_number.pdf")
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        with pytest.raises(UserWarning) as e:
+            tables = camelot.read_pdf(filename, flavor="stream")
+        assert str(e.value) == "No tables found in table area 1"
+
+
 def test_no_tables_found_logs_suppressed():
     filename = os.path.join(testdir, "foo.pdf")
     with warnings.catch_warnings():
@@ -77,7 +95,7 @@ def test_no_tables_found_logs_suppressed():
 
 
 def test_no_tables_found_warnings_suppressed():
-    filename = os.path.join(testdir, "blank.pdf")
+    filename = os.path.join(testdir, "empty.pdf")
     with warnings.catch_warnings():
         # the test should fail if any warning is thrown
         warnings.simplefilter("error")