r26629: python: Improve documentation in various places.

(This used to be commit ee71a27bca66426d34cb1d686a83ac6a342329d3)

3 files changed, 50 insertions, 17 deletions

diff --git a/source4/scripting/python/samba/getopt.py b/source4/scripting/python/samba/getopt.py
index c0e7053062..a087974a69 100644
--- a/source4/scripting/python/samba/getopt.py
+++ b/source4/scripting/python/samba/getopt.py
@@ -36,28 +36,28 @@ class CredentialsOptions(optparse.OptionGroup):
     def __init__(self, parser):
         optparse.OptionGroup.__init__(self, parser, "Credentials Options")
         self.add_option("--simple-bind-dn", metavar="DN", action="callback",
-                        callback=self.set_simple_bind_dn, type=str,
+                        callback=self._set_simple_bind_dn, type=str,
                         help="DN to use for a simple bind")
         self.add_option("--password", metavar="PASSWORD", action="callback",
-                        help="Password", type=str, callback=self.set_password)
+                        help="Password", type=str, callback=self._set_password)
         self.add_option("-U", "--username", metavar="USERNAME", 
                         action="callback", type=str,
-                        help="Username", callback=self.parse_username)
+                        help="Username", callback=self._parse_username)
         self.add_option("-W", "--workgroup", metavar="WORKGROUP", 
                         action="callback", type=str,
-                        help="Workgroup", callback=self.parse_workgroup)
+                        help="Workgroup", callback=self._parse_workgroup)
         self.creds = Credentials()
 
-    def parse_username(self, option, opt_str, arg, parser):
+    def _parse_username(self, option, opt_str, arg, parser):
         self.creds.parse_string(arg)
 
-    def parse_workgroup(self, option, opt_str, arg, parser):
+    def _parse_workgroup(self, option, opt_str, arg, parser):
         self.creds.set_domain(arg)
 
-    def set_password(self, option, opt_str, arg, parser):
+    def _set_password(self, option, opt_str, arg, parser):
         self.creds.set_password(arg)
 
-    def set_simple_bind_dn(self, option, opt_str, arg, parser):
+    def _set_simple_bind_dn(self, option, opt_str, arg, parser):
         self.creds.set_bind_dn(arg)
 
     def get_credentials(self):
diff --git a/source4/scripting/python/samba/provision.py b/source4/scripting/python/samba/provision.py
index bdfe035c41..db3749f721 100644
--- a/source4/scripting/python/samba/provision.py
+++ b/source4/scripting/python/samba/provision.py
@@ -23,6 +23,7 @@ import security
 from ldb import Dn, SCOPE_SUBTREE, SCOPE_ONELEVEL, SCOPE_BASE, LdbError, \
         LDB_ERR_NO_SUCH_OBJECT, timestring, CHANGETYPE_MODIFY, CHANGETYPE_NONE
 
+"""Functions for setting up a Samba configuration."""
 
 DEFAULTSITE = "Default-First-Site-Name"
 
@@ -53,7 +54,12 @@ class ProvisionPaths:
 
 
 def install_ok(lp, session_info, credentials):
