feat: support for generating charmcraft YAML from Python classes

.gitignore

@@ -13,6 +13,7 @@ coverage.xml
 .coverage.data
 /.tox
 .*.swp
+.ruff_cache
 
 # Tokens and settings for `act` to run GHA locally
 .env
@@ -27,6 +28,9 @@ coverage.xml
 ops_scenario.egg-info
 /testing/build/
 /testing/dist/
+ops_tools.egg-info
+/tools/build/
+/tools/dist/
 
 # Smoke test artifacts
 *.tar.gz

.sbomber-manifest-sdist.yaml

@@ -35,3 +35,13 @@ artifacts:
         version: ''
         channel: 'stable'
         cycle: '25.10'
+
+  - name: 'ops-tools'
+    type: 'sdist'
+    version: ''
+    compression: 'gz'
+    ssdlc_params:
+        name: 'ops-tools'
+        version: ''
+        channel: 'stable'
+        cycle: '25.10'

.sbomber-manifest-wheel.yaml

@@ -31,3 +31,11 @@ artifacts:
         version: ''
         channel: 'stable'
         cycle: '25.10'
+
+  - name: 'ops-tools'
+    type: 'wheel'
+    ssdlc_params:
+        name: 'ops-tools'
+        version: ''
+        channel: 'stable'
+        cycle: '25.10'

HACKING.md

@@ -242,13 +242,13 @@ Then, check out the main branch of your forked operator repo and pull upstream t
 1. Draft a release: Run: `tox -e draft-release` at the root directory of the forked repo.
 
     > This assumes a draft release on the main branch, and your forked remote name is `origin`, and the `canonical/operator` remote name is `upstream`.
-    > 
+    >
     > If you have different settings, add parameters accordingly. For example, the following command assumes your forked remote name is `mine`, and `canonical/operator` remote name is `origin`:
-    > 
+    >
     > `tox -e draft-release -- --canonical-remote origin --fork-remote mine`
-    > 
+    >
     > By default, the script makes a release on the main branch. If you want to make a release on another branch, for example, on "2.23-maintenance" (you do not need to switch to this branch in your forked repo), run it with the "--branch" parameter:
-    > 
+    >
     > `tox -e draft-release -- --branch 2.23-maintenance`
 
 2. Follow the steps of the `tox -e draft-release` output. You need to input the release title and an introduction section, which can be multiple paragraphs with empty lines in between. End the introduction section by typing a period sign (.) in a new line, then press enter.
