From d3b878e222e89f427527ef64c194129f40e1e928 Mon Sep 17 00:00:00 2001 From: Dima Tisnek Date: Tue, 10 Sep 2024 15:42:38 +0900 Subject: [PATCH] docs: note about repeatedly setting secret value in Juju 3.6 (#1366) https://warthogs.atlassian.net/browse/CHARMTECH-171 --------- Co-authored-by: Tony Meyer --- docs/custom_conf.py | 10 ++++++++-- docs/requirements.txt | 2 +- ops/charm.py | 22 +++++++++++----------- ops/model.py | 14 +++++++++----- tox.ini | 4 +--- 5 files changed, 30 insertions(+), 22 deletions(-) diff --git a/docs/custom_conf.py b/docs/custom_conf.py index 29e964360..b1ccbc019 100644 --- a/docs/custom_conf.py +++ b/docs/custom_conf.py @@ -379,7 +379,7 @@ def run(self): messages = [] if self.content: node += self.parse_content_to_nodes() - classes = ['versionmodified', self.change, 'jujuversion'] + classes = ['versionmodified', self.change] if len(node) > 0 and isinstance(node[0], nodes.paragraph): # The contents start with a paragraph. if node[0].rawsource: @@ -418,11 +418,17 @@ class JujuAdded(JujuVersion): text = 'Added' +class JujuChanged(JujuVersion): + change = 'changed' + text = 'Changed' + + class JujuRemoved(JujuVersion): change = 'removed' text = 'Scheduled for removal' def setup(app): - app.add_directive('jujuversion', JujuAdded) + app.add_directive('jujuadded', JujuAdded) + app.add_directive('jujuchanged', JujuChanged) app.add_directive('jujuremoved', JujuRemoved) diff --git a/docs/requirements.txt b/docs/requirements.txt index 0df7bf37d..340a58046 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -117,7 +117,7 @@ sphinx==8.0.2 # sphinx-tabs # sphinxcontrib-jquery # sphinxext-opengraph -sphinx-autobuild==2024.4.16 +sphinx-autobuild==2024.9.3 # via ops (pyproject.toml) sphinx-basic-ng==1.0.0b2 # via furo diff --git a/ops/charm.py b/ops/charm.py index dcd13d2dd..c626d11da 100644 --- a/ops/charm.py +++ b/ops/charm.py @@ -837,7 +837,7 @@ def restore(self, snapshot: Dict[str, Any]): class PebbleCustomNoticeEvent(PebbleNoticeEvent): """Event triggered when a Pebble notice of type "custom" is created or repeats. - .. jujuversion:: 3.4 + .. jujuadded:: 3.4 """ @@ -884,7 +884,7 @@ class PebbleCheckFailedEvent(PebbleCheckEvent): if the check is currently failing, check the current status with ``event.info.status == ops.pebble.CheckStatus.DOWN``. - .. jujuversion:: 3.6 + .. jujuadded:: 3.6 """ @@ -895,7 +895,7 @@ class PebbleCheckRecoveredEvent(PebbleCheckEvent): state (not simply failed, but failed at least as many times as the configured threshold). - .. jujuversion:: 3.6 + .. jujuadded:: 3.6 """ @@ -944,7 +944,7 @@ class SecretChangedEvent(SecretEvent): :meth:`event.secret.get_content() ` with ``refresh=True`` to tell Juju to start tracking the new revision. - .. jujuversion:: 3.0 + .. jujuadded:: 3.0 Charm secrets added in Juju 3.0, user secrets added in Juju 3.3 """ @@ -956,7 +956,7 @@ class SecretRotateEvent(SecretEvent): be rotated. The event will keep firing until the owner creates a new revision by calling :meth:`event.secret.set_content() `. - .. jujuversion:: 3.0 + .. jujuadded:: 3.0 """ def defer(self) -> NoReturn: @@ -983,7 +983,7 @@ class SecretRemoveEvent(SecretEvent): remove the now-unused revision. If the charm does not, then the event will be emitted again, when further revisions are ready for removal. - .. jujuversion:: 3.0 + .. jujuadded:: 3.0 """ def __init__(self, handle: 'Handle', id: str, label: Optional[str], revision: int): @@ -1020,7 +1020,7 @@ class SecretExpiredEvent(SecretEvent): must be removed. The event will keep firing until the owner removes the revision by calling :meth:`event.secret.remove_revision() `. - .. jujuversion:: 3.0 + .. jujuadded:: 3.0 """ def __init__(self, handle: 'Handle', id: str, label: Optional[str], revision: int): @@ -1213,7 +1213,7 @@ class CharmEvents(ObjectEvents): """Triggered by Juju on the observer when the secret owner changes its contents (see :class:`SecretChangedEvent`). - .. jujuversion:: 3.0 + .. jujuadded:: 3.0 Charm secrets added in Juju 3.0, user secrets added in Juju 3.3 """ @@ -1221,21 +1221,21 @@ class CharmEvents(ObjectEvents): """Triggered by Juju on the owner when a secret's expiration time elapses (see :class:`SecretExpiredEvent`). - .. jujuversion:: 3.0 + .. jujuadded:: 3.0 """ secret_rotate = EventSource(SecretRotateEvent) """Triggered by Juju on the owner when the secret's rotation policy elapses (see :class:`SecretRotateEvent`). - .. jujuversion:: 3.0 + .. jujuadded:: 3.0 """ secret_remove = EventSource(SecretRemoveEvent) """Triggered by Juju on the owner when a secret revision can be removed (see :class:`SecretRemoveEvent`). - .. jujuversion:: 3.0 + .. jujuadded:: 3.0 """ collect_app_status = EventSource(CollectStatusEvent) diff --git a/ops/model.py b/ops/model.py index 336ef5aaa..7571bd2ac 100644 --- a/ops/model.py +++ b/ops/model.py @@ -280,7 +280,7 @@ def get_secret(self, *, id: Optional[str] = None, label: Optional[str] = None) - again, unless ``refresh=True`` is used, or :meth:`Secret.set_content` has been called. - .. jujuversion:: 3.0 + .. jujuadded:: 3.0 Charm secrets added in Juju 3.0, user secrets added in Juju 3.3 Args: @@ -465,7 +465,7 @@ def add_secret( ) -> 'Secret': """Create a :class:`Secret` owned by this application. - .. jujuversion:: 3.0 + .. jujuadded:: 3.0 Args: content: A key-value mapping containing the payload of the secret, @@ -1246,7 +1246,7 @@ class Secret: All secret events have a :code:`.secret` attribute which provides the :class:`Secret` associated with that event. - .. jujuversion:: 3.0 + .. jujuadded:: 3.0 Charm secrets added in Juju 3.0, user secrets added in Juju 3.3 """ @@ -1460,6 +1460,10 @@ def set_content(self, content: Dict[str, str]): secret no longer exists, this method will succeed, but the unit will go into error state on completion of the current Juju hook. + .. jujuchanged:: 3.6 + A new secret revision will *not* be created if the content being set + is identical to the latest revision. + Args: content: A key-value mapping containing the payload of the secret, for example :code:`{"password": "foo123"}`. @@ -2939,7 +2943,7 @@ def send_signal(self, sig: Union[int, str], *service_names: str): def get_notice(self, id: str) -> pebble.Notice: """Get details about a single notice by ID. - .. jujuversion:: 3.4 + .. jujuadded:: 3.4 Raises: ModelError: if a notice with the given ID is not found @@ -2964,7 +2968,7 @@ def get_notices( See :meth:`ops.pebble.Client.get_notices` for documentation of the parameters. - .. jujuversion:: 3.4 + .. jujuadded:: 3.4 """ return self._pebble.get_notices( users=users, diff --git a/tox.ini b/tox.ini index 2c7a2496d..cf097a12f 100644 --- a/tox.ini +++ b/tox.ini @@ -54,10 +54,8 @@ description = Live development: build the Sphinx docs with autoreloading enabled deps = {[testenv:docs]deps} commands_pre = {[testenv:docs]commands_pre} -# https://github.com/sphinx-doc/sphinx-autobuild/issues/170 -change_dir = {tox_root}/docs commands = - sphinx-autobuild ./ ./_build/html --watch . --port 8000 + sphinx-autobuild docs/ docs/_build/html --watch ops/ --port 8000 {posargs} [testenv:fmt] description = Apply coding style standards to code