root / pkipplib / trunk / README @ 40

Revision 40, 5.4 kB (checked in by jerome, 17 years ago)

Now licensed under the terms of the GNU General Public License,
version 3 or later.

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