From 73b789b6d25698dba15c867c71d0cdd8c264f352 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Sat, 24 May 2008 04:01:57 +0200 Subject: Add docstrings to a couple more python modules. (This used to be commit b4560c90e5e8d3a35367d3a21d361dc4c9c0de23) --- source4/auth/auth.i | 6 ++++- source4/auth/auth.py | 4 +++ source4/auth/credentials/credentials.i | 2 +- source4/auth/credentials/credentials.py | 4 +++ source4/lib/events/events.i | 2 +- source4/lib/events/events.py | 4 +++ source4/lib/registry/registry.i | 6 ++++- source4/lib/registry/registry.py | 4 +++ source4/libcli/security/security.i | 13 +++++++++- source4/libcli/security/security.py | 40 ++++++++++++++++++++++++++++- source4/libcli/security/security_wrap.c | 25 ++++++++++++++---- source4/librpc/rpc/dcerpc.i | 6 ++++- source4/librpc/rpc/dcerpc.py | 4 +++ source4/param/param.i | 2 +- source4/param/param.py | 4 +++ source4/scripting/python/misc.i | 5 +++- source4/scripting/python/misc.py | 12 ++++++++- source4/scripting/python/misc_wrap.c | 5 +++- source4/scripting/python/samba/__init__.py | 2 ++ source4/scripting/python/samba/provision.py | 4 +-- 20 files changed, 136 insertions(+), 18 deletions(-) diff --git a/source4/auth/auth.i b/source4/auth/auth.i index b1743ef765..67c8137f67 100644 --- a/source4/auth/auth.i +++ b/source4/auth/auth.i @@ -16,7 +16,11 @@ along with this program. If not, see . */ -%module(package="samba.auth") auth +%define DOCSTRING +"Authentication and authorization support." +%enddef + +%module(docstring=DOCSTRING,package="samba.auth") auth %{ diff --git a/source4/auth/auth.py b/source4/auth/auth.py index 1a7aa6d0e7..226175a75b 100644 --- a/source4/auth/auth.py +++ b/source4/auth/auth.py @@ -3,6 +3,10 @@ # # Don't modify this file, modify the SWIG interface instead. +""" +Authentication and authorization support. +""" + import _auth import new new_instancemethod = new.instancemethod diff --git a/source4/auth/credentials/credentials.i b/source4/auth/credentials/credentials.i index 89eb4924b3..bb31d6d4c0 100644 --- a/source4/auth/credentials/credentials.i +++ b/source4/auth/credentials/credentials.i @@ -16,7 +16,7 @@ along with this program. If not, see . */ -%module(package="samba.credentials") credentials +%module(docstring="Credentials management.",package="samba.credentials") credentials %{ diff --git a/source4/auth/credentials/credentials.py b/source4/auth/credentials/credentials.py index fd00a8e6f0..2cd56c3599 100644 --- a/source4/auth/credentials/credentials.py +++ b/source4/auth/credentials/credentials.py @@ -3,6 +3,10 @@ # # Don't modify this file, modify the SWIG interface instead. +""" +Credentials management. +""" + import _credentials import new new_instancemethod = new.instancemethod diff --git a/source4/lib/events/events.i b/source4/lib/events/events.i index 7de8aec79d..5f790aeac5 100644 --- a/source4/lib/events/events.i +++ b/source4/lib/events/events.i @@ -16,7 +16,7 @@ along with this program. If not, see . */ -%module(package="samba.events") events; +%module(docstring="Event management.",package="samba.events") events; %import "../talloc/talloc.i"; diff --git a/source4/lib/events/events.py b/source4/lib/events/events.py index 264e0b7cdf..90695e3d92 100644 --- a/source4/lib/events/events.py +++ b/source4/lib/events/events.py @@ -3,6 +3,10 @@ # # Don't modify this file, modify the SWIG interface instead. +""" +Event management. +""" + import _events import new new_instancemethod = new.instancemethod diff --git a/source4/lib/registry/registry.i b/source4/lib/registry/registry.i index 7dd02b344c..9420ba2014 100644 --- a/source4/lib/registry/registry.i +++ b/source4/lib/registry/registry.i @@ -16,7 +16,11 @@ along with this program. If not, see . */ -%module registry +%define DOCSTRING +"Access to various registry formats and the Samba registry." +%enddef + +%module(docstring=DOCSTRING) registry %{ /* Include headers */ diff --git a/source4/lib/registry/registry.py b/source4/lib/registry/registry.py index 4c6e735414..0aeefb86c1 100644 --- a/source4/lib/registry/registry.py +++ b/source4/lib/registry/registry.py @@ -3,6 +3,10 @@ # # Don't modify this file, modify the SWIG interface instead. +""" +Access to various registry formats and the Samba registry. +""" + import _registry import new new_instancemethod = new.instancemethod diff --git a/source4/libcli/security/security.i b/source4/libcli/security/security.i index 647c9aea09..1d964cc3d5 100644 --- a/source4/libcli/security/security.i +++ b/source4/libcli/security/security.i @@ -16,7 +16,7 @@ along with this program. If not, see . */ -%module(package="samba.security") security +%module(docstring="Security-related classes.",package="samba.security") security %{ #include "includes.h" @@ -65,8 +65,14 @@ enum sec_privilege { typedef struct security_token { %extend { security_token(TALLOC_CTX *mem_ctx) { return security_token_initialise(mem_ctx); } + %feature("docstring") is_sid "S.is_sid(sid) -> bool\n" \ + "Check whether this token is of the specified SID."; bool is_sid(const struct dom_sid *sid); + %feature("docstring") is_system "S.is_system() -> bool\n" \ + "Check whether this is a system token."; bool is_system(); + %feature("docstring") is_anonymous "S.is_anonymus() -> bool\n" \ + "Check whether this is an anonymous token."; bool is_anonymous(); bool has_sid(const struct dom_sid *sid); bool has_builtin_administrators(); @@ -81,6 +87,8 @@ typedef struct security_token { typedef struct security_descriptor { %extend { security_descriptor(TALLOC_CTX *mem_ctx) { return security_descriptor_initialise(mem_ctx); } + %feature("docstring") sacl_add "S.sacl_add(ace) -> None\n" \ + "Add a security ace to this security descriptor"; NTSTATUS sacl_add(const struct security_ace *ace); NTSTATUS dacl_add(const struct security_ace *ace); NTSTATUS dacl_del(const struct dom_sid *trustee); @@ -111,6 +119,9 @@ typedef struct dom_sid { } } dom_sid; +%feature("docstring") random_sid "random_sid() -> sid\n" \ + "Generate a random SID"; + %inline %{ static struct dom_sid *random_sid(TALLOC_CTX *mem_ctx) { diff --git a/source4/libcli/security/security.py b/source4/libcli/security/security.py index 7e56e22cef..065c7a19e4 100644 --- a/source4/libcli/security/security.py +++ b/source4/libcli/security/security.py @@ -3,6 +3,10 @@ # # Don't modify this file, modify the SWIG interface instead. +""" +Security-related classes. +""" + import _security import new new_instancemethod = new.instancemethod @@ -86,6 +90,27 @@ class SecurityToken(object): __repr__ = _swig_repr def __init__(self, *args, **kwargs): _security.SecurityToken_swiginit(self,_security.new_SecurityToken(*args, **kwargs)) + def is_sid(*args, **kwargs): + """ + S.is_sid(sid) -> bool + Check whether this token is of the specified SID. + """ + return _security.SecurityToken_is_sid(*args, **kwargs) + + def is_system(*args, **kwargs): + """ + S.is_system() -> bool + Check whether this is a system token. + """ + return _security.SecurityToken_is_system(*args, **kwargs) + + def is_anonymous(*args, **kwargs): + """ + S.is_anonymus() -> bool + Check whether this is an anonymous token. + """ + return _security.SecurityToken_is_anonymous(*args, **kwargs) + __swig_destroy__ = _security.delete_SecurityToken SecurityToken.is_sid = new_instancemethod(_security.SecurityToken_is_sid,None,SecurityToken) SecurityToken.is_system = new_instancemethod(_security.SecurityToken_is_system,None,SecurityToken) @@ -103,6 +128,13 @@ class security_descriptor(object): __repr__ = _swig_repr def __init__(self, *args, **kwargs): _security.security_descriptor_swiginit(self,_security.new_security_descriptor(*args, **kwargs)) + def sacl_add(*args, **kwargs): + """ + S.sacl_add(ace) -> None + Add a security ace to this security descriptor + """ + return _security.security_descriptor_sacl_add(*args, **kwargs) + __swig_destroy__ = _security.delete_security_descriptor security_descriptor.sacl_add = new_instancemethod(_security.security_descriptor_sacl_add,None,security_descriptor) security_descriptor.dacl_add = new_instancemethod(_security.security_descriptor_dacl_add,None,security_descriptor) @@ -123,7 +155,13 @@ Sid.__eq__ = new_instancemethod(_security.Sid___eq__,None,Sid) Sid_swigregister = _security.Sid_swigregister Sid_swigregister(Sid) -random_sid = _security.random_sid + +def random_sid(*args): + """ + random_sid() -> sid + Generate a random SID + """ + return _security.random_sid(*args) privilege_name = _security.privilege_name privilege_id = _security.privilege_id diff --git a/source4/libcli/security/security_wrap.c b/source4/libcli/security/security_wrap.c index aabf6c27ee..a10626c043 100644 --- a/source4/libcli/security/security_wrap.c +++ b/source4/libcli/security/security_wrap.c @@ -3527,9 +3527,18 @@ fail: static PyMethodDef SwigMethods[] = { { (char *)"new_SecurityToken", (PyCFunction)_wrap_new_SecurityToken, METH_NOARGS, NULL}, - { (char *)"SecurityToken_is_sid", (PyCFunction) _wrap_SecurityToken_is_sid, METH_VARARGS | METH_KEYWORDS, NULL}, - { (char *)"SecurityToken_is_system", (PyCFunction)_wrap_SecurityToken_is_system, METH_O, NULL}, - { (char *)"SecurityToken_is_anonymous", (PyCFunction)_wrap_SecurityToken_is_anonymous, METH_O, NULL}, + { (char *)"SecurityToken_is_sid", (PyCFunction) _wrap_SecurityToken_is_sid, METH_VARARGS | METH_KEYWORDS, (char *)"\n" + "S.is_sid(sid) -> bool\n" + "Check whether this token is of the specified SID.\n" + ""}, + { (char *)"SecurityToken_is_system", (PyCFunction)_wrap_SecurityToken_is_system, METH_O, (char *)"\n" + "S.is_system() -> bool\n" + "Check whether this is a system token.\n" + ""}, + { (char *)"SecurityToken_is_anonymous", (PyCFunction)_wrap_SecurityToken_is_anonymous, METH_O, (char *)"\n" + "S.is_anonymus() -> bool\n" + "Check whether this is an anonymous token.\n" + ""}, { (char *)"SecurityToken_has_sid", (PyCFunction) _wrap_SecurityToken_has_sid, METH_VARARGS | METH_KEYWORDS, NULL}, { (char *)"SecurityToken_has_builtin_administrators", (PyCFunction)_wrap_SecurityToken_has_builtin_administrators, METH_O, NULL}, { (char *)"SecurityToken_has_nt_authenticated_users", (PyCFunction)_wrap_SecurityToken_has_nt_authenticated_users, METH_O, NULL}, @@ -3539,7 +3548,10 @@ static PyMethodDef SwigMethods[] = { { (char *)"SecurityToken_swigregister", SecurityToken_swigregister, METH_VARARGS, NULL}, { (char *)"SecurityToken_swiginit", SecurityToken_swiginit, METH_VARARGS, NULL}, { (char *)"new_security_descriptor", (PyCFunction)_wrap_new_security_descriptor, METH_NOARGS, NULL}, - { (char *)"security_descriptor_sacl_add", (PyCFunction) _wrap_security_descriptor_sacl_add, METH_VARARGS | METH_KEYWORDS, NULL}, + { (char *)"security_descriptor_sacl_add", (PyCFunction) _wrap_security_descriptor_sacl_add, METH_VARARGS | METH_KEYWORDS, (char *)"\n" + "S.sacl_add(ace) -> None\n" + "Add a security ace to this security descriptor\n" + ""}, { (char *)"security_descriptor_dacl_add", (PyCFunction) _wrap_security_descriptor_dacl_add, METH_VARARGS | METH_KEYWORDS, NULL}, { (char *)"security_descriptor_dacl_del", (PyCFunction) _wrap_security_descriptor_dacl_del, METH_VARARGS | METH_KEYWORDS, NULL}, { (char *)"security_descriptor_sacl_del", (PyCFunction) _wrap_security_descriptor_sacl_del, METH_VARARGS | METH_KEYWORDS, NULL}, @@ -3553,7 +3565,10 @@ static PyMethodDef SwigMethods[] = { { (char *)"delete_Sid", (PyCFunction)_wrap_delete_Sid, METH_O, NULL}, { (char *)"Sid_swigregister", Sid_swigregister, METH_VARARGS, NULL}, { (char *)"Sid_swiginit", Sid_swiginit, METH_VARARGS, NULL}, - { (char *)"random_sid", (PyCFunction)_wrap_random_sid, METH_NOARGS, NULL}, + { (char *)"random_sid", (PyCFunction)_wrap_random_sid, METH_NOARGS, (char *)"\n" + "random_sid() -> sid\n" + "Generate a random SID\n" + ""}, { (char *)"privilege_name", (PyCFunction) _wrap_privilege_name, METH_VARARGS | METH_KEYWORDS, NULL}, { (char *)"privilege_id", (PyCFunction) _wrap_privilege_id, METH_VARARGS | METH_KEYWORDS, NULL}, { NULL, NULL, 0, NULL } diff --git a/source4/librpc/rpc/dcerpc.i b/source4/librpc/rpc/dcerpc.i index f958d82e2e..2d7c27b07a 100644 --- a/source4/librpc/rpc/dcerpc.i +++ b/source4/librpc/rpc/dcerpc.i @@ -22,7 +22,11 @@ along with this program. If not, see . */ -%module dcerpc +%define DOCSTRING +"DCE/RPC protocol implementation" +%enddef + +%module(docstring=DOCSTRING) dcerpc %{ diff --git a/source4/librpc/rpc/dcerpc.py b/source4/librpc/rpc/dcerpc.py index db5b95cee8..5c26656230 100644 --- a/source4/librpc/rpc/dcerpc.py +++ b/source4/librpc/rpc/dcerpc.py @@ -3,6 +3,10 @@ # # Don't modify this file, modify the SWIG interface instead. +""" +DCE/RPC protocol implementation +""" + import _dcerpc import new new_instancemethod = new.instancemethod diff --git a/source4/param/param.i b/source4/param/param.i index 2c15f8f5e3..ad42919998 100644 --- a/source4/param/param.i +++ b/source4/param/param.i @@ -16,7 +16,7 @@ along with this program. If not, see . */ -%module(package="samba.param") param +%module(docstring="Parsing and writing Samba configuration files.",package="samba.param") param %{ #include diff --git a/source4/param/param.py b/source4/param/param.py index 3aebaf0e02..46c75cef97 100644 --- a/source4/param/param.py +++ b/source4/param/param.py @@ -3,6 +3,10 @@ # # Don't modify this file, modify the SWIG interface instead. +""" +Parsing and writing Samba configuration files. +""" + import _param import new new_instancemethod = new.instancemethod diff --git a/source4/scripting/python/misc.i b/source4/scripting/python/misc.i index 9a4c124121..56b862552a 100644 --- a/source4/scripting/python/misc.i +++ b/source4/scripting/python/misc.i @@ -16,7 +16,7 @@ along with this program. If not, see . */ -%module(package="samba.misc") misc +%module(docstring="Python bindings for miscellaneous Samba functions.",package="samba.misc") misc %{ #include "includes.h" @@ -37,6 +37,9 @@ %import "../../libcli/security/security.i" %import "../../libcli/util/errors.i" +%feature("docstring") generate_random_str "S.random_password(len) -> string\n" \ + "Generate random password with specified length."; + %rename(random_password) generate_random_str; char *generate_random_str(TALLOC_CTX *mem_ctx, size_t len); diff --git a/source4/scripting/python/misc.py b/source4/scripting/python/misc.py index 25e8d2de8c..0c14944001 100644 --- a/source4/scripting/python/misc.py +++ b/source4/scripting/python/misc.py @@ -3,6 +3,10 @@ # # Don't modify this file, modify the SWIG interface instead. +""" +Python bindings for miscellaneous Samba functions. +""" + import _misc import new new_instancemethod = new.instancemethod @@ -61,7 +65,13 @@ import ldb import credentials import param import security -random_password = _misc.random_password + +def random_password(*args, **kwargs): + """ + S.random_password(len) -> string + Generate random password with specified length. + """ + return _misc.random_password(*args, **kwargs) def ldb_set_credentials(*args, **kwargs): """ diff --git a/source4/scripting/python/misc_wrap.c b/source4/scripting/python/misc_wrap.c index 22a072fc6f..8c57237e5b 100644 --- a/source4/scripting/python/misc_wrap.c +++ b/source4/scripting/python/misc_wrap.c @@ -3216,7 +3216,10 @@ fail: static PyMethodDef SwigMethods[] = { - { (char *)"random_password", (PyCFunction) _wrap_random_password, METH_VARARGS | METH_KEYWORDS, NULL}, + { (char *)"random_password", (PyCFunction) _wrap_random_password, METH_VARARGS | METH_KEYWORDS, (char *)"\n" + "S.random_password(len) -> string\n" + "Generate random password with specified length.\n" + ""}, { (char *)"ldb_set_credentials", (PyCFunction) _wrap_ldb_set_credentials, METH_VARARGS | METH_KEYWORDS, (char *)"\n" "S.set_credentials(credentials)\n" "Set credentials to use when connecting.\n" diff --git a/source4/scripting/python/samba/__init__.py b/source4/scripting/python/samba/__init__.py index 94f9e4d005..e191227108 100644 --- a/source4/scripting/python/samba/__init__.py +++ b/source4/scripting/python/samba/__init__.py @@ -20,6 +20,8 @@ # along with this program. If not, see . # +"""Samba 4.""" + __docformat__ = "restructuredText" import os diff --git a/source4/scripting/python/samba/provision.py b/source4/scripting/python/samba/provision.py index a4730d8a07..3914fa8376 100644 --- a/source4/scripting/python/samba/provision.py +++ b/source4/scripting/python/samba/provision.py @@ -22,6 +22,8 @@ # along with this program. If not, see . # +"""Functions for setting up a Samba configuration.""" + from base64 import b64encode import os import pwd @@ -41,8 +43,6 @@ import urllib from ldb import SCOPE_SUBTREE, SCOPE_ONELEVEL, SCOPE_BASE, LdbError, \ LDB_ERR_NO_SUCH_OBJECT, timestring, CHANGETYPE_MODIFY, CHANGETYPE_NONE -"""Functions for setting up a Samba configuration.""" - __docformat__ = "restructuredText" DEFAULTSITE = "Default-First-Site-Name" -- cgit