Merge branch 'main' into fix-config-types-1182

docs/requirements.txt

@@ -1,10 +1,10 @@
 #
-# This file is autogenerated by pip-compile with Python 3.8
+# This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
 #    pip-compile --extra=docs --output-file=docs/requirements.txt pyproject.toml
 #
-alabaster==0.7.13
+alabaster==0.7.16
     # via sphinx
 babel==2.14.0
     # via sphinx
@@ -15,7 +15,7 @@ beautifulsoup4==4.12.3
     #   pyspelling
 bracex==2.4
     # via wcmatch
-canonical-sphinx-extensions==0.0.19
+canonical-sphinx-extensions==0.0.20
     # via ops (pyproject.toml)
 certifi==2024.2.2
     # via requests
@@ -33,14 +33,10 @@ furo==2024.1.29
     # via ops (pyproject.toml)
 html5lib==1.1
     # via pyspelling
-idna==3.6
+idna==3.7
     # via requests
 imagesize==1.4.1
     # via sphinx
-importlib-metadata==7.1.0
-    # via
-    #   markdown
-    #   sphinx
 jinja2==3.1.3
     # via
     #   myst-parser
@@ -49,7 +45,7 @@ linkify-it-py==2.0.3
     # via ops (pyproject.toml)
 livereload==2.6.3
     # via sphinx-autobuild
-lxml==5.1.0
+lxml==5.2.1
     # via pyspelling
 markdown==3.6
     # via pyspelling
@@ -74,8 +70,6 @@ pygments==2.17.2
     #   sphinx-tabs
 pyspelling==2.10
     # via ops (pyproject.toml)
-pytz==2024.1
-    # via babel
 pyyaml==6.0.1
     # via
     #   myst-parser
@@ -109,7 +103,7 @@ sphinx==6.2.1
     #   sphinx-tabs
     #   sphinxcontrib-jquery
     #   sphinxext-opengraph
-sphinx-autobuild==2021.3.14
+sphinx-autobuild==2024.2.4
     # via ops (pyproject.toml)
 sphinx-basic-ng==1.0.0b2
     # via furo
@@ -121,19 +115,19 @@ sphinx-notfound-page==1.0.0
     # via ops (pyproject.toml)
 sphinx-tabs==3.4.5
     # via ops (pyproject.toml)
-sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-applehelp==1.0.8
     # via sphinx
-sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-devhelp==1.0.6
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-htmlhelp==2.0.5
     # via sphinx
 sphinxcontrib-jquery==4.1
     # via ops (pyproject.toml)
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-qthelp==1.0.7
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==1.1.10
     # via sphinx
 sphinxext-opengraph==0.9.1
     # via ops (pyproject.toml)
@@ -149,5 +143,3 @@ webencodings==0.5.1
     # via html5lib
 websocket-client==1.7.0
     # via ops (pyproject.toml)
-zipp==3.18.1
-    # via importlib-metadata

ops/__init__.py

@@ -66,7 +66,6 @@
     'LeaderSettingsChangedEvent',
     'MetadataLinks',
     'PayloadMeta',
-    'PebbleChangeUpdatedEvent',
     'PebbleCustomNoticeEvent',
     'PebbleNoticeEvent',
     'PebbleReadyEvent',
@@ -209,7 +208,6 @@
     LeaderSettingsChangedEvent,
     MetadataLinks,
     PayloadMeta,
-    PebbleChangeUpdatedEvent,
     PebbleCustomNoticeEvent,
     PebbleNoticeEvent,
     PebbleReadyEvent,

ops/charm.py

@@ -34,7 +34,7 @@
     cast,
 )
 
-from ops import model, pebble
+from ops import model
 from ops._private import yaml
 from ops.framework import (
     EventBase,
@@ -387,11 +387,12 @@ class LeaderElectedEvent(HookEvent):
 
 
 class LeaderSettingsChangedEvent(HookEvent):
-    """DEPRECATED. Event triggered when leader changes any settings.
+    """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`).
+    .. 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`.)
     """
 
 
@@ -809,15 +810,6 @@ class PebbleCustomNoticeEvent(PebbleNoticeEvent):
     """Event triggered when a Pebble notice of type "custom" is created or repeats."""
 
 
-class PebbleChangeUpdatedEvent(PebbleNoticeEvent):
-    """Event triggered when a Pebble notice of type "change-update" is created or repeats."""
-
-    def get_change(self) -> pebble.Change:
-        """Get the Pebble change associated with this event."""
-        change_id = pebble.ChangeID(self.notice.key)
-        return self.workload.pebble.get_change(change_id)
-
-
 class SecretEvent(HookEvent):
     """Base class for all secret events."""
 
@@ -1094,8 +1086,10 @@ 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
     """
 
     collect_metrics = EventSource(CollectMetricsEvent)
@@ -1197,9 +1191,6 @@ def __init__(self, framework: Framework):
             container_name = container_name.replace('-', '_')
             self.on.define_event(f"{container_name}_pebble_ready", PebbleReadyEvent)
             self.on.define_event(f"{container_name}_pebble_custom_notice", PebbleCustomNoticeEvent)
-            self.on.define_event(
-                f"{container_name}_pebble_change_updated",
-                PebbleChangeUpdatedEvent)
 
     @property
     def app(self) -> model.Application:

ops/lib/__init__.py

@@ -14,9 +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
@@ -48,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.
@@ -61,6 +59,10 @@ 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
+        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)
@@ -101,8 +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)

ops/model.py

@@ -180,10 +180,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
 
@@ -769,7 +770,12 @@ class Port:
     """The port number. Will be ``None`` if protocol is ``'icmp'``."""
 
 
-OpenedPort = Port  # Alias for backwards compatibility.
+OpenedPort = Port
+"""Alias to Port for backwards compatibility.
+
+.. deprecated:: 2.7.0
+    Use :class:`Port` instead.
+"""
 
 
 _LazyValueType = typing.TypeVar("_LazyValueType")
@@ -1922,10 +1928,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'):
@@ -2016,7 +2024,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."""
         logger.warning("model.Storage.id is being replaced - please use model.Storage.index")
         return self.index
 

ops/pebble.py

@@ -1314,17 +1314,7 @@ def __repr__(self):
 class NoticeType(enum.Enum):
     """Enum of notice types."""
 
-    CHANGE_UPDATE = 'change-update'
-    """Recorded whenever a change is updated, that is, when it is first
-    spawned or its status was updated. The key for change-update notices is
-    the change ID.
-    """
-
     CUSTOM = 'custom'
-    """A custom notice reported via the Pebble client API or ``pebble notify``.
-    The key and data fields are provided by the user. The key must be in
-    the format ``example.com/path`` to ensure well-namespaced notice keys.
-    """
 
 
 class NoticesUsers(enum.Enum):