Add section for creating deferred events.

canonical · Aug 20, 2024 · 7b868f6 · 7b868f6
1 parent 6d4086a
commit 7b868f6
Show file tree

Hide file tree

Showing 77 changed files with 23,180 additions and 0 deletions.
diff --git a/UPGRADING.md b/UPGRADING.md
@@ -243,6 +243,31 @@ state = State(networks={"foo": Network.default()})
 state = State(networks={Network.default("foo")})
 ```
 
+### Use the .deferred() method to populate State.deferred
+
+Previously, there were multiple methods to populate the `State.deferred` list:
+events with a `.deferred()` method, the `scenario.deferred()` method, and
+creating a `DeferredEvent` object manually. Now, for Juju events, you should
+always use the `.deferred()` method of the event - this also ensures that the
+deferred event has all of the required links (to relations, containers, secrets,
+and so on).
+
+```python
+# Older Scenario code
+deferred_start = scenario.deferred('start', handler=MyCharm._on_start)
+deferred_relation_created = Relation('foo').changed_event.deferred(handler=MyCharm._on_foo_relation_changed)
+deferred_config_changed = DeferredEvent(
+    handle_path='MyCharm/on/config_changed[1]',
+    owner='MyCharm',
+    observer='_on_config_changed'
+)
+
+# Scenario 7.x
+deferred_start = ctx.on.start().deferred(handler=MyCharm._on_start)
+deferred_relation_changed = ctx.on.relation_changed(Relation('foo')).deferred(handler=MyCharm._on_foo_relation_changed)
+deferred_config_changed = ctx.on.config_changed().deferred(handler=MyCharm._on_config_changed)
+```
+
 ### Update names: State.storages, State.stored_states, Container.execs, Container.service_statuses
 
 The `State.storage` and `State.stored_state` attributes are now plurals. This

diff --git a/docs/_build/html/.buildinfo b/docs/_build/html/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: cb630d145fb79f914052923f2f8ce54d
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/_build/html/.doctrees/capture_events.doctree b/docs/_build/html/.doctrees/capture_events.doctree
diff --git a/docs/_build/html/.doctrees/consistency_checker.doctree b/docs/_build/html/.doctrees/consistency_checker.doctree
diff --git a/docs/_build/html/.doctrees/context.doctree b/docs/_build/html/.doctrees/context.doctree
diff --git a/docs/_build/html/.doctrees/environment.pickle b/docs/_build/html/.doctrees/environment.pickle
diff --git a/docs/_build/html/.doctrees/index.doctree b/docs/_build/html/.doctrees/index.doctree
diff --git a/docs/_build/html/.doctrees/state.doctree b/docs/_build/html/.doctrees/state.doctree
diff --git a/docs/_build/html/404.html b/docs/_build/html/404.html
@@ -0,0 +1,332 @@
+<!doctype html>
+<html class="no-js" lang="en" data-content_root="">
+  <head><meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width,initial-scale=1"/>
+    <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="/genindex.html" /><link rel="search" title="Search" href="/search.html" />
+
+    <link rel="shortcut icon" href="/_static/favicon.png"/><!-- Generated with Sphinx 6.2.1 and Furo 2024.01.29 -->
+        <title>Page not found - Scenario documentation</title>
+      <link rel="stylesheet" type="text/css" href="/_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="/_static/styles/furo.css?digest=369552022d0b975c8e74270ce6eabe0fb7978f24" />
+    <link rel="stylesheet" type="text/css" href="/_static/copybutton.css" />
+    <link rel="stylesheet" type="text/css" href="/_static/youtube.css" />
+    <link rel="stylesheet" type="text/css" href="/_static/related-links.css" />
+    <link rel="stylesheet" type="text/css" href="/_static/terminal-output.css" />
+    <link rel="stylesheet" type="text/css" href="/_static/tabs.css" />
+    <link rel="stylesheet" type="text/css" href="/_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css" />
+    <link rel="stylesheet" type="text/css" href="/_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
+    <link rel="stylesheet" type="text/css" href="/_static/custom.css" />
+    <link rel="stylesheet" type="text/css" href="/_static/header.css" />
+    <link rel="stylesheet" type="text/css" href="/_static/github_issue_links.css" />
+    <link rel="stylesheet" type="text/css" href="/_static/furo_colors.css" />
+
+</head>
+  <body>
+    <header id="header" class="p-navigation">
+
+  <div class="p-navigation__nav" role="menubar">
+
+    <ul class="p-navigation__links" role="menu">
+
+      <li>
+        <a class="p-logo" href="https://juju.is/docs/sdk" aria-current="page">
+          <img src="/_static/tag.png" alt="Logo" class="p-logo-image">
+          <div class="p-logo-text p-heading--4">Scenario
+          </div>
+        </a>
+      </li>
+
+      <li class="nav-ubuntu-com">
+        <a href="https://juju.is/docs/sdk" class="p-navigation__link">juju.is/docs/sdk</a>
+      </li>
+
+      <li>
+        <a href="#" class="p-navigation__link nav-more-links">More resources</a>
+        <ul class="more-links-dropdown">
+
+          <li>
+            <a href="https://discourse.charmhub.io/" class="p-navigation__sub-link p-dropdown__link">Forum</a>
+          </li>
+
+          <li>
+            <a href="https://github.com/canonical/ops-scenario" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
+          </li>
+
+        </ul>
+      </li>
+
+    </ul>
+  </div>
+</header>
+
+    <script>
+      document.body.dataset.theme = localStorage.getItem("theme") || "auto";
+    </script>
+
+
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+  <symbol id="svg-toc" viewBox="0 0 24 24">
+    <title>Contents</title>
+    <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
+      <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-menu" viewBox="0 0 24 24">
+    <title>Menu</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
+      <line x1="3" y1="12" x2="21" y2="12"></line>
+      <line x1="3" y1="6" x2="21" y2="6"></line>
+      <line x1="3" y1="18" x2="21" y2="18"></line>
+    </svg>
+  </symbol>
+  <symbol id="svg-arrow-right" viewBox="0 0 24 24">
+    <title>Expand</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
+      <polyline points="9 18 15 12 9 6"></polyline>
+    </svg>
+  </symbol>
+  <symbol id="svg-sun" viewBox="0 0 24 24">
+    <title>Light mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
+      <circle cx="12" cy="12" r="5"></circle>
+      <line x1="12" y1="1" x2="12" y2="3"></line>
+      <line x1="12" y1="21" x2="12" y2="23"></line>
+      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+      <line x1="1" y1="12" x2="3" y2="12"></line>
+      <line x1="21" y1="12" x2="23" y2="12"></line>
+      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+    </svg>
+  </symbol>
+  <symbol id="svg-moon" viewBox="0 0 24 24">
+    <title>Dark mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
+    </svg>
+  </symbol>
+  <symbol id="svg-sun-half" viewBox="0 0 24 24">
+    <title>Auto light/dark mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
+      <circle cx="12" cy="12" r="9" />
+      <path d="M13 12h5" />
+      <path d="M13 15h4" />
+      <path d="M13 18h1" />
+      <path d="M13 9h4" />
+      <path d="M13 6h1" />
+    </svg>
+  </symbol>
+</svg>
+
+<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
+<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
+<label class="overlay sidebar-overlay" for="__navigation">
+  <div class="visually-hidden">Hide navigation sidebar</div>
+</label>
+<label class="overlay toc-overlay" for="__toc">
+  <div class="visually-hidden">Hide table of contents sidebar</div>
+</label>
+
+
+
+<div class="page">
+  <header class="mobile-header">
+    <div class="header-left">
+      <label class="nav-overlay-icon" for="__navigation">
+        <div class="visually-hidden">Toggle site navigation sidebar</div>
+        <i class="icon"><svg><use href="#svg-menu"></use></svg></i>
+      </label>
+    </div>
+    <div class="header-center">
+      <a href="/index.html"><div class="brand">Scenario documentation</div></a>
+    </div>
+    <div class="header-right">
+      <div class="theme-toggle-container theme-toggle-header">
+        <button class="theme-toggle">
+          <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
+          <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
+          <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+          <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+        </button>
+      </div>
+      <label class="toc-overlay-icon toc-header-icon no-toc" for="__toc">
+        <div class="visually-hidden">Toggle table of contents sidebar</div>
+        <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+      </label>
+    </div>
+  </header>
+  <aside class="sidebar-drawer">
+    <div class="sidebar-container">
+
+      <div class="sidebar-sticky"><a class="sidebar-brand" href="/index.html">
+
+
+  <span class="sidebar-brand-text">Scenario documentation</span>
+
+</a><form class="sidebar-search-container" method="get" action="/search.html" role="search">
+    <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
+    <input type="submit" value="Go">
+    <input type="hidden" name="check_keywords" value="yes">
+    <input type="hidden" name="area" value="default">
+  </form>
+  <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
+  <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="/context.html">scenario.Context</a></li>
+<li class="toctree-l1"><a class="reference internal" href="/state.html">scenario.State</a></li>
+<li class="toctree-l1"><a class="reference internal" href="/capture_events.html">scenario.capture_events</a></li>
+<li class="toctree-l1"><a class="reference internal" href="/consistency_checker.html">scenario.consistency_checker</a></li>
+</ul>
+
+</div>
+</div>
+
+      </div>
+
+    </div>
+  </aside>
+  <div class="main">
+    <div class="content">
+      <div class="article-container">
+        <a href="#" class="back-to-top muted-link">
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+            <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
+          </svg>
+          <span>Back to top</span>
+        </a>
+        <div class="content-icon-container">
+          <div class="theme-toggle-container theme-toggle-content">
+            <button class="theme-toggle">
+              <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
+              <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
+              <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+              <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+            </button>
+          </div>
+          <label class="toc-overlay-icon toc-content-icon no-toc" for="__toc">
+            <div class="visually-hidden">Toggle table of contents sidebar</div>
+            <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+          </label>
+        </div>
+        <article role="main">
+          <section>
+  <h1>Page not found</h1>
+  <div class="sd-container-fluid sd-sphinx-override sd-mb-4 docutils">
+    <div class="sd-row sd-row-cols-1 sd-row-cols-xs-1 sd-row-cols-sm-1 sd-row-cols-md-2 sd-row-cols-lg-2 sd-g-5 sd-g-xs-5 sd-g-sm-5 sd-g-md-5 sd-g-lg-5 docutils">
+      <div class="sd-col sd-d-flex-column docutils">
+        <p><strong>Sorry, but the documentation page that you are looking for was not found.</strong></p>
+
+<p>Documentation changes over time, and pages are moved around. We try to redirect you to the updated content where possible, but unfortunately, that didn't work this time (maybe because the content you were looking for does not exist in this version of the documentation).</p>
+<p>You can try to use the navigation to locate the content you're looking for, or search for a similar page.</p>
+
+      </div>
+      <div class="sd-col sd-d-flex-column docutils">
+        <img alt="Penguin with a question mark" class="align-center" height="283" src="/_static/404.svg" width="287" />
+      </div>
+    </div>
+  </div>
+</section>
+        </article>
+      </div>
+      <footer>
+
+
+
+<div class="related-pages">
+
+
+
+
+</div>
+<div class="bottom-of-page">
+  <div class="left-details">
+    <div class="copyright">
+        Copyright &#169; 2024, Canonical Ltd.
+    </div>
+
+    <div class="last-updated">
+      Last updated on Aug 13, 2024</div>
+  </div>
+  <div class="right-details">
+
+
+
+
+    <div class="ask-discourse">
+      <a class="muted-link" href="https://discourse.charmhub.io/">Ask a question on Discourse</a>
+    </div>
+
+
+
+
+
+    <div class="ask-matrix">
+      <a class="muted-link" href="https://matrix.to/#/#charmhub-charmdev:ubuntu.com">Ask a question on Matrix</a>
+    </div>
+
+
+
+
+
+    <div class="issue-github">
+      <a class="muted-link" href="https://github.com/canonical/ops-scenario/issues/new?title=doc%3A+ADD+A+TITLE&body=DESCRIBE+THE+ISSUE%0A%0A---%0ADocument: 404">Open a GitHub issue for this page</a>
+    </div>
+
+
+    <div class="edit-github">
+      <a class="muted-link" href="https://github.com/canonical/ops-scenario/edit/main/docs/404">Edit this page on GitHub</a>
+    </div>
+
+
+
+    </div>
+  </div>
+</div>
+
+      </footer>
+    </div>
+    <aside class="toc-drawer no-toc">
+
+<div class="toc-sticky toc-scroll">
+
+    <div class="toc-title-container">
+      <span class="toc-title">
+       Contents
+      </span>
+    </div>
+    <div class="toc-tree-container">
+      <div class="toc-tree">
+
+      </div>
+    </div>
+
+
+  </div>
+
+    </aside>
+  </div>
+</div><script src="/_static/jquery.js"></script>
+    <script src="/_static/_sphinx_javascript_frameworks_compat.js"></script>
+    <script data-url_root="#" id="documentation_options" src="/_static/documentation_options.js"></script>
+    <script src="/_static/doctools.js"></script>
+    <script src="/_static/sphinx_highlight.js"></script>
+    <script src="/_static/scripts/furo.js"></script>
+    <script src="/_static/clipboard.min.js"></script>
+    <script src="/_static/copybutton.js"></script>
+    <script src="/_static/tabs.js"></script>
+    <script src="/_static/design-tabs.js"></script>
+    <script src="/_static/header-nav.js"></script>
+    <script src="/_static/github_issue_links.js"></script>
+
+<script>
+  const github_url = "https://github.com/canonical/ops-scenario";
+</script>
+</body>
+</html>