Merge pull request #175 from camelot-dev/revert-0-8-1

[MRG] Revert the changes in v0.8.1

.coveragerc

@@ -1,2 +1,3 @@
 [run]
-branch = True
+branch = True
+omit = camelot/ext/*

.deepsource.toml

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

.github/FUNDING.yml

@@ -0,0 +1 @@
+open_collective: camelot

.gitignore

@@ -12,5 +12,8 @@ coverage.xml
 .pytest_cache/
 _build/
 
+.venv/
+htmlcov/
+
 # vscode
-.vscode
+.vscode

.readthedocs.yml

@@ -0,0 +1,24 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.8
+  install:
+    - requirements: requirements.txt

.travis.yml

@@ -8,14 +8,6 @@ install:
   - make install
 jobs:
   include:
-    - stage: test
-      script:
-        - make test
-      python: '2.7'
-    - stage: test
-      script:
-        - make test
-      python: '3.5'
     - stage: test
       script:
         - make test
@@ -25,8 +17,13 @@ jobs:
         - make test
       python: '3.7'
       dist: xenial
+    - stage: test
+      script:
+        - make test
+      python: '3.8'
+      dist: xenial
     - stage: coverage
-      python: '3.6'
+      python: '3.8'
       script:
         - make test
         - codecov --verbose

CONTRIBUTING.md

@@ -16,14 +16,14 @@ As the [Requests Code Of Conduct](http://docs.python-requests.org/en/master/dev/
 
 ## Your first contribution
 
-A great way to start contributing to Camelot is to pick an issue tagged with the [help wanted](https://github.com/socialcopsdev/camelot/labels/help%20wanted) tag or the [good first issue](https://github.com/socialcopsdev/camelot/labels/good%20first%20issue) tag. If you're unable to find a good first issue, feel free to contact the maintainer.
+A great way to start contributing to Camelot is to pick an issue tagged with the [help wanted](https://github.com/camelot-dev/camelot/labels/help%20wanted) tag or the [good first issue](https://github.com/camelot-dev/camelot/labels/good%20first%20issue) tag. If you're unable to find a good first issue, feel free to contact the maintainer.
 
 ## Setting up a development environment
 
 To install the dependencies needed for development, you can use pip:
 
 <pre>
-$ pip install camelot-py[dev]
+$ pip install "camelot-py[dev]"
 </pre>
 
 Alternatively, you can clone the project repository, and install using pip:
@@ -36,7 +36,7 @@ $ pip install ".[dev]"
 
 ### Submit a pull request
 
-The preferred workflow for contributing to Camelot is to fork the [project repository](https://github.com/socialcopsdev/camelot) on GitHub, clone, develop on a branch and then finally submit a pull request. Here are the steps:
+The preferred workflow for contributing to Camelot is to fork the [project repository](https://github.com/camelot-dev/camelot) on GitHub, clone, develop on a branch and then finally submit a pull request. Here are the steps:
 
 1. Fork the project repository. Click on the ‘Fork’ button near the top of the page. This creates a copy of the code under your account on the GitHub.
 
@@ -106,7 +106,7 @@ The function docstrings are written using the [numpydoc](https://numpydoc.readth
 
 ## Filing Issues
 
-We use [GitHub issues](https://github.com/socialcopsdev/camelot/issues) to keep track of all issues and pull requests. Before opening an issue (which asks a question or reports a bug), please use GitHub search to look for existing issues (both open and closed) that may be similar.
+We use [GitHub issues](https://github.com/camelot-dev/camelot/issues) to keep track of all issues and pull requests. Before opening an issue (which asks a question or reports a bug), please use GitHub search to look for existing issues (both open and closed) that may be similar.
 
 ### Questions
 

HISTORY.md

@@ -4,6 +4,147 @@ Release History
 master
 ------
 
+0.8.2 (2020-07-27)
+------------------
+
+* Revert the changes in `0.8.1`.
+
+0.8.1 (2020-07-21)
+------------------
+
+**Bugfixes**
+
+* [#169](https://github.com/camelot-dev/camelot/issues/169) Fix import error caused by `pdfminer.six==20200720`. [#171](https://github.com/camelot-dev/camelot/pull/171) by Vinayak Mehta.
+
+0.8.0 (2020-05-24)
+------------------
+
+**Improvements**
+
+* Drop Python 2 support!
+    * Remove Python 2.7 and 3.5 support.
+    * Replace all instances of `.format` with f-strings.
+    * Remove all `__future__` imports.
+    * Fix HTTP 403 forbidden exception in read_pdf(url) and remove Python 2 urllib support.
+    * Fix test data.
+
+**Bugfixes**
+
+* Fix library discovery on Windows. [#32](https://github.com/camelot-dev/camelot/pull/32) by [KOLANICH](https://github.com/KOLANICH).
+* Fix calling convention of callback functions. [#34](https://github.com/camelot-dev/camelot/pull/34) by [KOLANICH](https://github.com/KOLANICH).
+
+0.7.3 (2019-07-07)
+------------------
+
+**Improvements**
+
+* Camelot now follows the Black code style! [#1](https://github.com/camelot-dev/camelot/pull/1) and [#3](https://github.com/camelot-dev/camelot/pull/3).
+
+**Bugfixes**
+
+* Fix Click.HelpFormatter monkey-patch. [#5](https://github.com/camelot-dev/camelot/pull/5) by [Dimiter Naydenov](https://github.com/dimitern).
+* Fix strip_text argument getting ignored. [#4](https://github.com/camelot-dev/camelot/pull/4) by [Dimiter Naydenov](https://github.com/dimitern).
+* [#25](https://github.com/camelot-dev/camelot/issues/25) edge_tol skipped in read_pdf. [#26](https://github.com/camelot-dev/camelot/pull/26) by Vinayak Mehta.
+* Fix pytest deprecation warning. [#2](https://github.com/camelot-dev/camelot/pull/2) by Vinayak Mehta.
+* [#293](https://github.com/socialcopsdev/camelot/issues/293) Split text ignores all text to the right of last cut. [#294](https://github.com/socialcopsdev/camelot/pull/294) by Vinayak Mehta.
+* [#277](https://github.com/socialcopsdev/camelot/issues/277) Sort TableList by order of tables in PDF. [#283](https://github.com/socialcopsdev/camelot/pull/283) by [Sym Roe](https://github.com/symroe).
+* [#312](https://github.com/socialcopsdev/camelot/issues/312) `table_regions` throws `ValueError` when `flavor='stream'`. [#332](https://github.com/socialcopsdev/camelot/pull/332) by Vinayak Mehta.
+
+0.7.2 (2019-01-10)
+------------------
+
+**Bugfixes**
+
+* [#245](https://github.com/socialcopsdev/camelot/issues/245) Fix AttributeError for encrypted files. [#251](https://github.com/socialcopsdev/camelot/pull/251) by Yatin Taluja.
+
+
+0.7.1 (2019-01-06)
+------------------
+
+**Bugfixes**
+
+* Move ghostscript import to inside the function so Anaconda builds don't fail.
+
+0.7.0 (2019-01-05)
+------------------
+
+**Improvements**
+
+* [#240](https://github.com/socialcopsdev/camelot/issues/209) Add support to analyze only certain page regions to look for tables. [#243](https://github.com/socialcopsdev/camelot/pull/243) by Vinayak Mehta.
+    * You can use `table_regions` in `read_pdf()` to specify approximate page regions which may contain tables.
+    * Kwarg `line_size_scaling` is now called `line_scale`.
+* [#212](https://github.com/socialcopsdev/camelot/issues/212) Add support to export as sqlite database. [#244](https://github.com/socialcopsdev/camelot/pull/244) by Vinayak Mehta.
+* [#239](https://github.com/socialcopsdev/camelot/issues/239) Raise warning if PDF is image-based. [#240](https://github.com/socialcopsdev/camelot/pull/240) by Vinayak Mehta.
+
+**Documentation**
+
+* Remove mention of old mesh kwarg from docs. [#241](https://github.com/socialcopsdev/camelot/pull/241) by [fte10kso](https://github.com/fte10kso).
+
+**Note**: The python wrapper to Ghostscript's C API is now vendorized under the `ext` module. This was done due to unavailability of the [ghostscript](https://pypi.org/project/ghostscript/) package on Anaconda. The code should be removed after we submit a recipe for it to conda-forge. With this release, the user doesn't need to ensure that the Ghostscript executable is available on the PATH variable.
+
+0.6.0 (2018-12-24)
+------------------
+
+**Improvements**
+
+* [#91](https://github.com/socialcopsdev/camelot/issues/91) Add support to read from url. [#236](https://github.com/socialcopsdev/camelot/pull/236) by Vinayak Mehta.
+* [#229](https://github.com/socialcopsdev/camelot/issues/229), [#230](https://github.com/socialcopsdev/camelot/issues/230) and [#233](https://github.com/socialcopsdev/camelot/issues/233) New configuration parameters. [#234](https://github.com/socialcopsdev/camelot/pull/234) by Vinayak Mehta.
+    * `strip_text`: To define characters that should be stripped from each string.
+    * `edge_tol`: Tolerance parameter for extending textedges vertically.
+    * `resolution`: Resolution used for PDF to PNG conversion.
+    * Check out the [advanced docs](https://camelot-py.readthedocs.io/en/master/user/advanced.html#strip-characters-from-text) for usage details.
+* [#170](https://github.com/socialcopsdev/camelot/issues/170) Add option to pass pdfminer layout kwargs. [#232](https://github.com/socialcopsdev/camelot/pull/232) by Vinayak Mehta.
+    * Keyword arguments for [pdfminer.layout.LAParams](https://github.com/euske/pdfminer/blob/master/pdfminer/layout.py#L33) can now be passed using `layout_kwargs` in `read_pdf()`.
+    * The `margins` keyword argument in `read_pdf()` is now deprecated.
+
+0.5.0 (2018-12-13)
+------------------
+
+**Improvements**
+
+* [#207](https://github.com/socialcopsdev/camelot/issues/207) Add a plot type for Stream text edges and detected table areas. [#224](https://github.com/socialcopsdev/camelot/pull/224) by Vinayak Mehta.
+* [#204](https://github.com/socialcopsdev/camelot/issues/204) `suppress_warnings` is now called `suppress_stdout`. [#225](https://github.com/socialcopsdev/camelot/pull/225) by Vinayak Mehta.
+
+**Bugfixes**
+
+* [#217](https://github.com/socialcopsdev/camelot/issues/217) Fix IndexError when scale is large.
+* [#105](https://github.com/socialcopsdev/camelot/issues/105), [#192](https://github.com/socialcopsdev/camelot/issues/192) and [#215](https://github.com/socialcopsdev/camelot/issues/215) in [#227](https://github.com/socialcopsdev/camelot/pull/227) by Vinayak Mehta.
+
+**Documentation**
+
+* Add pdfplumber comparison and update Tabula (stream) comparison. Check out the [wiki page](https://github.com/socialcopsdev/camelot/wiki/Comparison-with-other-PDF-Table-Extraction-libraries-and-tools).
+
+0.4.1 (2018-12-05)
+------------------
+
+**Bugfixes**
+
+* Add chardet to `install_requires` to fix [#210](https://github.com/socialcopsdev/camelot/issues/210). More details in [pdfminer.six#213](https://github.com/pdfminer/pdfminer.six/issues/213).
+
+0.4.0 (2018-11-23)
+------------------
+
+**Improvements**
+
+* [#102](https://github.com/socialcopsdev/camelot/issues/102) Detect tables automatically when Stream is used. [#206](https://github.com/socialcopsdev/camelot/pull/206) Add implementation of Anssi Nurminen's table detection algorithm by Vinayak Mehta.
+
+0.3.2 (2018-11-04)
+------------------
+
+**Improvements**
+
+* [#186](https://github.com/socialcopsdev/camelot/issues/186) Add `_bbox` attribute to table. [#193](https://github.com/socialcopsdev/camelot/pull/193) by Vinayak Mehta.
+    * You can use `table._bbox` to get coordinates of the detected table.
+
+0.3.1 (2018-11-02)
+------------------
+
+**Improvements**
+
+* Matplotlib is now an optional requirement. [#190](https://github.com/socialcopsdev/camelot/pull/190) by Vinayak Mehta.
+    * You can install it using `$ pip install camelot-py[plot]`.
+* [#127](https://github.com/socialcopsdev/camelot/issues/127) Add tests for plotting. Coverage is now at 87%! [#179](https://github.com/socialcopsdev/camelot/pull/179) by [Suyash Behera](https://github.com/Suyash458).
+
 0.3.0 (2018-10-28)
 ------------------
 

LICENSE

@@ -1,5 +1,11 @@
 MIT License
 
+Modifications:
+
+Copyright (c) 2019 Camelot Developers
+
+Original project:
+
 Copyright (c) 2018 Peeply Private Ltd (Singapore)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

Makefile

@@ -15,7 +15,7 @@ install:
 	pip install ".[dev]"
 
 test:
-	pytest --verbose --cov-config .coveragerc --cov-report term --cov-report xml --cov=camelot tests
+	pytest --verbose --cov-config .coveragerc --cov-report term --cov-report xml --cov=camelot --mpl
 
 docs:
 	cd docs && make html
@@ -25,4 +25,4 @@ publish:
 	pip install twine
 	python setup.py sdist
 	twine upload dist/*
-	rm -fr build dist .egg camelot_py.egg-info
+	rm -fr build dist .egg camelot_py.egg-info

README.md

@@ -1,12 +1,14 @@
 <p align="center">
-   <img src="https://raw.githubusercontent.com/socialcopsdev/camelot/master/docs/_static/camelot.png" width="200">
+   <img src="https://raw.githubusercontent.com/camelot-dev/camelot/master/docs/_static/camelot.png" width="200">
 </p>
 
 # Camelot: PDF Table Extraction for Humans
 
-[![Build Status](https://travis-ci.org/socialcopsdev/camelot.svg?branch=master)](https://travis-ci.org/socialcopsdev/camelot) [![Documentation Status](https://readthedocs.org/projects/camelot-py/badge/?version=master)](https://camelot-py.readthedocs.io/en/master/)
+[![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/)
- [![codecov.io](https://codecov.io/github/socialcopsdev/camelot/badge.svg?branch=master&service=github)](https://codecov.io/github/socialcopsdev/camelot?branch=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/)
+ [![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)
+
 
 **Camelot** is a Python library that makes it easy for *anyone* to extract tables from PDF files!
 
@@ -14,14 +16,14 @@
 
 ---
 
-**Here's how you can extract tables from PDF files.** Check out the PDF used in this example [here](https://github.com/socialcopsdev/camelot/blob/master/docs/_static/pdf/foo.pdf).
+**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).
 
 <pre>
 >>> import camelot
 >>> tables = camelot.read_pdf('foo.pdf')
 >>> tables
 &lt;TableList n=1&gt;
->>> tables.export('foo.csv', f='csv', compress=True) # json, excel, html
+>>> tables.export('foo.csv', f='csv', compress=True) # json, excel, html, sqlite
 >>> tables[0]
 &lt;Table shape=(7, 7)&gt;
 >>> tables[0].parsing_report
@@ -31,7 +33,7 @@
     'order': 1,
     'page': 1
 }
->>> tables[0].to_csv('foo.csv') # to_json, to_excel, to_html
+>>> tables[0].to_csv('foo.csv') # to_json, to_excel, to_html, to_sqlite
 >>> tables[0].df # get a pandas DataFrame!
 </pre>
 
@@ -53,34 +55,26 @@ There's a [command-line interface](https://camelot-py.readthedocs.io/en/master/u
 - **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 and HTML.
+- **Export** to multiple formats, including JSON, Excel, HTML and Sqlite.
 
-See [comparison with other PDF table extraction libraries and tools](https://github.com/socialcopsdev/camelot/wiki/Comparison-with-other-PDF-Table-Extraction-libraries-and-tools).
+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).
 
 ## Installation
 
 ### Using conda
 
-The easiest way to install Camelot is to install it with [conda](https://conda.io/docs/), which is the package manager that the [Anaconda](http://docs.continuum.io/anaconda/) distribution is built upon.
+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.
-
-First, let's add the [conda-forge](https://conda-forge.org/) channel to conda's config:
 
 <pre>
-$ conda config --add channels conda-forge
+$ conda install -c conda-forge camelot-py
-</pre>
-
-Now, you can simply use conda to install Camelot:
-
-<pre>
-$ conda install -c camelot-dev camelot-py
 </pre>
 
 ### Using pip
 
-After [installing the dependencies](https://camelot-py.readthedocs.io/en/master/user/install.html#using-pip) ([tk](https://packages.ubuntu.com/trusty/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 simply use pip to install Camelot:
 
 <pre>
-$ pip install camelot-py[all]
+$ pip install "camelot-py[cv]"
 </pre>
 
 ### From the source code
@@ -88,14 +82,14 @@ $ pip install camelot-py[all]
 After [installing the dependencies](https://camelot-py.readthedocs.io/en/master/user/install.html#using-pip), clone the repo using:
 
 <pre>
-$ git clone https://www.github.com/socialcopsdev/camelot
+$ git clone https://www.github.com/camelot-dev/camelot
 </pre>
 
 and install Camelot using pip:
 
 <pre>
 $ cd camelot
-$ pip install ".[all]"
+$ pip install ".[cv]"
 </pre>
 
 ## Documentation
@@ -111,7 +105,7 @@ The [Contributor's Guide](https://camelot-py.readthedocs.io/en/master/dev/contri
 You can check the latest sources with:
 
 <pre>
-$ git clone https://www.github.com/socialcopsdev/camelot
+$ git clone https://www.github.com/camelot-dev/camelot
 </pre>
 
 ### Setting up a development environment
@@ -119,7 +113,7 @@ $ git clone https://www.github.com/socialcopsdev/camelot
 You can install the development dependencies easily, using pip:
 
 <pre>
-$ pip install camelot-py[dev]
+$ pip install "camelot-py[dev]"
 </pre>
 
 ### Testing
@@ -130,10 +124,20 @@ After installation, you can run tests using:
 $ python setup.py test
 </pre>
 
+## Wrappers
+
+- [camelot-php](https://github.com/randomstate/camelot-php) provides a [PHP](https://www.php.net/) wrapper on Camelot.
+
 ## 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/socialcopsdev/camelot/blob/master/HISTORY.md).
+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).
 
 ## License
 
-This project is licensed under the MIT License, see the [LICENSE](https://github.com/socialcopsdev/camelot/blob/master/LICENSE) file for details.
+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/__init__.py

@@ -2,26 +2,20 @@
 
 import logging
 
-from click import HelpFormatter
-
 from .__version__ import __version__
 from .io import read_pdf
+from .plotting import PlotMethods
 
 
-def _write_usage(self, prog, args='', prefix='Usage: '):
-    return self._write_usage('camelot', args, prefix=prefix)
-
-
-# monkey patch click.HelpFormatter
-HelpFormatter._write_usage = HelpFormatter.write_usage
-HelpFormatter.write_usage = _write_usage
-
 # set up logging
-logger = logging.getLogger('camelot')
+logger = logging.getLogger("camelot")
 
-format_string = '%(asctime)s - %(levelname)s - %(message)s'
+format_string = "%(asctime)s - %(levelname)s - %(message)s"
-formatter = logging.Formatter(format_string, datefmt='%Y-%m-%dT%H:%M:%S')
+formatter = logging.Formatter(format_string, datefmt="%Y-%m-%dT%H:%M:%S")
 handler = logging.StreamHandler()
 handler.setFormatter(formatter)
 
 logger.addHandler(handler)
+
+# instantiate plot method
+plot = PlotMethods()

camelot/__main__.py

@@ -1,9 +1,7 @@
 # -*- coding: utf-8 -*-
 
-from __future__ import absolute_import
 
-
+__all__ = ("main",)
-__all__ = ('main',)
 
 
 def main():

camelot/__version__.py

@@ -1,11 +1,23 @@
 # -*- coding: utf-8 -*-
 
-VERSION = (0, 3, 0)
+VERSION = (0, 8, 2)
+PRERELEASE = None  # alpha, beta or rc
+REVISION = None
 
-__title__ = 'camelot-py'
+
-__description__ = 'PDF Table Extraction for Humans.'
+def generate_version(version, prerelease=None, revision=None):
-__url__ = 'http://camelot-py.readthedocs.io/'
+    version_parts = [".".join(map(str, version))]
-__version__ = '.'.join(map(str, VERSION))
+    if prerelease is not None:
-__author__ = 'Vinayak Mehta'
+        version_parts.append(f"-{prerelease}")
-__author_email__ = 'vmehta94@gmail.com'
+    if revision is not None:
-__license__ = 'MIT License'
+        version_parts.append(f".{revision}")
+    return "".join(version_parts)
+
+
+__title__ = "camelot-py"
+__description__ = "PDF Table Extraction for Humans."
+__url__ = "http://camelot-py.readthedocs.io/"
+__version__ = generate_version(VERSION, prerelease=PRERELEASE, revision=REVISION)
+__author__ = "Vinayak Mehta"
+__author_email__ = "vmehta94@gmail.com"
+__license__ = "MIT License"

camelot/cli.py

@@ -4,11 +4,17 @@ import logging
 
 import click
 
-from . import __version__
+try:
-from .io import read_pdf
+    import matplotlib.pyplot as plt
+except ImportError:
+    _HAS_MPL = False
+else:
+    _HAS_MPL = True
+
+from . import __version__, read_pdf, plot
 
 
-logger = logging.getLogger('camelot')
+logger = logging.getLogger("camelot")
 logger.setLevel(logging.INFO)
 
 
@@ -23,23 +29,49 @@ class Config(object):
 pass_config = click.make_pass_decorator(Config)
 
 
-@click.group()
+@click.group(name="camelot")
 @click.version_option(version=__version__)
-@click.option('-p', '--pages', default='1', help='Comma-separated page numbers.'
+@click.option("-q", "--quiet", is_flag=False, help="Suppress logs and warnings.")
-              ' Example: 1,3,4 or 1,4-end.')
+@click.option(
-@click.option('-pw', '--password', help='Password for decryption.')
+    "-p",
-@click.option('-o', '--output', help='Output file path.')
+    "--pages",
-@click.option('-f', '--format',
+    default="1",
-              type=click.Choice(['csv', 'json', 'excel', 'html']),
+    help="Comma-separated page numbers." " Example: 1,3,4 or 1,4-end or all.",
-              help='Output file format.')
+)
-@click.option('-z', '--zip', is_flag=True, help='Create ZIP archive.')
+@click.option("-pw", "--password", help="Password for decryption.")
-@click.option('-split', '--split_text', is_flag=True,
+@click.option("-o", "--output", help="Output file path.")
-              help='Split text that spans across multiple cells.')
+@click.option(
-@click.option('-flag', '--flag_size', is_flag=True, help='Flag text based on'
+    "-f",
-              ' font size. Useful to detect super/subscripts.')
+    "--format",
-@click.option('-M', '--margins', nargs=3, default=(1.0, 0.5, 0.1),
+    type=click.Choice(["csv", "json", "excel", "html", "sqlite"]),
-              help='PDFMiner char_margin, line_margin and word_margin.')
+    help="Output file format.",
-@click.option('-q', '--quiet', is_flag=True, help='Suppress warnings.')
+)
+@click.option("-z", "--zip", is_flag=True, help="Create ZIP archive.")
+@click.option(
+    "-split",
+    "--split_text",
+    is_flag=True,
+    help="Split text that spans across multiple cells.",
+)
+@click.option(
+    "-flag",
+    "--flag_size",
+    is_flag=True,
+    help="Flag text based on" " font size. Useful to detect super/subscripts.",
+)
+@click.option(
+    "-strip",
+    "--strip_text",
+    help="Characters that should be stripped from a string before"
+    " assigning it to a cell.",
+)
+@click.option(
+    "-M",
+    "--margins",
+    nargs=3,
+    default=(1.0, 0.5, 0.1),
+    help="PDFMiner char_margin, line_margin and word_margin.",
+)
 @click.pass_context
 def cli(ctx, *args, **kwargs):
     """Camelot: PDF Table Extraction for Humans"""
@@ -48,115 +80,225 @@ def cli(ctx, *args, **kwargs):
         ctx.obj.set_config(key, value)
 
 
-@cli.command('lattice')
+@cli.command("lattice")
-@click.option('-T', '--table_areas', default=[], multiple=True,
+@click.option(
-              help='Table areas to process. Example: x1,y1,x2,y2'
+    "-R",
-              ' where x1, y1 -> left-top and x2, y2 -> right-bottom.')
+    "--table_regions",
-@click.option('-back', '--process_background', is_flag=True,
+    default=[],
-              help='Process background lines.')
+    multiple=True,
-@click.option('-scale', '--line_size_scaling', default=15,
+    help="Page regions to analyze. Example: x1,y1,x2,y2"
-              help='Line size scaling factor. The larger the value,'
+    " where x1, y1 -> left-top and x2, y2 -> right-bottom.",
-              ' the smaller the detected lines.')
+)
-@click.option('-copy', '--copy_text', default=[], type=click.Choice(['h', 'v']),
+@click.option(
-              multiple=True, help='Direction in which text in a spanning cell'
+    "-T",
-              ' will be copied over.')
+    "--table_areas",
-@click.option('-shift', '--shift_text', default=['l', 't'],
+    default=[],
-              type=click.Choice(['', 'l', 'r', 't', 'b']), multiple=True,
+    multiple=True,
-              help='Direction in which text in a spanning cell will flow.')
+    help="Table areas to process. Example: x1,y1,x2,y2"
-@click.option('-l', '--line_close_tol', default=2,
+    " where x1, y1 -> left-top and x2, y2 -> right-bottom.",
-              help='Tolerance parameter used to merge close vertical'
+)
-              ' and horizontal lines.')
+@click.option(
-@click.option('-j', '--joint_close_tol', default=2,
+    "-back", "--process_background", is_flag=True, help="Process background lines."
-              help='Tolerance parameter used to decide whether'
+)
-              ' the detected lines and points lie close to each other.')
+@click.option(
-@click.option('-block', '--threshold_blocksize', default=15,
+    "-scale",
-              help='For adaptive thresholding, size of a pixel'
+    "--line_scale",
-              ' neighborhood that is used to calculate a threshold value for'
+    default=15,
-              ' the pixel. Example: 3, 5, 7, and so on.')
+    help="Line size scaling factor. The larger the value,"
-@click.option('-const', '--threshold_constant', default=-2,
+    " the smaller the detected lines.",
-              help='For adaptive thresholding, constant subtracted'
+)
-              ' from the mean or weighted mean. Normally, it is positive but'
+@click.option(
-              ' may be zero or negative as well.')
+    "-copy",
-@click.option('-I', '--iterations', default=0,
+    "--copy_text",
-              help='Number of times for erosion/dilation will be applied.')
+    default=[],
-@click.option('-plot', '--plot_type',
+    type=click.Choice(["h", "v"]),
-              type=click.Choice(['text', 'table', 'contour', 'joint', 'line']),
+    multiple=True,
-              help='Plot geometry found on PDF page, for debugging.')
+    help="Direction in which text in a spanning cell" " will be copied over.",
-@click.argument('filepath', type=click.Path(exists=True))
+)
+@click.option(
+    "-shift",
+    "--shift_text",
+    default=["l", "t"],
+    type=click.Choice(["", "l", "r", "t", "b"]),
+    multiple=True,
+    help="Direction in which text in a spanning cell will flow.",
+)
+@click.option(
+    "-l",
+    "--line_tol",
+    default=2,
+    help="Tolerance parameter used to merge close vertical" " and horizontal lines.",
+)
+@click.option(
+    "-j",
+    "--joint_tol",
+    default=2,
+    help="Tolerance parameter used to decide whether"
+    " the detected lines and points lie close to each other.",
+)
+@click.option(
+    "-block",
+    "--threshold_blocksize",
+    default=15,
+    help="For adaptive thresholding, size of a pixel"
+    " neighborhood that is used to calculate a threshold value for"
+    " the pixel. Example: 3, 5, 7, and so on.",
+)
+@click.option(
+    "-const",
+    "--threshold_constant",
+    default=-2,
+    help="For adaptive thresholding, constant subtracted"
+    " from the mean or weighted mean. Normally, it is positive but"
+    " may be zero or negative as well.",
+)
+@click.option(
+    "-I",
+    "--iterations",
+    default=0,
+    help="Number of times for erosion/dilation will be applied.",
+)
+@click.option(
+    "-res",
+    "--resolution",
+    default=300,
+    help="Resolution used for PDF to PNG conversion.",
+)
+@click.option(
+    "-plot",
+    "--plot_type",
+    type=click.Choice(["text", "grid", "contour", "joint", "line"]),
+    help="Plot elements found on PDF page for visual debugging.",
+)
+@click.argument("filepath", type=click.Path(exists=True))
 @pass_config
 def lattice(c, *args, **kwargs):
     """Use lines between text to parse the table."""
     conf = c.config
-    pages = conf.pop('pages')
+    pages = conf.pop("pages")
-    output = conf.pop('output')
+    output = conf.pop("output")
-    f = conf.pop('format')
+    f = conf.pop("format")
-    compress = conf.pop('zip')
+    compress = conf.pop("zip")
-    suppress_warnings = conf.pop('quiet')
+    quiet = conf.pop("quiet")
-    plot_type = kwargs.pop('plot_type')
+    plot_type = kwargs.pop("plot_type")
-    filepath = kwargs.pop('filepath')
+    filepath = kwargs.pop("filepath")
     kwargs.update(conf)
 
-    table_areas = list(kwargs['table_areas'])
+    table_regions = list(kwargs["table_regions"])
-    kwargs['table_areas'] = None if not table_areas else table_areas
+    kwargs["table_regions"] = None if not table_regions else table_regions
-    copy_text = list(kwargs['copy_text'])
+    table_areas = list(kwargs["table_areas"])
-    kwargs['copy_text'] = None if not copy_text else copy_text
+    kwargs["table_areas"] = None if not table_areas else table_areas
-    kwargs['shift_text'] = list(kwargs['shift_text'])
+    copy_text = list(kwargs["copy_text"])
+    kwargs["copy_text"] = None if not copy_text else copy_text
+    kwargs["shift_text"] = list(kwargs["shift_text"])
 
-    tables = read_pdf(filepath, pages=pages, flavor='lattice',
-                      suppress_warnings=suppress_warnings, **kwargs)
-    click.echo('Found {} tables'.format(tables.n))
     if plot_type is not None:
-        for table in tables:
+        if not _HAS_MPL:
-            table.plot(plot_type)
+            raise ImportError("matplotlib is required for plotting.")
     else:
         if output is None:
-            raise click.UsageError('Please specify output file path using --output')
+            raise click.UsageError("Please specify output file path using --output")
         if f is None:
-            raise click.UsageError('Please specify output file format using --format')
+            raise click.UsageError("Please specify output file format using --format")
+
+    tables = read_pdf(
+        filepath, pages=pages, flavor="lattice", suppress_stdout=quiet, **kwargs
+    )
+    click.echo(f"Found {tables.n} tables")
+    if plot_type is not None:
+        for table in tables:
+            plot(table, kind=plot_type)
+            plt.show()
+    else:
         tables.export(output, f=f, compress=compress)
 
 
-@cli.command('stream')
+@cli.command("stream")
-@click.option('-T', '--table_areas', default=[], multiple=True,
+@click.option(
-              help='Table areas to process. Example: x1,y1,x2,y2'
+    "-R",
-              ' where x1, y1 -> left-top and x2, y2 -> right-bottom.')
+    "--table_regions",
-@click.option('-C', '--columns', default=[], multiple=True,
+    default=[],
-              help='X coordinates of column separators.')
+    multiple=True,
-@click.option('-r', '--row_close_tol', default=2, help='Tolerance parameter'
+    help="Page regions to analyze. Example: x1,y1,x2,y2"
-              ' used to combine text vertically, to generate rows.')
+    " where x1, y1 -> left-top and x2, y2 -> right-bottom.",
-@click.option('-c', '--col_close_tol', default=0, help='Tolerance parameter'
+)
-              ' used to combine text horizontally, to generate columns.')
+@click.option(
-@click.option('-plot', '--plot_type',
+    "-T",
-              type=click.Choice(['text', 'table']),
+    "--table_areas",
-              help='Plot geometry found on PDF page for debugging.')
+    default=[],
-@click.argument('filepath', type=click.Path(exists=True))
+    multiple=True,
+    help="Table areas to process. Example: x1,y1,x2,y2"
+    " where x1, y1 -> left-top and x2, y2 -> right-bottom.",
+)
+@click.option(
+    "-C",
+    "--columns",
+    default=[],
+    multiple=True,
+    help="X coordinates of column separators.",
+)
+@click.option(
+    "-e",
+    "--edge_tol",
+    default=50,
+    help="Tolerance parameter" " for extending textedges vertically.",
+)
+@click.option(
+    "-r",
+    "--row_tol",
+    default=2,
+    help="Tolerance parameter" " used to combine text vertically, to generate rows.",
+)
+@click.option(
+    "-c",
+    "--column_tol",
+    default=0,
+    help="Tolerance parameter"
+    " used to combine text horizontally, to generate columns.",
+)
+@click.option(
+    "-plot",
+    "--plot_type",
+    type=click.Choice(["text", "grid", "contour", "textedge"]),
+    help="Plot elements found on PDF page for visual debugging.",
+)
+@click.argument("filepath", type=click.Path(exists=True))
 @pass_config
 def stream(c, *args, **kwargs):
     """Use spaces between text to parse the table."""
     conf = c.config
-    pages = conf.pop('pages')
+    pages = conf.pop("pages")
-    output = conf.pop('output')
+    output = conf.pop("output")
-    f = conf.pop('format')
+    f = conf.pop("format")
-    compress = conf.pop('zip')
+    compress = conf.pop("zip")
-    suppress_warnings = conf.pop('quiet')
+    quiet = conf.pop("quiet")
-    plot_type = kwargs.pop('plot_type')
+    plot_type = kwargs.pop("plot_type")
-    filepath = kwargs.pop('filepath')
+    filepath = kwargs.pop("filepath")
     kwargs.update(conf)
 
-    table_areas = list(kwargs['table_areas'])
+    table_regions = list(kwargs["table_regions"])
-    kwargs['table_areas'] = None if not table_areas else table_areas
+    kwargs["table_regions"] = None if not table_regions else table_regions
-    columns = list(kwargs['columns'])
+    table_areas = list(kwargs["table_areas"])
-    kwargs['columns'] = None if not columns else columns
+    kwargs["table_areas"] = None if not table_areas else table_areas
+    columns = list(kwargs["columns"])
+    kwargs["columns"] = None if not columns else columns
 
-    tables = read_pdf(filepath, pages=pages, flavor='stream',
-                      suppress_warnings=suppress_warnings, **kwargs)
-    click.echo('Found {} tables'.format(tables.n))
     if plot_type is not None:
-        for table in tables:
+        if not _HAS_MPL:
-            table.plot(plot_type)
+            raise ImportError("matplotlib is required for plotting.")
     else:
         if output is None:
-            raise click.UsageError('Please specify output file path using --output')
+            raise click.UsageError("Please specify output file path using --output")
         if f is None:
-            raise click.UsageError('Please specify output file format using --format')
+            raise click.UsageError("Please specify output file format using --format")
+
+    tables = read_pdf(
+        filepath, pages=pages, flavor="stream", suppress_stdout=quiet, **kwargs
+    )
+    click.echo(f"Found {tables.n} tables")
+    if plot_type is not None:
+        for table in tables:
+            plot(table, kind=plot_type)
+            plt.show()
+    else:
         tables.export(output, f=f, compress=compress)

camelot/core.py

@@ -1,13 +1,231 @@
 # -*- coding: utf-8 -*-
 
 import os
+import sqlite3
 import zipfile
 import tempfile
+from itertools import chain
+from operator import itemgetter
 
 import numpy as np
 import pandas as pd
 
-from .plotting import *
+
+# minimum number of vertical textline intersections for a textedge
+# to be considered valid
+TEXTEDGE_REQUIRED_ELEMENTS = 4
+# padding added to table area on the left, right and bottom
+TABLE_AREA_PADDING = 10
+
+
+class TextEdge(object):
+    """Defines a text edge coordinates relative to a left-bottom
+    origin. (PDF coordinate space)
+
+    Parameters
+    ----------
+    x : float
+        x-coordinate of the text edge.
+    y0 : float
+        y-coordinate of bottommost point.
+    y1 : float
+        y-coordinate of topmost point.
+    align : string, optional (default: 'left')
+        {'left', 'right', 'middle'}
+
+    Attributes
+    ----------
+    intersections: int
+        Number of intersections with horizontal text rows.
+    is_valid: bool
+        A text edge is valid if it intersections with at least
+        TEXTEDGE_REQUIRED_ELEMENTS horizontal text rows.
+
+    """
+
+    def __init__(self, x, y0, y1, align="left"):
+        self.x = x
+        self.y0 = y0
+        self.y1 = y1
+        self.align = align
+        self.intersections = 0
+        self.is_valid = False
+
+    def __repr__(self):
+        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}>"
+
+    def update_coords(self, x, y0, edge_tol=50):
+        """Updates the text edge's x and bottom y coordinates and sets
+        the is_valid attribute.
+        """
+        if np.isclose(self.y0, y0, atol=edge_tol):
+            self.x = (self.intersections * self.x + x) / float(self.intersections + 1)
+            self.y0 = y0
+            self.intersections += 1
+            # a textedge is valid only if it extends uninterrupted
+            # over a required number of textlines
+            if self.intersections > TEXTEDGE_REQUIRED_ELEMENTS:
+                self.is_valid = True
+
+
+class TextEdges(object):
+    """Defines a dict of left, right and middle text edges found on
+    the PDF page. The dict has three keys based on the alignments,
+    and each key's value is a list of camelot.core.TextEdge objects.
+    """
+
+    def __init__(self, edge_tol=50):
+        self.edge_tol = edge_tol
+        self._textedges = {"left": [], "right": [], "middle": []}
+
+    @staticmethod
+    def get_x_coord(textline, align):
+        """Returns the x coordinate of a text row based on the
+        specified alignment.
+        """
+        x_left = textline.x0
+        x_right = textline.x1
+        x_middle = x_left + (x_right - x_left) / 2.0
+        x_coord = {"left": x_left, "middle": x_middle, "right": x_right}
+        return x_coord[align]
+
+    def find(self, x_coord, align):
+        """Returns the index of an existing text edge using
+        the specified x coordinate and alignment.
+        """
+        for i, te in enumerate(self._textedges[align]):
+            if np.isclose(te.x, x_coord, atol=0.5):
+                return i
+        return None
+
+    def add(self, textline, align):
+        """Adds a new text edge to the current dict.
+        """
+        x = self.get_x_coord(textline, align)
+        y0 = textline.y0
+        y1 = textline.y1
+        te = TextEdge(x, y0, y1, align=align)
+        self._textedges[align].append(te)
+
+    def update(self, textline):
+        """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)
+            if idx is None:
+                self.add(textline, align)
+            else:
+                self._textedges[align][idx].update_coords(
+                    x_coord, textline.y0, edge_tol=self.edge_tol
+                )
+
+    def generate(self, textlines):
+        """Generates the text edges dict based on horizontal text
+        rows.
+        """
+        for tl in textlines:
+            if len(tl.get_text().strip()) > 1:  # TODO: hacky
+                self.update(tl)
+
+    def get_relevant(self):
+        """Returns the list of relevant text edges (all share the same
+        alignment) based on which list intersects horizontal text rows
+        the most.
+        """
+        intersections_sum = {
+            "left": sum(
+                te.intersections for te in self._textedges["left"] if te.is_valid
+            ),
+            "right": sum(
+                te.intersections for te in self._textedges["right"] if te.is_valid
+            ),
+            "middle": sum(
+                te.intersections for te in self._textedges["middle"] if te.is_valid
+            ),
+        }
+
+        # TODO: naive
+        # get vertical textedges that intersect maximum number of
+        # times with horizontal textlines
+        relevant_align = max(intersections_sum.items(), key=itemgetter(1))[0]
+        return self._textedges[relevant_align]
+
+    def get_table_areas(self, textlines, relevant_textedges):
+        """Returns a dict of interesting table areas on the PDF page
+        calculated using relevant text edges.
+        """
+
+        def pad(area, average_row_height):
+            x0 = area[0] - TABLE_AREA_PADDING
+            y0 = area[1] - TABLE_AREA_PADDING
+            x1 = area[2] + TABLE_AREA_PADDING
+            # add a constant since table headers can be relatively up
+            y1 = area[3] + average_row_height * 5
+            return (x0, y0, x1, y1)
+
+        # sort relevant textedges in reading order
+        relevant_textedges.sort(key=lambda te: (-te.y0, te.x))
+
+        table_areas = {}
+        for te in relevant_textedges:
+            if te.is_valid:
+                if not table_areas:
+                    table_areas[(te.x, te.y0, te.x, te.y1)] = None
+                else:
+                    found = None
+                    for area in table_areas:
+                        # check for overlap
+                        if te.y1 >= area[1] and te.y0 <= area[3]:
+                            found = area
+                            break
+                    if found is None:
+                        table_areas[(te.x, te.y0, te.x, te.y1)] = None
+                    else:
+                        table_areas.pop(found)
+                        updated_area = (
+                            found[0],
+                            min(te.y0, found[1]),
+                            max(found[2], te.x),
+                            max(found[3], te.y1),
+                        )
+                        table_areas[updated_area] = None
+
+        # extend table areas based on textlines that overlap
+        # vertically. it's possible that these textlines were
+        # eliminated during textedges generation since numbers and
+        # chars/words/sentences are often aligned differently.
+        # drawback: table areas that have paragraphs on their sides
+        # will include the paragraphs too.
+        sum_textline_height = 0
+        for tl in textlines:
+            sum_textline_height += tl.y1 - tl.y0
+            found = None
+            for area in table_areas:
+                # check for overlap
+                if tl.y0 >= area[1] and tl.y1 <= area[3]:
+                    found = area
+                    break
+            if found is not None:
+                table_areas.pop(found)
+                updated_area = (
+                    min(tl.x0, found[0]),
+                    min(tl.y0, found[1]),
+                    max(found[2], tl.x1),
+                    max(found[3], tl.y1),
+                )
+                table_areas[updated_area] = None
+        average_textline_height = sum_textline_height / float(len(textlines))
+
+        # add some padding to table areas
+        table_areas_padded = {}
+        for area in table_areas:
+            table_areas_padded[pad(area, average_textline_height)] = None
+
+        return table_areas_padded
 
 
 class Cell(object):
@@ -67,11 +285,14 @@ class Cell(object):
         self.bottom = False
         self.hspan = False
         self.vspan = False
-        self._text = ''
+        self._text = ""
 
     def __repr__(self):
-        return '<Cell x1={} y1={} x2={} y2={}>'.format(
+        x1 = round(self.x1, 2)
-            round(self.x1, 2), round(self.y1, 2), round(self.x2, 2), round(self.y2, 2))
+        y1 = round(self.y1, 2)
+        x2 = round(self.x2, 2)
+        y2 = round(self.y2, 2)
+        return f"<Cell x1={x1} y1={y1} x2={x2} y2={y2}>"
 
     @property
     def text(self):
@@ -79,7 +300,7 @@ class Cell(object):
 
     @text.setter
     def text(self, t):
-        self._text = ''.join([self._text, t])
+        self._text = "".join([self._text, t])
 
     @property
     def bound(self):
@@ -116,11 +337,11 @@ class Table(object):
         PDF page number.
 
     """
+
     def __init__(self, cols, rows):
         self.cols = cols
         self.rows = rows
-        self.cells = [[Cell(c[0], r[1], c[1], r[0])
+        self.cells = [[Cell(c[0], r[1], c[1], r[0]) for c in cols] for r in rows]
-                       for c in cols] for r in rows]
         self.df = None
         self.shape = (0, 0)
         self.accuracy = 0
@@ -129,7 +350,14 @@ class Table(object):
         self.page = None
 
     def __repr__(self):
-        return '<{} shape={}>'.format(self.__class__.__name__, self.shape)
+        return f"<{self.__class__.__name__} shape={self.shape}>"
+
+    def __lt__(self, other):
+        if self.page == other.page:
+            if self.order < other.order:
+                return True
+        if self.page < other.page:
+            return True
 
     @property
     def data(self):
@@ -147,10 +375,10 @@ class Table(object):
         """
         # pretty?
         report = {
-            'accuracy': round(self.accuracy, 2),
+            "accuracy": round(self.accuracy, 2),
-            'whitespace': round(self.whitespace, 2),
+            "whitespace": round(self.whitespace, 2),
-            'order': self.order,
+            "order": self.order,
-            'page': self.page
+            "page": self.page,
         }
         return report
 
@@ -162,7 +390,7 @@ class Table(object):
                 cell.left = cell.right = cell.top = cell.bottom = True
         return self
 
-    def set_edges(self, vertical, horizontal, joint_close_tol=2):
+    def set_edges(self, vertical, horizontal, joint_tol=2):
         """Sets a cell's edges to True depending on whether the cell's
         coordinates overlap with the line's coordinates within a
         tolerance.
@@ -178,12 +406,21 @@ class Table(object):
         for v in vertical:
             # find closest x coord
             # iterate over y coords and find closest start and end points
-            i = [i for i, t in enumerate(self.cols)
+            i = [
-                 if np.isclose(v[0], t[0], atol=joint_close_tol)]
+                i
-            j = [j for j, t in enumerate(self.rows)
+                for i, t in enumerate(self.cols)
-                 if np.isclose(v[3], t[0], atol=joint_close_tol)]
+                if np.isclose(v[0], t[0], atol=joint_tol)
-            k = [k for k, t in enumerate(self.rows)
+            ]
-                 if np.isclose(v[1], t[0], atol=joint_close_tol)]
+            j = [
+                j
+                for j, t in enumerate(self.rows)
+                if np.isclose(v[3], t[0], atol=joint_tol)
+            ]
+            k = [
+                k
+                for k, t in enumerate(self.rows)
+                if np.isclose(v[1], t[0], atol=joint_tol)
+            ]
             if not j:
                 continue
             J = j[0]
@@ -229,12 +466,21 @@ class Table(object):
         for h in horizontal:
             # find closest y coord
             # iterate over x coords and find closest start and end points
-            i = [i for i, t in enumerate(self.rows)
+            i = [
-                 if np.isclose(h[1], t[0], atol=joint_close_tol)]
+                i
-            j = [j for j, t in enumerate(self.cols)
+                for i, t in enumerate(self.rows)
-                 if np.isclose(h[0], t[0], atol=joint_close_tol)]
+                if np.isclose(h[1], t[0], atol=joint_tol)
-            k = [k for k, t in enumerate(self.cols)
+            ]
-                 if np.isclose(h[2], t[0], atol=joint_close_tol)]
+            j = [
+                j
+                for j, t in enumerate(self.cols)
+                if np.isclose(h[0], t[0], atol=joint_tol)
+            ]
+            k = [
+                k
+                for k, t in enumerate(self.cols)
+                if np.isclose(h[2], t[0], atol=joint_tol)
+            ]
             if not j:
                 continue
             J = j[0]
@@ -251,7 +497,7 @@ class Table(object):
                         self.cells[L][J].top = True
                         J += 1
             elif i == []:  # only bottom edge
-                I = len(self.rows) - 1
+                L = len(self.rows) - 1
                 if k:
                     K = k[0]
                     while J < K:
@@ -321,33 +567,6 @@ class Table(object):
                     cell.hspan = True
         return self
 
-    def plot(self, geometry_type):
-        """Plot geometry found on PDF page based on geometry_type
-        specified, useful for debugging and playing with different
-        parameters to get the best output.
-
-        Parameters
-        ----------
-        geometry_type : str
-            The geometry type for which a plot should be generated.
-            Can be 'text', 'table', 'contour', 'joint', 'line'
-
-        """
-        if self.flavor == 'stream' and geometry_type in ['contour', 'joint', 'line']:
-            raise NotImplementedError("{} cannot be plotted with flavor='stream'".format(
-                                       geometry_type))
-
-        if geometry_type == 'text':
-            plot_text(self._text)
-        elif geometry_type == 'table':
-            plot_table(self)
-        elif geometry_type == 'contour':
-            plot_contour(self._image)
-        elif geometry_type == 'joint':
-            plot_joint(self._image)
-        elif geometry_type == 'line':
-            plot_line(self._segments)
-
     def to_csv(self, path, **kwargs):
         """Writes Table to a comma-separated values (csv) file.
 
@@ -359,12 +578,7 @@ class Table(object):
             Output filepath.
 
         """
-        kw = {
+        kw = {"encoding": "utf-8", "index": False, "header": False, "quoting": 1}
-            'encoding': 'utf-8',
-            'index': False,
-            'header': False,
-            'quoting': 1
-        }
         kw.update(kwargs)
         self.df.to_csv(path, **kw)
 
@@ -379,12 +593,10 @@ class Table(object):
             Output filepath.
 
         """
-        kw = {
+        kw = {"orient": "records"}
-            'orient': 'records'
-        }
         kw.update(kwargs)
         json_string = self.df.to_json(**kw)
-        with open(path, 'w') as f:
+        with open(path, "w") as f:
             f.write(json_string)
 
     def to_excel(self, path, **kwargs):
@@ -399,8 +611,8 @@ class Table(object):
 
         """
         kw = {
-            'sheet_name': 'page-{}-table-{}'.format(self.page, self.order),
+            "sheet_name": f"page-{self.page}-table-{self.order}",
-            'encoding': 'utf-8'
+            "encoding": "utf-8",
         }
         kw.update(kwargs)
         writer = pd.ExcelWriter(path)
@@ -419,9 +631,28 @@ class Table(object):
 
         """
         html_string = self.df.to_html(**kwargs)
-        with open(path, 'w') as f:
+        with open(path, "w") as f:
             f.write(html_string)
 
+    def to_sqlite(self, path, **kwargs):
+        """Writes Table to sqlite database.
+
+        For kwargs, check :meth:`pandas.DataFrame.to_sql`.
+
+        Parameters
+        ----------
+        path : str
+            Output filepath.
+
+        """
+        kw = {"if_exists": "replace", "index": False}
+        kw.update(kwargs)
+        conn = sqlite3.connect(path)
+        table_name = f"page-{self.page}-table-{self.order}"
+        self.df.to_sql(table_name, conn, **kw)
+        conn.commit()
+        conn.close()
+
 
 class TableList(object):
     """Defines a list of camelot.core.Table objects. Each table can
@@ -433,12 +664,12 @@ class TableList(object):
         Number of tables in the list.
 
     """
+
     def __init__(self, tables):
         self._tables = tables
 
     def __repr__(self):
-        return '<{} n={}>'.format(
+        return f"<{self.__class__.__name__} n={self.n}>"
-            self.__class__.__name__, self.n)
 
     def __len__(self):
         return len(self._tables)
@@ -448,37 +679,35 @@ class TableList(object):
 
     @staticmethod
     def _format_func(table, f):
-        return getattr(table, 'to_{}'.format(f))
+        return getattr(table, f"to_{f}")
 
     @property
     def n(self):
         return len(self)
 
     def _write_file(self, f=None, **kwargs):
-        dirname = kwargs.get('dirname')
+        dirname = kwargs.get("dirname")
-        root = kwargs.get('root')
+        root = kwargs.get("root")
-        ext = kwargs.get('ext')
+        ext = kwargs.get("ext")
         for table in self._tables:
-            filename = os.path.join('{}-page-{}-table-{}{}'.format(
+            filename = f"{root}-page-{table.page}-table-{table.order}{ext}"
-                                    root, table.page, table.order, ext))
             filepath = os.path.join(dirname, filename)
             to_format = self._format_func(table, f)
             to_format(filepath)
 
     def _compress_dir(self, **kwargs):
-        path = kwargs.get('path')
+        path = kwargs.get("path")
-        dirname = kwargs.get('dirname')
+        dirname = kwargs.get("dirname")
-        root = kwargs.get('root')
+        root = kwargs.get("root")
-        ext = kwargs.get('ext')
+        ext = kwargs.get("ext")
-        zipname = os.path.join(os.path.dirname(path), root) + '.zip'
+        zipname = os.path.join(os.path.dirname(path), root) + ".zip"
-        with zipfile.ZipFile(zipname, 'w', allowZip64=True) as z:
+        with zipfile.ZipFile(zipname, "w", allowZip64=True) as z:
             for table in self._tables:
-                filename = os.path.join('{}-page-{}-table-{}{}'.format(
+                filename = f"{root}-page-{table.page}-table-{table.order}{ext}"
-                                        root, table.page, table.order, ext))
                 filepath = os.path.join(dirname, filename)
                 z.write(filepath, os.path.basename(filepath))
 
-    def export(self, path, f='csv', compress=False):
+    def export(self, path, f="csv", compress=False):
         """Exports the list of tables to specified file format.
 
         Parameters
@@ -486,7 +715,7 @@ class TableList(object):
         path : str
             Output filepath.
         f : str
-            File format. Can be csv, json, excel and html.
+            File format. Can be csv, json, excel, html and sqlite.
         compress : bool
             Whether or not to add files to a ZIP archive.
 
@@ -497,25 +726,28 @@ class TableList(object):
         if compress:
             dirname = tempfile.mkdtemp()
 
-        kwargs = {
+        kwargs = {"path": path, "dirname": dirname, "root": root, "ext": ext}
-            'path': path,
-            'dirname': dirname,
-            'root': root,
-            'ext': ext
-        }
 
-        if f in ['csv', 'json', 'html']:
+        if f in ["csv", "json", "html"]:
             self._write_file(f=f, **kwargs)
             if compress:
                 self._compress_dir(**kwargs)
-        elif f == 'excel':
+        elif f == "excel":
             filepath = os.path.join(dirname, basename)
             writer = pd.ExcelWriter(filepath)
             for table in self._tables:
-                sheet_name = 'page-{}-table-{}'.format(table.page, table.order)
+                sheet_name = f"page-{table.page}-table-{table.order}"
-                table.df.to_excel(writer, sheet_name=sheet_name, encoding='utf-8')
+                table.df.to_excel(writer, sheet_name=sheet_name, encoding="utf-8")
             writer.save()
             if compress:
-                zipname = os.path.join(os.path.dirname(path), root) + '.zip'
+                zipname = os.path.join(os.path.dirname(path), root) + ".zip"
-                with zipfile.ZipFile(zipname, 'w', allowZip64=True) as z:
+                with zipfile.ZipFile(zipname, "w", allowZip64=True) as z:
+                    z.write(filepath, os.path.basename(filepath))
+        elif f == "sqlite":
+            filepath = os.path.join(dirname, basename)
+            for table in self._tables:
+                table.to_sqlite(filepath)
+            if compress:
+                zipname = os.path.join(os.path.dirname(path), root) + ".zip"
+                with zipfile.ZipFile(zipname, "w", allowZip64=True) as z:
                     z.write(filepath, os.path.basename(filepath))

camelot/ext/ghostscript/COPYING

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<http://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<http://www.gnu.org/philosophy/why-not-lgpl.html>.

camelot/ext/ghostscript/__init__.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+ghostscript - A Python interface for the Ghostscript interpreter C-API
+"""
+#
+# Modifications 2018 by Vinayak Mehta <vmehta94@gmail.com>
+# Copyright 2010-2018 by Hartmut Goebel <h.goebel@crazy-compilers.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+from . import _gsprint as gs
+
+
+__author__ = "Hartmut Goebel <h.goebel@crazy-compilers.com>"
+__copyright__ = "Copyright 2010-2018 by Hartmut Goebel <h.goebel@crazy-compilers.com>"
+__license__ = "GNU General Public License version 3 (GPL v3)"
+__version__ = "0.6"
+
+
+class __Ghostscript(object):
+    def __init__(self, instance, args, stdin=None, stdout=None, stderr=None):
+        self._initialized = False
+        self._callbacks = None
+        if stdin or stdout or stderr:
+            self.set_stdio(stdin, stdout, stderr)
+        rc = gs.init_with_args(instance, args)
+        self._initialized = True
+        if rc == gs.e_Quit:
+            self.exit()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.exit()
+
+    def set_stdio(self, stdin=None, stdout=None, stderr=None):
+        """Set stdin, stdout and stderr of the ghostscript interpreter.
+
+        The ``stdin`` stream has to support the ``readline()``
+        interface. The ``stdout`` and ``stderr`` streams have to
+        support the ``write()`` and ``flush()`` interface.
+
+        Please note that this does not affect the input- and output-
+        streams of the devices. Esp. setting stdout does not allow
+        catching the devise-output even when using ``-sOutputFile=-``.
+
+        """
+        global __instance__
+        self._callbacks = (
+            stdin and gs._wrap_stdin(stdin) or None,
+            stdout and gs._wrap_stdout(stdout) or None,
+            stderr and gs._wrap_stderr(stderr) or None,
+        )
+        gs.set_stdio(__instance__, *self._callbacks)
+
+    def __del__(self):
+        self.exit()
+
+    def exit(self):
+        global __instance__
+        if self._initialized:
+            if __instance__ is not None:
+                gs.exit(__instance__)
+                gs.delete_instance(__instance__)
+                __instance__ = None
+            self._initialized = False
+
+
+def Ghostscript(*args, **kwargs):
+    """Factory function for setting up a Ghostscript instance
+    """
+    global __instance__
+    # Ghostscript only supports a single instance
+    if __instance__ is None:
+        __instance__ = gs.new_instance()
+    return __Ghostscript(
+        __instance__,
+        args,
+        stdin=kwargs.get("stdin", None),
+        stdout=kwargs.get("stdout", None),
+        stderr=kwargs.get("stderr", None),
+    )
+
+
+__instance__ = None

camelot/ext/ghostscript/_gsprint.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+ghostscript._gsprint - A low-level interface to the Ghostscript C-API using ctypes
+"""
+#
+# Modifications 2018 by Vinayak Mehta <vmehta94@gmail.com>
+# Copyright 2010-2018 by Hartmut Goebel <h.goebel@crazy-compilers.com>
+#
+# Display_callback Structure by Lasse Fister <commander@graphicore.de> in 2013
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+import sys
+from ctypes import *
+
+
+# base/gserrors.h
+#
+# Internal code for a normal exit when usage info is displayed.
+# This allows Window versions of Ghostscript to pause until
+# the message can be read.
+#
+e_Info = -110
+
+#
+# Internal code for the .quit operator.
+# The real quit code is an integer on the operand stack.
+# gs_interpret returns this only for a .quit with a zero exit code.
+#
+e_Quit = -101
+
+__author__ = "Hartmut Goebel <h.goebel@crazy-compilers.com>"
+__copyright__ = "Copyright 2010-2018 by Hartmut Goebel <h.goebel@crazy-compilers.com>"
+__license__ = "GNU General Public License version 3 (GPL v3)"
+__version__ = "0.6"
+
+gs_main_instance = c_void_p
+display_callback = c_void_p
+
+# https://www.ghostscript.com/doc/current/API.htm
+
+
+class GhostscriptError(Exception):
+    def __init__(self, ecode):
+        self.code = ecode
+
+
+def new_instance():
+    """Create a new instance of Ghostscript
+
+    This instance is passed to most other API functions.
+    """
+    # :todo: The caller_handle will be provided to callback functions.
+    display_callback = None
+    instance = gs_main_instance()
+    rc = libgs.gsapi_new_instance(pointer(instance), display_callback)
+    if rc != 0:
+        raise GhostscriptError(rc)
+    return instance
+
+
+def delete_instance(instance):
+    """Destroy an instance of Ghostscript
+
+    Before you call this, Ghostscript must have finished.
+    If Ghostscript has been initialised, you must call exit()
+    before delete_instance()
+    """
+    return libgs.gsapi_delete_instance(instance)
+
+
+if sys.platform == "win32":
+    c_stdstream_call_t = WINFUNCTYPE(c_int, gs_main_instance, POINTER(c_char), c_int)
+else:
+    c_stdstream_call_t = CFUNCTYPE(c_int, gs_main_instance, POINTER(c_char), c_int)
+
+
+def _wrap_stdin(infp):
+    """Wrap a filehandle into a C function to be used as `stdin` callback
+    for ``set_stdio``. The filehandle has to support the readline() method.
+    """
+
+    def _wrap(instance, dest, count):
+        try:
+            data = infp.readline(count)
+        except:
+            count = -1
+        else:
+            if not data:
+                count = 0
+            else:
+                count = len(data)
+                memmove(dest, c_char_p(data), count)
+        return count
+
+    return c_stdstream_call_t(_wrap)
+
+
+def _wrap_stdout(outfp):
+    """Wrap a filehandle into a C function to be used as `stdout` or
+    `stderr` callback for ``set_stdio``. The filehandle has to support the
+    write() and flush() methods.
+    """
+
+    def _wrap(instance, str, count):
+        outfp.write(str[:count])
+        outfp.flush()
+        return count
+
+    return c_stdstream_call_t(_wrap)
+
+
+_wrap_stderr = _wrap_stdout
+
+
+def set_stdio(instance, stdin, stdout, stderr):
+    """Set the callback functions for stdio.
+
+    ``stdin``, ``stdout`` and ``stderr`` have to be ``ctypes``
+    callback functions matching the ``_gsprint.c_stdstream_call_t``
+    prototype. You may want to use _wrap_* to wrap file handles.
+
+    Note 1: This function only changes stdio of the Postscript
+    interpreter, not that of the devices.
+
+    Note 2: Make sure you keep references to C function objects
+    as long as they are used from C code. Otherwise they may be
+    garbage collected, crashing your program when a callback is made.
+
+    The ``stdin`` callback function should return the number of
+    characters read, `0` for EOF, or `-1` for error. The `stdout` and
+    `stderr` callback functions should return the number of characters
+    written.
+
+    You may pass ``None`` for any of stdin, stdout or stderr , in which
+    case the system stdin, stdout resp. stderr will be used.
+    """
+    rc = libgs.gsapi_set_stdio(instance, stdin, stdout, stderr)
+    if rc not in (0, e_Quit, e_Info):
+        raise GhostscriptError(rc)
+    return rc
+
+
+def init_with_args(instance, argv):
+    """Initialise the interpreter
+
+    1. If quit or EOF occur during init_with_args(), the return value
+       will be e_Quit. This is not an error. You must call exit() and
+       must not call any other functions.
+
+    2. If usage info should be displayed, the return value will be
+       e_Info which is not an error. Do not call exit().
+
+    3. Under normal conditions this returns 0. You would then call one
+       or more run_*() functions and then finish with exit()
+    """
+    ArgArray = c_char_p * len(argv)
+    c_argv = ArgArray(*argv)
+    rc = libgs.gsapi_init_with_args(instance, len(argv), c_argv)
+    if rc not in (0, e_Quit, e_Info):
+        raise GhostscriptError(rc)
+    return rc
+
+
+def exit(instance):
+    """Exit the interpreter
+
+    This must be called on shutdown if init_with_args() has been
+    called, and just before delete_instance()
+    """
+    rc = libgs.gsapi_exit(instance)
+    if rc != 0:
+        raise GhostscriptError(rc)
+    return rc
+
+
+def __win32_finddll():
+    try:
+        import winreg
+    except ImportError:
+        # assume Python 2
+        from _winreg import (
+            OpenKey,
+            CloseKey,
+            EnumKey,
+            QueryValueEx,
+            QueryInfoKey,
+            HKEY_LOCAL_MACHINE,
+        )
+    else:
+        from winreg import (
+            OpenKey,
+            CloseKey,
+            EnumKey,
+            QueryValueEx,
+            QueryInfoKey,
+            HKEY_LOCAL_MACHINE,
+        )
+
+    from distutils.version import LooseVersion
+    import os
+
+    dlls = []
+    # Look up different variants of Ghostscript and take the highest
+    # version for which the DLL is to be found in the filesystem.
+    for key_name in (
+        "AFPL Ghostscript",
+        "Aladdin Ghostscript",
+        "GNU Ghostscript",
+        "GPL Ghostscript",
+    ):
+        try:
+            k1 = OpenKey(HKEY_LOCAL_MACHINE, "Software\\%s" % key_name)
+            for num in range(0, QueryInfoKey(k1)[0]):
+                version = EnumKey(k1, num)
+                try:
+                    k2 = OpenKey(k1, version)
+                    dll_path = QueryValueEx(k2, "GS_DLL")[0]
+                    CloseKey(k2)
+                    if os.path.exists(dll_path):
+                        dlls.append((LooseVersion(version), dll_path))
+                except WindowsError:
+                    pass
+            CloseKey(k1)
+        except WindowsError:
+            pass
+    if dlls:
+        dlls.sort()
+        return dlls[-1][-1]
+    else:
+        return None
+
+
+if sys.platform == "win32":
+    libgs = __win32_finddll()
+    if not libgs:
+        import ctypes.util
+
+        libgs = ctypes.util.find_library(
+            "".join(("gsdll", str(ctypes.sizeof(ctypes.c_voidp) * 8), ".dll"))
+        )  # finds in %PATH%
+    if not libgs:
+        raise RuntimeError("Please make sure that Ghostscript is installed")
+    libgs = windll.LoadLibrary(libgs)
+else:
+    try:
+        libgs = cdll.LoadLibrary("libgs.so")
+    except OSError:
+        # shared object file not found
+        import ctypes.util
+
+        libgs = ctypes.util.find_library("gs")
+        if not libgs:
+            raise RuntimeError("Please make sure that Ghostscript is installed")
+        libgs = cdll.LoadLibrary(libgs)
+
+del __win32_finddll

camelot/handlers.py

@@ -7,8 +7,14 @@ from PyPDF2 import PdfFileReader, PdfFileWriter
 
 from .core import TableList
 from .parsers import Stream, Lattice
-from .utils import (TemporaryDirectory, get_page_layout, get_text_objects,
+from .utils import (
-                    get_rotation)
+    TemporaryDirectory,
+    get_page_layout,
+    get_text_objects,
+    get_rotation,
+    is_url,
+    download_url,
+)
 
 
 class PDFHandler(object):
@@ -18,37 +24,41 @@ class PDFHandler(object):
 
     Parameters
     ----------
-    filename : str
+    filepath : str
-        Path to PDF file.
+        Filepath or URL of the PDF file.
     pages : str, optional (default: '1')
         Comma-separated page numbers.
-        Example: '1,3,4' or '1,4-end'.
+        Example: '1,3,4' or '1,4-end' or 'all'.
     password : str, optional (default: None)
         Password for decryption.
 
     """
-    def __init__(self, filename, pages='1', password=None):
+
-        self.filename = filename
+    def __init__(self, filepath, pages="1", password=None):
-        if not filename.lower().endswith('.pdf'):
+        if is_url(filepath):
+            filepath = download_url(filepath)
+        self.filepath = filepath
+        if not filepath.lower().endswith(".pdf"):
             raise NotImplementedError("File format not supported")
-        self.pages = self._get_pages(self.filename, pages)
+
         if password is None:
-            self.password = ''
+            self.password = ""
         else:
             self.password = password
             if sys.version_info[0] < 3:
-                self.password = self.password.encode('ascii')
+                self.password = self.password.encode("ascii")
+        self.pages = self._get_pages(self.filepath, pages)
 
-    def _get_pages(self, filename, pages):
+    def _get_pages(self, filepath, pages):
         """Converts pages string to list of ints.
 
         Parameters
         ----------
-        filename : str
+        filepath : str
-            Path to PDF file.
+            Filepath or URL of the PDF file.
         pages : str, optional (default: '1')
             Comma-separated page numbers.
-            Example: 1,3,4 or 1,4-end.
+            Example: '1,3,4' or '1,4-end' or 'all'.
 
         Returns
         -------
@@ -57,75 +67,77 @@ class PDFHandler(object):
 
         """
         page_numbers = []
-        if pages == '1':
+        if pages == "1":
-            page_numbers.append({'start': 1, 'end': 1})
+            page_numbers.append({"start": 1, "end": 1})
         else:
-            infile = PdfFileReader(open(filename, 'rb'), strict=False)
+            infile = PdfFileReader(open(filepath, "rb"), strict=False)
             if infile.isEncrypted:
                 infile.decrypt(self.password)
-            if pages == 'all':
+            if pages == "all":
-                page_numbers.append({'start': 1, 'end': infile.getNumPages()})
+                page_numbers.append({"start": 1, "end": infile.getNumPages()})
             else:
-                for r in pages.split(','):
+                for r in pages.split(","):
-                    if '-' in r:
+                    if "-" in r:
-                        a, b = r.split('-')
+                        a, b = r.split("-")
-                        if b == 'end':
+                        if b == "end":
                             b = infile.getNumPages()
-                        page_numbers.append({'start': int(a), 'end': int(b)})
+                        page_numbers.append({"start": int(a), "end": int(b)})
                     else:
-                        page_numbers.append({'start': int(r), 'end': int(r)})
+                        page_numbers.append({"start": int(r), "end": int(r)})
         P = []
         for p in page_numbers:
-            P.extend(range(p['start'], p['end'] + 1))
+            P.extend(range(p["start"], p["end"] + 1))
         return sorted(set(P))
 
-    def _save_page(self, filename, page, temp):
+    def _save_page(self, filepath, page, temp):
         """Saves specified page from PDF into a temporary directory.
 
         Parameters
         ----------
-        filename : str
+        filepath : str
-            Path to PDF file.
+            Filepath or URL of the PDF file.
         page : int
             Page number.
         temp : str
             Tmp directory.
 
         """
-        with open(filename, 'rb') as fileobj:
+        with open(filepath, "rb") as fileobj:
             infile = PdfFileReader(fileobj, strict=False)
             if infile.isEncrypted:
                 infile.decrypt(self.password)
-            fpath = os.path.join(temp, 'page-{0}.pdf'.format(page))
+            fpath = os.path.join(temp, f"page-{page}.pdf")
             froot, fext = os.path.splitext(fpath)
             p = infile.getPage(page - 1)
             outfile = PdfFileWriter()
             outfile.addPage(p)
-            with open(fpath, 'wb') as f:
+            with open(fpath, "wb") as f:
                 outfile.write(f)
             layout, dim = get_page_layout(fpath)
             # fix rotated PDF
-            lttextlh = get_text_objects(layout, ltype="lh")
+            chars = get_text_objects(layout, ltype="char")
-            lttextlv = get_text_objects(layout, ltype="lv")
+            horizontal_text = get_text_objects(layout, ltype="horizontal_text")
-            ltchar = get_text_objects(layout, ltype="char")
+            vertical_text = get_text_objects(layout, ltype="vertical_text")
-            rotation = get_rotation(lttextlh, lttextlv, ltchar)
+            rotation = get_rotation(chars, horizontal_text, vertical_text)
-            if rotation != '':
+            if rotation != "":
-                fpath_new = ''.join([froot.replace('page', 'p'), '_rotated', fext])
+                fpath_new = "".join([froot.replace("page", "p"), "_rotated", fext])
                 os.rename(fpath, fpath_new)
-                infile = PdfFileReader(open(fpath_new, 'rb'), strict=False)
+                infile = PdfFileReader(open(fpath_new, "rb"), strict=False)
                 if infile.isEncrypted:
                     infile.decrypt(self.password)
                 outfile = PdfFileWriter()
                 p = infile.getPage(0)
-                if rotation == 'anticlockwise':
+                if rotation == "anticlockwise":
                     p.rotateClockwise(90)
-                elif rotation == 'clockwise':
+                elif rotation == "clockwise":
                     p.rotateCounterClockwise(90)
                 outfile.addPage(p)
-                with open(fpath, 'wb') as f:
+                with open(fpath, "wb") as f:
                     outfile.write(f)
 
-    def parse(self, flavor='lattice', **kwargs):
+    def parse(
+        self, flavor="lattice", suppress_stdout=False, layout_kwargs={}, **kwargs
+    ):
         """Extracts tables by calling parser.get_tables on all single
         page PDFs.
 
@@ -134,6 +146,10 @@ class PDFHandler(object):
         flavor : str (default: 'lattice')
             The parsing method to use ('lattice' or 'stream').
             Lattice is used by default.
+        suppress_stdout : str (default: False)
+            Suppress logs and warnings.
+        layout_kwargs : dict, optional (default: {})
+            A dict of `pdfminer.layout.LAParams <https://github.com/euske/pdfminer/blob/master/pdfminer/layout.py#L33>`_ kwargs.
         kwargs : dict
             See camelot.read_pdf kwargs.
 
@@ -141,19 +157,19 @@ class PDFHandler(object):
         -------
         tables : camelot.core.TableList
             List of tables found in PDF.
-        geometry : camelot.core.GeometryList
-            List of geometry objects (contours, lines, joints) found
-            in PDF.
 
         """
         tables = []
         with TemporaryDirectory() as tempdir:
             for p in self.pages:
-                self._save_page(self.filename, p, tempdir)
+                self._save_page(self.filepath, p, tempdir)
-            pages = [os.path.join(tempdir, 'page-{0}.pdf'.format(p))
+            pages = [
-                     for p in self.pages]
+                os.path.join(tempdir, f"page-{p}.pdf") for p in self.pages
-            parser = Lattice(**kwargs) if flavor == 'lattice' else Stream(**kwargs)
+            ]
+            parser = Lattice(**kwargs) if flavor == "lattice" else Stream(**kwargs)
             for p in pages:
-                t = parser.extract_tables(p)
+                t = parser.extract_tables(
+                    p, suppress_stdout=suppress_stdout, layout_kwargs=layout_kwargs
+                )
                 tables.extend(t)
-        return TableList(tables)
+        return TableList(sorted(tables))

camelot/image_processing.py

@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
 
-from __future__ import division
-
 import cv2
 import numpy as np
 
@@ -39,16 +37,23 @@ def adaptive_threshold(imagename, process_background=False, blocksize=15, c=-2):
 
     if process_background:
         threshold = cv2.adaptiveThreshold(
-            gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
+            gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, blocksize, c
-            cv2.THRESH_BINARY, blocksize, c)
+        )
     else:
         threshold = cv2.adaptiveThreshold(
-            np.invert(gray), 255,
+            np.invert(gray),
-            cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, blocksize, c)
+            255,
+            cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
+            cv2.THRESH_BINARY,
+            blocksize,
+            c,
+        )
     return img, threshold
 
 
-def find_lines(threshold, direction='horizontal', line_size_scaling=15, iterations=0):
+def find_lines(
+    threshold, regions=None, direction="horizontal", line_scale=15, iterations=0
+):
     """Finds horizontal and vertical lines by applying morphological
     transformations on an image.
 
@@ -56,9 +61,13 @@ def find_lines(threshold, direction='horizontal', line_size_scaling=15, iteratio
     ----------
     threshold : object
         numpy.ndarray representing the thresholded image.
+    regions : list, optional (default: None)
+        List of page regions that may contain tables of the form x1,y1,x2,y2
+        where (x1, y1) -> left-top and (x2, y2) -> right-bottom
+        in image coordinate space.
     direction : string, optional (default: 'horizontal')
         Specifies whether to find vertical or horizontal lines.
-    line_size_scaling : int, optional (default: 15)
+    line_scale : int, optional (default: 15)
         Factor by which the page dimensions will be divided to get
         smallest length of lines that should be detected.
 
@@ -82,15 +91,21 @@ def find_lines(threshold, direction='horizontal', line_size_scaling=15, iteratio
     """
     lines = []
 
-    if direction == 'vertical':
+    if direction == "vertical":
-        size = threshold.shape[0] // line_size_scaling
+        size = threshold.shape[0] // line_scale
         el = cv2.getStructuringElement(cv2.MORPH_RECT, (1, size))
-    elif direction == 'horizontal':
+    elif direction == "horizontal":
-        size = threshold.shape[1] // line_size_scaling
+        size = threshold.shape[1] // line_scale
         el = cv2.getStructuringElement(cv2.MORPH_RECT, (size, 1))
     elif direction is None:
-        raise ValueError("Specify direction as either 'vertical' or"
+        raise ValueError("Specify direction as either 'vertical' or 'horizontal'")
-                         " 'horizontal'")
+
+    if regions is not None:
+        region_mask = np.zeros(threshold.shape)
+        for region in regions:
+            x, y, w, h = region
+            region_mask[y : y + h, x : x + w] = 1
+        threshold = np.multiply(threshold, region_mask)
 
     threshold = cv2.erode(threshold, el)
     threshold = cv2.dilate(threshold, el)
@@ -98,25 +113,27 @@ def find_lines(threshold, direction='horizontal', line_size_scaling=15, iteratio
 
     try:
         _, contours, _ = cv2.findContours(
-            threshold, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+            threshold.astype(np.uint8), cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
+        )
     except ValueError:
         # for opencv backward compatibility
         contours, _ = cv2.findContours(
-            threshold, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+            threshold.astype(np.uint8), cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
+        )
 
     for c in contours:
         x, y, w, h = cv2.boundingRect(c)
         x1, x2 = x, x + w
         y1, y2 = y, y + h
-        if direction == 'vertical':
+        if direction == "vertical":
             lines.append(((x1 + x2) // 2, y2, (x1 + x2) // 2, y1))
-        elif direction == 'horizontal':
+        elif direction == "horizontal":
             lines.append((x1, (y1 + y2) // 2, x2, (y1 + y2) // 2))
 
     return dmask, lines
 
 
-def find_table_contours(vertical, horizontal):
+def find_contours(vertical, horizontal):
     """Finds table boundaries using OpenCV's findContours.
 
     Parameters
@@ -138,11 +155,14 @@ def find_table_contours(vertical, horizontal):
 
     try:
         __, contours, __ = cv2.findContours(
-            mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+            mask.astype(np.uint8), cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
+        )
     except ValueError:
         # for opencv backward compatibility
         contours, __ = cv2.findContours(
-            mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+            mask.astype(np.uint8), cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
+        )
+    # sort in reverse based on contour area and use first 10 contours
     contours = sorted(contours, key=cv2.contourArea, reverse=True)[:10]
 
     cont = []
@@ -153,7 +173,7 @@ def find_table_contours(vertical, horizontal):
     return cont
 
 
-def find_table_joints(contours, vertical, horizontal):
+def find_joints(contours, vertical, horizontal):
     """Finds joints/intersections present inside each table boundary.
 
     Parameters
@@ -176,18 +196,20 @@ def find_table_joints(contours, vertical, horizontal):
         and (x2, y2) -> rt in image coordinate space.
 
     """
-    joints = np.bitwise_and(vertical, horizontal)
+    joints = np.multiply(vertical, horizontal)
     tables = {}
     for c in contours:
         x, y, w, h = c
         roi = joints[y : y + h, x : x + w]
         try:
             __, jc, __ = cv2.findContours(
-                roi, cv2.RETR_CCOMP, cv2.CHAIN_APPROX_SIMPLE)
+                roi.astype(np.uint8), cv2.RETR_CCOMP, cv2.CHAIN_APPROX_SIMPLE
+            )
         except ValueError:
             # for opencv backward compatibility
             jc, __ = cv2.findContours(
-                roi, cv2.RETR_CCOMP, cv2.CHAIN_APPROX_SIMPLE)
+                roi.astype(np.uint8), cv2.RETR_CCOMP, cv2.CHAIN_APPROX_SIMPLE
+            )
         if len(jc) <= 4:  # remove contours with less than 4 joints
             continue
         joint_coords = []

camelot/io.py

@@ -1,12 +1,20 @@
 # -*- coding: utf-8 -*-
+
 import warnings
 
 from .handlers import PDFHandler
 from .utils import validate_input, remove_extra
 
 
-def read_pdf(filepath, pages='1', password=None, flavor='lattice',
+def read_pdf(
-             suppress_warnings=False, **kwargs):
+    filepath,
+    pages="1",
+    password=None,
+    flavor="lattice",
+    suppress_stdout=False,
+    layout_kwargs={},
+    **kwargs
+):
     """Read PDF and return extracted tables.
 
     Note: kwargs annotated with ^ can only be used with flavor='stream'
@@ -15,17 +23,19 @@ def read_pdf(filepath, pages='1', password=None, flavor='lattice',
     Parameters
     ----------
     filepath : str
-        Path to PDF file.
+        Filepath or URL of the PDF file.
     pages : str, optional (default: '1')
         Comma-separated page numbers.
-        Example: '1,3,4' or '1,4-end'.
+        Example: '1,3,4' or '1,4-end' or 'all'.
     password : str, optional (default: None)
         Password for decryption.
     flavor : str (default: 'lattice')
         The parsing method to use ('lattice' or 'stream').
         Lattice is used by default.
-    suppress_warnings : bool, optional (default: False)
+    suppress_stdout : bool, optional (default: True)
-        Prevent warnings from being emitted by Camelot.
+        Print all logs and warnings.
+    layout_kwargs : dict, optional (default: {})
+        A dict of `pdfminer.layout.LAParams <https://github.com/euske/pdfminer/blob/master/pdfminer/layout.py#L33>`_ kwargs.
     table_areas : list, optional (default: None)
         List of table area strings of the form x1,y1,x2,y2
         where (x1, y1) -> left-top and (x2, y2) -> right-bottom
@@ -38,15 +48,18 @@ def read_pdf(filepath, pages='1', password=None, flavor='lattice',
     flag_size : bool, optional (default: False)
         Flag text based on font size. Useful to detect
         super/subscripts. Adds <s></s> around flagged text.
-    row_close_tol^ : int, optional (default: 2)
+    strip_text : str, optional (default: '')
+        Characters that should be stripped from a string before
+        assigning it to a cell.
+    row_tol^ : int, optional (default: 2)
         Tolerance parameter used to combine text vertically,
         to generate rows.
-    col_close_tol^ : int, optional (default: 0)
+    column_tol^ : int, optional (default: 0)
         Tolerance parameter used to combine text horizontally,
         to generate columns.
     process_background* : bool, optional (default: False)
         Process background lines.
-    line_size_scaling* : int, optional (default: 15)
+    line_scale* : int, optional (default: 15)
         Line size scaling factor. The larger the value the smaller
         the detected lines. Making it very large will lead to text
         being detected as lines.
@@ -57,10 +70,10 @@ def read_pdf(filepath, pages='1', password=None, flavor='lattice',
     shift_text* : list, optional (default: ['l', 't'])
         {'l', 'r', 't', 'b'}
         Direction in which text in a spanning cell will flow.
-    line_close_tol* : int, optional (default: 2)
+    line_tol* : int, optional (default: 2)
         Tolerance parameter used to merge close vertical and horizontal
         lines.
-    joint_close_tol* : int, optional (default: 2)
+    joint_tol* : int, optional (default: 2)
         Tolerance parameter used to decide whether the detected lines
         and points lie close to each other.
     threshold_blocksize* : int, optional (default: 15)
@@ -77,26 +90,30 @@ def read_pdf(filepath, pages='1', password=None, flavor='lattice',
         Number of times for erosion/dilation is applied.
 
         For more information, refer `OpenCV's dilate <https://docs.opencv.org/2.4/modules/imgproc/doc/filtering.html#dilate>`_.
-    margins : tuple
+    resolution* : int, optional (default: 300)
-        PDFMiner char_margin, line_margin and word_margin.
+        Resolution used for PDF to PNG conversion.
-
-        For more information, refer `PDFMiner docs <https://euske.github.io/pdfminer/>`_.
 
     Returns
     -------
     tables : camelot.core.TableList
 
     """
-    if flavor not in ['lattice', 'stream']:
+    if flavor not in ["lattice", "stream"]:
-        raise NotImplementedError("Unknown flavor specified."
+        raise NotImplementedError(
-                                  " Use either 'lattice' or 'stream'")
+            "Unknown flavor specified." " Use either 'lattice' or 'stream'"
+        )
 
     with warnings.catch_warnings():
-        if suppress_warnings:
+        if suppress_stdout:
             warnings.simplefilter("ignore")
 
         validate_input(kwargs, flavor=flavor)
         p = PDFHandler(filepath, pages=pages, password=password)
         kwargs = remove_extra(kwargs, flavor=flavor)
-        tables = p.parse(flavor=flavor, **kwargs)
+        tables = p.parse(
+            flavor=flavor,
+            suppress_stdout=suppress_stdout,
+            layout_kwargs=layout_kwargs,
+            **kwargs
+        )
         return tables

camelot/parsers/base.py

@@ -8,14 +8,13 @@ from ..utils import get_page_layout, get_text_objects
 class BaseParser(object):
     """Defines a base parser.
     """
-    def _generate_layout(self, filename):
+
+    def _generate_layout(self, filename, layout_kwargs):
         self.filename = filename
-        self.layout, self.dimensions = get_page_layout(
+        self.layout_kwargs = layout_kwargs
-            self.filename,
+        self.layout, self.dimensions = get_page_layout(filename, **layout_kwargs)
-            char_margin=self.char_margin,
+        self.images = get_text_objects(self.layout, ltype="image")
-            line_margin=self.line_margin,
+        self.horizontal_text = get_text_objects(self.layout, ltype="horizontal_text")
-            word_margin=self.word_margin)
+        self.vertical_text = get_text_objects(self.layout, ltype="vertical_text")
-        self.horizontal_text = get_text_objects(self.layout, ltype="lh")
-        self.vertical_text = get_text_objects(self.layout, ltype="lv")
         self.pdf_width, self.pdf_height = self.dimensions
         self.rootname, __ = os.path.splitext(self.filename)

camelot/parsers/lattice.py

@@ -1,8 +1,9 @@
 # -*- coding: utf-8 -*-
 
-from __future__ import division
 import os
+import sys
 import copy
+import locale
 import logging
 import warnings
 import subprocess
@@ -12,14 +13,25 @@ import pandas as pd
 
 from .base import BaseParser
 from ..core import Table
-from ..utils import (scale_image, scale_pdf, segments_in_bbox, text_in_bbox,
+from ..utils import (
-                     merge_close_lines, get_table_index, compute_accuracy,
+    scale_image,
-                     compute_whitespace)
+    scale_pdf,
-from ..image_processing import (adaptive_threshold, find_lines,
+    segments_in_bbox,
-                                find_table_contours, find_table_joints)
+    text_in_bbox,
+    merge_close_lines,
+    get_table_index,
+    compute_accuracy,
+    compute_whitespace,
+)
+from ..image_processing import (
+    adaptive_threshold,
+    find_lines,
+    find_contours,
+    find_joints,
+)
 
 
-logger = logging.getLogger('camelot')
+logger = logging.getLogger("camelot")
 
 
 class Lattice(BaseParser):
@@ -28,13 +40,17 @@ class Lattice(BaseParser):
 
     Parameters
     ----------
+    table_regions : list, optional (default: None)
+        List of page regions that may contain tables of the form x1,y1,x2,y2
+        where (x1, y1) -> left-top and (x2, y2) -> right-bottom
+        in PDF coordinate space.
     table_areas : list, optional (default: None)
         List of table area strings of the form x1,y1,x2,y2
         where (x1, y1) -> left-top and (x2, y2) -> right-bottom
         in PDF coordinate space.
     process_background : bool, optional (default: False)
         Process background lines.
-    line_size_scaling : int, optional (default: 15)
+    line_scale : int, optional (default: 15)
         Line size scaling factor. The larger the value the smaller
         the detected lines. Making it very large will lead to text
         being detected as lines.
@@ -50,10 +66,13 @@ class Lattice(BaseParser):
     flag_size : bool, optional (default: False)
         Flag text based on font size. Useful to detect
         super/subscripts. Adds <s></s> around flagged text.
-    line_close_tol : int, optional (default: 2)
+    strip_text : str, optional (default: '')
+        Characters that should be stripped from a string before
+        assigning it to a cell.
+    line_tol : int, optional (default: 2)
         Tolerance parameter used to merge close vertical and horizontal
         lines.
-    joint_close_tol : int, optional (default: 2)
+    joint_tol : int, optional (default: 2)
         Tolerance parameter used to decide whether the detected lines
         and points lie close to each other.
     threshold_blocksize : int, optional (default: 15)
@@ -70,30 +89,45 @@ class Lattice(BaseParser):
         Number of times for erosion/dilation is applied.
 
         For more information, refer `OpenCV's dilate <https://docs.opencv.org/2.4/modules/imgproc/doc/filtering.html#dilate>`_.
-    margins : tuple
+    resolution : int, optional (default: 300)
-        PDFMiner char_margin, line_margin and word_margin.
+        Resolution used for PDF to PNG conversion.
-
-        For more information, refer `PDFMiner docs <https://euske.github.io/pdfminer/>`_.
 
     """
-    def __init__(self, table_areas=None, process_background=False,
+
-                 line_size_scaling=15, copy_text=None, shift_text=['l', 't'],
+    def __init__(
-                 split_text=False, flag_size=False, line_close_tol=2,
+        self,
-                 joint_close_tol=2, threshold_blocksize=15, threshold_constant=-2,
+        table_regions=None,
-                 iterations=0, margins=(1.0, 0.5, 0.1), **kwargs):
+        table_areas=None,
+        process_background=False,
+        line_scale=15,
+        copy_text=None,
+        shift_text=["l", "t"],
+        split_text=False,
+        flag_size=False,
+        strip_text="",
+        line_tol=2,
+        joint_tol=2,
+        threshold_blocksize=15,
+        threshold_constant=-2,
+        iterations=0,
+        resolution=300,
+        **kwargs
+    ):
+        self.table_regions = table_regions
         self.table_areas = table_areas
         self.process_background = process_background
-        self.line_size_scaling = line_size_scaling
+        self.line_scale = line_scale
         self.copy_text = copy_text
         self.shift_text = shift_text
         self.split_text = split_text
         self.flag_size = flag_size
-        self.line_close_tol = line_close_tol
+        self.strip_text = strip_text
-        self.joint_close_tol = joint_close_tol
+        self.line_tol = line_tol
+        self.joint_tol = joint_tol
         self.threshold_blocksize = threshold_blocksize
         self.threshold_constant = threshold_constant
         self.iterations = iterations
-        self.char_margin, self.line_margin, self.word_margin = margins
+        self.resolution = resolution
 
     @staticmethod
     def _reduce_index(t, idx, shift_text):
@@ -121,19 +155,19 @@ class Lattice(BaseParser):
         indices = []
         for r_idx, c_idx, text in idx:
             for d in shift_text:
-                if d == 'l':
+                if d == "l":
                     if t.cells[r_idx][c_idx].hspan:
                         while not t.cells[r_idx][c_idx].left:
                             c_idx -= 1
-                if d == 'r':
+                if d == "r":
                     if t.cells[r_idx][c_idx].hspan:
                         while not t.cells[r_idx][c_idx].right:
                             c_idx += 1
-                if d == 't':
+                if d == "t":
                     if t.cells[r_idx][c_idx].vspan:
                         while not t.cells[r_idx][c_idx].top:
                             r_idx -= 1
-                if d == 'b':
+                if d == "b":
                     if t.cells[r_idx][c_idx].vspan:
                         while not t.cells[r_idx][c_idx].bottom:
                             r_idx += 1
@@ -162,72 +196,50 @@ class Lattice(BaseParser):
             if f == "h":
                 for i in range(len(t.cells)):
                     for j in range(len(t.cells[i])):
-                        if t.cells[i][j].text.strip() == '':
+                        if t.cells[i][j].text.strip() == "":
                             if t.cells[i][j].hspan and not t.cells[i][j].left:
                                 t.cells[i][j].text = t.cells[i][j - 1].text
             elif f == "v":
                 for i in range(len(t.cells)):
                     for j in range(len(t.cells[i])):
-                        if t.cells[i][j].text.strip() == '':
+                        if t.cells[i][j].text.strip() == "":
                             if t.cells[i][j].vspan and not t.cells[i][j].top:
                                 t.cells[i][j].text = t.cells[i - 1][j].text
         return t
 
     def _generate_image(self):
-        # TODO: get rid of ghostscript #96
+        from ..ext.ghostscript import Ghostscript
-        def get_executable():
-            import platform
-            from distutils.spawn import find_executable
 
-            class GhostscriptNotFound(Exception): pass
+        self.imagename = "".join([self.rootname, ".png"])
-
+        gs_call = "-q -sDEVICE=png16m -o {} -r300 {}".format(
-            gs = None
+            self.imagename, self.filename
-            system = platform.system().lower()
+        )
-            try:
+        gs_call = gs_call.encode().split()
-                if system == 'windows':
+        null = open(os.devnull, "wb")
-                    if find_executable('gswin32c.exe'):
+        with Ghostscript(*gs_call, stdout=null) as gs:
-                        gs = 'gswin32c.exe'
+            pass
-                    elif find_executable('gswin64c.exe'):
+        null.close()
-                        gs = 'gswin64c.exe'
-                    else:
-                        raise ValueError
-                else:
-                    if find_executable('gs'):
-                        gs = 'gs'
-                    elif find_executable('gsc'):
-                        gs = 'gsc'
-                    else:
-                        raise ValueError
-                if 'ghostscript' not in subprocess.check_output(
-                        [gs, '-version']).decode('utf-8').lower():
-                    raise ValueError
-            except ValueError:
-                raise GhostscriptNotFound(
-                    'Please make sure that Ghostscript is installed'
-                    ' and available on the PATH environment variable')
-
-            return gs
-
-        self.imagename = ''.join([self.rootname, '.png'])
-        gs_call = [
-            '-q',
-            '-sDEVICE=png16m',
-            '-o',
-            self.imagename,
-            '-r600',
-            self.filename
-        ]
-        gs = get_executable()
-        gs_call.insert(0, gs)
-
-        subprocess.call(
-            gs_call, stdout=open(os.devnull, 'w'),
-            stderr=subprocess.STDOUT)
 
     def _generate_table_bbox(self):
+        def scale_areas(areas):
+            scaled_areas = []
+            for area in areas:
+                x1, y1, x2, y2 = area.split(",")
+                x1 = float(x1)
+                y1 = float(y1)
+                x2 = float(x2)
+                y2 = float(y2)
+                x1, y1, x2, y2 = scale_pdf((x1, y1, x2, y2), image_scalers)
+                scaled_areas.append((x1, y1, abs(x2 - x1), abs(y2 - y1)))
+            return scaled_areas
+
         self.image, self.threshold = adaptive_threshold(
-            self.imagename, process_background=self.process_background,
+            self.imagename,
-            blocksize=self.threshold_blocksize, c=self.threshold_constant)
+            process_background=self.process_background,
+            blocksize=self.threshold_blocksize,
+            c=self.threshold_constant,
+        )
+
         image_width = self.image.shape[1]
         image_height = self.image.shape[0]
         image_width_scaler = image_width / float(self.pdf_width)
@@ -237,85 +249,110 @@ class Lattice(BaseParser):
         image_scalers = (image_width_scaler, image_height_scaler, self.pdf_height)
         pdf_scalers = (pdf_width_scaler, pdf_height_scaler, image_height)
 
-        vertical_mask, vertical_segments = find_lines(
+        if self.table_areas is None:
-            self.threshold, direction='vertical',
+            regions = None
-            line_size_scaling=self.line_size_scaling, iterations=self.iterations)
+            if self.table_regions is not None:
-        horizontal_mask, horizontal_segments = find_lines(
+                regions = scale_areas(self.table_regions)
-            self.threshold, direction='horizontal',
-            line_size_scaling=self.line_size_scaling, iterations=self.iterations)
 
-        if self.table_areas is not None:
+            vertical_mask, vertical_segments = find_lines(
-            areas = []
+                self.threshold,
-            for area in self.table_areas:
+                regions=regions,
-                x1, y1, x2, y2 = area.split(",")
+                direction="vertical",
-                x1 = float(x1)
+                line_scale=self.line_scale,
-                y1 = float(y1)
+                iterations=self.iterations,
-                x2 = float(x2)
+            )
-                y2 = float(y2)
+            horizontal_mask, horizontal_segments = find_lines(
-                x1, y1, x2, y2 = scale_pdf((x1, y1, x2, y2), image_scalers)
+                self.threshold,
-                areas.append((x1, y1, abs(x2 - x1), abs(y2 - y1)))
+                regions=regions,
-            table_bbox = find_table_joints(areas, vertical_mask, horizontal_mask)
+                direction="horizontal",
+                line_scale=self.line_scale,
+                iterations=self.iterations,
+            )
+
+            contours = find_contours(vertical_mask, horizontal_mask)
+            table_bbox = find_joints(contours, vertical_mask, horizontal_mask)
         else:
-            contours = find_table_contours(vertical_mask, horizontal_mask)
+            vertical_mask, vertical_segments = find_lines(
-            table_bbox = find_table_joints(contours, vertical_mask, horizontal_mask)
+                self.threshold,
+                direction="vertical",
+                line_scale=self.line_scale,
+                iterations=self.iterations,
+            )
+            horizontal_mask, horizontal_segments = find_lines(
+                self.threshold,
+                direction="horizontal",
+                line_scale=self.line_scale,
+                iterations=self.iterations,
+            )
+
+            areas = scale_areas(self.table_areas)
+            table_bbox = find_joints(areas, vertical_mask, horizontal_mask)
 
         self.table_bbox_unscaled = copy.deepcopy(table_bbox)
 
         self.table_bbox, self.vertical_segments, self.horizontal_segments = scale_image(
-            table_bbox, vertical_segments, horizontal_segments, pdf_scalers)
+            table_bbox, vertical_segments, horizontal_segments, pdf_scalers
+        )
 
     def _generate_columns_and_rows(self, table_idx, tk):
         # select elements which lie within table_bbox
         t_bbox = {}
         v_s, h_s = segments_in_bbox(
-            tk, self.vertical_segments, self.horizontal_segments)
+            tk, self.vertical_segments, self.horizontal_segments
-        t_bbox['horizontal'] = text_in_bbox(tk, self.horizontal_text)
+        )
-        t_bbox['vertical'] = text_in_bbox(tk, self.vertical_text)
+        t_bbox["horizontal"] = text_in_bbox(tk, self.horizontal_text)
-        self.t_bbox = t_bbox
+        t_bbox["vertical"] = text_in_bbox(tk, self.vertical_text)
 
-        for direction in t_bbox:
+        t_bbox["horizontal"].sort(key=lambda x: (-x.y0, x.x0))
-            t_bbox[direction].sort(key=lambda x: (-x.y0, x.x0))
+        t_bbox["vertical"].sort(key=lambda x: (x.x0, -x.y0))
+
+        self.t_bbox = t_bbox
 
         cols, rows = zip(*self.table_bbox[tk])
         cols, rows = list(cols), list(rows)
         cols.extend([tk[0], tk[2]])
         rows.extend([tk[1], tk[3]])
         # sort horizontal and vertical segments
-        cols = merge_close_lines(
+        cols = merge_close_lines(sorted(cols), line_tol=self.line_tol)
-            sorted(cols), line_close_tol=self.line_close_tol)
+        rows = merge_close_lines(sorted(rows, reverse=True), line_tol=self.line_tol)
-        rows = merge_close_lines(
-            sorted(rows, reverse=True), line_close_tol=self.line_close_tol)
         # make grid using x and y coord of shortlisted rows and cols
-        cols = [(cols[i], cols[i + 1])
+        cols = [(cols[i], cols[i + 1]) for i in range(0, len(cols) - 1)]
-                for i in range(0, len(cols) - 1)]
+        rows = [(rows[i], rows[i + 1]) for i in range(0, len(rows) - 1)]
-        rows = [(rows[i], rows[i + 1])
-                for i in range(0, len(rows) - 1)]
 
         return cols, rows, v_s, h_s
 
     def _generate_table(self, table_idx, cols, rows, **kwargs):
-        v_s = kwargs.get('v_s')
+        v_s = kwargs.get("v_s")
-        h_s = kwargs.get('h_s')
+        h_s = kwargs.get("h_s")
         if v_s is None or h_s is None:
-            raise ValueError('No segments found on {}'.format(self.rootname))
+            raise ValueError("No segments found on {}".format(self.rootname))
 
         table = Table(cols, rows)
         # set table edges to True using ver+hor lines
-        table = table.set_edges(v_s, h_s, joint_close_tol=self.joint_close_tol)
+        table = table.set_edges(v_s, h_s, joint_tol=self.joint_tol)
         # set table border edges to True
         table = table.set_border()
         # set spanning cells to True
         table = table.set_span()
 
         pos_errors = []
-        for direction in self.t_bbox:
+        # TODO: have a single list in place of two directional ones?
+        # sorted on x-coordinate based on reading order i.e. LTR or RTL
+        for direction in ["vertical", "horizontal"]:
             for t in self.t_bbox[direction]:
                 indices, error = get_table_index(
-                    table, t, direction, split_text=self.split_text,
+                    table,
-                    flag_size=self.flag_size)
+                    t,
+                    direction,
+                    split_text=self.split_text,
+                    flag_size=self.flag_size,
+                    strip_text=self.strip_text,
+                )
                 if indices[:2] != (-1, -1):
                     pos_errors.append(error)
-                    indices = Lattice._reduce_index(table, indices, shift_text=self.shift_text)
+                    indices = Lattice._reduce_index(
+                        table, indices, shift_text=self.shift_text
+                    )
                     for r_idx, c_idx, text in indices:
                         table.cells[r_idx][c_idx].text = text
         accuracy = compute_accuracy([[100, pos_errors]])
@@ -328,11 +365,11 @@ class Lattice(BaseParser):
         table.shape = table.df.shape
 
         whitespace = compute_whitespace(data)
-        table.flavor = 'lattice'
+        table.flavor = "lattice"
         table.accuracy = accuracy
         table.whitespace = whitespace
         table.order = table_idx + 1
-        table.page = int(os.path.basename(self.rootname).replace('page-', ''))
+        table.page = int(os.path.basename(self.rootname).replace("page-", ""))
 
         # for plotting
         _text = []
@@ -341,16 +378,25 @@ class Lattice(BaseParser):
         table._text = _text
         table._image = (self.image, self.table_bbox_unscaled)
         table._segments = (self.vertical_segments, self.horizontal_segments)
+        table._textedges = None
 
         return table
 
-    def extract_tables(self, filename):
+    def extract_tables(self, filename, suppress_stdout=False, layout_kwargs={}):
-        self._generate_layout(filename)
+        self._generate_layout(filename, layout_kwargs)
-        logger.info('Processing {}'.format(os.path.basename(self.rootname)))
+        if not suppress_stdout:
+            logger.info("Processing {}".format(os.path.basename(self.rootname)))
 
         if not self.horizontal_text:
-            warnings.warn("No tables found on {}".format(
+            if self.images:
-                os.path.basename(self.rootname)))
+                warnings.warn(
+                    "{} is image-based, camelot only works on"
+                    " text-based pages.".format(os.path.basename(self.rootname))
+                )
+            else:
+                warnings.warn(
+                    "No tables found on {}".format(os.path.basename(self.rootname))
+                )
             return []
 
         self._generate_image()
@@ -358,10 +404,12 @@ class Lattice(BaseParser):
 
         _tables = []
         # sort tables based on y-coord
-        for table_idx, tk in enumerate(sorted(
+        for table_idx, tk in enumerate(
-                self.table_bbox.keys(), key=lambda x: x[1], reverse=True)):
+            sorted(self.table_bbox.keys(), key=lambda x: x[1], reverse=True)
+        ):
             cols, rows, v_s, h_s = self._generate_columns_and_rows(table_idx, tk)
             table = self._generate_table(table_idx, cols, rows, v_s=v_s, h_s=h_s)
+            table._bbox = tk
             _tables.append(table)
 
         return _tables

camelot/parsers/stream.py

@@ -1,6 +1,5 @@
 # -*- coding: utf-8 -*-
 
-from __future__ import division
 import os
 import logging
 import warnings
@@ -9,12 +8,11 @@ import numpy as np
 import pandas as pd
 
 from .base import BaseParser
-from ..core import Table
+from ..core import TextEdges, Table
-from ..utils import (text_in_bbox, get_table_index, compute_accuracy,
+from ..utils import text_in_bbox, get_table_index, compute_accuracy, compute_whitespace
-                     compute_whitespace)
 
 
-logger = logging.getLogger('camelot')
+logger = logging.getLogger("camelot")
 
 
 class Stream(BaseParser):
@@ -26,6 +24,10 @@ class Stream(BaseParser):
 
     Parameters
     ----------
+    table_regions : list, optional (default: None)
+        List of page regions that may contain tables of the form x1,y1,x2,y2
+        where (x1, y1) -> left-top and (x2, y2) -> right-bottom
+        in PDF coordinate space.
     table_areas : list, optional (default: None)
         List of table area strings of the form x1,y1,x2,y2
         where (x1, y1) -> left-top and (x2, y2) -> right-bottom
@@ -38,29 +40,43 @@ class Stream(BaseParser):
     flag_size : bool, optional (default: False)
         Flag text based on font size. Useful to detect
         super/subscripts. Adds <s></s> around flagged text.
-    row_close_tol : int, optional (default: 2)
+    strip_text : str, optional (default: '')
+        Characters that should be stripped from a string before
+        assigning it to a cell.
+    edge_tol : int, optional (default: 50)
+        Tolerance parameter for extending textedges vertically.
+    row_tol : int, optional (default: 2)
         Tolerance parameter used to combine text vertically,
         to generate rows.
-    col_close_tol : int, optional (default: 0)
+    column_tol : int, optional (default: 0)
         Tolerance parameter used to combine text horizontally,
         to generate columns.
-    margins : tuple, optional (default: (1.0, 0.5, 0.1))
-        PDFMiner char_margin, line_margin and word_margin.
-
-        For more information, refer `PDFMiner docs <https://euske.github.io/pdfminer/>`_.
 
     """
-    def __init__(self, table_areas=None, columns=None, split_text=False,
+
-                 flag_size=False, row_close_tol=2, col_close_tol=0,
+    def __init__(
-                 margins=(1.0, 0.5, 0.1), **kwargs):
+        self,
+        table_regions=None,
+        table_areas=None,
+        columns=None,
+        split_text=False,
+        flag_size=False,
+        strip_text="",
+        edge_tol=50,
+        row_tol=2,
+        column_tol=0,
+        **kwargs
+    ):
+        self.table_regions = table_regions
         self.table_areas = table_areas
         self.columns = columns
         self._validate_columns()
         self.split_text = split_text
         self.flag_size = flag_size
-        self.row_close_tol = row_close_tol
+        self.strip_text = strip_text
-        self.col_close_tol = col_close_tol
+        self.edge_tol = edge_tol
-        self.char_margin, self.line_margin, self.word_margin = margins
+        self.row_tol = row_tol
+        self.column_tol = column_tol
 
     @staticmethod
     def _text_bbox(t_bbox):
@@ -86,7 +102,7 @@ class Stream(BaseParser):
         return text_bbox
 
     @staticmethod
-    def _group_rows(text, row_close_tol=2):
+    def _group_rows(text, row_tol=2):
         """Groups PDFMiner text objects into rows vertically
         within a tolerance.
 
@@ -94,7 +110,7 @@ class Stream(BaseParser):
         ----------
         text : list
             List of PDFMiner text objects.
-        row_close_tol : int, optional (default: 2)
+        row_tol : int, optional (default: 2)
 
         Returns
         -------
@@ -110,17 +126,17 @@ class Stream(BaseParser):
             # if t.get_text().strip() and all([obj.upright for obj in t._objs if
             # type(obj) is LTChar]):
             if t.get_text().strip():
-                if not np.isclose(row_y, t.y0, atol=row_close_tol):
+                if not np.isclose(row_y, t.y0, atol=row_tol):
                     rows.append(sorted(temp, key=lambda t: t.x0))
                     temp = []
                     row_y = t.y0
                 temp.append(t)
         rows.append(sorted(temp, key=lambda t: t.x0))
-        __ = rows.pop(0)  # hacky
+        __ = rows.pop(0)  # TODO: hacky
         return rows
 
     @staticmethod
-    def _merge_columns(l, col_close_tol=0):
+    def _merge_columns(l, column_tol=0):
         """Merges column boundaries horizontally if they overlap
         or lie within a tolerance.
 
@@ -128,7 +144,7 @@ class Stream(BaseParser):
         ----------
         l : list
             List of column x-coordinate tuples.
-        col_close_tol : int, optional (default: 0)
+        column_tol : int, optional (default: 0)
 
         Returns
         -------
@@ -142,17 +158,18 @@ class Stream(BaseParser):
                 merged.append(higher)
             else:
                 lower = merged[-1]
-                if col_close_tol >= 0:
+                if column_tol >= 0:
-                    if (higher[0] <= lower[1] or
+                    if higher[0] <= lower[1] or np.isclose(
-                            np.isclose(higher[0], lower[1], atol=col_close_tol)):
+                        higher[0], lower[1], atol=column_tol
+                    ):
                         upper_bound = max(lower[1], higher[1])
                         lower_bound = min(lower[0], higher[0])
                         merged[-1] = (lower_bound, upper_bound)
                     else:
                         merged.append(higher)
-                elif col_close_tol < 0:
+                elif column_tol < 0:
                     if higher[0] <= lower[1]:
-                        if np.isclose(higher[0], lower[1], atol=abs(col_close_tol)):
+                        if np.isclose(higher[0], lower[1], atol=abs(column_tol)):
                             merged.append(higher)
                         else:
                             upper_bound = max(lower[1], higher[1])
@@ -179,17 +196,18 @@ class Stream(BaseParser):
             List of continuous row y-coordinate tuples.
 
         """
-        row_mids = [sum([(t.y0 + t.y1) / 2 for t in r]) / len(r)
+        row_mids = [
-                    if len(r) > 0 else 0 for r in rows_grouped]
+            sum([(t.y0 + t.y1) / 2 for t in r]) / len(r) if len(r) > 0 else 0
+            for r in rows_grouped
+        ]
         rows = [(row_mids[i] + row_mids[i - 1]) / 2 for i in range(1, len(row_mids))]
         rows.insert(0, text_y_max)
         rows.append(text_y_min)
-        rows = [(rows[i], rows[i + 1])
+        rows = [(rows[i], rows[i + 1]) for i in range(0, len(rows) - 1)]
-                for i in range(0, len(rows) - 1)]
         return rows
 
     @staticmethod
-    def _add_columns(cols, text, row_close_tol):
+    def _add_columns(cols, text, row_tol):
         """Adds columns to existing list by taking into account
         the text that lies outside the current column x-coordinates.
 
@@ -208,10 +226,11 @@ class Stream(BaseParser):
 
         """
         if text:
-            text = Stream._group_rows(text, row_close_tol=row_close_tol)
+            text = Stream._group_rows(text, row_tol=row_tol)
             elements = [len(r) for r in text]
-            new_cols = [(t.x0, t.x1)
+            new_cols = [
-                        for r in text if len(r) == max(elements) for t in r]
+                (t.x0, t.x1) for r in text if len(r) == max(elements) for t in r
+            ]
             cols.extend(Stream._merge_columns(sorted(new_cols)))
         return cols
 
@@ -236,18 +255,57 @@ class Stream(BaseParser):
         cols = [(cols[i][0] + cols[i - 1][1]) / 2 for i in range(1, len(cols))]
         cols.insert(0, text_x_min)
         cols.append(text_x_max)
-        cols = [(cols[i], cols[i + 1])
+        cols = [(cols[i], cols[i + 1]) for i in range(0, len(cols) - 1)]
-                for i in range(0, len(cols) - 1)]
         return cols
 
     def _validate_columns(self):
         if self.table_areas is not None and self.columns is not None:
             if len(self.table_areas) != len(self.columns):
-                raise ValueError("Length of table_areas and columns"
+                raise ValueError("Length of table_areas and columns" " should be equal")
-                                 " should be equal")
+
+    def _nurminen_table_detection(self, textlines):
+        """A general implementation of the table detection algorithm
+        described by Anssi Nurminen's master's thesis.
+        Link: https://dspace.cc.tut.fi/dpub/bitstream/handle/123456789/21520/Nurminen.pdf?sequence=3
+
+        Assumes that tables are situated relatively far apart
+        vertically.
+        """
+        # TODO: add support for arabic text #141
+        # sort textlines in reading order
+        textlines.sort(key=lambda x: (-x.y0, x.x0))
+        textedges = TextEdges(edge_tol=self.edge_tol)
+        # generate left, middle and right textedges
+        textedges.generate(textlines)
+        # select relevant edges
+        relevant_textedges = textedges.get_relevant()
+        self.textedges.extend(relevant_textedges)
+        # guess table areas using textlines and relevant edges
+        table_bbox = textedges.get_table_areas(textlines, relevant_textedges)
+        # treat whole page as table area if no table areas found
+        if not len(table_bbox):
+            table_bbox = {(0, 0, self.pdf_width, self.pdf_height): None}
+
+        return table_bbox
 
     def _generate_table_bbox(self):
-        if self.table_areas is not None:
+        self.textedges = []
+        if self.table_areas is None:
+            hor_text = self.horizontal_text
+            if self.table_regions is not None:
+                # filter horizontal text
+                hor_text = []
+                for region in self.table_regions:
+                    x1, y1, x2, y2 = region.split(",")
+                    x1 = float(x1)
+                    y1 = float(y1)
+                    x2 = float(x2)
+                    y2 = float(y2)
+                    region_text = text_in_bbox((x1, y2, x2, y1), self.horizontal_text)
+                    hor_text.extend(region_text)
+            # find tables based on nurminen's detection algorithm
+            table_bbox = self._nurminen_table_detection(hor_text)
+        else:
             table_bbox = {}
             for area in self.table_areas:
                 x1, y1, x2, y2 = area.split(",")
@@ -256,22 +314,21 @@ class Stream(BaseParser):
                 x2 = float(x2)
                 y2 = float(y2)
                 table_bbox[(x1, y2, x2, y1)] = None
-        else:
-            table_bbox = {(0, 0, self.pdf_width, self.pdf_height): None}
         self.table_bbox = table_bbox
 
     def _generate_columns_and_rows(self, table_idx, tk):
         # select elements which lie within table_bbox
         t_bbox = {}
-        t_bbox['horizontal'] = text_in_bbox(tk, self.horizontal_text)
+        t_bbox["horizontal"] = text_in_bbox(tk, self.horizontal_text)
-        t_bbox['vertical'] = text_in_bbox(tk, self.vertical_text)
+        t_bbox["vertical"] = text_in_bbox(tk, self.vertical_text)
+
+        t_bbox["horizontal"].sort(key=lambda x: (-x.y0, x.x0))
+        t_bbox["vertical"].sort(key=lambda x: (x.x0, -x.y0))
+
         self.t_bbox = t_bbox
 
-        for direction in self.t_bbox:
-            self.t_bbox[direction].sort(key=lambda x: (-x.y0, x.x0))
-
         text_x_min, text_y_min, text_x_max, text_y_max = self._text_bbox(self.t_bbox)
-        rows_grouped = self._group_rows(self.t_bbox['horizontal'], row_close_tol=self.row_close_tol)
+        rows_grouped = self._group_rows(self.t_bbox["horizontal"], row_tol=self.row_tol)
         rows = self._join_rows(rows_grouped, text_y_max, text_y_min)
         elements = [len(r) for r in rows_grouped]
 
@@ -280,30 +337,50 @@ class Stream(BaseParser):
             # take (0, pdf_width) by default
             # similar to else condition
             # len can't be 1
-            cols = self.columns[table_idx].split(',')
+            cols = self.columns[table_idx].split(",")
             cols = [float(c) for c in cols]
             cols.insert(0, text_x_min)
             cols.append(text_x_max)
             cols = [(cols[i], cols[i + 1]) for i in range(0, len(cols) - 1)]
         else:
+            # calculate mode of the list of number of elements in
+            # each row to guess the number of columns
             ncols = max(set(elements), key=elements.count)
             if ncols == 1:
-                warnings.warn("No tables found on {}".format(
+                # if mode is 1, the page usually contains not tables
-                    os.path.basename(self.rootname)))
+                # but there can be cases where the list can be skewed,
+                # try to remove all 1s from list in this case and
+                # see if the list contains elements, if yes, then use
+                # the mode after removing 1s
+                elements = list(filter(lambda x: x != 1, elements))
+                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]
-            cols = self._merge_columns(sorted(cols), col_close_tol=self.col_close_tol)
+            cols = self._merge_columns(sorted(cols), column_tol=self.column_tol)
             inner_text = []
             for i in range(1, len(cols)):
                 left = cols[i - 1][1]
                 right = cols[i][0]
-                inner_text.extend([t for direction in self.t_bbox
+                inner_text.extend(
-                                     for t in self.t_bbox[direction]
+                    [
-                                     if t.x0 > left and t.x1 < right])
+                        t
-            outer_text = [t for direction in self.t_bbox
+                        for direction in self.t_bbox
-                            for t in self.t_bbox[direction]
+                        for t in self.t_bbox[direction]
-                            if t.x0 > cols[-1][1] or t.x1 < cols[0][0]]
+                        if t.x0 > left and t.x1 < right
+                    ]
+                )
+            outer_text = [
+                t
+                for direction in self.t_bbox
+                for t in self.t_bbox[direction]
+                if t.x0 > cols[-1][1] or t.x1 < cols[0][0]
+            ]
             inner_text.extend(outer_text)
-            cols = self._add_columns(cols, inner_text, self.row_close_tol)
+            cols = self._add_columns(cols, inner_text, self.row_tol)
             cols = self._join_columns(cols, text_x_min, text_x_max)
 
         return cols, rows
@@ -311,12 +388,20 @@ class Stream(BaseParser):
     def _generate_table(self, table_idx, cols, rows, **kwargs):
         table = Table(cols, rows)
         table = table.set_all_edges()
+
         pos_errors = []
-        for direction in self.t_bbox:
+        # TODO: have a single list in place of two directional ones?
+        # sorted on x-coordinate based on reading order i.e. LTR or RTL
+        for direction in ["vertical", "horizontal"]:
             for t in self.t_bbox[direction]:
                 indices, error = get_table_index(
-                    table, t, direction, split_text=self.split_text,
+                    table,
-                    flag_size=self.flag_size)
+                    t,
+                    direction,
+                    split_text=self.split_text,
+                    flag_size=self.flag_size,
+                    strip_text=self.strip_text,
+                )
                 if indices[:2] != (-1, -1):
                     pos_errors.append(error)
                     for r_idx, c_idx, text in indices:
@@ -328,11 +413,11 @@ class Stream(BaseParser):
         table.shape = table.df.shape
 
         whitespace = compute_whitespace(data)
-        table.flavor = 'stream'
+        table.flavor = "stream"
         table.accuracy = accuracy
         table.whitespace = whitespace
         table.order = table_idx + 1
-        table.page = int(os.path.basename(self.rootname).replace('page-', ''))
+        table.page = int(os.path.basename(self.rootname).replace("page-", ""))
 
         # for plotting
         _text = []
@@ -341,26 +426,37 @@ class Stream(BaseParser):
         table._text = _text
         table._image = None
         table._segments = None
+        table._textedges = self.textedges
 
         return table
 
-    def extract_tables(self, filename):
+    def extract_tables(self, filename, suppress_stdout=False, layout_kwargs={}):
-        self._generate_layout(filename)
+        self._generate_layout(filename, layout_kwargs)
-        logger.info('Processing {}'.format(os.path.basename(self.rootname)))
+        base_filename = os.path.basename(self.rootname)
+
+        if not suppress_stdout:
+            logger.info(f"Processing {base_filename}")
 
         if not self.horizontal_text:
-            warnings.warn("No tables found on {}".format(
+            if self.images:
-                os.path.basename(self.rootname)))
+                warnings.warn(
+                    f"{base_filename} is image-based, camelot only works on"
+                    " text-based pages."
+                )
+            else:
+                warnings.warn(f"No tables found on {base_filename}")
             return []
 
         self._generate_table_bbox()
 
         _tables = []
         # sort tables based on y-coord
-        for table_idx, tk in enumerate(sorted(
+        for table_idx, tk in enumerate(
-                self.table_bbox.keys(), key=lambda x: x[1], reverse=True)):
+            sorted(self.table_bbox.keys(), key=lambda x: x[1], reverse=True)
+        ):
             cols, rows = self._generate_columns_and_rows(table_idx, tk)
             table = self._generate_table(table_idx, cols, rows)
+            table._bbox = tk
             _tables.append(table)
 
         return _tables

camelot/plotting.py

@@ -1,108 +1,223 @@
-import cv2
+# -*- coding: utf-8 -*-
-import matplotlib.pyplot as plt
+
-import matplotlib.patches as patches
+try:
+    import matplotlib.pyplot as plt
+    import matplotlib.patches as patches
+except ImportError:
+    _HAS_MPL = False
+else:
+    _HAS_MPL = True
 
 
-def plot_text(text):
+class PlotMethods(object):
-    """Generates a plot for all text present on the PDF page.
+    def __call__(self, table, kind="text", filename=None):
+        """Plot elements found on PDF page based on kind
+        specified, useful for debugging and playing with different
+        parameters to get the best output.
 
-    Parameters
+        Parameters
-    ----------
+        ----------
-    text : list
+        table: camelot.core.Table
+            A Camelot Table.
+        kind : str, optional (default: 'text')
+            {'text', 'grid', 'contour', 'joint', 'line'}
+            The element type for which a plot should be generated.
+        filepath: str, optional (default: None)
+            Absolute path for saving the generated plot.
 
-    """
+        Returns
-    fig = plt.figure()
+        -------
-    ax = fig.add_subplot(111, aspect='equal')
+        fig : matplotlib.fig.Figure
-    xs, ys = [], []
+
-    for t in text:
+        """
-        xs.extend([t[0], t[2]])
+        if not _HAS_MPL:
-        ys.extend([t[1], t[3]])
+            raise ImportError("matplotlib is required for plotting.")
-        ax.add_patch(
+
-            patches.Rectangle(
+        if table.flavor == "lattice" and kind in ["textedge"]:
-                (t[0], t[1]),
+            raise NotImplementedError(
-                t[2] - t[0],
+                f"Lattice flavor does not support kind='{kind}'"
-                t[3] - t[1]
+            )
+        elif table.flavor == "stream" and kind in ["joint", "line"]:
+            raise NotImplementedError(
+                f"Stream flavor does not support kind='{kind}'"
             )
-        )
-    ax.set_xlim(min(xs) - 10, max(xs) + 10)
-    ax.set_ylim(min(ys) - 10, max(ys) + 10)
-    plt.show()
 
+        plot_method = getattr(self, kind)
+        return plot_method(table)
 
-def plot_table(table):
+    def text(self, table):
-    """Generates a plot for the table.
+        """Generates a plot for all text elements present
+        on the PDF page.
 
-    Parameters
+        Parameters
-    ----------
+        ----------
-    table : camelot.core.Table
+        table : camelot.core.Table
 
-    """
+        Returns
-    for row in table.cells:
+        -------
-        for cell in row:
+        fig : matplotlib.fig.Figure
-            if cell.left:
-                plt.plot([cell.lb[0], cell.lt[0]],
-                         [cell.lb[1], cell.lt[1]])
-            if cell.right:
-                plt.plot([cell.rb[0], cell.rt[0]],
-                         [cell.rb[1], cell.rt[1]])
-            if cell.top:
-                plt.plot([cell.lt[0], cell.rt[0]],
-                         [cell.lt[1], cell.rt[1]])
-            if cell.bottom:
-                plt.plot([cell.lb[0], cell.rb[0]],
-                         [cell.lb[1], cell.rb[1]])
-    plt.show()
 
+        """
+        fig = plt.figure()
+        ax = fig.add_subplot(111, aspect="equal")
+        xs, ys = [], []
+        for t in table._text:
+            xs.extend([t[0], t[2]])
+            ys.extend([t[1], t[3]])
+            ax.add_patch(patches.Rectangle((t[0], t[1]), t[2] - t[0], t[3] - t[1]))
+        ax.set_xlim(min(xs) - 10, max(xs) + 10)
+        ax.set_ylim(min(ys) - 10, max(ys) + 10)
+        return fig
 
-def plot_contour(image):
+    def grid(self, table):
-    """Generates a plot for all table boundaries present on the
+        """Generates a plot for the detected table grids
-    PDF page.
+        on the PDF page.
 
-    Parameters
+        Parameters
-    ----------
+        ----------
-    image : tuple
+        table : camelot.core.Table
 
-    """
+        Returns
-    img, table_bbox = image
+        -------
-    for t in table_bbox.keys():
+        fig : matplotlib.fig.Figure
-        cv2.rectangle(img, (t[0], t[1]),
-                      (t[2], t[3]), (255, 0, 0), 20)
-    plt.imshow(img)
-    plt.show()
 
+        """
+        fig = plt.figure()
+        ax = fig.add_subplot(111, aspect="equal")
+        for row in table.cells:
+            for cell in row:
+                if cell.left:
+                    ax.plot([cell.lb[0], cell.lt[0]], [cell.lb[1], cell.lt[1]])
+                if cell.right:
+                    ax.plot([cell.rb[0], cell.rt[0]], [cell.rb[1], cell.rt[1]])
+                if cell.top:
+                    ax.plot([cell.lt[0], cell.rt[0]], [cell.lt[1], cell.rt[1]])
+                if cell.bottom:
+                    ax.plot([cell.lb[0], cell.rb[0]], [cell.lb[1], cell.rb[1]])
+        return fig
 
-def plot_joint(image):
+    def contour(self, table):
-    """Generates a plot for all line intersections present on the
+        """Generates a plot for all table boundaries present
-    PDF page.
+        on the PDF page.
 
-    Parameters
+        Parameters
-    ----------
+        ----------
-    image : tuple
+        table : camelot.core.Table
 
-    """
+        Returns
-    img, table_bbox = image
+        -------
-    x_coord = []
+        fig : matplotlib.fig.Figure
-    y_coord = []
-    for k in table_bbox.keys():
-        for coord in table_bbox[k]:
-            x_coord.append(coord[0])
-            y_coord.append(coord[1])
-    plt.plot(x_coord, y_coord, 'ro')
-    plt.imshow(img)
-    plt.show()
 
+        """
+        try:
+            img, table_bbox = table._image
+            _FOR_LATTICE = True
+        except TypeError:
+            img, table_bbox = (None, {table._bbox: None})
+            _FOR_LATTICE = False
+        fig = plt.figure()
+        ax = fig.add_subplot(111, aspect="equal")
 
-def plot_line(segments):
+        xs, ys = [], []
-    """Generates a plot for all line segments present on the PDF page.
+        if not _FOR_LATTICE:
+            for t in table._text:
+                xs.extend([t[0], t[2]])
+                ys.extend([t[1], t[3]])
+                ax.add_patch(
+                    patches.Rectangle(
+                        (t[0], t[1]), t[2] - t[0], t[3] - t[1], color="blue"
+                    )
+                )
 
-    Parameters
+        for t in table_bbox.keys():
-    ----------
+            ax.add_patch(
-    segments : tuple
+                patches.Rectangle(
+                    (t[0], t[1]), t[2] - t[0], t[3] - t[1], fill=False, color="red"
+                )
+            )
+            if not _FOR_LATTICE:
+                xs.extend([t[0], t[2]])
+                ys.extend([t[1], t[3]])
+                ax.set_xlim(min(xs) - 10, max(xs) + 10)
+                ax.set_ylim(min(ys) - 10, max(ys) + 10)
 
-    """
+        if _FOR_LATTICE:
-    vertical, horizontal = segments
+            ax.imshow(img)
-    for v in vertical:
+        return fig
-        plt.plot([v[0], v[2]], [v[1], v[3]])
+
-    for h in horizontal:
+    def textedge(self, table):
-        plt.plot([h[0], h[2]], [h[1], h[3]])
+        """Generates a plot for relevant textedges.
-    plt.show()
+
+        Parameters
+        ----------
+        table : camelot.core.Table
+
+        Returns
+        -------
+        fig : matplotlib.fig.Figure
+
+        """
+        fig = plt.figure()
+        ax = fig.add_subplot(111, aspect="equal")
+        xs, ys = [], []
+        for t in table._text:
+            xs.extend([t[0], t[2]])
+            ys.extend([t[1], t[3]])
+            ax.add_patch(
+                patches.Rectangle((t[0], t[1]), t[2] - t[0], t[3] - t[1], color="blue")
+            )
+        ax.set_xlim(min(xs) - 10, max(xs) + 10)
+        ax.set_ylim(min(ys) - 10, max(ys) + 10)
+
+        for te in table._textedges:
+            ax.plot([te.x, te.x], [te.y0, te.y1])
+
+        return fig
+
+    def joint(self, table):
+        """Generates a plot for all line intersections present
+        on the PDF page.
+
+        Parameters
+        ----------
+        table : camelot.core.Table
+
+        Returns
+        -------
+        fig : matplotlib.fig.Figure
+
+        """
+        img, table_bbox = table._image
+        fig = plt.figure()
+        ax = fig.add_subplot(111, aspect="equal")
+        x_coord = []
+        y_coord = []
+        for k in table_bbox.keys():
+            for coord in table_bbox[k]:
+                x_coord.append(coord[0])
+                y_coord.append(coord[1])
+        ax.plot(x_coord, y_coord, "ro")
+        ax.imshow(img)
+        return fig
+
+    def line(self, table):
+        """Generates a plot for all line segments present
+        on the PDF page.
+
+        Parameters
+        ----------
+        table : camelot.core.Table
+
+        Returns
+        -------
+        fig : matplotlib.fig.Figure
+
+        """
+        fig = plt.figure()
+        ax = fig.add_subplot(111, aspect="equal")
+        vertical, horizontal = table._segments
+        for v in vertical:
+            ax.plot([v[0], v[2]], [v[1], v[3]])
+        for h in horizontal:
+            ax.plot([h[0], h[2]], [h[1], h[3]])
+        return fig

camelot/utils.py

@@ -1,12 +1,16 @@
-from __future__ import division
+# -*- coding: utf-8 -*-
+
+import os
+import re
+import random
 import shutil
+import string
 import tempfile
 import warnings
 from itertools import groupby
 from operator import itemgetter
 
 import numpy as np
-
 from pdfminer.pdfparser import PDFParser
 from pdfminer.pdfdocument import PDFDocument
 from pdfminer.pdfpage import PDFPage
@@ -14,43 +18,112 @@ from pdfminer.pdfpage import PDFTextExtractionNotAllowed
 from pdfminer.pdfinterp import PDFResourceManager
 from pdfminer.pdfinterp import PDFPageInterpreter
 from pdfminer.converter import PDFPageAggregator
-from pdfminer.layout import (LAParams, LTAnno, LTChar, LTTextLineHorizontal,
+from pdfminer.layout import (
-                             LTTextLineVertical)
+    LAParams,
+    LTAnno,
+    LTChar,
+    LTTextLineHorizontal,
+    LTTextLineVertical,
+    LTImage,
+)
+
+from urllib.request import Request, urlopen
+from urllib.parse import urlparse as parse_url
+from urllib.parse import uses_relative, uses_netloc, uses_params
 
 
-stream_kwargs = [
+_VALID_URLS = set(uses_relative + uses_netloc + uses_params)
-    'columns',
+_VALID_URLS.discard("")
-    'row_close_tol',
+
-    'col_close_tol'
+
-]
+# https://github.com/pandas-dev/pandas/blob/master/pandas/io/common.py
+def is_url(url):
+    """Check to see if a URL has a valid protocol.
+
+    Parameters
+    ----------
+    url : str or unicode
+
+    Returns
+    -------
+    isurl : bool
+        If url has a valid protocol return True otherwise False.
+
+    """
+    try:
+        return parse_url(url).scheme in _VALID_URLS
+    except Exception:
+        return False
+
+
+def random_string(length):
+    ret = ""
+    while length:
+        ret += random.choice(
+            string.digits + string.ascii_lowercase + string.ascii_uppercase
+        )
+        length -= 1
+    return ret
+
+
+def download_url(url):
+    """Download file from specified URL.
+
+    Parameters
+    ----------
+    url : str or unicode
+
+    Returns
+    -------
+    filepath : str or unicode
+        Temporary filepath.
+
+    """
+    filename = f"{random_string(6)}.pdf"
+    with tempfile.NamedTemporaryFile("wb", delete=False) as f:
+        headers = {"User-Agent": "Mozilla/5.0"}
+        request = Request(url, None, headers)
+        obj = urlopen(request)
+        content_type = obj.info().get_content_type()
+        if content_type != "application/pdf":
+            raise NotImplementedError("File format not supported")
+        f.write(obj.read())
+    filepath = os.path.join(os.path.dirname(f.name), filename)
+    shutil.move(f.name, filepath)
+    return filepath
+
+
+stream_kwargs = ["columns", "edge_tol", "row_tol", "column_tol"]
 lattice_kwargs = [
-    'process_background',
+    "process_background",
-    'line_size_scaling',
+    "line_scale",
-    'copy_text',
+    "copy_text",
-    'shift_text',
+    "shift_text",
-    'line_close_tol',
+    "line_tol",
-    'joint_close_tol',
+    "joint_tol",
-    'threshold_blocksize',
+    "threshold_blocksize",
-    'threshold_constant',
+    "threshold_constant",
-    'iterations'
+    "iterations",
+    "resolution",
 ]
 
 
-def validate_input(kwargs, flavor='lattice'):
+def validate_input(kwargs, flavor="lattice"):
     def check_intersection(parser_kwargs, input_kwargs):
         isec = set(parser_kwargs).intersection(set(input_kwargs.keys()))
         if isec:
-            raise ValueError("{} cannot be used with flavor='{}'".format(
+            raise ValueError(
-                             ",".join(sorted(isec)), flavor))
+                f"{','.join(sorted(isec))} cannot be used with flavor='{flavor}'"
+            )
 
-    if flavor == 'lattice':
+    if flavor == "lattice":
         check_intersection(stream_kwargs, kwargs)
     else:
         check_intersection(lattice_kwargs, kwargs)
 
 
-def remove_extra(kwargs, flavor='lattice'):
+def remove_extra(kwargs, flavor="lattice"):
-    if flavor == 'lattice':
+    if flavor == "lattice":
         for key in kwargs.keys():
             if key in stream_kwargs:
                 kwargs.pop(key)
@@ -180,29 +253,33 @@ def scale_image(tables, v_segments, h_segments, factors):
     v_segments_new = []
     for v in v_segments:
         x1, x2 = scale(v[0], scaling_factor_x), scale(v[2], scaling_factor_x)
-        y1, y2 = scale(abs(translate(-img_y, v[1])), scaling_factor_y), scale(
+        y1, y2 = (
-            abs(translate(-img_y, v[3])), scaling_factor_y)
+            scale(abs(translate(-img_y, v[1])), scaling_factor_y),
+            scale(abs(translate(-img_y, v[3])), scaling_factor_y),
+        )
         v_segments_new.append((x1, y1, x2, y2))
 
     h_segments_new = []
     for h in h_segments:
         x1, x2 = scale(h[0], scaling_factor_x), scale(h[2], scaling_factor_x)
-        y1, y2 = scale(abs(translate(-img_y, h[1])), scaling_factor_y), scale(
+        y1, y2 = (
-            abs(translate(-img_y, h[3])), scaling_factor_y)
+            scale(abs(translate(-img_y, h[1])), scaling_factor_y),
+            scale(abs(translate(-img_y, h[3])), scaling_factor_y),
+        )
         h_segments_new.append((x1, y1, x2, y2))
 
     return tables_new, v_segments_new, h_segments_new
 
 
-def get_rotation(lttextlh, lttextlv, ltchar):
+def get_rotation(chars, horizontal_text, vertical_text):
     """Detects if text in table is rotated or not using the current
     transformation matrix (CTM) and returns its orientation.
 
     Parameters
     ----------
-    lttextlh : list
+    horizontal_text : list
         List of PDFMiner LTTextLineHorizontal objects.
-    lttextlv : list
+    vertical_text : list
         List of PDFMiner LTTextLineVertical objects.
     ltchar : list
         List of PDFMiner LTChar objects.
@@ -215,13 +292,13 @@ def get_rotation(lttextlh, lttextlv, ltchar):
         rotated 90 degree clockwise.
 
     """
-    rotation = ''
+    rotation = ""
-    hlen = len([t for t in lttextlh if t.get_text().strip()])
+    hlen = len([t for t in horizontal_text if t.get_text().strip()])
-    vlen = len([t for t in lttextlv if t.get_text().strip()])
+    vlen = len([t for t in vertical_text if t.get_text().strip()])
     if hlen < vlen:
-        clockwise = sum(t.matrix[1] < 0 and t.matrix[2] > 0 for t in ltchar)
+        clockwise = sum(t.matrix[1] < 0 and t.matrix[2] > 0 for t in chars)
-        anticlockwise = sum(t.matrix[1] > 0 and t.matrix[2] < 0 for t in ltchar)
+        anticlockwise = sum(t.matrix[1] > 0 and t.matrix[2] < 0 for t in chars)
-        rotation = 'anticlockwise' if clockwise < anticlockwise else 'clockwise'
+        rotation = "anticlockwise" if clockwise < anticlockwise else "clockwise"
     return rotation
 
 
@@ -249,10 +326,16 @@ def segments_in_bbox(bbox, v_segments, h_segments):
     """
     lb = (bbox[0], bbox[1])
     rt = (bbox[2], bbox[3])
-    v_s = [v for v in v_segments if v[1] > lb[1] - 2 and
+    v_s = [
-           v[3] < rt[1] + 2 and lb[0] - 2 <= v[0] <= rt[0] + 2]
+        v
-    h_s = [h for h in h_segments if h[0] > lb[0] - 2 and
+        for v in v_segments
-           h[2] < rt[0] + 2 and lb[1] - 2 <= h[1] <= rt[1] + 2]
+        if v[1] > lb[1] - 2 and v[3] < rt[1] + 2 and lb[0] - 2 <= v[0] <= rt[0] + 2
+    ]
+    h_s = [
+        h
+        for h in h_segments
+        if h[0] > lb[0] - 2 and h[2] < rt[0] + 2 and lb[1] - 2 <= h[1] <= rt[1] + 2
+    ]
     return v_s, h_s
 
 
@@ -263,7 +346,7 @@ def text_in_bbox(bbox, text):
     ----------
     bbox : tuple
         Tuple (x1, y1, x2, y2) representing a bounding box where
-        (x1, y1) -> lb and (x2, y2) -> rt in PDFMiner coordinate
+        (x1, y1) -> lb and (x2, y2) -> rt in the PDF coordinate
         space.
     text : List of PDFMiner text objects.
 
@@ -275,20 +358,23 @@ def text_in_bbox(bbox, text):
     """
     lb = (bbox[0], bbox[1])
     rt = (bbox[2], bbox[3])
-    t_bbox = [t for t in text if lb[0] - 2 <= (t.x0 + t.x1) / 2.0
+    t_bbox = [
-              <= rt[0] + 2 and lb[1] - 2 <= (t.y0 + t.y1) / 2.0
+        t
-              <= rt[1] + 2]
+        for t in 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
 
 
-def merge_close_lines(ar, line_close_tol=2):
+def merge_close_lines(ar, line_tol=2):
     """Merges lines which are within a tolerance by calculating a
     moving mean, based on their x or y axis projections.
 
     Parameters
     ----------
     ar : list
-    line_close_tol : int, optional (default: 2)
+    line_tol : int, optional (default: 2)
 
     Returns
     -------
@@ -301,7 +387,7 @@ def merge_close_lines(ar, line_close_tol=2):
             ret.append(a)
         else:
             temp = ret[-1]
-            if np.isclose(temp, a, atol=line_close_tol):
+            if np.isclose(temp, a, atol=line_tol):
                 temp = (temp + a) / 2.0
                 ret[-1] = temp
             else:
@@ -309,7 +395,33 @@ def merge_close_lines(ar, line_close_tol=2):
     return ret
 
 
-def flag_font_size(textline, direction):
+def text_strip(text, strip=""):
+    """Strips any characters in `strip` that are present in `text`.
+    Parameters
+    ----------
+    text : str
+        Text to process and strip.
+    strip : str, optional (default: '')
+        Characters that should be stripped from `text`.
+    Returns
+    -------
+    stripped : str
+    """
+    if not strip:
+        return text
+
+    stripped = re.sub(
+        fr"[{''.join(map(re.escape, strip))}]", "", text, re.UNICODE
+    )
+    return stripped
+
+
+# TODO: combine the following functions into a TextProcessor class which
+# applies corresponding transformations sequentially
+# (inspired from sklearn.pipeline.Pipeline)
+
+
+def flag_font_size(textline, direction, strip_text=""):
     """Flags super/subscripts in text by enclosing them with <s></s>.
     May give false positives.
 
@@ -319,16 +431,27 @@ def flag_font_size(textline, direction):
         List of PDFMiner LTChar objects.
     direction : string
         Direction of the PDFMiner LTTextLine object.
+    strip_text : str, optional (default: '')
+        Characters that should be stripped from a string before
+        assigning it to a cell.
 
     Returns
     -------
     fstring : string
 
     """
-    if direction == 'horizontal':
+    if direction == "horizontal":
-        d = [(t.get_text(), np.round(t.height, decimals=6)) for t in textline if not isinstance(t, LTAnno)]
+        d = [
-    elif direction == 'vertical':
+            (t.get_text(), np.round(t.height, decimals=6))
-        d = [(t.get_text(), np.round(t.width, decimals=6)) for t in textline if not isinstance(t, LTAnno)]
+            for t in textline
+            if not isinstance(t, LTAnno)
+        ]
+    elif direction == "vertical":
+        d = [
+            (t.get_text(), np.round(t.width, decimals=6))
+            for t in textline
+            if not isinstance(t, LTAnno)
+        ]
     l = [np.round(size, decimals=6) for text, size in d]
     if len(set(l)) > 1:
         flist = []
@@ -336,21 +459,21 @@ def flag_font_size(textline, direction):
         for key, chars in groupby(d, itemgetter(1)):
             if key == min_size:
                 fchars = [t[0] for t in chars]
-                if ''.join(fchars).strip():
+                if "".join(fchars).strip():
-                    fchars.insert(0, '<s>')
+                    fchars.insert(0, "<s>")
-                    fchars.append('</s>')
+                    fchars.append("</s>")
-                    flist.append(''.join(fchars))
+                    flist.append("".join(fchars))
             else:
                 fchars = [t[0] for t in chars]
-                if ''.join(fchars).strip():
+                if "".join(fchars).strip():
-                    flist.append(''.join(fchars))
+                    flist.append("".join(fchars))
-        fstring = ''.join(flist).strip('\n')
+        fstring = "".join(flist)
     else:
-        fstring = ''.join([t.get_text() for t in textline]).strip('\n')
+        fstring = "".join([t.get_text() for t in textline])
-    return fstring
+    return text_strip(fstring, strip_text)
 
 
-def split_textline(table, textline, direction, flag_size=False):
+def split_textline(table, textline, direction, flag_size=False, strip_text=""):
     """Splits PDFMiner LTTextLine into substrings if it spans across
     multiple rows/columns.
 
@@ -365,6 +488,9 @@ def split_textline(table, textline, direction, flag_size=False):
         Whether or not to highlight a substring using <s></s>
         if its size is different from rest of the string. (Useful for
         super and subscripts.)
+    strip_text : str, optional (default: '')
+        Characters that should be stripped from a string before
+        assigning it to a cell.
 
     Returns
     -------
@@ -377,38 +503,70 @@ def split_textline(table, textline, direction, flag_size=False):
     cut_text = []
     bbox = textline.bbox
     try:
-        if direction == 'horizontal' and not textline.is_empty():
+        if direction == "horizontal" and not textline.is_empty():
-            x_overlap = [i for i, x in enumerate(table.cols) if x[0] <= bbox[2] and bbox[0] <= x[1]]
+            x_overlap = [
-            r_idx = [j for j, r in enumerate(table.rows) if r[1] <= (bbox[1] + bbox[3]) / 2 <= r[0]]
+                i
+                for i, x in enumerate(table.cols)
+                if x[0] <= bbox[2] and bbox[0] <= x[1]
+            ]
+            r_idx = [
+                j
+                for j, r in enumerate(table.rows)
+                if r[1] <= (bbox[1] + bbox[3]) / 2 <= r[0]
+            ]
             r = r_idx[0]
-            x_cuts = [(c, table.cells[r][c].x2) for c in x_overlap if table.cells[r][c].right]
+            x_cuts = [
+                (c, table.cells[r][c].x2) for c in x_overlap if table.cells[r][c].right
+            ]
             if not x_cuts:
                 x_cuts = [(x_overlap[0], table.cells[r][-1].x2)]
             for obj in textline._objs:
                 row = table.rows[r]
                 for cut in x_cuts:
                     if isinstance(obj, LTChar):
-                        if (row[1] <= (obj.y0 + obj.y1) / 2 <= row[0] and
+                        if (
-                                (obj.x0 + obj.x1) / 2 <= cut[1]):
+                            row[1] <= (obj.y0 + obj.y1) / 2 <= row[0]
+                            and (obj.x0 + obj.x1) / 2 <= cut[1]
+                        ):
                             cut_text.append((r, cut[0], obj))
                             break
+                        else:
+                            # TODO: add test
+                            if cut == x_cuts[-1]:
+                                cut_text.append((r, cut[0] + 1, obj))
                     elif isinstance(obj, LTAnno):
                         cut_text.append((r, cut[0], obj))
-        elif direction == 'vertical' and not textline.is_empty():
+        elif direction == "vertical" and not textline.is_empty():
-            y_overlap = [j for j, y in enumerate(table.rows) if y[1] <= bbox[3] and bbox[1] <= y[0]]
+            y_overlap = [
-            c_idx = [i for i, c in enumerate(table.cols) if c[0] <= (bbox[0] + bbox[2]) / 2 <= c[1]]
+                j
+                for j, y in enumerate(table.rows)
+                if y[1] <= bbox[3] and bbox[1] <= y[0]
+            ]
+            c_idx = [
+                i
+                for i, c in enumerate(table.cols)
+                if c[0] <= (bbox[0] + bbox[2]) / 2 <= c[1]
+            ]
             c = c_idx[0]
-            y_cuts = [(r, table.cells[r][c].y1) for r in y_overlap if table.cells[r][c].bottom]
+            y_cuts = [
+                (r, table.cells[r][c].y1) for r in y_overlap if table.cells[r][c].bottom
+            ]
             if not y_cuts:
                 y_cuts = [(y_overlap[0], table.cells[-1][c].y1)]
             for obj in textline._objs:
                 col = table.cols[c]
                 for cut in y_cuts:
                     if isinstance(obj, LTChar):
-                        if (col[0] <= (obj.x0 + obj.x1) / 2 <= col[1] and
+                        if (
-                                (obj.y0 + obj.y1) / 2 >= cut[1]):
+                            col[0] <= (obj.x0 + obj.x1) / 2 <= col[1]
+                            and (obj.y0 + obj.y1) / 2 >= cut[1]
+                        ):
                             cut_text.append((cut[0], c, obj))
                             break
+                        else:
+                            # TODO: add test
+                            if cut == y_cuts[-1]:
+                                cut_text.append((cut[0] - 1, c, obj))
                     elif isinstance(obj, LTAnno):
                         cut_text.append((cut[0], c, obj))
     except IndexError:
@@ -416,14 +574,26 @@ def split_textline(table, textline, direction, flag_size=False):
     grouped_chars = []
     for key, chars in groupby(cut_text, itemgetter(0, 1)):
         if flag_size:
-            grouped_chars.append((key[0], key[1], flag_font_size([t[2] for t in chars], direction)))
+            grouped_chars.append(
+                (
+                    key[0],
+                    key[1],
+                    flag_font_size(
+                        [t[2] for t in chars], direction, strip_text=strip_text
+                    ),
+                )
+            )
         else:
             gchars = [t[2].get_text() for t in chars]
-            grouped_chars.append((key[0], key[1], ''.join(gchars).strip('\n')))
+            grouped_chars.append(
+                (key[0], key[1], text_strip("".join(gchars), strip_text))
+            )
     return grouped_chars
 
 
-def get_table_index(table, t, direction, split_text=False, flag_size=False):
+def get_table_index(
+    table, t, direction, split_text=False, flag_size=False, strip_text=""
+):
     """Gets indices of the table cell where given text object lies by
     comparing their y and x-coordinates.
 
@@ -441,6 +611,9 @@ def get_table_index(table, t, direction, split_text=False, flag_size=False):
         Whether or not to highlight a substring using <s></s>
         if its size is different from rest of the string. (Useful for
         super and subscripts)
+    strip_text : str, optional (default: '')
+        Characters that should be stripped from a string before
+        assigning it to a cell.
 
     Returns
     -------
@@ -459,8 +632,9 @@ def get_table_index(table, t, direction, split_text=False, flag_size=False):
     """
     r_idx, c_idx = [-1] * 2
     for r in range(len(table.rows)):
-        if ((t.y0 + t.y1) / 2.0 < table.rows[r][0] and
+        if (t.y0 + t.y1) / 2.0 < table.rows[r][0] and (t.y0 + t.y1) / 2.0 > table.rows[
-                (t.y0 + t.y1) / 2.0 > table.rows[r][1]):
+            r
+        ][1]:
             lt_col_overlap = []
             for c in table.cols:
                 if c[0] <= t.x1 and c[1] >= t.x0:
@@ -470,11 +644,12 @@ def get_table_index(table, t, direction, split_text=False, flag_size=False):
                 else:
                     lt_col_overlap.append(-1)
             if len(list(filter(lambda x: x != -1, lt_col_overlap))) == 0:
-                text = t.get_text().strip('\n')
+                text = t.get_text().strip("\n")
                 text_range = (t.x0, t.x1)
                 col_range = (table.cols[0][0], table.cols[-1][1])
-                warnings.warn("{} {} does not lie in column range {}".format(
+                warnings.warn(
-                    text, text_range, col_range))
+                    f"{text} {text_range} does not lie in column range {col_range}"
+                )
             r_idx = r
             c_idx = lt_col_overlap.index(max(lt_col_overlap))
             break
@@ -495,12 +670,26 @@ def get_table_index(table, t, direction, split_text=False, flag_size=False):
     error = ((X * (y0_offset + y1_offset)) + (Y * (x0_offset + x1_offset))) / charea
 
     if split_text:
-        return split_textline(table, t, direction, flag_size=flag_size), error
+        return (
+            split_textline(
+                table, t, direction, flag_size=flag_size, strip_text=strip_text
+            ),
+            error,
+        )
     else:
         if flag_size:
-            return [(r_idx, c_idx, flag_font_size(t._objs, direction))], error
+            return (
+                [
+                    (
+                        r_idx,
+                        c_idx,
+                        flag_font_size(t._objs, direction, strip_text=strip_text),
+                    )
+                ],
+                error,
+            )
         else:
-            return [(r_idx, c_idx, t.get_text().strip('\n'))], error
+            return [(r_idx, c_idx, text_strip(t.get_text(), strip_text))], error
 
 
 def compute_accuracy(error_weights):
@@ -551,14 +740,20 @@ def compute_whitespace(d):
     r_nempty_cells, c_nempty_cells = [], []
     for i in d:
         for j in i:
-            if j.strip() == '':
+            if j.strip() == "":
                 whitespace += 1
     whitespace = 100 * (whitespace / float(len(d) * len(d[0])))
     return whitespace
 
 
-def get_page_layout(filename, char_margin=1.0, line_margin=0.5, word_margin=0.1,
+def get_page_layout(
-               detect_vertical=True, all_texts=True):
+    filename,
+    char_margin=1.0,
+    line_margin=0.5,
+    word_margin=0.1,
+    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.
@@ -581,16 +776,18 @@ def get_page_layout(filename, char_margin=1.0, line_margin=0.5, word_margin=0.1,
         Dimension of pdf page in the form (width, height).
 
     """
-    with open(filename, 'rb') as f:
+    with open(filename, "rb") as f:
         parser = PDFParser(f)
         document = PDFDocument(parser)
         if not document.is_extractable:
-            raise PDFTextExtractionNotAllowed
+            raise PDFTextExtractionNotAllowed(f"Text extraction is not allowed: {filename}")
-        laparams = LAParams(char_margin=char_margin,
+        laparams = LAParams(
-                            line_margin=line_margin,
+            char_margin=char_margin,
-                            word_margin=word_margin,
+            line_margin=line_margin,
-                            detect_vertical=detect_vertical,
+            word_margin=word_margin,
-                            all_texts=all_texts)
+            detect_vertical=detect_vertical,
+            all_texts=all_texts,
+        )
         rsrcmgr = PDFResourceManager()
         device = PDFPageAggregator(rsrcmgr, laparams=laparams)
         interpreter = PDFPageInterpreter(rsrcmgr, device)
@@ -624,9 +821,11 @@ def get_text_objects(layout, ltype="char", t=None):
     """
     if ltype == "char":
         LTObject = LTChar
-    elif ltype == "lh":
+    elif ltype == "image":
+        LTObject = LTImage
+    elif ltype == "horizontal_text":
         LTObject = LTTextLineHorizontal
-    elif ltype == "lv":
+    elif ltype == "vertical_text":
         LTObject = LTTextLineVertical
     if t is None:
         t = []

docs/_static/csv/table_regions.csv

@@ -0,0 +1,4 @@
+"Età dell’Assicuratoall’epoca del decesso","Misura % dimaggiorazione"
+"18-75","1,00%"
+"76-80","0,50%"
+"81 in poi","0,10%"

docs/_templates/sidebarintro.html

@@ -4,13 +4,13 @@
   </a>
 </p>
 <p>
-<iframe src="https://ghbtns.com/github-btn.html?user=socialcopsdev&repo=camelot&type=watch&count=true&size=large"
+<iframe src="https://ghbtns.com/github-btn.html?user=camelot-dev&repo=camelot&type=watch&count=true&size=large"
   allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
 </p>
 
 <h3>Useful Links</h3>
 <ul>
-  <li><a href="https://github.com/socialcopsdev/camelot">Camelot @ GitHub</a></li>
+  <li><a href="https://github.com/camelot-dev/camelot">Camelot @ GitHub</a></li>
   <li><a href="https://pypi.org/project/camelot-py/">Camelot @ PyPI</a></li>
-  <li><a href="https://github.com/socialcopsdev/camelot/issues">Issue Tracker</a></li>
+  <li><a href="https://github.com/camelot-dev/camelot/issues">Issue Tracker</a></li>
-</ul>
+</ul>

docs/_templates/sidebarlogo.html

@@ -4,6 +4,6 @@
   </a>
 </p>
 <p>
-<iframe src="https://ghbtns.com/github-btn.html?user=socialcopsdev&repo=camelot&type=watch&count=true&size=large"
+<iframe src="https://ghbtns.com/github-btn.html?user=camelot-dev&repo=camelot&type=watch&count=true&size=large"
   allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
-</p>
+</p>

docs/benchmark/lattice/agstat/agstat-data-pdfplumber.csv

@@ -0,0 +1,96 @@
+"0","1","2","3","4","5","6","7","8","9","10"
+"Sl.
+No.","District","n
+o
+i
+t
+a
+l3
+opu2-1hs)
+P1k
+d 20 la
+er n
+cto(I
+ef
+j
+o
+r
+P","%
+8
+8
+o )
+s
+ult t  tkh
+dna
+Aalen l
+v(I
+i
+u
+q
+E",")
+y
+n a
+umptiomentadult/donnes)
+nsres/h t
+ouimk
+Cqga
+al re00n L
+ot  4(I
+T @
+(","menteds, age)nes)
+uireg sewastton
+qn h 
+Reudis &ak
+al cld L
+tnen
+To(Ife(I","","","","",""
+"","","","","","","f
+i
+r
+a
+h
+K","i
+b
+a
+R","l
+a
+t
+o
+T","e
+c
+i
+R","y
+d
+d
+a
+P"
+"1","Balasore","23.65","20.81","3.04","3.47","2.78","0.86","3.64","0.17","0.25"
+"2","Bhadrak","15.34","13.50","1.97","2.25","3.50","0.05","3.55","1.30","1.94"
+"3","Balangir","17.01","14.97","2.19","2.50","6.23","0.10","6.33","3.83","5.72"
+"4","Subarnapur","6.70","5.90","0.86","0.98","4.48","1.13","5.61","4.63","6.91"
+"5","Cuttack","26.63","23.43","3.42","3.91","3.75","0.06","3.81","-0.10","-0.15"
+"6","Jagatsingpur","11.49","10.11","1.48","1.69","2.10","0.02","2.12","0.43","0.64"
+"7","Jajpur","18.59","16.36","2.39","2.73","2.13","0.04","2.17","-0.56","-0.84"
+"8","Kendrapara","14.62","12.87","1.88","2.15","2.60","0.07","2.67","0.52","0.78"
+"9","Dhenkanal","12.13","10.67","1.56","1.78","2.26","0.02","2.28","0.50","0.75"
+"10","Angul","12.93","11.38","1.66","1.90","1.73","0.02","1.75","-0.15","-0.22"
+"11","Ganjam","35.77","31.48","4.60","5.26","4.57","0.00","4.57","-0.69","-1.03"
+"12","Gajapati","5.85","5.15","0.75","0.86","0.68","0.01","0.69","-0.17","-0.25"
+"13","Kalahandi","16.12","14.19","2.07","2.37","5.42","1.13","6.55","4.18","6.24"
+"14","Nuapada","6.18","5.44","0.79","0.90","1.98","0.08","2.06","1.16","1.73"
+"15","Keonjhar","18.42","16.21","2.37","2.71","2.76","0.08","2.84","0.13","0.19"
+"16","Koraput","14.09","12.40","1.81","2.07","2.08","0.34","2.42","0.35","0.52"
+"17","Malkangiri","6.31","5.55","0.81","0.93","1.78","0.04","1.82","0.89","1.33"
+"18","Nabarangpur","12.50","11.00","1.61","1.84","3.26","0.02","3.28","1.44","2.15"
+"19","Rayagada","9.83","8.65","1.26","1.44","1.15","0.03","1.18","-0.26","-0.39"
+"20","Mayurbhanj","25.61","22.54","3.29","3.76","4.90","0.06","4.96","1.20","1.79"
+"21","Kandhamal","7.45","6.56","0.96","1.10","0.70","0.01","0.71","-0.39","-0.58"
+"22","Boudh","4.51","3.97","0.58","0.66","1.73","0.03","1.76","1.10","1.64"
+"23","Puri","17.29","15.22","2.22","2.54","2.45","0.99","3.44","0.90","1.34"
+"24","Khordha","23.08","20.31","2.97","3.39","2.02","0.03","2.05","-1.34","-2.00"
+"25","Nayagarh","9.78","8.61","1.26","1.44","2.10","0.00","2.10","0.66","0.99"
+"26","Sambalpur","10.62","9.35","1.37","1.57","3.45","0.71","4.16","2.59","3.87"
+"27","Bargarh","15.00","13.20","1.93","2.21","6.87","2.65","9.52","7.31","10.91"
+"28","Deogarh","3.18","2.80","0.41","0.47","1.12","0.07","1.19","0.72","1.07"
+"29","Jharsuguda","5.91","5.20","0.76","0.87","0.99","0.01","1.00","0.13","0.19"
+"30","","","18.66","2.72","3.11","4.72","0.02","4.74","1.63","2.43"

docs/benchmark/lattice/column_span_1/column_span_1-data-pdfplumber.csv

@@ -0,0 +1,56 @@
+"0","1","2","3","4","5","6","7"
+"Rate of Accidental Deaths & Suicides and Population Growth During 1967 to 2013","","","","","","",""
+"Sl. 
+No.","Year","Population 
+(in Lakh)","Accidental Deaths","","Suicides","","Percentage 
+Population 
+growth"
+"","","","Incidence","Rate","Incidence","Rate",""
+"(1)","(2)","(3)","(4)","(5)","(6)","(7)","(8)"
+"1.","1967","4999","126762","25.4","38829","7.8","2.2"
+"2.","1968","5111","126232","24.7","40688","8.0","2.2"
+"3.","1969","5225","130755","25.0","43633","8.4","2.2"
+"4.","1970","5343","139752","26.2","48428","9.1","2.3"
+"5.","1971","5512","105601","19.2","43675","7.9","3.2"
+"6.","1972","5635","106184","18.8","43601","7.7","2.2"
+"7.","1973","5759","130654","22.7","40807","7.1","2.2"
+"8.","1974","5883","110624","18.8","46008","7.8","2.2"
+"9.","1975","6008","113016","18.8","42890","7.1","2.1"
+"10.","1976","6136","111611","18.2","41415","6.7","2.1"
+"11.","1977","6258","117338","18.8","39718","6.3","2.0"
+"12.","1978","6384","118594","18.6","40207","6.3","2.0"
+"13.","1979","6510","108987","16.7","38217","5.9","2.0"
+"14.","1980","6636","116912","17.6","41663","6.3","1.9"
+"15.","1981","6840","122221","17.9","40245","5.9","3.1"
+"16.","1982","7052","125993","17.9","44732","6.3","3.1"
+"17.","1983","7204","128576","17.8","46579","6.5","2.2"
+"18.","1984","7356","134628","18.3","50571","6.9","2.1"
+"19.","1985","7509","139657","18.6","52811","7.0","2.1"
+"20.","1986","7661","147023","19.2","54357","7.1","2.0"
+"21.","1987","7814","152314","19.5","58568","7.5","2.0"
+"22.","1988","7966","163522","20.5","64270","8.1","1.9"
+"23.","1989","8118","169066","20.8","68744","8.5","1.9"
+"24.","1990","8270","174401","21.1","73911","8.9","1.9"
+"25.","1991","8496","188003","22.1","78450","9.2","2.7"
+"26.","1992","8677","194910","22.5","80149","9.2","2.1"
+"27.","1993","8838","192357","21.8","84244","9.5","1.9"
+"28.","1994","8997","190435","21.2","89195","9.9","1.8"
+"29.","1995","9160","222487","24.3","89178","9.7","1.8"
+"30.","1996","9319","220094","23.6","88241","9.5","1.7"
+"31.","1997","9552","233903","24.5","95829","10.0","2.5"
+"32.","1998","9709","258409","26.6","104713","10.8","1.6"
+"33.","1999","9866","271918","27.6","110587","11.2","1.6"
+"34.","2000","10021","255883","25.5","108593","10.8","1.6"
+"35.","2001","10270","271019","26.4","108506","10.6","2.5"
+"36.","2002","10506","260122","24.8","110417","10.5","2.3"
+"37.","2003","10682","259625","24.3","110851","10.4","1.7"
+"38.","2004","10856","277263","25.5","113697","10.5","1.6"
+"39.","2005","11028","294175","26.7","113914","10.3","1.6"
+"40.","2006","11198","314704","28.1","118112","10.5","1.5"
+"41.","2007","11366","340794","30.0","122637","10.8","1.5"
+"42.","2008","11531","342309","29.7","125017","10.8","1.4"
+"43.","2009","11694","357021","30.5","127151","10.9","1.4"
+"44.","2010","11858","384649","32.4","134599","11.4","1.4"
+"45.","2011","12102","390884","32.3","135585","11.2","2.1"
+"46.","2012","12134","394982","32.6","135445","11.2","1.0"
+"47.","2013","12288","400517","32.6","134799","11.0","1.0"

docs/benchmark/lattice/rotated/rotated-data-pdfplumber.csv

@@ -0,0 +1,18 @@
+"0","1","2"
+"","e
+bl
+a
+ail
+v
+a
+ 
+t
+o
+n
+ 
+a
+t
+a
+D
+ 
+*",""

docs/benchmark/lattice/twotables_1/twotables_1-data-pdfplumber.csv

@@ -0,0 +1,3 @@
+"0"
+"Sl."
+"No."

docs/benchmark/lattice/twotables_2/twotables_2-data-pdfplumber.csv

@@ -0,0 +1,3 @@
+"0"
+"Table 6 : DISTRIBUTION (%) OF HOUSEHOLDS BY LITERACY STATUS OF"
+"MALE HEAD OF THE HOUSEHOLD"

docs/benchmark/stream/12s0324/12s0324-data-camelot-page-1-table-1.csv

@@ -1,3 +1,7 @@
+"[In thousands (11,062.6 represents 11,062,600) For year ending December 31. Based on Uniform Crime Reporting (UCR)","","","","","","","","",""
+"Program. Represents arrests reported (not charged) by 12,910 agencies with a total population of 247,526,916 as estimated","","","","","","","","",""
+"by the FBI. Some persons may be arrested more than once during a year, therefore, the data in this table, in some cases,","","","","","","","","",""
+"could represent multiple arrests of the same person. See text, this section and source]","","","","","","","","",""
 "","","Total","","","Male","","","Female",""
 "Offense charged","","Under 18","18 years","","Under 18","18 years","","Under 18","18 years"
 "","Total","years","and over","Total","years","and over","Total","years","and over"
@@ -36,3 +40,4 @@
 "Curfew and loitering law violations  ..","91.0","91.0","(X)","63.1","63.1","(X)","28.0","28.0","(X)"
 "Runaways  . . . . . . . .. .. .. .. .. ....","75.8","75.8","(X)","34.0","34.0","(X)","41.8","41.8","(X)"
 "","– Represents zero. X Not applicable. 1 Buying, receiving, possessing stolen property. 2 Except forcible rape and prostitution.","","","","","","","",""
+"","Source: U.S. Department of Justice, Federal Bureau of Investigation, Uniform Crime Reports, Arrests Master Files.","","","","","","","",""

docs/benchmark/stream/12s0324/12s0324-data-camelot-page-1-table-2.csv

@@ -1,3 +1,7 @@
+"","Source: U.S. Department of Justice, Federal Bureau of Investigation, Uniform Crime Reports, Arrests Master Files.","","","",""
+"Table 325. Arrests by Race: 2009","","","","",""
+"[Based on Uniform Crime Reporting (UCR) Program. Represents arrests reported (not charged) by 12,371 agencies","","","","",""
+"with a total population of 239,839,971 as estimated by the FBI. See headnote, Table 324]","","","","",""
 "","","","","American",""
 "Offense charged","","","","Indian/Alaskan","Asian Pacific"
 "","Total","White","Black","Native","Islander"
@@ -34,3 +38,4 @@
 "Curfew and loitering law violations  . .. ... .. ....","89,578","54,439","33,207","872","1,060"
 "Runaways  . . . . . . . .. .. .. .. .. .. .... .. ..... .","73,616","48,343","19,670","1,653","3,950"
 "1 Except forcible rape and prostitution.","","","","",""
+"","Source: U.S. Department of Justice, Federal Bureau of Investigation, “Crime in the United States, Arrests,” September 2010,","","","",""

docs/benchmark/stream/birdisland/birdisland-data-camelot-page-1-table-1.csv

@@ -1,35 +1,43 @@
-"","","","","","SCN","Seed","Yield","Moisture","Lodgingg","g","Stand","","Gross"
+"","2012 BETTER VARIETIES Harvest Report for Minnesota Central  [ MNCE ]2012 BETTER VARIETIES Harvest Report for Minnesota Central  [ MNCE ]","","","","","","","","","","","","ALL SEASON TESTALL SEASON TEST",""
-"Company/Brandpy","","Product/Brand†","Technol.†","Mat.","Resist.","Trmt.†","Bu/A","%","%","","(x 1000)(",")","Income"
+"","Doug Toreen, Renville County, MN 55310          [ BIRD ISLAND ]Doug Toreen, Renville County, MN 55310","","","","","[ BIRD ISLAND ]","","","","","","","1.3 - 2.0 MAT. GROUP1.3 - 2.0 MAT. GROUP",""
-"KrugerKruger","","K2-1901K2 1901","RR2YRR2Y","1.91.9","RR","Ac,PVAc,PV","56.456.4","7.67.6","00","","126.3126.3","","$846$846"
+"PREVPREV. CROP/HERB:","CROP/HERB","C/ S","Corn / Surpass, RoundupR","d","","","","","","","","","","S2MNCE01S2MNCE01"
-"StineStine","","19RA02 §19RA02 §","RR2YRR2Y","1 91.9","RR","CMBCMB","55.355.3","7 67.6","00","","120 0120.0","","$830$830"
+"SOIL DESCRIPTION:","","C","Canisteo clay loam, mod. well drained, non-irrigated","","","","","","","","","","",""
-"WensmanWensman","","W 3190NR2W 3190NR2","RR2YRR2Y","1 91.9","RR","AcAc","54 554.5","7 67.6","00","","119 5119.5","","$818$818"
+"SOIL CONDITIONS:","","","High P, high K, 6.7 pH, 3.9% OM, Low SCN","","","","","","","","","","","30"" ROW SPACING"
-"H ftHefty","","H17Y12H17Y12","RR2YRR2Y","1 71.7","MRMR","II","53 753.7","7 77.7","00","","124 4124.4","","$806$806"
+"TILLAGE/CULTIVATION:TILLAGE/CULTIVATION:","","","conventional w/ fall tillconventional w/ fall till","","","","","","","","","","",""
-"Dyna-Gro","","S15RY53","RR2Y","1.5","R","Ac","53.6","7.7","0","","126.8","","$804"
+"PEST MANAGEMENT:PEST MANAGEMENT:","","Roundup twiceRoundup twice","","","","","","","","","","","",""
-"LG SeedsLG Seeds","","C2050R2C2050R2","RR2YRR2Y","2.12.1","RR","AcAc","53.653.6","7.77.7","00","","123.9123.9","","$804$804"
+"SEEDED - RATE:","","May 15M15","140,000 /A140 000 /A","","","","","","","","TOP 30 foTOP 30 for YIELD of 63 TESTED","","YIELD of 63 TESTED",""
-"Titan ProTitan Pro","","19M4219M42","RR2YRR2Y","1.91.9","RR","CMBCMB","53.653.6","7.77.7","00","","121.0121.0","","$804$804"
+"HARVESTEDHARVESTED - STAND:","STAND","O t 3Oct 3","122 921 /A122,921 /A","","","","","","","","","AVERAGE of (3) REPLICATIONSAVERAGE of (3) REPLICATIONS","",""
-"StineStine","","19RA02 (2) §19RA02 (2) §","RR2YRR2Y","1 91.9","RR","CMBCMB","53 453.4","7 77.7","00","","123 9123.9","","$801$801"
+"","","","","","","SCN","Seed","Yield","Moisture","Lodgingg","g","Stand","","Gross"
-"AsgrowAsgrow","","AG1832 §AG1832 §","RR2YRR2Y","1 81.8","MRMR","Ac PVAc,PV","52 952.9","7 77.7","00","","122 0122.0","","$794$794"
+"","Company/Brandpy","Product/Brand†","","Technol.†","Mat.","Resist.","Trmt.†","Bu/A","%","%","","(x 1000)(",")","Income"
-"Prairie Brandiid","","PB-1566R2662","RR2Y2","1.5","R","CMB","52.8","7.7","0","","122.9","","$792$"
+"","KrugerKruger","K2-1901K2 1901","","RR2YRR2Y","1.91.9","RR","Ac,PVAc,PV","56.456.4","7.67.6","00","","126.3126.3","","$846$846"
-"Channel","","1901R2","RR2Y","1.9","R","Ac,PV,","52.8","7.6","0","","123.4","","$791$"
+"","StineStine","19RA02 §19RA02 §","","RR2YRR2Y","1 91.9","RR","CMBCMB","55.355.3","7 67.6","00","","120 0120.0","","$830$830"
-"Titan ProTitan Pro","","20M120M1","RR2YRR2Y","2.02.0","RR","AmAm","52.552.5","7.57.5","00","","124.4124.4","","$788$788"
+"","WensmanWensman","W 3190NR2W 3190NR2","","RR2YRR2Y","1 91.9","RR","AcAc","54 554.5","7 67.6","00","","119 5119.5","","$818$818"
-"KrugerKruger","","K2-2002K2-2002","RR2YRR2Y","2 02.0","RR","Ac PVAc,PV","52 452.4","7 97.9","00","","125 4125.4","","$786$786"
+"","H ftHefty","H17Y12H17Y12","","RR2YRR2Y","1 71.7","MRMR","II","53 753.7","7 77.7","00","","124 4124.4","","$806$806"
-"ChannelChannel","","1700R21700R2","RR2YRR2Y","1 71.7","RR","Ac PVAc,PV","52 352.3","7 97.9","00","","123 9123.9","","$784$784"
+"","Dyna-Gro","S15RY53","","RR2Y","1.5","R","Ac","53.6","7.7","0","","126.8","","$804"
-"H ftHefty","","H16Y11H16Y11","RR2YRR2Y","1 61.6","MRMR","II","51 451.4","7 67.6","00","","123 9123.9","","$771$771"
+"","LG SeedsLG Seeds","C2050R2C2050R2","","RR2YRR2Y","2.12.1","RR","AcAc","53.653.6","7.77.7","00","","123.9123.9","","$804$804"
-"Anderson","","162R2Y","RR2Y","1.6","R","None","51.3","7.5","0","","119.5","","$770"
+"","Titan ProTitan Pro","19M4219M42","","RR2YRR2Y","1.91.9","RR","CMBCMB","53.653.6","7.77.7","00","","121.0121.0","","$804$804"
-"Titan ProTitan Pro","","15M2215M22","RR2YRR2Y","1.51.5","RR","CMBCMB","51.351.3","7.87.8","00","","125.4125.4","","$769$769"
+"","StineStine","19RA02 (2) §19RA02 (2) §","","RR2YRR2Y","1 91.9","RR","CMBCMB","53 453.4","7 77.7","00","","123 9123.9","","$801$801"
-"DairylandDairyland","","DSR-1710R2YDSR-1710R2Y","RR2YRR2Y","1 71.7","RR","CMBCMB","51 351.3","7 77.7","00","","122 0122.0","","$769$769"
+"","AsgrowAsgrow","AG1832 §AG1832 §","","RR2YRR2Y","1 81.8","MRMR","Ac PVAc,PV","52 952.9","7 77.7","00","","122 0122.0","","$794$794"
-"HeftyHefty","","H20R3H20R3","RR2YRR2Y","2 02.0","MRMR","II","50 550.5","8 28.2","00","","121 0121.0","","$757$757"
+"","Prairie Brandiid","PB-1566R2662","","RR2Y2","1.5","R","CMB","52.8","7.7","0","","122.9","","$792$"
-"PPrairie BrandiiBd","","PB 1743R2PB-1743R2","RR2YRR2Y","1 71.7","RR","CMBCMB","50 250.2","7 77.7","00","","125 8125.8","","$752$752"
+"","Channel","1901R2","","RR2Y","1.9","R","Ac,PV,","52.8","7.6","0","","123.4","","$791$"
-"Gold Country","","1741","RR2Y","1.7","R","Ac","50.1","7.8","0","","123.9","","$751"
+"","Titan ProTitan Pro","20M120M1","","RR2YRR2Y","2.02.0","RR","AmAm","52.552.5","7.57.5","00","","124.4124.4","","$788$788"
-"Trelaye ay","","20RR4303","RR2Y","2.00","R","Ac,Exc,","49.99 9","7.66","00","","127.88","","$749$9"
+"","KrugerKruger","K2-2002K2-2002","","RR2YRR2Y","2 02.0","RR","Ac PVAc,PV","52 452.4","7 97.9","00","","125 4125.4","","$786$786"
-"HeftyHefty","","H14R3H14R3","RR2YRR2Y","1.41.4","MRMR","II","49.749.7","7.77.7","00","","122.9122.9","","$746$746"
+"","ChannelChannel","1700R21700R2","","RR2YRR2Y","1 71.7","RR","Ac PVAc,PV","52 352.3","7 97.9","00","","123 9123.9","","$784$784"
-"Prairie BrandPrairie Brand","","PB-2099NRR2PB-2099NRR2","RR2YRR2Y","2 02.0","RR","CMBCMB","49 649.6","7 87.8","00","","126 3126.3","","$743$743"
+"","H ftHefty","H16Y11H16Y11","","RR2YRR2Y","1 61.6","MRMR","II","51 451.4","7 67.6","00","","123 9123.9","","$771$771"
-"WensmanWensman","","W 3174NR2W 3174NR2","RR2YRR2Y","1 71.7","RR","AcAc","49 349.3","7 67.6","00","","122 5122.5","","$740$740"
+"","Anderson","162R2Y","","RR2Y","1.6","R","None","51.3","7.5","0","","119.5","","$770"
-"KKruger","","K2 1602K2-1602","RR2YRR2Y","1 61.6","R","Ac,PV","48.78","7.66","00","","125.412","","$731$31"
+"","Titan ProTitan Pro","15M2215M22","","RR2YRR2Y","1.51.5","RR","CMBCMB","51.351.3","7.87.8","00","","125.4125.4","","$769$769"
-"NK Brand","","S18-C2 §§","RR2Y","1.8","R","CMB","48.7","7.7","0","","126.8","","$731$"
+"","DairylandDairyland","DSR-1710R2YDSR-1710R2Y","","RR2YRR2Y","1 71.7","RR","CMBCMB","51 351.3","7 77.7","00","","122 0122.0","","$769$769"
-"KrugerKruger","","K2-1902K2 1902","RR2YRR2Y","1.91.9","RR","Ac,PVAc,PV","48.748.7","7.57.5","00","","124.4124.4","","$730$730"
+"","HeftyHefty","H20R3H20R3","","RR2YRR2Y","2 02.0","MRMR","II","50 550.5","8 28.2","00","","121 0121.0","","$757$757"
-"Prairie BrandPrairie Brand","","PB-1823R2PB-1823R2","RR2YRR2Y","1 81.8","RR","NoneNone","48 548.5","7 67.6","00","","121 0121.0","","$727$727"
+"","PPrairie BrandiiBd","PB 1743R2PB-1743R2","","RR2YRR2Y","1 71.7","RR","CMBCMB","50 250.2","7 77.7","00","","125 8125.8","","$752$752"
-"Gold CountryGold Country","","15411541","RR2YRR2Y","1 51.5","RR","AcAc","48 448.4","7 67.6","00","","110 4110.4","","$726$726"
+"","Gold Country","1741","","RR2Y","1.7","R","Ac","50.1","7.8","0","","123.9","","$751"
-"","","","","","","Test Average  =","47 647.6","7 77.7","00","","122 9122.9","","$713$713"
+"","Trelaye ay","20RR4303","","RR2Y","2.00","R","Ac,Exc,","49.99 9","7.66","00","","127.88","","$749$9"
-"","","","","","","LSD (0.10)  =","5.7","0.3","ns","","37.8","","566.4"
+"","HeftyHefty","H14R3H14R3","","RR2YRR2Y","1.41.4","MRMR","II","49.749.7","7.77.7","00","","122.9122.9","","$746$746"
-"","F.I.R.S.T. Managerg","","","","","C.V.  =","8.8","2.9","","","56.4","","846.2"
+"","Prairie BrandPrairie Brand","PB-2099NRR2PB-2099NRR2","","RR2YRR2Y","2 02.0","RR","CMBCMB","49 649.6","7 87.8","00","","126 3126.3","","$743$743"
+"","WensmanWensman","W 3174NR2W 3174NR2","","RR2YRR2Y","1 71.7","RR","AcAc","49 349.3","7 67.6","00","","122 5122.5","","$740$740"
+"","KKruger","K2 1602K2-1602","","RR2YRR2Y","1 61.6","R","Ac,PV","48.78","7.66","00","","125.412","","$731$31"
+"","NK Brand","S18-C2 §§","","RR2Y","1.8","R","CMB","48.7","7.7","0","","126.8","","$731$"
+"","KrugerKruger","K2-1902K2 1902","","RR2YRR2Y","1.91.9","RR","Ac,PVAc,PV","48.748.7","7.57.5","00","","124.4124.4","","$730$730"
+"","Prairie BrandPrairie Brand","PB-1823R2PB-1823R2","","RR2YRR2Y","1 81.8","RR","NoneNone","48 548.5","7 67.6","00","","121 0121.0","","$727$727"
+"","Gold CountryGold Country","15411541","","RR2YRR2Y","1 51.5","RR","AcAc","48 448.4","7 67.6","00","","110 4110.4","","$726$726"
+"","","","","","","","Test Average  =","47 647.6","7 77.7","00","","122 9122.9","","$713$713"
+"","","","","","","","LSD (0.10)  =","5.7","0.3","ns","","37.8","","566.4"

docs/benchmark/stream/birdisland/birdisland-data-camelot-page-1-table-2.csv

@@ -0,0 +1,39 @@
+"TILLAGE/CULTIVATION:TILLAGE/CULTIVATION:","","conventional w/ fall tillconventional w/ fall till","","","","","","","","","","",""
+"PEST MANAGEMENT:PEST MANAGEMENT:","","Roundup twiceRoundup twice","","","","","","","","","","",""
+"SEEDED - RATE:","","May 15M15","140,000 /A140 000 /A","","","","","","","TOP 30 foTOP 30 for YIELD of 63 TESTED","","YIELD of 63 TESTED",""
+"HARVESTEDHARVESTED - STAND:STAND","","O t 3Oct 3","122 921 /A122,921 /A","","","","","","","","AVERAGE of (3) REPLICATIONSAVERAGE of (3) REPLICATIONS","",""
+"","","","","","SCN","Seed","Yield","Moisture","Lodgingg","g","Stand","","Gross"
+"Company/Brandpy","","Product/Brand†","Technol.†","Mat.","Resist.","Trmt.†","Bu/A","%","%","","(x 1000)(",")","Income"
+"KrugerKruger","","K2-1901K2 1901","RR2YRR2Y","1.91.9","RR","Ac,PVAc,PV","56.456.4","7.67.6","00","","126.3126.3","","$846$846"
+"StineStine","","19RA02 §19RA02 §","RR2YRR2Y","1 91.9","RR","CMBCMB","55.355.3","7 67.6","00","","120 0120.0","","$830$830"
+"WensmanWensman","","W 3190NR2W 3190NR2","RR2YRR2Y","1 91.9","RR","AcAc","54 554.5","7 67.6","00","","119 5119.5","","$818$818"
+"H ftHefty","","H17Y12H17Y12","RR2YRR2Y","1 71.7","MRMR","II","53 753.7","7 77.7","00","","124 4124.4","","$806$806"
+"Dyna-Gro","","S15RY53","RR2Y","1.5","R","Ac","53.6","7.7","0","","126.8","","$804"
+"LG SeedsLG Seeds","","C2050R2C2050R2","RR2YRR2Y","2.12.1","RR","AcAc","53.653.6","7.77.7","00","","123.9123.9","","$804$804"
+"Titan ProTitan Pro","","19M4219M42","RR2YRR2Y","1.91.9","RR","CMBCMB","53.653.6","7.77.7","00","","121.0121.0","","$804$804"
+"StineStine","","19RA02 (2) §19RA02 (2) §","RR2YRR2Y","1 91.9","RR","CMBCMB","53 453.4","7 77.7","00","","123 9123.9","","$801$801"
+"AsgrowAsgrow","","AG1832 §AG1832 §","RR2YRR2Y","1 81.8","MRMR","Ac PVAc,PV","52 952.9","7 77.7","00","","122 0122.0","","$794$794"
+"Prairie Brandiid","","PB-1566R2662","RR2Y2","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 ProTitan Pro","","20M120M1","RR2YRR2Y","2.02.0","RR","AmAm","52.552.5","7.57.5","00","","124.4124.4","","$788$788"
+"KrugerKruger","","K2-2002K2-2002","RR2YRR2Y","2 02.0","RR","Ac PVAc,PV","52 452.4","7 97.9","00","","125 4125.4","","$786$786"
+"ChannelChannel","","1700R21700R2","RR2YRR2Y","1 71.7","RR","Ac PVAc,PV","52 352.3","7 97.9","00","","123 9123.9","","$784$784"
+"H ftHefty","","H16Y11H16Y11","RR2YRR2Y","1 61.6","MRMR","II","51 451.4","7 67.6","00","","123 9123.9","","$771$771"
+"Anderson","","162R2Y","RR2Y","1.6","R","None","51.3","7.5","0","","119.5","","$770"
+"Titan ProTitan Pro","","15M2215M22","RR2YRR2Y","1.51.5","RR","CMBCMB","51.351.3","7.87.8","00","","125.4125.4","","$769$769"
+"DairylandDairyland","","DSR-1710R2YDSR-1710R2Y","RR2YRR2Y","1 71.7","RR","CMBCMB","51 351.3","7 77.7","00","","122 0122.0","","$769$769"
+"HeftyHefty","","H20R3H20R3","RR2YRR2Y","2 02.0","MRMR","II","50 550.5","8 28.2","00","","121 0121.0","","$757$757"
+"PPrairie BrandiiBd","","PB 1743R2PB-1743R2","RR2YRR2Y","1 71.7","RR","CMBCMB","50 250.2","7 77.7","00","","125 8125.8","","$752$752"
+"Gold Country","","1741","RR2Y","1.7","R","Ac","50.1","7.8","0","","123.9","","$751"
+"Trelaye ay","","20RR4303","RR2Y","2.00","R","Ac,Exc,","49.99 9","7.66","00","","127.88","","$749$9"
+"HeftyHefty","","H14R3H14R3","RR2YRR2Y","1.41.4","MRMR","II","49.749.7","7.77.7","00","","122.9122.9","","$746$746"
+"Prairie BrandPrairie Brand","","PB-2099NRR2PB-2099NRR2","RR2YRR2Y","2 02.0","RR","CMBCMB","49 649.6","7 87.8","00","","126 3126.3","","$743$743"
+"WensmanWensman","","W 3174NR2W 3174NR2","RR2YRR2Y","1 71.7","RR","AcAc","49 349.3","7 67.6","00","","122 5122.5","","$740$740"
+"KKruger","","K2 1602K2-1602","RR2YRR2Y","1 61.6","R","Ac,PV","48.78","7.66","00","","125.412","","$731$31"
+"NK Brand","","S18-C2 §§","RR2Y","1.8","R","CMB","48.7","7.7","0","","126.8","","$731$"
+"KrugerKruger","","K2-1902K2 1902","RR2YRR2Y","1.91.9","RR","Ac,PVAc,PV","48.748.7","7.57.5","00","","124.4124.4","","$730$730"
+"Prairie BrandPrairie Brand","","PB-1823R2PB-1823R2","RR2YRR2Y","1 81.8","RR","NoneNone","48 548.5","7 67.6","00","","121 0121.0","","$727$727"
+"Gold CountryGold Country","","15411541","RR2YRR2Y","1 51.5","RR","AcAc","48 448.4","7 67.6","00","","110 4110.4","","$726$726"
+"","","","","","","Test Average  =","47 647.6","7 77.7","00","","122 9122.9","","$713$713"
+"","","","","","","LSD (0.10)  =","5.7","0.3","ns","","37.8","","566.4"
+"","F.I.R.S.T. Managerg","","","","","C.V.  =","8.8","2.9","","","56.4","","846.2"

docs/benchmark/stream/district_health/district_health-data-pdfplumber.csv

@@ -0,0 +1,66 @@
+"0","1","2","3","4"
+"","DLHS-4 (2012-13)","","DLHS-3 (2007-08)",""
+"Indicators","TOTAL","RURAL","TOTAL","RURAL"
+"Child feeding practices (based on last-born child in the reference period) (%)","","","",""
+"Children age 0-5 months exclusively breastfed9 ..........................................................................  76.9  80.0 
+Children age 6-9 months receiving solid/semi-solid food and breast milk ....................................  78.6  75.0 
+Children age 12-23 months receiving breast feeding along with complementary feeding ...........  31.8  24.2   
+Children age 6-35 months exclusively breastfed for at least 6 months ........................................  4.7  3.4 
+Children under 3 years breastfed within one hour of birth ............................................................  42.9  46.5","","","NA","NA"
+"","","","85.9","89.3"
+"","","","NA","NA"
+"","","","30.0","27.7"
+"","","","50.6","52.9"
+"Birth Weight (%) (age below 36 months)","","","",""
+"Percentage of Children weighed at birth ......................................................................................  38.8  41.0  NA  NA 
+Percentage of Children with low birth weight (out of those who weighted) ( below 2.5 kg) .........  12.8  14.6  NA  NA","","","",""
+"Awareness about Diarrhoea (%)","","","",""
+"Women know about  what to do when a child gets  diarrhoea .....................................................  96.3  96.2","","","94.4","94.2"
+"Awareness about ARI (%)","","","",""
+"Women aware about danger signs of ARI10 .................................................................................  55.9  59.7","","","32.8","34.7"
+"Treatment of childhood diseases (based on last two surviving children born during the","","","",""
+"","","","",""
+"reference period) (%)","","","",""
+"","","","",""
+"Prevalence of diarrhoea in last 2 weeks for under 5 years old children .......................................  1.6  1.3  6.5  7.0 
+Children with diarrhoea in the last 2 weeks and received ORS11 .................................................  100.0  100.0  54.8  53.3 
+Children with diarrhoea in the last 2 weeks and sought advice/treatment ...................................  100.0  50.0  72.9  73.3 
+Prevalence of ARI in last 2 weeks for under 5 years old children ............................................   4.3  3.9  3.9  4.2 
+Children with acute respiratory infection or fever in last 2 weeks and sought advice/treatment  37.5  33.3  69.8  68.0 
+Children with diarrhoea in the last 2 weeks given Zinc along with ORS ......................................  66.6  50.0  NA  NA","","","6.5","7.0"
+"","","","54.8","53.3"
+"","","","72.9","73.3"
+"","","","3.9","4.2"
+"","","","69.8","68.0"
+"Awareness of RTI/STI and HIV/AIDS (%)","","","",""
+"Women who have heard of RTI/STI .............................................................................................  55.8  57.1 
+Women who have heard of HIV/AIDS ..........................................................................................  98.9  99.0 
+Women who have any symptoms of RTI/STI  ..............................................................................  13.9  13.5 
+Women who know the place to go for testing of HIV/AIDS12 .......................................................  59.9  57.1 
+Women underwent test for detecting HIV/AIDS12 ........................................................................  37.3  36.8","","","34.8","38.2"
+"","","","98.3","98.1"
+"","","","15.6","16.1"
+"","","","48.6","46.3"
+"","","","14.1","12.3"
+"Utilization of Government Health Services (%)","","","",""
+"Antenatal care ..............................................................................................................................  69.7  66.7  79.0  81.0 
+Treatment for pregnancy complications .......................................................................................  57.1  59.3  88.0  87.8 
+Treatment for post-delivery complications ...................................................................................  33.3  33.3  68.4  68.4 
+Treatment for vaginal discharge ...................................................................................................  20.0  25.0  73.9  71.4 
+Treatment for children with diarrhoea13 ........................................................................................  50.0  100.0  NA  NA 
+Treatment for children with ARI13 .................................................................................................  NA  NA  NA  NA","","","79.0","81.0"
+"","","","88.0","87.8"
+"","","","68.4","68.4"
+"","","","73.9","71.4"
+"Birth Registration (%)","","","",""
+"Children below age 5 years having birth registration done ..........................................................  40.6  44.3  NA  NA 
+Children below age 5 years who received birth certificate (out of those registered) ....................  65.9  63.6  NA  NA","","","",""
+"Personal Habits (age 15 years and above) (%)","","","",""
+"Men who use any kind of smokeless tobacco  .............................................................................  74.6  74.2  NA  NA 
+Women who use any kind of smokeless tobacco ........................................................................  59.5  58.9  NA  NA 
+Men who smoke ...........................................................................................................................  56.0  56.4  NA  NA 
+Women who smoke ......................................................................................................................  18.4  18.0  NA  NA 
+Men who consume alcohol ...........................................................................................................  58.4  58.2  NA  NA 
+Women who consume alcohol .....................................................................................................  10.9  9.3  NA  NA","","","",""
+"9 Children Who were given nothing but breast milk till the survey date  10Acute Respiratory Infections11Oral Rehydration Solutions/Salts.12Based on","","","",""
+"the women who have heard of HIV/AIDS.13 Last two weeks","","","",""

docs/benchmark/stream/health/health-data-pdfplumber.csv

@@ -0,0 +1,44 @@
+"0","1","2","3","4","5","6","7","8","9","10","11","12","13","14","15","16","17","18","19","20","21","22","23"
+"","Table: 5            Public Health Outlay 2012-13 (Budget Estimates)        (Rs. in 000)","","","","","","","","","","","","","","","","","","","","","",""
+"","States-A","","","Revenue","","","","","","Capital","","","","","","Total","","","Others(1)","","","Total",""
+"","","","","","","","","","","","","","","","","Revenue &","","","","","","",""
+"","","","Medical &  Family  Medical &  Family 
+Public  Welfare  Public  Welfare 
+Health  Health","","","","","","","","","","","","","","","","","","","",""
+"","","","","","","","","","","","","","","","","Capital","","","","","","",""
+"","","","","","","","","","","","","","","","","","","","","","","",""
+"","Andhra Pradesh","","","47,824,589","","","9,967,837","","","1,275,000","","","15,000","","","59,082,426","","","14,898,243","","","73,980,669",""
+"","","","","","","","","","","","","","","","","","","","","","","",""
+"Arunachal Pradesh   2,241,609  107,549  23,000  0  2,372,158  86,336  2,458,494","","","","","","","","","","","","","","","","","","","","","","",""
+"","Assam","","","14,874,821","","","2,554,197","","","161,600","","","0","","","17,590,618","","","4,408,505","","","21,999,123",""
+"","","","","","","","","","","","","","","","","","","","","","","",""
+"Bihar   21,016,708  4,332,141  5,329,000  0  30,677,849  2,251,571  32,929,420","","","","","","","","","","","","","","","","","","","","","","",""
+"","Chhattisgarh","","","11,427,311","","","1,415,660","","","2,366,592","","","0","","","15,209,563","","","311,163","","","15,520,726",""
+"","","","","","","","","","","","","","","","","","","","","","","",""
+"Delhi  28,084,780  411,700  4,550,000  0  33,046,480  5,000  33,051,480","","","","","","","","","","","","","","","","","","","","","","",""
+"","Goa","","","4,055,567","","","110,000","","","330,053","","","0","","","4,495,620","","","12,560","","","4,508,180",""
+"","","","","","","","","","","","","","","","","","","","","","","",""
+"Gujarat  26,328,400  6,922,900  12,664,000  42,000  45,957,300  455,860  46,413,160","","","","","","","","","","","","","","","","","","","","","","",""
+"","Haryana","","","15,156,681","","","1,333,527","","","40,100","","","0","","","16,530,308","","","1,222,698","","","17,753,006",""
+"","","","","","","","","","","","","","","","","","","","","","","",""
+"Himachal Pradesh  8,647,229  1,331,529  580,800  0  10,559,558  725,315  11,284,873","","","","","","","","","","","","","","","","","","","","","","",""
+"","Jammu & Kashmir","","","14,411,984","","","270,840","","","3,188,550","","","0","","","17,871,374","","","166,229","","","18,037,603",""
+"","","","","","","","","","","","","","","","","","","","","","","",""
+"Jharkhand  8,185,079  3,008,077  3,525,558  0  14,718,714  745,139  15,463,853","","","","","","","","","","","","","","","","","","","","","","",""
+"","Karnataka","","","34,939,843","","","4,317,801","","","3,669,700","","","0","","","42,927,344","","","631,088","","","43,558,432",""
+"","","","","","","","","","","","","","","","","","","","","","","",""
+"Kerala  27,923,965  3,985,473  929,503  0  32,838,941  334,640  33,173,581","","","","","","","","","","","","","","","","","","","","","","",""
+"","Madhya Pradesh","","","28,459,540","","","4,072,016","","","3,432,711","","","0","","","35,964,267","","","472,139","","","36,436,406",""
+"","","","","","","","","","","","","","","","","","","","","","","",""
+"Maharashtra  55,011,100  6,680,721  5,038,576  0  66,730,397  313,762  67,044,159","","","","","","","","","","","","","","","","","","","","","","",""
+"","Manipur","","","2,494,600","","","187,700","","","897,400","","","0","","","3,579,700","","","0","","","3,579,700",""
+"","","","","","","","","","","","","","","","","","","","","","","",""
+"Meghalaya  2,894,093  342,893  705,500  5,000  3,947,486  24,128  3,971,614","","","","","","","","","","","","","","","","","","","","","","",""
+"","Mizoram","","","1,743,501","","","84,185","","","10,250","","","0","","","1,837,936","","","17,060","","","1,854,996",""
+"","","","","","","","","","","","","","","","","","","","","","","",""
+"Nagaland   2,368,724  204,329  226,400  0  2,799,453  783,054  3,582,507","","","","","","","","","","","","","","","","","","","","","","",""
+"","Odisha","","","14,317,179","","","2,552,292","","","1,107,250","","","0","","","17,976,721","","","451,438","","","18,428,159",""
+"","","","","","","","","","","","","","","","","","","","","","","",""
+"Puducherry  4,191,757  52,249  192,400  0  4,436,406  2,173  4,438,579","","","","","","","","","","","","","","","","","","","","","","",""
+"","Punjab","","","19,775,485","","","2,208,343","","","2,470,882","","","0","","","24,454,710","","","1,436,522","","","25,891,232",""
+"","","","","","","","","","","","","","","","","","","","","","","",""

docs/benchmark/stream/missing_values/missing_values-data-pdfplumber.csv

@@ -0,0 +1,71 @@
+"0","1","2","3","4"
+"","DLHS-4 (2012-13)","","DLHS-3 (2007-08)",""
+"Indicators","TOTAL","RURAL","TOTAL","RURAL"
+"Reported Prevalence of Morbidity","","","",""
+"Any Injury .....................................................................................................................................   1.9  2.1   
+Acute Illness .................................................................................................................................   4.5  5.6   
+Chronic Illness ..............................................................................................................................   5.1  4.1","","","",""
+"","","","",""
+"","","","",""
+"Reported Prevalence of Chronic Illness during last one year (%)","","","",""
+"Disease of respiratory system ......................................................................................................   11.7  15.0   
+Disease of cardiovascular system ................................................................................................   8.9  9.3   
+Persons suffering from tuberculosis .............................................................................................   2.2  1.5","","","",""
+"","","","",""
+"","","","",""
+"Anaemia Status by Haemoglobin Level14 (%)","","","",""
+"Children (6-59 months) having anaemia ......................................................................................   68.5  71.9   
+Children (6-59 months) having severe anaemia ..........................................................................   6.7  9.4   
+Children (6-9 Years) having anaemia - Male ................................................................................   67.1  71.4   
+Children (6-9 Years) having severe anaemia - Male ....................................................................   4.4  2.4   
+Children (6-9 Years) having anaemia - Female ...........................................................................   52.4  48.8   
+Children (6-9 Years) having severe anaemia - Female ................................................................   1.2  0.0   
+Children (6-14 years) having  anaemia - Male .............................................................................   50.8  62.5   
+Children (6-14 years) having severe anaemia - Male ..................................................................   3.7  3.6   
+Children (6-14 years) having  anaemia - Female .........................................................................   48.3  50.0   
+Children (6-14 years) having severe anaemia - Female ..............................................................   4.3  6.1   
+Children (10-19 Years15) having anaemia - Male .........................................................................   37.9  51.2   
+Children (10-19 Years15) having severe anaemia - Male .............................................................   3.5  4.0   
+Children (10-19 Years15) having anaemia - Female .....................................................................   46.6  52.1   
+Children (10-19 Years15) having severe anaemia - Female .........................................................   6.4  6.5   
+Adolescents (15-19 years) having  anaemia ................................................................................   39.4  46.5   
+Adolescents (15-19 years) having severe anaemia .....................................................................   5.4  5.1   
+Pregnant women (15-49 aged) having anaemia ..........................................................................   48.8  51.5   
+Pregnant women (15-49 aged) having severe anaemia ..............................................................   7.1  8.8   
+Women (15-49 aged) having anaemia .........................................................................................   45.2  51.7   
+Women (15-49 aged) having severe anaemia .............................................................................   4.8  5.9   
+Persons (20 years and above) having anaemia ...........................................................................   37.8  42.1   
+Persons (20 years and above) having Severe anaemia ..............................................................   4.6  4.8","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"","","","",""
+"Blood Sugar Level (age 18 years and above) (%)","","","",""
+"Blood Sugar Level >140 mg/dl (high) ...........................................................................................   12.9  11.1   
+Blood Sugar Level >160 mg/dl (very high) ...................................................................................   7.0  5.1","","","",""
+"","","","",""
+"Hypertension (age 18 years and above) (%)","","","",""
+"Above Normal Range (Systolic >140 mm of Hg & Diastolic >90 mm of Hg )  ..............................   23.8  22.8   
+Moderately High (Systolic >160 mm of Hg & Diastolic >100 mm of Hg ) .....................................   8.2  7.1   
+Very High (Systolic >180 mm of Hg & Diastolic >110 mm of Hg ) ...............................................   3.7  3.1","","","",""
+"","","","",""
+"","","","",""
+"14 Any anaemia below 11g/dl, severe anaemia below 7g/dl. 15 Excluding age group 19 years","","","",""
+"Chronic Illness :Any person with symptoms persisting for longer than one month is defined as suffering from chronic illness","","","",""

docs/conf.py

@@ -63,7 +63,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Camelot'
-copyright = u'2018, <a href="https://socialcops.com" target="_blank">SocialCops</a>'
+copyright = u'2019, Camelot Developers'
 author = u'Vinayak Mehta'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -137,7 +137,7 @@ html_theme = 'alabaster'
 # documentation.
 html_theme_options = {
     'show_powered_by': False,
-    'github_user': 'socialcopsdev',
+    'github_user': 'camelot-dev',
     'github_repo': 'camelot',
     'github_banner': True,
     'show_related': False,

docs/dev/contributing.rst

@@ -7,7 +7,7 @@ If you're reading this, you're probably looking to contributing to Camelot. *Tim
 
 This document will help you get started with contributing documentation, code, testing and filing issues. If you have any questions, feel free to reach out to `Vinayak Mehta`_, the author and maintainer.
 
-.. _Vinayak Mehta: https://vinayak-mehta.github.io
+.. _Vinayak Mehta: https://www.vinayakmehta.com
 
 Code Of Conduct
 ---------------
@@ -29,15 +29,15 @@ Your first contribution
 
 A great way to start contributing to Camelot is to pick an issue tagged with the `help wanted`_ or the `good first issue`_ tags. If you're unable to find a good first issue, feel free to contact the maintainer.
 
-.. _help wanted: https://github.com/socialcopsdev/camelot/labels/help%20wanted
+.. _help wanted: https://github.com/camelot-dev/camelot/labels/help%20wanted
-.. _good first issue: https://github.com/socialcopsdev/camelot/labels/good%20first%20issue
+.. _good first issue: https://github.com/camelot-dev/camelot/labels/good%20first%20issue
 
 Setting up a development environment
 ------------------------------------
 
 To install the dependencies needed for development, you can use pip::
 
-    $ pip install camelot-py[dev]
+    $ pip install "camelot-py[dev]"
 
 Alternatively, you can clone the project repository, and install using pip::
 
@@ -51,7 +51,7 @@ Submit a pull request
 
 The preferred workflow for contributing to Camelot is to fork the `project repository`_ on GitHub, clone, develop on a branch and then finally submit a pull request. Here are the steps:
 
-.. _project repository: https://github.com/socialcopsdev/camelot
+.. _project repository: https://github.com/camelot-dev/camelot
 
 1. Fork the project repository. Click on the ‘Fork’ button near the top of the page. This creates a copy of the code under your account on the GitHub.
 
@@ -134,7 +134,7 @@ Filing Issues
 
 We use `GitHub issues`_ to keep track of all issues and pull requests. Before opening an issue (which asks a question or reports a bug), please use GitHub search to look for existing issues (both open and closed) that may be similar.
 
-.. _GitHub issues: https://github.com/socialcopsdev/camelot/issues
+.. _GitHub issues: https://github.com/camelot-dev/camelot/issues
 
 Questions
 ^^^^^^^^^

docs/index.rst

@@ -8,15 +8,15 @@ Camelot: PDF Table Extraction for Humans
 
 Release v\ |version|. (:ref:`Installation <install>`)
 
-.. image:: https://travis-ci.org/socialcopsdev/camelot.svg?branch=master
+.. image:: https://travis-ci.org/camelot-dev/camelot.svg?branch=master
-    :target: https://travis-ci.org/socialcopsdev/camelot
+    :target: https://travis-ci.org/camelot-dev/camelot
 
 .. image:: https://readthedocs.org/projects/camelot-py/badge/?version=master
     :target: https://camelot-py.readthedocs.io/en/master/
     :alt: Documentation Status
 
-.. image:: https://codecov.io/github/socialcopsdev/camelot/badge.svg?branch=master&service=github
+.. image:: https://codecov.io/github/camelot-dev/camelot/badge.svg?branch=master&service=github
-    :target: https://codecov.io/github/socialcopsdev/camelot?branch=master
+    :target: https://codecov.io/github/camelot-dev/camelot?branch=master
 
 .. image:: https://img.shields.io/pypi/v/camelot-py.svg
     :target: https://pypi.org/project/camelot-py/
@@ -27,6 +27,15 @@ Release v\ |version|. (:ref:`Installation <install>`)
 .. image:: https://img.shields.io/pypi/pyversions/camelot-py.svg
     :target: https://pypi.org/project/camelot-py/
 
+.. image:: https://badges.gitter.im/camelot-dev/Lobby.png
+    :target: https://gitter.im/camelot-dev/Lobby
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/ambv/black
+
+.. 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!
 
 .. note:: You can also check out `Excalibur`_, which is a web interface for Camelot!
@@ -78,7 +87,14 @@ Why Camelot?
 See `comparison with other PDF table extraction libraries and tools`_.
 
 .. _ETL and data analysis workflows: https://gist.github.com/vinayak-mehta/e5949f7c2410a0e12f25d3682dc9e873
-.. _comparison with other PDF table extraction libraries and tools: https://github.com/socialcopsdev/camelot/wiki/Comparison-with-other-PDF-Table-Extraction-libraries-and-tools
+.. _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
+----------------------------
+
+If Camelot helped you extract tables from PDFs, please consider supporting its development by `becoming a backer or a sponsor on OpenCollective`_!
+
+.. _becoming a backer or a sponsor on OpenCollective: https://opencollective.com/camelot
 
 The User Guide
 --------------
@@ -89,6 +105,7 @@ This part of the documentation begins with some background information about why
    :maxdepth: 2
 
    user/intro
+   user/install-deps
    user/install
    user/how-it-works
    user/quickstart
@@ -115,4 +132,4 @@ you.
 .. toctree::
    :maxdepth: 2
 
-   dev/contributing
+   dev/contributing

docs/user/advanced.rst

@@ -24,25 +24,34 @@ To process background lines, you can pass ``process_background=True``.
     >>> tables = camelot.read_pdf('background_lines.pdf', process_background=True)
     >>> tables[1].df
 
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot lattice -back background_lines.pdf
+
 .. csv-table::
   :file: ../_static/csv/background_lines.csv
 
-Plot geometry
+Visual debugging
--------------
+----------------
 
-You can use a :class:`table <camelot.core.Table>` object's :meth:`plot() <camelot.core.TableList.plot>` method to plot various geometries that were detected by Camelot while processing the PDF page. This can help you select table areas, column separators and debug bad table outputs, by tweaking different configuration parameters.
+.. note:: Visual debugging using ``plot()`` requires `matplotlib <https://matplotlib.org/>`_ which is an optional dependency. You can install it using ``$ pip install camelot-py[plot]``.
 
-The following geometries are available for plotting. You can pass them to the :meth:`plot() <camelot.core.TableList.plot>` method, which will then generate a `matplotlib <https://matplotlib.org/>`_ plot for the passed geometry.
+You can use the :class:`plot() <camelot.plotting.PlotMethods>` method to generate a `matplotlib <https://matplotlib.org/>`_ plot of various elements that were detected on the PDF page while processing it. This can help you select table areas, column separators and debug bad table outputs, by tweaking different configuration parameters.
+
+You can specify the type of element you want to plot using the ``kind`` keyword argument. The generated plot can be saved to a file by passing a ``filename`` keyword argument. The following plot types are supported:
 
 - 'text'
-- 'table'
+- 'grid'
 - 'contour'
 - 'line'
 - 'joint'
+- 'textedge'
 
-.. note:: The last three geometries can only be used with :ref:`Lattice <lattice>`, i.e. when ``flavor='lattice'``.
+.. note:: 'line' and 'joint' can only be used with :ref:`Lattice <lattice>` and 'textedge' can only be used with :ref:`Stream <stream>`.
 
-Let's generate a plot for each geometry using this `PDF <../_static/pdf/foo.pdf>`__ as an example. First, let's get all the tables out.
+Let's generate a plot for each type using this `PDF <../_static/pdf/foo.pdf>`__ as an example. First, let's get all the tables out.
 
 ::
 
@@ -50,8 +59,6 @@ Let's generate a plot for each geometry using this `PDF <../_static/pdf/foo.pdf>
     >>> tables
     <TableList n=1>
 
-.. _geometry_text:
-
 text
 ^^^^
 
@@ -59,9 +66,16 @@ Let's plot all the text present on the table's PDF page.
 
 ::
 
-    >>> tables[0].plot('text')
+    >>> camelot.plot(tables[0], kind='text')
+    >>> plt.show()
 
-.. figure:: ../_static/png/geometry_text.png
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot lattice -plot text foo.pdf
+
+.. figure:: ../_static/png/plot_text.png
     :height: 674
     :width: 1366
     :scale: 50%
@@ -72,18 +86,23 @@ This, as we shall later see, is very helpful with :ref:`Stream <stream>` for not
 
 .. note:: The *x-y* coordinates shown above change as you move your mouse cursor on the image, which can help you note coordinates.
 
-.. _geometry_table:
-
 table
 ^^^^^
 
-Let's plot the table (to see if it was detected correctly or not). This geometry type, along with contour, line and joint is useful for debugging and improving the extraction output, in case the table wasn't detected correctly. (More on that later.)
+Let's plot the table (to see if it was detected correctly or not). This plot type, along with contour, line and joint is useful for debugging and improving the extraction output, in case the table wasn't detected correctly. (More on that later.)
 
 ::
 
-    >>> tables[0].plot('table')
+    >>> camelot.plot(tables[0], kind='grid')
+    >>> plt.show()
 
-.. figure:: ../_static/png/geometry_table.png
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot lattice -plot grid foo.pdf
+
+.. figure:: ../_static/png/plot_table.png
     :height: 674
     :width: 1366
     :scale: 50%
@@ -92,8 +111,6 @@ Let's plot the table (to see if it was detected correctly or not). This geometry
 
 The table is perfect!
 
-.. _geometry_contour:
-
 contour
 ^^^^^^^
 
@@ -101,17 +118,22 @@ Now, let's plot all table boundaries present on the table's PDF page.
 
 ::
 
-    >>> tables[0].plot('contour')
+    >>> camelot.plot(tables[0], kind='contour')
+    >>> plt.show()
 
-.. figure:: ../_static/png/geometry_contour.png
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot lattice -plot contour foo.pdf
+
+.. figure:: ../_static/png/plot_contour.png
     :height: 674
     :width: 1366
     :scale: 50%
     :alt: A plot of all contours on a PDF page
     :align: left
 
-.. _geometry_line:
-
 line
 ^^^^
 
@@ -119,17 +141,22 @@ Cool, let's plot all line segments present on the table's PDF page.
 
 ::
 
-    >>> tables[0].plot('line')
+    >>> camelot.plot(tables[0], kind='line')
+    >>> plt.show()
 
-.. figure:: ../_static/png/geometry_line.png
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot lattice -plot line foo.pdf
+
+.. figure:: ../_static/png/plot_line.png
     :height: 674
     :width: 1366
     :scale: 50%
     :alt: A plot of all lines on a PDF page
     :align: left
 
-.. _geometry_joint:
-
 joint
 ^^^^^
 
@@ -137,50 +164,113 @@ Finally, let's plot all line intersections present on the table's PDF page.
 
 ::
 
-    >>> tables[0].plot('joint')
+    >>> camelot.plot(tables[0], kind='joint')
+    >>> plt.show()
 
-.. figure:: ../_static/png/geometry_joint.png
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot lattice -plot joint foo.pdf
+
+.. figure:: ../_static/png/plot_joint.png
     :height: 674
     :width: 1366
     :scale: 50%
     :alt: A plot of all line intersections on a PDF page
     :align: left
 
+textedge
+^^^^^^^^
+
+You can also visualize the textedges found on a page by specifying ``kind='textedge'``. To know more about what a "textedge" is, you can see pages 20, 35 and 40 of `Anssi Nurminen's master's thesis <http://dspace.cc.tut.fi/dpub/bitstream/handle/123456789/21520/Nurminen.pdf?sequence=3>`_.
+
+::
+
+    >>> camelot.plot(tables[0], kind='textedge')
+    >>> plt.show()
+
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot stream -plot textedge foo.pdf
+
+.. figure:: ../_static/png/plot_textedge.png
+    :height: 674
+    :width: 1366
+    :scale: 50%
+    :alt: A plot of relevant textedges on a PDF page
+    :align: left
+
 Specify table areas
 -------------------
 
-Since :ref:`Stream <stream>` treats the whole page as a table, `for now`_, it's useful to specify table boundaries in cases such as `these <../_static/pdf/table_areas.pdf>`__. You can :ref:`plot the text <geometry_text>` on this page and note the top left and bottom right coordinates of the table.
+In cases such as `these <../_static/pdf/table_areas.pdf>`__, it can be useful to specify exact table boundaries. You can plot the text on this page and note the top left and bottom right coordinates of the table.
 
 Table areas that you want Camelot to analyze can be passed as a list of comma-separated strings to :meth:`read_pdf() <camelot.read_pdf>`, using the ``table_areas`` keyword argument.
 
-.. _for now: https://github.com/socialcopsdev/camelot/issues/102
-
 ::
 
     >>> tables = camelot.read_pdf('table_areas.pdf', flavor='stream', table_areas=['316,499,566,337'])
     >>> tables[0].df
 
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot stream -T 316,499,566,337 table_areas.pdf
+
 .. csv-table::
   :file: ../_static/csv/table_areas.csv
 
+.. note:: ``table_areas`` accepts strings of the form x1,y1,x2,y2 where (x1, y1) -> top-left and (x2, y2) -> bottom-right in PDF coordinate space. In PDF coordinate space, the bottom-left corner of the page is the origin, with coordinates (0, 0).
+
+Specify table regions
+---------------------
+
+However there may be cases like `[1] <../_static/pdf/table_regions.pdf>`__ and `[2] <https://github.com/camelot-dev/camelot/blob/master/tests/files/tableception.pdf>`__, where the table might not lie at the exact coordinates every time but in an approximate region.
+
+You can use the ``table_regions`` keyword argument to :meth:`read_pdf() <camelot.read_pdf>` to solve for such cases. When ``table_regions`` is specified, Camelot will only analyze the specified regions to look for tables.
+
+::
+
+    >>> tables = camelot.read_pdf('table_regions.pdf', table_regions=['170,370,560,270'])
+    >>> tables[0].df
+
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot lattice -R 170,370,560,270 table_regions.pdf
+
+.. csv-table::
+  :file: ../_static/csv/table_regions.csv
+
 Specify column separators
 -------------------------
 
-In cases like `these <../_static/pdf/column_separators.pdf>`__, where the text is very close to each other, it is possible that Camelot may guess the column separators' coordinates incorrectly. To correct this, you can explicitly specify the *x* coordinate for each column separator by :ref:`plotting the text <geometry_text>` on the page.
+In cases like `these <../_static/pdf/column_separators.pdf>`__, where the text is very close to each other, it is possible that Camelot may guess the column separators' coordinates incorrectly. To correct this, you can explicitly specify the *x* coordinate for each column separator by plotting the text on the page.
 
 You can pass the column separators as a list of comma-separated strings to :meth:`read_pdf() <camelot.read_pdf>`, using the ``columns`` keyword argument.
 
 In case you passed a single column separators string list, and no table area is specified, the separators will be applied to the whole page. When a list of table areas is specified and you need to specify column separators as well, **the length of both lists should be equal**. Each table area will be mapped to each column separators' string using their indices.
 
-For example, if you have specified two table areas, ``table_areas=['12,23,43,54', '20,33,55,67']``, and only want to specify column separators for the first table, you can pass an empty string for the second table in the column separators' list like this, ``columns=['10,120,200,400', '']``.
+For example, if you have specified two table areas, ``table_areas=['12,54,43,23', '20,67,55,33']``, and only want to specify column separators for the first table, you can pass an empty string for the second table in the column separators' list like this, ``columns=['10,120,200,400', '']``.
 
-Let's get back to the *x* coordinates we got from :ref:`plotting text <geometry_text>` that exists on this `PDF <../_static/pdf/column_separators.pdf>`__, and get the table out!
+Let's get back to the *x* coordinates we got from plotting the text that exists on this `PDF <../_static/pdf/column_separators.pdf>`__, and get the table out!
 
 ::
 
     >>> tables = camelot.read_pdf('column_separators.pdf', flavor='stream', columns=['72,95,209,327,442,529,566,606,683'])
     >>> tables[0].df
 
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot stream -C 72,95,209,327,442,529,566,606,683 column_separators.pdf
+
 .. csv-table::
 
     "...","...","...","...","...","...","...","...","...","..."
@@ -200,6 +290,12 @@ To deal with cases like the output from the previous section, you can pass ``spl
     >>> tables = camelot.read_pdf('column_separators.pdf', flavor='stream', columns=['72,95,209,327,442,529,566,606,683'], split_text=True)
     >>> tables[0].df
 
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot -split stream -C 72,95,209,327,442,529,566,606,683 column_separators.pdf
+
 .. csv-table::
 
     "...","...","...","...","...","...","...","...","...","..."
@@ -220,13 +316,19 @@ In this case, the text that `other tools`_ return, will be ``24.912``. This is r
 
 You can solve this by passing ``flag_size=True``, which will enclose the superscripts and subscripts with ``<s></s>``, based on font size, as shown below.
 
-.. _other tools: https://github.com/socialcopsdev/camelot/wiki/Comparison-with-other-PDF-Table-Extraction-libraries-and-tools
+.. _other tools: https://github.com/camelot-dev/camelot/wiki/Comparison-with-other-PDF-Table-Extraction-libraries-and-tools
 
 ::
 
     >>> tables = camelot.read_pdf('superscript.pdf', flavor='stream', flag_size=True)
     >>> tables[0].df
 
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot -flag stream superscript.pdf
+
 .. csv-table::
 
     "...","...","...","...","...","...","...","...","...","...","..."
@@ -235,10 +337,87 @@ You can solve this by passing ``flag_size=True``, which will enclose the supersc
     "Madhya Pradesh","27.13","23.57","-","-","3.56","0.38","-","1.86","-","1.28"
     "...","...","...","...","...","...","...","...","...","...","..."
 
-Control how text is grouped into rows
+Strip characters from text
--------------------------------------
+--------------------------
 
-You can pass ``row_close_tol=<+int>`` to group the rows closer together, as shown below.
+You can strip unwanted characters like spaces, dots and newlines from a string using the ``strip_text`` keyword argument. Take a look at `this PDF <https://github.com/camelot-dev/camelot/blob/master/tests/files/tabula/12s0324.pdf>`_ as an example, the text at the start of each row contains a lot of unwanted spaces, dots and newlines.
+
+::
+
+    >>> tables = camelot.read_pdf('12s0324.pdf', flavor='stream', strip_text=' .\n')
+    >>> tables[0].df
+
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot -strip ' .\n' stream 12s0324.pdf
+
+.. csv-table::
+
+    "...","...","...","...","...","...","...","...","...","..."
+    "Forcible rape","17.5","2.6","14.9","17.2","2.5","14.7","–","–","–"
+    "Robbery","102.1","25.5","76.6","90.0","22.9","67.1","12.1","2.5","9.5"
+    "Aggravated assault","338.4","40.1","298.3","264.0","30.2","233.8","74.4","9.9","64.5"
+    "Property crime","1,396 .4","338 .7","1,057 .7","875 .9","210 .8","665 .1","608 .2","127 .9","392 .6"
+    "Burglary","240.9","60.3","180.6","205.0","53.4","151.7","35.9","6.9","29.0"
+    "...","...","...","...","...","...","...","...","...","..."
+
+Improve guessed table areas
+---------------------------
+
+While using :ref:`Stream <stream>`, automatic table detection can fail for PDFs like `this one <https://github.com/camelot-dev/camelot/blob/master/tests/files/edge_tol.pdf>`_. That's because the text is relatively far apart vertically, which can lead to shorter textedges being calculated.
+
+.. note:: To know more about how textedges are calculated to guess table areas, you can see pages 20, 35 and 40 of `Anssi Nurminen's master's thesis <http://dspace.cc.tut.fi/dpub/bitstream/handle/123456789/21520/Nurminen.pdf?sequence=3>`_.
+
+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()
+
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot stream -plot contour edge.pdf
+
+.. figure:: ../_static/png/edge_tol_1.png
+    :height: 674
+    :width: 1366
+    :scale: 50%
+    :alt: Table area with default edge_tol
+    :align: left
+
+To improve the detected area, you can increase the ``edge_tol`` (default: 50) value to counter the effect of text being placed relatively far apart vertically. Larger ``edge_tol`` will lead to longer textedges being detected, leading to an improved guess of the table area. Let's use a value of 500.
+
+::
+
+    >>> tables = camelot.read_pdf('edge_tol.pdf', flavor='stream', edge_tol=500)
+    >>> camelot.plot(tables[0], kind='contour')
+    >>> plt.show()
+
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot stream -e 500 -plot contour edge.pdf
+
+.. figure:: ../_static/png/edge_tol_2.png
+    :height: 674
+    :width: 1366
+    :scale: 50%
+    :alt: Table area with default edge_tol
+    :align: left
+
+As you can see, the guessed table area has improved!
+
+Improve guessed table rows
+--------------------------
+
+You can pass ``row_tol=<+int>`` to group the rows closer together, as shown below.
 
 ::
 
@@ -256,9 +435,15 @@ You can pass ``row_close_tol=<+int>`` to group the rows closer together, as show
 
 ::
 
-    >>> tables = camelot.read_pdf('group_rows.pdf', flavor='stream', row_close_tol=10)
+    >>> tables = camelot.read_pdf('group_rows.pdf', flavor='stream', row_tol=10)
     >>> tables[0].df
 
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot stream -r 10 group_rows.pdf
+
 .. csv-table::
 
     "Clave","Nombre Entidad","Clave","","Nombre Municipio","Clave","Nombre Localidad"
@@ -270,11 +455,11 @@ You can pass ``row_close_tol=<+int>`` to group the rows closer together, as show
 Detect short lines
 ------------------
 
-There might be cases while using :ref:`Lattice <lattice>` when smaller lines don't get detected. The size of the smallest line that gets detected is calculated by dividing the PDF page's dimensions with a scaling factor called ``line_size_scaling``. By default, its value is 15.
+There might be cases while using :ref:`Lattice <lattice>` when smaller lines don't get detected. The size of the smallest line that gets detected is calculated by dividing the PDF page's dimensions with a scaling factor called ``line_scale``. By default, its value is 15.
 
-As you can guess, the larger the ``line_size_scaling``, the smaller the size of lines getting detected.
+As you can guess, the larger the ``line_scale``, the smaller the size of lines getting detected.
 
-.. warning:: Making ``line_size_scaling`` very large (>150) will lead to text getting detected as lines.
+.. warning:: Making ``line_scale`` very large (>150) will lead to text getting detected as lines.
 
 Here's a `PDF <../_static/pdf/short_lines.pdf>`__ where small lines separating the the headers don't get detected with the default value of 15.
 
@@ -282,23 +467,31 @@ Here's a `PDF <../_static/pdf/short_lines.pdf>`__ where small lines separating t
     :alt: A PDF table with short lines
     :align: left
 
-Let's :ref:`plot the table <geometry_table>` for this PDF.
+Let's plot the table for this PDF.
 
 ::
 
     >>> tables = camelot.read_pdf('short_lines.pdf')
-    >>> tables[0].plot('table')
+    >>> camelot.plot(tables[0], kind='grid')
+    >>> plt.show()
 
 .. figure:: ../_static/png/short_lines_1.png
     :alt: A plot of the PDF table with short lines
     :align: left
 
-Clearly, the smaller lines separating the headers, couldn't be detected. Let's try with ``line_size_scaling=40``, and `plot the table <geometry_table>`_ again.
+Clearly, the smaller lines separating the headers, couldn't be detected. Let's try with ``line_scale=40``, and plot the table again.
 
 ::
 
-    >>> tables = camelot.read_pdf('short_lines.pdf', line_size_scaling=40)
+    >>> tables = camelot.read_pdf('short_lines.pdf', line_scale=40)
-    >>> tables[0].plot('table')
+    >>> camelot.plot(tables[0], kind='grid')
+    >>> plt.show()
+
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot lattice -scale 40 -plot grid short_lines.pdf
 
 .. figure:: ../_static/png/short_lines_2.png
     :alt: An improved plot of the PDF table with short lines
@@ -339,7 +532,7 @@ We'll use the `PDF <../_static/pdf/short_lines.pdf>`__ from the previous example
 
 ::
 
-    >>> tables = camelot.read_pdf('short_lines.pdf', line_size_scaling=40, shift_text=[''])
+    >>> tables = camelot.read_pdf('short_lines.pdf', line_scale=40, shift_text=[''])
     >>> tables[0].df
 
 .. csv-table::
@@ -360,9 +553,15 @@ No surprises there — it did remain in place (observe the strings "2400" and "A
 
 ::
 
-    >>> tables = camelot.read_pdf('short_lines.pdf', line_size_scaling=40, shift_text=['r', 'b'])
+    >>> tables = camelot.read_pdf('short_lines.pdf', line_scale=40, shift_text=['r', 'b'])
     >>> tables[0].df
 
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot lattice -scale 40 -shift r -shift b short_lines.pdf
+
 .. csv-table::
 
     "Investigations","No. ofHHs","Age/Sex/Physiological  Group","Preva-lence","C.I*","RelativePrecision","Sample sizeper State"
@@ -408,6 +607,12 @@ We don't need anything else. Now, let's pass ``copy_text=['v']`` to copy text in
     >>> tables = camelot.read_pdf('copy_text.pdf', copy_text=['v'])
     >>> tables[0].df
 
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot lattice -copy v copy_text.pdf
+
 .. csv-table::
 
     "Sl. No.","Name of State/UT","Name of District","Disease/ Illness","No. of Cases","No. of Deaths","Date of start of outbreak","Date of reporting","Current Status","..."
@@ -417,3 +622,14 @@ We don't need anything else. Now, let's pass ``copy_text=['v']`` to copy text in
     "4","West Bengal","West Medinipur","iv. Acute Diarrhoeal Disease","145","0","04/01/14","05/01/14","Under control","..."
     "4","West Bengal","Birbhum","v.  Food Poisoning","199","0","31/12/13","31/12/13","Under control","..."
     "4","West Bengal","Howrah","vi. Viral Hepatitis A &E","85","0","26/12/13","27/12/13","Under surveillance","..."
+
+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/>`_.
+
+::
+
+    >>> tables = camelot.read_pdf('foo.pdf', layout_kwargs={'detect_vertical': False})

docs/user/cli.rst

@@ -9,28 +9,30 @@ 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
+    Camelot: PDF Table Extraction for Humans
 
-Options:
+  Options:
-  --version                       Show the version and exit.
+    --version                       Show the version and exit.
-  -p, --pages TEXT                Comma-separated page numbers. Example: 1,3,4
+    -q, --quiet TEXT                Suppress logs and warnings.
-                                  or 1,4-end.
+    -p, --pages TEXT                Comma-separated page numbers. Example: 1,3,4
-  -pw, --password TEXT            Password for decryption.
+                                    or 1,4-end.
-  -o, --output TEXT               Output file path.
+    -pw, --password TEXT            Password for decryption.
-  -f, --format [csv|json|excel|html]
+    -o, --output TEXT               Output file path.
-                                  Output file format.
+    -f, --format [csv|json|excel|html]
-  -z, --zip                       Create ZIP archive.
+                                    Output file format.
-  -split, --split_text            Split text that spans across multiple cells.
+    -z, --zip                       Create ZIP archive.
-  -flag, --flag_size              Flag text based on font size. Useful to
+    -split, --split_text            Split text that spans across multiple cells.
-                                  detect super/subscripts.
+    -flag, --flag_size              Flag text based on font size. Useful to
-  -M, --margins <FLOAT FLOAT FLOAT>...
+                                    detect super/subscripts.
-                                  PDFMiner char_margin, line_margin and
+    -strip, --strip_text            Characters that should be stripped from a
-                                  word_margin.
+                                    string before assigning it to a cell.
-  -q, --quiet                     Suppress warnings.
+    -M, --margins <FLOAT FLOAT FLOAT>...
-  --help                          Show this message and exit.
+                                    PDFMiner char_margin, line_margin and
+                                    word_margin.
+    --help                          Show this message and exit.
 
-Commands:
+  Commands:
-  lattice  Use lines between text to parse the table.
+    lattice  Use lines between text to parse the table.
-  stream   Use spaces between text to parse the table.
+    stream   Use spaces between text to parse the table.

docs/user/how-it-works.rst

@@ -5,24 +5,24 @@ How It Works
 
 This part of the documentation includes a high-level explanation of how Camelot extracts tables from PDF files.
 
-You can choose between two table parsing methods, *Stream* and *Lattice*. These names for parsing methods inside Camelot were inspired from `Tabula`_.
+You can choose between two table parsing methods, *Stream* and *Lattice*. These names for parsing methods inside Camelot were inspired from `Tabula <https://github.com/tabulapdf/tabula>`_.
-
-.. _Tabula: https://github.com/tabulapdf/tabula
 
 .. _stream:
 
 Stream
 ------
 
-Stream can be used to parse tables that have whitespaces between cells to simulate a table structure. It looks for these spaces between text to form a table representation.
+Stream can be used to parse tables that have whitespaces between cells to simulate a table structure. It is built on top of PDFMiner's functionality of grouping characters on a page into words and sentences, using `margins <https://euske.github.io/pdfminer/#tools>`_.
 
-It is built on top of PDFMiner's functionality of grouping characters on a page into words and sentences, using `margins`_. After getting the words on a page, it groups them into rows based on their *y* coordinates. It then tries to guess the number of columns the table might have by calculating the mode of the number of words in each row. This mode is used to calculate *x* ranges for the table's columns. It then adds columns to this column range list based on any words that may lie outside or inside the current column *x* ranges.
+1. Words on the PDF page are grouped into text rows based on their *y* axis overlaps.
 
-.. _margins: https://euske.github.io/pdfminer/#tools
+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]
 
-.. note:: By default, Stream treats the whole PDF page as a table, which isn't ideal when there are more than two tables on a page with different number of columns. Automatic table detection for Stream is `in the works`_.
+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.
 
-.. _in the works: https://github.com/socialcopsdev/camelot/issues/102
+4. Words that lie inside/outside the current column *x* ranges are then used to extend the current list of columns.
+
+5. Finally, a table is formed using the text rows' *y* ranges and column *x* ranges and words found on the page are assigned to the table's cells based on their *x* and *y* coordinates.
 
 .. _lattice:
 
@@ -39,7 +39,7 @@ Let's see how Lattice processes the second page of `this PDF`_, step-by-step.
 
 1. Line segments are detected.
 
-.. image:: ../_static/png/geometry_line.png
+.. image:: ../_static/png/plot_line.png
     :height: 674
     :width: 1366
     :scale: 50%
@@ -49,7 +49,7 @@ Let's see how Lattice processes the second page of `this PDF`_, step-by-step.
 
 .. _and: https://en.wikipedia.org/wiki/Logical_conjunction
 
-.. image:: ../_static/png/geometry_joint.png
+.. image:: ../_static/png/plot_joint.png
     :height: 674
     :width: 1366
     :scale: 50%
@@ -59,7 +59,7 @@ Let's see how Lattice processes the second page of `this PDF`_, step-by-step.
 
 .. _or: https://en.wikipedia.org/wiki/Logical_disjunction
 
-.. image:: ../_static/png/geometry_contour.png
+.. image:: ../_static/png/plot_contour.png
     :height: 674
     :width: 1366
     :scale: 50%
@@ -75,10 +75,10 @@ Let's see how Lattice processes the second page of `this PDF`_, step-by-step.
 
 5. Spanning cells are detected using the line segments and line intersections.
 
-.. image:: ../_static/png/geometry_table.png
+.. image:: ../_static/png/plot_table.png
     :height: 674
     :width: 1366
     :scale: 50%
     :align: left
 
-6. Finally, the words found on the page are assigned to the table's cells based on their *x* and *y* coordinates.
+6. Finally, the words found on the page are assigned to the table's cells based on their *x* and *y* coordinates.

docs/user/install-deps.rst

@@ -0,0 +1,74 @@
+.. _install_deps:
+
+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
+
+OS-specific instructions
+------------------------
+
+For Ubuntu
+^^^^^^^^^^
+::
+
+    $ apt install python-tk ghostscript
+
+Or for Python 3::
+
+    $ apt install python3-tk ghostscript
+
+For macOS
+^^^^^^^^^
+::
+
+    $ brew install tcl-tk ghostscript
+
+For Windows
+^^^^^^^^^^^
+
+For Tkinter, you can download the `ActiveTcl Community Edition`_ from ActiveState. For ghostscript, you can get the installer at the `ghostscript downloads page`_.
+
+.. _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 were installed correctly
+------------------------------------------------------
+
+You can do the following checks to see if the dependencies were installed correctly.
+
+For Tkinter
+^^^^^^^^^^^
+
+Launch Python, and then at the prompt, type::
+
+    >>> import Tkinter
+
+Or in Python 3::
+
+    >>> 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.

docs/user/install.rst

@@ -3,22 +3,17 @@
 Installation of Camelot
 =======================
 
-This part of the documentation covers how to install Camelot.
+This part of the documentation covers the steps to install Camelot.
 
 Using conda
 -----------
 
-The easiest way to install Camelot is to install it with `conda`_, which is the package manager that the `Anaconda`_ distribution is built upon.
+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.
+::
 
-First, let's add the `conda-forge`_ channel to conda's config::
+    $ conda install -c conda-forge camelot-py
 
-    $ conda config --add channels conda-forge
+.. 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`_.
-
-Now, you can simply use conda to install Camelot::
-
-    $ conda install -c camelot-dev camelot-py
-
-.. note:: Camelot is available for Python 2.7, 3.5 and 3.6 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/
@@ -28,94 +23,25 @@ Now, you can simply use conda to install Camelot::
 Using pip
 ---------
 
-First, you'll need to install the dependencies, which include `Tkinter`_ and `ghostscript`_.
+After :ref:`installing the dependencies <install_deps>`, which include `Tkinter`_ and `ghostscript`_, you can simply use pip to install Camelot::
+
+    $ pip install "camelot-py[cv]"
 
 .. _Tkinter: https://wiki.python.org/moin/TkInter
 .. _ghostscript: https://www.ghostscript.com
 
-These can be installed using your system's package manager. You can run one of the following, based on your OS.
-
-For Ubuntu
-^^^^^^^^^^
-::
-
-    $ apt install python-tk ghostscript
-
-Or for Python 3::
-
-    $ apt install python3-tk ghostscript
-
-For macOS
-^^^^^^^^^
-::
-
-    $ brew install tcl-tk ghostscript
-
-For Windows
-^^^^^^^^^^^
-
-For Tkinter, you can download the `ActiveTcl Community Edition`_ from ActiveState. For ghostscript, you can get the installer at the `ghostscript downloads page`_.
-
-After installing ghostscript, you'll need to reboot your system to make sure that the ghostscript executable's path is in the windows PATH environment variable. In case you don't want to reboot, you can manually add the ghostscript executable's path to the PATH variable, `as shown here`_.
-
-.. _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
-
-----
-
-You can do the following checks to see if the dependencies were installed correctly.
-
-For Tkinter
-^^^^^^^^^^^
-
-Launch Python, and then at the prompt, type::
-
-    >>> import Tkinter
-
-Or in Python 3::
-
-    >>> 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.
-
-Finally, you can use pip to install Camelot::
-
-    $ pip install camelot-py[all]
-
 From the source code
 --------------------
 
-After `installing the dependencies`_, you can install from the source by:
+After :ref:`installing the dependencies <install_deps>`, you can install from the source by:
 
 1. Cloning the GitHub repository.
 ::
 
-    $ git clone https://www.github.com/socialcopsdev/camelot
+    $ git clone https://www.github.com/camelot-dev/camelot
 
 2. Then simply using pip again.
 ::
 
     $ cd camelot
-    $ pip install ".[all]"
+    $ pip install ".[cv]"
-
-.. _installing the dependencies: https://camelot-py.readthedocs.io/en/master/user/install.html#using-pip

docs/user/intro.rst

@@ -27,7 +27,7 @@ Here is a `comparison`_ of Camelot's output with outputs from other open-source
 .. _pdf-table-extract: https://github.com/ashima/pdf-table-extract
 .. _PDFTables: https://pdftables.com/
 .. _Smallpdf: https://smallpdf.com
-.. _comparison: https://github.com/socialcopsdev/camelot/wiki/Comparison-with-other-PDF-Table-Extraction-libraries-and-tools
+.. _comparison: https://github.com/camelot-dev/camelot/wiki/Comparison-with-other-PDF-Table-Extraction-libraries-and-tools
 
 What's in a name?
 -----------------

docs/user/quickstart.rst

@@ -14,7 +14,7 @@ Begin by importing the Camelot module::
 
     >>> import camelot
 
-Now, let's try to read a PDF. (You can check out the PDF used in this example `here`_.) Since the PDF has a table with clearly demarcated lines, we will use the :ref:`Lattice <lattice>` method here. To do that, we will set the ``mesh`` keyword argument to ``True``.
+Now, let's try to read a PDF. (You can check out the PDF used in this example `here`_.) Since the PDF has a table with clearly demarcated lines, we will use the :ref:`Lattice <lattice>` method here.
 
 .. note:: :ref:`Lattice <lattice>` is used by default. You can use :ref:`Stream <stream>` with ``flavor='stream'``.
 
@@ -56,7 +56,7 @@ Woah! The accuracy is top-notch and there is less whitespace, which means the ta
 .. csv-table::
   :file: ../_static/csv/foo.csv
 
-Looks good! You can now export the table as a CSV file using its :meth:`to_csv() <camelot.core.Table.to_csv>` method. Alternatively you can use :meth:`to_json() <camelot.core.Table.to_json>`, :meth:`to_excel() <camelot.core.Table.to_excel>` or :meth:`to_html() <camelot.core.Table.to_html>` methods to export the table as JSON, Excel and HTML files respectively.
+Looks good! You can now export the table as a CSV file using its :meth:`to_csv() <camelot.core.Table.to_csv>` method. Alternatively you can use :meth:`to_json() <camelot.core.Table.to_json>`, :meth:`to_excel() <camelot.core.Table.to_excel>` :meth:`to_html() <camelot.core.Table.to_html>` or :meth:`to_sqlite() <camelot.core.Table.to_sqlite>` methods to export the table as JSON, Excel, HTML files or a sqlite database respectively.
 
 ::
 
@@ -70,7 +70,13 @@ You can also export all tables at once, using the :class:`tables <camelot.core.T
 
     >>> tables.export('foo.csv', f='csv')
 
-This will export all tables as CSV files at the path specified. Alternatively, you can use ``f='json'``, ``f='excel'`` or ``f='html'``.
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot --format csv --output foo.csv lattice foo.pdf
+
+This will export all tables as CSV files at the path specified. Alternatively, you can use ``f='json'``, ``f='excel'``, ``f='html'`` or ``f='sqlite'``.
 
 .. note:: The :meth:`export() <camelot.core.TableList.export>` method exports files with a ``page-*-table-*`` suffix. In the example above, the single table in the list will be exported to ``foo-page-1-table-1.csv``. If the list contains multiple tables, multiple CSV files will be created. To avoid filling up your path with multiple files, you can use ``compress=True``, which will create a single ZIP file at your path with all the CSV files.
 
@@ -85,6 +91,12 @@ By default, Camelot only uses the first page of the PDF to extract tables. To sp
 
     >>> camelot.read_pdf('your.pdf', pages='1,2,3')
 
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot --pages 1,2,3 lattice your.pdf
+
 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
@@ -98,6 +110,12 @@ To extract tables from encrypted PDF files you must provide a password when call
     >>> tables
     <TableList n=1>
 
+.. tip::
+    Here's how you can do the same with the :ref:`command-line interface <cli>`.
+    ::
+
+        $ camelot --password userpass lattice foo.pdf
+
 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`_.

requirements.txt

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

setup.cfg

@@ -2,5 +2,5 @@
 test=pytest
 
 [tool:pytest]
-addopts = --verbose --cov-config .coveragerc --cov-report term --cov-report xml --cov=camelot tests
+addopts = --verbose --cov-config .coveragerc --cov-report term --cov-report xml --cov=camelot --mpl
-python_files = tests/test_*.py
+python_files = tests/test_*.py

setup.py

@@ -14,26 +14,33 @@ with open('README.md', 'r') as f:
 
 
 requires = [
+    'chardet>=3.0.4',
     'click>=6.7',
-    'matplotlib>=2.2.3',
     'numpy>=1.13.3',
     'openpyxl>=2.5.8',
     'pandas>=0.23.4',
-    'pdfminer.six>=20170720',
+    'pdfminer.six>=20200726',
     'PyPDF2>=1.26.0'
 ]
 
-all_requires = [
+cv_requires = [
     'opencv-python>=3.4.2.17'
 ]
 
+plot_requires = [
+    'matplotlib>=2.2.3',
+]
+
 dev_requires = [
     'codecov>=2.0.15',
-    'pytest>=3.8.0',
+    'pytest>=5.4.3',
-    'pytest-cov>=2.6.0',
+    'pytest-cov>=2.10.0',
-    'pytest-runner>=4.2',
+    'pytest-mpl>=0.11',
-    'Sphinx>=1.7.9'
+    'pytest-runner>=5.2',
+    'Sphinx>=3.1.2'
 ]
+
+all_requires = cv_requires + plot_requires
 dev_requires = dev_requires + all_requires
 
 
@@ -51,7 +58,9 @@ def setup_package():
                     install_requires=requires,
                     extras_require={
                         'all': all_requires,
-                        'dev': dev_requires
+                        'cv': cv_requires,
+                        'dev': dev_requires,
+                        'plot': plot_requires
                     },
                     entry_points={
                         'console_scripts': [
@@ -62,10 +71,9 @@ def setup_package():
                         # Trove classifiers
                         # Full list: https://pypi.python.org/pypi?%3Aaction=list_classifiers
                         'License :: OSI Approved :: MIT License',
-                        'Programming Language :: Python :: 2.7',
-                        'Programming Language :: Python :: 3.5',
                         'Programming Language :: Python :: 3.6',
-                        'Programming Language :: Python :: 3.7'
+                        'Programming Language :: Python :: 3.7',
+                        'Programming Language :: Python :: 3.8'
                     ])
 
     try:

tests/__init__.py

@@ -0,0 +1,3 @@
+import matplotlib
+
+matplotlib.use("agg")

tests/test_cli.py

@@ -9,109 +9,167 @@ from camelot.utils import TemporaryDirectory
 
 
 testdir = os.path.dirname(os.path.abspath(__file__))
-testdir = os.path.join(testdir, 'files')
+testdir = os.path.join(testdir, "files")
+
+
+def test_help_output():
+    runner = CliRunner()
+    prog_name = runner.get_default_prog_name(cli)
+    result = runner.invoke(cli, ["--help"])
+    output = result.output
+
+    assert prog_name == "camelot"
+    assert result.output.startswith("Usage: %(prog_name)s [OPTIONS] COMMAND" % locals())
+    assert all(
+        v in result.output
+        for v in ["Options:", "--version", "--help", "Commands:", "lattice", "stream"]
+    )
 
 
 def test_cli_lattice():
     with TemporaryDirectory() as tempdir:
-        infile = os.path.join(testdir, 'foo.pdf')
+        infile = os.path.join(testdir, "foo.pdf")
-        outfile = os.path.join(tempdir, 'foo.csv')
+        outfile = os.path.join(tempdir, "foo.csv")
         runner = CliRunner()
-        result = runner.invoke(cli, ['--format', 'csv', '--output', outfile,
+        result = runner.invoke(
-                                     'lattice', infile])
+            cli, ["--format", "csv", "--output", outfile, "lattice", infile]
+        )
         assert result.exit_code == 0
-        assert result.output == 'Found 1 tables\n'
+        assert result.output == "Found 1 tables\n"
 
-        result = runner.invoke(cli, ['--format', 'csv',
+        result = runner.invoke(cli, ["--format", "csv", "lattice", infile])
-                                     'lattice', infile])
+        output_error = "Error: Please specify output file path using --output"
-        output_error = 'Error: Please specify output file path using --output'
         assert output_error in result.output
 
-        result = runner.invoke(cli, ['--output', outfile,
+        result = runner.invoke(cli, ["--output", outfile, "lattice", infile])
-                                     'lattice', infile])
+        format_error = "Please specify output file format using --format"
-        format_error = 'Please specify output file format using --format'
         assert format_error in result.output
 
 
 def test_cli_stream():
     with TemporaryDirectory() as tempdir:
-        infile = os.path.join(testdir, 'budget.pdf')
+        infile = os.path.join(testdir, "budget.pdf")
-        outfile = os.path.join(tempdir, 'budget.csv')
+        outfile = os.path.join(tempdir, "budget.csv")
         runner = CliRunner()
-        result = runner.invoke(cli, ['--format', 'csv', '--output', outfile,
+        result = runner.invoke(
-                                     'stream', infile])
+            cli, ["--format", "csv", "--output", outfile, "stream", infile]
+        )
         assert result.exit_code == 0
-        assert result.output == 'Found 1 tables\n'
+        assert result.output == "Found 1 tables\n"
 
-        result = runner.invoke(cli, ['--format', 'csv', 'stream', infile])
+        result = runner.invoke(cli, ["--format", "csv", "stream", infile])
-        output_error = 'Error: Please specify output file path using --output'
+        output_error = "Error: Please specify output file path using --output"
         assert output_error in result.output
 
-        result = runner.invoke(cli, ['--output', outfile, 'stream', infile])
+        result = runner.invoke(cli, ["--output", outfile, "stream", infile])
-        format_error = 'Please specify output file format using --format'
+        format_error = "Please specify output file format using --format"
         assert format_error in result.output
 
 
 def test_cli_password():
     with TemporaryDirectory() as tempdir:
-        infile = os.path.join(testdir, 'health_protected.pdf')
+        infile = os.path.join(testdir, "health_protected.pdf")
-        outfile = os.path.join(tempdir, 'health_protected.csv')
+        outfile = os.path.join(tempdir, "health_protected.csv")
         runner = CliRunner()
-        result = runner.invoke(cli, ['--password', 'userpass',
+        result = runner.invoke(
-                                     '--format', 'csv', '--output', outfile,
+            cli,
-                                     'stream', infile])
+            [
+                "--password",
+                "userpass",
+                "--format",
+                "csv",
+                "--output",
+                outfile,
+                "stream",
+                infile,
+            ],
+        )
         assert result.exit_code == 0
-        assert result.output == 'Found 1 tables\n'
+        assert result.output == "Found 1 tables\n"
 
-        output_error = 'file has not been decrypted'
+        output_error = "file has not been decrypted"
         # no password
-        result = runner.invoke(cli, ['--format', 'csv', '--output', outfile,
+        result = runner.invoke(
-                                     'stream', infile])
+            cli, ["--format", "csv", "--output", outfile, "stream", infile]
+        )
         assert output_error in str(result.exception)
 
         # bad password
-        result = runner.invoke(cli, ['--password', 'wrongpass',
+        result = runner.invoke(
-                                     '--format', 'csv', '--output', outfile,
+            cli,
-                                     'stream', infile])
+            [
+                "--password",
+                "wrongpass",
+                "--format",
+                "csv",
+                "--output",
+                outfile,
+                "stream",
+                infile,
+            ],
+        )
         assert output_error in str(result.exception)
 
 
 def test_cli_output_format():
     with TemporaryDirectory() as tempdir:
-        infile = os.path.join(testdir, 'health.pdf')
+        infile = os.path.join(testdir, "health.pdf")
-        outfile = os.path.join(tempdir, 'health.{}')
+
         runner = CliRunner()
 
         # json
-        result = runner.invoke(cli, ['--format', 'json', '--output', outfile.format('json'),
+        outfile = os.path.join(tempdir, "health.json")
-                                     'stream', infile])
+        result = runner.invoke(
+            cli,
+            ["--format", "json", "--output", outfile, "stream", infile],
+        )
         assert result.exit_code == 0
 
         # excel
-        result = runner.invoke(cli, ['--format', 'excel', '--output', outfile.format('xlsx'),
+        outfile = os.path.join(tempdir, "health.xlsx")
-                                     'stream', infile])
+        result = runner.invoke(
+            cli,
+            ["--format", "excel", "--output", outfile, "stream", infile],
+        )
         assert result.exit_code == 0
 
         # html
-        result = runner.invoke(cli, ['--format', 'html', '--output', outfile.format('html'),
+        outfile = os.path.join(tempdir, "health.html")
-                                     'stream', infile])
+        result = runner.invoke(
+            cli,
+            ["--format", "html", "--output", outfile, "stream", infile],
+        )
         assert result.exit_code == 0
 
         # zip
-        result = runner.invoke(cli, ['--zip', '--format', 'csv', '--output', outfile.format('csv'),
+        outfile = os.path.join(tempdir, "health.csv")
-                                     'stream', infile])
+        result = runner.invoke(
+            cli,
+            [
+                "--zip",
+                "--format",
+                "csv",
+                "--output",
+                outfile,
+                "stream",
+                infile,
+            ],
+        )
         assert result.exit_code == 0
 
+
 def test_cli_quiet():
     with TemporaryDirectory() as tempdir:
-        infile = os.path.join(testdir, 'blank.pdf')
+        infile = os.path.join(testdir, "blank.pdf")
-        outfile = os.path.join(tempdir, 'blank.csv')
+        outfile = os.path.join(tempdir, "blank.csv")
         runner = CliRunner()
 
-        result = runner.invoke(cli, ['--format', 'csv', '--output', outfile,
+        result = runner.invoke(
-                                     'stream', infile])
+            cli, ["--format", "csv", "--output", outfile, "stream", infile]
-        assert 'No tables found on page-1' in result.output
+        )
+        assert "No tables found on page-1" in result.output
 
-        result = runner.invoke(cli, ['--quiet', '--format', 'csv',
+        result = runner.invoke(
-                                     '--output', outfile, 'stream', infile])
+            cli, ["--quiet", "--format", "csv", "--output", outfile, "stream", infile]
-        assert 'No tables found on page-1' not in result.output
+        )
+        assert "No tables found on page-1" not in result.output

tests/test_common.py

@@ -3,8 +3,11 @@
 import os
 
 import pandas as pd
+from pandas.testing import assert_frame_equal
 
 import camelot
+from camelot.core import Table, TableList
+from camelot.__version__ import generate_version
 
 from .data import *
 
@@ -13,12 +16,7 @@ testdir = os.path.join(testdir, "files")
 
 
 def test_parsing_report():
-    parsing_report = {
+    parsing_report = {"accuracy": 99.02, "whitespace": 12.24, "order": 1, "page": 1}
-        'accuracy': 99.02,
-        'whitespace': 12.24,
-        'order': 1,
-        'page': 1
-    }
 
     filename = os.path.join(testdir, "foo.pdf")
     tables = camelot.read_pdf(filename)
@@ -30,10 +28,10 @@ def test_password():
 
     filename = os.path.join(testdir, "health_protected.pdf")
     tables = camelot.read_pdf(filename, password="ownerpass", flavor="stream")
-    assert df.equals(tables[0].df)
+    assert_frame_equal(df, tables[0].df)
 
     tables = camelot.read_pdf(filename, password="userpass", flavor="stream")
-    assert df.equals(tables[0].df)
+    assert_frame_equal(df, tables[0].df)
 
 
 def test_stream():
@@ -41,7 +39,7 @@ def test_stream():
 
     filename = os.path.join(testdir, "health.pdf")
     tables = camelot.read_pdf(filename, flavor="stream")
-    assert df.equals(tables[0].df)
+    assert_frame_equal(df, tables[0].df)
 
 
 def test_stream_table_rotated():
@@ -49,19 +47,43 @@ def test_stream_table_rotated():
 
     filename = os.path.join(testdir, "clockwise_table_2.pdf")
     tables = camelot.read_pdf(filename, flavor="stream")
-    assert df.equals(tables[0].df)
+    assert_frame_equal(df, tables[0].df)
 
     filename = os.path.join(testdir, "anticlockwise_table_2.pdf")
     tables = camelot.read_pdf(filename, flavor="stream")
-    assert df.equals(tables[0].df)
+    assert_frame_equal(df, tables[0].df)
+
+
+def test_stream_two_tables():
+    df1 = pd.DataFrame(data_stream_two_tables_1)
+    df2 = pd.DataFrame(data_stream_two_tables_2)
+
+    filename = os.path.join(testdir, "tabula/12s0324.pdf")
+    tables = camelot.read_pdf(filename, flavor="stream")
+
+    assert len(tables) == 2
+    assert df1.equals(tables[0].df)
+    assert df2.equals(tables[1].df)
+
+
+def test_stream_table_regions():
+    df = pd.DataFrame(data_stream_table_areas)
+
+    filename = os.path.join(testdir, "tabula/us-007.pdf")
+    tables = camelot.read_pdf(
+        filename, flavor="stream", table_regions=["320,460,573,335"]
+    )
+    assert_frame_equal(df, tables[0].df)
 
 
 def test_stream_table_areas():
     df = pd.DataFrame(data_stream_table_areas)
 
     filename = os.path.join(testdir, "tabula/us-007.pdf")
-    tables = camelot.read_pdf(filename, flavor="stream", table_areas=["320,500,573,335"])
+    tables = camelot.read_pdf(
-    assert df.equals(tables[0].df)
+        filename, flavor="stream", table_areas=["320,500,573,335"]
+    )
+    assert_frame_equal(df, tables[0].df)
 
 
 def test_stream_columns():
@@ -69,8 +91,9 @@ def test_stream_columns():
 
     filename = os.path.join(testdir, "mexican_towns.pdf")
     tables = camelot.read_pdf(
-        filename, flavor="stream", columns=["67,180,230,425,475"], row_close_tol=10)
+        filename, flavor="stream", columns=["67,180,230,425,475"], row_tol=10
-    assert df.equals(tables[0].df)
+    )
+    assert_frame_equal(df, tables[0].df)
 
 
 def test_stream_split_text():
@@ -78,8 +101,12 @@ def test_stream_split_text():
 
     filename = os.path.join(testdir, "tabula/m27.pdf")
     tables = camelot.read_pdf(
-        filename, flavor="stream", columns=["72,95,209,327,442,529,566,606,683"], split_text=True)
+        filename,
-    assert df.equals(tables[0].df)
+        flavor="stream",
+        columns=["72,95,209,327,442,529,566,606,683"],
+        split_text=True,
+    )
+    assert_frame_equal(df, tables[0].df)
 
 
 def test_stream_flag_size():
@@ -87,16 +114,43 @@ def test_stream_flag_size():
 
     filename = os.path.join(testdir, "superscript.pdf")
     tables = camelot.read_pdf(filename, flavor="stream", flag_size=True)
-    assert df.equals(tables[0].df)
+    assert_frame_equal(df, tables[0].df)
+
+
+def test_stream_strip_text():
+    df = pd.DataFrame(data_stream_strip_text)
+
+    filename = os.path.join(testdir, "detect_vertical_false.pdf")
+    tables = camelot.read_pdf(filename, flavor="stream", strip_text=" ,\n")
+    assert_frame_equal(df, tables[0].df)
+
+
+def test_stream_edge_tol():
+    df = pd.DataFrame(data_stream_edge_tol)
+
+    filename = os.path.join(testdir, "edge_tol.pdf")
+    tables = camelot.read_pdf(filename, flavor="stream", edge_tol=500)
+    assert_frame_equal(df, tables[0].df)
+
+
+def test_stream_layout_kwargs():
+    df = pd.DataFrame(data_stream_layout_kwargs)
+
+    filename = os.path.join(testdir, "detect_vertical_false.pdf")
+    tables = camelot.read_pdf(
+        filename, flavor="stream", layout_kwargs={"detect_vertical": False}
+    )
+    assert_frame_equal(df, tables[0].df)
 
 
 def test_lattice():
     df = pd.DataFrame(data_lattice)
 
     filename = os.path.join(
-        testdir, "tabula/icdar2013-dataset/competition-dataset-us/us-030.pdf")
+        testdir, "tabula/icdar2013-dataset/competition-dataset-us/us-030.pdf"
+    )
     tables = camelot.read_pdf(filename, pages="2")
-    assert df.equals(tables[0].df)
+    assert_frame_equal(df, tables[0].df)
 
 
 def test_lattice_table_rotated():
@@ -104,11 +158,30 @@ def test_lattice_table_rotated():
 
     filename = os.path.join(testdir, "clockwise_table_1.pdf")
     tables = camelot.read_pdf(filename)
-    assert df.equals(tables[0].df)
+    assert_frame_equal(df, tables[0].df)
 
     filename = os.path.join(testdir, "anticlockwise_table_1.pdf")
     tables = camelot.read_pdf(filename)
-    assert df.equals(tables[0].df)
+    assert_frame_equal(df, tables[0].df)
+
+
+def test_lattice_two_tables():
+    df1 = pd.DataFrame(data_lattice_two_tables_1)
+    df2 = pd.DataFrame(data_lattice_two_tables_2)
+
+    filename = os.path.join(testdir, "twotables_2.pdf")
+    tables = camelot.read_pdf(filename)
+    assert len(tables) == 2
+    assert df1.equals(tables[0].df)
+    assert df2.equals(tables[1].df)
+
+
+def test_lattice_table_regions():
+    df = pd.DataFrame(data_lattice_table_regions)
+
+    filename = os.path.join(testdir, "table_region.pdf")
+    tables = camelot.read_pdf(filename, table_regions=["170,370,560,270"])
+    assert_frame_equal(df, tables[0].df)
 
 
 def test_lattice_table_areas():
@@ -116,7 +189,7 @@ def test_lattice_table_areas():
 
     filename = os.path.join(testdir, "twotables_2.pdf")
     tables = camelot.read_pdf(filename, table_areas=["80,693,535,448"])
-    assert df.equals(tables[0].df)
+    assert_frame_equal(df, tables[0].df)
 
 
 def test_lattice_process_background():
@@ -124,15 +197,15 @@ def test_lattice_process_background():
 
     filename = os.path.join(testdir, "background_lines_1.pdf")
     tables = camelot.read_pdf(filename, process_background=True)
-    assert df.equals(tables[1].df)
+    assert_frame_equal(df, tables[1].df)
 
 
 def test_lattice_copy_text():
     df = pd.DataFrame(data_lattice_copy_text)
 
     filename = os.path.join(testdir, "row_span_1.pdf")
-    tables = camelot.read_pdf(filename, line_size_scaling=60, copy_text="v")
+    tables = camelot.read_pdf(filename, line_scale=60, copy_text="v")
-    assert df.equals(tables[0].df)
+    assert_frame_equal(df, tables[0].df)
 
 
 def test_lattice_shift_text():
@@ -141,13 +214,13 @@ def test_lattice_shift_text():
     df_rb = pd.DataFrame(data_lattice_shift_text_right_bottom)
 
     filename = os.path.join(testdir, "column_span_2.pdf")
-    tables = camelot.read_pdf(filename, line_size_scaling=40)
+    tables = camelot.read_pdf(filename, line_scale=40)
     assert df_lt.equals(tables[0].df)
 
-    tables = camelot.read_pdf(filename, line_size_scaling=40, shift_text=[''])
+    tables = camelot.read_pdf(filename, line_scale=40, shift_text=[""])
     assert df_disable.equals(tables[0].df)
 
-    tables = camelot.read_pdf(filename, line_size_scaling=40, shift_text=['r', 'b'])
+    tables = camelot.read_pdf(filename, line_scale=40, shift_text=["r", "b"])
     assert df_rb.equals(tables[0].df)
 
 
@@ -156,4 +229,88 @@ def test_repr():
     tables = camelot.read_pdf(filename)
     assert repr(tables) == "<TableList n=1>"
     assert repr(tables[0]) == "<Table shape=(7, 7)>"
-    assert repr(tables[0].cells[0][0]) == "<Cell x1=120.48 y1=218.42 x2=164.64 y2=233.89>"
+    assert (
+        repr(tables[0].cells[0][0]) == "<Cell x1=120.48 y1=218.43 x2=164.64 y2=233.77>"
+    )
+
+
+def test_pages():
+    url = "https://camelot-py.readthedocs.io/en/master/_static/pdf/foo.pdf"
+    tables = camelot.read_pdf(url)
+    assert repr(tables) == "<TableList n=1>"
+    assert repr(tables[0]) == "<Table shape=(7, 7)>"
+    assert (
+        repr(tables[0].cells[0][0]) == "<Cell x1=120.48 y1=218.43 x2=164.64 y2=233.77>"
+    )
+
+    tables = camelot.read_pdf(url, pages="1-end")
+    assert repr(tables) == "<TableList n=1>"
+    assert repr(tables[0]) == "<Table shape=(7, 7)>"
+    assert (
+        repr(tables[0].cells[0][0]) == "<Cell x1=120.48 y1=218.43 x2=164.64 y2=233.77>"
+    )
+
+    tables = camelot.read_pdf(url, pages="all")
+    assert repr(tables) == "<TableList n=1>"
+    assert repr(tables[0]) == "<Table shape=(7, 7)>"
+    assert (
+        repr(tables[0].cells[0][0]) == "<Cell x1=120.48 y1=218.43 x2=164.64 y2=233.77>"
+    )
+
+
+def test_url():
+    url = "https://camelot-py.readthedocs.io/en/master/_static/pdf/foo.pdf"
+    tables = camelot.read_pdf(url)
+    assert repr(tables) == "<TableList n=1>"
+    assert repr(tables[0]) == "<Table shape=(7, 7)>"
+    assert (
+        repr(tables[0].cells[0][0]) == "<Cell x1=120.48 y1=218.43 x2=164.64 y2=233.77>"
+    )
+
+
+def test_arabic():
+    df = pd.DataFrame(data_arabic)
+
+    filename = os.path.join(testdir, "tabula/arabic.pdf")
+    tables = camelot.read_pdf(filename)
+    assert_frame_equal(df, tables[0].df)
+
+
+def test_table_order():
+    def _make_table(page, order):
+        t = Table([], [])
+        t.page = page
+        t.order = order
+        return t
+
+    table_list = TableList(
+        [_make_table(2, 1), _make_table(1, 1), _make_table(3, 4), _make_table(1, 2)]
+    )
+
+    assert [(t.page, t.order) for t in sorted(table_list)] == [
+        (1, 1),
+        (1, 2),
+        (2, 1),
+        (3, 4),
+    ]
+    assert [(t.page, t.order) for t in sorted(table_list, reverse=True)] == [
+        (3, 4),
+        (2, 1),
+        (1, 2),
+        (1, 1),
+    ]
+
+
+def test_version_generation():
+    version = (0, 7, 3)
+    assert generate_version(version, prerelease=None, revision=None) == "0.7.3"
+
+
+def test_version_generation_with_prerelease_revision():
+    version = (0, 7, 3)
+    prerelease = "alpha"
+    revision = 2
+    assert (
+        generate_version(version, prerelease=prerelease, revision=revision)
+        == "0.7.3-alpha.2"
+    )

tests/test_errors.py

@@ -10,82 +10,93 @@ import camelot
 
 testdir = os.path.dirname(os.path.abspath(__file__))
 testdir = os.path.join(testdir, "files")
-filename = os.path.join(testdir, 'foo.pdf')
+filename = os.path.join(testdir, "foo.pdf")
 
 
 def test_unknown_flavor():
-    message = ("Unknown flavor specified."
+    message = "Unknown flavor specified." " Use either 'lattice' or 'stream'"
-               " Use either 'lattice' or 'stream'")
+    with pytest.raises(NotImplementedError, match=message):
-    with pytest.raises(NotImplementedError, message=message):
+        tables = camelot.read_pdf(filename, flavor="chocolate")
-        tables = camelot.read_pdf(filename, flavor='chocolate')
 
 
 def test_input_kwargs():
     message = "columns cannot be used with flavor='lattice'"
-    with pytest.raises(ValueError, message=message):
+    with pytest.raises(ValueError, match=message):
-        tables = camelot.read_pdf(filename, columns=['10,20,30,40'])
+        tables = camelot.read_pdf(filename, columns=["10,20,30,40"])
 
 
 def test_unsupported_format():
-    message = 'File format not supported'
+    message = "File format not supported"
-    filename = os.path.join(testdir, 'foo.csv')
+    filename = os.path.join(testdir, "foo.csv")
-    with pytest.raises(NotImplementedError, message=message):
+    with pytest.raises(NotImplementedError, match=message):
         tables = camelot.read_pdf(filename)
 
 
 def test_stream_equal_length():
-    message = ("Length of table_areas and columns"
+    message = "Length of table_areas and columns" " should be equal"
-               " should be equal")
+    with pytest.raises(ValueError, match=message):
-    with pytest.raises(ValueError, message=message):
+        tables = camelot.read_pdf(
-        tables = camelot.read_pdf(filename, flavor='stream',
+            filename,
-            table_areas=['10,20,30,40'], columns=['10,20,30,40', '10,20,30,40'])
+            flavor="stream",
+            table_areas=["10,20,30,40"],
+            columns=["10,20,30,40", "10,20,30,40"],
+        )
+
+
+def test_image_warning():
+    filename = os.path.join(testdir, "image.pdf")
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        with pytest.raises(UserWarning) as e:
+            tables = camelot.read_pdf(filename)
+            assert (
+                str(e.value)
+                == "page-1 is image-based, camelot only works on text-based pages."
+            )
 
 
 def test_no_tables_found():
-    filename = os.path.join(testdir, 'blank.pdf')
+    filename = os.path.join(testdir, "blank.pdf")
     with warnings.catch_warnings():
-        warnings.simplefilter('error')
+        warnings.simplefilter("error")
         with pytest.raises(UserWarning) as e:
             tables = camelot.read_pdf(filename)
-        assert str(e.value) == 'No tables found on page-1'
+        assert str(e.value) == "No tables found on page-1"
+
+
+def test_no_tables_found_logs_suppressed():
+    filename = os.path.join(testdir, "foo.pdf")
+    with warnings.catch_warnings():
+        # the test should fail if any warning is thrown
+        warnings.simplefilter("error")
+        try:
+            tables = camelot.read_pdf(filename, suppress_stdout=True)
+        except Warning as e:
+            warning_text = str(e)
+            pytest.fail(f"Unexpected warning: {warning_text}")
 
 
 def test_no_tables_found_warnings_suppressed():
-    filename = os.path.join(testdir, 'blank.pdf')
+    filename = os.path.join(testdir, "blank.pdf")
     with warnings.catch_warnings():
         # the test should fail if any warning is thrown
-        warnings.simplefilter('error')
+        warnings.simplefilter("error")
         try:
-            tables = camelot.read_pdf(filename, suppress_warnings=True)
+            tables = camelot.read_pdf(filename, suppress_stdout=True)
         except Warning as e:
             warning_text = str(e)
-            pytest.fail('Unexpected warning: {}'.format(warning_text))
+            pytest.fail(f"Unexpected warning: {warning_text}")
-
-
-def test_ghostscript_not_found(monkeypatch):
-    import distutils
-
-    def _find_executable_patch(arg):
-        return ''
-
-    monkeypatch.setattr(distutils.spawn, 'find_executable', _find_executable_patch)
-
-    message = ('Please make sure that Ghostscript is installed and available'
-               ' on the PATH environment variable')
-    filename = os.path.join(testdir, 'foo.pdf')
-    with pytest.raises(Exception, message=message):
-        tables = camelot.read_pdf(filename)
 
 
 def test_no_password():
-    filename = os.path.join(testdir, 'health_protected.pdf')
+    filename = os.path.join(testdir, "health_protected.pdf")
-    message = 'file has not been decrypted'
+    message = "file has not been decrypted"
-    with pytest.raises(Exception, message=message):
+    with pytest.raises(Exception, match=message):
         tables = camelot.read_pdf(filename)
 
 
 def test_bad_password():
-    filename = os.path.join(testdir, 'health_protected.pdf')
+    filename = os.path.join(testdir, "health_protected.pdf")
-    message = 'file has not been decrypted'
+    message = "file has not been decrypted"
-    with pytest.raises(Exception, message=message):
+    with pytest.raises(Exception, match=message):
-        tables = camelot.read_pdf(filename, password='wrongpass')
+        tables = camelot.read_pdf(filename, password="wrongpass")

tests/test_plotting.py

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+
+import os
+
+import pytest
+
+import camelot
+
+
+testdir = os.path.dirname(os.path.abspath(__file__))
+testdir = os.path.join(testdir, "files")
+
+
+@pytest.mark.mpl_image_compare(baseline_dir="files/baseline_plots", remove_text=True)
+def test_text_plot():
+    filename = os.path.join(testdir, "foo.pdf")
+    tables = camelot.read_pdf(filename)
+    return camelot.plot(tables[0], kind="text")
+
+
+@pytest.mark.mpl_image_compare(baseline_dir="files/baseline_plots", remove_text=True)
+def test_grid_plot():
+    filename = os.path.join(testdir, "foo.pdf")
+    tables = camelot.read_pdf(filename)
+    return camelot.plot(tables[0], kind="grid")
+
+
+@pytest.mark.mpl_image_compare(baseline_dir="files/baseline_plots", remove_text=True)
+def test_lattice_contour_plot():
+    filename = os.path.join(testdir, "foo.pdf")
+    tables = camelot.read_pdf(filename)
+    return camelot.plot(tables[0], kind="contour")
+
+
+@pytest.mark.mpl_image_compare(baseline_dir="files/baseline_plots", remove_text=True)
+def test_stream_contour_plot():
+    filename = os.path.join(testdir, "tabula/12s0324.pdf")
+    tables = camelot.read_pdf(filename, flavor="stream")
+    return camelot.plot(tables[0], kind="contour")
+
+
+@pytest.mark.mpl_image_compare(baseline_dir="files/baseline_plots", remove_text=True)
+def test_line_plot():
+    filename = os.path.join(testdir, "foo.pdf")
+    tables = camelot.read_pdf(filename)
+    return camelot.plot(tables[0], kind="line")
+
+
+@pytest.mark.mpl_image_compare(baseline_dir="files/baseline_plots", remove_text=True)
+def test_joint_plot():
+    filename = os.path.join(testdir, "foo.pdf")
+    tables = camelot.read_pdf(filename)
+    return camelot.plot(tables[0], kind="joint")
+
+
+@pytest.mark.mpl_image_compare(baseline_dir="files/baseline_plots", remove_text=True)
+def test_textedge_plot():
+    filename = os.path.join(testdir, "tabula/12s0324.pdf")
+    tables = camelot.read_pdf(filename, flavor="stream")
+    return camelot.plot(tables[0], kind="textedge")