From 6a8adf41d3935e33e82b61e654e48d5f25953d4b Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Mon, 8 Apr 2024 16:40:03 +0800 Subject: [PATCH 1/5] docs: update docstrings with deprecated directive --- ops/charm.py | 4 ++++ ops/lib/__init__.py | 6 ++++++ ops/model.py | 10 +++++++++- 3 files changed, 19 insertions(+), 1 deletion(-) diff --git a/ops/charm.py b/ops/charm.py index fb687b453..fdd7fcc51 100644 --- a/ops/charm.py +++ b/ops/charm.py @@ -392,6 +392,8 @@ class LeaderSettingsChangedEvent(HookEvent): This event has been deprecated in favor of using a Peer relation, and having the leader set a value in the Application data bag for that peer relation. (see :class:`RelationChangedEvent`). + + .. deprecated:: 2.4.0 """ @@ -1086,6 +1088,8 @@ class CharmEvents(ObjectEvents): leader_settings_changed = EventSource(LeaderSettingsChangedEvent) """DEPRECATED. Triggered when leader changes any settings (see :class:`LeaderSettingsChangedEvent`). + + .. deprecated: 2.4.0 """ collect_metrics = EventSource(CollectMetricsEvent) diff --git a/ops/lib/__init__.py b/ops/lib/__init__.py index dde350159..7c24cdffd 100644 --- a/ops/lib/__init__.py +++ b/ops/lib/__init__.py @@ -17,6 +17,8 @@ DEPRECATED: The ops.lib functionality is deprecated, and is superseded by charm libraries (https://juju.is/docs/sdk/library) and regular Python imports. We now prefer to do version selection at build (charmcraft pack) time. + +.. deprecated:: 2.1.0 """ import logging @@ -61,6 +63,8 @@ def use(name: str, api: int, author: str) -> ModuleType: ImportError: if the library cannot be found. TypeError: if the name, api, or author are the wrong type. ValueError: if the name, api, or author are invalid. + + .. deprecated:: 2.1.0 """ warnings.warn("ops.lib is deprecated, prefer charm libraries instead", category=DeprecationWarning) @@ -103,6 +107,8 @@ def autoimport(): DEPRECATED: This function is deprecated. Prefer charm libraries instead (https://juju.is/docs/sdk/library). + + .. deprecated:: 2.1.0 """ warnings.warn("ops.lib is deprecated, prefer charm libraries instead", category=DeprecationWarning) diff --git a/ops/model.py b/ops/model.py index 7ca4e1381..a83693afe 100644 --- a/ops/model.py +++ b/ops/model.py @@ -181,6 +181,8 @@ def pod(self) -> 'Pod': Use :meth:`Pod.set_spec` to set the container specification for legacy Kubernetes charms. + + .. deprecated:: 2.4.0 """ return self._pod @@ -1910,6 +1912,8 @@ class Pod: Currently only supports simple access to setting the Juju pod spec via :attr:`.set_spec`. + + .. deprecated:: 2.4.0 """ def __init__(self, backend: '_ModelBackend'): @@ -2000,7 +2004,11 @@ def index(self) -> int: @property def id(self) -> int: - """DEPRECATED. Use :attr:`Storage.index` instead.""" + """DEPRECATED. Use :attr:`Storage.index` instead. + + .. deprecated:: 2.4.0 + Use :attr:`Storage.index` instead. + """ logger.warning("model.Storage.id is being replaced - please use model.Storage.index") return self.index From 29098957e6910c10ec8c23cad5a0ecd2a048fae8 Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Tue, 9 Apr 2024 07:55:09 +0800 Subject: [PATCH 2/5] docs: update deprecated docstrings --- ops/charm.py | 11 +++++------ ops/lib/__init__.py | 19 ++++++++----------- ops/model.py | 13 ++++--------- 3 files changed, 17 insertions(+), 26 deletions(-) diff --git a/ops/charm.py b/ops/charm.py index fdd7fcc51..268106363 100644 --- a/ops/charm.py +++ b/ops/charm.py @@ -387,13 +387,12 @@ class LeaderElectedEvent(HookEvent): class LeaderSettingsChangedEvent(HookEvent): - """DEPRECATED. Event triggered when leader changes any settings. - - This event has been deprecated in favor of using a Peer relation, - and having the leader set a value in the Application data bag for - that peer relation. (see :class:`RelationChangedEvent`). + """Event triggered when leader changes any settings. .. deprecated:: 2.4.0 + This event has been deprecated in favor of using a Peer relation, + and having the leader set a value in the Application data bag for + that peer relation. (See :class:`RelationChangedEvent`.) """ @@ -1086,7 +1085,7 @@ class CharmEvents(ObjectEvents): """Triggered when a new leader has been elected (see :class:`LeaderElectedEvent`).""" leader_settings_changed = EventSource(LeaderSettingsChangedEvent) - """DEPRECATED. Triggered when leader changes any settings (see + """Triggered when leader changes any settings (see :class:`LeaderSettingsChangedEvent`). .. deprecated: 2.4.0 diff --git a/ops/lib/__init__.py b/ops/lib/__init__.py index 7c24cdffd..9d04662b0 100644 --- a/ops/lib/__init__.py +++ b/ops/lib/__init__.py @@ -14,11 +14,10 @@ """Infrastructure for the opslib functionality. -DEPRECATED: The ops.lib functionality is deprecated, and is superseded by -charm libraries (https://juju.is/docs/sdk/library) and regular Python imports. -We now prefer to do version selection at build (charmcraft pack) time. - .. deprecated:: 2.1.0 + The ops.lib functionality is deprecated, and is superseded by + charm libraries (https://juju.is/docs/sdk/library) and regular Python imports. + We now prefer to do version selection at build (charmcraft pack) time. """ import logging @@ -50,9 +49,6 @@ def use(name: str, api: int, author: str) -> ModuleType: """Use a library from the ops libraries. - DEPRECATED: This function is deprecated. Prefer charm libraries instead - (https://juju.is/docs/sdk/library). - Args: name: the name of the library requested. api: the API version of the library. @@ -64,7 +60,9 @@ def use(name: str, api: int, author: str) -> ModuleType: TypeError: if the name, api, or author are the wrong type. ValueError: if the name, api, or author are invalid. - .. deprecated:: 2.1.0 + .. deprecated:: 2.1.0\ + This function is deprecated. Prefer charm libraries instead + (https://juju.is/docs/sdk/library). """ warnings.warn("ops.lib is deprecated, prefer charm libraries instead", category=DeprecationWarning) @@ -105,10 +103,9 @@ def autoimport(): otherwise changed in the current run, and the changes need to be seen. Otherwise libraries are found on first call of `use`. - DEPRECATED: This function is deprecated. Prefer charm libraries instead - (https://juju.is/docs/sdk/library). - .. deprecated:: 2.1.0 + This function is deprecated. Prefer charm libraries instead + (https://juju.is/docs/sdk/library). """ warnings.warn("ops.lib is deprecated, prefer charm libraries instead", category=DeprecationWarning) diff --git a/ops/model.py b/ops/model.py index a83693afe..42cd157ed 100644 --- a/ops/model.py +++ b/ops/model.py @@ -177,12 +177,11 @@ def storages(self) -> 'StorageMapping': def pod(self) -> 'Pod': """Represents the definition of a pod spec in legacy Kubernetes models. - DEPRECATED: New charms should use the sidecar pattern with Pebble. - Use :meth:`Pod.set_spec` to set the container specification for legacy Kubernetes charms. .. deprecated:: 2.4.0 + New charms should use the sidecar pattern with Pebble. """ return self._pod @@ -1908,12 +1907,12 @@ def fetch(self, name: str) -> Path: class Pod: """Represents the definition of a pod spec in legacy Kubernetes models. - DEPRECATED: New charms should use the sidecar pattern with Pebble. - Currently only supports simple access to setting the Juju pod spec via :attr:`.set_spec`. .. deprecated:: 2.4.0 + + New charms should use the sidecar pattern with Pebble. """ def __init__(self, backend: '_ModelBackend'): @@ -2004,11 +2003,7 @@ def index(self) -> int: @property def id(self) -> int: - """DEPRECATED. Use :attr:`Storage.index` instead. - - .. deprecated:: 2.4.0 - Use :attr:`Storage.index` instead. - """ + """.. deprecated:: 2.4.0 Use :attr:`Storage.index` instead.""" logger.warning("model.Storage.id is being replaced - please use model.Storage.index") return self.index From 2f37fa11b685c88e6c2fc17c00b24cd1d7f581c9 Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Tue, 9 Apr 2024 07:56:10 +0800 Subject: [PATCH 3/5] chore: fix typo --- ops/lib/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ops/lib/__init__.py b/ops/lib/__init__.py index 9d04662b0..0ea46c361 100644 --- a/ops/lib/__init__.py +++ b/ops/lib/__init__.py @@ -60,7 +60,7 @@ def use(name: str, api: int, author: str) -> ModuleType: TypeError: if the name, api, or author are the wrong type. ValueError: if the name, api, or author are invalid. - .. deprecated:: 2.1.0\ + .. deprecated:: 2.1.0 This function is deprecated. Prefer charm libraries instead (https://juju.is/docs/sdk/library). """ From 167a03804c0acbef7dd1a39b83312a7aff9dd06f Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Fri, 12 Apr 2024 14:08:12 +0800 Subject: [PATCH 4/5] chore: add deprecated for openedport and change it to a subclass --- ops/model.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/ops/model.py b/ops/model.py index 5e38eda50..25dab949c 100644 --- a/ops/model.py +++ b/ops/model.py @@ -767,7 +767,12 @@ class Port: """The port number. Will be ``None`` if protocol is ``'icmp'``.""" -OpenedPort = Port # Alias for backwards compatibility. +class OpenedPort(Port): + """Alias to Port for backwards compatibility. + + .. deprecated:: 2.7.0 + Use :class:`Port` instead. + """ class LazyMapping(Mapping[str, str], ABC): From b65cc6fc2912be598b342f8ab93e04bbcc5eacea Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Mon, 15 Apr 2024 09:53:41 +0800 Subject: [PATCH 5/5] chore: revert openport change --- ops/model.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/ops/model.py b/ops/model.py index 25dab949c..2ccdc33ea 100644 --- a/ops/model.py +++ b/ops/model.py @@ -767,12 +767,12 @@ class Port: """The port number. Will be ``None`` if protocol is ``'icmp'``.""" -class OpenedPort(Port): - """Alias to Port for backwards compatibility. +OpenedPort = Port +"""Alias to Port for backwards compatibility. - .. deprecated:: 2.7.0 - Use :class:`Port` instead. - """ +.. deprecated:: 2.7.0 + Use :class:`Port` instead. +""" class LazyMapping(Mapping[str, str], ABC):