3.8.0: socket path in Pebble tracing spans

This release adds a pebble.socket_path attribute to tracing spans. The attribute is useful for distinguishing spans where multiple Pebble daemons are used. We've also included several fixes and documentation improvements.

What's Changed

Features

• Note the socket path in Pebble tracing spans in #2555

Fixes

• Treat remote unit zero as explicit in #2454
• Ensure resources are cleaned up in testing.Context in #2506
• Close SQLite storage in Harness.cleanup() in #2507
• Restore sys.breakpointhook on _Manager teardown in #2542
• Avoid errors in finalisation due to already-closed websocket in #2548
• Use the correct value for JUJU_HOOK_NAME when objects contain dashes in #2552
• Avoid double-closing the framework in testing teardown in #2561
• Don't leak exec I/O threads when waiting on the change fails in #2558
• Take Pebble defaults into consideration when consistency checking Checks in #2567
• Tear down Runtime.exec() when the charm raises in #2581

Documentation

• Fix small issues in K8s tutorial in #2540
• Document user-secret observer lifecycle and secret-changed semantics in #2522
• Replace CoC with link to Ubuntu Code of Conduct in #2564
• Add a small note about -W error in the unit test how-to in #2560
• Add doc about subordinate charms in #2455
• Add 26.04 to the versions page and mark 2.23 as LTS in #2517
• Clarify storage-detaching applies to both machine and K8s charms in #2554
• Add guidance about names of workload-less charms in #2496
• Fix first unit tests command in machine charm tutorial in #2574
• Extend security explanation page to cover SEC0030 V1.3 gaps in #2571
• Move docs to canonical.com/juju/docs/ops in #2545
• Fix docstring of _Event._is_action_event in #2580

Tests

• Treat warnings as errors when running unit tests in #2541
• Fix mock_temp_dir fixture's open() patch in #2553
• Add integration tests for ops.hookcmds in #2520, #2562
• Fix integration test flakes on Juju 3 k8s and Juju 4 secrets in #2584

Refactoring

• Avoid yaml.load() to silence security scanner false positives in #2523
• Replace jsonpatch with an inline dict-diff in #2578
• Move the otlp-json package to be a regular ops-tracing module in #2585
• Distinguish between init and attribute types in testing state classes in #2331

CI

• Remove obsolete containerd workaround from integration workflow in #2519
• Use the sys.monitoring coverage core in #2518

Full Changelog: 3.7.1...3.8.0

3.7.1: fixes and documentation improvements

This patch release contains one fix and multiple documentation improvements.

The fix involves passing the endpoint name from a Relation down to the actual hook command, where Juju will use it to validate that it matches the provided relation ID.

We have added new how-to guides on initialising and publishing a charm. We also upgraded our docs to the latest Sphinx Stack 2.0.

What's Changed

Fixes

• Pass the endpoint name through to relation-get in #2499

Documentation

• Add a how-to guide focused on debugging charms in #2386
• Add metadata descriptions to the debug and public listing how-to guides in #2415
• Update tutorials and how-tos to use pytest-jubilant in #2406
• Add how-to guide about CI in #2405
• Test COS Lite integration with the k8s-5-observe charm in #2411
• Update tutorials and example charms to match Charmcraft 4.2 in #2407
• Update api_demo_server version to support non-amd64 architectures in #2448
• Pin to 24.04 when launching VMs in #2457
• Explain how to remove errored apps in k8s tutorial in #2445
• Align example charms with pre-release Charmcraft in #2444
• Add how-to guide for naming and initialising a charm in #2449
• Add a how-to guide about publishing a charm in #2420
• In the tutorials, recommend initing from GitHub in #2459
• Fix integration tests of K8s tutorial charms in #2471
• Replace the PGP key with the upstream page in SECURITY.md in #2474
• Bump api_demo_server to 1.0.4 in docs and example charms in #2473
• Refresh the machine workloads how-to in #2443
• Add COS Lite integration tests to K8s tutorial in #2478
• Add git workflow guidance for contributors in #2453
• Update profile guidance in HACKING.md in #2486
• Explain how to add an icon to a charm in #2451
• Adopt latest Charmcraft profiles, incl juju_setup marker on integration tests in #2497
• Improve support for agents, with Sphinx Stack upgrade in #2495
• Improve how-to about managing files in containers in #2470
• Improve Container.pull docs to avoid leaky files in #2508
• Clarify Secret manage-permission error in testing.State in #2510

Tests

• Extend the type checking of the ops-scenario tests in #2234, #2235
• Wait on ExecProcess after expected TypeError in #2509

