ops 3.5.2__tar.gz → 3.7.0__tar.gz

{ops-3.5.2 → ops-3.7.0}/CHANGES.md

@@ -1,3 +1,73 @@
+# 3.7.0 - 30 March 2026
+
+## Features
+
+* Enable interactive debugging via `breakpoint` in testing (#2363)
+* ops.testing autoload support for charmcraft extensions (#2367)
+* Allow testing.State.get_relation to accept relation objects (#2359)
+* Support charmcraft.yaml format as meta for testing.Context (#2296)
+
+## Fixes
+
+* Correct type annotation for StorageMeta.properties (#2348)
+* Move the testing.Container compatibility import so that mypy style checkers understand it (#2343)
+* Hold only copies of user provided meta/config/actions in testing.Context (#2349)
+* Deep-copy layer objects during testing.State plan rendering (#2380)
+* Return copies from testing.State secret_get and action_get (#2379)
+* Use timezone-aware datetimes in expiry calculation (#2378)
+* Warn before clearing non-empty container in testing (#2365)
+
+## Documentation
+
+* Replace links to juju.is by canonical.com/juju (#2368)
+* Refactor homepage to better put Ops in context (#2370)
+* Add pytest-operator migration guide from Jubilant docs (#2381)
+* Add a tip about AI help in the Jubilant migration guide (#2382)
+* Mention jhack scenario snapshot (#2351)
+* Update integration testing how-to guide (#2390)
+* Explain K8s charms briefly at the start of the tutorial (#2392)
+* Juju secrets identifier is now an opaque string (#2387)
+
+## Tests
+
+* Extend the type checking of the ops-scenario tests (#2230)
+
+## CI
+
+* Run ruff check --fix in tox -e format (#2369)
+* Check example charms with mypy in CI (#2360)
+* Update the list of published charms in the compatibility tests (#2384)
+* Adjust minimum Python version in broad charm compatibility tests (#2317)
+
+# 3.6.0 - 26 February 2026
+
+## Features
+
+* Bump default Juju version in `ops.testing.Context` to 3.6.14 (#2316)
+
+## Fixes
+
+* Correct the `Model.get_binding()` return type (#2329)
+* Only show executable in `ExecError.__str__`, not full command line (#2336)
+* Support Pydantic `MISSING` sentinel in `ops.Relation.save` (#2306)
+
+## Documentation
+
+* Add how-to subcategory for managing containers (#2309)
+* Remove 2.19 version in docs, tweak ops.testing title (#2332)
+* Use "true" and "false" consistently in the reference documentation (#2330)
+* Add CLI args as another place to not put sensitive data (#2334)
+* Fix remote unit kwarg in testing example (#2342)
+* Clarify that secret labels are not names (#2337)
+
+## Tests
+
+* Set `SCENARIO_BARE_CHARM_ERRORS=true` in Ops tests that care (#2314)
+
+## CI
+
+* Fix releasing on branches with no `versions.md` doc (#2323)
+
 # 3.5.2 - 11 February 2026
 
 ## Fixes

{ops-3.5.2 → ops-3.7.0}/HACKING.md

@@ -18,6 +18,9 @@ uv tool install tox --with tox-uv
 uv tool update-shell
 ```
 
+Optionally, to run checks automatically before each commit, install
+[pre-commit](https://pre-commit.com/#install) and run `pre-commit install`.
+
 You can validate that you have a working installation by running:
 
 ```sh

{ops-3.5.2 → ops-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ops
-Version: 3.5.2
+Version: 3.7.0
 Summary: The Python library behind great charms
 Author: The Charm Tech team at Canonical Ltd.
 License-Expression: Apache-2.0
@@ -22,9 +22,9 @@ Requires-Dist: PyYAML==6.*
 Requires-Dist: websocket-client==1.*
 Requires-Dist: opentelemetry-api~=1.0
 Provides-Extra: testing
-Requires-Dist: ops-scenario==8.5.2; extra == "testing"
+Requires-Dist: ops-scenario==8.7.0; extra == "testing"
 Provides-Extra: tracing
-Requires-Dist: ops-tracing==3.5.2; extra == "tracing"
+Requires-Dist: ops-tracing==3.7.0; extra == "tracing"
 Provides-Extra: harness
 Dynamic: license-file
 
@@ -32,7 +32,7 @@ Dynamic: license-file
 
 ![CI Status](https://github.com/canonical/operator/actions/workflows/framework-tests.yaml/badge.svg)
 
-The `ops` library is a Python framework for developing and testing Kubernetes and machine [charms](https://charmhub.io/). While charms can be written in any language, `ops` defines the latest standard, and charmers are encouraged to use Python with `ops` for all charms. The library is an official component of the Charm SDK, itself a part of [the Juju universe](https://juju.is/).
+The `ops` library is a Python framework for developing and testing Kubernetes and machine [charms](https://charmhub.io/). While charms can be written in any language, `ops` defines the latest standard, and charmers are encouraged to use Python with `ops` for all charms. The library is an official component of the Charm SDK, itself a part of [the Juju universe](https://canonical.com/juju).
 
 > - `ops` is  [available on PyPI](https://pypi.org/project/ops/).
 > - The latest version of `ops` requires Python 3.10 or above.

{ops-3.5.2 → ops-3.7.0}/README.md

@@ -2,7 +2,7 @@
 
 ![CI Status](https://github.com/canonical/operator/actions/workflows/framework-tests.yaml/badge.svg)
 
-The `ops` library is a Python framework for developing and testing Kubernetes and machine [charms](https://charmhub.io/). While charms can be written in any language, `ops` defines the latest standard, and charmers are encouraged to use Python with `ops` for all charms. The library is an official component of the Charm SDK, itself a part of [the Juju universe](https://juju.is/).
+The `ops` library is a Python framework for developing and testing Kubernetes and machine [charms](https://charmhub.io/). While charms can be written in any language, `ops` defines the latest standard, and charmers are encouraged to use Python with `ops` for all charms. The library is an official component of the Charm SDK, itself a part of [the Juju universe](https://canonical.com/juju).
 
 > - `ops` is  [available on PyPI](https://pypi.org/project/ops/).
 > - The latest version of `ops` requires Python 3.10 or above.

{ops-3.5.2 → ops-3.7.0}/STYLE.md

@@ -261,6 +261,14 @@ However, it's okay to use acronyms that are very well known in our domain, like
 
 Choice of words: For example, if the whole document uses "mandatory", you probably shouldn't use "required" in a newly added paragraph. For another example, if the whole document uses "list foo" when adding new content, don't use "get a list of bar".
 
+### Use "true"/"false" consistently in docstrings
+
+When describing boolean parameters in docstrings:
+
+- Use lowercase "true"/"false" (no backticks) for truth-y/falsy concepts: "if true, create parent directories".
+- Use double-backtick-quoted `` ``True`` ``/`` ``False`` `` when referring to the Python objects themselves: "pass ``True`` to enable".
+- Do not use bare "True"/"False" (capitalised without backticks).
+
 ### Be precise
 
 Be precise in names and verbs. Use precise verbs to describe the behaviour. For example, the appropriate description of `/v1/services` is "list services", while "get a service" is probably a better fit for `/v1/services/{name}`.

{ops-3.5.2/test/charms/test_main/lib → ops-3.7.0}/ops/_main.py

@@ -212,7 +212,7 @@ class _Dispatcher:
         self.event_name = name
 
     def is_restricted_context(self):
-        """Return True if we are running in a restricted Juju context.
+        """Return ``True`` if we are running in a restricted Juju context.
 
         When in a restricted context, most commands (relation-get, config-get,
         state-get) are not available. As such, we change how we interact with

{ops-3.5.2 → ops-3.7.0}/ops/_private/harness.py

@@ -184,7 +184,7 @@ class ActionFailed(Exception):  # noqa: N818 (name doesn't end with "Error")
     state: State | None
     """The Juju state after the action has been run.
 
-    When using Harness.run_action, this will be None.
+    When using Harness.run_action, this will be ``None``.
     """
 
     def __init__(
@@ -450,7 +450,7 @@ class Harness(Generic[CharmType]):
         should be active when the charm starts, and then call this method. This method will
         automatically create and add peer relations that are specified in metadata.yaml.
 
-        If the charm metadata specifies containers, this sets can_connect to True for all
+        If the charm metadata specifies containers, this sets can_connect to ``True`` for all
         containers (in addition to triggering pebble-ready for each).
 
         Example::
@@ -801,8 +801,8 @@ class Harness(Generic[CharmType]):
         Args:
             storage_name: The storage backend name on the Charm
             count: Number of disks being added
-            attach: True to also attach the storage mount; if :meth:`begin`
-                has been called a True value will also emit storage-attached
+            attach: If true, also attach the storage mount; if :meth:`begin`
+                has been called a true value will also emit storage-attached
 
         Return:
             A list of storage IDs, e.g. ["my-storage/1", "my-storage/2"].
@@ -1646,7 +1646,7 @@ class Harness(Generic[CharmType]):
         do/don't trigger extra calls.
 
         Args:
-            reset: If True, reset the calls list back to empty, if false, the call list is
+            reset: If true, reset the calls list back to empty, if false, the call list is
                 preserved.
 
         Return:
@@ -1859,7 +1859,7 @@ class Harness(Generic[CharmType]):
 
         Args:
             secret_id: The ID of the secret associated with the event.
-            label: Label value to send to the event. If None, the secret's
+            label: Label value to send to the event. If ``None``, the secret's
                 label is used.
         """
         secret = self._ensure_secret(secret_id)
@@ -1880,7 +1880,7 @@ class Harness(Generic[CharmType]):
             secret_id: The ID of the secret associated with the event.
             revision: Revision number to provide to the event. This should be
                 an item from the list returned by :meth:`get_secret_revisions`.
-            label: Label value to send to the event. If None, the secret's
+            label: Label value to send to the event. If ``None``, the secret's
                 label is used.
         """
         secret = self._ensure_secret(secret_id)
@@ -1901,7 +1901,7 @@ class Harness(Generic[CharmType]):
             secret_id: The ID of the secret associated with the event.
             revision: Revision number to provide to the event. This should be
                 an item from the list returned by :meth:`get_secret_revisions`.
-            label: Label value to send to the event. If None, the secret's
+            label: Label value to send to the event. If ``None``, the secret's
                 label is used.
         """
         secret = self._ensure_secret(secret_id)
@@ -2545,7 +2545,7 @@ class _TestingModelBackend:
 
         Args:
             name: name (i.e. from metadata.yaml).
-            include_detached: True to include unattached storage mounts as well.
+            include_detached: If true, include unattached storage mounts as well.
         """
         return [
             index
@@ -2599,7 +2599,11 @@ class _TestingModelBackend:
             self._storage_attached[name].remove(index)
 
     def _storage_attach(self, storage_id: str):
-        """Mark the named storage_id as attached and return True if it was previously detached."""
+        """Mark the named storage_id as attached.
+
+        Returns:
+            ``True`` if it was previously detached.
+        """
         # NOTE: This is an extra function for _TestingModelBackend to simulate
         # re-attachment of a storage unit.  This is not present in
         # ops.model._ModelBackend.
@@ -2910,7 +2914,7 @@ class _TestingModelBackend:
 
     @classmethod
     def _generate_secret_id(cls) -> str:
-        # Not a proper Juju secrets-style xid, but that's okay
+        # Not a proper Juju secrets identifier, but that's okay
         return f'secret:{uuid.uuid4()}'
 
     def secret_add(

{ops-3.5.2 → ops-3.7.0}/ops/charm.py

@@ -2019,7 +2019,7 @@ class RelationMeta:
     """
 
     optional: bool
-    """If True, the relation is considered optional.
+    """If true, the relation is considered optional.
 
     This value is informational only and is not used by Juju itself (all
     relations are optional from Juju's perspective), but it may be set in
@@ -2079,7 +2079,7 @@ class StorageMeta:
     multiple_range: tuple[int, int | None] | None
     """Range of numeric qualifiers when multiple storage units are used."""
 
-    properties = list[str]
+    properties: list[str]
     """List of additional characteristics of the storage."""
 
     def __init__(self, name: str, raw: _StorageMetaDict):

{ops-3.5.2/test/charms/test_main/lib → ops-3.7.0}/ops/framework.py

@@ -78,7 +78,7 @@ class Handle:
     """Handle defines a name for an object in the form of a hierarchical path.
 
     The provided parent is the object (or that object's handle) that this handle
-    sits under, or None if the object identified by this handle stands by itself
+    sits under, or ``None`` if the object identified by this handle stands by itself
     as the root of its own hierarchy.
 
     The handle kind is a string that defines a namespace so objects with the
@@ -1231,7 +1231,7 @@ class StoredState:
     Data is stored alongside the charm (in the charm container for Kubernetes
     sidecar charms, and on the machine for machine charms). The exceptions are
     two deprecated cases: Kubernetes podspec charms, and charms explicitly
-    passing `True` for `use_juju_for_storage` when running :meth:`ops.main`.
+    passing ``True`` for ``use_juju_for_storage`` when running :meth:`ops.main`.
 
     For machine charms, charms are upgraded in-place on the machine, so the data
     is preserved. For Kubernetes sidecar charms, when the charm is upgraded, the

{ops-3.5.2/test/charms/test_main/lib → ops-3.7.0}/ops/hookcmds/_types.py

@@ -154,7 +154,7 @@ class CloudSpec:
     """Whether to skip TLS verification."""
 
     is_controller_cloud: bool = False
-    """If this is the cloud used by the controller, defaults to False."""
+    """If this is the cloud used by the controller, defaults to ``False``."""
 
     @classmethod
     def _from_dict(cls, d: dict[str, Any]) -> CloudSpec:

{ops-3.5.2 → ops-3.7.0}/ops/log.py

@@ -61,8 +61,8 @@ def setup_root_logging(
 
     Args:
         model_backend: a ModelBackend to use for juju-log
-        debug: if True, write logs to stderr as well as to juju-log.
-        exc_stderr: if True, write uncaught exceptions to stderr as well as to juju-log.
+        debug: if true, write logs to stderr as well as to juju-log.
+        exc_stderr: if true, write uncaught exceptions to stderr as well as to juju-log.
     """
     logger = logging.getLogger()
     logger.setLevel(logging.DEBUG)

{ops-3.5.2/test/charms/test_main/lib → ops-3.7.0}/ops/model.py

@@ -259,7 +259,7 @@ class Model:
         """
         return self.relations._get_unique(relation_name, relation_id)
 
-    def get_binding(self, binding_key: str | Relation) -> Binding | None:
+    def get_binding(self, binding_key: str | Relation) -> Binding:
         """Get a network space binding.
 
         Args:
@@ -536,7 +536,7 @@ def _calculate_expiry(
     if isinstance(expire, datetime.datetime):
         return expire
     elif isinstance(expire, datetime.timedelta):
-        return datetime.datetime.now() + expire
+        return datetime.datetime.now(tz=datetime.timezone.utc) + expire
     else:
         raise TypeError(
             'Expiration time must be a datetime or timedelta from now, '
@@ -1382,7 +1382,7 @@ class Secret:
         identifier for identifying one secret in a set of secrets of arbitrary
         size, use :attr:`unique_identifier` -- this should be rare.)
 
-        This will be None if the secret was obtained using
+        This will be ``None`` if the secret was obtained using
         :meth:`Model.get_secret` with a label but no ID.
         """
         return self._id
@@ -1391,8 +1391,7 @@ class Secret:
     def unique_identifier(self) -> str | None:
         """Unique identifier of this secret.
 
-        This is the secret's globally-unique identifier (currently a
-        20-character Xid, for example "9m4e2mr0ui3e8a215n4g").
+        This is the secret's globally-unique identifier (alphanumeric).
 
         Charms should use :attr:`id` (the secret's locator ID) to send
         the secret's ID across relation data, and labels (:attr:`label`) to
@@ -1401,7 +1400,7 @@ class Secret:
         cases where the charm has a set of secrets of arbitrary size, for
         example, a group of 10 or 20 TLS certificates.
 
-        This will be None if the secret was obtained using
+        This will be ``None`` if the secret was obtained using
         :meth:`Model.get_secret` with a label but no ID.
         """
         if self._id is None:
@@ -1445,7 +1444,7 @@ class Secret:
         Juju will ensure that the entity (the owner or observer) only has one
         secret with this label at once.
 
-        This will be None if the secret was obtained using
+        This will be ``None`` if the secret was obtained using
         :meth:`Model.get_secret` with an ID but no label.
         """
         return self._label
@@ -1873,6 +1872,10 @@ class Relation:
                 # data.destination will be stored under the Juju relation key 'to'
                 relation.save(data, self.unit)
 
+        If a Pydantic model's ``model_dump`` method omits any field (e.g. if its
+        value is Pydantic's ``MISSING`` sentinel) the field will be erased from
+        the relation data.
+
         Args:
             obj: an object with attributes to save to the relation data, typically
                 a Pydantic ``BaseModel`` subclass or dataclass.
@@ -1915,7 +1918,11 @@ class Relation:
             values = {field: getattr(obj, field) for field in fields}
 
         # Encode each value, and then pass it over to Juju.
-        data = {field: encoder(values[attr]) for attr, field in sorted(fields.items())}
+        # Missing values are erased from the databag using empty string values.
+        data = {
+            field: encoder(values[attr]) if attr in values else ''
+            for attr, field in sorted(fields.items())
+        }
         self.data[dst].update(data)
 
 
@@ -2643,9 +2650,9 @@ class Container:
                 combining).
             layer: A YAML string, configuration layer dict, or pebble.Layer
                 object containing the Pebble layer to add.
-            combine: If combine is False (the default), append the new layer
+            combine: If combine is false (the default), append the new layer
                 as the top layer with the given label (must be unique). If
-                combine is True and the label already exists, the two layers
+                combine is true and the label already exists, the two layers
                 are combined into a single one considering the layer override
                 rules; if the layer doesn't exist, it is added as usual.
         """
@@ -2798,7 +2805,7 @@ class Container:
             encoding: Encoding to use for encoding source str to bytes, or
                 strings read from source if it is a TextIO type. Ignored if
                 source is bytes or BinaryIO.
-            make_dirs: If True, create parent directories if they don't exist.
+            make_dirs: If true, create parent directories if they don't exist.
             permissions: Permissions (mode) to create file with (Pebble default
                 is 0o644).
             user_id: User ID (UID) for file. If neither ``group_id`` nor ``group`` is provided,
@@ -3036,6 +3043,7 @@ class Container:
             type=ftype,
             size=info.st_size,
             permissions=stat.S_IMODE(info.st_mode),
+            # This is unused, but a required FileInfo field.
             last_modified=datetime.datetime.fromtimestamp(info.st_mtime),
             user_id=info.st_uid,
             user=pw_name,
@@ -3130,7 +3138,7 @@ class Container:
 
         Args:
             path: Path of the directory to create on the remote system.
-            make_parents: If True, create parent directories if they don't exist.
+            make_parents: If true, create parent directories if they don't exist.
             permissions: Permissions (mode) to create directory with (Pebble
                 default is 0o755).
             user_id: User ID (UID) for directory. If neither ``group_id`` nor ``group``
@@ -3158,13 +3166,13 @@ class Container:
 
         Args:
             path: Path of the file or directory to delete from the remote system.
-            recursive: If True, and path is a directory, recursively delete it and
+            recursive: If true, and path is a directory, recursively delete it and
                        everything under it. If path is a file, delete the file. In
                        either case, do nothing if the file or directory does not
                        exist. Behaviourally similar to ``rm -rf <file|dir>``.
 
         Raises:
-            pebble.PathError: If a relative path is provided, or if `recursive` is False
+            pebble.PathError: If a relative path is provided, or if ``recursive`` is ``False``
                 and the file or directory cannot be removed (it does not exist or is not empty).
         """
         self._pebble.remove_path(path, recursive=recursive)
@@ -4277,7 +4285,7 @@ class CloudSpec:
     """Whether to skip TLS verification."""
 
     is_controller_cloud: bool = False
-    """If this is the cloud used by the controller, defaults to False."""
+    """If this is the cloud used by the controller, defaults to ``False``."""
 
     @classmethod
     def from_dict(cls, d: dict[str, Any]) -> CloudSpec:

{ops-3.5.2/test/charms/test_main/lib → ops-3.7.0}/ops/pebble.py

@@ -540,9 +540,9 @@ class ExecError(Error, Generic[AnyStr]):
     """Standard error from the process.
 
     If :meth:`ExecProcess.wait_output` was being called and ``combine_stderr``
-    was False, this is the captured stderr as a str (or bytes if encoding was
+    was ``False``, this is the captured stderr as a str (or bytes if encoding was
     None). If :meth:`ExecProcess.wait` was being called or ``combine_stderr``
-    was True, this is None.
+    was ``True``, this is None.
     """
 
     def __init__(
@@ -558,7 +558,7 @@ class ExecError(Error, Generic[AnyStr]):
         self.stderr = stderr
 
     def __str__(self):
-        message = f'non-zero exit code {self.exit_code} executing {self.command!r}'
+        message = f'non-zero exit code {self.exit_code} executing {self.command[0]!r}'
 
         for name, out in [('stdout', self.stdout), ('stderr', self.stderr)]:
             if out is None:
@@ -1069,7 +1069,7 @@ class ServiceInfo:
         self.current = current
 
     def is_running(self) -> bool:
-        """Return True if this service is running (in the active state)."""
+        """Return ``True`` if this service is running (in the active state)."""
         return self.current == ServiceStatus.ACTIVE
 
     @classmethod
@@ -1425,7 +1425,7 @@ class CheckInfo:
     level: CheckLevel | str | None
     """Check level.
 
-    This can be :attr:`CheckLevel.ALIVE`, :attr:`CheckLevel.READY`, or None (level not set).
+    This can be :attr:`CheckLevel.ALIVE`, :attr:`CheckLevel.READY`, or ``None`` (level not set).
     """
 
     startup: CheckStartup
@@ -1453,7 +1453,7 @@ class CheckInfo:
     :meth:`Client.start_checks`. It is reset to one when the check
     succeeds after the check's failure threshold was reached.
 
-    This will be None if the version of Pebble being queried doesn't return
+    This will be ``None`` if the version of Pebble being queried doesn't return
     the ``successes`` field (introduced in Pebble v1.23.0).
     """
 
@@ -1472,7 +1472,7 @@ class CheckInfo:
     change_id: ChangeID | None
     """Change ID of ``perform-check`` or ``recover-check`` change driving this check.
 
-    This will be None on older versions of Pebble, which did not use changes
+    This will be ``None`` on older versions of Pebble, which did not use changes
     to drive health checks.
     """
 
@@ -1708,7 +1708,7 @@ class ExecProcess(Generic[AnyStr]):
 
     If the stdin argument was not passed to :meth:`Client.exec`, this is a
     writable file-like object the caller can use to stream input to the
-    process. It is None if stdin was passed to :meth:`Client.exec`.
+    process. It is ``None`` if stdin was passed to :meth:`Client.exec`.
     """
 
     stdout: IO[AnyStr] | None
@@ -1716,16 +1716,16 @@ class ExecProcess(Generic[AnyStr]):
 
     If the stdout argument was not passed to :meth:`Client.exec`, this is a
     readable file-like object the caller can use to stream output from the
-    process. It is None if stdout was passed to :meth:`Client.exec`.
+    process. It is ``None`` if stdout was passed to :meth:`Client.exec`.
     """
 
     stderr: IO[AnyStr] | None
     """Standard error from the process.
 
     If the stderr argument was not passed to :meth:`Client.exec` and
-    ``combine_stderr`` was False, this is a readable file-like object the
-    caller can use to stream error output from the process. It is None if
-    stderr was passed to :meth:`Client.exec` or ``combine_stderr`` was True.
+    ``combine_stderr`` was ``False``, this is a readable file-like object the
+    caller can use to stream error output from the process. It is ``None`` if
+    stderr was passed to :meth:`Client.exec` or ``combine_stderr`` was ``True``.
     """
 
     def __init__(
@@ -1820,8 +1820,8 @@ class ExecProcess(Generic[AnyStr]):
         """Wait for the process to finish and return tuple of (stdout, stderr).
 
         If a timeout was specified to the :meth:`Client.exec` call, this waits
-        at most that duration. If combine_stderr was True, stdout will include
-        the process's standard error, and stderr will be None.
+        at most that duration. If combine_stderr was ``True``, stdout will include
+        the process's standard error, and stderr will be ``None``.
 
         Raises:
             ChangeError: if there was an error starting or running the process.
@@ -1878,7 +1878,7 @@ class ExecProcess(Generic[AnyStr]):
 
 
 def _has_fileno(f: Any) -> bool:
-    """Return True if the file-like object has a valid fileno() method."""
+    """Return ``True`` if the file-like object has a valid fileno() method."""
     try:
         f.fileno()
         return True
@@ -2443,7 +2443,7 @@ class Client:
         Args:
             change_id: Change ID of change to wait for.
             timeout: Maximum time in seconds to wait for the change to be
-                ready. It may be None, in which case wait_change never times out.
+                ready. It may be ``None``, in which case wait_change never times out.
             delay: If polling, this is the delay in seconds between attempts.
 
         Returns:
@@ -2539,8 +2539,8 @@ class Client:
     def add_layer(self, label: str, layer: str | LayerDict | Layer, *, combine: bool = False):
         """Dynamically add a new layer onto the Pebble configuration layers.
 
-        If combine is False (the default), append the new layer as the top
-        layer with the given label. If combine is True and the label already
+        If combine is false (the default), append the new layer as the top
+        layer with the given label. If combine is true and the label already
         exists, the two layers are combined into a single one considering the
         layer override rules; if the layer doesn't exist, it is added as usual.
         """
@@ -2605,12 +2605,12 @@ class Client:
         Args:
             path: Path of the file to read from the remote system.
             encoding: Encoding to use for decoding the file's bytes to str,
-                or None to specify no decoding.
+                or ``None`` to specify no decoding.
 
         Returns:
             A readable file-like object, whose read() method will return str
             objects decoded according to the specified encoding, or bytes if
-            encoding is None.
+            encoding is ``None``.
 
         Raises:
             PathError: If there was an error reading the file at path, for
@@ -2689,7 +2689,7 @@ class Client:
             encoding: Encoding to use for encoding source str to bytes, or
                 strings read from source if it is a TextIO type. Ignored if
                 source is bytes or BinaryIO.
-            make_dirs: If True, create parent directories if they don't exist.
+            make_dirs: If true, create parent directories if they don't exist.
             permissions: Permissions (mode) to create file with (Pebble default
                 is 0o644).
             user_id: User ID (UID) for file. If neither ``group_id`` nor ``group`` is provided,
@@ -2849,7 +2849,7 @@ class Client:
 
         Args:
             path: Path of the directory to create on the remote system.
-            make_parents: If True, create parent directories if they don't exist.
+            make_parents: If true, create parent directories if they don't exist.
             permissions: Permissions (mode) to create directory with (Pebble
                 default is 0o755).
             user_id: User ID (UID) for directory. If neither ``group_id`` nor ``group``
@@ -2885,13 +2885,13 @@ class Client:
 
         Args:
             path: Path of the file or directory to delete from the remote system.
-            recursive: If True, and path is a directory, recursively delete it and
+            recursive: If true, and path is a directory, recursively delete it and
                        everything under it. If path is a file, delete the file. In
                        either case, do nothing if the file or directory does not
                        exist. Behaviourally similar to ``rm -rf <file|dir>``.
 
         Raises:
-            pebble.PathError: If a relative path is provided, or if `recursive` is False
+            pebble.PathError: If a relative path is provided, or if ``recursive`` is ``False``
                 and the file or directory cannot be removed (it does not exist or is not empty).
         """
         path = str(path)
@@ -3074,13 +3074,13 @@ class Client:
                 :meth:`ExecProcess.wait_output` to capture error output as a
                 string, or read from :meth:`ExecProcess.stderr` to stream
                 error output from the process. Must be None if combine_stderr
-                is True.
+                is ``True``.
             encoding: If encoding is set (the default is UTF-8), the types
                 read or written to stdin/stdout/stderr are str, and encoding
                 is used to encode them to bytes. If encoding is None, the
                 types read or written are raw bytes.
-            combine_stderr: If True, process's stderr output is combined into
-                its stdout (the stderr argument must be None). If False,
+            combine_stderr: If true, process's stderr output is combined into
+                its stdout (the stderr argument must be None). If false,
                 separate streams are used for stdout and stderr.
 
         Returns:

{ops-3.5.2/test/charms/test_main/lib → ops-3.7.0}/ops/storage.py

@@ -192,7 +192,7 @@ class SQLiteStorage:
 
         Args:
             event_path: If supplied, will only yield events that match event_path. If not
-                supplied (or None/'') will return all events.
+                supplied (or ``None``/``''``) will return all events.
 
         Returns:
             Iterable of (event_path, observer_path, method_name) tuples
@@ -294,7 +294,7 @@ class JujuStorage:
 
         Args:
             event_path: If supplied, will only yield events that match event_path. If not
-                supplied (or None/'') will return all events.
+                supplied (or ``None``/``''``) will return all events.
 
         Returns:
             Iterable of (event_path, observer_path, method_name) tuples