Module cups :: Class Connection
[show private | 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().
Method Summary
  __init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature
  __new__(T, S, ...)
T.__new__(S, ...) -> a new object with type S, a subtype of T
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.
dict adminGetServerSettings()
Get server settings.
None adminSetServerSettings(settings)
Set server settings.
None cancelJob(jobid)
None cancelSubscription(id)
Cancel a subscription.
integer createSubscription(uri)
Create a subscription.
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.
dict getClasses()
Return a dict, indexed by name, of objects representing classes.
string or None getDefault()
Get the system default printer.
dict getDests()
Return a dict representing available destinations.
dict getDevices()
Return 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)
Fetch a CUPS server resource to a local file.
dict getJobs(which_jobs, my_jobs)
Fetch a list of jobs.
list getNotifications(subscription_ids)
Get notifications for subscribed events.
string getPPD(name)
Fetch a printer's PPD.
dict getPPDs()
Return a dict, indexed by PPD name, of dicts representing PPDs, indexed by attribute.
dict getPrinterAttributes()
Fetch the attributes for a printer, specified either by name or by uri but not both.
dict getPrinters()
Return 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.
job ID printTestPage(name)
Print a test page.
None putFile(resource, filename)
This is for uploading new configuration files for the CUPS server.
  rejectJobs(name)
Cause printer to reject jobs.
None renewSubscription(id)
Renew a subscription.
None restartJob(jobid)
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.
    Inherited from object
  __delattr__(...)
x.__delattr__('name') <==> del x.name
  __getattribute__(...)
x.__getattribute__('name') <==> x.name
  __hash__(x)
x.__hash__() <==> hash(x)
  __reduce__(...)
helper for pickle
  __reduce_ex__(...)
helper for pickle
  __repr__(x)
x.__repr__() <==> repr(x)
  __setattr__(...)
x.__setattr__('name', value) <==> x.name = value
  __str__(x)
x.__str__() <==> str(x)

Method Details

__init__(...)
(Constructor)

x.__init__(...) initializes x; see x.__class__.__doc__ for signature
Overrides:
__builtin__.object.__init__

__new__(T, S, ...)

T.__new__(S, ...) -> a new object with type S, a subtype of T
Returns:
a new object with type S, a subtype of T
Overrides:
__builtin__.object.__new__

acceptJobs(name)

Cause printer to accept jobs.
Parameters:
name - queue name
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

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.
Keyword Parameters:
filename - local filename of PPD file
           (type=string)
ppdname - filename from getPPDs
           (type=string)
info - human-readable information about the printer
           (type=string)
location - human-readable printer location
           (type=string)
device - device URI string
           (type=string)
ppd - PPD object
           (type=cups.PPD instance)
Returns:
None
Raises:
IPPError - IPP problem

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 - queue name
           (type=string)
option - option name, for example 'job-priority'
           (type=string)
value - option value as a string
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

addPrinterToClass(name, class)

Add a printer to a class. If the class does not yet exist, it is created.
Parameters:
name - queue name
           (type=string)
class - class name
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

adminGetServerSettings()

Get server settings.
Returns:
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
           (type=dict)
Raises:
IPPError - IPP problem

See Also: adminSetServerSettings

adminSetServerSettings(settings)

Set server settings.
Parameters:
settings - dict of server settings
           (type=dict)
Returns:
None
Raises:
IPPError - IPP problem

See Also: adminGetServerSettings

cancelJob(jobid)

Parameters:
jobid - job ID to cancel
           (type=integer)
Returns:
None
Raises:
IPPError - IPP problem

cancelSubscription(id)

Cancel a subscription.
Parameters:
id - subscription ID
           (type=integer)
Returns:
None
Raises:
IPPError - IPP problem

createSubscription(uri)

Create a subscription.
Parameters:
uri - URI for object
           (type=string)
Keyword Parameters:
events - events to receive notifications for
           (type=string list)
job_id - job ID to receive notifications for
           (type=integer)
recipient_uri - URI for notifications recipient
           (type=string)
lease_duration - lease duration in seconds
           (type=integer)
time_interval - time interval
           (type=integer)
user_data - user data to receieve with notifications
           (type=string)
Returns:
subscription ID
           (type=integer)
Raises:
IPPError - IPP problem

deleteClass(class)

Delete a class.
Parameters:
class - class name
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

deletePrinter(name)

Delete a printer.
Parameters:
name - queue name
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

deletePrinterFromClass(name, class)

Remove a printer from a class. If the class would be left empty, it is removed.
Parameters:
name - queue name
           (type=string)
class - class name
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

deletePrinterOptionDefault(name, option)

Removes a network default option. See addPrinterOptionDefault.
Parameters:
name - queue name
           (type=string)
option - option name, for example 'job-priority'
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

disablePrinter(name)

Disable printer. This prevents the printer from processing its job queue.
Parameters:
name - queue name
           (type=string)
Keyword Parameters:
reason - optional human-readable reason for disabling the printer
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

enablePrinter(name)

Enable printer. This allows the printer to process its job queue.
Parameters:
name - queue name
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

getClasses()

Returns:
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.
           (type=dict)
Raises:
IPPError - IPP problem

getDefault()

Get the system default printer.
Returns:
default printer name or None
           (type=string or None)

getDests()

Returns:
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.
           (type=dict)
Raises:
IPPError - IPP problem

getDevices()

Returns:
a dict, indexed by device URI, of dicts representing devices, indexed by attribute.
           (type=dict)
Raises:
IPPError - IPP problem

getDocument(printer_uri, job_id, document_number)

Fetches the job document and stores it in a temporary file.
Parameters:
printer_uri - the printer-uri for the printer
           (type=string)
job_id - the job ID
           (type=integer)
document_number - the document number to retrieve
           (type=integer)
