api-doc.sh: Cleanup: Remove unused function
stbt.get_config: Explicitly cast return value to `str`

`ConfigParser.get` always returns a string already, but this helps
`pylint` (a static analyser), which otherwise would fail when run on a
script that calls `stbt.get_config(...).split(":")`:

    xxx.py:nnn: [E1103] Instance of '_Chainmap' has no 'startswith'
                member (but some types could not be inferred)
`wait_for_match` etc: Fix race condition when specifying match parameters

This was manifesting as intermittent failures of the test
`test_wait_for_match_confirm_methods_produce_different_results`.

This is issue #24: https://github.com/drothlis/stb-tester/issues/24

The race condition is that the `template` property of the
`stbt-templatematch` GStreamer element is being set *before* setting the
`confirmMethod` property. Sometimes the GStreamer element manages to
process one frame using the new template, and post a message, before the
`confirmMethod` property is set. The default `confirmMethod` value
causes a different match result than what we expect with the value we
wanted to set.

HOW I DIAGNOSED IT
==================

This was easy to diagnose with the following patch:

   diff --git a/gst/gsttemplatematch.c b/gst/gsttemplatematch.c
   index bd115e2..6642b81 100644
   --- a/gst/gsttemplatematch.c
   +++ b/gst/gsttemplatematch.c
   @@ -503,6 +503,10 @@ gst_templatematch_chain (GstPad * pad, GstBuffer * buf)
          matched = FALSE;
        }

   +    printf("*** matched: %s\n", matched ? "true" : "false");
   +    printf("*** confirmMethod: %d\n", filter->confirmMethod);
   +    printf("*** template: %s\n", filter->template);
   +
        s = gst_structure_new ("template_match",
            "x", G_TYPE_UINT, best_pos.x,
            "y", G_TYPE_UINT, best_pos.y,

I got the following output:

    stbt-run: Searching for tests/known-fail-template.png
    *** matched: true
    *** confirmMethod: 1
    *** template: tests/known-fail-template.png
    *** matched: false
    *** confirmMethod: 2
    *** template: tests/known-fail-template.png

THINGS THAT DIDN'T WORK
=======================

    diff --git a/stbt.py b/stbt.py
    index 646b758..4aa18bf 100644
    --- a/stbt.py
    +++ b/stbt.py
    @@ -754,8 +754,7 @@ def Display.detect:
                 properties_backup[key] = getattr(element.props, key)

             try:
    -            for key in properties.keys():
    -                setattr(element.props, key, properties[key])
    +            element.set_properties(**properties)

                 # Timeout after 10s in case no messages are received on the bus.
                 # This happens when starting a new instance of stbt when the

It seems that `set_properties` doesn't set all properties atomically.

    diff --git a/stbt.py b/stbt.py
    index c5ddd26..bcdaf08 100644
    --- a/stbt.py
    +++ b/stbt.py
    @@ -655,8 +655,10 @@ def Display.detect
                 params_backup[key] = getattr(element.props, key)

             try:
    +            self.pipeline.set_state(gst.STATE_PAUSED)
                 for key in params.keys():
                     setattr(element.props, key, params[key])
    +            self.pipeline.set_state(gst.STATE_PLAYING)

                 # Timeout after 10s in case no messages are received on the bus.
                 # This happens when starting a new instance of stbt when the

Pausing the pipeline while we set the properties didn't make any
difference either. Maybe the `set_state` function doesn't block until
the pipeline is actually paused?

THE FIX
=======

This fix simply sets the `template` property after all the other
properties. This works because `detect_match` discards messages from the
GStreamer element if the message's `template` field doesn't match the
template we are looking for.

We do the same for the `enabled` property of the `stbt-motiondetect`
GStreamer element used by `detect_motion`. Note that
`stbt-templatematch` doesn't have an `enabled` property, because the
`template` property serves the same purpose.

This is a *temporary* fix because, in theory, the GStreamer element
could have posted a message *after* we've stopped reading messages but
before we set the `template` property back to null. If the next
`wait_for_match` uses the same template but with different match
parameters, it might read the old message from the bus and mistakenly
accept it.

A more robust fix would be to set some serial number property (*after*
setting the new template and all match-parameter properties), have the
GStreamer element include this serial number in the messages it posts,
and have the python application check that the serial number in the
messages matches the value it set.
gsttemplatematch.c: GStreamer element documentation comment

I have no idea where the "#" and "%" notation comes from; I just copied
the notation from gstmotiondetect.c. The closest I found was by googling
for "gobject doc comments" which found this:
https://live.gnome.org/GObjectIntrospection/Annotations

which doesn't actually describe the "#" notation anywhere but does use
it in a couple of examples to refer to a type. Note though that the
above url refers to GObjectIntrospection which is fairly new; for
example it's used by GStreamer 1.0 but not by GStreamer 0.10 (the
version stb-tester uses).
stbt.get_config API change from (key, section='global') to (section, key)