-    """Check whether the current install seems ok."""
+    """Check whether the current install seems ok.
+    
+    :param lp: Loadparm context
+    :param session_info: Session information
+    :param credentials: Credentials
+    """
     if lp.get("realm") == "":
         return False
     ldb = Ldb(lp.get("sam database"), session_info=session_info, 
diff --git a/source4/scripting/python/samba/samba3.py b/source4/scripting/python/samba/samba3.py
index 113348e6f1..cffedb54af 100644
--- a/source4/scripting/python/samba/samba3.py
+++ b/source4/scripting/python/samba/samba3.py
@@ -26,7 +26,7 @@ import os
 import tdb
 
 
-class TdbDatabase:
+class TdbDatabase(object):
     """Simple Samba 3 TDB database reader."""
     def __init__(self, file):
         """Open a file.
@@ -228,6 +228,7 @@ class IdmapDatabase(TdbDatabase):
 
 
 class SecretsDatabase(TdbDatabase):
+    """Samba 3 Secrets database reader."""
     def get_auth_password(self):
         return self.tdb.get("SECRETS/AUTH_PASSWORD")
 
@@ -246,6 +247,10 @@ class SecretsDatabase(TdbDatabase):
                 yield k[len("SECRETS/LDAP_BIND_PW/"):].rstrip("\0")
 
     def domains(self):
+        """Iterate over domains in this database.
+
+        :return: Iterator over the names of domains in this database.
+        """
         for k in self.tdb.keys():
             if k.startswith("SECRETS/SID/"):
                 yield k[len("SECRETS/SID/"):].rstrip("\0")
@@ -287,10 +292,15 @@ SHARE_DATABASE_VERSION_V1 = 1
 SHARE_DATABASE_VERSION_V2 = 2
 
 class ShareInfoDatabase(TdbDatabase):
+    """Samba 3 Share Info database reader."""
     def _check_version(self):
         assert self.tdb.fetch_int32("INFO/version\0") in (SHARE_DATABASE_VERSION_V1, SHARE_DATABASE_VERSION_V2)
 
     def get_secdesc(self, name):
+        """Obtain the security descriptor on a particular share.
+        
+        :param name: Name of the share
+        """
         secdesc = self.tdb.get("SECDESC/%s" % name)
         # FIXME: Run ndr_pull_security_descriptor
         return secdesc
@@ -302,9 +312,11 @@ class Shares:
         self.shareinfo = shareinfo
 
     def __len__(self):
+        """Number of shares."""
         return len(self.lp) - 1
 
     def __iter__(self):
+        """Iterate over the share names."""
         return self.lp.__iter__()
 
 
@@ -329,7 +341,7 @@ ACB_PW_EXPIRED = 0x00020000
 ACB_NO_AUTH_DATA_REQD = 0x00080000
 
 acb_info_mapping = {
-        'N': ACB_PWNOTREQ,  # 'N'o password. 
+        'N': ACB_PWNOTREQ,  # 'N'o password.
         'D': ACB_DISABLED,  # 'D'isabled.
         'H': ACB_HOMDIRREQ, # 'H'omedir required.
         'T': ACB_TEMPDUP,   # 'T'emp account.
@@ -344,6 +356,11 @@ acb_info_mapping = {
         }
 
 def decode_acb(text):
+    """Decode a ACB field.
+
+    :param text: ACB text
+    :return: integer with flags set.
+    """
     assert not "[" in text and not "]" in text
     ret = 0
     for x in text:
@@ -352,6 +369,10 @@ def decode_acb(text):
 
 
 class SAMUser:
+    """Samba 3 SAM User.
+    
+    :note: Unknown or unset fields are set to None.
+    """
     def __init__(self, name, uid=None, lm_password=None, nt_password=None, acct_ctrl=None, 
                  last_change_time=None, nt_username=None, fullname=None, logon_time=None, logoff_time=None,
                  acct_desc=None, group_rid=None, bad_password_count=None, logon_count=None,
@@ -398,6 +419,7 @@ class SAMUser:
         return self.__dict__ == other.__dict__
 
 class SmbpasswdFile:
+    """Samba 3 smbpasswd file reader."""
     def __init__(self, file):
         self.users = {}
         f = open(file, 'r')
@@ -458,13 +480,14 @@ TDBSAM_USER_PREFIX = "USER_"
 
 
 class LdapSam:
+    """Samba 3 LDAP passdb backend reader."""
     def __init__(self, url):
         self.ldap_url = ldap_url
 
 
-class TdbSam:
-    def __init__(self, file):
-        self.tdb = tdb.Tdb(file, flags=os.O_RDONLY)
+class TdbSam(TdbDatabase):
+    """Samba 3 TDB passdb backend reader."""
+    def _check_version(self):
         self.version = self.tdb.fetch_uint32("INFO/version\0") or 0
         assert self.version in (0, 1, 2)
 
@@ -555,9 +578,6 @@ class TdbSam:
         assert len(data) == 0
         return user
 
-    def close(self):
-        self.tdb.close()
-
 
 def shellsplit(text):
     """Very simple shell-like line splitting.
@@ -582,6 +602,7 @@ def shellsplit(text):
 
 
 class WinsDatabase:
+    """Samba 3 WINS database reader."""
     def __init__(self, file):
         self.entries = {}
         f = open(file, 'r')
@@ -618,7 +639,13 @@ class WinsDatabase:
         pass
 
 class Samba3:
+    """Samba 3 configuration and state data reader."""
     def __init__(self, libdir, smbconfpath):
+        """Open the configuration and data for a Samba 3 installation.
+
+        :param libdir: Library directory
+        :param smbconfpath: Path to the smb.conf file.
+        """
         self.smbconfpath = smbconfpath
         self.libdir = libdir
         import param