Returns:
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.
           (type=dict)
Raises:
RuntimeError - Not supported in libcups until 1.4
IPPError - IPP problem

getFile(resource, filename)

Fetch a CUPS server resource to a local file.

This is for obtaining CUPS server configuration files and log files.
Parameters:
resource - resource name
           (type=string)
filename - name of local file for storage
           (type=string)
Returns:
None
Raises:
HTTPError - HTTP problem

getJobs(which_jobs='not-completed', my_jobs=False)

Fetch a list of jobs.
Parameters:
which_jobs - which jobs to fetch; possible values: 'completed', 'not-completed', 'all'
           (type=string)
my_jobs - whether to restrict the returned jobs to those owned by the current CUPS user (as set by cups.setUser).
           (type=boolean)
Returns:
a dict, indexed by job ID, of dicts representing job attributes.
           (type=dict)
Raises:
IPPError - IPP problem

getNotifications(subscription_ids)

Get notifications for subscribed events.
Parameters:
subscription_ids - list of subscription IDs to receive notifications for
           (type=integer list)
Returns:
list of dicts, each representing an event
           (type=list)
Raises:
IPPError - IPP problem

getPPD(name)

Fetch a printer's PPD.
Parameters:
name - queue name
           (type=string)
Returns:
temporary PPD file name
           (type=string)
Raises:
IPPError - IPP problem

getPPDs()

Returns:
a dict, indexed by PPD name, of dicts representing PPDs, indexed by attribute.
           (type=dict)
Raises:
IPPError - IPP problem

getPrinterAttributes()

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

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.
           (type=dict)
Raises:
IPPError - IPP problem

getPrinters()

Returns:
a dict, indexed by name, of dicts representing queues, indexed by attribute.
           (type=dict)
Raises:
IPPError - IPP problem

getServerPPD(ppd_name)

Fetches the named PPD and stores it in a temporary file.
Parameters:
ppd_name - the ppd-name of a PPD
           (type=string)
Returns:
temporary filename holding the PPD
           (type=string)
Raises:
RuntimeError - Not supported in libcups until 1.3
IPPError - IPP problem

getSubscriptions(uri)

Get subscriptions.
Parameters:
uri - URI for object
           (type=string)
Keyword Parameters:
my_subscriptions - only return subscriptions belonging to the current user (default False)
           (type=boolean)
job_id - only return subscriptions relating to this job
           (type=integer)
Returns:
list of subscriptions
           (type=integer list)
Raises:
IPPError - IPP problem

printTestPage(name)

Print a test page.
Parameters:
name - queue name
           (type=string)
Keyword Parameters:
file - input file (default is CUPS test page)
           (type=string)
title - job title (default 'Test Page')
           (type=string)
format - document format (default 'application/postscript')
           (type=string)
user - user to submit the job as (default 'guest')
           (type=string)
Returns:
job ID
Raises:
IPPError - IPP problem

putFile(resource, filename)

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 - resource name
           (type=string)
filename - name of local file to upload
           (type=string)
Returns:
None
Raises:
HTTPError - HTTP problem

rejectJobs(name)

Cause printer to reject jobs.
Parameters:
name - queue name
           (type=string)
Keyword Parameters:
reason - optional human-readable reason for rejecting jobs
           (type=string)
Raises:
IPPError - IPP problem

renewSubscription(id)

Renew a subscription.
Parameters:
id - subscription ID
           (type=integer)
Returns:
None
Raises:
IPPError - IPP problem

restartJob(jobid)

Restart a job.
Parameters:
jobid - job ID to restart
           (type=integer)
Returns:
None
Raises:
IPPError - IPP problem

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 - queue name
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

setJobHoldUntil(jobid, job_hold_until)

Specifies when a job should be printed.
Parameters:
jobid - job ID to adjust
           (type=integer)
job_hold_until - when to print the job; examples: 'hold', 'immediate', 'restart', resume'
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

setPrinterDevice(name, device_uri)

Set the device URI for a printer.
Parameters:
name - queue name
           (type=string)
device_uri - device URI
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

setPrinterErrorPolicy(name, policy)

Set the printer's error policy.
Parameters:
name - queue name
           (type=string)
policy - policy name; supported policy names can be found by using the getPrinterAttributes function and looking for the 'printer-error-policy-supported' attribute
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

setPrinterInfo(name, info)

Set the human-readable information about a printer.
Parameters:
name - queue name
           (type=string)
info - human-readable information about the printer
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

setPrinterJobSheets(name, start, end)

Specifies job sheets for a printer.
Parameters:
name - queue name
           (type=string)
start - name of a sheet to print before each job
           (type=string)
end - name of a sheet to print after each job
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

setPrinterLocation(name, location)

Set the human-readable printer location
Parameters:
name - queue name
           (type=string)
location - human-readable printer location
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

setPrinterOpPolicy(name, policy)

Set the printer's operation policy.
Parameters:
name - queue name
           (type=string)
policy - policy name; supported policy names can be found by using the getPrinterAttributes function and looking for the 'printer-op-policy-supported' attribute
           (type=string)
Returns:
None
Raises:
IPPError - IPP problem

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 - queue name
           (type=string)
shared - whether printer should be shared
           (type=boolean)
Returns:
None
Raises:
IPPError - IPP problem

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 - queue name
           (type=string)
allowed - list of allowed users; ['all'] means there will be no user-name restriction.
           (type=string list)
Returns:
None
Raises:
IPPError - IPP problem

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 - queue name
           (type=string)
denied - list of denied users; ['none'] means there will be no user-name restriction.
           (type=string list)
Returns:
None
Raises:
IPPError - IPP problem

Generated by Epydoc 2.1 on Sat Feb 2 06:23:37 2008 http://epydoc.sf.net