Switch to quiet output by default, Add verbose parameter to API calls

Fixes #84

Author: JazzCore

README.rst

@@ -97,15 +97,11 @@ You can specify all wkhtmltopdf `options <http://wkhtmltopdf.org/usage/wkhtmltop
 
 	pdfkit.from_url('http://google.com', 'out.pdf', options=options)
 
-By default, PDFKit will show all ``wkhtmltopdf`` output. If you don't want it, you need to pass ``quiet`` option:
+By default, PDFKit will run ``wkhtmltopdf`` with ``quiet`` option turned on, since in most cases output is not needed and can cause excessive memory usage and corrupted results. If need to get ``wkhtmltopdf`` output you should pass ``verbose=True`` to API calls:
 
 .. code-block:: python
 
-    options = {
-        'quiet': ''
-        }
-
-    pdfkit.from_url('google.com', 'out.pdf', options=options)
+    pdfkit.from_url('google.com', 'out.pdf', verbose=True)
 
 Due to wkhtmltopdf command syntax, **TOC** and **Cover** options must be specified separately. If you need cover before TOC, use ``cover_first`` option:
 
@@ -179,6 +175,29 @@ Also you can use ``configuration()`` call to check if wkhtmltopdf is present in
 Troubleshooting
 ---------------
 
+Debugging issues with PDF generation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you struggling to generate correct PDF firstly you should check wkhtmltopdf output for some clues, you can get it by passing ``verbose=True`` to API calls:
+
+.. code-block:: python
+
+	pdfkit.from_url('http://google.com', 'out.pdf', verbose=True)
+
+If you are getting strage results in PDF or some option looks like its ignored you should try to run ``wkhtmltopdf`` directly to see if it produces the same result. You can get CLI command by creating ``pdfkit.PDFKit`` class directly and then calling its ``command()`` method:
+
+.. code-block:: python
+
+	import pdfkit
+
+	r = pdfkit.PDFKit('html', 'string', verbose=True)
+	print(' '.join(r.command()))
+	# try running wkhtmltopdf to create PDF
+	output = r.to_pdf()
+
+Common errors:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 - ``IOError: 'No wkhtmltopdf executable found'``:
 
   Make sure that you have wkhtmltopdf in your `$PATH` or set via custom configuration (see preceding section). *where wkhtmltopdf* in Windows or *which wkhtmltopdf* on Linux should return actual path to binary.

pdfkit/api.py

@@ -5,7 +5,7 @@
 
 
 def from_url(url, output_path=None, options=None, toc=None, cover=None,
-             configuration=None, cover_first=False):
+             configuration=None, cover_first=False, verbose=False):
     """
     Convert file of files from URLs to PDF document
 
@@ -16,18 +16,19 @@ def from_url(url, output_path=None, options=None, toc=None, cover=None,
     :param cover: (optional) string with url/filename with a cover html page
     :param configuration: (optional) instance of pdfkit.configuration.Configuration()
     :param cover_first: (optional) if True, cover always precedes TOC
+    :param verbose: (optional) By default '--quiet' is passed to all calls, set this to False to get wkhtmltopdf output to stdout.
 
     Returns: True on success
     """
 
     r = PDFKit(url, 'url', options=options, toc=toc, cover=cover,
-               configuration=configuration, cover_first=cover_first)
+               configuration=configuration, cover_first=cover_first, verbose=verbose)
 
     return r.to_pdf(output_path)
 
 
 def from_file(input, output_path=None, options=None, toc=None, cover=None, css=None,
-              configuration=None, cover_first=False):
+              configuration=None, cover_first=False, verbose=False):
     """
     Convert HTML file or files to PDF document
 
@@ -39,18 +40,19 @@ def from_file(input, output_path=None, options=None, toc=None, cover=None, css=N
     :param css: (optional) string with path to css file which will be added to a single input file
     :param configuration: (optional) instance of pdfkit.configuration.Configuration()
     :param cover_first: (optional) if True, cover always precedes TOC
+    :param verbose: (optional) By default '--quiet' is passed to all calls, set this to False to get wkhtmltopdf output to stdout.
 
     Returns: True on success
     """
 
     r = PDFKit(input, 'file', options=options, toc=toc, cover=cover, css=css,
-               configuration=configuration, cover_first=cover_first)
+               configuration=configuration, cover_first=cover_first, verbose=verbose)
 
     return r.to_pdf(output_path)
 
 
 def from_string(input, output_path=None, options=None, toc=None, cover=None, css=None,
-                configuration=None, cover_first=False):
+                configuration=None, cover_first=False, verbose=False):
     """
     Convert given string or strings to PDF document
 
@@ -62,12 +64,13 @@ def from_string(input, output_path=None, options=None, toc=None, cover=None, css
     :param css: (optional) string with path to css file which will be added to a input string
     :param configuration: (optional) instance of pdfkit.configuration.Configuration()
     :param cover_first: (optional) if True, cover always precedes TOC
+    :param verbose: (optional) By default '--quiet' is passed to all calls, set this to False to get wkhtmltopdf output to stdout.
 
     Returns: True on success
     """
 
     r = PDFKit(input, 'string', options=options, toc=toc, cover=cover, css=css,
-               configuration=configuration, cover_first=cover_first)
+               configuration=configuration, cover_first=cover_first, verbose=verbose)
 
     return r.to_pdf(output_path)
 

pdfkit/pdfkit.py

@@ -39,7 +39,7 @@ def __str__(self):
             return self.msg
 
     def __init__(self, url_or_file, type_, options=None, toc=None, cover=None,
-                 css=None, configuration=None, cover_first=False):
+                 css=None, configuration=None, cover_first=False, verbose=False):
 
         self.source = Source(url_or_file, type_)
         self.configuration = (Configuration() if configuration is None
@@ -61,6 +61,7 @@ def __init__(self, url_or_file, type_, options=None, toc=None, cover=None,
         self.toc = {} if toc is None else toc
         self.cover = cover
         self.cover_first = cover_first
+        self.verbose = verbose
         self.css = css
         self.stylesheets = []
 
@@ -89,6 +90,9 @@ def _command(self, path=None):
 
         yield self.wkhtmltopdf
 
+        if not self.verbose:
+            self.options.update({'--quiet': ''})
+
         for argpart in self._genargs(self.options):
             if argpart:
                 yield argpart
@@ -133,10 +137,12 @@ def handle_error(exit_code, stderr):
         if exit_code == 0:
             return
 
+        stderr_lines = stderr.splitlines()
+
         # Sometimes wkhtmltopdf will exit with non-zero
         # even if it finishes generation.
         # If will display 'Done' in the second last line
-        if stderr.splitlines()[-2].strip() == 'Done':
+        if len(stderr_lines) > 1 and stderr.splitlines()[-2].strip() == 'Done':
             return
 
         if 'cannot connect to X server' in stderr:

tests/pdfkit-tests.py

@@ -201,8 +201,9 @@ def test_skip_nonpdfkit_tags(self):
 
     def test_toc_handling_without_options(self):
         r = pdfkit.PDFKit('hmtl', 'string', toc={'xsl-style-sheet': 'test.xsl'})
-        self.assertEqual(r.command()[1], 'toc')
-        self.assertEqual(r.command()[2], '--xsl-style-sheet')
+        self.assertEqual(r.command()[1], '--quiet')
+        self.assertEqual(r.command()[2], 'toc')
+        self.assertEqual(r.command()[3], '--xsl-style-sheet')
 
     def test_toc_with_options(self):
         options = {
@@ -217,16 +218,18 @@ def test_toc_with_options(self):
 
         command = r.command()
 
-        self.assertEqual(command[1 + len(options) * 2], 'toc')
-        self.assertEqual(command[1 + len(options) * 2 + 1], '--xsl-style-sheet')
+        self.assertEqual(command[1 + len(options) * 2], '--quiet')
+        self.assertEqual(command[2 + len(options) * 2], 'toc')
+        self.assertEqual(command[2 + len(options) * 2 + 1], '--xsl-style-sheet')
 
     def test_cover_without_options(self):
         r = pdfkit.PDFKit('html', 'string', cover='test.html')
 
         command = r.command()
 
-        self.assertEqual(command[1], 'cover')
-        self.assertEqual(command[2], 'test.html')
+        self.assertEqual(command[1], '--quiet')
+        self.assertEqual(command[2], 'cover')
+        self.assertEqual(command[3], 'test.html')
 
     def test_cover_with_options(self):
         options = {
@@ -241,8 +244,9 @@ def test_cover_with_options(self):
 
         command = r.command()
 
-        self.assertEqual(command[1 + len(options) * 2], 'cover')
-        self.assertEqual(command[1 + len(options) * 2 + 1], 'test.html')
+        self.assertEqual(command[1 + len(options) * 2], '--quiet')
+        self.assertEqual(command[2 + len(options) * 2], 'cover')
+        self.assertEqual(command[2 + len(options) * 2 + 1], 'test.html')
 
     def test_cover_and_toc(self):
         options = {
@@ -289,10 +293,25 @@ def test_filter_empty_and_none_values_in_opts(self):
             'quiet': False
         }
 
-        r = pdfkit.PDFKit('html', 'string', options=options)
+        r = pdfkit.PDFKit('html', 'string', options=options, verbose=True)
         cmd = r.command()
         self.assertEqual(len(cmd), 6)
 
+    def test_verbose_option(self):
+        options = {
+            'outline': '',
+            'footer-line': None,
+            'quiet': True
+        }
+
+        r = pdfkit.PDFKit('html', 'string')
+        cmd = r.command()
+        self.assertTrue('--quiet' in cmd)
+
+        r = pdfkit.PDFKit('html', 'string', options=options)
+        cmd = r.command()
+        self.assertTrue('--quiet' in cmd)
+
 
 class TestPDFKitGeneration(unittest.TestCase):
     """Test to_pdf() method"""