This changes the python API to:

    stbt.get_config(section, key)

Since 9283df1, `get_config` no longer falls back to the "global" config
section, so it makes less sense to provide a default `section`. The
change in parameter order is more consistent with python's
`ConfigParser`, and with our command-line tool `stbt config` (and other
similar command-line tools like `git config`).

I wanted to make this API change now, before there are too many users of
`stbt.get_config`. `stbt.get_config` was only added in the previous
stb-tester release (0.12). Hopefully most users were only passing one
parameter, so now that the second parameter doesn't have a default value
you'd find the API change by running `pylint`. If they were using the
keyword parameter (in 0.12 it was called "tool" instead of "section")
then pylint will also catch the change. Otherwise there will be a
run-time failure because it's highly unlikely you'll have a section in
your config file matching the key you're looking for, with a key
matching the section you're looking for.
stbt config: Nicer error messages
stbt config: API change from `[section] key` to `section.key`

This changes the command-line tool's API to:

    stbt config <section>.<key>

Since 9283df1, the search for a configuration key no longer falls back
to the "global" config section, so it makes less sense to provide a
default section. The new API is consistent with `git config`, and it
will allow us (in future) to add a parameter to specify the default
value should the key not be found in the configuration files.

I wanted to make this change now, before there are too many users of
`stbt config` (which was only added in the previous stb-tester release,
0.12). All current users of the tool will fail: Those specifying two
parameters will fail because now only one parameter is allowed; those
specifying a single parameter will fail because that parameter doesn't
include the section and the key name separated by a dot. So at least
there won't be any confusing silent changes in behaviour.
Move default configuration to a location not writable by the user

The existing configuration search path was:

    1. /etc/stbt/stbt.conf
    2. ~/.config/stbt/stbt.conf
    3. $STBT_CONFIG_FILE

This commit adds a new path *before* the existing paths:

    0. /usr/libexec/stbt/stbt.conf
    1. ...
    2. ...
    3. ...

(assuming a typical installation prefix; exact paths may vary).

This is because /etc/stbt/stbt.conf is intended to be editable by the
user or the system administrator; if that user removes some
configuration entries, `stbt` will now continue to work.

