Changeset 19 for pkipplib/trunk

Timestamp:

05/22/06 21:48:26 (18 years ago)

Author:

jerome

Message:

The README now include setup documentation and examples of use.

Files:

• pkipplib/trunk/README (modified) (1 diff)

pkipplib/trunk/README

@@ -18 +18 @@
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
+=======================================================================
+
+This software is a Python library which can prepare IPP requests with
+the help of a somewhat high level API. These requests can then be sent
+to an IPP printer or print server (e.g. CUPS).
+
+This library can also parse IPP answers received, and create high
+level Python objects from them.
+
+Both of these actions can be done through an IPPRequest class
+and its instance methods.
+
+Finally, a CUPS class can be leveraged to easily deal with CUPS 
+print servers.
+
+All of this library being written in the Python language, there's
+no need to link the code with the CUPS' API, which makes it
+independant of the CUPS version being installed.
+
+=======================================================================
+
+Installation :
+--------------
+
+        1 - Grab the latest version of this library from :
+        
+            http://www.pykota.com/software/pkipplib/
+            
+        2 - Extract the tarball :    
+        
+            $ tar -zxf pkipplib-x.yy.tar.gz
+            
+        3 - Install the Python module :    
+        
+            $ cd pkipplib-x.yy
+            $ python setup.py install
+
+NB : for the installation script to work, you need to install
+the python-dev package on your system first.
+
+=======================================================================
+
+Examples :
+----------
+
+--- CUT ---
+# Parsing.py    EXAMPLE
+from pkipplib import pkipplib
+
+# Read IPP datas from a CUPS job control file
+myfile = open("/var/spool/cups/c00155")
+ippdatas = myfile.read()
+myfile.close()
+
+# Parse these datas
+request = pkipplib.IPPRequest(ippdatas)
+request.parse()
+
+# Print the whole result as a string
+print request
+
+# Access one of the job's attributes directly 
+print request.job["job-name"]
+--- CUT ---
+
+
+--- CUT ---
+# Building.py   EXAMPLE
+from pkipplib import pkipplib
+
+# Create a CUPS_GET_DEFAULT request
+request = pkipplib.IPPRequest(operation_id=pkipplib.CUPS_GET_DEFAULT)
+request.operation["attributes-charset"] = ("charset", "utf-8")
+request.operation["attributes-natural-language"] = ("naturalLanguage", "en-us")
+
+# Get the request as binary datas
+ippdatas = request.dump()
+
+# Parse these datas back
+newrequest = pkipplib.IPPRequest(ippdatas)
+newrequest.parse()
+
+# Of course, the result of parsing matches what we created before.
+print newrequest.operation["attributes-natural-language"]
+--- CUT ---
+
+
+--- CUT ---
+# CUPS' API
+from pkipplib import pkipplib
+
+# By default, connects to http://localhost:631
+cups = pkipplib.CUPS()
+
+# High level API : retrieve info about job 3 :
+answer = cups.getJobAttributes(3)
+print answer.job["document-format"]
+# That's all folks !
+
+# Lower level API :
+request = cups.newRequest(pkipplib.IPP_GET_PRINTER_ATTRIBUTES)
+request.operation["printer-uri"] = ("uri", 
+                                    cups.identifierToURI("printers", "HP2100"))
+for attribute in ("printer-uri-supported",                                     
+                  "printer-type",
+                  "member-uris") :
+    # IMPORTANT : here, despite the unusual syntax, we append to              
+    # the list of requested attributes :
+    request.operation["requested-attributes"] = ("nameWithoutLanguage", attribute)
+    
+# Sends this request to the CUPS server    
+answer = request.doRequest()    
+
+# Print the answer as a string of text
+print answer
+--- CUT ---
+
+=======================================================================
+
+Please email bug reports, enhancements or comments to : alet@librelogiciel.com