@@ -258,11 +258,12 @@ Then, check out the main branch of your forked operator repo and pull upstream t
     > You can troubleshoot errors on the [Actions Tab](https://github.com/canonical/operator/actions).
 
     > Pushing the tags will trigger automatic builds for the Python packages and
-    > publish them to PyPI ([ops](https://pypi.org/project/ops/) 
-    > ,[ops-scenario](https://pypi.org/project/ops-scenario), and 
-    > [ops-tracing](https://pypi.org/project/ops-tracing/)).
+    > publish them to PyPI ([ops](https://pypi.org/project/ops/)
+    > ,[ops-scenario](https://pypi.org/project/ops-scenario),
+    > [ops-tracing](https://pypi.org/project/ops-tracing/)), and
+    > [ops-tools](https://pypi.org/project/ops-tools/)).
     > Note that it sometimes take a bit of time for the new releases to show up.
-    > 
+    >
     > See [.github/workflows/publish.yaml](.github/workflows/publish.yaml) for details.
     >
     > You can troubleshoot errors on the [Actions Tab](https://github.com/canonical/operator/actions).
@@ -273,7 +274,7 @@ Then, check out the main branch of your forked operator repo and pull upstream t
 7. Post release: At the root directory of your forked `canonical/operator` repo, check out to the main branch to ensure the release automation script is up-to-date, then run: `tox -e post-release`.
 
     > This assumes the same defaults as mentioned in step 1.
-    > 
+    >
     > Add parameters accordingly if your setup differs, for example, if you are releasing from a maintenance branch.
 
 8. Follow the steps of the `tox -e post-release` output. If it succeeds, a PR named "chore: adjust versions after release" will be created. Get it reviewed and merged.

docs/reference/index.md

@@ -10,5 +10,5 @@ pebble
 ops-testing
 ops-testing-harness
 ops-tracing
+ops-tools
 ```
-

docs/reference/ops-tools.rst

@@ -0,0 +1,7 @@
+.. _ops_tools:
+
+`ops_tools`
+===========
+
+.. automodule:: ops_tools
+   :exclude-members: main

pyproject.toml

@@ -45,6 +45,7 @@ lint = [
 ]
 docs = [
     "ops[testing,tracing]",
+    "ops-tools",
     "canonical-sphinx[full]",
     "packaging",
     "sphinxcontrib-svg2pdfconverter[CairoSVG]",
@@ -53,6 +54,7 @@ docs = [
 ]
 unit = [
     "ops[testing,tracing]",
+    "ops-tools",
     "pytest~=8.4",
     "jsonpatch~=1.33",
     "pydantic~=2.10",
@@ -92,12 +94,13 @@ requires = [
 build-backend = "setuptools.build_meta"
 
 [tool.uv.workspace]
-members = ["tracing", "testing"]
+members = ["tracing", "testing", "tools"]
 
 [tool.uv.sources]
 ops = { workspace = true }
 ops-scenario = { workspace = true }
 ops-tracing = { workspace = true }
+ops-tools = { workspace = true }
 
 [tool.setuptools.packages.find]
 include = ["ops", "ops._private", "ops.lib"]
@@ -273,6 +276,10 @@ exclude = ["tracing/ops_tracing/vendor/*"]
     "RUF015",  # Prefer `next` over single element slice
     "SIM115",  # Use a context manager for opening files
 ]
+"tools/tests_tools/*" = [
+    # All documentation linting.
+    "D",
+]
 "ops/_private/timeconv.py" = [
     "RUF001",  # String contains ambiguous `µ` (MICRO SIGN). Did you mean `μ` (GREEK SMALL LETTER MU)?
     "RUF002",  # Docstring contains ambiguous `µ` (MICRO SIGN). Did you mean `μ` (GREEK SMALL LETTER MU)?
@@ -300,9 +307,9 @@ convention = "google"
 builtins-ignorelist = ["id", "min", "map", "range", "type", "TimeoutError", "ConnectionError", "Warning", "input", "format"]
 
 [tool.pyright]
-include = ["ops/*.py", "ops/_private/*.py", "test/*.py", "test/charms/*/src/*.py", "testing/src/*.py"]
+include = ["ops/*.py", "ops/_private/*.py", "test/*.py", "test/charms/*/src/*.py", "testing/src/*.py", "tools/src/*.py", "tools/tests_tools/*.py"]
 exclude = ["tracing/*"]
-extraPaths = ["testing", "tracing"]
+extraPaths = ["testing", "tracing", "tools"]
 pythonVersion = "3.10" # check no python > 3.10 features are used
 pythonPlatform = "All"
 typeCheckingMode = "strict"

release.py

@@ -49,6 +49,7 @@
     'ops/src': pathlib.Path('ops/version.py'),
     'ops/pyproject': pathlib.Path('pyproject.toml'),
     'testing': pathlib.Path('testing/pyproject.toml'),
+    'tools': pathlib.Path('tools/pyproject.toml'),
     'tracing': pathlib.Path('tracing/pyproject.toml'),
     'uvlock': pathlib.Path('uv.lock'),
 }
@@ -386,6 +387,13 @@ def update_tracing_version(ops_version: str):
     update_pyproject_versions(VERSION_FILES['tracing'], ops_version, deps={'ops': ops_version})
 
 
+def update_tools_version(ops_version: str):
+    """Update the tools pyproject version."""
+    major, rest = ops_version.split('.', 1)
+    tools_version = f'{int(major) - 2}.{rest}'
+    update_pyproject_versions(VERSION_FILES['tools'], tools_version, deps={})
+
+
 def update_uv_lock():
     """Update the uv.lock file with the new versions."""
     subprocess.run(['uv', 'lock'], check=True)  # noqa: S607
@@ -421,6 +429,7 @@ def update_versions_for_release(tag: str):
     update_ops_version(tag, scenario_version)
     update_testing_version(tag, scenario_version)
     update_tracing_version(tag)
+    update_tools_version(tag)
     update_uv_lock()
 
 
@@ -464,6 +473,7 @@ def update_versions_for_post_release(repo: github.Repository.Repository, branch_
     update_ops_version(ops_version, scenario_version)
     update_testing_version(ops_version, scenario_version)
     update_tracing_version(ops_version)
+    update_tools_version(ops_version)
     update_uv_lock()
 
 

test/charms/test_main/src/charm.py

@@ -32,6 +32,7 @@
 # during unit tests, and test_main failures that subprocess out are often
 # difficult to debug. Uncomment this line to get more informative errors when
 # running the tests.
+# When uncommented the test_hook_and_dispatch_with_failing_hook test will fail.
 # logger.addHandler(logging.StreamHandler(sys.stderr))
 
 

testing/src/scenario/state.py

@@ -1975,6 +1975,10 @@ def autoload(charm_type: type[CharmBase]) -> _CharmSpec[CharmType]:
             # try to load using legacy metadata.yaml/actions.yaml/config.yaml files
             meta, config, actions = _CharmSpec._load_metadata_legacy(charm_root)
 
+        # TODO: ideally, we would look for ConfigBase classes in the charm
+        # module and autoload from there at this point. Leaving this until the
+        # conversation about if & how the generation is done is resolved.
+
         if not meta:
             # still no metadata? bug out
             raise MetadataNotFoundError(

testing/tests/test_e2e/test_actions.py

@@ -1,5 +1,8 @@
 from __future__ import annotations
 
+import dataclasses
+
+import ops_tools
 import pytest
 from ops import __version__ as ops_version
 from ops.charm import ActionEvent, CharmBase
@@ -203,3 +206,27 @@ def test_default_arguments():
     assert action.name == name
     assert action.params == {}
     assert action.id == expected_id
+
+
+def test_action_using_generated_action():
+    @dataclasses.dataclass
+    class Act:
+        a: int
+        b: float
+        c: str
+
+    class Charm(CharmBase):
+        def __init__(self, framework: Framework):
+            super().__init__(framework)
+            framework.observe(self.on['act'].action, self._on_action)
+
+        def _on_action(self, event: ActionEvent):
+            self.typed_params = event.load_params(Act, 10, c='foo')
+
+    schema = ops_tools.action_to_juju_schema(Act)
+    ctx = Context(Charm, meta={'name': 'foo'}, actions=schema)
+    with ctx(ctx.on.action('act', params={'b': 3.14}), State()) as mgr:
+        mgr.run()
+        assert mgr.charm.typed_params.a == 10
+        assert mgr.charm.typed_params.b == 3.14
+        assert mgr.charm.typed_params.c == 'foo'

testing/tests/test_e2e/test_config.py

@@ -1,20 +1,24 @@
 from __future__ import annotations
 
+import dataclasses
+
 import pytest
-from ops.charm import CharmBase
-from ops.framework import Framework
 
+import ops
+import ops_tools
+
+from scenario.context import Context
 from scenario.state import State
 from ..helpers import trigger
 
 
 @pytest.fixture(scope='function')
 def mycharm():
-    class MyCharm(CharmBase):
-        def __init__(self, framework: Framework):
+    class MyCharm(ops.CharmBase):
+        def __init__(self, framework: ops.Framework):
             super().__init__(framework)
             for evt in self.on.events().values():
-                self.framework.observe(evt, self._on_event)
+                framework.observe(evt, self._on_event)
 
         def _on_event(self, event):
             pass
@@ -23,7 +27,7 @@ def _on_event(self, event):
 
 
 def test_config_get(mycharm):
-    def check_cfg(charm: CharmBase):
+    def check_cfg(charm: ops.CharmBase):
         assert charm.config['foo'] == 'bar'
         assert charm.config['baz'] == 1
 
@@ -40,7 +44,7 @@ def check_cfg(charm: CharmBase):
 
 
 def test_config_get_default_from_meta(mycharm):
-    def check_cfg(charm: CharmBase):
+    def check_cfg(charm: ops.CharmBase):
         assert charm.config['foo'] == 'bar'
         assert charm.config['baz'] == 2
         assert charm.config['qux'] is False
@@ -72,11 +76,11 @@ def check_cfg(charm: CharmBase):
     ),
 )
 def test_config_in_not_mutated(mycharm, cfg_in):
-    class MyCharm(CharmBase):
-        def __init__(self, framework: Framework):
+    class MyCharm(ops.CharmBase):
+        def __init__(self, framework: ops.Framework):
             super().__init__(framework)
             for evt in self.on.events().values():
-                self.framework.observe(evt, self._on_event)
+                framework.observe(evt, self._on_event)
 
         def _on_event(self, event):
             # access the config to trigger a config-get
@@ -101,3 +105,27 @@ def _on_event(self, event):
     )
     # check config was not mutated by scenario
     assert state_out.config == cfg_in
+
+
+def test_config_using_generated_config():
+    @dataclasses.dataclass
+    class Config:
+        a: int
+        b: float
+        c: str
+
+    class Charm(ops.CharmBase):
+        def __init__(self, framework: ops.Framework):
+            super().__init__(framework)
+            framework.observe(self.on.config_changed, self._on_config_changed)
+
+        def _on_config_changed(self, event: ops.ConfigChangedEvent):
+            self.typed_config = self.load_config(Config, 10, c='foo')
+
+    schema = ops_tools.config_to_juju_schema(Config)
+    ctx = Context(Charm, meta={'name': 'foo'}, config=schema)
+    with ctx(ctx.on.config_changed(), State(config={'b': 3.14})) as mgr:
+        mgr.run()
+        assert mgr.charm.typed_config.a == 10
+        assert mgr.charm.typed_config.b == 3.14
+        assert mgr.charm.typed_config.c == 'foo'