Merge branch 'main' into pyright-test_infra-1007

.github/workflows/framework-tests.yaml

@@ -67,10 +67,10 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Set up Go 1.17
+      - name: Set up Go 1.20
         uses: actions/setup-go@v1
         with:
-          go-version: "1.17"
+          go-version: "1.20"
 
       - name: Install tox
         run: pip install tox

ops/charm.py

@@ -241,7 +241,7 @@ class ConfigChangedEvent(HookEvent):
       This event notifies the charm of its initial configuration.
       Typically, this event will fire between an :class:`install <InstallEvent>`
       and a :class:`start <StartEvent>` during the startup sequence
-      (when you first deploy a unit), but in general it will fire whenever
+      (when a unit is first deployed), but in general it will fire whenever
       the unit is (re)started, for example after pod churn on Kubernetes, on unit
       rescheduling, on unit upgrade or refresh, and so on.
     - As a specific instance of the above point: when networking changes
@@ -519,8 +519,8 @@ def snapshot(self) -> Dict[str, Any]:
     def departing_unit(self) -> Optional[model.Unit]:
         """The :class:`ops.Unit` that is departing, if any.
 
-        You can use this to determine (for example) whether *you* are the
-        departing unit.
+        Use this method to determine (for example) whether this unit is the
+        departing one.
         """
         # doing this on init would fail because `framework` gets patched in
         # post-init
@@ -729,7 +729,7 @@ class SecretChangedEvent(SecretEvent):
     a new secret revision, and all applications or units that are tracking this
     secret will be notified via this event that a new revision is available.
 
-    Typically, you will want to fetch the new content by calling
+    Typically, the charm will fetch the new content by calling
     :meth:`event.secret.get_content() <ops.Secret.get_content>` with ``refresh=True``
     to tell Juju to start tracking the new revision.
     """
@@ -757,7 +757,7 @@ class SecretRemoveEvent(SecretEvent):
     observers have updated to that new revision, this event will be fired to
     inform the secret owner that the old revision can be removed.
 
-    Typically, you will want to call
+    Typically, the charm will call
     :meth:`event.secret.remove_revision() <ops.Secret.remove_revision>` to
     remove the now-unused revision.
     """
@@ -1005,7 +1005,7 @@ class CharmBase(Object):
 
     :code:`CharmBase` is used to create a charm. This is done by inheriting
     from :code:`CharmBase` and customising the subclass as required. So to
-    create your own charm, say ``MyCharm``, define a charm class and set up the
+    create a charm called ``MyCharm``, define a charm class and set up the
     required event handlers (“hooks”) in its constructor::
 
         import logging

ops/framework.py

@@ -202,7 +202,7 @@ def defer(self) -> None:
         the result of an action, or any event other than metric events. The
         queue of events will be dispatched before the new event is processed.
 
-        From the above you may deduce, but it's important to point out:
+        Important points that follow from the above:
 
         * ``defer()`` does not interrupt the execution of the current event
           handler. In almost all cases, a call to ``defer()`` should be followed
@@ -220,19 +220,18 @@ def defer(self) -> None:
 
         The general desire to call ``defer()`` happens when some precondition
         isn't yet met. However, care should be exercised as to whether it is
-        better to defer this event so that you see it again, or whether it is
+        better to defer this event so that it is seen again, or whether it is
         better to just wait for the event that indicates the precondition has
         been met.
 
-        For example, if ``config-changed`` is fired, and you are waiting for
-        different config, there is no reason to defer the event because there
-        will be a *different* ``config-changed`` event when the config actually
-        changes, rather than checking to see if maybe config has changed prior
-        to every other event that occurs.
+        For example, if handling a config change requires that two config
+        values are changed, there's no reason to defer the first
+        ``config-changed`` because there will be a *second* ``config-changed``
+        event fired when the other config value changes.
 
-        Similarly, if you need 2 events to occur before you are ready to
-        proceed (say event A and B). When you see event A, you could chose to
-        ``defer()`` it because you haven't seen B yet. However, that leads to:
+        Similarly, if two events need to occur before execution can proceed
+        (say event A and B), the event A handler could ``defer()`` because B
+        has not been seen yet. However, that leads to:
 
         1. event A fires, calls defer()
 
@@ -242,7 +241,6 @@ def defer(self) -> None:
 
         3. At some future time, event C happens, which also checks if A can
            proceed.
-
         """
         logger.debug("Deferring %s.", self)
         self.deferred = True
@@ -1360,8 +1358,8 @@ def _from_iterable(cls, it: Iterable[_T]) -> Set[_T]:
 
         Per https://docs.python.org/3/library/collections.abc.html
         if the Set mixin is being used in a class with a different constructor signature,
-        you will need to override _from_iterable() with a classmethod that can construct
-        new instances from an iterable argument.
+        override _from_iterable() with a classmethod that can construct new instances
+        from an iterable argument.
         """
         return set(it)
 

ops/lib/__init__.py

@@ -96,9 +96,9 @@ def use(name: str, api: int, author: str) -> ModuleType:
 def autoimport():
     """Find all libs in the path and enable use of them.
 
-    You only need to call this if you've installed a package or
-    otherwise changed sys.path in the current run, and need to see the
-    changes. Otherwise libraries are found on first call of `use`.
+    Call this function only when a package has been installed or sys.path has been
+    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).

ops/main.py

@@ -340,7 +340,7 @@ def is_restricted_context(self):
 
 def _should_use_controller_storage(db_path: Path, meta: CharmMeta) -> bool:
     """Figure out whether we want to use controller storage or not."""
-    # if you've previously used local state, carry on using that
+    # if local state has been used previously, carry on using that
     if db_path.exists():
         return False
 
@@ -368,7 +368,7 @@ def main(charm_class: Type[ops.charm.CharmBase],
     The event name is based on the way this executable was called (argv[0]).
 
     Args:
-        charm_class: your charm class.
+        charm_class: the charm class to instantiate and receive the event.
         use_juju_for_storage: whether to use controller-side storage. If not specified
             then kubernetes charms that haven't previously used local storage and that
             are running on a new enough Juju default to controller-side storage,