Indjections

This project enables one-line installation of Django packages by injecting code in the right places.

Installation

Install using pip:

pip install indjections

or, if using pipenv:

pipenv install indjections --dev

Add 'indjections' to your INSTALLED_APPS setting.

INSTALLED_APPS = [
    ...
    'indjections',
]

Example

By default, indjections assumes your TOML file is a Pipfile in the project root. For example, say your Pipfile has the following packages:

[dev-packages]
django-debug-toolbar = "*"

[packages]
djangorestframework = "*"
django-hijack = "*"

To install these packages, you just have to run a Django management command:

python manage.py indject

This will auto-insert code into settings.py, urls.py, and base.html as described by the package's documentation. For example, for django-hijack, the following snippet is added to settings.py (as described in the documentation):

### block: django-hijack ####
INSTALLED_APPS += ['hijack', 'compat']
### endblock: django-hijack ####

Moreover, if you remove this package from your project's Pipfile and rerun python manage.py indject, then indjections will search for ### block: django-hijack ####/### endblock: django-hijack #### and delete this text.

Note that indjections assumes that base.html is the Django admin base.html and is located at your project root's templates/admin/base.html. If you want to use another base.html, you can add a setting to your project's settings.py:

INDJECTIONS_SETTINGS = {
    'BASE_HTML': os.path.join(BASE_DIR, 'templates', 'custom_base.html')
}

In some cases, a package installer might insert code at the app and model level (see the discussion below for more detail). By default, all apps and models in the project are included. (Obviously, this won't impact third party packages in any way.) To include/exclude a subset, you can add a setting to your project's settings.py:

INDJECTIONS_SETTINGS = {
    'INCLUDE_APPS': {
        'main': ['djangorestframework']  # any list of installation files
    },
}

or

INDJECTIONS_SETTINGS = {
    'EXCLUDE_APPS': {
        'main': ['djangorestframework']  # any list of installation files
    },
}

If both INCLUDE_APPS and EXCLUDE_APPS are specified, an exception will be raised.

Q&A

What if I want to modify the inserted code?

You have two options:

1. If you change ### block: django-hijack #### to ### block: django-hijack/lock ####, then injections will not reinsert code if python manage.py indject is run again. However, if the package is removed from the TOML file, then indjections will delete the block even if lock appears in the block header.
2. indjections installation files are regular Python modules. If you create a custom installation file, indjections will look for custom installers in the custom_installers directory of your project's root directory. For example, if you want to create a custom installer for djangorestframework, you just add a file called {project_root_directory}/custom_installers/djangorestframework.py. Then this version will be used and the default indjections version will be ignored.

What if I don't use pipenv?

The packages can be defined with any TOML file. For example, if you use poetry, then add the following to your project's settings.py:

INDJECTIONS_SETTINGS = {
    'TOML_FILE': os.path.join(BASE_DIR, 'pyproject.toml'),
    'TOML_KEYS': ["tool.poetry.dependencies", "tool.poetry.dev-dependencies"],
}

Does this package run anything in production?

No. indjections is only used during development to help with Django configurations and project setup.

Why do I need another package?

I got tired of installing packages by hand. This project has a similar goal to Cookiecutter Django. I didn't love the cookiecutter approach, so I wrote indjections as an alternative. Cookiecutter Django is a top down approach where packages are all bundled together. So if you don't like something, you need to spend time removing code (or writing your own cookiecutter). indjections is a bottom up approach i.e., you can do the usual django-admin startproject {project_name} and then let python manage.py indject insert code in the right places.

How do I create my own installation file?

indjections looks for a module named indjections.packages.{package_name}. This declaratively defines 6 locations in a Django project:

settings: The bottom of settings.py as defined by the DJANGO_SETTINGS_MODULE environment variable.

urls: The bottom of urls.py as defined by settings.ROOT_URLCONF.

base_top: The very top of base.html e.g., {% load i18n %}

base_head: The bottom of the `` section in base.html e.g., custom CSS.

base_body: The top of the `` section in base.html.

base_finally: The bottom of the `` section in base.html e.g., Javascript `