This fixes a bug introduced by cb751ea5.
It turns out that .itervalues() is a bad idea, given that the
args dictionary is modified by plugins, leading to a bug when
we have multiple test source plugins enabled at once.

I'm sorry I didn't notice this before the commit was merged.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

Implement a feature to skip notifying broken plugins on
stderr. Let's say a user has a broken plugin that can't
be fixed right now, and he/she doesn't want to be bothered
by having it notified in stderr all the time avocado is
executed, add a configuration option that allows you to
selectively ignore plugins to display errors in stderr.

The reason why the feature is configurable is that we
want users to be notified when a new plugin is present
and for some reason is also broken, this finer grained
control is more useful to users IMHO.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

Use python's ast module to safely evaluate the list values.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

API Review (2nd round, 2nd batch) - All commits but Exceptions

It was mentioned that we should think of avocado.utils as a subproject
that happens to live in the same source tree. So, it should not make
use of any avocado module. If that's the case, maybe we don't want to
keep referencing 'avocado.utils' in the utils module themselves.

This is in accordance with PEP-0328[1]

[1] - https://www.python.org/dev/peps/pep-0328/Signed-off-by: NCleber Rosa <crosa@redhat.com>

This means also moving its dependencies, namely spark and gdbmi_parser,
to a place under avocado/utils. I've chosen to add another level here
to clearly identify those deps as 3rd party external modules that are
reused in Avocado.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The avocado.settings module is not intended to be used by tests but
by the framework itself. So, let's move it to avocado.core.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This is also a module that shouldn't be used directly by tests,
as tests themselves have attributes with the right data directories
already ready to use.

So, let's move it to avocado.core.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

There's no current use case for direct use of the multiplexer APIs
from test code, so let's move that to avocado.core.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

It looks like there's no need for the logging configuration and the
application of that configuration to live under avocado main module,
so let's move it to avocado.core.log.

Also, there also seems to be no need for the configuration to be
applied at the main module import time.

Since when the avocado command line test runner is run and also
when a test is run "directly" results in instantiating an
avocado.core.app.AvocadoApp object, this looks like the best place
for the logging configuration to actually be performed.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Even though aexpect is possibly a good candidate for the avocado.utils
namespace, there are plans to actually move it into a standalone Python
project/module. So, since no tests are currently using the module
directly, let's move to avocado.core.

It can not be removed at this point because the avocado-virt extension
uses it. A PR is being sent to avocado-virt to sync with this change.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The initial idea about the avocado.restclient namespace was that
eventually users could write scripts using that as an API to
interact with avocado-server using Python code.

While the idea is still valid, the avocado-server interface is
a simple and standards compliant RESTful interface. Thus, users
can still easily interact with it without us having to support
a formal Python API at this point.

In the future, if need arises, we can improve the Python REST
client API and promote it to a public namespace.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

avocado.utils.software_manager: Check if yum module is present

When using the software_manager component on a Red Hat like distro,
if the yum module for Python is not installed, log the information
as an error message and use the basic support from rpm/yum.

Why this?

If the module yum is not installed (for example, in a virtualenv),
the software_manager component will not traceback when creating
an instance of YumBackend and only the method provides() will be disabled.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

For a while we have been using code similar to this:

def load_plugins(self, args):
    for key in args.__dict__.keys():
        if key.endswith('_loader'):

One could argue that the sufix check is not quite elegant
or correct, so we can remove that and get straight to the
business of checking the actual loading class we're interested
in. This PR changes all the occurrences of that practice inside
the avocado code.

Changes from v2:
 * Use iteritems() instead of .keys(), as suggested by ldoktor.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

Documentation Review (2nd round) - (v2)

The text means that Avocado is made of the test runner, libs, etc.
So, that should really be written as "composed of" instead of
"composed by".

Just to be extra clear, Avocado is "composed by" the Avocado
Development Team.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The reference documentation now contains a section on the libraries and
APIs, giving information on where those can be found in the `avocado`
namespace, and their respective API stability promises.

Then, instead of giving too much information about it in the introductory
section, let's just link to the reference section if the user wants to
know more about it.

Changes from v1:
* Fix typo spotted by Lucas (s/will/you).
Signed-off-by: NCleber Rosa <crosa@redhat.com>

APIs are the interfaces that our libraries provide. So where we actually
want to talk about the full set of value that we provide to test users,
let's use the term libraries. And use APIs when it makes more sense to
do so.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

First, the wording was not clear about the language choices and the
added benefits of using Python. Also, let's focus on using the term
libraries instead of APIs. Libraries are an important part of Avocado
(see definition of what Avocado is) and IMHO denote more value than
the term APIs does.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

And not *on* a given language.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Documentation Review (v2)

Makefile: require a clean source tree before running local checks

This is just a review followed by minor wording changes and some
heavier formatting changes.

Changes from v1:
* Wording changes suggested by Lucas.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

After reading the text and shuffling the order a bit, I think this
has an easier to follow structure. A few highlights:

* An Avocado test is really a method, that is, for many methods we
  have many tests.
* Suppress the attempt to briefly explain the Multiplexer here,
  giving instead a link to a more complete documentation.

Changes from v1:
* Mention the function naming conventions for the test methods and
  link to PEP 8 relevant section for functions and classes.
* Break into finer grained sections.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

[fixup] docs: simplify Writing Avocado Test section text
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The idea is to remove everything that is not critical to the user's
understanding of the core concepts.

Also, to sync to the new multi-test in a single class capabilities
of Avocado, let's name the main test method `test`. This paves the
way for other (multi test) examples that name test methods with
the exact same prefix (test_foo, test_bar and so on).
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This includes moving the reference text and diagram on test order
resolution to the Reference Guide. Since this also included
information on what are simple and instrumented tests, let's
merge and reuse that.

Also, let's rename "Simple example" to "Basic example" so that it
does not confuse users with the concept of a Simple Test, since this
example is actually an Instrumented Test.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This commit tries to reduce the learning curve for a new Avocado user.

* The sections were broken down with new levels
* Reduce text by using links if users want more information on a topic
* Introduced a Reference Guide, where these more detailed and often
  design/internals about Avocado will be documented.
* Default the usage examples assuming an installation based on packages
* A lot of wording changes, always intending to make it simpler

Changes from v1:
* Wording changes suggested by Lucas.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Signed-off-by: NCleber Rosa <crosa@redhat.com>

First, let's assume these docs are intended for users by renaming
the first section simply "Installing Avocado".

I tried to make the "Installing Avocado" introductory text shorter,
so that it's easier to read, and if the user really wants to take
a look at the repos he/she can click on the links.

Also broke down the installation section into more sub levels.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This makes it even more clear that this feature is about a command
line option and can work with unmodified tests.

Also, the user reading this will at least know that some other
options are available, and will probably refer back to `--help`
if he needs further assistance.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Two sentences in the usage string of the --gdb-pre-run-commands
command line option lacked a white space between them, making it
difficult on the user to quickly read it and grasp it.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Since the command line (aka transparent execution of binaries) use
case is easier to grasp and probably will see more frequent use then
the API, let's present that first.

Also, standardize on the feature names, fix some typos and add a
little bit more of cross reference.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Like a git commit message, let's try to be really succient about the
first line a user will read about avocado.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Since Avocado in our context is a proper name, and not really just
some fruit, let's refer to it using a capitalized word.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Sure, sphix gave us a hand with the generation of the index file to
point us to the right direction. But, by now, we don't have to keep
that old tip.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

For completeness purporses this adds the current year to the copyright
string.
Signed-off-by: NCleber Rosa <crosa@redhat.com>