CI

• Drop external action for checking PR title format in #2388
• Add a dependabot cooldown in #2413
• Sort the directory entries when updating the best practices list in #2422
• Configure dependabot for the example charms in #2426
• Pin zizmor and TIOBE tool versions in pyproject.toml rather than the workflow in #2437
• Add 26.04 to smoke tests and remove outdated metadata.yaml in #2450
• Use charmcraft test for example charm in #2440
• Add workflow_dispatch trigger to workflows where it is useful in #2468
• Ensure the correct job is selected in updating charm pins in #2500

Full Changelog: 3.7.0...3.7.1

3.7.0: ops.testing usability improvements

This release brings usability improvement in state transition testing: charmcraft extensions are now expanded, which means easier testing of 12-factor charms; breakpoint is supported; .get_relation can be called with a relation object; a single argument to Context can be used for metadata, actions and config declarations. Additionally, there are fixes for the run-time: secret expiration time zone, typing: StorageMeta.properties and state transition testing: mypy support, cleaner ownership for state data and a warning when unit test potentially relies on container data.

What's Changed

Features

• Enable interactive debugging via breakpoint in testing in #2363
• ops.testing autoload support for charmcraft extensions in #2367
• Allow testing.State.get_relation to accept relation objects in #2359
• Support charmcraft.yaml format as meta for testing.Context in #2296

Fixes

• Correct type annotation for StorageMeta.properties in #2348
• Move the testing.Container compatibility import so that mypy style checkers understand it in #2343
• Hold only copies of user provided meta/config/actions in testing.Context in #2349
• Deep-copy layer objects during testing.State plan rendering in #2380
• Return copies from testing.State secret_get and action_get in #2379
• Use timezone-aware datetimes in expiry calculation in #2378
• Warn before clearing non-empty container in testing in #2365

Documentation

• Replace links to juju.is by canonical.com/juju in #2368
• Refactor homepage to better put Ops in context in #2370
• Add pytest-operator migration guide from Jubilant docs in #2381
• Add a tip about AI help in the Jubilant migration guide in #2382
• Mention jhack scenario snapshot in #2351
• Update integration testing how-to guide in #2390
• Explain K8s charms briefly at the start of the tutorial in #2392
• Juju secrets identifier is now an opaque string in #2387

Tests

• Extend the type checking of the ops-scenario tests in #2230

CI

• Run ruff check --fix in tox -e format in #2369
• Check example charms with mypy in CI in #2360
• Update the list of published charms in the compatibility tests in #2384
• Adjust minimum Python version in broad charm compatibility tests in #2317

Full Changelog: 3.6.0...3.7.0

3.6.0: Use Juju 3.6.14 as the default version in ops.testing

In this release, the ops.testing Context sets the mock Juju version to 3.6.14 (you can customise this if needed).

If you're using Pebble's exec to run commands in containers, and the exec failed (with a timeout, for example), the exception would previously include the entire command that was attempted; it now only includes the first item, to protect against sensitive data leaking into exceptions. However, we strongly recommend against passing sensitive data in the command line - use other methods (such as environment variables) whenever possible.

If you'd like to use Pydantic's experimental MISSING sentinel, that will now work with Relation.save (ops will consider a value of MISSING to mean "delete from Juju").

What's Changed

Features

• Bump default Juju version in ops.testing.Context to 3.6.14 in #2316

Fixes

• Correct the Model.get_binding() return type in #2329
• Only show executable in ExecError.__str__, not full command line in #2336
• Support Pydantic MISSING sentinel in ops.Relation.save in #2306

Documentation

• Add how-to subcategory for managing containers in #2309
• Remove 2.19 version in docs, tweak ops.testing title in #2332
• Use "true" and "false" consistently in the reference documentation in #2330
• Add CLI args as another place to not put sensitive data in #2334
• Fix remote unit kwarg in testing example in #2342
• Clarify that secret labels are not names in #2337

Tests

• Set SCENARIO_BARE_CHARM_ERRORS=true in Ops tests that care in #2314

CI

• Fix releasing on branches with no versions.md doc in #2323

Full Changelog: 3.5.2...3.6.0

3.5.2: fixes for testing package build and more

This release is prompted by a fix to recent build failures for ops[testing]. The release also includes a couple of minor fixes for the testing framework itself: making the level argument of testing.CheckInfo type checking compatible with pebble.CheckInfo.level, and baking in the knowledge that credential-get is available on K8s in newer Juju versions.

What's Changed

Fixes

