# Τεκμηρίωση του Django - 5.2.8

# How to create custom `django-admin` commands

Οι εφαρμογές μπορούν να κάνουν register τις δικές τους ενέργειες με το `manage.py`. Για παράδειγμα, ίσως να θέλετε να προσθέσετε μια `manage.py` ενέργεια για ένα Django app το οποίο προωθείτε για διανομή. Σε αυτό το άρθρο θα χτίσουμε μια δικιά μας εντολή, με το όνομα `closepoll`, για την εφαρμογή `polls` που φτιάξαμε στον οδηγό.

To do this, add a `management/commands` directory to the application. Django will register a `manage.py` command for each Python module in that directory whose name doesn’t begin with an underscore. For example:

    polls/
        __init__.py
        models.py
        management/
            __init__.py
            commands/
                __init__.py
                _private.py
                closepoll.py
        tests.py
        views.py

Σε αυτό το παράδειγμα, η εντολή `closepoll` θα είναι διαθέσιμη σε κάθε project που έχει εγκατεστημένη αυτή την εφαρμογή, ήτοι, η εφαρμογή `polls` βρίσκεται μέσα στη ρύθμιση `INSTALLED_APPS`.

Το module `_private.py` δεν θα είναι διαθέσιμο ως μια εντολή διαχείρισης (management command), αφού το όνομα του ξεκινά με την κάτω παύλα.

Το module `closepoll.py` έχει μόνο μια απαίτηση – πρέπει να ορίσει μια κλάση `Command` η οποία κάνει extend την κλάση `BaseCommand` ή μια από τις subclasses της.

Αυτόνομα scripts

Οι παραμετροποιήσιμες εντολές διαχείρισης είναι εξαιρετικά χρήσιμες για την εκτέλεση αυτόνομων scripts ή για scripts τα οποία εκτελούνται σε περιοδική βάση από το crontab του UNIX ή από τα scheduled tasks των Windows.

Για να υλοποιήσετε την εντολή επεξεργαστείτε το αρχείο `polls/management/commands/closepoll.py` για να δείχνει κάπως έτσι:

    from django.core.management.base import BaseCommand, CommandError
    from polls.models import Question as Poll

    class Command(BaseCommand):
        help = "Closes the specified poll for voting"

        def add_arguments(self, parser):
            parser.add_argument("poll_ids", nargs="+", type=int)

        def handle(self, *args, **options):
            for poll_id in options["poll_ids"]:
                try:
                    poll = Poll.objects.get(pk=poll_id)
                except Poll.DoesNotExist:
                    raise CommandError('Poll "%s" does not exist' % poll_id)

                poll.opened = False
                poll.save()

                self.stdout.write(
                    self.style.SUCCESS('Successfully closed poll "%s"' % poll_id)
                )

Σημείωση

Όταν χρησιμοποιείτε εντολές διαχείρισης και θέλετε να εμφανίσετε κάτι στην κονσόλα, θα πρέπει να το στέλνετε στο `self.stdout` και στο `self.stderr`, αντί να το εκτυπώνετε απ’ ευθείας στο `stdout` και `stderr`. Χρησιμοποιώντας αυτά, το τεστ της εντολής σας γίνεται παιχνιδάκι. Σημειώστε, επίσης, ότι δεν χρειάζεται να προσθέτετε το χαρακτήρα της νέας γραμμής (line feed) στο τέλος κάθε `self.stdout` ή `self.stderr` του μηνύματος σας. Θα προστεθεί αυτόματα από το Django εκτός και αν θέλετε διαφορετικά χρησιμοποιώντας την παράμετρο `ending`:

    self.stdout.write("Unterminated line", ending="")

The new custom command can be called using `python manage.py closepoll <poll_ids>`.

The `handle()` method takes one or more `poll_ids` and sets `poll.opened` to `False` for each one. If the user referenced any nonexistent polls, a `CommandError` is raised. The `poll.opened` attribute does not exist in the tutorial and was added to `polls.models.Question` for this example.

## Προαιρετικά arguments