Putting a config file in /usr/libexec may be a bit weird, but it is oh
so convenient for it to be in the same directory as stbt.py. According
to the Filesystem Hierarchy Standard (http://www.pathname.com/fhs/) it
should be in /usr/share, I suppose. On Fedora 17, packages like "rpm"
and "udev" store various configuration files (not executables, not
shared libraries) under /usr/lib/<package>/ so there is a precedent
(but that's lib, not libexec).

Note that `make install` installs stbt.conf to both
/usr/libexec/stbt/stbt.conf and /etc/stbt/stbt.conf. The latter serves
to document all available config options; the user can choose to remove
some entries, and `stbt` continues to work because it finds that entry
in /usr/libexec/stbt/stbt.conf.

Note that I didn't list /usr/libexec/stbt/stbt.conf in the README.rst /
man page, because it isn't something that users should be concerned with;
it's an implementation detail. /usr/lib* is for read-only data.
stbt.py: Cleanup: Rename GStreamer `params` variable to `properties`

This is consistent with GStreamer's nomenclature, and it serves to
clarify the distinction between the GStreamer *properties* (an
implementation detail) and the templatematch *parameters* (passed in by
the user).
README: Clarify documentation of templatematch parameters

* Reference python functions as `detect_match` instead of
  `detect_match()`, for consistency with the rest of the README.

* match_method:
  + Describe the purpose and effect of the cvMatchTemplate algorithm,
    not the implementation detail of what it returns (a "heat map").
  + Correct the possible values (from "sqdiff" to "sqdiff-normed", etc).
  + Don't use a table, because it was causing the following warning to be
    printed when opening the man page with `man` (a bug in groff?):
      grotty:<standard input> (<standard input>):6245: character above first line discarded
      grotty:<standard input> (<standard input>):6249: character above first line discarded
      grotty:<standard input> (<standard input>):6253: character above first line discarded
  + Include the docs.opencv.org URLs in plain text; otherwise they get
    lost when converting to man page format.

* match_threshold:
  + Don't mention the "confirm" stage because it hasn't been introduced yet.
  + Fix spelling of "cvMatchTemplate".
  + Remove irrelevant link to floating-point details.

* confirm_method:
  + Explain why the "confirm" step is needed.
  + Explain that it is run just on the Region of Interest identified by the
    previous step.
  + Move discussion of `normed-absdiff` disadvantages from the `absdiff`
    section (where the normalisation of `normed-absdiff` hasn't been
    explained yet) to the `normed-absdiff` section.
  + Don't recommend specific numbers for the `normed-absdiff`
    `confirm_threshold`, because the useful threshold depends entirely on
    the luminance range of the template and source images.

* erode_passes:
  + Move after `confirm_threshold`, to keep `confirm_method` and
    `confirm_threshold` closer together; this matches the order that the
    `confirm_threshold` and `erode_passes` parameters are used in.
  + Explain that `erode_passes` applies to the "confirm" algorithm.
stbt.py: Cleanup: Move `get_config` function to the top of the file

This is needed by the next commit where I add a function that calls
`get_config` to set the function's default parameter values.

A function's default parameter values are evaluated when the function
is *defined*, not when the function is *called*; so `get_config` needs
to have been defined before that function.
`wait_for_match` etc. take `MatchParameters` argument instead of `**kwargs`

Commit dd44303b changed the `wait_for_match` signature from:

    wait_for_match(
        image,
        timeout_secs=10,
        consecutive_matches=1,
        match_method=1,
        match_threshold=0.8,
        confirm_method=2,
        erode_passes=1,
        confirm_threshold=None,
        noise_threshold=None)

to:

    wait_for_match(
        image,
        timeout_secs=10,
        consecutive_matches=1,
        noise_threshold=None,
        **kwargs)

because the default values for the templatematch-related parameters are
now loaded from stbt.conf.

That made the API slightly more obscure (yes it's documented in the man
page, but developers often like to refer to the source code directly),
and it also meant that tools like pylint won't catch mis-spellings of
those parameter names.

This commit makes the parameters explicit again, but instead of passing
them as individual keyword arguments to `wait_for_match`, you pass in
a `MatchParameters` object.

This saves duplicating all the image processing parameters as keyword
arguments in `wait_for_match`, `detect_match`, `press_until_match`, and
all user-defined functions that wrap the above (of which we have quite a
few at YouView, such as `wait_for_any_match`, `match`, and `match_any`).

The downside is that it makes the call sites quite a bit more verbose.
See for example this change made to one of the selftests in this commit:

    - wait_for_match("$scratchdir/gamut.png", confirm_threshold=0.7)
    + wait_for_match("$scratchdir/gamut.png",
    +                match_parameters=MatchParameters(confirm_threshold=0.7))

The argument in favour of this change is:

+ Advanced users of stb-tester will have quite a lot of their own
  user-defined functions that would benefit from this.

+ The uglyness at the call sites is something that shouldn't be very
  frequent; the image processing algorithm should *just work* most of
  the time without customisation (except for, possibly, global settings
  in stbt.conf).
Move documentation for `MatchParameters` into the source code

Note that this documentation still appears in README.rst, but now in the
section that is automatically populated from the source code docstrings.

A note regarding the changes to api-doc.sh:

We now want to print a class's full docstring, not just the first
paragraph (as delimited by a blank line). Before `MatchParameters`, none
of the classes' docstrings had more than one paragraph. So now we use
everything in the pydoc output up to "Methods defined here" (which pydoc
prints for classes with methods) or to "Method resolution order" (which
pydoc prints for all classes, and is the first thing to appear after the
docstring for classes with no methods explicitly defined in the source
code).
Merge branch 'match-parameters'

The functional change here is commit 25d7f3a9 (`wait_for_match` etc.
take `MatchParameters` argument instead of `**kwargs`). See that commit
message for details.

* match-parameters:
  Move documentation for `MatchParameters` into the source code
  `wait_for_match` etc. take `MatchParameters` argument instead of `**kwargs`
  stbt.py: Cleanup: Move `get_config` function to the top of the file
  README: Clarify documentation of templatematch parameters
  stbt.py: Cleanup: Rename GStreamer `params` variable to `properties`

Closes #25.
stbt-completion: Update config search path to match 1fc5016e

The completions offered for `stbt config` now also look in the default
config location added in commit 1fc5016e.
stbt.py: Deprecation messages should point at source location of caller

...not at the line in stbt.py with the call to `warnings.warn`.

Note that the default values for `stacklevel` is 1, and it is
interpreted as relative to the *implementation* of `warnings.warn`, not
its caller.

Changing the stacklevel to 2 makes the warning messages appear to belong
to the module of the *caller* of `wait_for_match` (etc.), not to the
`stbt` module, so with the existing `filterwarnings` specification the
warning messages wouldn't be printed at all. Hence the change to match
on the message contents instead of the module.

Unfortunately `stbt run` runs the script via `execfile`, so for scripts
executed directly via `stbt run`, the warning message will show "stbt"
for the source file (but the line number will the line number of the
offending statement in the actual script). I think that this commit is
still worthwhile because the source file will be printed correctly for
any calls to `wait_for_match` made from a *library* imported by the
top-level script. In our corpus of test scripts at YouView the vast
majority of calls to `wait_for_match` are made from such library
functions, so the source location printed by this change is of real
value.
stbt.py: Don't use object instance for `match_parameters` default value

A function's default parameter values are evaluated *once* when the
function is defined, not when the function is called; and the function
modifies this value, so subsequent calls to the same function could
get a nasty surprise if they're expecting the original default value.
For example:

(1)  def wait_for_match(..., match_parameters=MatchParameters()):
     ...

     stbt.wait_for_match("template.png", noise_threshold=0.1)
(2)  └ match_parameters.confirm_threshold = noise_threshold

     stbt.wait_for_match("template.png")
(3)  └ properties["confirmThreshold"] = match_parameters.confirm_threshold

All 3 of the numbered lines are referencing the same `MatchParameters`
instance, so the second call to `wait_for_match` sees the modification
that was made in the first call.

Thanks to Aiman Baharna for spotting this.
stbt-completion: Correction of completion of LIRC control-recorder

A modification missing from 1ccc2b1f: the new LIRC remote types haven't
been added to the completion function of '--control-recorder'.
stbt-run: Exit with different exit codes by exception type

To make interpreting test results by a test harness easier, `stbt run`
exits with exit code '0' on success, '1' if 'stbt.UITestError' is raised
indicating a test failure, and '2' if any other exception is raised
indicating a test case error or environment error.

The test execution framework shall be configured to report the two
types of failures differently, so that it's easy to distinguish between
bugs caught and other kinds of errors.
README: Document exit status