Module cups :: Class Connection
[hide private]
[frames] | no frames]

type Connection

object --+
         |
        Connection

CUPS connection

A connection to the CUPS server. Before it is created the connection server and username should be set using cups.setServer and cups.setUser; otherwise the defaults will be used. When a Connection object is instantiated it results in a call to the libcups function httpConnectEncrypt().

The constructor takes optional arguments host, port, and encryption, which default to the values of cups.getServer(), cups.getPort(), and cups.getEncryption().

Instance Methods [hide private]
 
__init__(...)
x.__init__(...) initializes x; see help(type(x)) for signature
a new object with type S, a subtype of T
__new__(T, S, ...)
 
__repr__(x)
repr(x)
None
acceptJobs(name)
Cause printer to accept jobs.
None
addPrinter(name)
Add or adjust a print queue.
None
addPrinterOptionDefault(name, option, value)
Set a network default option.
None
addPrinterToClass(name, class)
Add a printer to a class.
None
adminExportSamba(name, samba_server, samba_username, samba_password)
Export a printer to Samba.
dict
adminGetServerSettings()
Get server settings.
None
adminSetServerSettings(settings)
Set server settings.
None
authenticateJob(jobid, auth_info=None)
None
cancelAllJobs(name=None, uri=None, my_jobs=False, purge_jobs=True)
None
cancelJob(jobid, purge_job=False)
None
cancelSubscription(id)
Cancel a subscription.
integer
createJob(printer, title, options)
Create an empty job for streaming.
 
createSubscription(...)
createSubscription(uri, events=[], job_id=-1, recipient_uri=, lease_duration=-1, time_interval=-1, user_data=) -> integer
None
deleteClass(class)
Delete a class.
None
deletePrinter(name)
Delete a printer.
None
deletePrinterFromClass(name, class)
Remove a printer from a class.
None
deletePrinterOptionDefault(name, option)
Removes a network default option.
None
disablePrinter(name)
Disable printer.
None
enablePrinter(name)
Enable printer.
integer
finishDocument(printer)
Finish sending a document.
dict
getClasses()
Returns: a dict, indexed by name, of objects representing classes.
string or None
getDefault()
Get the system default printer.
dict
getDests()
Returns: a dict representing available destinations.
dict
getDevices(limit=0, exclude_schemes=None, include_schemes=None)
Returns: a dict, indexed by device URI, of dicts representing devices, indexed by attribute.
dict
getDocument(printer_uri, job_id, document_number)
Fetches the job document and stores it in a temporary file.
None
getFile(resource, filename=None, fd=-1, file=None)
Fetch a CUPS server resource to a local file.
dict
getJobAttributes(jobid, requested_attributes=None)
Fetch job attributes.
dict
getJobs(which_jobs='not-completed', my_jobs=False, limit=-1, first_job_id=-1, requested_attributes=None)
Fetch a list of jobs.
list
getNotifications(subscription_ids)
Get notifications for subscribed events.
string
getPPD(name)
Fetch a printer's PPD.
(status,modtime,filename)
getPPD3(name, modtime=..., filename=...)
Fetch a printer's PPD if it is newer.
dict
getPPDs(limit=0, exclude_schemes=None, include_schemes=None, ppd_natural_language=None, ppd_device_id=None, ppd_make=None, ppd_make_and_model=None, ppd_model_number=-1, ppd_product=None, ppd_psversion=None, ppd_type=None)
Returns: a dict, indexed by PPD name, of dicts representing PPDs, indexed by attribute.
dict
getPPDs2(limit=0, exclude_schemes=None, include_schemes=None, ppd_natural_language=None, ppd_device_id=None, ppd_make=None, ppd_make_and_model=None, ppd_model_number=-1, ppd_product=None, ppd_psversion=None, ppd_type=None)
Returns: a dict, indexed by PPD name, of dicts representing PPDs, indexed by attribute.
dict
getPrinterAttributes(name=None, uri=None, requested_attributes=None)
Fetch the attributes for a printer, specified either by name or by uri but not both.
dict
getPrinters()
Returns: a dict, indexed by name, of dicts representing queues, indexed by attribute.
string
getServerPPD(ppd_name)
Fetches the named PPD and stores it in a temporary file.
integer list
getSubscriptions(uri)
Get subscriptions.
None
moveJob(printer_uri=None, job_id=-1, job_printer_uri)
Move a job specified by printer_uri and jobid (only one need be given) to the printer specified by job_printer_uri.
integer
printFile(printer, filename, title, options)
Print a file.
integer
printFiles(printer, filenames, title, options)
Print a list of files.
job ID
printTestPage(name)
Print a test page.
None
putFile(resource, filename=None, fd=-1, file=None)
This is for uploading new configuration files for the CUPS server.
 
