Add type hints to public API code

This MR adds type hints to the public API of BuildStream. In other words, basically the plugin-author facing APIs.

There are some exceptions to this rule where I needed to add type hints to some private API. This has been done only in cases where mypy was complaining about not being being able to infer type of certain thing.

Some caveats:

• Majority of this patch comes in form of a a single commit. This is intentional as breaking it down will result in commits for which type checking will fail.

• Since Python 3.5 is our lowest common denominator (at this time anyway), supporting it means that we can't use some of the goodies that came in 3.6, like variable annotations. For peculiar reasons, typing.Deque also happens to be missing from 3.5.

• To get hints for Cythonized code, we will need to add stubs for them. I have not added this in this patch.

• There are cases where importing a module for type annotation would result in import cycle. In such cases I have put those imports behind a if typing.TYPE_CHECKING guard, and used forward references. More details on this topic can be found in mypy documentation.

• pylint reports imports as unused when they are used only in type comments. It does deal with proper type annotations correctly, but not with type comments. So, I had to litter a few imports with # pylint: disable=unused-import This is not an issue anymore - fixed by putting such imports behind if TYPE_CHECKING guard.

• In a small number of cases, adding type hints was non-trvial. I have used # type: ignore in these cases, and added a comment describing the reason.

---

This was originally discussed in this ML thread.