Αλλάζοντας εύκολα την εντολή `closepoll` ώστε να δέχεται επιπρόσθετες επιλογές όταν την καλείτε, θα μπορούσε να διαγράφει ένα poll αντί να το θέτει ως κλειστό (`poll.opened = False`). Αυτές οι επιλογές μπορούν να προστεθούν στη μέθοδο `add_arguments()` ως εξής:

    class Command(BaseCommand):
        def add_arguments(self, parser):
            # Positional arguments
            parser.add_argument("poll_ids", nargs="+", type=int)

            # Named (optional) arguments
            parser.add_argument(
                "--delete",
                action="store_true",
                help="Delete poll instead of closing it",
            )

        def handle(self, *args, **options):
            # ...
            if options["delete"]:
                poll.delete()
            # ...

The option (`delete` in our example) is available in the options dict parameter of the handle method. See the `argparse` Python documentation for more about `add_argument` usage.

Πέρα από τη δυνατότητα της πρόσθεσης δικών σας επιλογών στην εντολή, όλες οι εντολές διαχείρισης μπορούν να δεχτούν μερικές δικές τους, προεγκατεστημένες, επιλογές όπως η `--verbosity` και η `--traceback`.

## Εντολές διαχείρισης και locales

By default, management commands are executed with the current active locale.

If, for some reason, your custom management command must run without an active locale (for example, to prevent translated content from being inserted into the database), deactivate translations using the `@no_translations` decorator on your `handle()` method:

    from django.core.management.base import BaseCommand, no_translations

    class Command(BaseCommand):
        ...

        @no_translations
        def handle(self, *args, **options): ...

Since translation deactivation requires access to configured settings, the decorator can’t be used for commands that work without configured settings.

## Τεστ

Πληροφορίες στο πως να τεστάρετε τις δικές σας εντολές διαχείρισης, μπορείτε να βρείτε στα εργαλεία για τεστ.

## Overriding commands

Django registers the built-in commands and then searches for commands in `INSTALLED_APPS` in reverse. During the search, if a command name duplicates an already registered command, the newly discovered command overrides the first.

In other words, to override a command, the new command must have the same name and its app must be before the overridden command’s app in `INSTALLED_APPS`.

Management commands from third-party apps that have been unintentionally overridden can be made available under a new name by creating a new command in one of your project’s apps (ordered before the third-party app in `INSTALLED_APPS`) which imports the `Command` of the overridden command.

## Objects εντολών

class BaseCommand

Η κύρια κλάση από την οποία πηγάζουν όλες οι εντολές διαχείρισης.

Χρησιμοποιήστε αυτή την κλάση αν θέλετε να έχετε πρόσβαση σε όλους τους μηχανισμούς οι οποίοι μεταφράζουν τις επιλογές στη γραμμή εντολών (όπως την `--delete` που χρησιμοποιήσαμε νωρίτερα) και αποφασίζουν, ανάλογα την επιλογή, ποιον κώδικα να καλέσουν περαιτέρω. Αν δεν θέλετε να αλλάξετε κάποια από αυτές τις συμπεριφορές, ίσως σας φανεί χρήσιμη μια από τις subclasses της `BaseCommand`.

Πραγματοποιώντας subclassing στην κλάση `BaseCommand` απαιτεί να υλοποιήσετε τη μέθοδο `handle()`.

### Attributes

Όλα τα attributes μπορούν να οριστούν στη δική σας κλάση και να χρησιμοποιηθούν στις subclasses της `BaseCommand`.

BaseCommand.help

  Μια μικρή περιγραφή της εντολής η οποία θα εκτυπωθεί στην κονσόλα όταν ο χρήστης τρέξει την εντολή `python manage.py help <command>`.

BaseCommand.missing_args_message

  If your command defines mandatory positional arguments, you can customize the message error returned in the case of missing arguments. The default is output by `argparse` («too few arguments»).

BaseCommand.output_transaction

  Τύπου boolean που υποδεικνύει αν η εντολή θα εκτυπώσει (στην κονσόλα) εντολές SQL. Αν είναι `True`, τότε η έξοδος θα συμπεριληφθεί μέσα σε ένα `BEGIN;` και `COMMIT;`. Προεπιλεγμένη τιμή είναι το `False`.

BaseCommand.requires_migrations_checks

  Τύπου boolean. Αν είναι `True`, η εντολή θα εκτυπώσει ένα warning αν το σετ των migrations στο δίσκο δεν ταιριάζει με τα migrations στη βάση δεδομένων. Υπόψιν ότι, ένα warning δεν εμποδίζει την εντολή από το να εκτελεστεί. Προεπιλεγμένη τιμή είναι το `False`.

BaseCommand.requires_system_checks

  A list or tuple of tags, e.g. `[Tags.staticfiles, Tags.models]`. System checks registered in the chosen tags will be checked for errors prior to executing the command. The value `'__all__'` can be used to specify that all system checks should be performed. Default value is `'__all__'`.

BaseCommand.style

  Ένα attribute που βοηθά στο να χρωματίσει την έξοδο (δηλαδή το κείμενο) όταν γράφετε στο `self.stdout` ή στο `self.stderr`. Για παράδειγμα:

      self.stdout.write(self.style.SUCCESS("..."))

  Δείτε στο χρωματίζοντας την έξοδο για να μάθετε πως να τροποποιείτε την παλέτα των χρωμάτων και να δείτε τα διαθέσιμα στυλ (χρήση της έκδοσης των κεφαλαίων γραμμάτων των «ρόλων» όπως περιγράφονται σε αυτή την ενότητα).

  Αν δηλώσετε την επιλογή `--no-color` όταν τρέχετε την εντολή σας, όλες οι κλήσεις της `self.style()` θα επιστρέψουν το αρχικό string χωρίς κάποιο χρώμα.

BaseCommand.suppressed_base_arguments

  The default command options to suppress in the help output. This should be a set of option names (e.g. `'--verbosity'`). The default values for the suppressed options are still passed.

### Μέθοδοι

Η κλάση `BaseCommand` έχει μερικές μεθόδους οι οποίες μπορούν να παρακαμφθούν (overridden) αλλά μόνο η μέθοδος `handle()` πρέπει να υλοποιηθεί υποχρεωτικά.

Υλοποίηση ενός constructor μέσα σε μια subclass

Αν υλοποιήσετε την `__init__` μέσα σε μια subclass της `BaseCommand` θα πρέπει πρώτα να καλέσετε την `__init__` της κλάσης `BaseCommand`, όπως φαίνεται παρακάτω:

    class Command(BaseCommand):
        def __init__(self, *args, **kwargs):
            super().__init__(*args, **kwargs)
            # ...

BaseCommand.create_parser(prog_name, subcommand, **kwargs)

  Returns a `CommandParser` instance, which is an `ArgumentParser` subclass with a few customizations for Django.

  You can customize the instance by overriding this method and calling `super()` with `kwargs` of `ArgumentParser` parameters.

BaseCommand.add_arguments(parser)

  Σημείο εισόδου για να προσθέσετε arguments στο μεταφραστή (parser) για τον χειρισμό των arguments που εισάγονται στη γραμμή εντολών (όπως το argument `--delete` που αναφέραμε παραπάνω). Τυχόν δικές σας διαχειριστικές εντολές θα πρέπει να παρακάμπτουν αυτή τη μέθοδο για να προσθέσουν positional και optional arguments που θα δέχεται η εντολή. Η κλήση της `super()` δεν είναι απαραίτητη όταν κάνετε απ’ ευθείας subclass την κλάση `BaseCommand`.

BaseCommand.get_version()

  Επιστρέφει την έκδοση του Django, η οποία θα πρέπει να είναι η σωστή για όλες τις προεγκατεστημένες εντολές του Django. Τυχόν δικές σας διαχειριστικές εντολές μπορούν να παρακάμψουν αυτή τη μέθοδο για να επιστρέφουν τη δική τους έκδοση.

BaseCommand.execute(*args, **options)

  Tries to execute this command, performing system checks if needed (as controlled by the `requires_system_checks` attribute). If the command raises a `CommandError`, it’s intercepted and printed to `stderr`.

Καλώντας μια εντολή διαχείρισης μέσα από τον κώδικα σας

Η μέθοδος `execute()` δεν θα πρέπει να καλείται απ” ευθείας από τον κώδικα σας για την εκτέλεση μιας εντολής. Αντί αυτής, χρησιμοποιήστε τη συνάρτηση `call_command()`.

BaseCommand.handle(*args, **options)

  Η πραγματική λογική της εντολής. Όλες οι subclasses πρέπει να υλοποιήσουν αυτή τη μέθοδο.

  It may return a string which will be printed to `stdout` (wrapped by `BEGIN;` and `COMMIT;` if `output_transaction` is `True`).

BaseCommand.check(app_configs=None, tags=None, display_num_errors=False, include_deployment_checks=False, fail_level=checks.ERROR, databases=None)

  Uses the system check framework to inspect the entire Django project for potential problems. Serious problems are raised as a `CommandError`; warnings are output to `stderr`; minor notifications are output to `stdout`.

  If `app_configs` and `tags` are both `None`, all system checks are performed except deployment and database related checks. `tags` can be a list of check tags, like `compatibility` or `models`.

  You can pass `include_deployment_checks=True` to also perform deployment checks, and list of database aliases in the `databases` to run database related checks against them.

BaseCommand.get_check_kwargs(options)
  New in Django 5.2.

  Supplies kwargs for the call to `check()`, including transforming the value of `requires_system_checks` to the `tag` kwarg.

  Override this method to change the values supplied to `check()`. For example, to opt into database related checks you can override `get_check_kwargs()` as follows:

      def get_check_kwargs(self, options):
          kwargs = super().get_check_kwargs(options)
          return {**kwargs, "databases": [options["database"]]}

### `BaseCommand` subclasses

class AppCommand

Μια εντολή διαχείρισης η οποία δέχεται ως arguments (όπως το `<poll_id>` στην εντολή που γράψαμε παραπάνω `python manage.py closepoll <poll_id>`) ένα ή περισσότερα labels εφαρμογών και κάνει κάτι με καθένα από αυτά.

Αντί της υλοποίησης της μεθόδου `handle()`, οι subclasses πρέπει να υλοποιούν τη μέθοδο `handle_app_config()` η οποία θα καλείται μια φορά για κάθε εφαρμογή.

AppCommand.handle_app_config(app_config, **options)

  Εκτελεί τις ενέργειες της εντολής για το `app_config` το οποίο θα είναι ένα instance της κλάσης `AppConfig` που αντιστοιχεί στο label της εφαρμογής που δόθηκε στη γραμμή εντολών.

class LabelCommand

Μια εντολή διαχείρισης η οποία δέχεται ένα η περισσότερα arguments (labels) μέσω της γραμμής εντολών και κάνει κάτι με καθένα από αυτά.

Αντί της υλοποίησης της μεθόδου `handle()`, οι subclasses πρέπει να υλοποιούν τη μέθοδο `handle_label()`, η οποία θα καλείται μια φορά για κάθε label.

LabelCommand.label

  Ένα αλφαριθμητικό (string) που περιγράφει τις παραμέτρους που δόθηκαν στην εντολή. Το αλφαριθμητικό χρησιμοποιείται στα μηνύματα σφαλμάτων καθώς και στο κείμενο περιγραφής της εντολής. Προεπιλογή είναι το `'label'`.

LabelCommand.handle_label(label, **options)

  Εκτελεί τις ενέργειες της εντολής για το `label`, το οποίο θα είναι ένα string όπως δόθηκε στη γραμμή εντολών.

### Exceptions εντολής

exception CommandError(returncode=1)

Μια κλάση Exception που υποδεικνύει ότι προέκυψε κάποιο πρόβλημα κατά τη διάρκεια εκτέλεσης της εντολής διαχείρισης.

If this exception is raised during the execution of a management command from a command line console, it will be caught and turned into a nicely-printed error message to the appropriate output stream (i.e., `stderr`); as a result, raising this exception (with a sensible description of the error) is the preferred way to indicate that something has gone wrong in the execution of a command. It accepts the optional `returncode` argument to customize the exit status for the management command to exit with, using `sys.exit()`.

Αν η εντολή διαχείρισης καλείται μέσα από τον κώδικα σας μέσω της συνάρτησης `call_command()`, τότε είναι δικό σας θέμα να κάνετε catch, όποτε το κρίνετε απαραίτητο, αυτό το exception.