fix: rework ops.main type hints to allow different flavours (callable class)

[dimaqq]

Merge readiness check

• implementation
• tests
• docs
• re-export some symbols

Release readiness check

• full super-tox
• jhack PR or decision to re-export symbols + small PR
• Scenario 6 should just work, super-tox is happy
• Scenario 7 PR
• PR to one charm where lint step gets broken chore: reenable ops.main type hints hardware-observer-operator#298

Slated for ops==2.17.0

https://warthogs.atlassian.net/browse/CHARMTECH-232

[tonyandrewmeyer]

Looks good to me - a few minor queries/suggestions.

I did not review any of the code in _main.py other than main(), assuming that it was unchanged from main.py - if that's not the case and there are tweaks there too, could you please note that in the PR description and I'd want to re-review.

Speaking of the PR description: I assume it's because there are three competing solutions in different PRs, but it's currently empty: could you please fix that?

[dimaqq]

py:func reference target not found: ops.main [ref.func] I'm at a loss how to link to new top-level ops.main()

[tonyandrewmeyer]

py:func reference target not found: ops.main [ref.func] I'm at a loss how to link to new top-level ops.main()

Can you just put in a custom inline target and link to that instead? You'd lose the auto formatting, but at least it would be a link. Like:

def main(...):
    """_`ops.main()` is the thing you want to call."""

Charms should call ops.main()_ in order to handle the event.

[dimaqq]

[benhoyt]

Couple of nit comments, comment about re-exporting those few names in main.py, and question whether we need test_main_type_hint.py.

[benhoyt]

Docs look good though -- thanks!

[dimaqq]

I've decided to re-export the set of symbols that Scenario 6 uses specifically.

Rationale: many charms use Scenario and we shouldn't potentially break a whole bunch of charms if they pin dependencies asymmetrically (compatible ops, exact scenario); and to decouple Scenario 6 update from this PR in calendar time.

[james-garner-canonical]

I've given things a read through and it looks good to me, with the caveat that I'm still not familiar enough with the code base for that to signify a lot. I raised a couple of questions on test_main_type_hint.py just about the type checking tests.