diff --git a/docs/conf.py b/docs/conf.py index be1050ba36f..03bf6682efe 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -273,7 +273,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('contents', 'django', 'Django Documentation', ['Django Software Foundation'], 1) + ('ref/django-admin', 'django-admin', 'Utility script for the Django Web framework', ['Django Software Foundation'], 1), ] diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index a08d07eae57..cd41938c3af 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -420,3 +420,19 @@ Translating documentation See :ref:`Localizing the Django documentation ` if you'd like to help translate the documentation into another language. + +.. _django-admin-manpage: + +``django-admin`` man page +------------------------- + +Sphinx can generate a manual page for the +:doc:`django-admin ` command. This is configured in +``docs/conf.py``. Unlike other documentation output, this man page should be +included in the Django repository and the releases as +``docs/man/django-admin.1``. There isn't a need to update this file when +updating the documentation, as it's updated once as part of the release process. + +To generate an updated version of the man page, run ``make man`` in the +``docs`` directory. The new man page will be written in +``docs/_build/man/django-admin.1``. diff --git a/docs/man/django-admin.1 b/docs/man/django-admin.1 index 243a15edf57..557907231d5 100644 --- a/docs/man/django-admin.1 +++ b/docs/man/django-admin.1 @@ -1,237 +1,2602 @@ -.TH "django-admin" "1" "March 2008" "Django Project" "" -.SH "NAME" -django\-admin \- Utility script for the Django Web framework -.SH "SYNOPSIS" -.B django\-admin -.I -.B [options] +.\" Man page generated from reStructuredText. +. +.TH "DJANGO-ADMIN" "1" "March 10, 2015" "1.8" "Django" +.SH NAME +django-admin \- Utility script for the Django Web framework +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. .sp -.SH "DESCRIPTION" -This utility script provides commands for creation and maintenance of Django -projects and apps. +\fBdjango\-admin\fP is Django\(aqs command\-line utility for administrative tasks. +This document outlines all it can do. .sp -With the exception of -.BI startproject, -all commands listed below can also be performed with the -.BI manage.py -script found at the top level of each Django project directory. +Prior to Django 1.7, \fBdjango\-admin\fP was only installed as +\fBdjango\-admin.py\fP\&. + .sp -.SH "ACTIONS" +In addition, \fBmanage.py\fP is automatically created in each Django project. +\fBmanage.py\fP is a thin wrapper around \fBdjango\-admin\fP that takes care of +several things for you before delegating to \fBdjango\-admin\fP: +.INDENT 0.0 +.IP \(bu 2 +It puts your project\(aqs package on \fBsys.path\fP\&. +.IP \(bu 2 +It sets the \fBDJANGO_SETTINGS_MODULE\fP environment variable so that +it points to your project\(aqs \fBsettings.py\fP file. +.IP \(bu 2 +It calls \fBdjango.setup()\fP to initialize various internals of Django. +.UNINDENT +.sp +\fBdjango.setup()\fP didn\(aqt exist in previous versions of Django. + +.sp +The \fBdjango\-admin\fP script should be on your system path if you installed +Django via its \fBsetup.py\fP utility. If it\(aqs not on your path, you can find it +in \fBsite\-packages/django/bin\fP within your Python installation. Consider +symlinking it from some place on your path, such as \fB/usr/local/bin\fP\&. +.sp +For Windows users, who do not have symlinking functionality available, you can +copy \fBdjango\-admin.exe\fP to a location on your existing path or edit the +\fBPATH\fP settings (under \fBSettings \- Control Panel \- System \- Advanced \- +Environment...\fP) to point to its installed location. +.sp +Generally, when working on a single Django project, it\(aqs easier to use +\fBmanage.py\fP than \fBdjango\-admin\fP\&. If you need to switch between multiple +Django settings files, use \fBdjango\-admin\fP with +\fBDJANGO_SETTINGS_MODULE\fP or the \fI\%\-\-settings\fP command line +option. +.sp +The command\-line examples throughout this document use \fBdjango\-admin\fP to +be consistent, but any example can use \fBmanage.py\fP just as well. +.SH USAGE +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ django\-admin [options] +$ manage.py [options] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBcommand\fP should be one of the commands listed in this document. +\fBoptions\fP, which is optional, should be zero or more of the options available +for the given command. +.SS Getting runtime help +.INDENT 0.0 .TP -.BI cleanup -Cleans out old data from the database (only expired sessions at the moment). +.B django\-admin help +.UNINDENT +.sp +Run \fBdjango\-admin help\fP to display usage information and a list of the +commands provided by each application. +.sp +Run \fBdjango\-admin help \-\-commands\fP to display a list of all available +commands. +.sp +Run \fBdjango\-admin help \fP to display a description of the given +command and a list of its available options. +.SS App names +.sp +Many commands take a list of "app names." An "app name" is the basename of +the package containing your models. For example, if your \fBINSTALLED_APPS\fP +contains the string \fB\(aqmysite.blog\(aq\fP, the app name is \fBblog\fP\&. +.SS Determining the version +.INDENT 0.0 .TP -.BI "compilemessages [" "\-\-locale=LOCALE" "] [" "\-\-exclude=LOCALE" "] [" "\-\-use\-fuzzy" "]" -Compiles .po files to .mo files for use with builtin gettext support. +.B django\-admin version +.UNINDENT +.sp +Run \fBdjango\-admin version\fP to display the current Django version. +.sp +The output follows the schema described in \fI\%PEP 386\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +1.4.dev17026 +1.4a1 +1.4 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Displaying debug output +.sp +Use \fI\%\-\-verbosity\fP to specify the amount of notification and debug information +that \fBdjango\-admin\fP should print to the console. For more details, see the +documentation for the \fI\%\-\-verbosity\fP option. +.SH AVAILABLE COMMANDS +.SS check +.INDENT 0.0 .TP -.BI "createcachetable [" "tablename" "]" -Creates the table needed to use the SQL cache backend +.B django\-admin check +.UNINDENT +.sp + +.sp +Uses the \fBsystem check framework\fP to inspect +the entire Django project for common problems. +.sp +The system check framework will confirm that there aren\(aqt any problems with +your installed models or your admin registrations. It will also provide warnings +of common compatibility problems introduced by upgrading Django to a new version. +Custom checks may be introduced by other libraries and applications. +.sp +By default, all apps will be checked. You can check a subset of apps by providing +a list of app labels as arguments: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +python manage.py check auth admin myapp +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If you do not specify any app, all apps will be checked. +.INDENT 0.0 .TP -.BI "createsuperuser [" "\-\-username=USERNAME" "] [" "\-\-email=EMAIL" "]" -Creates a superuser account (a user who has all permissions). +.B \-\-tag +.UNINDENT +.sp +The \fBsystem check framework\fP performs many different +types of checks. These check types are categorized with tags. You can use these tags +to restrict the checks performed to just those in a particular category. For example, +to perform only security and compatibility checks, you would run: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +python manage.py check \-\-tag security \-\-tag compatibility +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 .TP -.B dbshell -Runs the command\-line client for the specified -.BI database ENGINE. +.B \-\-list\-tags +.UNINDENT +.sp +List all available tags. +.INDENT 0.0 .TP -.B diffsettings -Displays differences between the current -.B settings.py -and Django's default settings. Settings that don't appear in the defaults are -followed by "###". +.B \-\-deploy +.UNINDENT +.sp + +.sp +The \fB\-\-deploy\fP option activates some additional checks that are only relevant +in a deployment setting. +.sp +You can use this option in your local development environment, but since your +local development settings module may not have many of your production settings, +you will probably want to point the \fBcheck\fP command at a different settings +module, either by setting the \fBDJANGO_SETTINGS_MODULE\fP environment variable, +or by passing the \fB\-\-settings\fP option: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +python manage.py check \-\-deploy \-\-settings=production_settings +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Or you could run it directly on a production or staging deployment to verify +that the correct settings are in use (omitting \fB\-\-settings\fP). You could even +make it part of your integration test suite. +.SS compilemessages +.INDENT 0.0 .TP -.BI "dumpdata [" "\-\-all" "] [" "\-\-format=FMT" "] [" "\-\-indent=NUM" "] [" "\-\-natural=NATURAL" "] [" "app_label app_label app_label.Model ..." "]" +.B django\-admin compilemessages +.UNINDENT +.sp +Compiles .po files created by \fI\%makemessages\fP to .mo files for use with +the builtin gettext support. See \fB/topics/i18n/index\fP\&. +.sp +Use the \fI\%\-\-locale\fP option (or its shorter version \fB\-l\fP) to +specify the locale(s) to process. If not provided, all locales are processed. +.sp +Use the \fI\%\-\-exclude\fP option (or its shorter version \fB\-x\fP) to +specify the locale(s) to exclude from processing. If not provided, no locales +are excluded. +.sp +You can pass \fB\-\-use\-fuzzy\fP option (or \fB\-f\fP) to include fuzzy translations +into compiled files. +.sp +Added \fB\-\-exclude\fP and \fB\-\-use\-fuzzy\fP options. + +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin compilemessages \-\-locale=pt_BR +django\-admin compilemessages \-\-locale=pt_BR \-\-locale=fr \-f +django\-admin compilemessages \-l pt_BR +django\-admin compilemessages \-l pt_BR \-l fr \-\-use\-fuzzy +django\-admin compilemessages \-\-exclude=pt_BR +django\-admin compilemessages \-\-exclude=pt_BR \-\-exclude=fr +django\-admin compilemessages \-x pt_BR +django\-admin compilemessages \-x pt_BR \-x fr +.ft P +.fi +.UNINDENT +.UNINDENT +.SS createcachetable +.INDENT 0.0 +.TP +.B django\-admin createcachetable +.UNINDENT +.sp +Creates the cache tables for use with the database cache backend. See +\fB/topics/cache\fP for more information. +.sp +The \fI\%\-\-database\fP option can be used to specify the database +onto which the cachetable will be installed. +.sp +It is no longer necessary to provide the cache table name or the +\fI\%\-\-database\fP option. Django takes this information from your +settings file. If you have configured multiple caches or multiple databases, +all cache tables are created. + +.SS dbshell +.INDENT 0.0 +.TP +.B django\-admin dbshell +.UNINDENT +.sp +Runs the command\-line client for the database engine specified in your +\fBENGINE\fP setting, with the connection parameters specified in your +\fBUSER\fP, \fBPASSWORD\fP, etc., settings. +.INDENT 0.0 +.IP \(bu 2 +For PostgreSQL, this runs the \fBpsql\fP command\-line client. +.IP \(bu 2 +For MySQL, this runs the \fBmysql\fP command\-line client. +.IP \(bu 2 +For SQLite, this runs the \fBsqlite3\fP command\-line client. +.UNINDENT +.sp +This command assumes the programs are on your \fBPATH\fP so that a simple call to +the program name (\fBpsql\fP, \fBmysql\fP, \fBsqlite3\fP) will find the program in +the right place. There\(aqs no way to specify the location of the program +manually. +.sp +The \fI\%\-\-database\fP option can be used to specify the database +onto which to open a shell. +.SS diffsettings +.INDENT 0.0 +.TP +.B django\-admin diffsettings +.UNINDENT +.sp +Displays differences between the current settings file and Django\(aqs default +settings. +.sp +Settings that don\(aqt appear in the defaults are followed by \fB"###"\fP\&. For +example, the default settings don\(aqt define \fBROOT_URLCONF\fP, so +\fBROOT_URLCONF\fP is followed by \fB"###"\fP in the output of +\fBdiffsettings\fP\&. +.sp +The \fI\%\-\-all\fP option may be provided to display all settings, even +if they have Django\(aqs default value. Such settings are prefixed by \fB"###"\fP\&. +.SS dumpdata +.INDENT 0.0 +.TP +.B django\-admin dumpdata +.UNINDENT +.sp Outputs to standard output all data in the database associated with the named application(s). +.sp +If no application name is provided, all installed applications will be dumped. +.sp +The output of \fBdumpdata\fP can be used as input for \fI\%loaddata\fP\&. +.sp +Note that \fBdumpdata\fP uses the default manager on the model for selecting the +records to dump. If you\(aqre using a \fIcustom manager\fP as +the default manager and it filters some of the available records, not all of the +objects will be dumped. +.sp +The \fI\%\-\-all\fP option may be provided to specify that +\fBdumpdata\fP should use Django\(aqs base manager, dumping records which +might otherwise be filtered or modified by a custom manager. +.INDENT 0.0 .TP -.BI flush -Removes all data from the database and then re-installs any initial data. +.B \-\-format +.UNINDENT +.sp +By default, \fBdumpdata\fP will format its output in JSON, but you can use the +\fB\-\-format\fP option to specify another format. Currently supported formats +are listed in \fIserialization\-formats\fP\&. +.INDENT 0.0 .TP -.B inspectdb -Introspects the database tables in the database specified in settings.py and outputs a Django -model module. +.B \-\-indent +.UNINDENT +.sp +By default, \fBdumpdata\fP will output all data on a single line. This isn\(aqt +easy for humans to read, so you can use the \fB\-\-indent\fP option to +pretty\-print the output with a number of indentation spaces. +.sp +The \fI\%\-\-exclude\fP option may be provided to prevent specific +applications or models (specified as in the form of \fBapp_label.ModelName\fP) +from being dumped. If you specify a model name to \fBdumpdata\fP, the dumped +output will be restricted to that model, rather than the entire application. +You can also mix application names and model names. +.sp +The \fI\%\-\-database\fP option can be used to specify the database +from which data will be dumped. +.INDENT 0.0 .TP -.BI "loaddata [" "fixture fixture ..." "]" +.B \-\-natural\-foreign +.UNINDENT +.sp + +.sp +When this option is specified, Django will use the \fBnatural_key()\fP model +method to serialize any foreign key and many\-to\-many relationship to objects of +the type that defines the method. If you are dumping \fBcontrib.auth\fP +\fBPermission\fP objects or \fBcontrib.contenttypes\fP \fBContentType\fP objects, you +should probably be using this flag. See the \fInatural keys\fP documentation for more details on this +and the next option. +.INDENT 0.0 +.TP +.B \-\-natural\-primary +.UNINDENT +.sp + +.sp +When this option is specified, Django will not provide the primary key in the +serialized data of this object since it can be calculated during +deserialization. +.INDENT 0.0 +.TP +.B \-\-natural +.UNINDENT +.sp +Deprecated since version 1.7: Equivalent to the \fI\%\-\-natural\-foreign\fP option; use that instead. + +.sp +Use \fInatural keys\fP to represent +any foreign key and many\-to\-many relationship with a model that provides +a natural key definition. +.INDENT 0.0 +.TP +.B \-\-pks +.UNINDENT +.sp +By default, \fBdumpdata\fP will output all the records of the model, but +you can use the \fB\-\-pks\fP option to specify a comma separated list of +primary keys on which to filter. This is only available when dumping +one model. +.INDENT 0.0 +.TP +.B \-\-output +.UNINDENT +.sp + +.sp +By default \fBdumpdata\fP will output all the serialized data to standard output. +This options allows to specify the file to which the data is to be written. +.SS flush +.INDENT 0.0 +.TP +.B django\-admin flush +.UNINDENT +.sp +Removes all data from the database, re\-executes any post\-synchronization +handlers, and reinstalls any initial data fixtures. +.sp +The \fI\%\-\-noinput\fP option may be provided to suppress all user +prompts. +.sp +The \fI\%\-\-database\fP option may be used to specify the database +to flush. +.SS \fB\-\-no\-initial\-data\fP +.sp +Use \fB\-\-no\-initial\-data\fP to avoid loading the initial_data fixture. +.SS inspectdb +.INDENT 0.0 +.TP +.B django\-admin inspectdb +.UNINDENT +.sp +Introspects the database tables and views in the database pointed\-to by the +\fBNAME\fP setting and outputs a Django model module (a \fBmodels.py\fP +file) to standard output. +.sp +Use this if you have a legacy database with which you\(aqd like to use Django. +The script will inspect the database and create a model for each table or view +within it. +.sp +As you might expect, the created models will have an attribute for every field +in the table or view. Note that \fBinspectdb\fP has a few special cases in its +field\-name output: +.INDENT 0.0 +.IP \(bu 2 +If \fBinspectdb\fP cannot map a column\(aqs type to a model field type, it\(aqll +use \fBTextField\fP and will insert the Python comment +\fB\(aqThis field type is a guess.\(aq\fP next to the field in the generated +model. +.IP \(bu 2 +If the database column name is a Python reserved word (such as +\fB\(aqpass\(aq\fP, \fB\(aqclass\(aq\fP or \fB\(aqfor\(aq\fP), \fBinspectdb\fP will append +\fB\(aq_field\(aq\fP to the attribute name. For example, if a table has a column +\fB\(aqfor\(aq\fP, the generated model will have a field \fB\(aqfor_field\(aq\fP, with +the \fBdb_column\fP attribute set to \fB\(aqfor\(aq\fP\&. \fBinspectdb\fP will insert +the Python comment +\fB\(aqField renamed because it was a Python reserved word.\(aq\fP next to the +field. +.UNINDENT +.sp +This feature is meant as a shortcut, not as definitive model generation. After +you run it, you\(aqll want to look over the generated models yourself to make +customizations. In particular, you\(aqll need to rearrange models\(aq order, so that +models that refer to other models are ordered properly. +.sp +Primary keys are automatically introspected for PostgreSQL, MySQL and +SQLite, in which case Django puts in the \fBprimary_key=True\fP where +needed. +.sp +\fBinspectdb\fP works with PostgreSQL, MySQL and SQLite. Foreign\-key detection +only works in PostgreSQL and with certain types of MySQL tables. +.sp +Django doesn\(aqt create database defaults when a +\fBdefault\fP is specified on a model field. +Similarly, database defaults aren\(aqt translated to model field defaults or +detected in any fashion by \fBinspectdb\fP\&. +.sp +By default, \fBinspectdb\fP creates unmanaged models. That is, \fBmanaged = False\fP +in the model\(aqs \fBMeta\fP class tells Django not to manage each table\(aqs creation, +modification, and deletion. If you do want to allow Django to manage the +table\(aqs lifecycle, you\(aqll need to change the +\fBmanaged\fP option to \fBTrue\fP (or simply remove +it because \fBTrue\fP is its default value). +.sp +The \fI\%\-\-database\fP option may be used to specify the +database to introspect. +.sp +A feature to inspect database views was added. In previous versions, only +tables (not views) were inspected. + +.SS loaddata +.INDENT 0.0 +.TP +.B django\-admin loaddata +.UNINDENT +.sp Searches for and loads the contents of the named fixture into the database. +.sp +The \fI\%\-\-database\fP option can be used to specify the database +onto which the data will be loaded. +.INDENT 0.0 .TP -.BI "install [" "app_label ..." "]" -Executes -.B sqlall -for the given app(s) in the current database. +.B \-\-ignorenonexistent +.UNINDENT +.sp +The \fI\%\-\-ignorenonexistent\fP option can be used to ignore fields and +models that may have been removed since the fixture was originally generated. +.INDENT 0.0 .TP -.BI "makemessages [" "\-\-locale=LOCALE" "] [" "\-\-exclude=LOCALE" "] [" "\-\-domain=DOMAIN" "] [" "\-\-extension=EXTENSION" "] [" "\-\-all" "] [" "\-\-symlinks" "] [" "\-\-ignore=PATTERN" "] [" "\-\-no\-default\-ignore" "] [" "\-\-no\-wrap" "] [" "\-\-no\-location" "]" +.B \-\-app +.UNINDENT +.sp +The \fI\%\-\-app\fP option can be used to specify a single app to look +for fixtures in rather than looking through all apps. +.sp +\fB\-\-app\fP was added. + +.sp +\fB\-\-ignorenonexistent\fP also ignores non\-existent models. + +.SS What\(aqs a "fixture"? +.sp +A \fIfixture\fP is a collection of files that contain the serialized contents of +the database. Each fixture has a unique name, and the files that comprise the +fixture can be distributed over multiple directories, in multiple applications. +.sp +Django will search in three locations for fixtures: +.INDENT 0.0 +.IP 1. 3 +In the \fBfixtures\fP directory of every installed application +.IP 2. 3 +In any directory named in the \fBFIXTURE_DIRS\fP setting +.IP 3. 3 +In the literal path named by the fixture +.UNINDENT +.sp +Django will load any and all fixtures it finds in these locations that match +the provided fixture names. +.sp +If the named fixture has a file extension, only fixtures of that type +will be loaded. For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin loaddata mydata.json +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +would only load JSON fixtures called \fBmydata\fP\&. The fixture extension +must correspond to the registered name of a +\fIserializer\fP (e.g., \fBjson\fP or \fBxml\fP). +.sp +If you omit the extensions, Django will search all available fixture types +for a matching fixture. For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin loaddata mydata +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +would look for any fixture of any fixture type called \fBmydata\fP\&. If a fixture +directory contained \fBmydata.json\fP, that fixture would be loaded +as a JSON fixture. +.sp +The fixtures that are named can include directory components. These +directories will be included in the search path. For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin loaddata foo/bar/mydata.json +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +would search \fB/fixtures/foo/bar/mydata.json\fP for each installed +application, \fB/foo/bar/mydata.json\fP for each directory in +\fBFIXTURE_DIRS\fP, and the literal path \fBfoo/bar/mydata.json\fP\&. +.sp +When fixture files are processed, the data is saved to the database as is. +Model defined \fBsave()\fP methods are not called, and +any \fBpre_save\fP or +\fBpost_save\fP signals will be called with +\fBraw=True\fP since the instance only contains attributes that are local to the +model. You may, for example, want to disable handlers that access +related fields that aren\(aqt present during fixture loading and would otherwise +raise an exception: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +from django.db.models.signals import post_save +from .models import MyModel + +def my_handler(**kwargs): + # disable the handler during fixture loading + if kwargs[\(aqraw\(aq]: + return + ... + +post_save.connect(my_handler, sender=MyModel) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +You could also write a simple decorator to encapsulate this logic: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +from functools import wraps + +def disable_for_loaddata(signal_handler): + """ + Decorator that turns off signal handlers when loading fixture data. + """ + @wraps(signal_handler) + def wrapper(*args, **kwargs): + if kwargs[\(aqraw\(aq]: + return + signal_handler(*args, **kwargs) + return wrapper + +@disable_for_loaddata +def my_handler(**kwargs): + ... +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Just be aware that this logic will disable the signals whenever fixtures are +deserialized, not just during \fBloaddata\fP\&. +.sp +Note that the order in which fixture files are processed is undefined. However, +all fixture data is installed as a single transaction, so data in +one fixture can reference data in another fixture. If the database backend +supports row\-level constraints, these constraints will be checked at the +end of the transaction. +.sp +The \fI\%dumpdata\fP command can be used to generate input for \fBloaddata\fP\&. +.SS Compressed fixtures +.sp +Fixtures may be compressed in \fBzip\fP, \fBgz\fP, or \fBbz2\fP format. For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin loaddata mydata.json +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +would look for any of \fBmydata.json\fP, \fBmydata.json.zip\fP, +\fBmydata.json.gz\fP, or \fBmydata.json.bz2\fP\&. The first file contained within a +zip\-compressed archive is used. +.sp +Note that if two fixtures with the same name but different +fixture type are discovered (for example, if \fBmydata.json\fP and +\fBmydata.xml.gz\fP were found in the same fixture directory), fixture +installation will be aborted, and any data installed in the call to +\fBloaddata\fP will be removed from the database. +.INDENT 0.0 +.INDENT 3.5 +.IP "MySQL with MyISAM and fixtures" +.sp +The MyISAM storage engine of MySQL doesn\(aqt support transactions or +constraints, so if you use MyISAM, you won\(aqt get validation of fixture +data, or a rollback if multiple transaction files are found. +.UNINDENT +.UNINDENT +.SS Database\-specific fixtures +.sp +If you\(aqre in a multi\-database setup, you might have fixture data that +you want to load onto one database, but not onto another. In this +situation, you can add database identifier into the names of your fixtures. +.sp +For example, if your \fBDATABASES\fP setting has a \(aqmaster\(aq database +defined, name the fixture \fBmydata.master.json\fP or +\fBmydata.master.json.gz\fP and the fixture will only be loaded when you +specify you want to load data into the \fBmaster\fP database. +.SS makemessages +.INDENT 0.0 +.TP +.B django\-admin makemessages +.UNINDENT +.sp Runs over the entire source tree of the current directory and pulls out all strings marked for translation. It creates (or updates) a message file in the -conf/locale (in the django tree) or locale (for project and application) directory. +conf/locale (in the Django tree) or locale (for project and application) +directory. After making changes to the messages files you need to compile them +with \fI\%compilemessages\fP for use with the builtin gettext support. See +the \fIi18n documentation\fP for details. +.INDENT 0.0 .TP -.BI "runfcgi [" "KEY=val" "] [" "KEY=val" "] " "..." -Runs this project as a FastCGI application. Requires flup. Use -.B runfcgi help -for help on the KEY=val pairs. +.B \-\-all +.UNINDENT +.sp +Use the \fB\-\-all\fP or \fB\-a\fP option to update the message files for all +available languages. +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin makemessages \-\-all +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 .TP -.BI "runserver [" "\-\-noreload" "] [" "\-\-nothreading" "] [" "\-\-nostatic" "] [" "\-\-insecure" "] [" "\-\-ipv6" "] [" "port|ipaddr:port" "]" -Starts a lightweight Web server for development. -.TP -.BI "shell [" "\-\-plain" "]" -Runs a Python interactive interpreter. Tries to use IPython, if it's available. -The -.BI \-\-plain -option forces the use of the standard Python interpreter even when IPython is -installed. -.TP -.BI "sql [" "app_label ..." "]" -Prints the CREATE TABLE SQL statements for the given app name(s). -.TP -.BI "sqlall [" "app_label ..." "]" -Prints the CREATE TABLE, initial\-data and CREATE INDEX SQL statements for the -given model module name(s). -.TP -.BI "sqlclear [" "app_label ..." "]" -Prints the DROP TABLE SQL statements for the given app name(s). -.TP -.BI "sqlcustom [" "app_label ..." "]" -Prints the custom SQL statements for the given app name(s). -.TP -.BI "sqlflush [" "app_label ..." "]" -Prints the SQL statements that would be executed for the "flush" command. -.TP -.BI "sqlindexes [" "app_label ..." "]" -Prints the CREATE INDEX SQL statements for the given model module name(s). -.TP -.BI "sqlsequencereset [" "app_label ..." "]" -Prints the SQL statements for resetting PostgreSQL sequences for the -given app name(s). -.TP -.BI "startapp [" "\-\-template=PATH_OR_URL" "] [" "\-\-extension=EXTENSION" "] [" "\-\-name=FILENAME" "] [" "app_label" "] [" "destination" "]" -Creates a Django app directory structure for the given app name in -the current directory or the optional destination. -.TP -.BI "startproject [" "\-\-template=PATH_OR_URL" "] [" "\-\-extension=EXTENSION" "] [" "\-\-name=FILENAME" "] [" "projectname" "] [" "destination" "]" -Creates a Django project directory structure for the given project name -in the current directory or the optional destination. -.TP -.BI migrate -Runs migrations for apps containing migrations, and just creates missing tables -for apps without migrations. -.TP -.BI "test [" "\-\-verbosity" "] [" "\-\-failfast" "] [" "app_label ..." "]" -Runs the test suite for the specified applications, or the entire project if -no apps are specified -.TP -.BI "testserver [" "\-\-addrport=ipaddr|port" "] [" "fixture fixture ..." "]" -Runs the test suite for the specified applications, or the entire project if -no apps are specified -.TP -.BI validate -Validates all installed models. -.SH "OPTIONS" -.TP -.I \-\-version -Show program's version number and exit. -.TP -.I \-h, \-\-help -Show this help message and exit. -.TP -.I \-\-settings=SETTINGS -Python path to settings module, e.g. "myproject.settings.main". If -this isn't provided, the DJANGO_SETTINGS_MODULE environment variable -will be used. -.TP -.I \-\-pythonpath=PYTHONPATH -Lets you manually add a directory the Python path, -e.g. "/home/djangoprojects/myproject". -.TP -.I \-\-plain -Use plain Python, not IPython, for the "shell" command. -.TP -.I \-\-noinput -Do not prompt the user for input. -.TP -.I \-\-noreload -Disable the development server's auto\-reloader. -.TP -.I \-\-nostatic -Disable automatic serving of static files from STATIC_URL. -.TP -.I \-\-nothreading -Disable the development server's threading. -.TP -.I \-\-insecure -Enables serving of static files even if DEBUG is False. -.TP -.I \-\-ipv6 -Enables IPv6 addresses. -.TP -.I \-\-verbosity=VERBOSITY -Verbosity level: 0=minimal output, 1=normal output, 2=all output. -.TP -.I \-\-traceback -By default, django-admin will show a simple error message whenever an -error occurs. If you specify this option, django-admin will -output a full stack trace whenever an exception is raised. -.TP -.I \-l, \-\-locale=LOCALE -The locale to process when using makemessages or compilemessages. -.TP -.I \-x, \-\-exclude=LOCALE -The locale to exclude from processing when using makemessages or compilemessages. -.TP -.I \-d, \-\-domain=DOMAIN -The domain of the message files (default: "django") when using makemessages. -.TP -.I \-e, \-\-extension=EXTENSION -The file extension(s) to examine (separate multiple -extensions with commas, or use \-e multiple times) (makemessages command). -.TP -.I \-s, \-\-symlinks -Follows symlinks to directories when examining source code and templates for -translation strings (makemessages command). -.TP -.I \-i, \-\-ignore=PATTERN -Ignore files or directories matching this glob-style pattern. Use multiple -times to ignore more (makemessages command). -.TP -.I \-\-no\-default\-ignore -Don't ignore the common private glob-style patterns 'CVS', '.*', '*~' and '*.pyc' -(makemessages command). -.TP -.I \-\-no\-wrap -Don't break long message lines into several lines (makemessages command). -.TP -.I \-\-no\-location -Don't write '#: filename:line' comment lines in language files (makemessages command). -.TP -.I \-a, \-\-all -Process all available locales when using makemessages. -.TP -.I \-\-template=PATH_OR_URL -The file or directory path or URL to load the project and app templates from. -.TP -.I \-n, \-\-name=FILENAME -The name of an additional file to render when using app and project templates. -.TP -.I \-\-database=DB -Used to specify the database on which a command will operate. If not -specified, this option will default to an alias of "default". -.SH "ENVIRONMENT" -.TP -.I DJANGO_SETTINGS_MODULE -In the absence of the -.BI \-\-settings -option, this environment variable defines the settings module to be read. -It should be in Python-import form, e.g. "myproject.settings". +.B \-\-extension +.UNINDENT +.sp +Use the \fB\-\-extension\fP or \fB\-e\fP option to specify a list of file extensions +to examine (default: ".html", ".txt"). +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin makemessages \-\-locale=de \-\-extension xhtml +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Separate multiple extensions with commas or use \-e or \-\-extension multiple times: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin makemessages \-\-locale=de \-\-extension=html,txt \-\-extension xml +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Use the \fI\%\-\-locale\fP option (or its shorter version \fB\-l\fP) to +specify the locale(s) to process. +.sp -.SH "SEE ALSO" -Full descriptions of all these options, with examples, as well as documentation -for the rest of the Django framework, can be found on the Django site: .sp -.I http://docs.djangoproject.com/en/dev/ +Use the \fI\%\-\-exclude\fP option (or its shorter version \fB\-x\fP) to +specify the locale(s) to exclude from processing. If not provided, no locales +are excluded. .sp -or in the distributed documentation. -.SH "AUTHORS/CREDITS" -Originally developed at World Online in Lawrence, Kansas, USA. Refer to the -AUTHORS file in the Django distribution for contributors. +Example usage: +.INDENT 0.0 +.INDENT 3.5 .sp -.SH "LICENSE" -New BSD license. For the full license text refer to the LICENSE file in the -Django distribution. +.nf +.ft C +django\-admin makemessages \-\-locale=pt_BR +django\-admin makemessages \-\-locale=pt_BR \-\-locale=fr +django\-admin makemessages \-l pt_BR +django\-admin makemessages \-l pt_BR \-l fr +django\-admin makemessages \-\-exclude=pt_BR +django\-admin makemessages \-\-exclude=pt_BR \-\-exclude=fr +django\-admin makemessages \-x pt_BR +django\-admin makemessages \-x pt_BR \-x fr +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Added the \fB\-\-previous\fP option to the \fBmsgmerge\fP command when merging +with existing po files. + +.INDENT 0.0 +.TP +.B \-\-domain +.UNINDENT +.sp +Use the \fB\-\-domain\fP or \fB\-d\fP option to change the domain of the messages files. +Currently supported: +.INDENT 0.0 +.IP \(bu 2 +\fBdjango\fP for all \fB*.py\fP, \fB*.html\fP and \fB*.txt\fP files (default) +.IP \(bu 2 +\fBdjangojs\fP for \fB*.js\fP files +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-symlinks +.UNINDENT +.sp +Use the \fB\-\-symlinks\fP or \fB\-s\fP option to follow symlinks to directories when +looking for new translation strings. +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin makemessages \-\-locale=de \-\-symlinks +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-ignore +.UNINDENT +.sp +Use the \fB\-\-ignore\fP or \fB\-i\fP option to ignore files or directories matching +the given \fI\%glob\fP\-style pattern. Use multiple times to ignore more. +.sp +These patterns are used by default: \fB\(aqCVS\(aq\fP, \fB\(aq.*\(aq\fP, \fB\(aq*~\(aq\fP, \fB\(aq*.pyc\(aq\fP +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin makemessages \-\-locale=en_US \-\-ignore=apps/* \-\-ignore=secret/*.html +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-default\-ignore +.UNINDENT +.sp +Use the \fB\-\-no\-default\-ignore\fP option to disable the default values of +\fI\%\-\-ignore\fP\&. +.INDENT 0.0 +.TP +.B \-\-no\-wrap +.UNINDENT +.sp +Use the \fB\-\-no\-wrap\fP option to disable breaking long message lines into +several lines in language files. +.INDENT 0.0 +.TP +.B \-\-no\-location +.UNINDENT +.sp +Use the \fB\-\-no\-location\fP option to not write \(aq\fB#: filename:line\fP’ +comment lines in language files. Note that using this option makes it harder +for technically skilled translators to understand each message\(aqs context. +.INDENT 0.0 +.TP +.B \-\-keep\-pot +.UNINDENT +.sp +Use the \fB\-\-keep\-pot\fP option to prevent Django from deleting the temporary +.pot files it generates before creating the .po file. This is useful for +debugging errors which may prevent the final language files from being created. +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +See \fIcustomizing\-makemessages\fP for instructions on how to customize +the keywords that \fI\%makemessages\fP passes to \fBxgettext\fP\&. +.UNINDENT +.UNINDENT +.SS makemigrations [] +.INDENT 0.0 +.TP +.B django\-admin makemigrations +.UNINDENT +.sp + +.sp +Creates new migrations based on the changes detected to your models. +Migrations, their relationship with apps and more are covered in depth in +\fBthe migrations documentation\fP\&. +.sp +Providing one or more app names as arguments will limit the migrations created +to the app(s) specified and any dependencies needed (the table at the other end +of a \fBForeignKey\fP, for example). +.INDENT 0.0 +.TP +.B \-\-empty +.UNINDENT +.sp +The \fB\-\-empty\fP option will cause \fBmakemigrations\fP to output an empty +migration for the specified apps, for manual editing. This option is only +for advanced users and should not be used unless you are familiar with +the migration format, migration operations, and the dependencies between +your migrations. +.INDENT 0.0 +.TP +.B \-\-dry\-run +.UNINDENT +.sp +The \fB\-\-dry\-run\fP option shows what migrations would be made without +actually writing any migrations files to disk. Using this option along with +\fB\-\-verbosity 3\fP will also show the complete migrations files that would be +written. +.INDENT 0.0 +.TP +.B \-\-merge +.UNINDENT +.sp +The \fB\-\-merge\fP option enables fixing of migration conflicts. The +\fI\%\-\-noinput\fP option may be provided to suppress user prompts during +a merge. +.INDENT 0.0 +.TP +.B \-\-name, \-n +.UNINDENT +.sp + +.sp +The \fB\-\-name\fP option allows you to give the migration(s) a custom name instead +of a generated one. +.INDENT 0.0 +.TP +.B \-\-exit, \-e +.UNINDENT +.sp + +.sp +The \fB\-\-exit\fP option will cause \fBmakemigrations\fP to exit with error code 1 +when no migration are created (or would have been created, if combined with +\fB\-\-dry\-run\fP). +.SS migrate [ []] +.INDENT 0.0 +.TP +.B django\-admin migrate +.UNINDENT +.sp + +.sp +Synchronizes the database state with the current set of models and migrations. +Migrations, their relationship with apps and more are covered in depth in +\fBthe migrations documentation\fP\&. +.sp +The behavior of this command changes depending on the arguments provided: +.INDENT 0.0 +.IP \(bu 2 +No arguments: All migrated apps have all of their migrations run, +and all unmigrated apps are synchronized with the database, +.IP \(bu 2 +\fB\fP: The specified app has its migrations run, up to the most +recent migration. This may involve running other apps\(aq migrations too, due +to dependencies. +.IP \(bu 2 +\fB \fP: Brings the database schema to a state where +the named migration is applied, but no later migrations in the same app are +applied. This may involve unapplying migrations if you have previously +migrated past the named migration. Use the name \fBzero\fP to unapply all +migrations for an app. +.UNINDENT +.sp +Unlike \fBsyncdb\fP, this command does not prompt you to create a superuser if +one doesn\(aqt exist (assuming you are using \fBdjango.contrib.auth\fP). Use +\fI\%createsuperuser\fP to do that if you wish. +.sp +The \fI\%\-\-database\fP option can be used to specify the database to +migrate. +.INDENT 0.0 +.TP +.B \-\-fake +.UNINDENT +.sp +The \fB\-\-fake\fP option tells Django to mark the migrations as having been +applied or unapplied, but without actually running the SQL to change your +database schema. +.sp +This is intended for advanced users to manipulate the +current migration state directly if they\(aqre manually applying changes; +be warned that using \fB\-\-fake\fP runs the risk of putting the migration state +table into a state where manual recovery will be needed to make migrations +run correctly. +.sp + +.INDENT 0.0 +.TP +.B \-\-fake\-initial +.UNINDENT +.sp +The \fB\-\-fake\-initial\fP option can be used to allow Django to skip an app\(aqs +initial migration if all database tables with the names of all models created +by all \fBCreateModel\fP operations in that +migration already exist. This option is intended for use when first running +migrations against a database that preexisted the use of migrations. This +option does not, however, check for matching database schema beyond matching +table names and so is only safe to use if you are confident that your existing +schema matches what is recorded in your initial migration. +.sp +Deprecated since version 1.8: The \fB\-\-list\fP option has been moved to the \fI\%showmigrations\fP +command. + +.SS runfcgi [options] +.INDENT 0.0 +.TP +.B django\-admin runfcgi +.UNINDENT +.sp +Deprecated since version 1.7: FastCGI support is deprecated and will be removed in Django 1.9. + +.sp +Starts a set of FastCGI processes suitable for use with any Web server that +supports the FastCGI protocol. See the \fBFastCGI deployment documentation\fP for details. Requires the Python FastCGI module from +\fI\%flup\fP\&. +.sp +Internally, this wraps the WSGI application object specified by the +\fBWSGI_APPLICATION\fP setting. +.sp +The options accepted by this command are passed to the FastCGI library and +don\(aqt use the \fB\(aq\-\-\(aq\fP prefix as is usual for other Django management commands. +.INDENT 0.0 +.TP +.B protocol +.UNINDENT +.sp +\fBprotocol=PROTOCOL\fP +.sp +Protocol to use. \fIPROTOCOL\fP can be \fBfcgi\fP, \fBscgi\fP, \fBajp\fP, etc. +(default is \fBfcgi\fP) +.INDENT 0.0 +.TP +.B host +.UNINDENT +.sp +\fBhost=HOSTNAME\fP +.sp +Hostname to listen on. +.INDENT 0.0 +.TP +.B port +.UNINDENT +.sp +\fBport=PORTNUM\fP +.sp +Port to listen on. +.INDENT 0.0 +.TP +.B socket +.UNINDENT +.sp +\fBsocket=FILE\fP +.sp +UNIX socket to listen on. +.INDENT 0.0 +.TP +.B method +.UNINDENT +.sp +\fBmethod=IMPL\fP +.sp +Possible values: \fBprefork\fP or \fBthreaded\fP (default \fBprefork\fP) +.INDENT 0.0 +.TP +.B maxrequests +.UNINDENT +.sp +\fBmaxrequests=NUMBER\fP +.sp +Number of requests a child handles before it is killed and a new child is +forked (0 means no limit). +.INDENT 0.0 +.TP +.B maxspare +.UNINDENT +.sp +\fBmaxspare=NUMBER\fP +.sp +Max number of spare processes / threads. +.INDENT 0.0 +.TP +.B minspare +.UNINDENT +.sp +\fBminspare=NUMBER\fP +.sp +Min number of spare processes / threads. +.INDENT 0.0 +.TP +.B maxchildren +.UNINDENT +.sp +\fBmaxchildren=NUMBER\fP +.sp +Hard limit number of processes / threads. +.INDENT 0.0 +.TP +.B daemonize +.UNINDENT +.sp +\fBdaemonize=BOOL\fP +.sp +Whether to detach from terminal. +.INDENT 0.0 +.TP +.B pidfile +.UNINDENT +.sp +\fBpidfile=FILE\fP +.sp +Write the spawned process\-id to file \fIFILE\fP\&. +.INDENT 0.0 +.TP +.B workdir +.UNINDENT +.sp +\fBworkdir=DIRECTORY\fP +.sp +Change to directory \fIDIRECTORY\fP when daemonizing. +.INDENT 0.0 +.TP +.B debug +.UNINDENT +.sp +\fBdebug=BOOL\fP +.sp +Set to true to enable flup tracebacks. +.INDENT 0.0 +.TP +.B outlog +.UNINDENT +.sp +\fBoutlog=FILE\fP +.sp +Write stdout to the \fIFILE\fP file. +.INDENT 0.0 +.TP +.B errlog +.UNINDENT +.sp +\fBerrlog=FILE\fP +.sp +Write stderr to the \fIFILE\fP file. +.INDENT 0.0 +.TP +.B umask +.UNINDENT +.sp +\fBumask=UMASK\fP +.sp +Umask to use when daemonizing. The value is interpreted as an octal number +(default value is \fB0o22\fP). +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin runfcgi socket=/tmp/fcgi.sock method=prefork daemonize=true \e + pidfile=/var/run/django\-fcgi.pid +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Run a FastCGI server as a daemon and write the spawned PID in a file. +.SS runserver [port or address:port] +.INDENT 0.0 +.TP +.B django\-admin runserver +.UNINDENT +.sp +Starts a lightweight development Web server on the local machine. By default, +the server runs on port 8000 on the IP address \fB127.0.0.1\fP\&. You can pass in an +IP address and port number explicitly. +.sp +If you run this script as a user with normal privileges (recommended), you +might not have access to start a port on a low port number. Low port numbers +are reserved for the superuser (root). +.sp +This server uses the WSGI application object specified by the +\fBWSGI_APPLICATION\fP setting. +.sp +DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through +security audits or performance tests. (And that\(aqs how it\(aqs gonna stay. We\(aqre in +the business of making Web frameworks, not Web servers, so improving this +server to be able to handle a production environment is outside the scope of +Django.) +.sp +The development server automatically reloads Python code for each request, as +needed. You don\(aqt need to restart the server for code changes to take effect. +However, some actions like adding files don\(aqt trigger a restart, so you\(aqll +have to restart the server in these cases. +.sp +Compiling translation files now also restarts the development server. + +.sp +If you are using Linux and install \fI\%pyinotify\fP, kernel signals will be used to +autoreload the server (rather than polling file modification timestamps each +second). This offers better scaling to large projects, reduction in response +time to code modification, more robust change detection, and battery usage +reduction. +.sp +\fBpyinotify\fP support was added. + +.sp +When you start the server, and each time you change Python code while the +server is running, the server will check your entire Django project for errors (see +the \fI\%check\fP command). If any errors are found, they will be printed +to standard output, but it won\(aqt stop the server. +.sp +You can run as many servers as you want, as long as they\(aqre on separate ports. +Just execute \fBdjango\-admin runserver\fP more than once. +.sp +Note that the default IP address, \fB127.0.0.1\fP, is not accessible from other +machines on your network. To make your development server viewable to other +machines on the network, use its own IP address (e.g. \fB192.168.2.1\fP) or +\fB0.0.0.0\fP or \fB::\fP (with IPv6 enabled). +.sp +You can provide an IPv6 address surrounded by brackets +(e.g. \fB[200a::1]:8000\fP). This will automatically enable IPv6 support. +.sp +A hostname containing ASCII\-only characters can also be used. +.sp +If the \fBstaticfiles\fP contrib app is enabled +(default in new projects) the \fI\%runserver\fP command will be overridden +with its own \fIrunserver\fP command. +.sp +If \fI\%migrate\fP was not previously executed, the table that stores the +history of migrations is created at first run of \fBrunserver\fP\&. +.INDENT 0.0 +.TP +.B \-\-noreload +.UNINDENT +.sp +Use the \fB\-\-noreload\fP option to disable the use of the auto\-reloader. This +means any Python code changes you make while the server is running will \fInot\fP +take effect if the particular Python modules have already been loaded into +memory. +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin runserver \-\-noreload +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-nothreading +.UNINDENT +.sp +The development server is multithreaded by default. Use the \fB\-\-nothreading\fP +option to disable the use of threading in the development server. +.INDENT 0.0 +.TP +.B \-\-ipv6, \-6 +.UNINDENT +.sp +Use the \fB\-\-ipv6\fP (or shorter \fB\-6\fP) option to tell Django to use IPv6 for +the development server. This changes the default IP address from +\fB127.0.0.1\fP to \fB::1\fP\&. +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin runserver \-\-ipv6 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Examples of using different ports and addresses +.sp +Port 8000 on IP address \fB127.0.0.1\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin runserver +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Port 8000 on IP address \fB1.2.3.4\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin runserver 1.2.3.4:8000 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Port 7000 on IP address \fB127.0.0.1\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin runserver 7000 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Port 7000 on IP address \fB1.2.3.4\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin runserver 1.2.3.4:7000 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Port 8000 on IPv6 address \fB::1\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin runserver \-6 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Port 7000 on IPv6 address \fB::1\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin runserver \-6 7000 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Port 7000 on IPv6 address \fB2001:0db8:1234:5678::9\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin runserver [2001:0db8:1234:5678::9]:7000 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Port 8000 on IPv4 address of host \fBlocalhost\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin runserver localhost:8000 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Port 8000 on IPv6 address of host \fBlocalhost\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin runserver \-6 localhost:8000 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Serving static files with the development server +.sp +By default, the development server doesn\(aqt serve any static files for your site +(such as CSS files, images, things under \fBMEDIA_URL\fP and so forth). If +you want to configure Django to serve static media, read +\fB/howto/static\-files/index\fP\&. +.SS shell +.INDENT 0.0 +.TP +.B django\-admin shell +.UNINDENT +.sp +Starts the Python interactive interpreter. +.sp +Django will use \fI\%IPython\fP or \fI\%bpython\fP if either is installed. If you have a +rich shell installed but want to force use of the "plain" Python interpreter, +use the \fB\-\-plain\fP option, like so: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin shell \-\-plain +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If you would like to specify either IPython or bpython as your interpreter if +you have both installed you can specify an alternative interpreter interface +with the \fB\-i\fP or \fB\-\-interface\fP options like so: +.sp +IPython: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin shell \-i ipython +django\-admin shell \-\-interface ipython +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +bpython: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin shell \-i bpython +django\-admin shell \-\-interface bpython +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +When the "plain" Python interactive interpreter starts (be it because +\fB\-\-plain\fP was specified or because no other interactive interface is +available) it reads the script pointed to by the \fI\%PYTHONSTARTUP\fP +environment variable and the \fB~/.pythonrc.py\fP script. If you don\(aqt wish this +behavior you can use the \fB\-\-no\-startup\fP option. e.g.: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin shell \-\-plain \-\-no\-startup +.ft P +.fi +.UNINDENT +.UNINDENT +.SS showmigrations [ []] +.INDENT 0.0 +.TP +.B django\-admin showmigrations +.UNINDENT +.sp + +.sp +Shows all migrations in a project. +.INDENT 0.0 +.TP +.B \-\-list, \-l +.UNINDENT +.sp +The \fB\-\-list\fP option lists all of the apps Django knows about, the +migrations available for each app, and whether or not each migrations is +applied (marked by an \fB[X]\fP next to the migration name). +.sp +Apps without migrations are also listed, but have \fB(no migrations)\fP printed +under them. +.INDENT 0.0 +.TP +.B \-\-plan, \-p +.UNINDENT +.sp +The \fB\-\-plan\fP option shows the migration plan Django will follow to apply +migrations. Any supplied app labels are ignored because the plan might go +beyond those apps. Same as \fB\-\-list\fP, applied migrations are marked by an +\fB[X]\fP\&. For a verbosity of 2 and above, all dependencies of a migration will +also be shown. +.SS sql +.INDENT 0.0 +.TP +.B django\-admin sql +.UNINDENT +.sp +Prints the CREATE TABLE SQL statements for the given app name(s). +.sp +The \fI\%\-\-database\fP option can be used to specify the database for +which to print the SQL. +.SS sqlall +.INDENT 0.0 +.TP +.B django\-admin sqlall +.UNINDENT +.sp +Prints the CREATE TABLE and initial\-data SQL statements for the given app name(s). +.sp +Refer to the description of \fI\%sqlcustom\fP for an explanation of how to +specify initial data. +.sp +The \fI\%\-\-database\fP option can be used to specify the database for +which to print the SQL. +.sp +The \fBsql*\fP management commands now respect the \fBallow_migrate()\fP method +of \fBDATABASE_ROUTERS\fP\&. If you have models synced to non\-default +databases, use the \fI\%\-\-database\fP flag to get SQL for those +models (previously they would always be included in the output). + +.SS sqlclear +.INDENT 0.0 +.TP +.B django\-admin sqlclear +.UNINDENT +.sp +Prints the DROP TABLE SQL statements for the given app name(s). +.sp +The \fI\%\-\-database\fP option can be used to specify the database for +which to print the SQL. +.SS sqlcustom +.INDENT 0.0 +.TP +.B django\-admin sqlcustom +.UNINDENT +.sp +Prints the custom SQL statements for the given app name(s). +.sp +For each model in each specified app, this command looks for the file +\fB/sql/.sql\fP, where \fB\fP is the given app +name and \fB\fP is the model\(aqs name in lowercase. For example, if you +have an app \fBnews\fP that includes a \fBStory\fP model, \fBsqlcustom\fP will +attempt to read a file \fBnews/sql/story.sql\fP and append it to the output of +this command. +.sp +Each of the SQL files, if given, is expected to contain valid SQL. The SQL +files are piped directly into the database after all of the models\(aq +table\-creation statements have been executed. Use this SQL hook to make any +table modifications, or insert any SQL functions into the database. +.sp +Note that the order in which the SQL files are processed is undefined. +.sp +The \fI\%\-\-database\fP option can be used to specify the database for +which to print the SQL. +.SS sqldropindexes +.INDENT 0.0 +.TP +.B django\-admin sqldropindexes +.UNINDENT +.sp +Prints the DROP INDEX SQL statements for the given app name(s). +.sp +The \fI\%\-\-database\fP option can be used to specify the database for +which to print the SQL. +.SS sqlflush +.INDENT 0.0 +.TP +.B django\-admin sqlflush +.UNINDENT +.sp +Prints the SQL statements that would be executed for the \fI\%flush\fP +command. +.sp +The \fI\%\-\-database\fP option can be used to specify the database for +which to print the SQL. +.SS sqlindexes +.INDENT 0.0 +.TP +.B django\-admin sqlindexes +.UNINDENT +.sp +Prints the CREATE INDEX SQL statements for the given app name(s). +.sp +The \fI\%\-\-database\fP option can be used to specify the database for +which to print the SQL. +.SS sqlmigrate +.INDENT 0.0 +.TP +.B django\-admin sqlmigrate +.UNINDENT +.sp +Prints the SQL for the named migration. This requires an active database +connection, which it will use to resolve constraint names; this means you must +generate the SQL against a copy of the database you wish to later apply it on. +.sp +Note that \fBsqlmigrate\fP doesn\(aqt colorize its output. +.sp +The \fI\%\-\-database\fP option can be used to specify the database for +which to generate the SQL. +.INDENT 0.0 +.TP +.B \-\-backwards +.UNINDENT +.sp +By default, the SQL created is for running the migration in the forwards +direction. Pass \fB\-\-backwards\fP to generate the SQL for +unapplying the migration instead. +.SS sqlsequencereset +.INDENT 0.0 +.TP +.B django\-admin sqlsequencereset +.UNINDENT +.sp +Prints the SQL statements for resetting sequences for the given app name(s). +.sp +Sequences are indexes used by some database engines to track the next available +number for automatically incremented fields. +.sp +Use this command to generate SQL which will fix cases where a sequence is out +of sync with its automatically incremented field data. +.sp +The \fI\%\-\-database\fP option can be used to specify the database for +which to print the SQL. +.SS squashmigrations +.INDENT 0.0 +.TP +.B django\-admin squashmigrations +.UNINDENT +.sp +Squashes the migrations for \fBapp_label\fP up to and including \fBmigration_name\fP +down into fewer migrations, if possible. The resulting squashed migrations +can live alongside the unsquashed ones safely. For more information, +please read \fImigration\-squashing\fP\&. +.INDENT 0.0 +.TP +.B \-\-no\-optimize +.UNINDENT +.sp +By default, Django will try to optimize the operations in your migrations +to reduce the size of the resulting file. Pass \fB\-\-no\-optimize\fP if this +process is failing for you or creating incorrect migrations, though please +also file a Django bug report about the behavior, as optimization is meant +to be safe. +.SS startapp [destination] +.INDENT 0.0 +.TP +.B django\-admin startapp +.UNINDENT +.sp +Creates a Django app directory structure for the given app name in the current +directory or the given destination. +.sp +By default the directory created contains a \fBmodels.py\fP file and other app +template files. (See the \fI\%source\fP for more details.) If only the app +name is given, the app directory will be created in the current working +directory. +.sp +If the optional destination is provided, Django will use that existing +directory rather than creating a new one. You can use \(aq.\(aq to denote the current +working directory. +.sp +For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin startapp myapp /Users/jezdez/Code/myapp +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-template +.UNINDENT +.sp +With the \fB\-\-template\fP option, you can use a custom app template by providing +either the path to a directory with the app template file, or a path to a +compressed file (\fB\&.tar.gz\fP, \fB\&.tar.bz2\fP, \fB\&.tgz\fP, \fB\&.tbz\fP, \fB\&.zip\fP) +containing the app template files. +.sp +For example, this would look for an app template in the given directory when +creating the \fBmyapp\fP app: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin startapp \-\-template=/Users/jezdez/Code/my_app_template myapp +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Django will also accept URLs (\fBhttp\fP, \fBhttps\fP, \fBftp\fP) to compressed +archives with the app template files, downloading and extracting them on the +fly. +.sp +For example, taking advantage of Github\(aqs feature to expose repositories as +zip files, you can use a URL like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin startapp \-\-template=https://github.com/githubuser/django\-app\-template/archive/master.zip myapp +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +When Django copies the app template files, it also renders certain files +through the template engine: the files whose extensions match the +\fB\-\-extension\fP option (\fBpy\fP by default) and the files whose names are passed +with the \fB\-\-name\fP option. The \fBtemplate context\fP used is: +.INDENT 0.0 +.IP \(bu 2 +Any option passed to the \fBstartapp\fP command (among the command\(aqs supported +options) +.IP \(bu 2 +\fBapp_name\fP \-\- the app name as passed to the command +.IP \(bu 2 +\fBapp_directory\fP \-\- the full path of the newly created app +.IP \(bu 2 +\fBdocs_version\fP \-\- the version of the documentation: \fB\(aqdev\(aq\fP or \fB\(aq1.x\(aq\fP +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +When the app template files are rendered with the Django template +engine (by default all \fB*.py\fP files), Django will also replace all +stray template variables contained. For example, if one of the Python files +contains a docstring explaining a particular feature related +to template rendering, it might result in an incorrect example. +.sp +To work around this problem, you can use the \fBtemplatetag\fP +templatetag to "escape" the various parts of the template syntax. +.UNINDENT +.UNINDENT +.SS startproject [destination] +.INDENT 0.0 +.TP +.B django\-admin startproject +.UNINDENT +.sp +Creates a Django project directory structure for the given project name in +the current directory or the given destination. +.sp +By default, the new directory contains \fBmanage.py\fP and a project package +(containing a \fBsettings.py\fP and other files). See the \fI\%template source\fP for +details. +.sp +If only the project name is given, both the project directory and project +package will be named \fB\fP and the project directory +will be created in the current working directory. +.sp +If the optional destination is provided, Django will use that existing +directory as the project directory, and create \fBmanage.py\fP and the project +package within it. Use \(aq.\(aq to denote the current working directory. +.sp +For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin startproject myproject /Users/jezdez/Code/myproject_repo +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +As with the \fI\%startapp\fP command, the \fB\-\-template\fP option lets you +specify a directory, file path or URL of a custom project template. See the +\fI\%startapp\fP documentation for details of supported project template +formats. +.sp +For example, this would look for a project template in the given directory +when creating the \fBmyproject\fP project: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin startproject \-\-template=/Users/jezdez/Code/my_project_template myproject +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Django will also accept URLs (\fBhttp\fP, \fBhttps\fP, \fBftp\fP) to compressed +archives with the project template files, downloading and extracting them on the +fly. +.sp +For example, taking advantage of Github\(aqs feature to expose repositories as +zip files, you can use a URL like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin startproject \-\-template=https://github.com/githubuser/django\-project\-template/archive/master.zip myproject +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +When Django copies the project template files, it also renders certain files +through the template engine: the files whose extensions match the +\fB\-\-extension\fP option (\fBpy\fP by default) and the files whose names are passed +with the \fB\-\-name\fP option. The \fBtemplate context\fP used is: +.INDENT 0.0 +.IP \(bu 2 +Any option passed to the \fBstartproject\fP command (among the command\(aqs +supported options) +.IP \(bu 2 +\fBproject_name\fP \-\- the project name as passed to the command +.IP \(bu 2 +\fBproject_directory\fP \-\- the full path of the newly created project +.IP \(bu 2 +\fBsecret_key\fP \-\- a random key for the \fBSECRET_KEY\fP setting +.IP \(bu 2 +\fBdocs_version\fP \-\- the version of the documentation: \fB\(aqdev\(aq\fP or \fB\(aq1.x\(aq\fP +.UNINDENT +.sp +Please also see the \fI\%rendering warning\fP as mentioned +for \fI\%startapp\fP\&. +.SS syncdb +.INDENT 0.0 +.TP +.B django\-admin syncdb +.UNINDENT +.sp +Deprecated since version 1.7: This command has been deprecated in favor of the \fI\%migrate\fP +command, which performs both the old behavior as well as executing +migrations. It is now just an alias to that command. + +.sp +Alias for \fI\%migrate\fP\&. +.SS test +.INDENT 0.0 +.TP +.B django\-admin test +.UNINDENT +.sp +Runs tests for all installed models. See \fB/topics/testing/index\fP for more +information. +.INDENT 0.0 +.TP +.B \-\-failfast +.UNINDENT +.sp +The \fB\-\-failfast\fP option can be used to stop running tests and report the +failure immediately after a test fails. +.INDENT 0.0 +.TP +.B \-\-testrunner +.UNINDENT +.sp +The \fB\-\-testrunner\fP option can be used to control the test runner class that +is used to execute tests. If this value is provided, it overrides the value +provided by the \fBTEST_RUNNER\fP setting. +.INDENT 0.0 +.TP +.B \-\-liveserver +.UNINDENT +.sp +The \fB\-\-liveserver\fP option can be used to override the default address where +the live server (used with \fBLiveServerTestCase\fP) is +expected to run from. The default value is \fBlocalhost:8081\fP\&. +.INDENT 0.0 +.TP +.B \-\-keepdb +.UNINDENT +.sp + +.sp +The \fB\-\-keepdb\fP option can be used to preserve the test database between test +runs. This has the advantage of skipping both the create and destroy actions +which greatly decreases the time to run tests, especially those in a large +test suite. If the test database does not exist, it will be created on the first +run and then preserved for each subsequent run. Any unapplied migrations will also +be applied to the test database before running the test suite. +.INDENT 0.0 +.TP +.B \-\-reverse +.UNINDENT +.sp + +.sp +The \fB\-\-reverse\fP option can be used to sort test cases in the opposite order. +This may help in debugging tests that aren\(aqt properly isolated and have side +effects. \fIGrouping by test class\fP is preserved when using +this option. +.INDENT 0.0 +.TP +.B \-\-debug\-sql +.UNINDENT +.sp + +.sp +The \fB\-\-debug\-sql\fP option can be used to enable \fISQL logging\fP for failing tests. If \fI\%\-\-verbosity\fP is \fB2\fP, +then queries in passing tests are also output. +.SS testserver +.INDENT 0.0 +.TP +.B django\-admin testserver +.UNINDENT +.sp +Runs a Django development server (as in \fI\%runserver\fP) using data from +the given fixture(s). +.sp +For example, this command: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin testserver mydata.json +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\&...would perform the following steps: +.INDENT 0.0 +.IP 1. 3 +Create a test database, as described in \fIthe\-test\-database\fP\&. +.IP 2. 3 +Populate the test database with fixture data from the given fixtures. +(For more on fixtures, see the documentation for \fI\%loaddata\fP above.) +.IP 3. 3 +Runs the Django development server (as in \fI\%runserver\fP), pointed at +this newly created test database instead of your production database. +.UNINDENT +.sp +This is useful in a number of ways: +.INDENT 0.0 +.IP \(bu 2 +When you\(aqre writing \fBunit tests\fP of how your views +act with certain fixture data, you can use \fBtestserver\fP to interact with +the views in a Web browser, manually. +.IP \(bu 2 +Let\(aqs say you\(aqre developing your Django application and have a "pristine" +copy of a database that you\(aqd like to interact with. You can dump your +database to a fixture (using the \fI\%dumpdata\fP command, explained +above), then use \fBtestserver\fP to run your Web application with that data. +With this arrangement, you have the flexibility of messing up your data +in any way, knowing that whatever data changes you\(aqre making are only +being made to a test database. +.UNINDENT +.sp +Note that this server does \fInot\fP automatically detect changes to your Python +source code (as \fI\%runserver\fP does). It does, however, detect changes to +templates. +.INDENT 0.0 +.TP +.B \-\-addrport [port number or ipaddr:port] +.UNINDENT +.sp +Use \fB\-\-addrport\fP to specify a different port, or IP address and port, from +the default of \fB127.0.0.1:8000\fP\&. This value follows exactly the same format and +serves exactly the same function as the argument to the \fI\%runserver\fP +command. +.sp +Examples: +.sp +To run the test server on port 7000 with \fBfixture1\fP and \fBfixture2\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin testserver \-\-addrport 7000 fixture1 fixture2 +django\-admin testserver fixture1 fixture2 \-\-addrport 7000 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +(The above statements are equivalent. We include both of them to demonstrate +that it doesn\(aqt matter whether the options come before or after the fixture +arguments.) +.sp +To run on 1.2.3.4:7000 with a \fBtest\fP fixture: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin testserver \-\-addrport 1.2.3.4:7000 test +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fI\%\-\-noinput\fP option may be provided to suppress all user +prompts. +.SS validate +.INDENT 0.0 +.TP +.B django\-admin validate +.UNINDENT +.sp +Deprecated since version 1.7: Replaced by the \fI\%check\fP command. + +.sp +Validates all installed models (according to the \fBINSTALLED_APPS\fP +setting) and prints validation errors to standard output. +.SH COMMANDS PROVIDED BY APPLICATIONS +.sp +Some commands are only available when the \fBdjango.contrib\fP application that +\fBimplements\fP them has been +\fBenabled\fP\&. This section describes them grouped by +their application. +.SS \fBdjango.contrib.auth\fP +.SS changepassword +.INDENT 0.0 +.TP +.B django\-admin changepassword +.UNINDENT +.sp +This command is only available if Django\(aqs \fBauthentication system\fP (\fBdjango.contrib.auth\fP) is installed. +.sp +Allows changing a user\(aqs password. It prompts you to enter twice the password of +the user given as parameter. If they both match, the new password will be +changed immediately. If you do not supply a user, the command will attempt to +change the password whose username matches the current user. +.sp +Use the \fB\-\-database\fP option to specify the database to query for the user. If +it\(aqs not supplied, Django will use the \fBdefault\fP database. +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin changepassword ringo +.ft P +.fi +.UNINDENT +.UNINDENT +.SS createsuperuser +.INDENT 0.0 +.TP +.B django\-admin createsuperuser +.UNINDENT +.sp +This command is only available if Django\(aqs \fBauthentication system\fP (\fBdjango.contrib.auth\fP) is installed. +.sp +Creates a superuser account (a user who has all permissions). This is +useful if you need to create an initial superuser account or if you need to +programmatically generate superuser accounts for your site(s). +.sp +When run interactively, this command will prompt for a password for +the new superuser account. When run non\-interactively, no password +will be set, and the superuser account will not be able to log in until +a password has been manually set for it. +.INDENT 0.0 +.TP +.B \-\-username +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-email +.UNINDENT +.sp +The username and email address for the new account can be supplied by +using the \fB\-\-username\fP and \fB\-\-email\fP arguments on the command +line. If either of those is not supplied, \fBcreatesuperuser\fP will prompt for +it when running interactively. +.sp +Use the \fB\-\-database\fP option to specify the database into which the superuser +object will be saved. +.sp + +.sp +You can subclass the management command and override \fBget_input_data()\fP if you +want to customize data input and validation. Consult the source code for +details on the existing implementation and the method\(aqs parameters. For example, +it could be useful if you have a \fBForeignKey\fP in +\fBREQUIRED_FIELDS\fP and want to +allow creating an instance instead of entering the primary key of an existing +instance. +.SS \fBdjango.contrib.gis\fP +.SS ogrinspect +.sp +This command is only available if \fBGeoDjango\fP +(\fBdjango.contrib.gis\fP) is installed. +.sp +Please refer to its \fBdescription\fP in the GeoDjango +documentation. +.SS \fBdjango.contrib.sessions\fP +.SS clearsessions +.INDENT 0.0 +.TP +.B django\-admin clearsessions +.UNINDENT +.sp +Can be run as a cron job or directly to clean out expired sessions. +.SS \fBdjango.contrib.sitemaps\fP +.SS ping_google +.sp +This command is only available if the \fBSitemaps framework\fP (\fBdjango.contrib.sitemaps\fP) is installed. +.sp +Please refer to its \fBdescription\fP in the Sitemaps +documentation. +.SS \fBdjango.contrib.staticfiles\fP +.SS collectstatic +.sp +This command is only available if the \fBstatic files application\fP (\fBdjango.contrib.staticfiles\fP) is installed. +.sp +Please refer to its \fBdescription\fP in the +\fBstaticfiles\fP documentation. +.SS findstatic +.sp +This command is only available if the \fBstatic files application\fP (\fBdjango.contrib.staticfiles\fP) is installed. +.sp +Please refer to its \fBdescription\fP in the \fBstaticfiles\fP documentation. +.SH DEFAULT OPTIONS +.sp +Although some commands may allow their own custom options, every command +allows for the following options: +.INDENT 0.0 +.TP +.B \-\-pythonpath +.UNINDENT +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin migrate \-\-pythonpath=\(aq/home/djangoprojects/myproject\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Adds the given filesystem path to the Python \fI\%import search path\fP\&. If this +isn\(aqt provided, \fBdjango\-admin\fP will use the \fBPYTHONPATH\fP environment +variable. +.sp +Note that this option is unnecessary in \fBmanage.py\fP, because it takes care of +setting the Python path for you. +.INDENT 0.0 +.TP +.B \-\-settings +.UNINDENT +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin migrate \-\-settings=mysite.settings +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Explicitly specifies the settings module to use. The settings module should be +in Python package syntax, e.g. \fBmysite.settings\fP\&. If this isn\(aqt provided, +\fBdjango\-admin\fP will use the \fBDJANGO_SETTINGS_MODULE\fP environment +variable. +.sp +Note that this option is unnecessary in \fBmanage.py\fP, because it uses +\fBsettings.py\fP from the current project by default. +.INDENT 0.0 +.TP +.B \-\-traceback +.UNINDENT +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin migrate \-\-traceback +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +By default, \fBdjango\-admin\fP will show a simple error message whenever an +\fBCommandError\fP occurs, but a full stack trace +for any other exception. If you specify \fB\-\-traceback\fP, \fBdjango\-admin\fP +will also output a full stack trace when a \fBCommandError\fP is raised. +.INDENT 0.0 +.TP +.B \-\-verbosity +.UNINDENT +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin migrate \-\-verbosity 2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Use \fB\-\-verbosity\fP to specify the amount of notification and debug information +that \fBdjango\-admin\fP should print to the console. +.INDENT 0.0 +.IP \(bu 2 +\fB0\fP means no output. +.IP \(bu 2 +\fB1\fP means normal output (default). +.IP \(bu 2 +\fB2\fP means verbose output. +.IP \(bu 2 +\fB3\fP means \fIvery\fP verbose output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-color +.UNINDENT +.sp + +.sp +Example usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin sqlall \-\-no\-color +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +By default, \fBdjango\-admin\fP will format the output to be colorized. For +example, errors will be printed to the console in red and SQL statements will +be syntax highlighted. To prevent this and have a plain text output, pass the +\fB\-\-no\-color\fP option when running your command. +.SH COMMON OPTIONS +.sp +The following options are not available on every command, but they are common +to a number of commands. +.INDENT 0.0 +.TP +.B \-\-database +.UNINDENT +.sp +Used to specify the database on which a command will operate. If not +specified, this option will default to an alias of \fBdefault\fP\&. +.sp +For example, to dump data from the database with the alias \fBmaster\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin dumpdata \-\-database=master +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-exclude +.UNINDENT +.sp +Exclude a specific application from the applications whose contents is +output. For example, to specifically exclude the \fBauth\fP application from +the output of dumpdata, you would call: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin dumpdata \-\-exclude=auth +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If you want to exclude multiple applications, use multiple \fB\-\-exclude\fP +directives: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-admin dumpdata \-\-exclude=auth \-\-exclude=contenttypes +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-locale +.UNINDENT +.sp +Use the \fB\-\-locale\fP or \fB\-l\fP option to specify the locale to process. +If not provided all locales are processed. +.INDENT 0.0 +.TP +.B \-\-noinput +.UNINDENT +.sp +Use the \fB\-\-noinput\fP option to suppress all user prompting, such as "Are +you sure?" confirmation messages. This is useful if \fBdjango\-admin\fP is +being executed as an unattended, automated script. +.SH EXTRA NICETIES +.SS Syntax coloring +.sp +The \fBdjango\-admin\fP / \fBmanage.py\fP commands will use pretty +color\-coded output if your terminal supports ANSI\-colored output. It +won\(aqt use the color codes if you\(aqre piping the command\(aqs output to +another program. +.sp +Under Windows, the native console doesn\(aqt support ANSI escape sequences so by +default there is no color output. But you can install the \fI\%ANSICON\fP +third\-party tool, the Django commands will detect its presence and will make +use of its services to color output just like on Unix\-based platforms. +.sp +The colors used for syntax highlighting can be customized. Django +ships with three color palettes: +.INDENT 0.0 +.IP \(bu 2 +\fBdark\fP, suited to terminals that show white text on a black +background. This is the default palette. +.IP \(bu 2 +\fBlight\fP, suited to terminals that show black text on a white +background. +.IP \(bu 2 +\fBnocolor\fP, which disables syntax highlighting. +.UNINDENT +.sp +You select a palette by setting a \fBDJANGO_COLORS\fP environment +variable to specify the palette you want to use. For example, to +specify the \fBlight\fP palette under a Unix or OS/X BASH shell, you +would run the following at a command prompt: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +export DJANGO_COLORS="light" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +You can also customize the colors that are used. Django specifies a +number of roles in which color is used: +.INDENT 0.0 +.IP \(bu 2 +\fBerror\fP \- A major error. +.IP \(bu 2 +\fBnotice\fP \- A minor error. +.IP \(bu 2 +\fBsql_field\fP \- The name of a model field in SQL. +.IP \(bu 2 +\fBsql_coltype\fP \- The type of a model field in SQL. +.IP \(bu 2 +\fBsql_keyword\fP \- An SQL keyword. +.IP \(bu 2 +\fBsql_table\fP \- The name of a model in SQL. +.IP \(bu 2 +\fBhttp_info\fP \- A 1XX HTTP Informational server response. +.IP \(bu 2 +\fBhttp_success\fP \- A 2XX HTTP Success server response. +.IP \(bu 2 +\fBhttp_not_modified\fP \- A 304 HTTP Not Modified server response. +.IP \(bu 2 +\fBhttp_redirect\fP \- A 3XX HTTP Redirect server response other than 304. +.IP \(bu 2 +\fBhttp_not_found\fP \- A 404 HTTP Not Found server response. +.IP \(bu 2 +\fBhttp_bad_request\fP \- A 4XX HTTP Bad Request server response other than 404. +.IP \(bu 2 +\fBhttp_server_error\fP \- A 5XX HTTP Server Error response. +.UNINDENT +.sp +Each of these roles can be assigned a specific foreground and +background color, from the following list: +.INDENT 0.0 +.IP \(bu 2 +\fBblack\fP +.IP \(bu 2 +\fBred\fP +.IP \(bu 2 +\fBgreen\fP +.IP \(bu 2 +\fByellow\fP +.IP \(bu 2 +\fBblue\fP +.IP \(bu 2 +\fBmagenta\fP +.IP \(bu 2 +\fBcyan\fP +.IP \(bu 2 +\fBwhite\fP +.UNINDENT +.sp +Each of these colors can then be modified by using the following +display options: +.INDENT 0.0 +.IP \(bu 2 +\fBbold\fP +.IP \(bu 2 +\fBunderscore\fP +.IP \(bu 2 +\fBblink\fP +.IP \(bu 2 +\fBreverse\fP +.IP \(bu 2 +\fBconceal\fP +.UNINDENT +.sp +A color specification follows one of the following patterns: +.INDENT 0.0 +.IP \(bu 2 +\fBrole=fg\fP +.IP \(bu 2 +\fBrole=fg/bg\fP +.IP \(bu 2 +\fBrole=fg,option,option\fP +.IP \(bu 2 +\fBrole=fg/bg,option,option\fP +.UNINDENT +.sp +where \fBrole\fP is the name of a valid color role, \fBfg\fP is the +foreground color, \fBbg\fP is the background color and each \fBoption\fP +is one of the color modifying options. Multiple color specifications +are then separated by semicolon. For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +export DJANGO_COLORS="error=yellow/blue,blink;notice=magenta" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +would specify that errors be displayed using blinking yellow on blue, +and notices displayed using magenta. All other color roles would be +left uncolored. +.sp +Colors can also be specified by extending a base palette. If you put +a palette name in a color specification, all the colors implied by that +palette will be loaded. So: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +export DJANGO_COLORS="light;error=yellow/blue,blink;notice=magenta" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +would specify the use of all the colors in the light color palette, +\fIexcept\fP for the colors for errors and notices which would be +overridden as specified. +.sp + +.sp +Support for color\-coded output from \fBdjango\-admin\fP / \fBmanage.py\fP +utilities on Windows by relying on the ANSICON application was added in Django +1.7. +.SS Bash completion +.sp +If you use the Bash shell, consider installing the Django bash completion +script, which lives in \fBextras/django_bash_completion\fP in the Django +distribution. It enables tab\-completion of \fBdjango\-admin\fP and +\fBmanage.py\fP commands, so you can, for instance... +.INDENT 0.0 +.IP \(bu 2 +Type \fBdjango\-admin\fP\&. +.IP \(bu 2 +Press [TAB] to see all available options. +.IP \(bu 2 +Type \fBsql\fP, then [TAB], to see all available options whose names start +with \fBsql\fP\&. +.UNINDENT +.sp +See \fB/howto/custom\-management\-commands\fP for how to add customized actions. +.INDENT 0.0 +.TP +.B django.core.management.call_command(name, *args, **options) +.UNINDENT +.sp +To call a management command from code use \fBcall_command\fP\&. +.INDENT 0.0 +.TP +.B \fBname\fP +the name of the command to call. +.TP +.B \fB*args\fP +a list of arguments accepted by the command. +.TP +.B \fB**options\fP +named options accepted on the command\-line. +.UNINDENT +.sp +Examples: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +from django.core import management +management.call_command(\(aqflush\(aq, verbosity=0, interactive=False) +management.call_command(\(aqloaddata\(aq, \(aqtest_data\(aq, verbosity=0) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Note that command options that take no arguments are passed as keywords +with \fBTrue\fP or \fBFalse\fP, as you can see with the \fBinteractive\fP option above. +.sp +Named arguments can be passed by using either one of the following syntaxes: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Similar to the command line +management.call_command(\(aqdumpdata\(aq, \(aq\-\-natural\-foreign\(aq) + +# Named argument similar to the command line minus the initial dashes and +# with internal dashes replaced by underscores +management.call_command(\(aqdumpdata\(aq, natural_foreign=True) + +# \(gause_natural_foreign_keys\(ga is the option destination variable +management.call_command(\(aqdumpdata\(aq, use_natural_foreign_keys=True) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The first syntax is now supported thanks to management commands using the +\fI\%argparse\fP module. For the second syntax, Django previously passed +the option name as\-is to the command, now it is always using the \fBdest\fP +variable name (which may or may not be the same as the option name). + +.sp +Command options which take multiple options are passed a list: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +management.call_command(\(aqdumpdata\(aq, exclude=[\(aqcontenttypes\(aq, \(aqauth\(aq]) +.ft P +.fi +.UNINDENT +.UNINDENT +.SH OUTPUT REDIRECTION +.sp +Note that you can redirect standard output and error streams as all commands +support the \fBstdout\fP and \fBstderr\fP options. For example, you could write: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +with open(\(aq/tmp/command_output\(aq) as f: + management.call_command(\(aqdumpdata\(aq, stdout=f) +.ft P +.fi +.UNINDENT +.UNINDENT +.SH AUTHOR +Django Software Foundation +.SH COPYRIGHT +Django Software Foundation and contributors +.\" Generated by docutils manpage writer. +.