Zulip has a number of Django management commands that
If you need some Python code to run with a Zulip context (access to
the database, etc.) in a script, it should probably go in a management
command. The key thing distinguishing these from production scripts
scripts/) and development scripts (
tools/) is that management
commands can access the database.
While Zulip takes advantage of built-in Django management commands for things like managing Django migrations, we also have dozens that we’ve written for a range of purposes:
- Cron jobs to do regular updates, e.g.
- Useful parts of provisioning or upgrading a Zulip development
environment or server, e.g.
- The actual scripts run by supervisord to run the persistent
processes in a Zulip server, e.g.
- For a sysadmin to verify a Zulip server’s configuration during
- As the interface for doing those rare operations that don’t have a
UI yet, e.g.
change_user_email(for the case where the user doesn’t control the old email address).
- For a sysadmin to easily interact with and script common possible
changes they might want to make to the database on a Zulip server.
Writing management commands¶
It’s generally pretty easy to template off an existing management
command to write a new one. Some good examples are
deactivate_realm. The Django documentation
is good, but we have a few pieces advice specific to the Zulip
- If you need to access a realm or user, use the
zerver/lib/management.pyso you don’t need to write the tedious code of looking those objects up. This is especially important for users, since the library handles the issues around looking up users by email well (if there’s a unique user with that email, just modify it without requiring the user to specify the realm as well, but if there’s a collision, throw a nice error).
- Avoid writing a lot of code in management commands; management
commands are annoying to unit test, and thus easier to maintain if
all the interesting logic is in a nice function that is unit tested
(and ideally, also used in Zulip’s existing code). Look for code in
zerver/lib/that already does what you need. For most actions, you can just call a
do_change_footype function from
zerver/lib/actions.pyto do all the work; this is usually far better than manipulating the database correctly, since the library functions used by the UI are maintained to correctly live-update the UI if needed.