• Make testing.CheckInfo level arg type match pebble.CheckInfo.level in #2274
• Make testing consistency check aware that credential-get is available on k8s in newer Juju in #2307
• Drop unused setuptools_scm build dependency in #2310

Documentation

• Update Pebble version in Juju 3.6 in #2295
• Refresh K8s tutorial to use Concierge and uv-based Charmcraft profile in #2285
• Add missing "How to" in page titles in #2289
• Fix and improve observability part of K8s tutorial in #2305

Full Changelog: 3.5.1...3.5.2

2.23.2: fix testing package build

What's Changed

This release fixes a recent build failure for ops[testing].

Fixes

• Drop unused setuptools_scm build dependency in #2318

Documentation

• For 2.23, update links and config for switch to documentation.ubuntu.com/ops in #1942
• For 2.x, fix site title and unstyled error pages in #1945
• For 2.x, remove .html extensions in #1954
• For 2.x, fix unstyled error pages in #1973

Full Changelog: 2.23.1...2.23.2

3.5.1: fixes and documentation improvements

This is a maintenance release that includes work on Ops internals and documentation.

What's Changed

Fixes

• Use parse_rfc3339 for datetime parsing to support Juju 4 in #2264
• Correct the value of additional_properties in the action meta in Juju 4 in #2250
• Prevent KeyError on auth-type when creating CloudCredential object in #2268
• _checks_action should return empty list when there are no changes in #2270

Documentation

• Provide examples in unit testing how-to, and other small improvements in #2251
• Update the action how-to to explain the additionalProperties default flip in #2249
• For state-transition tests, clarify about immutability and reusing state in #2153
• Fix and clarify holistic example of handling storage in #2098
• Remove comments from K8s tutorial and clarify about persisting data in #2253
• Clarify handling of postgres relation data in K8s tutorial in #2256
• Improve unit tests of httpbin demo charm in #2254
• Add version information for tools in the charming ecosystem in #2231
• Avoid emojis that render differently across platforms in #2273
• Secrets over CMR comment added in #2271
• Fix charm name in httpbin deploy command in #2276
• Updated security@ubuntu.com PGP key in #2286

Tests

• Remove unnecessary test module in #2247

CI

• Replace git reference injection with wheel artifacts in charm test workflows in #2252
• Explicitly provide the charmcraft repo location in CI in #2277
• Remove outdated custom signature generation in #2280

Full Changelog: 3.5.0...3.5.1

3.5.0: env var to control extension wrapping in testing

This is a small release with some user-facing changes to ops.testing.

We've added an environment variable to disable the use of UncaughtCharmError in testing. By default, exceptions raised from charm code are wrapped in an UncaughtCharmError in state-transition tests. This makes debugging harder and adds extra steps to making assertions about expected errors in tests. Set SCENARIO_BARE_CHARM_ERRORS=true to have exceptions be propagated to your test code as-is instead. This may become the default behaviour in a future major ops release. You can lock in the current default behaviour explicitly by setting SCENARIO_BARE_CHARM_ERRORS=false in your test runners.

Additionally, the ops.testing.Context.charm_spec attribute is now deprecated -- this is intended for internal use only, and was not widely used, so the warning should steer new users in the right direction.

What's Changed

Features

• Env var to control exception wrapping in tests in #2142
• Deprecate testing.Context.charm_spec in #2219

Documentation

• Fix charmcraft init command in #2210
• Update CI examples to use uv and tox-uv in #2213
• Update and clarify info about environment prep in #2217
• Match Charmcraft profiles in tox.ini example for integration testing in #2221
• Use base 24.04 for httpbin-demo charm in #2222
• Clarify parts of the machine charm tutorial in #2223
• Match Charmcraft profiles in "Write and structure charm code" in #2220
• Use cosl binary in K8s tutorial charm to work around error in #2232
• Fix URL issues by updating doc starter pack in #2238

Tests

• Don't skip tests if ops[testing] isn't installed in #2215
• Switch the integration test charms to use the uv plugin in #2218

CI

• Avoid jitter in the best practice doc PRs in #2193
• Ignore PERF401 (manual list comprehension) across the repo in #2201
• The git commands need to be run in the operator directory as well in #2197
• Have cycle in the sbomber manifests use the default value in #2209
• Add pytest.warns to note an expected warning in #2092
• Update release script to handle non-final versions in #2199
• Add ops-tracing as a dependency for the observability tests in #2239
• Add scheduled workflow for packing and integration testing example charms in #2233

Full Changelog: 3.4.0...3.5.0

3.4.0: a low-level API for the Juju hook commands

