ajout de la doc pydoc

darcs-hash:20061123200724-f46e9-fdd14a07b448b323145a69bae0d9c66a3eb54f71.gz

lib/impression/__init__.py

@@ -1,4 +1,5 @@
-""" 
+#!/usr/bin/env python
+# -*- coding: iso-8859-15 -*-
 # #############################################################
 #                                            ..                
 #                       ....  ............   ........          
@@ -24,6 +25,9 @@
 # Copyright (c) 2006 by www.crans.org                          
 # #############################################################
 """
+Classe pour gérer l'envoie de pdf à l'imprimante.
+Calcule le coût des options d'impression.
+"""
 __version__ = '1'
 
 import sys, syslog, os.path
@@ -119,21 +123,40 @@ LPR_OPTIONS = {
 #                       ERREURS                            #
 # ######################################################## #
 # 
-#
+
 class FichierInvalide(Exception):
+    """
+    Exception renvoyée lorsqu'un fichier ne passe pas.
+    utilisée avec deux arguments : une chaîne décrivant l'erreur et une chaine avec le nom du fichier
+    """
     def __str__(self):
+        """
+        Description de l'erreur.
+        """
         return self.args[0]
     def file(self):
+        """
+        Nom du fichier qui pose problème
+        """
         try:
             return self.args[1]
         except:
             return "n/a"
 
 class SoldeInsuffisant(Exception):
+    """
+    Solde insuffisant pour l'impression demandée
+    """
     pass
 class PrintError(Exception):
+    """
+    Erreur lors de l'impression
+    """
     pass
 class SettingsError(Exception):
+    """
+    Erreur de paramètres.
+    """
     pass
 # ######################################################## #
 #                    CLASSE IMPRESSION                     #
@@ -141,6 +164,10 @@ class SettingsError(Exception):
 # 
 #
 class impression:
+    """impression
+    
+    Un objet impression correspond à un fichier pdf et un adhérent.
+    """
     # fichier (chemin)
     _fichier = ""
     # adherent (instance)
@@ -164,6 +191,12 @@ class impression:
     
     
     def __init__(self, path_to_pdf, adh = None):
+        """impression(path_to_pdf [, adh])
+        
+        Crée un nouvel objet impression à partir du fichier pdf pointé par path_to_pdf.
+        Si adh ext donné, il peut être soit une instance d'un objet adhérent de crans_ldap soit le login de l'adhérent.
+        Lève l'exception FichierInvalide si le fichier n'existe pas ou si ce n'est pas un pdf.
+        """
         self._fichier = path_to_pdf
         # on verifie que le fichier existe
         if not os.path.isfile(path_to_pdf):
@@ -171,8 +204,6 @@ class impression:
         if not open(path_to_pdf).read().startswith("%PDF"):
             raise FichierInvalide, ("Le fichier ne semble pas etre un PDF", path_to_pdf)
         os.system("/usr/scripts/impression/compatibilise %s" % escapeForShell( path_to_pdf ) )
-        
-        
         self._adh = adh
         # calcule le prix de l'encre tout de suite
         try:
@@ -184,7 +215,12 @@ class impression:
 
     
     def changeSettings(self, agraphes = None, papier = None, couleurs = None, recto_verso=None, copies=None):
-        # recalcule et renvoie le prix
+        """changeSettings([keyword=value])
+        
+        Change les parametres de l'impression, recalcule et renvoie le nouveau prix.
+        Lève une exceotion SettingError si les paramètres son invalides.
+        """
+        #recalcule et renvoie le prix
         if (couleurs):
             if couleurs not in COULEURS_VALEURS_POSSIBLES:
                 raise SettingsError, "Valeur de couleurs inconnue : %s" % str(couleurs)
@@ -222,6 +258,10 @@ class impression:
         return self._calcule_prix()
 
     def printSettings(self):
+        """printSettings()
+        
+        Affiche les maramètres courrants sur la sortie standard
+        """
         print "Type impression: " + LABELS[self._settings['couleurs']]
         print "Agraphes: " + LABELS[self._settings['agraphes']]
         print "Papier: " + LABELS[self._settings['papier']]
@@ -230,23 +270,49 @@ class impression:
     
 
     def prix(self):
+        """prix()
+        
+        Renvoie le prix courrant de l'impression
+        """
         return self._prix
     
     def fileName(self):
+        """fileName()
+        
+        renvoie le nom du fichier pdf (exemple : monPdf.pdf)
+        """
         return os.path.basename(self._fichier)
     
     def filePath(self):
+        """filePath()
+        
+        renvoie le chemin d'accès au fichier pdf.
+        """
         return self._fichier
     
     
     def devisDetaille(self):
+        """devisDetaille()
+        
+        renvoie un disctionnaire contenant le devis (intitulé, PU., quantité) pour tous les éléments de l'impression
+        (papier, encre, agrafes...)
+        """
         return self._details_devis
     
     def pages(self):
+        """pages()
+        
+        renvoie le nombre de pages du document (page au sens nombre de faces à imprimer et non le nombre de feuilles)
+        """
         return self._nb_pages
 
         
     def imprime(self):
+        """imprime()
+        
+        imprime le document pdf. débite l'adhérent si adhérent il y a.
+        (si il a été indiqué à l'initialisation de l'objet)
+        """
         # debite l'adherent si adherent il y a
         if (self._adh != None):
             adh = self._get_adh(self._adh)
@@ -259,6 +325,10 @@ class impression:
         self._exec_imprime()
     
     def printDevis(self):
+        """printDevis()
+        
+        Affiche le devis sur la sortie standard.
+        """
         print "titre \t\t |  p.u. \t quandtite \t total"
         for anItem in self._details_devis:
             print anItem[0][:5] + "\t\t | " + str(anItem[1]) + "\t\t | " + str(anItem[2]) + "\t\t | " + str(anItem[1]*anItem[2])

lib/impression/cout.py

@@ -18,14 +18,16 @@
 #  ................................                            
 #                                                              
 # #############################################################
-# cout.py                                                                                                                    
+"""
-#                                                              
+ cout.py 
-#     Fonctions pour calculer le prix d'une impression         
+
-#       (ne calcul que le prix de l'encre.
+     Fonctions pour calculer le prix d'une impression
-#        retourne le prix pour une copie en A4)
+       (ne calcul que le prix de l'encre.
-#                                                              
+        retourne le prix pour une copie en A4)
-# Copyright (c) 2006 by www.crans.org                          
+
-# #############################################################
+ Copyright (c) 2006 by www.crans.org                          
+"""
+
 import sys, time, tempfile, os, commands, string, random, re
 sys.path.append('/usr/scripts/gestion')
 import config
@@ -50,6 +52,9 @@ COUT_PASSAGE_TAMBOUR_COULEUR = config.impression.c_tambour_coul
 # 
 #
 class FichierInvalide(Exception):
+    """
+    Si le fichier est invalide
+    """
     def __str__(self):
         return self.args[0]
     def file(self):
@@ -64,6 +69,9 @@ class FichierInvalide(Exception):
 # Clacul le prix d'une impression couleur
 #
 def base_prix_couleurs(path_fichier_pdf):
+    """
+    Clacul le prix d'une impression couleur   sur papier A4 pour le fichier path_fichier_pdf
+    """
     # nom_rep seras le dossier dans tmp ou tous les fichier créé par
     #     convert seront entreposé
     
@@ -109,6 +117,9 @@ def base_prix_couleurs(path_fichier_pdf):
 # calcul le prix d'une impression en noir et blanc
 #
 def base_prix_nb(path_fichier_pdf):
+    """
+    Clacul le prix d'une impression noire et blanc sur papier A4 pour le fichier path_fichier_pdf
+    """
     # nom_rep seras le dossier dans tmp ou tous les fichier créé par
     #     convert seront entreposé
 

lib/impression/digicode.py

@@ -16,12 +16,13 @@
 #  ................................                            
 #                                                              
 # #############################################################
-# digicode.py                                                                                                                    
+"""
-#                                                              
+ digicode.py                                                                                                                    
-#     Fonctions pour controler le digicode du 4@J
+                                                              
-#                                                              
+     Fonctions pour controler le digicode du 4@J
-# Copyright (c) 2006 by www.crans.org                          
+                                                              
-# #############################################################
+ Copyright (c) 2006 by www.crans.org                          
+"""
 import sys, time, tempfile, os, commands, string, random
 import crans.utils.files
 def __init__():
@@ -32,10 +33,6 @@ def __init__():
 CODES_SERVER = "zamok"
 CODES_DIR = "/var/impression/codes/"
 
-# test pour voir si on est bien sur la bonne machine
-import socket
-if socket.gethostname() != CODES_SERVER:
-    raise EnvironmentError, "La manipulation des codes pour le digicode n'est possible que sur %s" % CODES_SERVER
 
 # #############################################################
 # EXCEPTIONS
@@ -46,7 +43,10 @@ def CodeAlreadyExists(Exception):
 # #############################################################
 # FONCTIONS
 # #############################################################
-
+# test pour voir si on est bien sur la bonne machine
+import socket
+if socket.gethostname() != CODES_SERVER:
+    raise EnvironmentError, "La manipulation des codes pour le digicode n'est possible que sur %s" % CODES_SERVER
 
 # ###############################
 # save_code
@@ -54,6 +54,7 @@ def CodeAlreadyExists(Exception):
 # enregistre le codes avec "monString" dans le fichier 
 #
 def save_code(code, monString=""):
+    """enregistre le codes avec "monString" dans le fichier """
     code = str(code)
     if os.path.exists( os.path.join( CODES_DIR, code ) ):
         raise CodeAlreadyExists
@@ -72,7 +73,7 @@ def save_code(code, monString=""):
 # et l'enregistre 
 #
 def gen_code(user_name):
-    """ Genere le code et l'enregistre dans /var/impression/codes pour radius """
+    """ Genere un code au hasard l'enregistre avec user_name dans le fichier"""
     # Generation du code et ecriture du code
     rand=random.Random()
     # Graine automatique avec le temps
