feat: support for generating charmcraft YAML from Python classes

.gitignore

@@ -13,6 +13,7 @@ coverage.xml
 .coverage.data
 /.tox
 .*.swp
+.ruff_cache
 .claude/settings.local.json
 
 # Tokens and settings for `act` to run GHA locally
@@ -28,6 +29,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

@@ -32,3 +32,14 @@ artifacts:
         name: 'ops-tracing'
         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

@@ -28,3 +28,12 @@ artifacts:
         name: 'ops-tracing'
         version: ''
         channel: 'stable'
+        cycle: '25.10'
+
+  - name: 'ops-tools'
+    type: 'wheel'
+    ssdlc_params:
+        name: 'ops-tools'
+        version: ''
+        channel: 'stable'
+        cycle: '25.10'

HACKING.md

@@ -318,8 +318,9 @@ Then, check out the main branch of your forked operator repo and pull upstream t
 
     > 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/)).
+    > ,[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.

docs/reference/index.md

@@ -43,6 +43,7 @@ An API for tracing charm code and sending data to sources such as the [Canonical
 :maxdepth: 1
 
 ops-tracing
+ops-tools
 ```
 
 ## Hook commands

docs/reference/ops-tools.rst

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

pyproject.toml

@@ -43,8 +43,18 @@ lint = [
     "pyright~=1.1",
     "typing_extensions~=4.2",
 ]
+docs = [
+    "ops[testing,tracing]",
+    "ops-tools",
+    "canonical-sphinx[full]",
+    "packaging",
+    "sphinxcontrib-svg2pdfconverter[CairoSVG]",
+    "sphinx-last-updated-by-git",
+    "sphinx-sitemap~=2.8",
+]
 unit = [
     "ops[testing,tracing]",
+    "ops-tools",
     "pytest~=8.4",
     "jsonpatch~=1.33",
     "pydantic~=2.10",
@@ -86,12 +96,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"]
@@ -227,6 +238,10 @@ exclude = ["tracing/ops_tracing/vendor/*"]
     # All documentation linting.
     "D",
 ]
+"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)?
@@ -254,9 +269,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

@@ -50,6 +50,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'),
     'versions_doc': pathlib.Path('docs/explanation/versions.md'),
@@ -380,6 +381,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_versions_doc(version: str):
     """Update the Ops version table in docs/explanation/versions.md.
 
@@ -463,6 +471,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_versions_doc(tag)
     update_uv_lock()
 
@@ -503,6 +512,7 @@ def update_versions_for_post_release(branch_name: str):
     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/tests/test_e2e/test_actions.py

@@ -3,6 +3,9 @@
 
 from __future__ import annotations
 
+import dataclasses
+
+import ops_tools
 import pytest
 from scenario import Context
 from scenario.state import State, _Action, _next_action_id
@@ -223,3 +226,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

@@ -3,22 +3,25 @@
 
 from __future__ import annotations
 
+import dataclasses
+
+import ops_tools
 import pytest
+from scenario.context import Context
 from scenario.state import State
 
-from ops.charm import CharmBase
-from ops.framework import Framework
+import ops
 
 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
@@ -27,7 +30,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
 
@@ -44,7 +47,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
@@ -76,11 +79,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
@@ -105,3 +108,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'