The cupsprinter module

A simple module using CUPS to send a document directly to a printer described by a QPrinter. This is especially useful with PDF documents.

Uses the cups module, although it elegantly fails when that module is not present. The cups module can be found in the pycups package at .

There are two methods to send a document to a printer:

  1. Using the lp shell command

  2. Using the cups module, which uses libcups to directly contact the server.

This module provides both possibilities.

Use CmdHandle.create() to get a CmdHandle, if lp is available, or use IppHandle.create() to get a IppHandle, if the cups module is available and a connection to the server can be established.

A function handle() is available; that tries first to get an IppHandle and then a LprHandle. Usage of this module is this simple:

import qpageview.cupsprinter

h = qpageview.cupsprinter.handle()
if h:

You can supply a QPrinter instance (that’d be the normal workflow :-)

h = qpageview.cupsprinter.handle(printer)
if h:

In this case all options that are set in the QPrinter object will be used when sending the document to the printer.

If printFile() returns True, printing is considered successful. If False, you can read the status and error attributes:

if not h.printFile('/path/to/document.pdf'):
    QMessageBox.warning(None, "Printing failure",
        "There was an error:\n{0} (status: {1})".format(h.error, h.status))

To print a list of files in one job, use printFiles().

class Handle(printer=None)[source]

Bases: object

Shared implementation of a handle that can send documents to a printer.


Use the specified QPrinter.


Return the QPrinter given on init, or a new default QPrinter instance.


Return the dict of CUPS options read from the printer object.


Return a sensible job title based on the list of filenames.

This method is called when the user did not specify a job title.

printFile(filename, title=None, options=None)[source]

Print the file.

printFiles(filenames, title=None, options=None)[source]

Print a list of files.

If the title is None, the basename of the filename is used. Options may be a dictionary of CUPS options. All keys and values should be strings.

Returns True if the operation was successful. Returns False if there was an error; after the call to printFile(), the status and error attributes contain the returncode of the operation and the error message.

class CmdHandle(command, server='', port=0, user='', printer=None)[source]

Bases: qpageview.cupsprinter.Handle

Print a document using the lp shell command.

classmethod create(printer=None, server='', port=0, user='', cmd='lp')[source]

Create a handle to print using a shell command, if available.

class IppHandle(connection, printer=None)[source]

Bases: qpageview.cupsprinter.Handle

Print a document using a connection to the CUPS server.

classmethod create(printer=None, server='', port=0, user='')[source]

Return a handle to print using a connection to the (local) CUPS server, if available.

handle(printer=None, server='', port=0, user='')[source]

Return the first available handle to print a document to a CUPS server.


Return the dict of CUPS options read from the QPrinter object.


Remove ‘page-set’ even/odd cups options from the printer’s CUPS options.

Qt’s QPrintDialog fails to reset the ‘page-set’ option back to ‘all pages’, so a previous value (even or odd) could remain in the print options, even if the user has selected All Pages in the print dialog.

This function clears the page-set setting from the cups options. If the user selects or has selected even or odd pages, it will be added again by the dialog.

So call this function on a QPrinter, just before showing a QPrintDialog.