@@ -106,6 +107,10 @@ def gen_code(user_name):
 # liste les codes et leur age en secondes
 #
 def list_code():
+    """
+    Renvoie la liste des codes existants.
+    La liste est sous la forme [(code, age (en sec), contenu du fichier),...]
+    """
     files = os.listdir(CODES_DIR)
     code_list = []
     for aCode in files:
@@ -115,6 +120,10 @@ def list_code():
     return code_list
 
 def read_code_file(code):
+    """
+    Lis le fichier correspondant à code.
+    Renvoie le contenu du fichier.
+    """
     myfile = open(os.path.join(CODES_DIR, code ), 'r')
     lineStr = myfile.readline()
     myfile.close()
@@ -127,6 +136,9 @@ def read_code_file(code):
 # supprime les codes vieux de plus de 24h
 #
 def menage():
+    """
+    Supprime les codes vieux de plus de 24h
+    """
     fileList = os.listdir(CODES_DIR)
     for aFile in fileList:
         aFilePath = os.path.join(CODES_DIR, aFile)

lib/impression/etat_imprimante.py

@@ -1,12 +1,20 @@
 #!/usr/bin/env python
 # -*- coding: iso-8859-15 -*-
+"""
+ etat_imprimante.py
+ 
+     Récupère, filtre et formate l'état actuel de l'imprimante                                                              
+
+ Copyright (c) 2006 by www.crans.org                          
+
+"""
 
 import sys
 sys.path.append("/usr/scripts/gestion")
 
 import hptools
 
