s4-python: Some reformatting for the purpose of pydoctor.

11 files changed, 105 insertions, 64 deletions

diff --git a/source4/scripting/python/samba/__init__.py b/source4/scripting/python/samba/__init__.py
index a9b43498bf..ee45d931cd 100644
--- a/source4/scripting/python/samba/__init__.py
+++ b/source4/scripting/python/samba/__init__.py
@@ -128,7 +128,7 @@ class Ldb(_Ldb):
 
     def erase_users_computers(self, dn):
         """Erases user and computer objects from our AD.
-        
+
         This is needed since the 'samldb' module denies the deletion of primary
         groups. Therefore all groups shouldn't be primary somewhere anymore.
         """
@@ -153,7 +153,7 @@ class Ldb(_Ldb):
 
     def erase_except_schema_controlled(self):
         """Erase this ldb.
-        
+
         :note: Removes all records, except those that are controlled by
             Samba4's schema.
         """
@@ -246,7 +246,8 @@ def substitute_var(text, values):
 
 
 def check_all_substituted(text):
-    """Make sure that all substitution variables in a string have been replaced.
+    """Check that all substitution variables in a string have been replaced.
+
     If not, raise an exception.
 
     :param text: The text to search for substitution variables
@@ -257,7 +258,8 @@ def check_all_substituted(text):
     var_start = text.find("${")
     var_end = text.find("}", var_start)
 
-    raise Exception("Not all variables substituted: %s" % text[var_start:var_end+1])
+    raise Exception("Not all variables substituted: %s" %
+        text[var_start:var_end+1])
 
 
 def read_and_sub_file(file_name, subst_vars):
@@ -306,14 +308,14 @@ def ensure_external_module(modulename, location):
     """Add a location to sys.path if an external dependency can't be found.
 
     :param modulename: Module name to import
-    :param location: Location to add to sys.path (can be relative to 
-        ${srcdir}/lib
+    :param location: Location to add to sys.path (can be relative to
+        ${srcdir}/lib)
     """
     try:
         __import__(modulename)
     except ImportError:
         if in_source_tree():
