From a01f1e4e0480181985457617a7aa93b7b32dc80d Mon Sep 17 00:00:00 2001 From: "Gustavo J. A. M. Carneiro" Date: Tue, 29 Apr 2008 22:25:24 +0100 Subject: [PATCH] documentation work --- pybindgen/cppattribute.py | 6 +- pybindgen/cppclass.py | 86 +++++++------- pybindgen/enum.py | 8 +- pybindgen/function.py | 7 +- pybindgen/gccxmlparser.py | 46 ++++---- pybindgen/module.py | 14 +-- pybindgen/settings.py | 2 + pybindgen/typehandlers/base.py | 151 +++++++++++++------------ pybindgen/typehandlers/pyobjecttype.py | 10 +- 9 files changed, 167 insertions(+), 163 deletions(-) diff --git a/pybindgen/cppattribute.py b/pybindgen/cppattribute.py index 738617d..eaf1dc3 100644 --- a/pybindgen/cppattribute.py +++ b/pybindgen/cppattribute.py @@ -235,12 +235,12 @@ class PyMetaclass(object): """ def __init__(self, name, parent_metaclass_expr, getsets=None): """ - name -- name of the metaclass (should normally end with Meta) - parent_metaclass_expr -- C expression that should give a + @param name: name of the metaclass (should normally end with Meta) + @param parent_metaclass_expr: C expression that should give a pointer to the parent metaclass (should have a C type of PyTypeObject*) - getsets -- name of a PyGetSetDef C array variable, or None + @param getsets: name of a PyGetSetDef C array variable, or None """ assert getsets is None or isinstance(getsets, PyGetSetDef) assert isinstance(name, basestring) diff --git a/pybindgen/cppclass.py b/pybindgen/cppclass.py index 200d8ce..6f94544 100644 --- a/pybindgen/cppclass.py +++ b/pybindgen/cppclass.py @@ -38,13 +38,13 @@ def default_instance_creation_function(cpp_class, code_block, lvalue, C++ class instance needs to be created; this default implementation uses a standard C++ new allocator. - cpp_class -- the CppClass object whose instance is to be created - code_block -- CodeBlock object on which the instance creation code should be generated - lvalue -- lvalue expression that should hold the result in the end - contruct_type_name -- actual name of type to be constructed (it is + @param cpp_class: the CppClass object whose instance is to be created + @param code_block: CodeBlock object on which the instance creation code should be generated + @param lvalue: lvalue expression that should hold the result in the end + @param parameters: stringified list of parameters + @param construct_type_name: actual name of type to be constructed (it is not always the class name, sometimes it's the python helper class) - parameters -- stringified list of parameters """ assert lvalue assert not lvalue.startswith('None') @@ -327,33 +327,33 @@ class CppClass(object): incomplete_type=False, free_function=None, incref_function=None, decref_function=None, python_name=None): - """Constructor - name -- class name - parent -- optional parent class wrapper - incref_method -- if the class supports reference counting, the + """ + @param name: class name + @param parent: optional parent class wrapper + @param incref_method: if the class supports reference counting, the name of the method that increments the reference count (may be inherited from parent if not given) - decref_method -- if the class supports reference counting, the + @param decref_method: if the class supports reference counting, the name of the method that decrements the reference count (may be inherited from parent if not given) - automatic_type_narrowing -- if True, automatic return type + @param automatic_type_narrowing: if True, automatic return type narrowing will be done on objects of this class and its descendants when returned by pointer from a function or method. - allow_subclassing -- if True, generated class wrappers will + @param allow_subclassing: if True, generated class wrappers will allow subclassing in Python. - is_singleton -- if True, the class is considered a singleton, + @param is_singleton: if True, the class is considered a singleton, and so the python wrapper will never call the C++ class destructor to free the value. - peekref_method -- if the class supports reference counting, the + @param peekref_method: if the class supports reference counting, the name of the method that returns the current reference count. - free_function -- name of C function used to deallocate class instances - incref_function -- same as incref_method, but as a function instead of method - decref_method -- same as decref_method, but as a function instead of method - python_name -- name of the class as it will appear from Python side + @param free_function: name of C function used to deallocate class instances + @param incref_function: same as incref_method, but as a function instead of method + @param decref_method: same as decref_method, but as a function instead of method + @param python_name: name of the class as it will appear from Python side """ assert outer_class is None or isinstance(outer_class, CppClass) self.incomplete_type = incomplete_type @@ -612,9 +612,8 @@ class CppClass(object): """ Add a hook function to be called just prior to a helper class being generated. The hook function applies to this class and - all subclasses. The hook function is called like this: - - hook_function(helper_class) + all subclasses. The hook function is called like this:: + hook_function(helper_class) """ if not callable(hook): raise TypeError("hook function must be callable") @@ -637,7 +636,7 @@ class CppClass(object): """Set a custom function to be called to create instances of this class and its subclasses. - instance_creation_function -- instance creation function; see + @param instance_creation_function: instance creation function; see default_instance_creation_function() for signature and example. """ @@ -905,8 +904,8 @@ public: """ Add a method to the class. - method -- a CppMethod instance that can generate the method wrapper - name -- optional name of the class method as it will appear + @param method: a CppMethod instance that can generate the method wrapper + @param name: optional name of the class method as it will appear from Python side """ name = utils.ascii(name) @@ -969,7 +968,7 @@ public: """ Add a constructor to the class. - wrapper -- a CppConstructor instance + @param wrapper: a CppConstructor instance """ if isinstance(wrapper, function.Function): wrapper = CppFunctionAsConstructor(wrapper.parameters, wrapper.function_name) @@ -983,10 +982,9 @@ public: def add_static_attribute(self, value_type, name, is_const=False): """ - Caveat: static attributes cannot be changed from Python; not implemented. - value_type -- a ReturnValue object - name -- attribute name (i.e. the name of the class member variable) - is_const -- True if the attribute is const, i.e. cannot be modified + @param value_type: a ReturnValue object + @param name: attribute name (i.e. the name of the class member variable) + @param is_const: True if the attribute is const, i.e. cannot be modified """ assert isinstance(value_type, ReturnValue) getter = CppStaticAttributeGetter(value_type, self, name) @@ -999,11 +997,11 @@ public: def add_instance_attribute(self, value_type, name, is_const=False, getter=None, setter=None): """ - value_type -- a ReturnValue object - name -- attribute name (i.e. the name of the class member variable) - is_const -- True if the attribute is const, i.e. cannot be modified - getter -- None, or name of a method of this class used to get the value - setter -- None, or name of a method of this class used to set the value + @param value_type: a ReturnValue object + @param name: attribute name (i.e. the name of the class member variable) + @param is_const: True if the attribute is const, i.e. cannot be modified + @param getter: None, or name of a method of this class used to get the value + @param setter: None, or name of a method of this class used to set the value """ assert isinstance(value_type, ReturnValue) getter_wrapper = CppInstanceAttributeGetter(value_type, self, name, getter=getter) @@ -1511,8 +1509,8 @@ class CppClassRefParameter(CppClassParameterBase): def __init__(self, ctype, name, direction=Parameter.DIRECTION_IN, is_const=False, default_value=None): """ - ctype -- C type, normally 'MyClass*' - name -- parameter name + @param ctype: C type, normally 'MyClass*' + @param name: parameter name """ if ctype == self.cpp_class.name: ctype = self.cpp_class.full_name @@ -1735,14 +1733,14 @@ class CppClassPtrParameter(CppClassParameterBase): def __init__(self, ctype, name, transfer_ownership=None, custodian=None, is_const=False): """ - ctype -- C type, normally 'MyClass*' - name -- parameter name + @param ctype: C type, normally 'MyClass*' + @param name: parameter name - transfer_ownership -- this parameter transfer the ownership of + @param transfer_ownership: this parameter transfer the ownership of the pointed-to object to the called function; should be omitted if custodian is given. - custodian -- the object (custodian) that is responsible for + @param custodian: the object (custodian) that is responsible for managing the life cycle of the parameter. Possible values are: None: no object is custodian; the integer -1: the return value; the @@ -1753,7 +1751,7 @@ class CppClassPtrParameter(CppClassParameterBase): custodian. Note: only C++ class parameters can be used as custodians, not parameters of builtin Python types. - is_const -- if true, the parameter has a const attached to the leftmost + @param is_const: if true, the parameter has a const attached to the leftmost """ if ctype == self.cpp_class.name: ctype = self.cpp_class.full_name @@ -1952,11 +1950,11 @@ class CppClassPtrReturnValue(CppClassReturnValueBase): def __init__(self, ctype, caller_owns_return=None, custodian=None, is_const=False): """ - ctype -- C type, normally 'MyClass*' - caller_owns_return -- if true, ownership of the object pointer + @param ctype: C type, normally 'MyClass*' + @param caller_owns_return: if true, ownership of the object pointer is transferred to the caller; should be omitted when custodian is given. - custodian -- the object (custodian) that is responsible for + @param custodian: the object (custodian) that is responsible for managing the life cycle of the return value. Possible values are: None: no object is custodian; the integer 0: the instance of the diff --git a/pybindgen/enum.py b/pybindgen/enum.py index 057e98f..57845b7 100644 --- a/pybindgen/enum.py +++ b/pybindgen/enum.py @@ -14,10 +14,10 @@ class Enum(object): """ Creates a new enum wrapper, which should be added to a module with module.add_enum(). - cname -- C name of the enum type - values -- a list of strings with all enumeration value names - values_prefix -- prefix to add to value names, or None - cpp_namespace -- optional C++ namespace identifier, or None. + @param name: C name of the enum type + @param values: a list of strings with all enumeration value names + @param values_prefix: prefix to add to value names, or None + @param cpp_namespace: optional C++ namespace identifier, or None. Note: this namespace is *in addition to* whatever namespace of the module the enum belongs to. Typically this parameter is to diff --git a/pybindgen/function.py b/pybindgen/function.py index e755c23..9c8e821 100644 --- a/pybindgen/function.py +++ b/pybindgen/function.py @@ -132,10 +132,11 @@ class Function(ForwardWrapperBase): def get_py_method_def(self, name): - """Returns an array element to use in a PyMethodDef table. - Should only be called after code generation. + """ + Returns an array element to use in a PyMethodDef table. + Should only be called after code generation. - name -- python function/method name + @param name: python function/method name """ flags = self.get_py_method_def_flags() return "{\"%s\", (PyCFunction) %s, %s, %s }," % \ diff --git a/pybindgen/gccxmlparser.py b/pybindgen/gccxmlparser.py index 2ec70f0..6d51ce4 100644 --- a/pybindgen/gccxmlparser.py +++ b/pybindgen/gccxmlparser.py @@ -353,8 +353,8 @@ class ModuleParser(object): Creates an object that will be able parse header files and create a pybindgen module definition. - module_name -- name of the Python module - module_namespace_name -- optional C++ namespace name; if + @param module_name: name of the Python module + @param module_namespace_name: optional C++ namespace name; if given, only definitions of this namespace will be included in the python module @@ -378,20 +378,20 @@ class ModuleParser(object): definition to a PyBindGen wrapper object. This hook function will be called for every scanned type, function, or method, and given the a chance to modify the annotations for that - definition. It will be called like this: + definition. It will be called like this::: - pre_scan_hook(module_parser, pygccxml_definition, global_annotations, - parameter_annotations) + pre_scan_hook(module_parser, pygccxml_definition, global_annotations, + parameter_annotations) where: - module_parser -- the ModuleParser (this class) instance - pygccxml_definition -- the definition reported by pygccxml - global_annotations -- a dicionary containing the "global annotations" + - module_parser -- the ModuleParser (this class) instance + - pygccxml_definition -- the definition reported by pygccxml + - global_annotations -- a dicionary containing the "global annotations" for the definition, i.e. a set of key=value pairs not associated with any particular parameter - parameter_annotations -- a dicionary containing the "parameter + - parameter_annotations -- a dicionary containing the "parameter annotations" for the definition. It is a dict whose keys are parameter names and whose values are dicts containing the @@ -408,15 +408,15 @@ class ModuleParser(object): """ Add a function to be called right after converting a gccxml definition to a PyBindGen wrapper object. This hook function will be called for - every scanned type, function, or method. It will be called like this: + every scanned type, function, or method. It will be called like this:: - post_scan_hook(module_parser, pygccxml_definition, pybindgen_wrapper) + post_scan_hook(module_parser, pygccxml_definition, pybindgen_wrapper) where: - module_parser -- the ModuleParser (this class) instance - pygccxml_definition -- the definition reported by pygccxml - pybindgen_wrapper -- a pybindgen object that generates a wrapper, + - module_parser -- the ModuleParser (this class) instance + - pygccxml_definition -- the definition reported by pygccxml + - pybindgen_wrapper -- a pybindgen object that generates a wrapper, such as CppClass, Function, or CppMethod. """ if not callable(hook): @@ -435,11 +435,11 @@ class ModuleParser(object): """ parses a set of header files and returns a pybindgen Module instance. It is equivalent to calling the following methods: - 1. parse_init(header_files, include_paths, whitelist_paths) - 2. scan_types() - 3. scan_methods() - 4. scan_functions() - 5. parse_finalize() + 1. parse_init(header_files, include_paths, whitelist_paths) + 2. scan_types() + 3. scan_methods() + 4. scan_functions() + 5. parse_finalize() """ self.parse_init(header_files, include_paths, whitelist_paths) self.scan_types() @@ -453,10 +453,10 @@ class ModuleParser(object): Prepares to parse a set of header files. The following methods should then be called in order to finish the rest of scanning process: - 1. scan_types() - 2. scan_methods() - 2. scan_functions() - 3. parse_finalize() + 1. scan_types() + 2. scan_methods() + 2. scan_functions() + 3. parse_finalize() """ assert isinstance(header_files, list) self.header_files = [os.path.abspath(f) for f in header_files] diff --git a/pybindgen/module.py b/pybindgen/module.py index 033332a..312f3e5 100644 --- a/pybindgen/module.py +++ b/pybindgen/module.py @@ -80,9 +80,9 @@ class Module(object): def set_c_function_name_transformer(self, transformer): """Sets the function to be used when transforming a C function name into the python function name; the given given function - is called like this: + is called like this:: - python_name = transformer(c_name) + python_name = transformer(c_name) """ self.c_function_name_transformer = transformer @@ -90,7 +90,7 @@ class Module(object): """ Adds an additional include directive, needed to compile this python module - include -- the name of the header file to include, including + @param include: the name of the header file to include, including surrounding "" or <>. """ include = utils.ascii(include) @@ -103,8 +103,8 @@ class Module(object): """ Add a function to the module. - wrapper -- a Function instance that can generate the wrapper - name -- name of the module function as it will appear from + @param wrapper: a Function instance that can generate the wrapper + @param name: name of the module function as it will appear from Python side; if not given, the c_function_name_transformer callback, or strip_prefix, will be used to guess the Python name. @@ -127,7 +127,7 @@ class Module(object): """ Add a class to the module. - class_ -- a CppClass object + @param class_: a CppClass object """ assert isinstance(class_, CppClass) class_.module = self @@ -157,7 +157,7 @@ class Module(object): (note: assuming here one-to-one mapping between 'module' and 'compilation unit'). - definition_name -- a string that uniquely identifies the code + @param definition_name: a string that uniquely identifies the code definition that will be added. If the given definition was already declared KeyError is raised. diff --git a/pybindgen/settings.py b/pybindgen/settings.py index a148850..65f4e05 100644 --- a/pybindgen/settings.py +++ b/pybindgen/settings.py @@ -24,6 +24,7 @@ Allow generated classes to be subclassed by default. unblock_threads = False """ +Generate code to support threads. When True, by default methods/functions/constructors will unblock threads around the funcion call, i.e. allows other Python threads to run during the call. @@ -42,6 +43,7 @@ class ErrorHandler(object): error_handler = None """ +Custom error handling. Error handler, or None. When it is None, code generation exceptions propagate to the caller. Else it can be a pybindgen.utils.ErrorHandler subclass instance that handles the error. diff --git a/pybindgen/typehandlers/base.py b/pybindgen/typehandlers/base.py index 8edf3a4..30effa8 100644 --- a/pybindgen/typehandlers/base.py +++ b/pybindgen/typehandlers/base.py @@ -95,15 +95,9 @@ class CodeBlock(object): def __init__(self, error_return, declarations, predecessor=None): ''' - error_return -- code that is generated on error conditions - (detected by write_error_check()); normally - it returns from the wrapper function, - e.g. return NULL; - predecessor -- optional predecessor code block; a - predecessor is used to search for additional - cleanup actions. + CodeBlock constructor - >>> block = CodeBlock('return NULL;', DeclarationsScope()) + >>> block = CodeBlock("return NULL;", DeclarationsScope()) >>> block.write_code("foo();") >>> cleanup1 = block.add_cleanup_code("clean1();") >>> cleanup2 = block.add_cleanup_code("clean2();") @@ -123,6 +117,14 @@ class CodeBlock(object): bar(); clean3(); clean1(); + + @param error_return: code that is generated on error conditions + (detected by write_error_check()); normally + it returns from the wrapper function, + e.g. return NULL; + @param predecessor: optional predecessor code block; a + predecessor is used to search for additional + cleanup actions. ''' assert isinstance(declarations, DeclarationsScope) assert predecessor is None or isinstance(predecessor, CodeBlock) @@ -193,11 +195,9 @@ class CodeBlock(object): def write_error_check(self, failure_expression, failure_cleanup=None): '''Add a chunk of code that checks for a possible error - Keywork arguments: - - failure_expression -- C boolean expression that is true when + @param failure_expression: C boolean expression that is true when an error occurred - failure_cleanup -- optional extra cleanup code to write only + @param failure_cleanup: optional extra cleanup code to write only for the the case when failure_expression is true; this extra cleanup code comes before all other cleanup code previously registered. @@ -259,12 +259,12 @@ class ParseTupleParameters(object): """ Adds a new parameter specification - param_template -- template item, see documentation for + @param param_template: template item, see documentation for PyArg_ParseTuple for more information - param_values -- list of parameters, see documentation + @param param_values: list of parameters, see documentation for PyArg_ParseTuple for more information - prepend -- whether this parameter should be parsed first - optional -- whether the parameter is optional; note that after + @param prepend: whether this parameter should be parsed first + @param optional: whether the parameter is optional; note that after the first optional parameter, all remaining parameters must also be optional """ @@ -348,12 +348,12 @@ class BuildValueParameters(object): """ Adds a new parameter to the Py_BuildValue (or similar) statement. - param_template -- template item, see documentation for + @param param_template: template item, see documentation for Py_BuildValue for more information - param_values -- list of C expressions to use as value, see documentation + @param param_values: list of C expressions to use as value, see documentation for Py_BuildValue for more information - prepend -- whether this parameter should come first in the tuple being built - cancels_cleanup -- optional handle to a cleanup action, + @param prepend: whether this parameter should come first in the tuple being built + @param cancels_cleanup: optional handle to a cleanup action, that is removed after the call. Typically this is used for 'N' parameters, which already consume an object reference @@ -386,12 +386,8 @@ class DeclarationsScope(object): """Manages variable declarations in a given scope.""" def __init__(self, parent_scope=None): - """Constructor - - parent_scope -- optional 'parent scope'; if given, - declarations in this scope will avoid clashing - with names in the parent scope, and vice - versa. + """ + Constructor >>> scope = DeclarationsScope() >>> scope.declare_variable('int', 'foo') @@ -410,6 +406,11 @@ class DeclarationsScope(object): int foo2; int foo3 = 1; const char *kwargs[] = {"hello", NULL}; + + @param parent_scope: optional 'parent scope'; if given, + declarations in this scope will avoid clashing + with names in the parent scope, and vice + versa. """ self._declarations = codesink.MemoryCodeSink() ## name -> number of variables with that name prefix @@ -426,11 +427,11 @@ class DeclarationsScope(object): def declare_variable(self, type_, name, initializer=None, array=None): """Add code to declare a variable. Returns the actual variable name used (uses 'name' as base, with a number in case of conflict.) - type_ -- C type name of the variable - name -- base name of the variable; actual name used can be + @param type_: C type name of the variable + @param name: base name of the variable; actual name used can be slightly different in case of name conflict. - initializer -- optional, value to initialize the variable with - array -- optional, array size specifiction, e.g. '[]', or '[100]' + @param initializer: optional, value to initialize the variable with + @param array: optional, array size specifiction, e.g. '[]', or '[100]' """ try: num = self.declared_variables[name] @@ -452,7 +453,7 @@ class DeclarationsScope(object): def reserve_variable(self, name): """Reserve a variable name, to be used later. - name -- base name of the variable; actual name used can be + @param name: base name of the variable; actual name used can be slightly different in case of name conflict. """ try: @@ -478,7 +479,7 @@ class ReverseWrapperBase(object): Reverse wrappers all have the following general structure in common: - 1. 'declarations' -- variable declarations; for compatibility with + 1. 'declarations' -- variable declarations; for compatibility with older C compilers it is very important that all declarations come before any simple statement. Declarations can be added with the add_declaration() method on the 'declarations' @@ -486,22 +487,22 @@ class ReverseWrapperBase(object): ' retval', unless return-type is void, and 'PyObject *py_retval'; - 2. 'code before call' -- this is a code block dedicated to contain + 2. 'code before call' -- this is a code block dedicated to contain all code that is needed before calling into Python; code can be freely added to it by accessing the 'before_call' (a CodeBlock instance) attribute; - 3. 'call into python' -- this is realized by a + 3. 'call into python' -- this is realized by a PyObject_CallMethod(...) or similar Python API call; the list of parameters used in this call can be customized by accessing the 'build_params' (a BuildValueParameters instance) attribute; - 4. 'code after call' -- this is a code block dedicated to contain + 4. 'code after call' -- this is a code block dedicated to contain all code that must come after calling into Python; code can be freely added to it by accessing the 'after_call' (a CodeBlock instance) attribute; - 5. A 'return retval' statement (or just 'return' if return_value is void) + 5. A 'return retval' statement (or just 'return' if return_value is void) """ @@ -509,8 +510,8 @@ class ReverseWrapperBase(object): ''' Base constructor - return_value -- type handler for the return value - parameters -- a list of type handlers for the parameters + @param return_value: type handler for the return value + @param parameters: a list of type handlers for the parameters ''' @@ -553,9 +554,9 @@ class ReverseWrapperBase(object): def generate(self, code_sink, wrapper_name, decl_modifiers=('static',), decl_post_modifiers=()): """Generate the wrapper - code_sink -- a CodeSink object that will receive the code - wrapper_name -- C/C++ identifier of the function/method to generate - decl_modifiers -- list of C/C++ declaration modifiers, e.g. 'static' + @param code_sink: a CodeSink object that will receive the code + @param wrapper_name: C/C++ identifier of the function/method to generate + @param decl_modifiers: list of C/C++ declaration modifiers, e.g. 'static' """ assert isinstance(decl_modifiers, (list, tuple)) assert all([isinstance(mod, str) for mod in decl_modifiers]) @@ -627,7 +628,7 @@ class ForwardWrapperBase(object): Forward wrappers all have the following general structure in common: - 1. 'declarations' -- variable declarations; for compatibility with + 1. 'declarations' -- variable declarations; for compatibility with older C compilers it is very important that all declarations come before any simple statement. Declarations can be added with the add_declaration() method on the 'declarations' @@ -635,34 +636,34 @@ class ForwardWrapperBase(object): ' retval', unless return-type is void, and 'PyObject *py_retval'; - 2. 'code before parse' -- code before the + 2. 'code before parse' -- code before the PyArg_ParseTupleAndKeywords call; code can be freely added to it by accessing the 'before_parse' (a CodeBlock instance) attribute; - 3. A PyArg_ParseTupleAndKeywords call; uses items from the + 3. A PyArg_ParseTupleAndKeywords call; uses items from the parse_params object; - 4. 'code before call' -- this is a code block dedicated to contain + 4. 'code before call' -- this is a code block dedicated to contain all code that is needed before calling the C function; code can be freely added to it by accessing the 'before_call' (a CodeBlock instance) attribute; - 5. 'call into C' -- this is realized by a C/C++ call; the list of + 5. 'call into C' -- this is realized by a C/C++ call; the list of parameters that should be used is in the 'call_params' wrapper attribute; - 6. 'code after call' -- this is a code block dedicated to contain + 6. 'code after call' -- this is a code block dedicated to contain all code that must come after calling into Python; code can be freely added to it by accessing the 'after_call' (a CodeBlock instance) attribute; - 7. A py_retval = Py_BuildValue(...) call; this call can be + 7. A py_retval = Py_BuildValue(...) call; this call can be customized, so that out/inout parameters can add additional return values, by accessing the 'build_params' (a BuildValueParameters instance) attribute; - 8. Cleanup and return. + 8. Cleanup and return. Object constructors cannot return values, and so the step 7 is to be omitted for them. @@ -679,13 +680,13 @@ class ForwardWrapperBase(object): ''' Base constructor - return_value -- type handler for the return value - parameters -- a list of type handlers for the parameters - parse_error_return -- statement to return an error during parameter parsing - error_return -- statement to return an error after parameter parsing - force_parse -- force generation of code to parse parameters even if there are none - no_c_retval -- force the wrapper to not have a C return value - unblock_threads -- generate code to unblock python threads during the C function call + @param return_value: type handler for the return value + @param parameters: a list of type handlers for the parameters + @param parse_error_return: statement to return an error during parameter parsing + @param error_return: statement to return an error after parameter parsing + @param force_parse: force generation of code to parse parameters even if there are none + @param no_c_retval: force the wrapper to not have a C return value + @param unblock_threads: generate code to unblock python threads during the C function call ''' assert isinstance(return_value, ReturnValue) or return_value is None assert isinstance(parameters, list) @@ -881,9 +882,9 @@ class TypeTransformation(object): def get_untransformed_name(self, name): """ Given a transformed named, get the original C type name. - E.g., given a smart pointer transformation, MySmartPointer: + E.g., given a smart pointer transformation, MySmartPointer:: - get_untransformed_name('MySmartPointer') -> 'Foo*' + get_untransformed_name('MySmartPointer') -> 'Foo*' """ raise NotImplementedError @@ -891,9 +892,9 @@ class TypeTransformation(object): """ Given a type_handler class, create an instance with proper customization. - type_handler_class -- type handler class - args -- arguments - kwargs -- keywords arguments + @param type_handler_class: type handler class + @param args: arguments + @param kwargs: keywords arguments """ raise NotImplementedError @@ -902,9 +903,10 @@ class TypeTransformation(object): Transforms a value expression of the original type to an equivalent value expression in the transformed type. - Example, with the transformation: 'T*' -> 'boost::shared_ptr' - Then: transform(wrapper, 'foo') -> - 'boost::shared_ptr<%s>(foo)' % type_handler.untransformed_ctype + Example, with the transformation:: + 'T*' -> 'boost::shared_ptr' + Then:: + transform(wrapper, 'foo') -> 'boost::shared_ptr<%s>(foo)' % type_handler.untransformed_ctype """ raise NotImplementedError @@ -913,9 +915,10 @@ class TypeTransformation(object): Transforms a value expression of the transformed type to an equivalent value expression in the original type. - Example, with the transformation: 'T*' -> 'boost::shared_ptr' - Then: untransform(wrapper, 'foo') -> - 'foo->get_pointer()' + Example, with the transformation:: + 'T*' -> 'boost::shared_ptr' + Then:: + untransform(wrapper, 'foo') -> 'foo->get_pointer()' """ raise NotImplementedError @@ -993,7 +996,7 @@ class ReturnValue(object): Keywork Arguments: - ctype -- actual C/C++ type being used + @param ctype: actual C/C++ type being used ''' if type(self) is ReturnValue: raise TypeError('ReturnValue is an abstract class; use ReturnValue.new(...)') @@ -1099,9 +1102,9 @@ class Parameter(object): Keywork Arguments: - ctype -- actual C/C++ type being used - name -- parameter name - direction -- direction of the parameter transfer, valid values + @param ctype: actual C/C++ type being used + @param name: parameter name + @param direction: direction of the parameter transfer, valid values are DIRECTION_IN, DIRECTION_OUT, and DIRECTION_IN|DIRECTION_OUT ''' @@ -1166,8 +1169,8 @@ class TypeMatcher(object): def register(self, name, type_handler): """Register a new handler class for a given C type - name -- C type name - type_handler -- class to handle this C type + @param name: C type name + @param type_handler: class to handle this C type """ if name in self._types: raise ValueError("return type %s already registered" % (name,)) @@ -1181,7 +1184,7 @@ class TypeMatcher(object): Returns a handler with the given ctype name, or raises KeyError. Supports type transformations. - name -- C type name, possibly transformed (e.g. MySmartPointer looks up Foo*) + @param name: C type name, possibly transformed (e.g. MySmartPointer looks up Foo*) """ try: return self._types[name], None diff --git a/pybindgen/typehandlers/pyobjecttype.py b/pybindgen/typehandlers/pyobjecttype.py index fe783a3..094197e 100644 --- a/pybindgen/typehandlers/pyobjecttype.py +++ b/pybindgen/typehandlers/pyobjecttype.py @@ -12,9 +12,9 @@ class PyObjectParam(Parameter): def __init__(self, ctype, name, transfer_ownership): """ - ctype -- C type, normally 'PyObject*' - name -- parameter name - transfer_ownership -- this parameter transfer the ownership of + @param ctype: C type, normally 'PyObject*' + @param name: parameter name + @param transfer_ownership: this parameter transfer the ownership of the pointed-to object to the called function """ @@ -44,8 +44,8 @@ class PyObjectReturnValue(ReturnValue): def __init__(self, ctype, caller_owns_return): """ - ctype -- C type, normally 'MyClass*' - caller_owns_return -- if true, ownership of the object pointer + @param ctype: C type, normally 'MyClass*' + @param caller_owns_return: if true, ownership of the object pointer is transferred to the caller """ super(PyObjectReturnValue, self).__init__(ctype)