Add engine relaying libvirt events

[cbosdo]

What does this PR do?

Libvirt API offers clients to register callbacks for various events.
libvirt_events engine will listen on a libvirt URI (local or remote)
for events and send them to the salt event bus.

What issues does this PR fix or reference?

Nothing that is in the issue tracker to my knowledge

Tests written?

No: those would require a running libvirt daemon
Yes

Commits signed with GPG?

Yes

[cbosdo]

I can't change the callback signature: codeclimate would need to be silenced for those functions that have more than 4 arguments.

I don't really know what to do with the docstrings of the callbacks: either pylint is complaining not having them or code climate complains because their are too similar. Honestly, considering how useless those would be, I'ld just let pylint complain.

Codeclimate complains that the file is too long... but is it possible at all to have the code of an engine split into several files? Ideally I would separate the callbacks from the rest of the engine, not sure if that is possible / wanted.

[isbm]

Can we also rename callbacks from dom_<something> to domain_...? Because this is confusing with DOM (document object model). The callbacks can be also "hidden", i.e. starts from the underscore: def _something.

[isbm]

I would refactor all this into a dictionary. The def nth is not needed anywhere, because the dictionary has .get(...) function.

[cbosdo]

Found a way to get rid of these lists by introspecting libvirt module.

[isbm]

@cbosdo Unit tests do not need to have libvirt installed, only integration tests. So you can just mock.MagicMock all the output from the libvirt part and unit-test everything, since we do not really need to test the libvirt itself.

[isbm]

I am not sure you're using this correctly: https://docs.python.org/3/library/unittest.mock.html#unittest.mock.call

[cbosdo]

unit tests added now

[rallytime]

Thanks @cbosdo! There's some lint failures here: https://jenkins.saltstack.com/job/PR/job/salt-pr-lint-n/20144/violations/

[cbosdo]

Fixed the pylint errors now

[rallytime]

@cbosdo I have a couple of comments here that need to be addressed. Thank you so much for writing the tests, too!

[rallytime]

I know this is picky, but can you make this encoding line the standard version?

# -*- coding: utf-8 -*-

[rallytime]

resend --> resends

[rallytime]

Can you also add a version directive to this?

.. versionadded:: Fluorine

[rallytime]

This type of msg handling and version checking should be done in the __virtual__() function.

[isbm]

@cbosdo actually @rallytime is right. So just move checks to the __virtual__ itself:

try:
    import libvirt
except ImportError:
    libvirt = None

def __virtual__():
    '''
    Only load if libvirt python binding is present
    '''
    if libvirt is None:
        msg = 'libvirt module not found'
    elif libvirt.getVersion() < 1000000:
        msg = 'libvirt >= 1.0.0 required'
    else:
        msg = ''

    return bool(libvirt), msg

OK, basically copypaste this. 😉

[cbosdo]

This makes pylint complain on the if libvirt is None: line:
[used-before-assignment] Using variable 'libvirt' before assignment

And on the libvirt = None line that you didn't move:
[redefined-outer-name] Redefining name 'libvirt' from outer scope

[isbm]

If checks has to be in __virtual__, then just mute Lint in this case.

[rallytime]

Can you document all of the arguments here? And provide an example of how they should be used?

[rallytime]

Same comment here about docs.

[rallytime]

Rather than commenting in many places repeatedly, I'll just say this here: Any public facing function needs docs for all args/kwargs and some examples of usage. If you could update all of those below, that would be great.

[cbosdo]

All these helper functions aren't intended to be used by external code, I'ld rather hide them, but adding those comments can't harm

[isbm]

@cbosdo even hidden usually should at least document what it does. But yes, I would underscore them in front, since they are all internal.

[cbosdo]

any update on that PR?

[rallytime]

@cbosdo There's a lint violation here: https://jenkins.saltstack.com/job/PR/job/salt-pr-lint-n/20500/violations/file/salt/engines/libvirt_events.py/

[cbosdo]

@rallytime right! fixed all the pylint errors now.

[rallytime]

@cbosdo Awesome! Thanks! We're working on getting some testing issues resolved here, so we'll restart them when that's resolved.

In the mean time, @garethgreenaway can you swing by here and review this when you get a moment?

[garethgreenaway]

Looks good!

[cbosdo]

hum... looks like the branch would need a rebase before merging... should I do it now that it has been approved or you can still do it at merge time?

[cbosdo]

@rallytime is it me or the changes you requested (which have been implemented by the time) are blocking this PR?

[rallytime]

re-run py2

[rallytime]

@cbosdo Apologies for the delay. Some of the test results timed out so I am re-running some. Once those come back we can get this in. Thanks for the bump!