Update HISTORY.md

[MRG] Add implementation of Anssi Nurminen's table detection algorithm

.editorconfig

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

.travis.yml

@@ -1,20 +1,32 @@
-sudo: false
+sudo: true
 language: python
 cache: pip
-python:
+addons:
-  - "2.7"
+  apt:
-  - "3.5"
+    update: true
-  - "3.6"
-matrix:
-  include:
-    - python: 3.7
-      dist: xenial
-      sudo: true
-before_install:
-  - sudo apt-get install python-tk python3-tk ghostscript
 install:
-  - pip install ".[dev]"
+  - make install
-script:
+jobs:
-  - pytest --verbose --cov-config .coveragerc --cov-report term --cov-report xml --cov=camelot tests
+  include:
-after_success:
+    - stage: test
-  - codecov --verbose
+      script:
+        - make test
+      python: '2.7'
+    - stage: test
+      script:
+        - make test
+      python: '3.5'
+    - stage: test
+      script:
+        - make test
+      python: '3.6'
+    - stage: test
+      script:
+        - make test
+      python: '3.7'
+      dist: xenial
+    - stage: coverage
+      python: '3.6'
+      script:
+        - make test
+        - codecov --verbose

HISTORY.md

@@ -1,6 +1,62 @@
 Release History
 ===============
 
