r1101@denkpolster: jan | 2008-04-05 23:22:04 +0200

work on documentation
  * documentation updates (addresses #13)
  * make stmtcreator execute as __main__ only


git-svn-id: file:///home/www/usr01/svn/gnuviechadmin/trunk@254 a67ec6bc-e5d5-0310-a910-815c51eb3124

gnuviechadmin/__init__.py

@@ -1,6 +1,7 @@
-# -*- coding: UTF-8 -*-
+# -*- python -*-
+# -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007 by Jan Dittberner.
+# Copyright (C) 2007, 2008 by Jan Dittberner.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -19,4 +20,8 @@
 #
 # Version: $Id$
 
-"""This is the gnuviechadmin package."""
+"""This is the Gnuviech Admin main package.
+
+Gnuviech Admin is a server administration toolkit. The project page is
+at http://www.gnuviech-server.de/projects/gnuviechadmin/.
+"""

gnuviechadmin/backend/settings.py

@@ -20,6 +20,12 @@
 #
 # Version: $Id$
 
+"""The Gnuviech Admin settings module.
+
+This module handles all central configuration of Gnuviech Admin. It
+parses configuration files and provides functions for reading
+templates."""
+
 import ConfigParser, os, string, logging.config
 
 # global settings which must not be user configurable

gnuviechadmin/cli/CliCommand.py

@@ -1,6 +1,7 @@
-# -*- coding: UTF-8 -*-
+# -*- python -*-
+# -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007 by Jan Dittberner.
+# Copyright (C) 2007, 2008 by Jan Dittberner.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -23,10 +24,10 @@ import getopt, sys, logging
 from gnuviechadmin.exceptions import GnuviechadminError
 
 class CliCommand:
-    """Base class for command line interface. A specific
+    """Base class for command line interface.
-    implementation class must define the fields name, description and
-    _optionmap.
 
+    A specific implementation class must define the fields name,
+    description and _optionmap.
 
     The field name is the name of the subcommand.
 

gnuviechadmin/cli/__init__.py

@@ -1,6 +1,7 @@
-# -*- coding: UTF-8 -*-
+# -*- python -*-
+# -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007 by Jan Dittberner.
+# Copyright (C) 2007, 2008 by Jan Dittberner.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

gnuviechadmin/cli/client.py

@@ -1,6 +1,7 @@
-# -*- coding: UTF-8 -*-
+# -*- python -*-
+# -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007 by Jan Dittberner.
+# Copyright (C) 2007, 2008 by Jan Dittberner.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

gnuviechadmin/cli/domain.py

@@ -1,6 +1,7 @@
-# -*- coding: UTF-8 -*-
+# -*- python -*-
+# -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007 by Jan Dittberner.
+# Copyright (C) 2007, 2008 by Jan Dittberner.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

gnuviechadmin/cli/record.py

@@ -1,6 +1,7 @@
-# -*- coding: UTF-8 -*-
+# -*- python -*-
+# -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007 by Jan Dittberner.
+# Copyright (C) 2007, 2008 by Jan Dittberner.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

gnuviechadmin/cli/sysuser.py

@@ -1,6 +1,7 @@
-# -*- coding: UTF-8 -*-
+# -*- python -*-
+# -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007 by Jan Dittberner.
+# Copyright (C) 2007, 2008 by Jan Dittberner.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

gnuviechadmin/exceptions.py

@@ -1,6 +1,7 @@
-# -*- coding: UTF-8 -*-
+# -*- python -*-
+# -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007 by Jan Dittberner.
+# Copyright (C) 2007, 2008 by Jan Dittberner.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

gnuviechadmin/util/__init__.py

@@ -1,6 +1,7 @@
-# -*- coding: UTF-8 -*-
+# -*- python -*-
+# -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007 by Jan Dittberner.
+# Copyright (C) 2007, 2008 by Jan Dittberner.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -21,4 +22,9 @@
 
 """This is the gnuviechadmin.util package.
 
-The package provides utility modules for various functions."""
+The package provides utility modules for various functions.
+
+ * getenttools to handle user and group information
+ * gpgmail for sending gpg signed and encrypted mails
+ * passwordutils for generating and checking passwords
+ * stmtcreator to create email account SQL statements"""

gnuviechadmin/util/getenttools.py

@@ -1,6 +1,7 @@
-# -*- coding: UTF-8 -*-
+# -*- python -*-
+# -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007 by Jan Dittberner.
+# Copyright (C) 2007, 2008 by Jan Dittberner.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -19,11 +20,14 @@
 #
 # Version: $Id$
 
+"""Tools for handling user and group information."""
+
 import pwd, grp
 
 class PasswdUser(object):
     """This class represents users in the user database."""
     def __init__(self, username, pw, uid, gid, gecos, home, shell):
+        """Create a new PasswdUser."""
         self.username = username
         self.uid = int(uid)
         self.gid = int(gid)
@@ -32,6 +36,7 @@ class PasswdUser(object):
         self.shell = shell
 
     def __repr__(self):
+        """Returns a user string representation."""
         return "%s(%s:%d:%d:%s:%s:%s)" % (self.__class__.__name__,
                                           self.username,
                                           self.uid,
@@ -43,20 +48,24 @@ class PasswdUser(object):
 class PasswdGroup(object):
     """This class represents lines in the groups database."""
     def __init__(self, groupname, pw, gid, members):
+        """Create a new PasswdGroup."""
         self.groupname = groupname
         self.gid = int(gid)
         self.members = members
 
     def __repr__(self):
+        """Returns a group string representation."""
         return "%s(%s:%d:%s)" % (self.__class__.__name__,
                                  self.groupname,
                                  self.gid,
                                  ",".join(self.members))
 
 def parse_groups():
+    """Parses all available groups to PasswdGroup instances."""
     return [PasswdGroup(*arr) for arr in grp.getgrall()]
 
 def parse_users():
+    """Parses all available users to PasswdUser instances."""
     return [PasswdUser(*arr) for arr in pwd.getpwall()]
 
 def find_user_by_prefix(prefix):
@@ -78,8 +87,16 @@ def get_group_by_id(gid):
     return None
 
 def get_next_uid(lowerboundary = 10000, upperboundary = 65536):
-    """Gets the first available user id in the range between lowerboundary and
+    """Gets the first available user id in the given range.
-    upper boundary."""
+
+    The returned uid is a value between lowerboundary and upper
+    boundary. An exception is raised if no uid can be found.
+
+    Keyword arguments:
+    lowerboundary -- lower boundary for uid range
+    upperboundary -- upper boundary for uid range
+
+    """
     for uid in range(lowerboundary, upperboundary):
       try:
         user = pwd.getpwuid(uid)

gnuviechadmin/util/gpgmail.py

@@ -20,6 +20,12 @@
 #
 # Version: $Id$
 
+"""GPG mail handling.
+
+This module provides functionallity for sending signed and encrypted
+email using GnuPG.
+"""
+
 import smtplib
 from email.MIMEText import MIMEText
 from pyme import core
@@ -28,9 +34,18 @@ from pyme.constants.sig import mode
 from gnuviechadmin.backend.settings import config
 
 def send_mail(subject, text):
-    """This method sends a mail with the given text and subject
+    """Send a signed and possibly encrypted mail.
-    and signs it usign GnuPG. If a public key of the recipient is
+
-    available the mail is encrypted."""
+    This method sends a mail with the given text and subject and signs
+    it using GnuPG. If a public key of the recipient is available the
+    mail is encrypted. The sender and recipient addresses are taken
+    from the configuration (section: common, properties: mailfrom,
+    mailto)
+
+    Arguments:
+    subject -- mail subject
+    text -- mail text
+    """
     if not text.__class__.__name__ == 'str':
         text = text.encode('ascii', 'replace')
     plain = core.Data(text)

gnuviechadmin/util/passwordutils.py

@@ -1,6 +1,7 @@
+# -*- python -*-
 # -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007 by Jan Dittberner.
+# Copyright (C) 2007, 2008 by Jan Dittberner.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -19,25 +20,39 @@
 #
 # Version: $Id$
 
+"""This module provides some functions for password handling."""
 import crypt, crack, random
 
 _pwchars = []
-for pair in (('0', '9'), ('A', 'Z'), ('a', 'z')):
+for _pair in (('0', '9'), ('A', 'Z'), ('a', 'z')):
-    _pwchars.extend(range(ord(pair[0]), ord(pair[1])))
+    _pwchars.extend(range(ord(_pair[0]), ord(_pair[1])))
-_saltchars = [char for char in _pwchars]
+_saltchars = [_char for _char in _pwchars]
-for char in "-+/*_@":
+for _char in "-+/*_@":
-    _pwchars.append(ord(char))
+    _pwchars.append(ord(_char))
 
 def generatepassword(minlength = 8, maxlength = 12):
-    """Generates a random password with a length between the given
+    """Generates a new random password with a given length.
-    minlength and maxlength values."""
+
+    The generated password has a length between minlength and maxlength.
+
+    Keyword arguments:
+    minlength -- minimum length of the generated password
+    maxlength -- the maximum length of the generated password
+
+    """
     return "".join([chr(letter) for letter in \
                     random.sample(_pwchars,
                                   random.randint(minlength, maxlength))])
 
 def checkpassword(password):
-    """Checks the password with cracklib. The password is returned if
+    """Checks the password with cracklib.
-    it is good enough. Otherwise None is returned."""
+
+    The password is returned if it is good enough. Otherwise None is
+    returned.
+
+    Arguments:
+    password -- the password to check
+    """
     try:
         return crack.VeryFascistCheck(password)
     except ValueError, ve:
@@ -45,15 +60,25 @@ def checkpassword(password):
     return None
     
 def md5_crypt_password(password):
-    """Hashes the given password with MD5 and a random salt value."""
+    """Hashes the given password with MD5 and a random salt value.
+
+    A password hashed with MD5 and a random salt value is returned.
+
+    Arguments:
+    password -- the password to hash
+    """
     salt = "".join([chr(letter) for letter in \
                     random.sample(_saltchars, 8)])
     return crypt.crypt(password, '$1$' + salt)
 
 def get_pw_tuple(password = None):
-    """Gets a valid tuple consisting of a password and a md5 hash of the
+    """Gets a valid (password, hashvalue) tuple.
-    password. If a password is given it is checked and if it is too weak
+
-    replaced by a generated one."""
+    The tuple consists of a password and a md5 hash of the same
+    password. If a password is given it is checked and if it is too
+    weak replaced by a generated one.
+
+    """
     while password == None or checkpassword(password) == None:
         password = generatepassword()
     return (password, md5_crypt_password(password))

gnuviechadmin/util/stmtcreator.py

@@ -1,3 +1,29 @@
+# -*- python -*-
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2007, 2008 by Jan Dittberner.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+# USA.
+#
+# Version: $Id$
+
+"""This is an SQL statement creator as a prototype for mail account
+creation."""
+
+if __name__ == '__main___':
   from passwordutils import *
   import sys
 
@@ -8,4 +34,3 @@ for line in sys.stdin.read().splitlines():
     pwtuple = get_pw_tuple()
     print "INSERT INTO mailpassword (id, clearpass, cryptpass, uid, gid, home, spamcheck) VALUES ('%s', '%s', '%s', %d, %d, '/home/mail/%s/%s', 'false');" % (parts[1], pwtuple[0], pwtuple[1], int(parts[2]), 119, username, parts[1])
     print "INSERT INTO mailaddress (domainid, email, target) VALUES (%d, '%s', '%s');" % (int(parts[3]), email, parts[1])
-