-dico = {
+_dico = {
   u"PrÁt": u"Prêt",
   u"Pr menus, appuy \x1e": u"",
   u"Powersave activÅ": u"En veille",
@@ -27,6 +35,7 @@ dico = {
 }
 
 class ErreurCommunication(Exception):
+    """Si une erreur est survenue lors de la communication avec l'imprimante"""
     pass
 
 def etat():
@@ -37,7 +46,7 @@ def etat():
         liste_msg = []
         for oid in liste_oid:
             msg = comm.get_string(oid).decode("ISO-8859-1")
-            msg = dico.get(msg, msg)
+            msg = _dico.get(msg, msg)
             if msg: liste_msg.append(msg)
     except Exception,err:
         raise ErreurCommunication, str(err)

lib/utils/files.py

@@ -1,13 +1,44 @@
+#!/usr/bin/env python
+# -*- coding: iso-8859-15 -*-
+# #############################################################
+#                                            ..
+#                       ....  ............   ........
+#                     .     .......   .            ....  ..
+#                   .  ... ..   ..   ..    ..   ..... .  ..
+#                   .. .. ....@@@.  ..  .       ........  .
+#              ..  .  .. ..@.@@..@@.  .@@@@@@@   @@@@@@. ....
+#         .@@@@. .@@@@. .@@@@..@@.@@..@@@..@@@..@@@@.... ....
+#       @@@@... .@@@.. @@ @@  .@..@@..@@...@@@.  .@@@@@.    ..
+#     .@@@..  . @@@.   @@.@@..@@.@@..@@@   @@ .@@@@@@..  .....
+#    ...@@@.... @@@    .@@.......... ........ .....        ..
+#   . ..@@@@.. .         .@@@@.   .. .......  . .............
+#  .   ..   ....           ..     .. . ... ....
+# .    .       ....   ............. .. ...
+# ..  ..  ...   ........ ...      ...
+#  ................................
+#
+# #############################################################
+"""
+files.py
+ 
+    Fonction de base sur les fichiers
+     
+Copyright (c) 2006 by www.crans.org
+"""
+
 import datetime, time, os
 
 def ageOfFile(pathToFile):
-	pathToFile = os.path.expanduser(pathToFile)
+    """renvoie l'age d'un fichier en secondes"""
-	return int(time.time()) - os.path.getmtime(pathToFile)
+    pathToFile = os.path.expanduser(pathToFile)
+    return int(time.time()) - os.path.getmtime(pathToFile)
 
 def fileIsOlderThan(pathToFile, days=0, hours=0, minutes=0, seconds=0):
-	time= (((days*24) + hours) * 60 + minutes) * 60 + seconds
+    """teste si un fichier est plus vieux on non que la valeur donnée"""
-	return ageOfFile(pathToFile) > time
+    time= (((days*24) + hours) * 60 + minutes) * 60 + seconds
+    return ageOfFile(pathToFile) > time
 
 def dirIsEmpty(pathToDir):
-	return os.listdir(pathToDir) == []
+    """teste : répond True si le dossier est vide."""
+    return os.listdir(pathToDir) == []