+master
+------
+
+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)
+------------------
+
+**Improvements**
+
+* [#162](https://github.com/socialcopsdev/camelot/issues/162) Add password keyword argument. [#180](https://github.com/socialcopsdev/camelot/pull/180) by [rbares](https://github.com/rbares).
+    * An encrypted PDF can now be decrypted by passing `password='<PASSWORD>'` to `read_pdf` or `--password <PASSWORD>` to the command-line interface. (Limited encryption algorithm support from PyPDF2.)
+* [#139](https://github.com/socialcopsdev/camelot/issues/139) Add suppress_warnings keyword argument. [#155](https://github.com/socialcopsdev/camelot/pull/155) by [Jonathan Lloyd](https://github.com/jonathanlloyd).
+    * Warnings raised by Camelot can now be suppressed by passing `suppress_warnings=True` to `read_pdf` or `--quiet` to the command-line interface.
+* [#154](https://github.com/socialcopsdev/camelot/issues/154) The CLI can now be run using `python -m`. Try `python -m camelot --help`. [#159](https://github.com/socialcopsdev/camelot/pull/159) by [Parth P Panchal](https://github.com/pqrth).
+* [#165](https://github.com/socialcopsdev/camelot/issues/165) Rename `table_area` to `table_areas`. [#171](https://github.com/socialcopsdev/camelot/pull/171) by [Parth P Panchal](https://github.com/pqrth).
+
+**Bugfixes**
+
+* Raise error if the ghostscript executable is not on the PATH variable. [#166](https://github.com/socialcopsdev/camelot/pull/166) by Vinayak Mehta.
+* Convert filename to lowercase to check for PDF extension. [#169](https://github.com/socialcopsdev/camelot/pull/169) by [Vinicius Mesel](https://github.com/vmesel).
+
+**Files**
+
+* [#114](https://github.com/socialcopsdev/camelot/issues/114) Add Makefile and make codecov run only once. [#132](https://github.com/socialcopsdev/camelot/pull/132) by [Vaibhav Mule](https://github.com/vaibhavmule).
+* Add .editorconfig. [#151](https://github.com/socialcopsdev/camelot/pull/151) by [KOLANICH](https://github.com/KOLANICH).
+* Downgrade numpy version from 1.15.2 to 1.13.3.
+* Add requirements.txt for readthedocs.
+
+**Documentation**
+
+* Add "Using conda" section to installation instructions.
+* Add readthedocs badge.
+
 0.2.3 (2018-10-08)
 ------------------
 
@@ -63,4 +119,4 @@ Release History
 0.1.0 (2018-09-24)
 ------------------
 
-* Birth!
+* Rebirth!

Makefile

@@ -0,0 +1,28 @@
+.PHONY: docs
+INSTALL :=
+UNAME_S := $(shell uname -s)
+ifeq ($(UNAME_S),Linux)
+	INSTALL := @sudo apt install python-tk python3-tk ghostscript
+else ifeq ($(UNAME_S),Darwin)
+	INSTALL := @brew install tcl-tk ghostscript
+else
+	INSTALL := @echo "Please install tk and ghostscript"
+endif
+
+install:
+	$(INSTALL)
+	pip install --upgrade pip
+	pip install ".[dev]"
+
+test:
+	pytest --verbose --cov-config .coveragerc --cov-report term --cov-report xml --cov=camelot --mpl
+
+docs:
+	cd docs && make html
+	@echo "\033[95m\n\nBuild successful! View the docs homepage at docs/_build/html/index.html.\n\033[0m"
+
+publish:
+	pip install twine
+	python setup.py sdist
+	twine upload dist/*
+	rm -fr build dist .egg camelot_py.egg-info

README.md

@@ -4,11 +4,14 @@
 
 # Camelot: PDF Table Extraction for Humans
 
-[![Build Status](https://travis-ci.org/socialcopsdev/camelot.svg?branch=master)](https://travis-ci.org/socialcopsdev/camelot) [![codecov.io](https://codecov.io/github/socialcopsdev/camelot/badge.svg?branch=master&service=github)](https://codecov.io/github/socialcopsdev/camelot?branch=master)
+[![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/)
- [![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/)
+ [![codecov.io](https://codecov.io/github/socialcopsdev/camelot/badge.svg?branch=master&service=github)](https://codecov.io/github/socialcopsdev/camelot?branch=master)
+ [![image](https://img.shields.io/pypi/v/camelot-py.svg)](https://pypi.org/project/camelot-py/) [![image](https://img.shields.io/pypi/l/camelot-py.svg)](https://pypi.org/project/camelot-py/) [![image](https://img.shields.io/pypi/pyversions/camelot-py.svg)](https://pypi.org/project/camelot-py/) [![Gitter chat](https://badges.gitter.im/camelot-dev/Lobby.png)](https://gitter.im/camelot-dev/Lobby)
 
 **Camelot** is a Python library that makes it easy for *anyone* to extract tables from PDF files!
 
+**Note:** You can also check out [Excalibur](https://github.com/camelot-dev/excalibur), which is a web interface for Camelot!
+
 ---
 
 **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).
@@ -41,7 +44,7 @@
 | 2032_2     | 0.17      | 57.8          | 21.7%                | 0.3%            | 2.7%            | 1.2%           |
 | 4171_1     | 0.07      | 173.9         | 58.1%                | 1.6%            | 2.1%            | 0.5%           |
 
-There's a [command-line interface](https://camelot-py.readthedocs.io/en/latest/user/cli.html) too!
+There's a [command-line interface](https://camelot-py.readthedocs.io/en/master/user/cli.html) too!
 
 **Note:** Camelot only works with text-based PDFs and not scanned documents. (As Tabula [explains](https://github.com/tabulapdf/tabula#why-tabula), "If you can click and drag to select text in your table in a PDF viewer, then your PDF is text-based".)
 
@@ -56,15 +59,25 @@ See [comparison with other PDF table extraction libraries and tools](https://git
 
 ## Installation
 
-After [installing the dependencies](https://camelot-py.readthedocs.io/en/latest/user/install.html) ([tk](https://packages.ubuntu.com/trusty/python-tk) and [ghostscript](https://www.ghostscript.com/)), you can simply use pip to install Camelot:
+### Using conda
+
+The easiest way to install Camelot is to install it with [conda](https://conda.io/docs/), which is a package manager and  environment management system for the [Anaconda](http://docs.continuum.io/anaconda/) distribution.
 
 <pre>
-$ pip install camelot-py[all]
+$ conda install -c conda-forge camelot-py
 </pre>
 
-### Alternatively
+### Using pip
 
-After [installing the dependencies](https://camelot-py.readthedocs.io/en/latest/user/install.html), clone the repo using:
+After [installing the dependencies](https://camelot-py.readthedocs.io/en/master/user/install-deps.html) ([tk](https://packages.ubuntu.com/trusty/python-tk) and [ghostscript](https://www.ghostscript.com/)), you can simply use pip to install Camelot:
+
+<pre>
+$ pip install camelot-py[cv]
+</pre>
+
+### From the source code
+
+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
@@ -74,18 +87,16 @@ and install Camelot using pip:
 
 <pre>
 $ cd camelot
-$ pip install ".[all]"
+$ pip install ".[cv]"
 </pre>
 
-**Note:** Use a [virtualenv](https://virtualenv.pypa.io/en/stable/) if you don't want to affect your global Python installation.
-
 ## Documentation
 
 Great documentation is available at [http://camelot-py.readthedocs.io/](http://camelot-py.readthedocs.io/).
 
 ## Development
 
-The [Contributor's Guide](https://camelot-py.readthedocs.io/en/latest/dev/contributing.html) has detailed information about contributing code, documentation, tests and more. We've included some basic information in this README.
+The [Contributor's Guide](https://camelot-py.readthedocs.io/en/master/dev/contributing.html) has detailed information about contributing code, documentation, tests and more. We've included some basic information in this README.
 
 ### Source code
 
@@ -117,4 +128,4 @@ Camelot uses [Semantic Versioning](https://semver.org/). For the available versi
 
 ## License
 
-This project is licensed under the MIT License, see the [LICENSE](https://github.com/socialcopsdev/camelot/blob/master/LICENSE) file for details.
+This project is licensed under the MIT License, see the [LICENSE](https://github.com/socialcopsdev/camelot/blob/master/LICENSE) file for details.

camelot/__init__.py

@@ -2,10 +2,21 @@
 
 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')
 
@@ -15,3 +26,6 @@ handler = logging.StreamHandler()
 handler.setFormatter(formatter)
 
 logger.addHandler(handler)
+
+# instantiate plot method
+plot = PlotMethods()

camelot/__main__.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import absolute_import
+
+
+__all__ = ('main',)
+
+
+def main():
+    from camelot.cli import cli
+
+    cli()
+
+
+if __name__ == "__main__":
+    main()

camelot/__version__.py

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

camelot/cli.py

@@ -3,9 +3,14 @@
 import logging
 
 import click
+try:
+    import matplotlib.pyplot as plt
+except ImportError:
+    _HAS_MPL = False
+else:
+    _HAS_MPL = True
 
-from . import __version__
+from . import __version__, read_pdf, plot
-from .io import read_pdf
 
 
 logger = logging.getLogger('camelot')
@@ -27,6 +32,7 @@ pass_config = click.make_pass_decorator(Config)
 @click.version_option(version=__version__)
 @click.option('-p', '--pages', default='1', help='Comma-separated page numbers.'
               ' Example: 1,3,4 or 1,4-end.')
+@click.option('-pw', '--password', help='Password for decryption.')
 @click.option('-o', '--output', help='Output file path.')
 @click.option('-f', '--format',
               type=click.Choice(['csv', 'json', 'excel', 'html']),
@@ -38,6 +44,7 @@ pass_config = click.make_pass_decorator(Config)
               ' font size. Useful to detect super/subscripts.')
 @click.option('-M', '--margins', nargs=3, default=(1.0, 0.5, 0.1),
               help='PDFMiner char_margin, line_margin and word_margin.')
+@click.option('-q', '--quiet', is_flag=True, help='Suppress warnings.')
 @click.pass_context
 def cli(ctx, *args, **kwargs):
     """Camelot: PDF Table Extraction for Humans"""
@@ -47,7 +54,7 @@ def cli(ctx, *args, **kwargs):
 
 
 @cli.command('lattice')
-@click.option('-T', '--table_area', default=[], multiple=True,
+@click.option('-T', '--table_areas', default=[], multiple=True,
               help='Table areas to process. Example: x1,y1,x2,y2'
               ' where x1, y1 -> left-top and x2, y2 -> right-bottom.')
 @click.option('-back', '--process_background', is_flag=True,
@@ -78,8 +85,8 @@ def cli(ctx, *args, **kwargs):
 @click.option('-I', '--iterations', default=0,
               help='Number of times for erosion/dilation will be applied.')
 @click.option('-plot', '--plot_type',
-              type=click.Choice(['text', 'table', 'contour', 'joint', 'line']),
+              type=click.Choice(['text', 'grid', 'contour', 'joint', 'line']),
-              help='Plot geometry found on PDF page, for debugging.')
+              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):
@@ -89,31 +96,39 @@ def lattice(c, *args, **kwargs):
     output = conf.pop('output')
     f = conf.pop('format')
     compress = conf.pop('zip')
+    suppress_warnings = conf.pop('quiet')
     plot_type = kwargs.pop('plot_type')
     filepath = kwargs.pop('filepath')
     kwargs.update(conf)
 
-    table_area = list(kwargs['table_area'])
+    table_areas = list(kwargs['table_areas'])
-    kwargs['table_area'] = None if not table_area else table_area
+    kwargs['table_areas'] = None if not table_areas else table_areas
     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', **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')
         if f is None:
             raise click.UsageError('Please specify output file format using --format')
+
+    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:
+            plot(table, kind=plot_type)
+            plt.show()
+    else:
         tables.export(output, f=f, compress=compress)
 
 
 @cli.command('stream')
-@click.option('-T', '--table_area', default=[], multiple=True,
+@click.option('-T', '--table_areas', default=[], 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,
@@ -123,8 +138,8 @@ def lattice(c, *args, **kwargs):
 @click.option('-c', '--col_close_tol', default=0, help='Tolerance parameter'
               ' used to combine text horizontally, to generate columns.')
 @click.option('-plot', '--plot_type',
-              type=click.Choice(['text', 'table']),
+              type=click.Choice(['text', 'grid']),
-              help='Plot geometry found on PDF page for debugging.')
+              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):
@@ -134,23 +149,31 @@ def stream(c, *args, **kwargs):
     output = conf.pop('output')
     f = conf.pop('format')
     compress = conf.pop('zip')
+    suppress_warnings = conf.pop('quiet')
     plot_type = kwargs.pop('plot_type')
     filepath = kwargs.pop('filepath')
     kwargs.update(conf)
 
-    table_area = list(kwargs['table_area'])
+    table_areas = list(kwargs['table_areas'])
-    kwargs['table_area'] = None if not table_area else table_area
+    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', **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')
         if f is None:
             raise click.UsageError('Please specify output file format using --format')
+
+    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:
+            plot(table, kind=plot_type)
+            plt.show()
+    else:
         tables.export(output, f=f, compress=compress)

camelot/core.py

@@ -3,11 +3,208 @@
 import os
 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
+# y coordinate tolerance for extending textedge
+TEXTEDGE_EXTEND_TOLERANCE = 50
+# 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):
+        return '<TextEdge x={} y0={} y1={} align={} valid={}>'.format(
+            round(self.x, 2), round(self.y0, 2), round(self.y1, 2), self.align, self.is_valid)
+
+    def update_coords(self, x, y0):
+        """Updates the text edge's x and bottom y coordinates and sets
+        the is_valid attribute.
+        """
+        if np.isclose(self.y0, y0, atol=TEXTEDGE_EXTEND_TOLERANCE):
+            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):
+        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)
+
+    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):
@@ -321,33 +518,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.
 

camelot/handlers.py

@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
 
 import os
+import sys
 
 from PyPDF2 import PdfFileReader, PdfFileWriter
 
@@ -21,14 +22,22 @@ class PDFHandler(object):
         Path to 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'.
+    password : str, optional (default: None)
+        Password for decryption.
 
     """
-    def __init__(self, filename, pages='1'):
+    def __init__(self, filename, pages='1', password=None):
         self.filename = filename
-        if not self.filename.endswith('.pdf'):
+        if not filename.lower().endswith('.pdf'):
             raise NotImplementedError("File format not supported")
         self.pages = self._get_pages(self.filename, pages)
+        if password is None:
+            self.password = ''
+        else:
+            self.password = password
+            if sys.version_info[0] < 3:
+                self.password = self.password.encode('ascii')
 
     def _get_pages(self, filename, pages):
         """Converts pages string to list of ints.
@@ -52,6 +61,8 @@ class PDFHandler(object):
             page_numbers.append({'start': 1, 'end': 1})
         else:
             infile = PdfFileReader(open(filename, 'rb'), strict=False)
+            if infile.isEncrypted:
+                infile.decrypt(self.password)
             if pages == 'all':
                 page_numbers.append({'start': 1, 'end': infile.getNumPages()})
             else:
@@ -84,7 +95,7 @@ class PDFHandler(object):
         with open(filename, 'rb') as fileobj:
             infile = PdfFileReader(fileobj, strict=False)
             if infile.isEncrypted:
-                infile.decrypt('')
+                infile.decrypt(self.password)
             fpath = os.path.join(temp, 'page-{0}.pdf'.format(page))
             froot, fext = os.path.splitext(fpath)
             p = infile.getPage(page - 1)
@@ -103,7 +114,7 @@ class PDFHandler(object):
                 os.rename(fpath, fpath_new)
                 infile = PdfFileReader(open(fpath_new, 'rb'), strict=False)
                 if infile.isEncrypted:
-                    infile.decrypt('')
+                    infile.decrypt(self.password)
                 outfile = PdfFileWriter()
                 p = infile.getPage(0)
                 if rotation == 'anticlockwise':
@@ -130,9 +141,6 @@ 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 = []

camelot/io.py

@@ -1,10 +1,12 @@
 # -*- coding: utf-8 -*-
+import warnings
 
 from .handlers import PDFHandler
 from .utils import validate_input, remove_extra
 
 
-def read_pdf(filepath, pages='1', flavor='lattice', **kwargs):
+def read_pdf(filepath, pages='1', password=None, flavor='lattice',
+             suppress_warnings=False, **kwargs):
     """Read PDF and return extracted tables.
 
     Note: kwargs annotated with ^ can only be used with flavor='stream'
@@ -16,11 +18,15 @@ def read_pdf(filepath, pages='1', flavor='lattice', **kwargs):
         Path to 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'.
+    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.
-    table_area : list, optional (default: None)
+    suppress_warnings : bool, optional (default: False)
+        Prevent warnings from being emitted by Camelot.
+    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.
@@ -85,8 +91,12 @@ def read_pdf(filepath, pages='1', flavor='lattice', **kwargs):
         raise NotImplementedError("Unknown flavor specified."
                                   " Use either 'lattice' or 'stream'")
 
-    validate_input(kwargs, flavor=flavor)
+    with warnings.catch_warnings():
-    p = PDFHandler(filepath, pages)
+        if suppress_warnings:
-    kwargs = remove_extra(kwargs, flavor=flavor)
+            warnings.simplefilter("ignore")
-    tables = p.parse(flavor=flavor, **kwargs)
+
-    return tables
+        validate_input(kwargs, flavor=flavor)
+        p = PDFHandler(filepath, pages=pages, password=password)
+        kwargs = remove_extra(kwargs, flavor=flavor)
+        tables = p.parse(flavor=flavor, **kwargs)
+        return tables

camelot/parsers/lattice.py

@@ -28,7 +28,7 @@ class Lattice(BaseParser):
 
     Parameters
     ----------
-    table_area : list, optional (default: None)
+    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.
@@ -76,12 +76,12 @@ class Lattice(BaseParser):
         For more information, refer `PDFMiner docs <https://euske.github.io/pdfminer/>`_.
 
     """
-    def __init__(self, table_area=None, process_background=False,
+    def __init__(self, table_areas=None, process_background=False,
                  line_size_scaling=15, copy_text=None, shift_text=['l', 't'],
                  split_text=False, flag_size=False, line_close_tol=2,
                  joint_close_tol=2, threshold_blocksize=15, threshold_constant=-2,
                  iterations=0, margins=(1.0, 0.5, 0.1), **kwargs):
-        self.table_area = table_area
+        self.table_areas = table_areas
         self.process_background = process_background
         self.line_size_scaling = line_size_scaling
         self.copy_text = copy_text
@@ -174,15 +174,39 @@ class Lattice(BaseParser):
         return t
 
     def _generate_image(self):
-        # TODO: hacky, get rid of ghostscript #96
+        # TODO: get rid of ghostscript #96
-        def get_platform():
+        def get_executable():
             import platform
+            from distutils.spawn import find_executable
 
-            info = {
+            class GhostscriptNotFound(Exception): pass
-                'system': platform.system().lower(),
+
-                'machine': platform.machine().lower()
+            gs = None
-            }
+            system = platform.system().lower()
-            return info
+            try:
+                if system == 'windows':
+                    if find_executable('gswin32c.exe'):
+                        gs = 'gswin32c.exe'
+                    elif find_executable('gswin64c.exe'):
+                        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 = [
@@ -193,15 +217,9 @@ class Lattice(BaseParser):
             '-r600',
             self.filename
         ]
-        info = get_platform()
+        gs = get_executable()
-        if info['system'] == 'windows':
+        gs_call.insert(0, gs)
-            bit = info['machine'][-2:]
+
-            gs_call.insert(0, 'gswin{}c.exe'.format(bit))
-        else:
-            if 'ghostscript' in subprocess.check_output(['gs', '-version']).decode('utf-8').lower():
-                gs_call.insert(0, 'gs')
-            else:
-                gs_call.insert(0, "gsc")
         subprocess.call(
             gs_call, stdout=open(os.devnull, 'w'),
             stderr=subprocess.STDOUT)
@@ -226,9 +244,9 @@ class Lattice(BaseParser):
             self.threshold, direction='horizontal',
             line_size_scaling=self.line_size_scaling, iterations=self.iterations)
 
-        if self.table_area is not None:
+        if self.table_areas is not None:
             areas = []
-            for area in self.table_area:
+            for area in self.table_areas:
                 x1, y1, x2, y2 = area.split(",")
                 x1 = float(x1)
                 y1 = float(y1)
@@ -344,6 +362,7 @@ class Lattice(BaseParser):
                 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

@@ -9,7 +9,7 @@ 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,
                      compute_whitespace)
 
@@ -26,7 +26,7 @@ class Stream(BaseParser):
 
     Parameters
     ----------
-    table_area : list, optional (default: None)
+    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.
@@ -50,10 +50,10 @@ class Stream(BaseParser):
         For more information, refer `PDFMiner docs <https://euske.github.io/pdfminer/>`_.
 
     """
-    def __init__(self, table_area=None, columns=None, split_text=False,
+    def __init__(self, table_areas=None, columns=None, split_text=False,
                  flag_size=False, row_close_tol=2, col_close_tol=0,
                  margins=(1.0, 0.5, 0.1), **kwargs):
-        self.table_area = table_area
+        self.table_areas = table_areas
         self.columns = columns
         self._validate_columns()
         self.split_text = split_text
@@ -116,7 +116,7 @@ class Stream(BaseParser):
                     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
@@ -241,15 +241,40 @@ class Stream(BaseParser):
         return cols
 
     def _validate_columns(self):
-        if self.table_area is not None and self.columns is not None:
+        if self.table_areas is not None and self.columns is not None:
-            if len(self.table_area) != len(self.columns):
+            if len(self.table_areas) != len(self.columns):
-                raise ValueError("Length of table_area and columns"
+                raise ValueError("Length of table_areas and columns"
                                  " 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()
+        # generate left, middle and right textedges
+        textedges.generate(textlines)
+        # select relevant edges
+        relevant_textedges = textedges.get_relevant()
+        # 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_area is not None:
+        if self.table_areas is not None:
             table_bbox = {}
-            for area in self.table_area:
+            for area in self.table_areas:
                 x1, y1, x2, y2 = area.split(",")
                 x1 = float(x1)
                 y1 = float(y1)
@@ -257,7 +282,8 @@ class Stream(BaseParser):
                 y2 = float(y2)
                 table_bbox[(x1, y2, x2, y1)] = None
         else:
-            table_bbox = {(0, 0, self.pdf_width, self.pdf_height): None}
+            # find tables based on nurminen's detection algorithm
+            table_bbox = self._nurminen_table_detection(self.horizontal_text)
         self.table_bbox = table_bbox
 
     def _generate_columns_and_rows(self, table_idx, tk):
@@ -286,10 +312,21 @@ class Stream(BaseParser):
             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("No tables found in table area {}".format(
+                        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)
             inner_text = []
@@ -361,6 +398,7 @@ class Stream(BaseParser):
                 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,179 @@
-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 == 'stream' and kind in ['contour', 'joint', 'line']:
-                (t[0], t[1]),
+            raise NotImplementedError("Stream flavor does not support kind='{}'".format(
-                t[2] - t[0],
+                                      kind))
-                t[3] - t[1]
+
+        plot_method = getattr(self, kind)
+        return plot_method(table)
+
+    def text(self, table):
+        """Generates a plot for all text elements 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')
+        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_xlim(min(xs) - 10, max(xs) + 10)
+        ax.set_ylim(min(ys) - 10, max(ys) + 10)
-    ax.set_ylim(min(ys) - 10, max(ys) + 10)
+        return fig
-    plt.show()
 
+    def grid(self, table):
+        """Generates a plot for the detected table grids
+        on the PDF page.
 
-def plot_table(table):
+        Parameters
-    """Generates a plot for the table.
+        ----------
+        table : camelot.core.Table
 
-    Parameters
+        Returns
-    ----------
+        -------
-    table : camelot.core.Table
+        fig : matplotlib.fig.Figure
 
-    """
+        """
-    for row in table.cells:
+        fig = plt.figure()
-        for cell in row:
+        ax = fig.add_subplot(111, aspect='equal')
-            if cell.left:
+        for row in table.cells:
-                plt.plot([cell.lb[0], cell.lt[0]],
+            for cell in row:
-                         [cell.lb[1], cell.lt[1]])
+                if cell.left:
-            if cell.right:
+                    ax.plot([cell.lb[0], cell.lt[0]],
-                plt.plot([cell.rb[0], cell.rt[0]],
+                            [cell.lb[1], cell.lt[1]])
-                         [cell.rb[1], cell.rt[1]])
+                if cell.right:
-            if cell.top:
+                    ax.plot([cell.rb[0], cell.rt[0]],
-                plt.plot([cell.lt[0], cell.rt[0]],
+                            [cell.rb[1], cell.rt[1]])
-                         [cell.lt[1], cell.rt[1]])
+                if cell.top:
-            if cell.bottom:
+                    ax.plot([cell.lt[0], cell.rt[0]],
-                plt.plot([cell.lb[0], cell.rb[0]],
+                            [cell.lt[1], cell.rt[1]])
-                         [cell.lb[1], cell.rb[1]])
+                if cell.bottom:
-    plt.show()
+                    ax.plot([cell.lb[0], cell.rb[0]],
+                            [cell.lb[1], cell.rb[1]])
+        return fig
 
+    def contour(self, table):
+        """Generates a plot for all table boundaries present
+        on the PDF page.
 
-def plot_contour(image):
+        Parameters
-    """Generates a plot for all table boundaries present on the
+        ----------
-    PDF page.
+        table : camelot.core.Table
 
-    Parameters
+        Returns
-    ----------
+        -------
-    image : tuple
+        fig : matplotlib.fig.Figure
 
-    """
+        """
-    img, table_bbox = image
+        img, table_bbox = table._image
-    for t in table_bbox.keys():
+        fig = plt.figure()
-        cv2.rectangle(img, (t[0], t[1]),
+        ax = fig.add_subplot(111, aspect='equal')
-                      (t[2], t[3]), (255, 0, 0), 20)
+        for t in table_bbox.keys():
-    plt.imshow(img)
+            ax.add_patch(
-    plt.show()
+                patches.Rectangle(
+                    (t[0], t[1]),
+                    t[2] - t[0],
+                    t[3] - t[1],
+                    fill=None,
+                    edgecolor='red'
+                )
+            )
+        ax.imshow(img)
+        return fig
 
+    def joint(self, table):
+        """Generates a plot for all line intersections present
+        on the PDF page.
 
-def plot_joint(image):
+        Parameters
-    """Generates a plot for all line intersections present on the
+        ----------
-    PDF page.
+        table : camelot.core.Table
 
-    Parameters
+        Returns
-    ----------
+        -------
-    image : tuple
+        fig : matplotlib.fig.Figure
 
-    """
+        """
-    img, table_bbox = image
+        img, table_bbox = table._image
-    x_coord = []
+        fig = plt.figure()
-    y_coord = []
+        ax = fig.add_subplot(111, aspect='equal')
-    for k in table_bbox.keys():
+        x_coord = []
-        for coord in table_bbox[k]:
+        y_coord = []
-            x_coord.append(coord[0])
+        for k in table_bbox.keys():
-            y_coord.append(coord[1])
+            for coord in table_bbox[k]:
-    plt.plot(x_coord, y_coord, 'ro')
+                x_coord.append(coord[0])
-    plt.imshow(img)
+                y_coord.append(coord[1])
-    plt.show()
+        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.
 
-def plot_line(segments):
+        Parameters
-    """Generates a plot for all line segments present on the PDF page.
+        ----------
+        table : camelot.core.Table
 
-    Parameters
+        Returns
-    ----------
+        -------
-    segments : tuple
+        fig : matplotlib.fig.Figure
 
-    """
+        """
-    vertical, horizontal = segments
+        fig = plt.figure()
-    for v in vertical:
+        ax = fig.add_subplot(111, aspect='equal')
-        plt.plot([v[0], v[2]], [v[1], v[3]])
+        vertical, horizontal = table._segments
-    for h in horizontal:
+        for v in vertical:
-        plt.plot([h[0], h[2]], [h[1], h[3]])
+            ax.plot([v[0], v[2]], [v[1], v[3]])
-    plt.show()
+        for h in horizontal:
+            ax.plot([h[0], h[2]], [h[1], h[3]])
+        return fig

docs/conf.py

@@ -63,7 +63,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Camelot'
-copyright = u'2018, Peeply Private Ltd (Singapore)'
+copyright = u'2018, <a href="https://socialcops.com" target="_blank">SocialCops</a>'
 author = u'Vinayak Mehta'
 
 # The version info for the project you're documenting, acts as replacement for

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
 ---------------

docs/index.rst

@@ -11,6 +11,10 @@ Release v\ |version|. (:ref:`Installation <install>`)
 .. image:: https://travis-ci.org/socialcopsdev/camelot.svg?branch=master
     :target: https://travis-ci.org/socialcopsdev/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
     :target: https://codecov.io/github/socialcopsdev/camelot?branch=master
 
@@ -23,8 +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
+
 **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!
+
+.. _Excalibur: https://github.com/camelot-dev/excalibur
+
 ----
 
 **Here's how you can extract tables from PDF files.** Check out the PDF used in this example `here`_.
@@ -81,6 +92,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
@@ -107,4 +119,4 @@ you.
 .. toctree::
    :maxdepth: 2
 
-   dev/contributing
+   dev/contributing

docs/user/advanced.rst

@@ -27,22 +27,24 @@ To process background lines, you can pass ``process_background=True``.
 .. 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'
 
-.. note:: The last three geometries can only be used with :ref:`Lattice <lattice>`, i.e. when ``flavor='lattice'``.
+.. note:: The last three plot types can only be used with :ref:`Lattice <lattice>`, i.e. when ``flavor='lattice'``.
 
-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 +52,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 +59,10 @@ 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
+.. figure:: ../_static/png/plot_text.png
     :height: 674
     :width: 1366
     :scale: 50%
@@ -72,18 +73,17 @@ 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
+.. figure:: ../_static/png/plot_table.png
     :height: 674
     :width: 1366
     :scale: 50%
@@ -92,8 +92,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 +99,16 @@ 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
+.. 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 +116,16 @@ 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
+.. 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,9 +133,10 @@ 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
+.. figure:: ../_static/png/plot_joint.png
     :height: 674
     :width: 1366
     :scale: 50%
@@ -149,7 +146,7 @@ Finally, let's plot all line intersections present on the table's PDF page.
 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 left-top and right-bottom coordinates of the table.
+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 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.
 
@@ -166,15 +163,15 @@ Table areas that you want Camelot to analyze can be passed as a list of comma-se
 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!
 
 ::
 
@@ -282,23 +279,25 @@ 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_size_scaling=40``, and plot the table again.
 
 ::
 
     >>> tables = camelot.read_pdf('short_lines.pdf', line_size_scaling=40)
-    >>> tables[0].plot('table')
+    >>> camelot.plot(tables[0], kind='grid')
+    >>> plt.show()
 
 .. figure:: ../_static/png/short_lines_2.png
     :alt: An improved plot of the PDF table with short lines
@@ -416,4 +415,4 @@ We don't need anything else. Now, let's pass ``copy_text=['v']`` to copy text in
     "3","Odisha","Kalahandi","iii. Food Poisoning","42","0","02/01/14","03/01/14","Under control","..."
     "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","..."
+    "4","West Bengal","Howrah","vi. Viral Hepatitis A &E","85","0","26/12/13","27/12/13","Under surveillance","..."

docs/user/cli.rst

@@ -11,12 +11,13 @@ You can print the help for the interface by typing ``camelot --help`` in your fa
 
   Usage: camelot [OPTIONS] COMMAND [ARGS]...
 
-  Camelot: PDF Table Extraction for Humans
+    Camelot: PDF Table Extraction for Humans
 
   Options:
     --version                       Show the version and exit.
     -p, --pages TEXT                Comma-separated page numbers. Example: 1,3,4
                                     or 1,4-end.
+    -pw, --password TEXT            Password for decryption.
     -o, --output TEXT               Output file path.
     -f, --format [csv|json|excel|html]
                                     Output file format.
@@ -27,8 +28,9 @@ You can print the help for the interface by typing ``camelot --help`` in your fa
     -M, --margins <FLOAT FLOAT FLOAT>...
                                     PDFMiner char_margin, line_margin and
                                     word_margin.
+    -q, --quiet                     Suppress warnings.
     --help                          Show this message and exit.
 
   Commands:
     lattice  Use lines between text to parse the table.
-    stream   Use spaces between text to parse the table.
+    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 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,76 @@
+.. _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`_.
+
+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
+
+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,90 +3,37 @@
 Installation of Camelot
 =======================
 
-This part of the documentation covers how to install Camelot. First, you'll need to install the dependencies, which include `Tkinter`_ and `ghostscript`_.
+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 a package manager and environment management system for the `Anaconda`_ distribution.
+::
+
+    $ conda install -c conda-forge 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/
+.. _downloads page: https://www.ghostscript.com/download/gsdnld.html
+.. _conda-forge: https://conda-forge.org/
+
+Using pip
+---------
+
+After :ref:`installing the dependencies <install_deps>`, which include `Tkinter`_ and `ghostscript`_, you can simply use pip to install Camelot::
+
+    $ pip install camelot-py[cv]
 
 .. _Tkinter: https://wiki.python.org/moin/TkInter
 .. _ghostscript: https://www.ghostscript.com
 
-Install the dependencies
+From the source code
-------------------------
+--------------------
 
-These can be installed using your system's package manager. You can run one of the following, based on your OS.
+After :ref:`installing the dependencies <install_deps>`, you can install from the source by:
-
-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.
-
-$ pip install camelot-py[all]
------------------------------
-
-After installing the dependencies, you can simply use pip to install Camelot::
-
-    $ pip install camelot-py[all]
-
-Get the source code
--------------------
-
-Alternatively, you can install from the source by:
 
 1. Cloning the GitHub repository.
 ::
@@ -97,4 +44,4 @@ Alternatively, you can install from the source by:
 ::
 
     $ cd camelot
-    $ pip install ".[all]"
+    $ pip install ".[cv]"

docs/user/quickstart.rst

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

requirements.txt

@@ -0,0 +1,8 @@
+click>=6.7
+matplotlib>=2.2.3
+numpy>=1.13.3
+opencv-python>=3.4.2.17
+openpyxl>=2.5.8
+pandas>=0.23.4
+pdfminer.six>=20170720
+PyPDF2>=1.26.0

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

@@ -15,25 +15,31 @@ with open('README.md', 'r') as f:
 
 requires = [
     'click>=6.7',
-    'matplotlib>=2.2.3',
+    'numpy>=1.13.3',
-    'numpy>=1.15.2',
     'openpyxl>=2.5.8',
     'pandas>=0.23.4',
     'pdfminer.six>=20170720',
     '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-cov>=2.6.0',
+    'pytest-mpl>=0.10',
     'pytest-runner>=4.2',
     'Sphinx>=1.7.9'
 ]
+
+all_requires = cv_requires + plot_requires
 dev_requires = dev_requires + all_requires
 
 
@@ -51,7 +57,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': [
@@ -76,5 +84,5 @@ def setup_package():
     setup(**metadata)
 
 
-if __name__ >= '__main__':
+if __name__ == '__main__':
     setup_package()

tests/__init__.py

@@ -0,0 +1,2 @@
+import matplotlib
+matplotlib.use('agg')

tests/data.py

@@ -33,55 +33,141 @@ data_stream = [
     ["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"],
+    ["Punjab", "19,775,485", "2,208,343", "2,470,882", "0", "24,454,710", "1,436,522", "25,891,232"]
-    ["", "Health Sector Financing by Centre and States/UTs in India [2009-10 to 2012-13](Revised)                               P a g e  |23", "", "", "", "", "", ""]
 ]
 
 data_stream_table_rotated = [
-    ["", "", "Table 21  Current use of contraception by background characteristics\u2014Continued", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
+    ["Table 21  Current use of contraception by background characteristics\u2014Continued", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
-    ["", "", "", "", "", "", "Modern method", "", "", "", "", "", "", "Traditional method", "", "", "", ""],
+    ["", "", "", "", "", "Modern method", "", "", "", "", "", "", "Traditional method", "", "", "", ""],
-    ["", "", "", "Any", "", "", "", "", "", "", "Other", "Any", "", "", "", "Not", "", "Number"],
+    ["", "", "Any", "", "", "", "", "", "", "Other", "Any", "", "", "", "Not", "", "Number"],
-    ["", "", "Any", "modern", "Female", "Male", "", "", "", "Condom/", "modern", "traditional", "", "With-", "Folk", "currently", "", "of"],
+    ["", "Any", "modern", "Female", "Male", "", "", "", "Condom/", "modern", "traditional", "", "With-", "Folk", "currently", "", "of"],
-    ["", "Background characteristic", "method", "method", "sterilization", "sterilization", "Pill", "IUD", "Injectables", "Nirodh", "method", "method", "Rhythm", "drawal", "method", "using", "Total", "women"],
+    ["Background characteristic", "method", "method", "sterilization", "sterilization", "Pill", "IUD", "Injectables", "Nirodh", "method", "method", "Rhythm", "drawal", "method", "using", "Total", "women"],
-    ["", "Caste/tribe", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
+    ["Caste/tribe", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
-    ["", "Scheduled caste", "74.8", "55.8", "42.9", "0.9", "9.7", "0.0", "0.2", "2.2", "0.0", "19.0", "11.2", "7.4", "0.4", "25.2", "100.0", "1,363"],
+    ["Scheduled caste", "74.8", "55.8", "42.9", "0.9", "9.7", "0.0", "0.2", "2.2", "0.0", "19.0", "11.2", "7.4", "0.4", "25.2", "100.0", "1,363"],
-    ["", "Scheduled tribe", "59.3", "39.0", "26.8", "0.6", "6.4", "0.6", "1.2", "3.5", "0.0", "20.3", "10.4", "5.8", "4.1", "40.7", "100.0", "256"],
+    ["Scheduled tribe", "59.3", "39.0", "26.8", "0.6", "6.4", "0.6", "1.2", "3.5", "0.0", "20.3", "10.4", "5.8", "4.1", "40.7", "100.0", "256"],
-    ["", "Other backward class", "71.4", "51.1", "34.9", "0.0", "8.6", "1.4", "0.0", "6.2", "0.0", "20.4", "12.6", "7.8", "0.0", "28.6", "100.0", "211"],
+    ["Other backward class", "71.4", "51.1", "34.9", "0.0", "8.6", "1.4", "0.0", "6.2", "0.0", "20.4", "12.6", "7.8", "0.0", "28.6", "100.0", "211"],
-    ["", "Other", "71.1", "48.8", "28.2", "0.8", "13.3", "0.9", "0.3", "5.2", "0.1", "22.3", "12.9", "9.1", "0.3", "28.9", "100.0", "3,319"],
+    ["Other", "71.1", "48.8", "28.2", "0.8", "13.3", "0.9", "0.3", "5.2", "0.1", "22.3", "12.9", "9.1", "0.3", "28.9", "100.0", "3,319"],
-    ["", "Wealth index", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
+    ["Wealth index", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
-    ["", "Lowest", "64.5", "48.6", "34.3", "0.5", "10.5", "0.6", "0.7", "2.0", "0.0", "15.9", "9.9", "4.6", "1.4", "35.5", "100.0", "1,258"],
+    ["Lowest", "64.5", "48.6", "34.3", "0.5", "10.5", "0.6", "0.7", "2.0", "0.0", "15.9", "9.9", "4.6", "1.4", "35.5", "100.0", "1,258"],
-    ["", "Second", "68.5", "50.4", "36.2", "1.1", "11.4", "0.5", "0.1", "1.1", "0.0", "18.1", "11.2", "6.7", "0.2", "31.5", "100.0", "1,317"],
+    ["Second", "68.5", "50.4", "36.2", "1.1", "11.4", "0.5", "0.1", "1.1", "0.0", "18.1", "11.2", "6.7", "0.2", "31.5", "100.0", "1,317"],
-    ["", "Middle", "75.5", "52.8", "33.6", "0.6", "14.2", "0.4", "0.5", "3.4", "0.1", "22.7", "13.4", "8.9", "0.4", "24.5", "100.0", "1,018"],
+    ["Middle", "75.5", "52.8", "33.6", "0.6", "14.2", "0.4", "0.5", "3.4", "0.1", "22.7", "13.4", "8.9", "0.4", "24.5", "100.0", "1,018"],
-    ["", "Fourth", "73.9", "52.3", "32.0", "0.5", "12.5", "0.6", "0.2", "6.3", "0.2", "21.6", "11.5", "9.9", "0.2", "26.1", "100.0", "908"],
+    ["Fourth", "73.9", "52.3", "32.0", "0.5", "12.5", "0.6", "0.2", "6.3", "0.2", "21.6", "11.5", "9.9", "0.2", "26.1", "100.0", "908"],
-    ["", "Highest", "78.3", "44.4", "19.5", "1.0", "9.7", "1.4", "0.0", "12.7", "0.0", "33.8", "18.2", "15.6", "0.0", "21.7", "100.0", "733"],
+    ["Highest", "78.3", "44.4", "19.5", "1.0", "9.7", "1.4", "0.0", "12.7", "0.0", "33.8", "18.2", "15.6", "0.0", "21.7", "100.0", "733"],
-    ["", "Number of living children", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
+    ["Number of living children", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
-    ["", "No children", "25.1", "7.6", "0.3", "0.5", "2.0", "0.0",
+    ["No children", "25.1", "7.6", "0.3", "0.5", "2.0", "0.0",
     "0.0", "4.8", "0.0", "17.5", "9.0", "8.5", "0.0", "74.9", "100.0", "563"],
-    ["", "1 child", "66.5", "32.1", "3.7", "0.7", "20.1", "0.7", "0.1", "6.9", "0.0", "34.3", "18.9", "15.2", "0.3", "33.5", "100.0", "1,190"],
+    ["1 child", "66.5", "32.1", "3.7", "0.7", "20.1", "0.7", "0.1", "6.9", "0.0", "34.3", "18.9", "15.2", "0.3", "33.5", "100.0", "1,190"],
-    ["\x18\x18", "1 son", "66.8", "33.2", "4.1", "0.7", "21.1", "0.5", "0.3", "6.6", "0.0", "33.5", "21.2", "12.3", "0.0", "33.2", "100.0", "672"],
+    ["1 son", "66.8", "33.2", "4.1", "0.7", "21.1", "0.5", "0.3", "6.6", "0.0", "33.5", "21.2", "12.3", "0.0", "33.2", "100.0", "672"],
-    ["", "No sons", "66.1", "30.7", "3.1", "0.6", "18.8", "0.8", "0.0", "7.3", "0.0", "35.4", "15.8", "19.0", "0.6", "33.9", "100.0", "517"],
+    ["No sons", "66.1", "30.7", "3.1", "0.6", "18.8", "0.8", "0.0", "7.3", "0.0", "35.4", "15.8", "19.0", "0.6", "33.9", "100.0", "517"],
-    ["", "2 children", "81.6", "60.5", "41.8", "0.9", "11.6", "0.8", "0.3", "4.8", "0.2", "21.1", "12.2", "8.3", "0.6", "18.4", "100.0", "1,576"],
+    ["2 children", "81.6", "60.5", "41.8", "0.9", "11.6", "0.8", "0.3", "4.8", "0.2", "21.1", "12.2", "8.3", "0.6", "18.4", "100.0", "1,576"],
-    ["", "1 or more sons", "83.7", "64.2", "46.4", "0.9", "10.8", "0.8", "0.4", "4.8", "0.1", "19.5", "11.1", "7.6", "0.7", "16.3", "100.0", "1,268"],
+    ["1 or more sons", "83.7", "64.2", "46.4", "0.9", "10.8", "0.8", "0.4", "4.8", "0.1", "19.5", "11.1", "7.6", "0.7", "16.3", "100.0", "1,268"],
-    ["", "No sons", "73.2", "45.5", "23.2", "1.0", "15.1", "0.9", "0.0", "4.8", "0.5", "27.7", "16.8", "11.0", "0.0", "26.8", "100.0", "308"],
+    ["No sons", "73.2", "45.5", "23.2", "1.0", "15.1", "0.9", "0.0", "4.8", "0.5", "27.7", "16.8", "11.0", "0.0", "26.8", "100.0", "308"],
-    ["", "3 children", "83.9", "71.2", "57.7", "0.8", "9.8", "0.6", "0.5", "1.8", "0.0", "12.7", "8.7", "3.3", "0.8", "16.1", "100.0", "961"],
+    ["3 children", "83.9", "71.2", "57.7", "0.8", "9.8", "0.6", "0.5", "1.8", "0.0", "12.7", "8.7", "3.3", "0.8", "16.1", "100.0", "961"],
-    ["", "1 or more sons", "85.0", "73.2", "60.3", "0.9", "9.4", "0.5", "0.5", "1.6", "0.0", "11.8", "8.1", "3.0", "0.7", "15.0", "100.0", "860"],
+    ["1 or more sons", "85.0", "73.2", "60.3", "0.9", "9.4", "0.5", "0.5", "1.6", "0.0", "11.8", "8.1", "3.0", "0.7", "15.0", "100.0", "860"],
-    ["", "No sons", "74.7", "53.8", "35.3", "0.0", "13.7", "1.6", "0.0", "3.2", "0.0", "20.9", "13.4", "6.1", "1.5", "25.3", "100.0", "101"],
+    ["No sons", "74.7", "53.8", "35.3", "0.0", "13.7", "1.6", "0.0", "3.2", "0.0", "20.9", "13.4", "6.1", "1.5", "25.3", "100.0", "101"],
-    ["", "4+ children", "74.3", "58.1", "45.1", "0.6", "8.7", "0.6", "0.7", "2.4", "0.0", "16.1", "9.9", "5.4", "0.8", "25.7", "100.0", "944"],
+    ["4+ children", "74.3", "58.1", "45.1", "0.6", "8.7", "0.6", "0.7", "2.4", "0.0", "16.1", "9.9", "5.4", "0.8", "25.7", "100.0", "944"],
-    ["", "1 or more sons", "73.9", "58.2", "46.0", "0.7", "8.3", "0.7", "0.7", "1.9", "0.0", "15.7", "9.4", "5.5", "0.8", "26.1", "100.0", "901"],
+    ["1 or more sons", "73.9", "58.2", "46.0", "0.7", "8.3", "0.7", "0.7", "1.9", "0.0", "15.7", "9.4", "5.5", "0.8", "26.1", "100.0", "901"],
-    ["", "No sons", "(82.1)", "(57.3)", "(25.6)", "(0.0)", "(17.8)", "(0.0)", "(0.0)", "(13.9)", "(0.0)", "(24.8)", "(21.3)", "(3.5)", "(0.0)", "(17.9)", "100.0", "43"],
+    ["No sons", "(82.1)", "(57.3)", "(25.6)", "(0.0)", "(17.8)", "(0.0)", "(0.0)", "(13.9)", "(0.0)", "(24.8)", "(21.3)", "(3.5)", "(0.0)", "(17.9)", "100.0", "43"],
-    ["", "Total", "71.2", "49.9", "32.2",
+    ["Total", "71.2", "49.9", "32.2",
     "0.7", "11.7", "0.6", "0.3", "4.3", "0.1", "21.3", "12.3", "8.4", "0.5", "28.8", "100.0", "5,234"],
-    ["", "NFHS-2 (1998-99)", "66.6", "47.3", "32.0", "1.8", "9.2", "1.4", "na", "2.9", "na", "na", "8.7", "9.8", "na", "33.4", "100.0", "4,116"],
+    ["NFHS-2 (1998-99)", "66.6", "47.3", "32.0", "1.8", "9.2", "1.4", "na", "2.9", "na", "na", "8.7", "9.8", "na", "33.4", "100.0", "4,116"],
-    ["", "NFHS-1 (1992-93)", "57.7", "37.6", "26.5", "4.3", "3.6", "1.3", "0.1", "1.9", "na", "na", "11.3", "8.3", "na", "42.3", "100.0", "3,970"],
+    ["NFHS-1 (1992-93)", "57.7", "37.6", "26.5", "4.3", "3.6", "1.3", "0.1", "1.9", "na", "na", "11.3", "8.3", "na", "42.3", "100.0", "3,970"]
-    ["", "", "Note: If more than one method is used, only the most effective method is considered in this tabulation. Total includes women for whom caste/tribe was not known or is missing, who are", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
-    ["", "not shown separately.", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
-    ["", "na = Not available", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
-    ["", "", "ns = Not shown; see table 2b, footnote 1", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
-    ["", "( ) Based on 25-49 unweighted cases.", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
-    ["", "", "", "", "", "", "", "", "54", "", "", "", "", "", "", "", "", ""]
 ]
 
-data_stream_table_area = [
+data_stream_two_tables_1 = [
+    ["[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"],
+    ["Total   . . .  .  .  .  .  . .  . .  . .  . .  . .  . .  . .  . .  .  .", "11,062 .6", "1,540 .0", "9,522 .6", "8,263 .3", "1,071 .6", "7,191 .7", "2,799 .2", "468 .3", "2,330 .9"],
+    ["Violent crime  .  .  .  .  .  .  .  . .  . .  . .  . .  . .  .", "467 .9", "69 .1", "398 .8", "380 .2", "56 .5", "323 .7", "87 .7", "12 .6", "75 .2"],
+    ["Murder and nonnegligent", "", "", "", "", "", "", "", "", ""],
+    ["manslaughter . . . . . . . .. .. .. .. ..", "10.0", "0.9", "9.1", "9.0", "0.9", "8.1", "1.1", "–", "1.0"],
+    ["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"],
+    ["Larceny-theft . . . . . . . .. .. .. .. .. .", "1,080.1", "258.1", "822.0", "608.8", "140.5", "468.3", "471.3", "117.6", "353.6"],
+    ["Motor vehicle theft . . . . .. .. . .... .", "65.6", "16.0", "49.6", "53.9", "13.3", "40.7", "11.7", "2.7", "8.9"],
+    ["Arson .. . . . .. . ... .... .... .... .", "9.8", "4.3", "5.5", "8.1", "3.7", "4.4", "1.7", "0.6", "1.1"],
+    ["Other assaults .. . . . . .. . ... . ... ..", "1,061.3", "175.3", "886.1", "785.4", "115.4", "670.0", "276.0", "59.9", "216.1"],
+    ["Forgery and counterfeiting .. . . . . . ..", "68.9", "1.7", "67.2", "42.9", "1.2", "41.7", "26.0", "0.5", "25.5"],
+    ["Fraud .... .. . . .. ... .... .... ....", "173.7", "5.1", "168.5", "98.4", "3.3", "95.0", "75.3", "1.8", "73.5"],
+    ["Embezzlement . . .. . . . .. . ... . ....", "14.6", "–", "14.1", "7.2", "–", "6.9", "7.4", "–", "7.2"],
+    ["Stolen property 1  . . . . . . .. . .. .. ...", "84.3", "15.1", "69.2", "66.7", "12.2", "54.5", "17.6", "2.8", "14.7"],
+    ["Vandalism  . . . . . . . .. .. .. .. .. ....", "217.4", "72.7", "144.7", "178.1", "62.8", "115.3", "39.3", "9.9", "29.4"],
+    ["Weapons; carrying, possessing, etc. .", "132.9", "27.1", "105.8", "122.1", "24.3", "97.8", "10.8", "2.8", "8.0"],
+    ["Prostitution and commercialized vice",
+    "56.9", "1.1", "55.8", "17.3", "–", "17.1", "39.6", "0.8", "38.7"],
+    ["Sex offenses 2  . . . . .. . . . .. .. .. . ..", "61.5", "10.7", "50.7", "56.1", "9.6", "46.5", "5.4", "1.1", "4.3"],
+    ["Drug abuse violations  . . . . . . . .. ...", "1,333.0", "136.6", "1,196.4", "1,084.3", "115.2", "969.1", "248.7", "21.4", "227.3"],
+    ["Gambling .. . . . . .. ... . ... . ... ...", "8.2", "1.4", "6.8", "7.2", "1.4", "5.9", "0.9", "–", "0.9"],
+    ["Offenses against the family and", "", "", "", "", "", "", "", "", ""],
+    ["children . . . .. . . .. .. .. .. .. .. . ..", "92.4", "3.7", "88.7", "68.9", "2.4", "66.6", "23.4", "1.3", "22.1"],
+    ["Driving under the influence . . . . . .. .", "1,158.5", "109.2", "1,147.5", "895.8", "8.2", "887.6", "262.7", "2.7", "260.0"],
+    ["Liquor laws  . . . . . . . .. .. .. .. .. .. .", "48.2", "90.2", "368.0", "326.8", "55.4", "271.4",
+    "131.4", "34.7", "96.6"],
+    ["Drunkenness . . .. . . . .. . ... . ... ..", "488.1", "11.4", "476.8", "406.8", "8.5", "398.3", "81.3", "2.9", "78.4"],
+    ["Disorderly conduct . .. . . . . . .. .. .. .", "529.5", "136.1", "393.3", "387.1", "90.8", "296.2", "142.4", "45.3", "97.1"],
+    ["Vagrancy . . . .. . . . ... .... .... ...", "26.6", "2.2", "24.4", "20.9", "1.6", "19.3", "5.7", "0.6", "5.1"],
+    ["All other offenses (except traffic) . . ..", "306.1", "263.4", "2,800.8", "2,337.1", "194.2", "2,142.9", "727.0", "69.2", "657.9"],
+    ["Suspicion . . . .. . . .. .. .. .. .. .. . ..", "1.6", "–", "1.4", "1.2", "–", "1.0", "–", "–", "–"],
+    ["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.", "", "", "", "", "", "", "", ""]
+]
+
+data_stream_two_tables_2 = [
+    ["", "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"],
+    ["Total  . . . . .  . .  .  . .  .  . . .  .  . . .  .  . .  . . .  .  . . . . .  . .  . .  .", "10,690,561", "7,389,208", "3,027,153", "150,544", "123,656"],
+    ["Violent crime  .  .  .  .  .  .  .  . .  . .  . .  . .  . . . .  . .  . . . . . .  .", "456,965", "268,346", "177,766", "5,608", "5,245"],
+    ["Murder and nonnegligent manslaughter . .. ... .", "9,739", "4,741", "4,801", "100", "97"],
+    ["Forcible rape . . . . . . . .. .. .. .. .... .. ...... .", "16,362", "10,644", "5,319", "169", "230"],
+    ["Robbery . . . . .. . . . ... . ... . .... .... .... . . .", "100,496", "43,039", "55,742", "726", "989"],
+    ["Aggravated assault  . . . . . . . .. .. ...... .. ....", "330,368", "209,922", "111,904", "4,613", "3,929"],
+    ["Property crime  .  .  .  .  . .  .  .  .  . . .  .  . . .  . . . . .  . . .  . . .", "1,364,409", "922,139", "406,382", "17,599", "18,289"],
+    ["Burglary . . .. . . . .. . .... .... .... .... ... . . .", "234,551", "155,994", "74,419", "2,021", "2,117"],
+    ["Larceny-theft . . . . . . . .. .. .. .. .... .. ...... .", "1,056,473", "719,983", "306,625", "14,646", "15,219"],
+    ["Motor vehicle theft . . . . . .. ... . ... ..... ... ..", "63,919", "39,077", "23,184", "817", "841"],
+    ["Arson .. . . .. .. .. ... .... .... .... .... . . . . .", "9,466", "7,085", "2,154", "115", "112"],
+    ["Other assaults .. . . . . . ... . ... . ... ..... ... ..", "1,032,502", "672,865", "332,435", "15,127", "12,075"],
+    ["Forgery and counterfeiting .. . . . . . ... ..... .. ..", "67,054", "44,730", "21,251", "345", "728"],
+    ["Fraud ... . . . . .. .. .. .. .. .. .. .. .. .... . . . . . .", "161,233", "108,032", "50,367", "1,315", "1,519"],
+    ["Embezzlement . . . .. . . . ... . ... . .... ... .....", "13,960", "9,208", "4,429", "75", "248"],
+    ["Stolen property; buying, receiving, possessing .. .", "82,714", "51,953", "29,357", "662", "742"],
+    ["Vandalism  . . . . . . . .. .. .. .. .. .. .... .. ..... .", "212,173", "157,723", "48,746", "3,352", "2,352"],
+    ["Weapons—carrying, possessing, etc. .. .. ... .. .", "130,503", "74,942", "53,441", "951", "1,169"],
+    ["Prostitution and commercialized vice  . ... .. .. ..", "56,560", "31,699", "23,021", "427", "1,413"],
+    ["Sex offenses 1 . . . . . . . .. .. .. .. .... .. ...... .", "60,175", "44,240", "14,347", "715", "873"],
+    ["Drug abuse violations  . . . . . . . .. . ..... .. .....", "1,301,629", "845,974", "437,623", "8,588", "9,444"],
+    ["Gambling . . . . .. . . . ... . ... . .. ... . ...... .. .", "8,046", "2,290", "5,518", "27", "211"],
+    ["Offenses against the family and children ... .. .. .", "87,232", "58,068", "26,850", "1,690", "624"],
+    ["Driving under the influence . . . . . . .. ... ...... .", "1,105,401", "954,444", "121,594", "14,903", "14,460"],
+    ["Liquor laws  . . . . . . . .. .. .. .. .. . ..... .. .....", "444,087", "373,189", "50,431", "14,876", "5,591"],
+    ["Drunkenness . .. . . . . . ... . ... . ..... . .......", "469,958", "387,542", "71,020", "8,552", "2,844"],
+    ["Disorderly conduct . . .. . . . . .. .. . ..... .. .....", "515,689", "326,563", "176,169", "8,783", "4,174"],
+    ["Vagrancy . . .. .. . . .. ... .... .... .... .... . . .", "26,347", "14,581", "11,031", "543", "192"],
+    ["All other offenses (except traffic) . .. .. .. ..... ..", "2,929,217", "1,937,221", "911,670", "43,880", "36,446"],
+    ["Suspicion . . .. . . . .. .. .. .. .. .. .. ...... .. . . .", "1,513", "677", "828", "1", "7"],
+    ["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,", "", "", "", ""]
+]
+
+data_stream_table_areas = [
     ["", "One Withholding"],
     ["Payroll Period", "Allowance"],
     ["Weekly", "$71.15"],
@@ -187,14 +273,10 @@ data_stream_split_text = [
     ["", "", "", "", "1522 WEST LINDSEY", "", "", "", "", ""],
     ["632575", "BAW", "BASHU LEGENDS", "HYH HE CHUANG LLC", "STREET", "NORMAN", "OK", "73069", "-", "2014/07/21"],
     ["", "", "", "DEEP FORK HOLDINGS", "", "", "", "", "", ""],
-    ["543149", "BAW", "BEDLAM BAR-B-Q", "LLC", "610 NORTHEAST 50TH", "OKLAHOMA CITY", "OK", "73105", "(405) 528-7427", "2015/02/23"],
+    ["543149", "BAW", "BEDLAM BAR-B-Q", "LLC", "610 NORTHEAST 50TH", "OKLAHOMA CITY", "OK", "73105", "(405) 528-7427", "2015/02/23"]
-    ["", "", "", "", "Page 1 of 151", "", "", "", "", ""]
 ]
 
 data_stream_flag_size = [
-    ["", "TABLE 125: STATE-WISE COMPOSITION OF OUTSTANDING LIABILITIES - 1997 <s>(Contd.)</s>", "", "", "", "", "", "", "", "", ""],
-    ["", "", "", "", "(As at end-March)", "", "", "", "", "", ""],
-    ["", "", "", "", "", "", "", "", "", "", "(<s>`</s> Billion)"],
     ["States", "Total", "Market", "NSSF", "WMA", "Loans", "Loans", "Loans", "Loans", "Loans", "Loans"],
     ["", "Internal", "Loans", "", "from", "from", "from", "from", "from", "from SBI", "from"],
     ["", "Debt", "", "", "RBI", "Banks", "LIC", "GIC", "NABARD", "& Other", "NCDC"],
@@ -230,9 +312,7 @@ data_stream_flag_size = [
     ["Uttar Pradesh", "80.62", "74.89", "-", "4.34", "1.34", "0.6", "-", "-0.21", "0.18", "0.03"],
     ["West Bengal", "34.23", "32.19", "-", "-", "2.04", "0.77", "-", "0.06", "-", "0.51"],
     ["NCT Delhi", "-", "-", "-", "-", "-", "-", "-", "-", "-", "-"],
-    ["ALL STATES", "513.38", "436.02", "-", "25.57", "51.06", "14.18", "-", "8.21", "11.83", "11.08"],
+    ["ALL STATES", "513.38", "436.02", "-", "25.57", "51.06", "14.18", "-", "8.21", "11.83", "11.08"]
-    ["<s>2</s> Includes `2.45 crore outstanding under “Market Loan Suspense”.", "", "", "", "", "", "", "", "", "", ""],
-    ["", "", "", "", "445", "", "", "", "", "", ""]
 ]
 
 data_lattice = [
@@ -261,7 +341,39 @@ data_lattice_table_rotated = [
     ["Pooled", "38742", "53618", "60601", "86898", "4459", "21918", "27041", "14312", "18519"]
 ]
 
-data_lattice_table_area = [
+data_lattice_two_tables_1 = [
+    ["State", "n", "Literacy Status", "", "", "", "", ""],
+    ["", "", "Illiterate", "Read & Write", "1-4 std.", "5-8 std.", "9-12 std.", "College"],
+    ["Kerala", "2400", "7.2", "0.5", "25.3", "20.1", "41.5", "5.5"],
+    ["Tamil Nadu", "2400", "21.4", "2.3", "8.8", "35.5", "25.8", "6.2"],
+    ["Karnataka", "2399", "37.4", "2.8", "12.5", "18.3", "23.1", "5.8"],
+    ["Andhra Pradesh", "2400", "54.0", "1.7", "8.4", "13.2", "18.8", "3.9"],
+    ["Maharashtra", "2400", "22.0", "0.9", "17.3", "20.3", "32.6", "7.0"],
+    ["Gujarat", "2390", "28.6", "0.1", "14.4", "23.1", "26.9", "6.8"],
+    ["Madhya Pradesh", "2402", "29.1", "3.4", "8.5", "35.1", "13.3", "10.6"],
+    ["Orissa", "2405", "33.2", "1.0", "10.4", "25.7", "21.2", "8.5"],
+    ["West Bengal", "2293", "41.7", "4.4", "13.2", "17.1", "21.2", "2.4"],
+    ["Uttar Pradesh", "2400", "35.3", "2.1", "4.5", "23.3", "27.1", "7.6"],
+    ["Pooled", "23889", "30.9", "1.9", "12.3", "23.2", "25.2", "6.4"]
+]
+
+data_lattice_two_tables_2 = [
+    ["State", "n", "Literacy Status", "", "", "", "", ""],
+    ["", "", "Illiterate", "Read & Write", "1-4 std.", "5-8 std.", "9-12 std.", "College"],
+    ["Kerala", "2400", "8.8", "0.3", "20.1", "17.0", "45.6", "8.2"],
+    ["Tamil Nadu", "2400", "29.9", "1.5", "8.5", "33.1", "22.3", "4.8"],
+    ["Karnataka", "2399", "47.9", "2.5", "10.2", "18.8", "18.4", "2.3"],
+    ["Andhra Pradesh", "2400", "66.4", "0.7", "6.8", "12.9", "11.4", "1.8"],
+    ["Maharashtra", "2400", "41.3", "0.6", "14.1", "20.1", "21.6", "2.2"],
+    ["Gujarat", "2390", "57.6", "0.1", "10.3", "16.5", "12.9", "2.7"],
+    ["Madhya Pradesh", "2402", "58.7", "2.2", "6.6", "24.1", "5.3", "3.0"],
+    ["Orissa", "2405", "50.0", "0.9", "8.1", "21.9", "15.1", "4.0"],
+    ["West Bengal", "2293", "49.1", "4.8", "11.2", "16.8", "17.1", "1.1"],
+    ["Uttar Pradesh", "2400", "67.3", "2.0", "3.1", "17.2", "7.7", "2.7"],
+    ["Pooled", "23889", "47.7", "1.5", "9.9", "19.9", "17.8", "3.3"]
+]
+
+data_lattice_table_areas = [
     ["", "", "", "", "", "", "", "", ""],
     ["State", "n", "Literacy Status", "", "", "", "", "", ""],
     ["", "", "Illiterate", "Read & Write", "1-4 std.", "5-8 std.", "9-12 std.", "College", ""],

tests/test_cli.py

@@ -1,79 +1,117 @@
-# -*- coding: utf-8 -*-
+# -*- coding: utf-8 -*-
-
+
-import os
+import os
-
+
-from click.testing import CliRunner
+from click.testing import CliRunner
-
+
-from camelot.cli import cli
+from camelot.cli import cli
-from camelot.utils import TemporaryDirectory
+from camelot.utils import TemporaryDirectory
-
+
-
+
-testdir = os.path.dirname(os.path.abspath(__file__))
+testdir = os.path.dirname(os.path.abspath(__file__))
-testdir = os.path.join(testdir, 'files')
+testdir = os.path.join(testdir, 'files')
-
+
-
+
-def test_cli_lattice():
+def test_cli_lattice():
-    with TemporaryDirectory() as tempdir:
+    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()
+        runner = CliRunner()
-        result = runner.invoke(cli, ['--format', 'csv', '--output', outfile,
+        result = runner.invoke(cli, ['--format', 'csv', '--output', outfile,
-                                     'lattice', infile])
+                                     'lattice', infile])
-        assert result.exit_code == 0
+        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
+        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
+        assert format_error in result.output
-
+
-
+
-def test_cli_stream():
+def test_cli_stream():
-    with TemporaryDirectory() as tempdir:
+    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()
+        runner = CliRunner()
-        result = runner.invoke(cli, ['--format', 'csv', '--output', outfile,
+        result = runner.invoke(cli, ['--format', 'csv', '--output', outfile,
-                                     'stream', infile])
+                                     'stream', infile])
-        assert result.exit_code == 0
+        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
+        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
+        assert format_error in result.output
-
+
-
+
-def test_cli_output_format():
+def test_cli_password():
-    with TemporaryDirectory() as tempdir:
+    with TemporaryDirectory() as tempdir:
-        infile = os.path.join(testdir, 'health.pdf')
+        infile = os.path.join(testdir, 'health_protected.pdf')
-        outfile = os.path.join(tempdir, 'health.{}')
+        outfile = os.path.join(tempdir, 'health_protected.csv')
-        runner = CliRunner()
+        runner = CliRunner()
-
+        result = runner.invoke(cli, ['--password', 'userpass',
-        # json
+                                     '--format', 'csv', '--output', outfile,
-        result = runner.invoke(cli, ['--format', 'json', '--output', outfile.format('json'),
+                                     'stream', infile])
-                                     'stream', infile])
+        assert result.exit_code == 0
-        assert result.exit_code == 0
+        assert result.output == 'Found 1 tables\n'
-
+
-        # excel
+        output_error = 'file has not been decrypted'
-        result = runner.invoke(cli, ['--format', 'excel', '--output', outfile.format('xlsx'),
+        # no password
-                                     'stream', infile])
+        result = runner.invoke(cli, ['--format', 'csv', '--output', outfile,
-        assert result.exit_code == 0
+                                     'stream', infile])
-
+        assert output_error in str(result.exception)
-        # html
+
-        result = runner.invoke(cli, ['--format', 'html', '--output', outfile.format('html'),
+        # bad password
-                                     'stream', infile])
+        result = runner.invoke(cli, ['--password', 'wrongpass',
-        assert result.exit_code == 0
+                                     '--format', 'csv', '--output', outfile,
-
+                                     'stream', infile])
-        # zip
+        assert output_error in str(result.exception)
-        result = runner.invoke(cli, ['--zip', '--format', 'csv', '--output', outfile.format('csv'),
+
-                                     'stream', infile])
+
-        assert result.exit_code == 0
+def test_cli_output_format():
+    with TemporaryDirectory() as tempdir:
+        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'),
+                                     'stream', infile])
+        assert result.exit_code == 0
+
+        # excel
+        result = runner.invoke(cli, ['--format', 'excel', '--output', outfile.format('xlsx'),
+                                     'stream', infile])
+        assert result.exit_code == 0
+
+        # html
+        result = runner.invoke(cli, ['--format', 'html', '--output', outfile.format('html'),
+                                     'stream', infile])
+        assert result.exit_code == 0
+
+        # zip
+        result = runner.invoke(cli, ['--zip', '--format', 'csv', '--output', outfile.format('csv'),
+                                     'stream', infile])
+        assert result.exit_code == 0
+
+def test_cli_quiet():
+    with TemporaryDirectory() as tempdir:
+        infile = os.path.join(testdir, 'blank.pdf')
+        outfile = os.path.join(tempdir, 'blank.csv')
+        runner = CliRunner()
+
+        result = runner.invoke(cli, ['--format', 'csv', '--output', outfile,
+                                     'stream', infile])
+        assert 'No tables found on page-1' in result.output
+
+        result = runner.invoke(cli, ['--quiet', '--format', 'csv',
+                                     '--output', outfile, 'stream', infile])
+        assert 'No tables found on page-1' not in result.output

tests/test_common.py

@@ -25,6 +25,17 @@ def test_parsing_report():
     assert tables[0].parsing_report == parsing_report
 
 
+def test_password():
+    df = pd.DataFrame(data_stream)
+
+    filename = os.path.join(testdir, "health_protected.pdf")
+    tables = camelot.read_pdf(filename, password="ownerpass", flavor="stream")
+    assert df.equals(tables[0].df)
+
+    tables = camelot.read_pdf(filename, password="userpass", flavor="stream")
+    assert df.equals(tables[0].df)
+
+
 def test_stream():
     df = pd.DataFrame(data_stream)
 
@@ -45,11 +56,22 @@ def test_stream_table_rotated():
     assert df.equals(tables[0].df)
 
 
-def test_stream_table_area():
+def test_stream_two_tables():
-    df = pd.DataFrame(data_stream_table_area)
+    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_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_area=["320,500,573,335"])
+    tables = camelot.read_pdf(filename, flavor="stream", table_areas=["320,500,573,335"])
     assert df.equals(tables[0].df)
 
 
@@ -100,11 +122,22 @@ def test_lattice_table_rotated():
     assert df.equals(tables[0].df)
 
 
-def test_lattice_table_area():
+def test_lattice_two_tables():
-    df = pd.DataFrame(data_lattice_table_area)
+    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, table_area=["80,693,535,448"])
+    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_areas():
+    df = pd.DataFrame(data_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)
 
 
@@ -139,7 +172,7 @@ def test_lattice_shift_text():
     tables = camelot.read_pdf(filename, line_size_scaling=40, shift_text=['r', 'b'])
     assert df_rb.equals(tables[0].df)
 
-    
+
 def test_repr():
     filename = os.path.join(testdir, "foo.pdf")
     tables = camelot.read_pdf(filename)

tests/test_errors.py

@@ -34,20 +34,58 @@ def test_unsupported_format():
 
 
 def test_stream_equal_length():
-    message = ("Length of table_area and columns"
+    message = ("Length of table_areas and columns"
                " should be equal")
     with pytest.raises(ValueError, message=message):
         tables = camelot.read_pdf(filename, flavor='stream',
-            table_area=['10,20,30,40'], columns=['10,20,30,40', '10,20,30,40'])
+            table_areas=['10,20,30,40'], columns=['10,20,30,40', '10,20,30,40'])
 
 
 def test_no_tables_found():
     filename = os.path.join(testdir, 'blank.pdf')
-    # TODO: use pytest.warns
     with warnings.catch_warnings():
         warnings.simplefilter('error')
-        try:
+        with pytest.raises(UserWarning) as e:
             tables = camelot.read_pdf(filename)
-        except Exception as e:
+        assert str(e.value) == 'No tables found on page-1'
-            assert type(e).__name__ == 'UserWarning'
+
-            assert str(e) == 'No tables found on page-1'
+
+def test_no_tables_found_warnings_suppressed():
+    filename = os.path.join(testdir, 'blank.pdf')
+    with warnings.catch_warnings():
+        # the test should fail if any warning is thrown
+        warnings.simplefilter('error')
+        try:
+            tables = camelot.read_pdf(filename, suppress_warnings=True)
+        except Warning as e:
+            warning_text = str(e)
+            pytest.fail('Unexpected warning: {}'.format(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')
+    message = 'file has not been decrypted'
+    with pytest.raises(Exception, message=message):
+        tables = camelot.read_pdf(filename)
+
+
+def test_bad_password():
+    filename = os.path.join(testdir, 'health_protected.pdf')
+    message = 'file has not been decrypted'
+    with pytest.raises(Exception, message=message):
+        tables = camelot.read_pdf(filename, password='wrongpass')

tests/test_plotting.py

@@ -0,0 +1,51 @@
+# -*- 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_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_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')