rejectJobs(name)
Cause printer to reject jobs.
None
renewSubscription(id, lease_duration=-1)
Renew a subscription.
None
restartJob(job_id, job_hold_until=None)
Restart a job.
None
setDefault(name)
Set the system default printer.
None
setJobHoldUntil(jobid, job_hold_until)
Specifies when a job should be printed.
None
setPrinterDevice(name, device_uri)
Set the device URI for a printer.
None
setPrinterErrorPolicy(name, policy)
Set the printer's error policy.
None
setPrinterInfo(name, info)
Set the human-readable information about a printer.
None
setPrinterJobSheets(name, start, end)
Specifies job sheets for a printer.
None
setPrinterLocation(name, location)
Set the human-readable printer location
None
setPrinterOpPolicy(name, policy)
Set the printer's operation policy.
None
setPrinterShared(name, shared)
Set whether a printer is shared with other people.
None
setPrinterUsersAllowed(name, allowed)
Set the list of users allowed to use a printer.
None
setPrinterUsersDenied(name, denied)
Set the list of users denied the use of a printer.
integer
startDocument(printer, job_id, doc_name, format, last_document)
Add a document to a job created with createJob.
integer
writeRequestData(buffer, length)
Write data after an IPP request.
Method Details [hide private]

__init__(...)
(Constructor)

 

x.__init__(...) initializes x; see help(type(x)) for signature

Overrides: object.__init__

__new__(T, S, ...)

 
Returns: a new object with type S, a subtype of T
Overrides: object.__new__

__repr__(x)
(Representation operator)

 

repr(x)

Overrides: object.__repr__

acceptJobs(name)

 

Cause printer to accept jobs.

Parameters:
  • name (string) - queue name
Returns: None
Raises:

addPrinter(name)

 

Add or adjust a print queue. Several parameters can select which PPD to use (filename, ppdname, and ppd) but only one may be given.

Parameters:
  • filename (string) - local filename of PPD file
  • ppdname (string) - filename from getPPDs
  • info (string) - human-readable information about the printer
  • location (string) - human-readable printer location
  • device (string) - device URI string
  • ppd (cups.PPD instance) - PPD object
Returns: None
Raises:

addPrinterOptionDefault(name, option, value)

 

Set a network default option. Jobs submitted to the named queue will have the job option added if it is not already present in the job. This works with CUPS servers of at least version 1.2.

Parameters:
  • name (string) - queue name
  • option (string) - option name, for example 'job-priority'
  • value (string) - option value as a string
Returns: None
Raises:

addPrinterToClass(name, class)

 

Add a printer to a class. If the class does not yet exist, it is created.

Parameters:
  • name (string) - queue name
  • class (string) - class name
Returns: None
Raises:

adminExportSamba(name, samba_server, samba_username, samba_password)

 

Export a printer to Samba.

Parameters:
  • name (string) - queue name
  • samba_server (string) - samba server
  • samba_username (string) - samba username
  • samba_password (string) - samba password
Returns: None
Raises:

adminGetServerSettings()

 

Get server settings.

Returns: dict
dict representing server settings; keywords include CUPS_SERVER_DEBUG_LOGGING, CUPS_SERVER_REMOTE_ADMIN, CUPS_SERVER_REMOTE_PRINTERS, CUPS_SERVER_SHARE_PRINTERS, CUPS_SERVER_USER_CANCEL_ANY
Raises:

adminSetServerSettings(settings)

 

Set server settings.

Parameters:
  • settings (dict) - dict of server settings
Returns: None
Raises:

authenticateJob(jobid, auth_info=None)

 
Parameters:
  • jobid (integer) - job ID to authenticate
  • auth_info (optional string list) - authentication details
Returns: None
Raises:

cancelAllJobs(name=None, uri=None, my_jobs=False, purge_jobs=True)

 
Parameters:
  • name (string) - queue name
  • uri (string) - printer URI
  • my_jobs (boolean) - whether to restrict operation to jobs owned by the current CUPS user (as set by cups.setUser).
  • purge_jobs (boolean) - whether to remove data and control files
Returns: None
Raises:

cancelJob(jobid, purge_job=False)

 
Parameters:
  • jobid (integer) - job ID to cancel
  • purge_job (boolean) - whether to remove data and control files
Returns: None
Raises:

cancelSubscription(id)

 

Cancel a subscription.

Parameters:
  • id (integer) - subscription ID
Returns: None
Raises:

createJob(printer, title, options)

 

Create an empty job for streaming.

Parameters:
  • printer (string) - queue name
  • title (string) - title of the print job
  • options (dict) - dict of options
Returns: integer
job ID
Raises:

createSubscription(...)

 
createSubscription(uri, events=[], job_id=-1, recipient_uri=,
                   lease_duration=-1, time_interval=-1,
                   user_data=) -> integer

Create a subscription.

@type uri: string
@param uri: URI for object
@type events: string list
@keyword events: events to receive notifications for
@type job_id: integer
@keyword job_id: job ID to receive notifications for
@type recipient_uri: string
@keyword recipient_uri: URI for notifications recipient
@type lease_duration: integer
@keyword lease_duration: lease duration in seconds
@type time_interval: integer
@keyword time_interval: time interval
@type user_data: string
@keyword user_data: user data to receieve with notifications
@return: subscription ID
@raise IPPError: IPP problem

deleteClass(class)

 

Delete a class.

Parameters:
  • class (string) - class name
Returns: None
Raises:

deletePrinter(name)

 

Delete a printer.

Parameters:
  • name (string) - queue name
Returns: None
Raises:

deletePrinterFromClass(name, class)

 

Remove a printer from a class. If the class would be left empty, it is removed.

Parameters:
  • name (string) - queue name
  • class (string) - class name
Returns: None
Raises:

deletePrinterOptionDefault(name, option)

 

Removes a network default option. See addPrinterOptionDefault.

Parameters:
  • name (string) - queue name
  • option (string) - option name, for example 'job-priority'
Returns: None
Raises:

disablePrinter(name)

 

Disable printer. This prevents the printer from processing its job queue.

Parameters:
  • name (string) - queue name
  • reason (string) - optional human-readable reason for disabling the printer
Returns: None
Raises:

enablePrinter(name)

 

Enable printer. This allows the printer to process its job queue.

Parameters:
  • name (string) - queue name
Returns: None
Raises:

finishDocument(printer)

 

Finish sending a document.

Parameters:
  • printer (string) - queue name
Returns: integer
HTTP status
Raises:

getClasses()

 
Returns: dict
a dict, indexed by name, of objects representing classes. Each class object is either a string, in which case it is for the remote class; or a list, in which case it is a list of queue names.
Raises:

getDefault()

 

Get the system default printer.

Returns: string or None
default printer name or None

getDests()

 
Returns: dict
a dict representing available destinations. Each dictionary key is a pair of (queue, instance) strings, and the dictionary value is a cups.Dest object. In addition to the available destinations, a special dictionary key (None,None) is provided for looking up the default destination; this destination will also be available under its own key.
Raises:

getDevices(limit=0, exclude_schemes=None, include_schemes=None)

 
Parameters:
  • limit (integer) - maximum number of devices to return
  • exclude_schemes (string list) - URI schemes to exclude
  • include_schemes (string list) - URI schemes to include