The main feature in this release is the introduction of ops.hookcmds, which provides an API to the Juju hook commands. The API is low-level, complete (other than deprecated commands), and generally a 1-1 mapping to the hook commands, but providing a Pythonic interface.

Additionally, the length of the defer queue is now logged; more arguments can be passed as paths to ops.Container and ops.PebbleClient methods; and state transition testing Context has gained optional availability zone and principal unit arguments.

What's Changed

Breaking Changes

There are breaking changes in this release. Please review them carefully:

• Fix: Change JujuContext.machine_id from int to str in #2108
  • Note that this fix was already included in Ops 3.3.1
  • If you use this field, you may need to adjust type hints in your code
• Fix: Ensure that the testing context manager is exited when an exception occurs in #2117
  • If you use ops.testing.Context as a context manager and expect the charm to raise an exception, you need to adjust the expected exception type.

Features

• Add a low-level API for the Juju hook commands in #2019
• Make PebbleClient file methods also accept pathlib.PurePath in #2097
• Log the total number of deferred events in #2161
• Allow setting the Juju availability zone and principal unit in the testing Context in #2187

Fixes

• Allow actions without params or descriptions in ops[testing] in #2090
• Ensure ops.Pebble.pull cleans up temporary files if it errors in #2087
• Make secret info description visible to the charm in ops[testing] in #2115
• Raise ActionFailed when using Context as a context manager in #2121
• Detect categories with an explanation mark indicating breaking changes in #2132
• Normalise Secret.owner to 'app' for ops[testing] output state in #2127
• Don't cache secret metadata in Ops in #2143
• Secret-info-get cannot be provided with both an ID and a label in #2170
• Minor hookcmds fixes in #2175

Documentation

• Update referenced examples for managing interfaces in #2068
• Tidy up spelling and formatting in several places in #2060
• Add missing assignment to state_out in unit tests how-to in #2075
• Update the holistic/delta explanation with the reconciler pattern in #2029
• Fix broken setup/teardown links in README in #2094
• Update info about release docs, mark testing changelog as not maintained in #2074
• Switch to makefile for building the docs in #2073
• Document how to extract the charm instance from the testing context in #2084
• Add a how-to guide for migrating away from Harness in #2062
• Rename hook tools to hook commands in #2114
• Remove legacy how-to guide for Harness in #2122
• Update the Juju release the metrics functionality is removed from 4.0 to 3.6.11 in #2126
• Clarify that Context is the testing context not only the Juju context in #2123
• Explain the Charmhub public listing process and add a reference list of best practices in #1989
• Expand next steps for K8s tutorial in #2034
• Remove mention of the simple Charmcraft profile in #2138
• Expand landing pages with summaries of pages in #2140
• Update environment setup for integration tests and K8s tutorial in #2124
• Replace machine charm tutorial by an improved tutorial in #2119
• Change HACKING.md instructions for maintaining Charmcraft profiles in #2151
• In integration tests, use consistent approach to logging and packing in #2150
• In integration testing how-to, clarify that Juju model is destroyed after module all tests in the module complete in #2154
• Remove Charmcraft channel specifier from machine charm tutorial in #2148
• Add AI contribution note and style guideline for type annotation of return values in #2168
• Add ops[testing] to the ops.testing docstring in #2171
• Add links to the Juju hook from each event class in #2176
• Add a short umask note in #2184

Tests

• Re-enable testing consistency checks after disabling them in #2141
• Expand secrets integration and state transition tests in #2130

Refactoring

• Use ops.hookcmds in _ModelBackend in #2116
• Don't get the storage details from --help in #2172
• Drop 3.8 and 3.9 compatibility code in #2173
• Use json.dumps to produce the YAML in relation-set and state-set in #2174
• Rely on type annotations instead of casts in hookcmds in #2179

CI

• Add integration and state transition tests for the secrets API in #2078
• Temporarily disable tracing integration tests in #2102
• Add secrets tests follow-up in #2105
• Support monorepos in ops charm compatibility testing in #2100
• Test both Charmcraft 3 and Charmcraft 4 profiles in #2103
• Add automated doc checks (and related starter pack updates) in #2099
• Clean up accidental workflow trigger in #2144
• Test if package versions match dependency versions before publishing in #2139
• Update spelling in #2167
• Test against 4.0/stable in #2186
• Store charmcraft logs if smoke tests fail in #2192
• Use Juju channel 4/stable in Ops smoke tests in #2190

Full Changelog: 3.3.0...3.4.0

3.4.0b3 Fix dependency version in testing extra

3.4.0b2 was not released to PyPI, as there was an error in the testing optional extra. This release is otherwise identical to 3.4.0b2.