feat: deprecate testing.Context.charm_spec

[james-garner-canonical]

This PR deprecates accessing testing.Context.charm_spec, because the _CharmSpec type is private, and was never intended to be exposed publicly.

I suggest we open PRs for the two known users of this attribute before the next release, or even before merging this PR, per @tonyandrewmeyer's research and suggested fixes:

• grafana-agent-operator - this is using charm_spec to get the charm Class and adjust a private attribute on it. I would have thought the test could just import the charm class and do it directly - the charm_type isn't a copy, it's the same class object.
• charmcraft (!) - I guess this is a legitimate use (so perhaps we shouldn't deprecate and maybe should document), pulling the container name from the metadata rather than hard-coding it in the test. The metadata isn't available elsewhere (you can get it from the model, but not until you've already called run). However, from_context() would do this for you in a nicer way, so maybe the right thing is to encourage that. (The test is using scenario as the namespace, so maybe it's quite old?).

Resolves #2131

---

Requesting review from @benhoyt, since his instinct was to avoid deprecation noise and publicly document this instead; and from @tonyandrewmeyer since he's the most familiar with this and what charms should be using instead.

[tonyandrewmeyer]

CharmSpec has:

• the charm class - I feel like you should know what this is in your tests and just use it directly rather than via this object
• the meta dict, which is roughly metadata.yaml
• the actions dict, which is roughly actions.yaml
• the config dict, which is roughly config.yml
• an autoloaded Boolean - I feel this is definitely for internal use, and not something you'd use directly in tests.
• a helper to get all the relations - it seems like no-one is using this, and it does seem like something that would make more sense exposed in a different way (as a general helper function or on the Context object) if people did want it

For the metadata, it seems like a meta property on Context that returned an ops.CharmMeta would be a cleaner way to provide this rather than the raw dictionaries. In my earlier (very quick) research it did seem like only charmcraft was actually using this. It does seem reasonable to want this information, but it also seems like in a lot of tests it'd be hard-coded and that isn't really an issue (and using from_context() is an alternative).

So I'm +0 on deprecating (and also opening a PR for grafana-agent-operator - maybe also charmcraft, although I think it's pinned to an old ops-scenario version, so there might be a need for a larger PR that modernises other things).

I'm interested in @PietroPasotti's take here too. Essentially: do you think we should document Context.charm_spec or deprecate it?

[tonyandrewmeyer]

Assuming that we do deprecate, the code change looks good to me.

I think we should add a test that validates that there's a warning (pytest.warns) if you access .charm_spec. We probably don't need other tests, assuming that none of them are using .charm_spec directly (if so, we should pytest.warns there to silence the warning, but also see if that's actually a use-case).

[james-garner-canonical]

I've opened PRs to migrate the two users off Context.charm_spec.

• test: refactor e2e unit tests to avoid ops.testing.Context.charm_spec grafana-agent-operator#355
• test: refactor init-extensions tests to avoid using ops.testing.Context.charm_spec charmcraft#2527

I'll update this PR to use @warnings.deprecated and to mention alternatives in the docstring before requesting further review.

[james-garner-canonical]

warnings.deprecated is Python 3.13+. Luckily, typing_extensions has backported it, and type checkers respect the backport. This introduces a testing-only runtime dependency on typing_extensions (currently it's type checking only in ops), which I think is OK.

[james-garner-canonical]

Turns out it needs to be typing_extensions.deprecated instead since warnings.deprecated is Python 3.13+. I've added a test to assert the warning is raised at runtime. The docstring and warning show up nicely in the IDE -- in VS Code, ctx.charm_spec is highlighted as an error, and the hover contents show:

[tonyandrewmeyer]

Nice, thanks!