Returns: dict
a dict, indexed by device URI, of dicts representing devices, indexed by attribute.
Raises:

getDocument(printer_uri, job_id, document_number)

 

Fetches the job document and stores it in a temporary file.

Parameters:
  • printer_uri (string) - the printer-uri for the printer
  • job_id (integer) - the job ID
  • document_number (integer) - the document number to retrieve
Returns: dict
a dict with the following keys: 'file' (string), temporary filename holding the job document; 'document-format' (string), its MIME type. There may also be a 'document-name' key, in which case this is for the document name.
Raises:
  • RuntimeError - Not supported in libcups until 1.4
  • IPPError - IPP problem

getFile(resource, filename=None, fd=-1, file=None)

 

Fetch a CUPS server resource to a local file.

This is for obtaining CUPS server configuration files and log files.

Parameters:
  • resource (string) - resource name
  • filename (string) - name of local file for storage
  • fd (int) - file descriptor of local file
  • file (file) - Python file object for local file
Returns: None
Raises:

getJobAttributes(jobid, requested_attributes=None)

 

Fetch job attributes.

Parameters:
  • jobid (integer) - job ID
  • requested_attributes (string list) - list of requested attribute names
Returns: dict
a dict representing job attributes.
Raises:

getJobs(which_jobs='not-completed', my_jobs=False, limit=-1, first_job_id=-1, requested_attributes=None)

 

Fetch a list of jobs.

Parameters:
  • which_jobs (string) - which jobs to fetch; possible values: 'completed', 'not-completed', 'all'
  • my_jobs (boolean) - whether to restrict the returned jobs to those owned by the current CUPS user (as set by cups.setUser).
  • limit (integer) - maximum number of jobs to return
  • first_job_id (integer) - lowest job ID to return
  • requested_attributes (string list) - list of requested attribute names
Returns: dict
a dict, indexed by job ID, of dicts representing job attributes.
Raises:

getNotifications(subscription_ids)

 

Get notifications for subscribed events.

Parameters:
  • subscription_ids (integer list) - list of subscription IDs to receive notifications for
Returns: list
list of dicts, each representing an event
Raises:

getPPD(name)

 

Fetch a printer's PPD.

Parameters:
  • name (string) - queue name
Returns: string
temporary PPD file name
Raises:

getPPD3(name, modtime=..., filename=...)

 

Fetch a printer's PPD if it is newer.

Parameters:
  • name (string) - queue name
  • modtime (float) - modification time of existing file
  • filename (string) - filename of existing file
Returns: (status,modtime,filename)
tuple of HTTP status, modification time, and filename

getPPDs(limit=0, exclude_schemes=None, include_schemes=None, ppd_natural_language=None, ppd_device_id=None, ppd_make=None, ppd_make_and_model=None, ppd_model_number=-1, ppd_product=None, ppd_psversion=None, ppd_type=None)

 
Parameters:
  • limit (integer) - maximum number of PPDs to return
  • exclude_schemes (string list) - list of PPD schemes to exclude
  • include_schemes (string list) - list of PPD schemes to include
  • ppd_natural_language (string) - required language
  • ppd_device_id (string) - IEEE 1284 Device ID to match against
  • ppd_make (string) - required printer manufacturer
  • ppd_make_and_model (string) - required make and model
  • ppd_model_number (integer) - model number required (from cupsModelNumber in PPD file)
  • ppd_product (string) - required PostScript product string (Product)
  • ppd_psversion (string) - required PostScript version (PSVersion)
  • ppd_type (string) - required type of PPD. Valid values are fax; pdf; postscript; raster; unknown.
Returns: dict
a dict, indexed by PPD name, of dicts representing PPDs, indexed by attribute.
Raises:

getPPDs2(limit=0, exclude_schemes=None, include_schemes=None, ppd_natural_language=None, ppd_device_id=None, ppd_make=None, ppd_make_and_model=None, ppd_model_number=-1, ppd_product=None, ppd_psversion=None, ppd_type=None)

 
Parameters:
  • limit (integer) - maximum number of PPDs to return
  • exclude_schemes (string list) - list of PPD schemes to exclude
  • include_schemes (string list) - list of PPD schemes to include
  • ppd_natural_language (string) - required language
  • ppd_device_id (string) - IEEE 1284 Device ID to match against
  • ppd_make (string) - required printer manufacturer
  • ppd_make_and_model (string) - required make and model
  • ppd_model_number (integer) - model number required (from cupsModelNumber in PPD file)
  • ppd_product (string) - required PostScript product string (Product)
  • ppd_psversion (string) - required PostScript version (PSVersion)
  • ppd_type (string) - required type of PPD. Valid values are fax; pdf; postscript; raster; unknown.
Returns: dict
a dict, indexed by PPD name, of dicts representing PPDs, indexed by attribute. All attribute values are lists.
Raises:

getPrinterAttributes(name=None, uri=None, requested_attributes=None)

 

Fetch the attributes for a printer, specified either by name or by uri but not both.

Parameters:
  • name (string) - queue name
  • uri (string) - queue URI
  • requested_attributes (string list) - list of requested attribute names
Returns: dict
a dict, indexed by attribute, of printer attributes for the specified printer.

Attributes:

  • 'job-sheets-supported': list of strings
  • 'job-sheets-default': tuple of strings (start, end)
  • 'printer-error-policy-supported': if present, list of strings
  • 'printer-error-policy': if present, string
  • 'printer-op-policy-supported': if present, list of strings
  • 'printer-op-policy': if present, string

There are other attributes; the exact list of attributes returned will depend on the IPP server.

Raises:

getPrinters()

 
Returns: dict
a dict, indexed by name, of dicts representing queues, indexed by attribute.
Raises:

getServerPPD(ppd_name)

 

Fetches the named PPD and stores it in a temporary file.

Parameters:
  • ppd_name (string) - the ppd-name of a PPD
Returns: string
temporary filename holding the PPD
Raises:
  • RuntimeError - Not supported in libcups until 1.3
  • IPPError - IPP problem

getSubscriptions(uri)

 

Get subscriptions.

Parameters:
  • uri (string) - URI for object
  • my_subscriptions (boolean) - only return subscriptions belonging to the current user (default False)
  • job_id (integer) - only return subscriptions relating to this job
Returns: integer list
list of subscriptions
Raises:

moveJob(printer_uri=None, job_id=-1, job_printer_uri)

 

Move a job specified by printer_uri and jobid (only one need be given) to the printer specified by job_printer_uri.

Parameters:
  • job_id (integer) - job ID to move
  • printer_uri (string) - printer to move job(s) from
  • job_printer_uri (string) - printer to move job(s) to
Returns: None
Raises:

printFile(printer, filename, title, options)

 

Print a file.

Parameters:
  • printer (string) - queue name
  • filename (string) - local file path to the document
  • title (string) - title of the print job
  • options (dict) - dict of options
Returns: integer
job ID
Raises:

printFiles(printer, filenames, title, options)

 

Print a list of files.

Parameters:
  • printer (string) - queue name
  • filenames (list) - list of local file paths to the documents
  • title (string) - title of the print job
  • options (dict) - dict of options
Returns: integer
job ID
Raises:

printTestPage(name)

 

Print a test page.

Parameters:
  • name (string) - queue name
  • file (string) - input file (default is CUPS test page)
  • title (string) - job title (default 'Test Page')
  • format (string) - document format (default 'application/postscript')
  • user (string) - user to submit the job as
Returns: job ID
Raises:

putFile(resource, filename=None, fd=-1, file=None)

 

This is for uploading new configuration files for the CUPS server. Note: adminSetServerSettings is a way of adjusting server settings without needing to parse the configuration file.

Parameters:
  • resource (string) - resource name
  • filename (string) - name of local file to upload
  • fd (int) - file descriptor of local file
  • file (file) - Python file object for local file
Returns: None
Raises:

