File: //usr/share/doc/python3-django-postorius/html/development.html
<!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"><meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Deployment" href="deployment.html" /><link rel="prev" title="Installation" href="setup.html" />
<!-- Generated with Sphinx 7.2.6 and Furo 2023.09.10 -->
<title>Development - Postorius 1.3.10 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b76e3c8a" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=0f5ed9ba" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=e61b947c" />
<style>
body {
--color-code-background: #eeffcc;
--color-code-foreground: black;
}
@media not print {
body[data-theme="dark"] {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
@media (prefers-color-scheme: dark) {
body:not([data-theme="light"]) {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
}
}
</style></head>
<body>
<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">Postorius 1.3.10 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" 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">Postorius 1.3.10 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="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">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="setup.html">Installation</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Development</a></li>
<li class="toctree-l1"><a class="reference internal" href="deployment.html">Deployment</a></li>
<li class="toctree-l1"><a class="reference internal" href="news.html">News / Changelog</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" 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 id="development">
<h1>Development<a class="headerlink" href="#development" title="Link to this heading">#</a></h1>
<p>This is a short guide to help you get started with Postorius development.</p>
<section id="development-workflow">
<h2>Development Workflow<a class="headerlink" href="#development-workflow" title="Link to this heading">#</a></h2>
<p>The source code is hosted on <a class="reference external" href="https://gitlab.com/mailman/postorius">GitLab</a>, which means that we are using
Git for version control.</p>
<p>Changes are not made directly in the project’s master branch, but in
feature-related personal branches, which get reviewed and then merged into
the master branch. There is a contribution guide <a class="reference external" href="http://wiki.list.org/DEV/HowToContributeGit">here</a>, that mentions the basics
about contributing to any mailman project.</p>
<p>An ideal workflow would be like this:</p>
<ol class="arabic simple">
<li><p>File a bug to suggest a new feature or report a bug (or just pick one of
the existing bugs).</p></li>
<li><p>Create a new branch with your code changes.</p></li>
<li><p>Make a “merge request” to get your code reviewed and merged.</p></li>
</ol>
</section>
<section id="first-contributions-coverage-reports">
<h2>First Contributions / Coverage Reports<a class="headerlink" href="#first-contributions-coverage-reports" title="Link to this heading">#</a></h2>
<p>If you don’t know how you can contribute,
writing tests is a good way to get you started.</p>
<p>You can start by exploring the existing <a class="reference external" href="https://mailman.gitlab.io/postorius/index.html">test coverage</a>
and finding code that’s not covered ie. not tested.</p>
</section>
<section id="installing-and-running-the-tests">
<h2>Installing and running the tests<a class="headerlink" href="#installing-and-running-the-tests" title="Link to this heading">#</a></h2>
<p>After checkout you can run the tests using <code class="docutils literal notranslate"><span class="pre">tox</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ tox
</pre></div>
</div>
<p>By default this will test against a couple of different environments.
If you want to only run the tests in a specific environment or a single
module, you can specify this using the <code class="docutils literal notranslate"><span class="pre">-e</span></code> option and/or a double
dash:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span># List all currently configured envs:
$ tox -l
py36-django22
py36-django31
py36-django32
py36-django-latest
py37-django22
py37-django31
py37-django32
py37-django-latest
py38-django22
py38-django31
py38-django32
py38-django-latest
py39-django22
py39-django31
py39-django32
py39-django-latest
py310-django22
py310-django31
py310-django32
py310-django-latest
# Test Django 3.2 on Python3.7 only:
$ tox -e py37-django32
# Run only tests in ``test_address_activation.py``:
$ tox -e py37-django32-- src/postoriustests/test_address_activation.py
# You get the idea...
$ tox -e py37-django32 -- postorius.tests.test_address_activation
</pre></div>
</div>
<p>All test modules reside in the <code class="docutils literal notranslate"><span class="pre">postorius/src/postorius/tests</span></code>
directory. Please have a look at the existing examples.</p>
</section>
<section id="calling-mailman-s-rest-api">
<h2>Calling Mailman’s REST API<a class="headerlink" href="#calling-mailman-s-rest-api" title="Link to this heading">#</a></h2>
<p>A lot of Postorius’ code involves calls to Mailman’s REST API (through the
<code class="docutils literal notranslate"><span class="pre">mailmanclient</span></code> library). Postorius’ test uses <a class="reference external" href="https://docs.pytest.org/en/latest/contents.html">pytest</a> along with
<a class="reference external" href="https://pytest-django.readthedocs.io/en/latest/">pytest-django</a> to run tests.</p>
<p>Postorius uses <a class="reference external" href="https://docs.pytest.org/en/latest/fixture.html">pytest fixtures</a> to setup Mailman Core’s REST API and is
defined at <code class="docutils literal notranslate"><span class="pre">postorius.tests.mailman_api_tests.conftest.mailman_rest_layer</span></code>. It
is set to <code class="docutils literal notranslate"><span class="pre">autouse=True</span></code> so, all the tests inside the module
<code class="docutils literal notranslate"><span class="pre">mailman_api_tests</span></code> automatically use it.</p>
<p><code class="docutils literal notranslate"><span class="pre">mailman_rest_layer</span></code> starts up <code class="docutils literal notranslate"><span class="pre">incoming</span></code> runner and <code class="docutils literal notranslate"><span class="pre">rest</span></code> runner using
<code class="docutils literal notranslate"><span class="pre">mailman.testing.helpersTestableMaster</span></code>. It also removes all the data after
every <code class="docutils literal notranslate"><span class="pre">TestCase</span></code> class.</p>
</section>
<section id="view-authorization">
<h2>View Authorization<a class="headerlink" href="#view-authorization" title="Link to this heading">#</a></h2>
<p>Three of Django’s default User roles are relevant for Postorius:</p>
<ul class="simple">
<li><p>Superuser: Can do everything.</p></li>
<li><p>AnonymousUser: Can view list index and info pages.</p></li>
<li><p>Authenticated users: Can view list index and info pages. Can (un)subscribe
from lists.</p></li>
</ul>
<p>Apart from these default roles, there are two others relevant in Postorius:</p>
<ul class="simple">
<li><p>List owners: Can change list settings, moderate messages and delete their
lists.</p></li>
<li><p>List moderators: Can moderate messages.</p></li>
</ul>
<p>There are a number of decorators to protect views from unauthorized users.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">@user_passes_test(lambda</span> <span class="pre">u:</span> <span class="pre">u.is_superuser)</span></code> (redirects to login form)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">@login_required</span></code> (redirects to login form)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">@list_owner_required</span></code> (returns 403 if logged-in user isn’t the
list’s owner)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">@list_moderator_required</span></code> (returns 403 if logged-in user isn’t the
list’s moderator)</p></li>
</ul>
</section>
<section id="accessing-the-mailman-api">
<h2>Accessing the Mailman API<a class="headerlink" href="#accessing-the-mailman-api" title="Link to this heading">#</a></h2>
<p>Postorius uses mailmanclient to connect to Mailman’s REST API. In order to
directly use the client, <code class="docutils literal notranslate"><span class="pre">cd</span></code> to the <code class="docutils literal notranslate"><span class="pre">example_project</span></code> folder and execute
<code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">manage.py</span> <span class="pre">mmclient</span></code>. This will open a python shell (IPython, if
that’s available) and provide you with a client object connected to your
local Mailman API server (it uses the credentials from your settings.py).</p>
<p>A quick example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python manage.py mmclient
>>> client
<Client (user:pwd) http://localhost:8001/3.1/>
>>> print(client.system['mailman_version'])
GNU Mailman 3.0.0b2+ (Here Again)
>>> mailman_dev = client.get_list('mailman-developers@python.org')
>>> print(mailman_dev.settings)
{u'description': u'Mailman development',
u'default_nonmember_action': u'hold', ...}
</pre></div>
</div>
<p>For detailed information how to use mailmanclient, check out its <a class="reference external" href="http://docs.mailman3.org/projects/mailmanclient/en/latest/using.html">documentation</a>.</p>
</section>
</section>
</article>
</div>
<footer>
<div class="related-pages">
<a class="next-page" href="deployment.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Deployment</div>
</div>
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="setup.html">
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">Installation</div>
</div>
</a>
</div>
<div class="bottom-of-page">
<div class="left-details">
<div class="copyright">
Copyright © 2024, The Free Software Foundation
</div>
Made with <a href="https://www.sphinx-doc.org/">Sphinx</a> and <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s
<a href="https://github.com/pradyunsg/furo">Furo</a>
</div>
<div class="right-details">
</div>
</div>
</footer>
</div>
<aside class="toc-drawer">
<div class="toc-sticky toc-scroll">
<div class="toc-title-container">
<span class="toc-title">
On this page
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">Development</a><ul>
<li><a class="reference internal" href="#development-workflow">Development Workflow</a></li>
<li><a class="reference internal" href="#first-contributions-coverage-reports">First Contributions / Coverage Reports</a></li>
<li><a class="reference internal" href="#installing-and-running-the-tests">Installing and running the tests</a></li>
<li><a class="reference internal" href="#calling-mailman-s-rest-api">Calling Mailman’s REST API</a></li>
<li><a class="reference internal" href="#view-authorization">View Authorization</a></li>
<li><a class="reference internal" href="#accessing-the-mailman-api">Accessing the Mailman API</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=0034329e"></script>
<script src="_static/doctools.js?v=888ff710"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=3e7832f7"></script>
</body>
</html>