socon and manage.py

This document will highlight the purpose and the use of both the socon and manage.py command-line utility.

socon is Socon’s command line utility for administrative tasks. It is mostly used when you haven’t yet created a container.

When a container is created the manage.py is automatically created in each Socon container. It does exactly the same thing as the socon command but it also sets the SOCON_SETTINGS_MODULE environment variable that is used to set the main settings.py file.

Generally, when working on a single Socon container, it’s easier to use manage.py than socon. If you need to switch between multiple Socon settings files, use socon with SOCON_SETTINGS_MODULE or the --settings command line option.

Usage

$ socon <commad> [options]
$ python manage.py <commad> [options]
$ python -m socon <commad> [options]

command should be one of the commands listed below. options will depend on the command. A project command, will always require to have the --project option no matter what.

Getting help

socon help

There are different ways of getting help using Socon.

  1. socon help to display information about commands associated to Socon but also to the common space, the plugins and the projects.

  2. socon <command> help to display a description of the given command and a list of available options.

Note

When using socon <command> help you can always specify --project if this command is part of a project or if it has been redefined. If the command has been redefined in a project and you don’t specify --project we will return the helper from the most important registry that defines this command. More information here

Determining the version

socon version

Run socon version to display the current Socon version.

The output follows the schema described in PEP 440:

1.0.dev4a7a299
1.0a1
1.0

Displaying debug output

Use --verbosity to specify the amount of notifications and debug information that socon prints to the console. By default the verbosity is set to 0.

Available commands

createcontainer

socon createcontainer name

Create a Socon container directory structure for the given container name in the current directory.

By default, the new directory contains manage.py, the container package that stores the settings.py and the projects directory.

--target DIRECTORY

Specify a destination directory.

If only the container name is given, both the project directory and project package will be named <containername> and the container directory will be created in the current working directory.

If the target directory is provided, Socon will use that existing directory as the container directory, and create manage.py and the container package within it. Use ‘.’ to denote the current working directory.

In case the directory does not exist, Socon will create it and use it as its container directory.

For example:

socon createcontainer mycontainer --target /Path/to/container/super_container

createproject

socon createproject name

Create a Socon project directory structure for the given project name in the current directory under the projects directory.

Warning

You must be in a container or inside the projects directory when executing this command otherwise Socon will raise an exception.

By default, the new directory contains a projects.py file and a management directory. projects.py is used by Socon to register the project if defined by the INSTALLED_PROJECTS setting. The management directory contains the config.py file that will hold your project settings.

--target DIRECTORY

Specify a destination directory that must be in a container.

If only the project name is given, the project directory will be created in the current container under the projects directory.

If the target directory is provided, Socon will use that existing directory rather than creating a new one. You can use ‘.’ to denote the current working directory. This mean the you can create a project outside a container using the target directory but it should point to a valid container.

For example:

socon createproject myproject --target path/to/a/container

createcommand

socon createcommand name

Create a Socon command template, can be called from the root container, inside the projects folder, or inside a specific project/ plugin folder.

--type TYPE

Specifies the type of command to be generated

  • project generates a template for ProjectCommand (default)

  • base generates a template for BaseCommand

--projectname NAME

If called from the root container or from the projects folder, you need to specify --projectname to indicate to which project you want to add the command. This value is by default "None" which refers to the common folder if it is called from the root container.

--target TARGET

Specify a destination directory

For example:

python manage.py createcommand launch --type project --projectname artemis

createplugin

socon createplugin name

Create a Socon plugin directory structure for the given plugin name in the current directory.

By default the new directory contains all the file to create a simple python package. A README.rst, a setup.py and a plugin package that store a file:plugins.py file that is used by Socon to register the plugin if defined by the INSTALLED_PLUGINS setting.

--target DIRECTORY

Specify a destination directory.

If only the plugin name is given, both the plugin directory and plugin package will be named <pluginname> and the plugin directory will be created in the current working directory.

If the target directory is provided, Socon will use that existing directory as the plugin directory, and create all the necessary files. Use ‘.’ to denote the current working directory.

In case the directory does not exist, Socon will create it and use it as its plugin directory.

For example:

socon createplugin myplugin --target /path/to/plugins/super_plugin

check

socon check

Socon will perform a check on all installed projects and the common space. This means that Socon will check all managers and hooks that have been declared and raise any potential errors. By default the check command will raise the error and exit.

--show_all

Display all errors that the check command encountered when importing configs and managers.

Default options

--settings

Specifies the settings module to use. The settings module should be in Python package syntax, e.g. mysite.settings. If this isn’t provided, socon will use the SOCON_SETTINGS_MODULE environment variable.

This option is unnecessary in manage.py, because it uses settings.py from the current project by default.

Example usage:

socon check --settings=mysite.settings
--project

Specifies the project to use for the command.

Warning

This option is mandatory for a project command. It is optional when we run a general command.

When we specify this option for a general command, Socon will check in the project directory of the project specified. If the project does not exist or the command is not in the project, an error will be raised.

For a project command, this option is mandatory as the command needs to load a ProjectConfig to work. If the project does not exist, an error will be raised by Socon.

--verbosity

Specifies the amount of notifications and debug information that a command should print to the console.

  • 0 means no output.

  • 1 means normal output (default).

  • 2 means verbose output.

  • 3 means very verbose output.

Example usage:

socon createproject --verbosity 2

Running management commands from your code

socon.core.management.call_command(name, *args)

To call a management command from code use call_command.

name

the name of the command to call.

*args

a list of arguments accepted by the command. Arguments are passed to the argument parser, so you can use the same style as you would on the command line.

Examples:

from socon.core.management import call_command

call_command('createcontainer', 'test', '--target=dir')

The return value of the call_command() function is the same as the return value of the handle() method of the command.