Implement #109

[mottosso]

Here's one way to solve #109.

[hdd]

Hi , not sure I'm getting this commit.
How does this solve #109 ?
Can't see any warning for the users.

[mottosso]

Hey, It's an attempt at solving the underlying issue. About users not knowing what is and isn't being added by Qt.py.

Solving it via the documentation route.

It's just a thought. The problem I see with warnings, is that it might get inconsistent; where only the things we add that are pure functions can give warnings, whereas other things, such as plain attributes ala __binding__ won't actually throw a warning. This way, we could potentially cover all bases.

[mottosso]

Ah, darn. This should have gone into it's own PR.

[mottosso]

Ok, done. Let me know what you think @fredrikaverpil! Especially about the README. My motivation was to better highlight important bits, i.e. docs, goal and usage.

[fredrikaverpil]

Ok let's see. So what was being discussed is whether we should print warnings to explain whether e.g. QtWidgets.QWidget or QtGui.QWidget is being actually called, right?

Like mentioned in #109 (comment) we're just making simple remappings and there's no code inbetween to catch such events. Also, I'm not sure I understand why such warnings being printed is useful - or if we could at all implement such a feature reliably. The sole purpose of this shim is to just take care of this as good as possible "under the hood" and provide the means to debug and catch these kinds of things yourself when needed.
@hdd Perhaps I'm missing something?

I agree that taking the documentation route makes more sense to me as well.
I've read the README and I think it looks good, but I think it doesn't fully communicate what was being discussed in #101 which perhaps would be a good time to address;

• We'd like to keep Qt.py simple, simple to grasp/read through (and therefore simple to maintain).
• We don't want software to rely on functionality provided by Qt.py other than the actual compatibility features (remappings).
• Instead of building custom (and sometimes advanced) convenience functionality into Qt.py, the primary goal is to create minimal compatibility between bindings (in most cases remappings).

I think perhaps these incentives should go into some kind of "development vision" under the development guidelines.

I've been busy lately but I've been meaning to set up a PR of a bunch of different example usage of the load_ui function (#81), since I believe we shouldn't add the more advanced secondary arguments to that function because of the bullet points above. Perhaps in an EXAMPLE_USAGE.md or in its own folder examples containing gist-like examples.

Taking all of that into consideration, an "example" could perhaps show how to print warnings for a specific use case but I think you indirectly already covered this well in the README. However, it wouldn't hurt to be more allowing towards new examples in comparison to PRs towards actual functionality of Qt.py which needs to be thoroughly considered and discussed.

So this all looks good to me.
@hdd I'm all ears to hear what you have to say about all of this.

[mottosso]

I've read the README and I think it looks good, but I think it doesn't fully communicate what was being discussed in #101 which perhaps would be a good time to address;

Agreed. I've added "Development goals", with your two last points condensed into what I think is what we're trying to say. Let's add/remove to this list as our picture becomes clearer.

Perhaps in an EXAMPLE_USAGE.md or in its own folder examples containing gist-like examples.

How about actual gists? That way, the library would be in our README.

E.g.

• Coping with differences
• Testing cross-compatible code
• Catch error

It would on the other hand enable gists to change under our noses, and prevent anyone from contributing.

An examples/ directory isn't a bad idea.

[fredrikaverpil]

Looks great!

I think gists (although changing/disappearing) is a good idea but I think the /examples approach is even better. It'll be direct and to the point to ask contributors put their PRs into an "example" rather into an actual implementation - and not have to ask them to go and make a gist instead.