root / pkipplib / trunk / README @ 3562

Revision 3562, 5.3 kB (checked in by jerome, 10 years ago)

Changed copyright years.

  • Property svn:keywords set to Author Date Id Revision
Line 
1pkipplib : IPP and CUPS support for Python
2
3$Id$
4
5# (c) 2003-2013 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    * send-jabber : a notifier that sends Jabber messages, contributed
163                    by Allison Jones.
164
165      samplenotifier and send-jabber are present in the notifiers/
166      directory, but won't be installed automatically. You must put them
167      into CUPS' notifier directory, e.g. /usr/lib/cups/notifier/
168
169  In the future more command line tools will be included.
170
171=======================================================================
172
173Please report any problem to the bug tracker at http://trac.pykota.com
Note: See TracBrowser for help on using the browser.