Export BleakClient and BleakScanner as toplevel objects (#582)

[jackjansen]

This pull request adds toplevel objects BleakClient and BleakScanner and documents them. The objects are basically the underlying backend objects for the current platform, but this way they can be subclassed within bleak (as well as allowing more understandable user documentation). See #582 and related issues for the rationale.

The pull request is not complete yet (I still have to remove the GitHub action changes), I'm opening it mainly for discussion.

One of the things I would like feedback on: I would like to follow a similar pattern for BleakGATTService and BleakGATTCharacteristic, but I'd want to hear the opinion of the bleak maintainers. The advantage, especially from a documentation/usability point of view, would be that all objects needed for normal use would be exported from the top level, and the whole backends business becomes essentially an implementation detail.

[dlech]

The advantage, especially from a documentation/usability point of view, would be that all objects needed for normal use would be exported from the top level, and the whole backends business becomes essentially an implementation detail.

Yes, I agree this would be a nice improvement.

[jackjansen]

@dlech can you have a look? All relevant classes are now exported from toplevel. The documentation has be reorganised to have the low-level stuff and the base classes in a separate page. I've also added some prose to help people along, but: that's the prose that would have helped me along, it'd be good to have more pairs of eyes on it.

[jackjansen]

I think I'm getting close. Please check.

Also, it would be good to test that the code still runs on all platforms. I can only test on macOS. And I've had to do some restructuring to make things documentable in a sane way (for example adding BLEDevice subclasses to all backends that didn't have them yet, even though they are empty).

And, who knows, maybe when I removed the docstrings I've removed a line or two of useful code too...

[jackjansen]

Next try.

It's getting increasingly more bothersome to merge develop into this branch, mainly because I've had to move some backend base class implementation methods into abstract classes (the stuff related to the async context manager). So now when there's changes in those classes on develop I have to handcraft those.

[jackjansen]

@dlech I want to abandon this merge request, #982 is really all I need.

But that means we would lose any documentation fixes you hint at maybe wanting to pick up.

What do you suggest?

[dlech]

You mentioned before that some of the stuff you wrote were things you would have like to have known when you first started using Bleak. So if you could copy and paste that into a new pull request, I'm sure other newbies would appreciate having that in the docs.

[dlech]

Closing since this has been broken down into smaller pull requests and issues.