Skip to content

vint21h/django-mcadmin

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

A django-mcadmin documentation

GitHub Coveralls License Version Supported Python version Supported Django version Package format Python wheel support Package status

django-mcadmin is a Django reusable app that provides simple run management commands from admin
  • Obtain your copy of source code from the git repository: $ git clone https://github.com/vint21h/django-mcadmin.git. Or download the latest release from https://github.com/vint21h/django-mcadmin/tags/.
  • Run $ python ./setup.py install from the repository source tree or unpacked archive. Or use pip: $ pip install django-mcadmin.
  • Add "mcadmin" to settings.INSTALLED_APPS:
# settings.py

INSTALLED_APPS += [
    "mcadmin",
]
  • Add "mcadmin" to your URLs definitions:
# urls.py

from django.urls import re_path, include


urlpatterns += [
    re_path(r"^admin/mcadmin/", include("mcadmin.urls")),
]
  • Run $ python ./manage.py migrate in your project folder to apply app migrations.
MCADMIN_EXAMPLES_PATH
Management commands files templates path. Defaults to: settings.STATIC_ROOT.
MCADMIN_UPLOADS_PATH
Management commands forms with files upload path. Defaults to: settings.MEDIA_ROOT.
MCADMIN_MODULE_NAME
Management commands admin classes search module name. Defaults to: "mcommands".
MCADMIN_USE_PERMISSIONS
Management commands admin classes search module name. Defaults to: False.

For example, exists management command like this:

# management/commands/something-useless.py

from django.core.management.base import BaseCommand


class Command(BaseCommand):

    help: str = "Useless management command"

    def add_arguments(self, parser):

        parser.add_argument(
            "--object-id",
            "-o",
            dest="object_id",
            help="Object ID",
            action="store",
            required=True,
            metavar="OBJECT_ID",
            type=int,
        )

    def handle(self, *args, **kwargs):

        self.stdout.write(kwargs.get("object_id"))

Next, you need to create a form for this management command admin which we use in the next piece of code:

# forms.py

from django import forms


class SomethingUselessManagementCommandAdminForm(forms.Form):

    object_id = forms.IntegerField(label="Object ID", required=True)

And finally, write management command admin class and register it:

# mcommands/something-useless.py

from mcadmin.command import ManagementCommandAdmin
from mcadmin.registry import registry

from forms import SomethingUselessManagementCommandAdminForm


class SomethingUselessManagementCommandAdmin(ManagementCommandAdmin):

    command: str = "something-useless"
    name: str = "Useless management command"
    form: Type[Form] = SomethingUselessManagementCommandAdminForm


# registering management command admin custom classes
registry.register(command=SomethingUselessManagementCommandAdmin)

Also, there are some helpers for building more complex flows, like management commands that can be executed directly or as a background task or management commands that handle uploaded files. For example:

Management command:

# management/commands/distributed-something-useless-with-file.py

from mcadmin.management.commands import TaskCommand


class Command(TaskCommand):

    help: str = "Useless management command which process file uploaded from a command from and can be executed directly or as background task"

    def add_arguments(self, parser):

        parser.add_argument(
            "--task",
            "-T",
            dest="as_task",
            help="Run command as background task",
            default=False,
            action="store",
            metavar="TASK",
            type=bool,
        )
        parser.add_argument(
            "--object-id",
            "-o",
            dest="object_id",
            help="Object ID",
            action="store",
            required=True,
            metavar="OBJECT_ID",
            type=int,
        )
        parser.add_argument(
            "--data",
            "-D",
            dest="data",
            help="Path to file with data",
            action="store",
            metavar="DATA",
            type=str,
        )

    def _local(self, *args, **kwargs):

        self.stdout.write(kwargs.get("object_id"))
        self.stdout.write(kwargs.get("data"))

    def _as_task(self, *args, **kwargs):

        # There must be code which executed in threads or call celery task or something else asynchronous.
        self.stdout.write(kwargs.get("object_id"))
        self.stdout.write(kwargs.get("data"))

Management command admin form:

# forms.py

from django import forms

from mcadmin.forms.helpers import (
    ManagementCommandAdminTaskForm,
    ManagementCommandAdminFilesForm
)


class DistributedSomethingUselessWithFileManagementCommandAdminForm(
    ManagementCommandAdminTaskForm,
    ManagementCommandAdminFilesForm
):

    data = forms.FileField(label="data, required=True)
    object_id = forms.IntegerField(label="Object ID", required=True)

Management command admin example file:

# mcommands/examples.py

from mcadmin.example import ManagementCommandAdminExampleFile


class DistributedSomethingUselessWithFileManagementCommandAdminExampleFile(
    ManagementCommandAdminExampleFile
):

    description: str = "Management command with files example file"
    path: str = "distributed-something-useless-with-file-example.csv"

Or for the file which not served using Django but directly available for download via HTTP:

# mcommands/examples.py

from mcadmin.example import ManagementCommandAdminExampleFile


class DistributedSomethingUselessWithFileManagementCommandAdminExampleFile(
    ManagementCommandAdminExampleFile
):

    description: str = "Management command with files example file"
    path: str = "https://www.example.com/distributed-something-useless-with-file-example.csv"
    raw: bool = True

Management command admin:

# mcommands/something-useless.py

from mcadmin.command import ManagementCommandAdmin
from mcadmin.registry import registry

from forms import DistributedSomethingUselessWithFileManagementCommandAdminForm


class DistributedSomethingUselessWithFileManagementCommandAdmin(ManagementCommandAdmin):

    command: str = "distributed-something-useless-with-file"
    name: str = "Distributed useless management command with file"
    form: Type[Form] = DistributedSomethingUselessWithFileManagementCommandAdminForm
    examples: Type[ManagementCommandAdminExampleFile] = [DistributedSomethingUselessWithFileManagementCommandAdminExampleFile]


# registering management command admin custom classes
registry.register(command=DistributedSomethingUselessWithFileManagementCommandAdmin)
  1. Fork it
  2. Install GNU Make
  3. Install and configure pyenv and pyenv-virtualenv plugin
  4. Install and configure direnv
  5. Create environment config from example
cp .env.example .env
  1. Install development dependencies:
make install
  1. Create your fix/feature branch:
git checkout -b my-new-fix-or-feature
  1. Check code style and moreover:
make check
  1. Run tests:
make test
  1. Push to the branch:
git push origin my-new-fix-or-feature
  1. Create a new Pull Request

django-mcadmin is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. For complete license text see COPYING file.

Project Website: https://github.com/vint21h/django-mcadmin/

Author: Alexei Andrushievich <vint21h@vint21h.pp.ua>

For other authors list see AUTHORS file.