# django-routines
[](https://opensource.org/licenses/MIT)
[](https://github.com/astral-sh/ruff)
[](https://pypi.python.org/pypi/django-routines/)
[](https://pypi.python.org/pypi/django-routines/)
[](https://pypi.org/project/django-routines/)
[](https://pypi.python.org/pypi/django-routines)
[](http://django-routines.readthedocs.io/?badge=latest/)
[](https://codecov.io/gh/bckohan/django-routines)
[](https://github.com/bckohan/django-routines/actions/workflows/test.yml)
[](https://github.com/bckohan/django-routines/actions/workflows/lint.yml)
Configure batches of Django management commands in your settings files and run them all at once. For example, batch together your common database maintenance tasks, deployment routines or any other set of commands you need to run together. This helps single source general site maintenance into your settings files keeping your code base [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).
## Example
Let's define two named routines, "package" and "deploy". The package routine will be a collection of commands that we typically run to generate package artifacts (like migrations and transpiled javascript). The deploy routine will be a collection of commands we typically run when deploying the site for the first time on a new server or when we deploy version updates on the server.
**Routine commands are run in the order they are registered, or by [priority](#priorities).**
There are two types of commands, management commands and system commands. The management commands will be called in the same process space as routine unless --subprocess is specified in which case they will use the same management script as routine was invoked with or whatever value you supply to --manage-script. System commands are always invoked as subprocesses.
In our settings file we may define these routines like this:
```python
from django_routines import (
ManagementCommand,
SystemCommand,
command,
system,
routine
)
# register routines and their help text
routine(
name="package",
help_text=(
"Generate pre-package artifacts like migrations and transpiled "
"javascript."
)
)
# you may register commands on a routine after defining a routine (or before!)
command("package", "makemigrations")
command("package", "renderstatic")
system("package", "poetry", "build")
routine(
"deploy",
"Deploy the site application into production.",
# you may also specify commands inline using the ManagementCommand dataclass
ManagementCommand(
("routine", "package"), switches=["prepare"]
), # routine commands can be other routines!
ManagementCommand("migrate"),
ManagementCommand("collectstatic"),
ManagementCommand(("shellcompletion", "install"), switches=["initial"]),
ManagementCommand(("loaddata", "./fixtures/demo.json"), switches=["demo"]),
SystemCommand(("touch", "/path/to/wsgi.py")),
# define switches that toggle commands on and off
prepare="Generate artifacts like migrations and transpiled javascript.",
initial="Things to do on the very first deployment on a new server.",
demo="Load the demo data.",
)
```
The routine command will read our settings file and generate two subcommands, one called deploy and one called package:
Now we can run all of our package routines with one command:
```bash
?> ./manage.py routine package
makemigrations
...
renderstatic
...
poetry build
...
```
The deploy command has several switches that we can enable to run additional commands.
For example to deploy our demo on a new server we would run:
```bash
?> ./manage.py routine deploy --initial --demo
migrate
...
collectstatic
...
shellcompletion install
...
loaddata ./fixtures/demo.json
...
touch /path/to/wsgi.py
```
## Settings
The [ManagementCommand](https://django-routines.readthedocs.io/en/latest/reference.html#django_routines.ManagementCommand) dataclass, [routine](https://django-routines.readthedocs.io/en/latest/reference.html#django_routines.routine) and [command](https://django-routines.readthedocs.io/en/latest/reference.html#django_routines.command) helper functions in the example above make it easier for us to work with the native configuration format which is a dictionary structure defined in the ``DJANGO_ROUTINES`` setting attribute. For example the above configuration is equivalent to:
```python
DJANGO_ROUTINES = {
"deploy": {
"commands": [
{"command": ("routine", "package"), "switches": ["prepare"]},
{"command": "migrate"},
{"command": "collectstatic"},
{
"command": ("shellcompletion", "install"),
"switches": ["initial"],
},
{
"command": ("loaddata", "./fixtures/demo.json"),
"switches": ["demo"],
},
{"command": ("touch", "/path/to/wsgi.py"), "kind": "system"},
],
"help_text": "Deploy the site application into production.",
"name": "deploy",
"switch_helps": {
"demo": "Load the demo data.",
"initial": "Things to do on the very first deployment on a new "
"server.",
"prepare": "Generate artifacts like migrations and transpiled "
"javascript.",
},
},
"package": {
"commands": [
{"command": "makemigrations"},
{"command": "renderstatic"},
{"command": ("poetry", "build"), "kind": "system"},
],
"help_text": "Generate pre-package artifacts like migrations and "
"transpiled javascript.",
"name": "package",
},
}
```
## Priorities
If you are composing settings from multiple apps or source files using a utility like [django-split-settings](https://pypi.org/project/django-split-settings/) you may not be able to define all routines at once. You can use priorities to make sure commands defined in a de-coupled way run in the correct order.
```python
command("deploy", "makemigrations", priority=1)
command("deploy", "migrate", priority=2)
```
## Options
When specifying arguments you may add them to the command tuple OR specify them as named options in the style that will be passed to [call_command](https://docs.djangoproject.com/en/stable/ref/django-admin/#django.core.management.call_command):
```python
# these two are equivalent
command("package", "makemigrations", "--no-header")
command("package", "makemigrations", no_header=True)
```
## Execution Controls
There are several switches that can be used to control the execution of routines. Pass these parameters when you define the Routine.
- ``atomic``: Run the routine in a transaction.
- ``continue_on_error``: Continue running the routine even if a command fails.
The default routine behavior for these execution controls can be overridden on the command line.
## Installation
1. Clone django-routines from [GitHub](https://github.com/bckohan/django-routines) or install a release off [PyPI](https://pypi.python.org/pypi/django-routines) :
```bash
pip install django-routines
```
[rich](https://rich.readthedocs.io/) is a powerful library for rich text and beautiful formatting in the terminal. It is not required, but highly recommended for the best experience:
```bash
pip install "django-routines[rich]"
```
2. Add ``django_routines`` to your ``INSTALLED_APPS`` setting:
```python
INSTALLED_APPS = [
...
'django_routines',
'django_typer', # optional!
]
```
*You only need to install [django_typer](https://github.com/bckohan/django-typer) as an app if you want to use the shellcompletion command to [enable tab-completion](https://django-typer.readthedocs.io/en/latest/shell_completion.html) or if you would like django-typer to install [rich traceback rendering](https://django-typer.readthedocs.io/en/latest/howto.html#configure-rich-stack-traces) for you - which it does by default if rich is also installed.*
## Rationale
When does it make sense to configure routines in Django settings? Its generally convenient to group common management pathways into easily discoverable and executable aggregations of subroutines. This is usually done in supporting shell scripts or just files and in most cases that is appropriate. If your goal is to keep your Django deployment as tight and self contained as possible and the deployment is not generally very complex, using django-routines can make a lot of sense. It can eliminate extra dependencies on a shell scripting environment or just files and can keep this logic packaged with your installable wheel.
Raw data
{
"_id": null,
"home_page": "https://django-routines.readthedocs.io",
"name": "django-routines",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "django, CLI, management, routine, routines, batch, commands, deploy, tasks, package, backup",
"author": "Brian Kohan",
"author_email": "bckohan@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/dc/bd/54380fa6bc66255615c7b81a4b257a459dcf610d71f713d3e6c347011c5b/django_routines-1.2.1.tar.gz",
"platform": null,
"description": "# django-routines\n\n\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/astral-sh/ruff)\n[](https://pypi.python.org/pypi/django-routines/)\n[](https://pypi.python.org/pypi/django-routines/)\n[](https://pypi.org/project/django-routines/)\n[](https://pypi.python.org/pypi/django-routines)\n[](http://django-routines.readthedocs.io/?badge=latest/)\n[](https://codecov.io/gh/bckohan/django-routines)\n[](https://github.com/bckohan/django-routines/actions/workflows/test.yml)\n[](https://github.com/bckohan/django-routines/actions/workflows/lint.yml)\n\n\nConfigure batches of Django management commands in your settings files and run them all at once. For example, batch together your common database maintenance tasks, deployment routines or any other set of commands you need to run together. This helps single source general site maintenance into your settings files keeping your code base [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).\n\n## Example\n\nLet's define two named routines, \"package\" and \"deploy\". The package routine will be a collection of commands that we typically run to generate package artifacts (like migrations and transpiled javascript). The deploy routine will be a collection of commands we typically run when deploying the site for the first time on a new server or when we deploy version updates on the server.\n\n**Routine commands are run in the order they are registered, or by [priority](#priorities).**\n\nThere are two types of commands, management commands and system commands. The management commands will be called in the same process space as routine unless --subprocess is specified in which case they will use the same management script as routine was invoked with or whatever value you supply to --manage-script. System commands are always invoked as subprocesses.\n\nIn our settings file we may define these routines like this:\n\n```python\nfrom django_routines import (\n ManagementCommand,\n SystemCommand,\n command,\n system,\n routine\n)\n\n# register routines and their help text\nroutine(\n name=\"package\",\n help_text=(\n \"Generate pre-package artifacts like migrations and transpiled \"\n \"javascript.\"\n )\n)\n# you may register commands on a routine after defining a routine (or before!)\ncommand(\"package\", \"makemigrations\")\ncommand(\"package\", \"renderstatic\")\nsystem(\"package\", \"poetry\", \"build\")\n\nroutine(\n \"deploy\",\n \"Deploy the site application into production.\",\n\n # you may also specify commands inline using the ManagementCommand dataclass\n ManagementCommand(\n (\"routine\", \"package\"), switches=[\"prepare\"]\n ), # routine commands can be other routines!\n ManagementCommand(\"migrate\"),\n ManagementCommand(\"collectstatic\"),\n ManagementCommand((\"shellcompletion\", \"install\"), switches=[\"initial\"]),\n ManagementCommand((\"loaddata\", \"./fixtures/demo.json\"), switches=[\"demo\"]),\n SystemCommand((\"touch\", \"/path/to/wsgi.py\")),\n\n # define switches that toggle commands on and off\n prepare=\"Generate artifacts like migrations and transpiled javascript.\",\n initial=\"Things to do on the very first deployment on a new server.\",\n demo=\"Load the demo data.\",\n)\n```\n\nThe routine command will read our settings file and generate two subcommands, one called deploy and one called package:\n\n\n\nNow we can run all of our package routines with one command:\n\n```bash\n ?> ./manage.py routine package\n makemigrations\n ...\n renderstatic\n ...\n poetry build\n ...\n```\n\nThe deploy command has several switches that we can enable to run additional commands.\n\n\n\nFor example to deploy our demo on a new server we would run:\n\n```bash\n ?> ./manage.py routine deploy --initial --demo\n migrate\n ...\n collectstatic\n ...\n shellcompletion install\n ...\n loaddata ./fixtures/demo.json\n ...\n touch /path/to/wsgi.py\n```\n\n## Settings\n\nThe [ManagementCommand](https://django-routines.readthedocs.io/en/latest/reference.html#django_routines.ManagementCommand) dataclass, [routine](https://django-routines.readthedocs.io/en/latest/reference.html#django_routines.routine) and [command](https://django-routines.readthedocs.io/en/latest/reference.html#django_routines.command) helper functions in the example above make it easier for us to work with the native configuration format which is a dictionary structure defined in the ``DJANGO_ROUTINES`` setting attribute. For example the above configuration is equivalent to:\n\n```python\nDJANGO_ROUTINES = {\n \"deploy\": {\n \"commands\": [\n {\"command\": (\"routine\", \"package\"), \"switches\": [\"prepare\"]},\n {\"command\": \"migrate\"},\n {\"command\": \"collectstatic\"},\n {\n \"command\": (\"shellcompletion\", \"install\"),\n \"switches\": [\"initial\"],\n },\n {\n \"command\": (\"loaddata\", \"./fixtures/demo.json\"),\n \"switches\": [\"demo\"],\n },\n {\"command\": (\"touch\", \"/path/to/wsgi.py\"), \"kind\": \"system\"},\n ],\n \"help_text\": \"Deploy the site application into production.\",\n \"name\": \"deploy\",\n \"switch_helps\": {\n \"demo\": \"Load the demo data.\",\n \"initial\": \"Things to do on the very first deployment on a new \"\n \"server.\",\n \"prepare\": \"Generate artifacts like migrations and transpiled \"\n \"javascript.\",\n },\n },\n \"package\": {\n \"commands\": [\n {\"command\": \"makemigrations\"},\n {\"command\": \"renderstatic\"},\n {\"command\": (\"poetry\", \"build\"), \"kind\": \"system\"},\n ],\n \"help_text\": \"Generate pre-package artifacts like migrations and \"\n \"transpiled javascript.\",\n \"name\": \"package\",\n },\n}\n```\n\n\n## Priorities\n\nIf you are composing settings from multiple apps or source files using a utility like [django-split-settings](https://pypi.org/project/django-split-settings/) you may not be able to define all routines at once. You can use priorities to make sure commands defined in a de-coupled way run in the correct order.\n\n```python\n command(\"deploy\", \"makemigrations\", priority=1)\n command(\"deploy\", \"migrate\", priority=2)\n```\n\n## Options\n\nWhen specifying arguments you may add them to the command tuple OR specify them as named options in the style that will be passed to [call_command](https://docs.djangoproject.com/en/stable/ref/django-admin/#django.core.management.call_command):\n\n```python\n # these two are equivalent\n command(\"package\", \"makemigrations\", \"--no-header\")\n command(\"package\", \"makemigrations\", no_header=True)\n```\n\n## Execution Controls\n\nThere are several switches that can be used to control the execution of routines. Pass these parameters when you define the Routine.\n\n- ``atomic``: Run the routine in a transaction.\n- ``continue_on_error``: Continue running the routine even if a command fails.\n\nThe default routine behavior for these execution controls can be overridden on the command line.\n\n\n## Installation\n\n\n1. Clone django-routines from [GitHub](https://github.com/bckohan/django-routines) or install a release off [PyPI](https://pypi.python.org/pypi/django-routines) :\n\n ```bash\n pip install django-routines\n ```\n\n [rich](https://rich.readthedocs.io/) is a powerful library for rich text and beautiful formatting in the terminal. It is not required, but highly recommended for the best experience:\n\n ```bash\n pip install \"django-routines[rich]\"\n ```\n\n\n2. Add ``django_routines`` to your ``INSTALLED_APPS`` setting:\n\n ```python\n INSTALLED_APPS = [\n ...\n 'django_routines',\n 'django_typer', # optional!\n ]\n ```\n\n *You only need to install [django_typer](https://github.com/bckohan/django-typer) as an app if you want to use the shellcompletion command to [enable tab-completion](https://django-typer.readthedocs.io/en/latest/shell_completion.html) or if you would like django-typer to install [rich traceback rendering](https://django-typer.readthedocs.io/en/latest/howto.html#configure-rich-stack-traces) for you - which it does by default if rich is also installed.*\n\n## Rationale\n\nWhen does it make sense to configure routines in Django settings? Its generally convenient to group common management pathways into easily discoverable and executable aggregations of subroutines. This is usually done in supporting shell scripts or just files and in most cases that is appropriate. If your goal is to keep your Django deployment as tight and self contained as possible and the deployment is not generally very complex, using django-routines can make a lot of sense. It can eliminate extra dependencies on a shell scripting environment or just files and can keep this logic packaged with your installable wheel.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Define named groups of management commands in Django settings files for batched execution.",
"version": "1.2.1",
"project_urls": {
"Homepage": "https://django-routines.readthedocs.io",
"Repository": "https://github.com/bckohan/django-routines"
},
"split_keywords": [
"django",
" cli",
" management",
" routine",
" routines",
" batch",
" commands",
" deploy",
" tasks",
" package",
" backup"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d5cbe49475f9c7e37e08fc716c13e584d89c61f610edae9c1ea57d5c770f25ea",
"md5": "fa150e1ba45936642b7f43f12f913fbc",
"sha256": "5df810fa21ed9a4ce76aa4531b5b279587c8e5da49b6f024c1d02a972a212c19"
},
"downloads": -1,
"filename": "django_routines-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa150e1ba45936642b7f43f12f913fbc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 14202,
"upload_time": "2024-08-26T21:23:04",
"upload_time_iso_8601": "2024-08-26T21:23:04.316052Z",
"url": "https://files.pythonhosted.org/packages/d5/cb/e49475f9c7e37e08fc716c13e584d89c61f610edae9c1ea57d5c770f25ea/django_routines-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dcbd54380fa6bc66255615c7b81a4b257a459dcf610d71f713d3e6c347011c5b",
"md5": "7fb3a7bc40f979f79935d1dd6cad70ff",
"sha256": "b4c6c65ed6846cf15e63cc3235b0a513776739255462c5abb5ce7af27ee00511"
},
"downloads": -1,
"filename": "django_routines-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "7fb3a7bc40f979f79935d1dd6cad70ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 16614,
"upload_time": "2024-08-26T21:23:09",
"upload_time_iso_8601": "2024-08-26T21:23:09.347389Z",
"url": "https://files.pythonhosted.org/packages/dc/bd/54380fa6bc66255615c7b81a4b257a459dcf610d71f713d3e6c347011c5b/django_routines-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-26 21:23:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bckohan",
"github_project": "django-routines",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-routines"
}
JSON
