root / pkipplib / trunk / README @ 35

Revision 35, 5.4 kB (checked in by jerome, 18 years ago)

Documents samplenotifier.

  • Property svn:keywords set to Author Date Id Revision
Line 
1pkipplib : IPP and CUPS support for Python
2
3$Id$
4
5(c) 2003, 2004, 2005, 2006 Jerome Alet <alet@librelogiciel.com>
6This program is free software; you can redistribute it and/or modify
7it under the terms of the GNU General Public License as published by
8the Free Software Foundation; either version 2 of the License, or
9(at your option) any later version.
10
11This program is distributed in the hope that it will be useful,
12but WITHOUT ANY WARRANTY; without even the implied warranty of
13MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14GNU General Public License for more details.
15
16You should have received a copy of the GNU General Public License
17along with this program; if not, write to the Free Software
18Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19
20=======================================================================
21
22This software is a Python library which can prepare IPP requests with
23the help of a somewhat high level API. These requests can then be sent
24to an IPP printer or print server (e.g. CUPS).
25
26This library can also parse IPP answers received, and create high
27level Python objects from them.
28
29Both of these actions can be done through an IPPRequest class
30and its instance methods.
31
32Finally, a CUPS class can be leveraged to easily deal with CUPS
33print servers.
34
35All of this library being written in the Python language, there's
36no need to link the code with the CUPS' API, which makes it
37independant of the CUPS version being installed.
38
39=======================================================================
40
41Installation :
42--------------
43
44        1 - Grab the latest version of this library from :
45       
46            http://www.pykota.com/software/pkipplib/
47           
48        2 - Extract the tarball :   
49       
50            $ tar -zxf pkipplib-x.yy.tar.gz
51           
52        3 - Install the Python module :   
53       
54            $ cd pkipplib-x.yy
55            $ python setup.py install
56
57NB : for the installation script to work, you need to install
58the python-dev package on your system first.
59
60=======================================================================
61
62Examples :
63----------
64
65--- CUT ---
66# Parsing.py    EXAMPLE
67from pkipplib import pkipplib
68
69# Read IPP datas from a CUPS job control file
70myfile = open("/var/spool/cups/c00155")
71ippdatas = myfile.read()
72myfile.close()
73
74# Parse these datas
75request = pkipplib.IPPRequest(ippdatas)
76request.parse()
77
78# Print the whole result as a string
79print request
80
81# Access one of the job's attributes directly
82print request.job["job-name"]
83--- CUT ---
84
85
86--- CUT ---
87# Building.py   EXAMPLE
88from pkipplib import pkipplib
89
90# Create a CUPS_GET_DEFAULT request
91request = pkipplib.IPPRequest(operation_id=pkipplib.CUPS_GET_DEFAULT)
92request.operation["attributes-charset"] = ("charset", "utf-8")
93request.operation["attributes-natural-language"] = ("naturalLanguage", "en-us")
94
95# Get the request as binary datas
96ippdatas = request.dump()
97
98# Parse these datas back
99newrequest = pkipplib.IPPRequest(ippdatas)
100newrequest.parse()
101
102# Of course, the result of parsing matches what we created before.
103print newrequest.operation["attributes-natural-language"]
104--- CUT ---
105
106
107--- CUT ---
108# CUPS' API
109from pkipplib import pkipplib
110
111# Create a CUPS client instance
112# cups = pkipplib.CUPS(url="http://server:631", username="john", password="blah!")
113cups = pkipplib.CUPS()
114
115# High level API : retrieve info about job 3 :
116answer = cups.getJobAttributes(3)
117print answer.job["document-format"]
118# That's all folks !
119
120# Lower level API :
121request = cups.newRequest(pkipplib.IPP_GET_PRINTER_ATTRIBUTES)
122request.operation["printer-uri"] = ("uri",
123                                    cups.identifierToURI("printers", "HP2100"))
124for attribute in ("printer-uri-supported",                                     
125                  "printer-type",
126                  "member-uris") :
127    # IMPORTANT : here, despite the unusual syntax, we append to             
128    # the list of requested attributes :
129    request.operation["requested-attributes"] = ("nameWithoutLanguage", attribute)
130   
131# Sends this request to the CUPS server   
132answer = cups.doRequest(request)
133
134# Print the answer as a string of text
135print answer
136--- CUT ---
137
138=======================================================================
139
140Command line tools :
141
142  pkipplib currently includes the following command line tools :
143 
144    * pksubscribe : can create or delete IPP subscriptions.
145   
146          See pksubscribe --help for details.
147       
148          examples :
149         
150            $ pksubscribe --cups http://localhost:631 \
151                          --events printer-added,printer-deleted \
152                          --recipient mynotifier \
153                          --duration 0
154                         
155            $ pksubscribe --username root \             
156                          --password HacKMe \
157                          --delete 34 58 98
158                         
159    * samplenotifier : can handle printer-added and printer-deleted
160      notifications and automatically create or remove printers
161      from PyKota's database (just adapt the code for other needs).
162     
163      samplenotifier is present in the notifiers/ directory, but
164      won't be installed automatically.
165
166  In the future more command line tools will be included.
167 
168=======================================================================
169
170Please email bug reports, enhancements or comments to : alet@librelogiciel.com
Note: See TracBrowser for help on using the browser.