-            sys.path.insert(0, 
+            sys.path.insert(0,
                 os.path.join(os.path.dirname(__file__),
                              "../../../../lib", location))
             __import__(modulename)
diff --git a/source4/scripting/python/samba/join.py b/source4/scripting/python/samba/join.py
index deeedc5ad3..12df25a866 100644
--- a/source4/scripting/python/samba/join.py
+++ b/source4/scripting/python/samba/join.py
@@ -18,13 +18,14 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-import samba.getopt as options
+"""Joining a domain."""
+
 from samba.auth import system_session
 from samba.samdb import SamDB
-from samba import gensec, Ldb, drs_utils, dsdb
+from samba import gensec, Ldb, drs_utils
 import ldb, samba, sys, os, uuid
-from samba.ndr import ndr_pack, ndr_unpack, ndr_print
-from samba.dcerpc import security, drsuapi, misc, netlogon, nbt
+from samba.ndr import ndr_pack
+from samba.dcerpc import security, drsuapi, misc, nbt
 from samba.credentials import Credentials, DONT_USE_KERBEROS
 from samba.provision import secretsdb_self_join, provision, FILL_DRS, find_setup_dir
 from samba.schema import Schema
diff --git a/source4/scripting/python/samba/ms_schema.py b/source4/scripting/python/samba/ms_schema.py
index 2c773bd005..64bb28a967 100644
--- a/source4/scripting/python/samba/ms_schema.py
+++ b/source4/scripting/python/samba/ms_schema.py
@@ -1,10 +1,11 @@
-#!/usr/bin/env python
 #
 # create schema.ldif (as a string) from WSPP documentation
 #
 # based on minschema.py and minschema_wspp
 #
 
+"""Generate LDIF from WSPP documentation."""
+
 import re
 import base64
 import uuid
@@ -276,5 +277,3 @@ if __name__ == '__main__':
         sys.exit(1)
         
     print read_ms_schema(attr_file, classes_file)
-
-        
diff --git a/source4/scripting/python/samba/ndr.py b/source4/scripting/python/samba/ndr.py
index 3397e1da14..112668523f 100644
--- a/source4/scripting/python/samba/ndr.py
+++ b/source4/scripting/python/samba/ndr.py
@@ -1,31 +1,49 @@
-#!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
 # Unix SMB/CIFS implementation.
 # Copyright © Jelmer Vernooij <jelmer@samba.org> 2008
-#   
+#
 # 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 3 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, see <http://www.gnu.org/licenses/>.
 #
 
+
+"""Network Data Representation (NDR) marshalling and unmarshalling."""
+
+
 def ndr_pack(object):
-    return object.__ndr_pack__()
+    """Pack a NDR object.
+    
+    :param object: Object to pack
+    :return: String object with marshalled object.
+    """
+    ndr_pack = getattr(object, "__ndr_pack__", None)
+    if ndr_pack is None:
+        raise TypeError("%r is not a NDR object" % object)
+    return ndr_pack()
 
 
 def ndr_unpack(cls, data):
+    """NDR unpack an object.
+
+    :param cls: Class of the object to unpack
+    :param data: Buffer to unpack
+    :return: Unpacked object
+    """
     object = cls()
     object.__ndr_unpack__(data)
     return object
 
+
 def ndr_print(object):
     return object.__ndr_print__()
diff --git a/source4/scripting/python/samba/ntacls.py b/source4/scripting/python/samba/ntacls.py
index 4f1c922810..0667a5199c 100644
--- a/source4/scripting/python/samba/ntacls.py
+++ b/source4/scripting/python/samba/ntacls.py
@@ -18,6 +18,9 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
+"""NT Acls."""
+
+
 import os
 import samba.xattr_native, samba.xattr_tdb
 from samba.dcerpc import security, xattr
diff --git a/source4/scripting/python/samba/provision/__init__.py b/source4/scripting/python/samba/provision/__init__.py
index 6b32a71213..37d99a519d 100644
--- a/source4/scripting/python/samba/provision/__init__.py
+++ b/source4/scripting/python/samba/provision/__init__.py
@@ -53,17 +53,20 @@ from samba import (
     valid_netbios_name,
     version,
     )
+from samba.dcerpc import security
+from samba.dcerpc.misc import (
+    SEC_CHAN_BDC,
+    SEC_CHAN_WKSTA,
+    )
 from samba.dsdb import (
     DS_DOMAIN_FUNCTION_2003,
     DS_DOMAIN_FUNCTION_2008_R2,
     ENC_ALL_TYPES,
     )
-from samba.dcerpc import security
-from samba.dcerpc.misc import SEC_CHAN_BDC, SEC_CHAN_WKSTA
 from samba.idmap import IDmapDB
 from samba.ms_display_specifiers import read_ms_ldif
 from samba.ntacls import setntacl, dsacl2fsacl
-from samba.ndr import ndr_pack,ndr_unpack
+from samba.ndr import ndr_pack, ndr_unpack
 from samba.provision.backend import (
     ExistingBackend,
     FDSBackend,
diff --git a/source4/scripting/python/samba/provision/backend.py b/source4/scripting/python/samba/provision/backend.py
index 8bd9d1f8e5..809dd4f9ec 100644
--- a/source4/scripting/python/samba/provision/backend.py
+++ b/source4/scripting/python/samba/provision/backend.py
@@ -319,7 +319,8 @@ class OpenLDAPBackend(LDAPBackend):
         """Setup a Berkeley database.
 
         :param setup_path: Setup path function.
-        :param dbdir: Database directory."""
+        :param dbdir: Database directory.
+        """
         if not os.path.isdir(os.path.join(dbdir, "bdb-logs")):
             os.makedirs(os.path.join(dbdir, "bdb-logs"), 0700)
             if not os.path.isdir(os.path.join(dbdir, "tmp")):
diff --git a/source4/scripting/python/samba/samba3.py b/source4/scripting/python/samba/samba3.py
index 42e9f9b335..2c323bd0b4 100644
--- a/source4/scripting/python/samba/samba3.py
+++ b/source4/scripting/python/samba/samba3.py
@@ -1,18 +1,16 @@
-#!/usr/bin/env python
-
 # Unix SMB/CIFS implementation.
 # Copyright (C) Jelmer Vernooij <jelmer@samba.org> 2007
-#   
+#
 # 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 3 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, see <http://www.gnu.org/licenses/>.
 #
@@ -67,7 +65,7 @@ class TdbDatabase(object):
 
 class Registry(TdbDatabase):
     """Simple read-only support for reading the Samba3 registry.
-    
+
     :note: This object uses the same syntax for registry key paths as 
         Samba 3. This particular format uses forward slashes for key path 
         separators and abbreviations for the predefined key names. 
@@ -769,7 +767,7 @@ class Samba3(object):
 
     def get_policy_db(self):
         return PolicyDatabase(self.libdir_path("account_policy.tdb"))
-    
+
     def get_registry(self):
         return Registry(self.libdir_path("registry.tdb"))
 
diff --git a/source4/scripting/python/samba/samdb.py b/source4/scripting/python/samba/samdb.py
index a86302a514..43b1938a0e 100644
--- a/source4/scripting/python/samba/samdb.py
+++ b/source4/scripting/python/samba/samdb.py
@@ -83,10 +83,12 @@ class SamDB(samba.Ldb):
         user_dn = res[0].dn
 
         userAccountControl = int(res[0]["userAccountControl"][0])
-        if (userAccountControl & 0x2):
-            userAccountControl = userAccountControl & ~0x2 # remove disabled bit
-        if (userAccountControl & 0x20):
-            userAccountControl = userAccountControl & ~0x20 # remove 'no password required' bit
+        if userAccountControl & 0x2:
+            # remove disabled bit
+            userAccountControl = userAccountControl & ~0x2
+        if userAccountControl & 0x20:
+             # remove 'no password required' bit
+            userAccountControl = userAccountControl & ~0x20
 
         mod = """
 dn: %s
@@ -179,7 +181,8 @@ pwdLastSet: 0
 
         :param groupname: Name of the target group
         :param listofmembers: Comma-separated list of group members
-        :param add_members_operation: Defines if its an add or remove operation
+        :param add_members_operation: Defines if its an add or remove
+            operation
         """
 
         groupfilter = "(&(sAMAccountName=%s)(objectCategory=%s,%s))" % (groupname, "CN=Group,CN=Schema,CN=Configuration", self.domain_dn())
@@ -444,6 +447,9 @@ accountExpires: %u
         """Read the domain SID used by this LDB. """
         return dsdb._samdb_get_domain_sid(self)
 
+    domain_sid = property(get_domain_sid, set_domain_sid,
+        "SID for the domain")
+
     def set_invocation_id(self, invocation_id):
         """Set the invocation id for this SamDB handle.
 
@@ -451,6 +457,13 @@ accountExpires: %u
         """
         dsdb._dsdb_set_ntds_invocation_id(self, invocation_id)
 
+    def get_invocation_id(self):
+        """Get the invocation_id id"""
+        return dsdb._samdb_ntds_invocation_id(self)
+
+    invocation_id = property(get_invocation_id, set_invocation_id,
+        "Invocation ID GUID")
+
     def get_oid_from_attid(self, attid):
         return dsdb._dsdb_get_oid_from_attid(self, attid)
 
@@ -459,10 +472,6 @@ accountExpires: %u
         return dsdb._dsdb_get_attid_from_lDAPDisplayName(self,
             ldap_display_name, is_schema_nc)
 
-    def get_invocation_id(self):
-        """Get the invocation_id id"""
-        return dsdb._samdb_ntds_invocation_id(self)
-
     def set_ntds_settings_dn(self, ntds_settings_dn):
         """Set the NTDS Settings DN, as would be returned on the dsServiceName
         rootDSE attribute.
@@ -473,10 +482,6 @@ accountExpires: %u
         """
         dsdb._samdb_set_ntds_settings_dn(self, ntds_settings_dn)
 
-    invocation_id = property(get_invocation_id, set_invocation_id)
-
-    domain_sid = property(get_domain_sid, set_domain_sid)
-
     def get_ntds_GUID(self):
         """Get the NTDS objectGUID"""
         return dsdb._samdb_ntds_objectGUID(self)
diff --git a/source4/scripting/python/samba/schema.py b/source4/scripting/python/samba/schema.py
index a8aaa5d09a..0bc60fa321 100644
--- a/source4/scripting/python/samba/schema.py
+++ b/source4/scripting/python/samba/schema.py
@@ -76,7 +76,8 @@ class Schema(object):
         """
 
         self.schemadn = schemadn
-        # We need to have the am_rodc=False just to keep some warnings quiet - this isn't a real SAM, so it's meaningless.
+        # We need to have the am_rodc=False just to keep some warnings quiet -
+        # this isn't a real SAM, so it's meaningless.
         self.ldb = SamDB(global_schema=False, am_rodc=False)
         if invocationid is not None:
             self.ldb.set_invocation_id(invocationid)
diff --git a/source4/scripting/python/samba/upgrade.py b/source4/scripting/python/samba/upgrade.py
index 84aaba2c55..2911d7808f 100644
--- a/source4/scripting/python/samba/upgrade.py
+++ b/source4/scripting/python/samba/upgrade.py
@@ -1,8 +1,18 @@
-#!/usr/bin/env python
+# backend code for upgrading from Samba3
+# Copyright Jelmer Vernooij 2005-2007
 #
-#    backend code for upgrading from Samba3
-#    Copyright Jelmer Vernooij 2005-2007
-#    Released under the GNU GPL v3 or later
+# 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 3 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, see <http://www.gnu.org/licenses/>.
 #
 
 """Support code for upgrading from Samba 3 to Samba 4."""
@@ -34,7 +44,7 @@ samba3UserMustLogonToChangePassword: %d
 samba3BadLockoutMinutes: %d
 samba3DisconnectTime: %d
 
-""" % (dn, policy.min_password_length, 
+""" % (dn, policy.min_password_length,
     policy.password_history, policy.minimum_password_age,
     policy.maximum_password_age, policy.lockout_duration,
     policy.reset_count_minutes, policy.user_must_logon_to_change_password,
@@ -43,7 +53,7 @@ samba3DisconnectTime: %d
 
 def import_sam_account(samldb,acc,domaindn,domainsid):
     """Import a Samba 3 SAM account.
-    
+
     :param samldb: Samba 4 SAM Database handle
     :param acc: Samba 3 account
     :param domaindn: Domain DN
@@ -59,7 +69,7 @@ def import_sam_account(samldb,acc,domaindn,domainsid):
 
     if acc.fullname is None:
         acc.fullname = acc.username
-    
+
     assert acc.fullname is not None
     assert acc.nt_username is not None
 
@@ -78,8 +88,8 @@ def import_sam_account(samldb,acc,domaindn,domainsid):
         "samba3Domain": acc.domain,
         "samba3DirDrive": acc.dir_drive,
         "samba3MungedDial": acc.munged_dial,
-        "samba3Homedir": acc.homedir, 
-        "samba3LogonScript": acc.logon_script, 
+        "samba3Homedir": acc.homedir,
+        "samba3LogonScript": acc.logon_script,
         "samba3ProfilePath": acc.profile_path,
         "samba3Workstations": acc.workstations,
         "samba3KickOffTime": str(acc.kickoff_time),
@@ -95,7 +105,7 @@ def import_sam_account(samldb,acc,domaindn,domainsid):
 
 def import_sam_group(samldb, sid, gid, sid_name_use, nt_name, comment, domaindn):
     """Upgrade a SAM group.
-    
+
     :param samldb: SAM database.
     :param gid: Group GID
     :param sid_name_use: SID name use
@@ -109,7 +119,7 @@ def import_sam_group(samldb, sid, gid, sid_name_use, nt_name, comment, domaindn)
 
     if nt_name in ("Domain Guests", "Domain Users", "Domain Admins"):
         return None
-    
+
     if gid == -1:
         gr = grp.getgrnam(nt_name)
     else:
@@ -121,12 +131,12 @@ def import_sam_group(samldb, sid, gid, sid_name_use, nt_name, comment, domaindn)
         unixname = gr.gr_name
 
     assert unixname is not None
-    
+
     samldb.add({
         "dn": "cn=%s,%s" % (nt_name, domaindn),
         "objectClass": ["top", "group"],
         "description": comment,
-        "cn": nt_name, 
+        "cn": nt_name,
         "objectSid": sid,
         "unixName": unixname,
         "samba3SidNameUse": str(sid_name_use)
@@ -160,7 +170,7 @@ def import_idmap(samdb,samba3_idmap,domaindn):
 
 def import_wins(samba4_winsdb, samba3_winsdb):
     """Import settings from a Samba3 WINS database.
-    
+
     :param samba4_winsdb: WINS database to import to
     :param samba3_winsdb: WINS database to import from
     """
@@ -225,7 +235,7 @@ replace: @LIST
 
 
 smbconf_keep = [
-    "dos charset", 
+    "dos charset",
     "unix charset",
     "display charset",
     "comment",
@@ -322,7 +332,7 @@ def upgrade_smbconf(oldconf,mark):
     """Remove configuration variables not present in Samba4
 
     :param oldconf: Old configuration structure
-    :param mark: Whether removed configuration variables should be 
+    :param mark: Whether removed configuration variables should be
         kept in the new configuration as "samba3:<name>"
     """
     data = oldconf.data()
@@ -384,12 +394,12 @@ def upgrade_provision(samba3, setup_dir, logger, credentials, session_info,
     netbiosname = oldconf.get("netbios name")
 
     secrets_db = samba3.get_secrets_db()
-    
+
     if domainname is None:
         domainname = secrets_db.domains()[0]
         logger.warning("No domain specified in smb.conf file, assuming '%s'",
                 domainname)
-    
+
     if realm is None:
         if oldconf.get("domain logons") == "True":
             logger.warning("No realm specified in smb.conf file and being a DC. That upgrade path doesn't work! Please add a 'realm' directive to your old smb.conf to let us know which one you want to use (generally it's the upcased DNS domainname).")
@@ -404,7 +414,7 @@ def upgrade_provision(samba3, setup_dir, logger, credentials, session_info,
     if domainsid is None:
         logger.warning("Can't find domain secrets for '%s'; using random SID",
             domainname)
-    
+
     if netbiosname is not None:
         machinepass = secrets_db.get_machine_password(netbiosname)
     else:
@@ -422,7 +432,7 @@ def upgrade_provision(samba3, setup_dir, logger, credentials, session_info,
     # FIXME: import_registry(registry.Registry(), samba3.get_registry())
 
     # FIXME: import_idmap(samdb,samba3.get_idmap_db(),domaindn)
-    
+
     groupdb = samba3.get_groupmapping_db()
     for sid in groupdb.groupsids():
         (gid, sid_name_use, nt_name, comment) = groupdb.get_group(sid)