Hello Dominique,

welcome to the OpenSCAP ecosystem!

We are happy that you would like to (and actually already have started to) contribute to our project, and we will try to to provide feedback and answer questions on a more timely manner.

The topic that you have raised looks interesting and valuable - we are aware that our Python bindings are not in the top shape, but we don't know the specifics. As of now, they are used mainly in the Oscap Anaconda Addon project, where we consider them to be "good enough". However, we would like the openscap functionality to be used by another projects, so when such opportunity arises, we are happy for it.

Concerning your proposal, see comments inline:

On 07. 10. 19 12:26, BLAZE Dominique wrote:
Recently i've learn how to use the python binding of openscap. It was pretty hard at the begin, because when you have not understand how this API works you are swimming in the fog :D
I am not a Python binding expert, and whenever I had to use our oscap module, I have simply referred to the C documentation, and called those wrapped functions in a similar way how one would call them in the C code, including e.g. the ..._free(...) functions that free memory of individual data structures. This is not very Pythonic, but it works.

It is quite likely that you have a better vision of how things should operat, could you share a more high-level view with us?

So firstly I think that a tutorial to explain how to approach this API should be awesome (how to interpret error, how to use C documentation through the api etc.)
A tutorial would be great - it could be part of the project's documentation.
Secondly, i think that an "introspection" feature should be great. For instance, when you are trying to use a callback and you don't really know what kind of argument you have, we actually need to:

  * find which kind of object we have
  * following this, deduct which functions are availables (overrided
    ones, or builtins ones). For the builtins you need to find the
    right page in the C documentation etc. (and if you don't know how
    the api routes function calls, you will probaly get lost)

Do I under stand correctly that this introspection feature is meant to be used by programmers that would like to use (i.e. not to develop) oscap bindings? I would expect that API documentation combined with good binding code that integrates with python static analyzers in editors should do the trick, and one shouldn't need to use the interactive console in other cases than quickly checking things out.
But with a call to arg.introspect(), we cand return (or directly print ?):

  * The object type (and potentatially interresting attributes).
  * The overrided functions (using its __dict__ ).
  * The builtins functions using OSCAP.__dict__ (and a filter to keep
    only the builtin functions prefixed with the object name).
  * Potentially a link to the C documentation (faster, and avoid to
    choose a wrong documentation version like me ... )

Eventually a function listing all builtins functions (OSCAP.__dict__ ) should be usefull. For instance by calling openscap_api.introspect_all() or openscap_api.common.introspect() So i'm looking forward for your advice about this proposal; i think it could be a good helper (it's not necessary but it helps, especially when you don't know well how to use this api), but perhaps some of you think it's not relevant.
Are there other projects that use this technique to assist their users with Python wrappers? Or maybe could you share how this is superior to checking out the C API in order to see what is available and what to supply as a function argument?
Here is an example of function that i've add in openscap_api to facilitate my comprehension of objects. Of course I propose to make a proper version of that custom function, following what I said before. If you agree, have you remaks about notations etc. ? (should I print directly or return a string, is the call "obj.instrospect()" well nammed etc.) About the tutorial I was thinking to a README.md in the folder openscap/swig

# in class Oscap_Object:
  def introspect_current(self):
        """ Returns all builtin function accessible through SWIG which is corresponding to the current object """
        for (k, v) in OSCAP.__dict__.items():
            if k.startswith(self.object):
        return funcs

# loading oval file and running eval agent with a callback
def oval_callback(msg, usr):
print("Msg returned by callback: "+msg.__repr__());

python3 test_api.py
OVAL file loaded :)
Msg returned by callback: <Oscap Object of type 'oval_result_definition' with instance '<Swig Object of type 'struct oval_result_definition *' at 0x7f1ba4bd8120>'> {'oval_result_definition_add_message': <built-in function oval_result_definition_add_message>,  'oval_result_definition_clone': <built-in function oval_result_definition_clone>,  'oval_result_definition_eval': <built-in function oval_result_definition_eval>,  'oval_result_definition_free': <built-in function oval_result_definition_free>,  'oval_result_definition_get_criteria': <built-in function oval_result_definition_get_criteria>,  'oval_result_definition_get_definition': <built-in function oval_result_definition_get_definition>,  'oval_result_definition_get_id': <built-in function oval_result_definition_get_id>,  'oval_result_definition_get_instance': <built-in function oval_result_definition_get_instance>,  'oval_result_definition_get_messages': <built-in function oval_result_definition_get_messages>,  'oval_result_definition_get_result': <built-in function oval_result_definition_get_result>,  'oval_result_definition_get_system': <built-in function oval_result_definition_get_system>,

Like i said, not necessary but it really easier (especially if a sample msg.introspect() is sufficient).


Open-scap-list mailing list
Open-scap-list mailing list

Reply via email to