RFE: improve discoverability of the URL configuration
On mailman-users@mailman3.org Odhiambo proposed a working sample urls.py
that site admins could drop into /etc/mailman3
. While this is a good idea in itself it likely requires some additional work, and doesn't really improve discoverability and debuggability of the urlconf.
Specifically, there's a ROOT_URLCONF
variable (currently from site-packages/mailman_web/settings/base.py
, where it points to mailman_web.urls
). It can be set to just urls
in settings.py
, but you may need to prepend /etc/mailman3
to sys.path
somewhere.
None of this is currently easily discoverable. As seen with the OP in the thread cited above, it's also fragile. /mailman3
and /postorius
are not confusable paths: an URI can only match one, but order matters?! And it's complex: sys.path
can be set via the PYTHONPATH
environment variable in your shell or by systemd, it can be set in settings.py or your gunicorn conf (and probably for other WSGI providers like uwsgi and mod_wsgi), or using the --pythonpath option to the mailman-web
utility. In fact this may already be done in mailman_web/settings/*.py
.
There should be enough information above for someone with a minimum understanding of Python code and of packaging, and some experience using the mailman-web utility to
- trace through the code to figure out how the
ROOT_URLCONF
andsys.path
variables are set, - find a relatively early place in the initialization of the mailman-web process to add
/etc/mailman3
tosys.path
if it's not there, - improve documentation of the urlconf, preferably using a working sample root urlconf
I think the arrangement proposed above is a good one for discoverability. Since there has to be a default root urls.py
somewhere, I think it ought to be installed someplace that's visible for non-developer admins, i.e. /etc/mailman3
. I think putting it in site-packages/mailman_web
, while it helps to encourage uniformity of the urlconf across Mailman 3 installations, is really bad for discoverability. So I propose removing site-packages/mailman_web/urls.py
.