rejectJobs(name)

 

Cause printer to reject jobs.

Parameters:
  • name (string) - queue name
  • reason (string) - optional human-readable reason for rejecting jobs
Raises:

renewSubscription(id, lease_duration=-1)

 

Renew a subscription.

Parameters:
  • id (integer) - subscription ID
  • lease_duration (integer) - lease duration in seconds
Returns: None
Raises:

restartJob(job_id, job_hold_until=None)

 

Restart a job.

Parameters:
  • job_id (integer) - job ID to restart
  • job_hold_until (string) - new job-hold-until value for job
Returns: None
Raises:

setDefault(name)

 

Set the system default printer. Note that this can be over-ridden on a per-user basis using the lpoptions command.

Parameters:
  • name (string) - queue name
Returns: None
Raises:

setJobHoldUntil(jobid, job_hold_until)

 

Specifies when a job should be printed.

Parameters:
  • jobid (integer) - job ID to adjust
  • job_hold_until (string) - when to print the job; examples: 'hold', 'immediate', 'restart', resume'
Returns: None
Raises:

setPrinterDevice(name, device_uri)

 

Set the device URI for a printer.

Parameters:
  • name (string) - queue name
  • device_uri (string) - device URI
Returns: None
Raises:

setPrinterErrorPolicy(name, policy)

 

Set the printer's error policy.

Parameters:
  • name (string) - queue name
  • policy (string) - policy name; supported policy names can be found by using the getPrinterAttributes function and looking for the 'printer-error-policy-supported' attribute
Returns: None
Raises:

setPrinterInfo(name, info)

 

Set the human-readable information about a printer.

Parameters:
  • name (string) - queue name
  • info (string) - human-readable information about the printer
Returns: None
Raises:

setPrinterJobSheets(name, start, end)

 

Specifies job sheets for a printer.

Parameters:
  • name (string) - queue name
  • start (string) - name of a sheet to print before each job
  • end (string) - name of a sheet to print after each job
Returns: None
Raises:

setPrinterLocation(name, location)

 

Set the human-readable printer location

Parameters:
  • name (string) - queue name
  • location (string) - human-readable printer location
Returns: None
Raises:

setPrinterOpPolicy(name, policy)

 

Set the printer's operation policy.

Parameters:
  • name (string) - queue name
  • policy (string) - policy name; supported policy names can be found by using the getPrinterAttributes function and looking for the 'printer-op-policy-supported' attribute
Returns: None
Raises:

setPrinterShared(name, shared)

 

Set whether a printer is shared with other people. This works with CUPS servers of at least version 1.2, by setting the printer-is-shared printer attribute.

Parameters:
  • name (string) - queue name
  • shared (boolean) - whether printer should be shared
Returns: None
Raises:

setPrinterUsersAllowed(name, allowed)

 

Set the list of users allowed to use a printer. This works with CUPS server of at least version 1.2, by setting the requesting-user-name-allowed printer attribute.

Parameters:
  • name (string) - queue name
  • allowed (string list) - list of allowed users; ['all'] means there will be no user-name restriction.
Returns: None
Raises:

setPrinterUsersDenied(name, denied)

 

Set the list of users denied the use of a printer. This works with CUPS servers of at least version 1.2, by setting the requesting-user-name-denied printer attribute.

Parameters:
  • name (string) - queue name
  • denied (string list) - list of denied users; ['none'] means there will be no user-name restriction.
Returns: None
Raises:

startDocument(printer, job_id, doc_name, format, last_document)

 

Add a document to a job created with createJob.

Parameters:
  • printer (string) - queue name
  • job_id (integer) - job ID to create document
  • doc_name (string) - name of the document
  • format (string) - MIME type
  • last_document (integer) - 1 for last document of job, 0 otherwise
Returns: integer
HTTP status
Raises:

writeRequestData(buffer, length)

 

Write data after an IPP request.

Parameters:
  • buffer (string) - bytes to write
  • length (integer) - number of bytes to write
Returns: integer
HTTP status
Raises: