Commands

This document references the base class for general and project commands. For information on how to use them and how to write your own commands, see custom commands. You can also find a tutorial about commands here

Command objects

class BaseCommand

The base class from which all general management commands ultimately derive.

Use this class if you want access to all of the mechanisms which parse the command-line arguments and work out what code to call in response. Subclassing this class, will make all your command general commands.

Subclassing the BaseCommand class requires that you implement the handle() method.

Attributes

All attributes can be set in your derived class and can be used in BaseCommand’s subclasses.

BaseCommand.help

A short description of the command, which will be printed in the help message when the user runs the command 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.keep_extras_args

Boolean that let you keep extra arguments that have been passed to your command. If you had the occasion to work with Argparse you know that there is two methods to parse your args. The parse_args() that will throw you an error if you pass an argument that it doesn’t know. And the parse_known_args() that gives you a tuple with a Namespace and a list of option of unknown arguments and their values. keep_extras_args register that list in the Config.extras_args attribute.

BaseCommand.name

Name of the command. This attribute is not mandatory. By default its value will be the name of your command class in lowercase. If the name of the class contains the word Command at the end of it like CreateCommand. The name will be stripped out and the final name will be create.

Methods

BaseCommand has a few methods that can be overridden. but only the handle() method must be implemented.

Implementing a constructor in a subclass

If you implement __init__ in your subclass of BaseCommand, you must call BaseCommand’s __init__:

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 Socon.

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

BaseCommand.add_arguments(parser)

Entry point to add parser arguments to handle command line arguments passed to the command. Custom commands should override this method to add both positional and optional arguments accepted by the command. Calling super() is not needed when directly subclassing BaseCommand.

BaseCommand.get_version()

Returns Socon’s version, which should be correct for all built-in Socon commands. User-supplied commands can override this method to return their own version.

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.

BaseCommand.handle(config: :class:`Config`)

The actual logic of the command. Subclasses must implement this method. It may return a string which will be printed to stdout

BaseCommand subclasses

class ProjectCommand

The base class from which all project management commands ultimately derive.

Use this class if you want access all of the mechanisms which parse the command-line arguments and work out what code to call in response. Subclassing this class will make all your commands project dependent. It means that you must pass the --project to make it work.

Subclassing the ProjectCommand class requires that you implement the handle() method.

Configurable attributes

projects

Set which projects can access this command. This argument limits the access scope of the command. By default all projects can have access to this command.

Methods

ProjectCommand.handle(config, project_config)

The actual logic of the command. Subclasses must implement this method. It may return a string which will be printed to stdout

Command exceptions

exception CommandError(returncode=1)

Exception class indicating a problem while executing a management command.

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().

Config object

class Config

Base class that stores information about the command being executed. This class also provides nice features like a terminal object to help you write into the terminal and a temporary directory that is automatically clean at the end of the script.

Attributes

Config.options

Argparse Namespace. Let you access the command line options as attribute.

Config.extras_args

Keep the extra arguments of the command if you set the BaseCommand.keep_extras_args attribute to True.

Config.tmpdir

Provide a temporary directory using tempfile.mkdtemp(). This tmpdir is automatically remove at program termination.

Config.terminal

Provide a terminal writer from socon.utils.terminal. This terminal can help you print formatted messages to the terminal. See more here Terminal

Methods

Config.getoption(name: str, default=None, skip=True)

Return an option value. This function allows you to pass a default value if not found or raise a ValueError

The ValueError is raised only if skip is set to False. Otherwise, getoption() will return None

Subcommand object

class Subcommand

Inherit from BaseCommand. This type of command enables you to define multiple commands under one specific command.

Subclassing the Subcommand class requires that you to define the subcommand_manager attribute.

Attributes

Subcommand.subcommand_manager

The name of the manager that holds all the subcommands. The name of that manager must be different than “subcommands” as it’s the name of the SubcommandManager manager.