feat: deprecate testing.Context.charm_spec

testing/pyproject.toml

@@ -23,6 +23,7 @@ keywords = ["juju", "test"]
 dependencies = [
     "ops==3.5.0.dev0",
     "PyYAML>=6.0.1",
+    "typing_extensions>=4.9.0",  # for `deprecated` decorator, replace with stdlib `warnings.deprecated` when we're Python 3.13+
 ]
 readme = "README.md"
 requires-python = ">=3.10"

testing/src/scenario/context.py

@@ -16,6 +16,8 @@
 from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any, Generic
 
+from typing_extensions import deprecated
+
 import ops
 from ops._private.harness import ActionFailed
 
@@ -695,15 +697,15 @@ def __init__(
                 config=config,
             )
 
-        self.charm_spec = spec
+        self._charm_spec = spec
         self.charm_root = charm_root
         self.juju_version = juju_version
         if juju_version.split('.')[0] == '2':
             logger.warning(
                 'Juju 2.x is closed and unsupported. You may encounter inconsistencies.',
             )
 
-        self.app_name = app_name or self.charm_spec.meta.get('name')
+        self.app_name = app_name or self._charm_spec.meta.get('name')
         self.unit_id = unit_id
         self._machine_id = machine_id
         self._availability_zone = availability_zone
@@ -736,6 +738,19 @@ def __init__(
 
         self.on = CharmEvents()
 
+    @property
+    @deprecated('Use State.from_context to generate a State from charm metadata.', stacklevel=2)
+    def charm_spec(self):
+        """Deprecated property for accessing the Context's charm specification.
+
+        The ``_CharmSpec`` class is private and intended for internal use only.
+        ``Context.charm_spec`` will be removed in a future major version.
+
+        Consider accessing the charm class or metadata directly, or using
+        :meth:`State.from_context` to generate a ``State`` from your charm's metadata.
+        """
+        return self._charm_spec
+
     def _set_output_state(self, output_state: State):
         """Hook for Runtime to set the output state."""
         self._output_state = output_state
@@ -853,7 +868,7 @@ def run(self, event: _Event, state: State) -> State:
     def _run(self, event: _Event, state: State):
         runtime = Runtime(
             app_name=self.app_name,
-            charm_spec=self.charm_spec,
+            charm_spec=self._charm_spec,
             juju_version=self.juju_version,
             charm_root=self.charm_root,
             unit_id=self.unit_id,

testing/src/scenario/state.py

@@ -1780,8 +1780,8 @@ def from_context(
         Items that are found in the metadata and are also in the passed
         arguments will be merged, with the passed values taking precedence.
         """
-        meta = ctx.charm_spec.meta
-        spec_config = ctx.charm_spec.config
+        meta = ctx._charm_spec.meta
+        spec_config = ctx._charm_spec.config
         config = {} if config is None else config
         if spec_config:
             options = spec_config.get('options', {})
@@ -1811,10 +1811,10 @@ def from_context(
                 continue
             storages.add(Storage(name=storage_name))
         stored_states = set(stored_states or ())
-        for attr in dir(ctx.charm_spec.charm_type):
-            value = getattr(ctx.charm_spec.charm_type, attr)
+        for attr in dir(ctx._charm_spec.charm_type):
+            value = getattr(ctx._charm_spec.charm_type, attr)
             if isinstance(value, ops.StoredState):
-                owner_path = ctx.charm_spec.charm_type.handle_kind
+                owner_path = ctx._charm_spec.charm_type.handle_kind
                 if any(ss.name == attr and ss.owner_path == owner_path for ss in stored_states):
                     continue
                 stored_states.add(StoredState(attr, owner_path=owner_path))

testing/tests/test_context.py

@@ -179,3 +179,9 @@ def _on_start(self, event):
     ctx = Context(GoodCharm, meta={'name': 'crashy'})
     ctx.run(ctx.on.start(), State())
     assert 'TEST_ENV_VAR' not in os.environ
+
+
+def test_charm_spec_is_deprecated():
+    ctx = Context(CharmBase, meta={'name': 'some-name'})
+    with pytest.warns(DeprecationWarning):
+        ctx.charm_spec  # type: ignore