diff options
Diffstat (limited to 'parts/django/docs/ref/django-admin.txt')
| -rw-r--r-- | parts/django/docs/ref/django-admin.txt | 1293 |
1 files changed, 1293 insertions, 0 deletions
diff --git a/parts/django/docs/ref/django-admin.txt b/parts/django/docs/ref/django-admin.txt new file mode 100644 index 0000000..70faa3c --- /dev/null +++ b/parts/django/docs/ref/django-admin.txt @@ -0,0 +1,1293 @@ +============================= +django-admin.py and manage.py +============================= + +``django-admin.py`` is Django's command-line utility for administrative tasks. +This document outlines all it can do. + +In addition, ``manage.py`` is automatically created in each Django project. +``manage.py`` is a thin wrapper around ``django-admin.py`` that takes care of +two things for you before delegating to ``django-admin.py``: + + * It puts your project's package on ``sys.path``. + + * It sets the :envvar:`DJANGO_SETTINGS_MODULE` environment variable so that + it points to your project's ``settings.py`` file. + +The ``django-admin.py`` script should be on your system path if you installed +Django via its ``setup.py`` utility. If it's not on your path, you can find it +in ``site-packages/django/bin`` within your Python installation. Consider +symlinking it from some place on your path, such as ``/usr/local/bin``. + +For Windows users, who do not have symlinking functionality available, you can +copy ``django-admin.py`` to a location on your existing path or edit the +``PATH`` settings (under ``Settings - Control Panel - System - Advanced - +Environment...``) to point to its installed location. + +Generally, when working on a single Django project, it's easier to use +``manage.py``. Use ``django-admin.py`` with ``DJANGO_SETTINGS_MODULE``, or the +``--settings`` command line option, if you need to switch between multiple +Django settings files. + +The command-line examples throughout this document use ``django-admin.py`` to +be consistent, but any example can use ``manage.py`` just as well. + +Usage +===== + +.. code-block:: bash + + django-admin.py <command> [options] + manage.py <command> [options] + +``command`` should be one of the commands listed in this document. +``options``, which is optional, should be zero or more of the options available +for the given command. + +Getting runtime help +-------------------- + +.. django-admin-option:: --help + +Run ``django-admin.py help`` to display a list of all available commands. +Run ``django-admin.py help <command>`` to display a description of the +given command and a list of its available options. + +App names +--------- + +Many commands take a list of "app names." An "app name" is the basename of +the package containing your models. For example, if your ``INSTALLED_APPS`` +contains the string ``'mysite.blog'``, the app name is ``blog``. + +Determining the version +----------------------- + +.. django-admin-option:: --version + +Run ``django-admin.py --version`` to display the current Django version. + +Examples of output:: + + 0.95 + 0.96 + 0.97-pre-SVN-6069 + +Displaying debug output +----------------------- + +Use :djadminopt:`--verbosity` to specify the amount of notification and debug information +that ``django-admin.py`` should print to the console. For more details, see the +documentation for the :djadminopt:`--verbosity` option. + +Available commands +================== + +cleanup +------- + +.. django-admin:: cleanup + +.. versionadded:: 1.0 + +Can be run as a cronjob or directly to clean out old data from the database +(only expired sessions at the moment). + +compilemessages +--------------- + +.. django-admin:: compilemessages + +.. versionchanged:: 1.0 + Before 1.0 this was the "bin/compile-messages.py" command. + +Compiles .po files created with ``makemessages`` to .mo files for use with +the builtin gettext support. See :doc:`/topics/i18n/index`. + +Use the :djadminopt:`--locale` option to specify the locale to process. +If not provided, all locales are processed. + +Example usage:: + + django-admin.py compilemessages --locale=br_PT + +createcachetable +---------------- + +.. django-admin:: createcachetable + +Creates a cache table named ``tablename`` for use with the database cache +backend. See :doc:`/topics/cache` for more information. + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database +onto which the cachetable will be installed. + +dbshell +------- + +.. django-admin:: dbshell + +Runs the command-line client for the database engine specified in your +``ENGINE`` setting, with the connection parameters specified in your +``USER``, ``PASSWORD``, etc., settings. + + * For PostgreSQL, this runs the ``psql`` command-line client. + * For MySQL, this runs the ``mysql`` command-line client. + * For SQLite, this runs the ``sqlite3`` command-line client. + +This command assumes the programs are on your ``PATH`` so that a simple call to +the program name (``psql``, ``mysql``, ``sqlite3``) will find the program in +the right place. There's no way to specify the location of the program +manually. + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database +onto which to open a shell. + +diffsettings +------------ + +.. django-admin:: diffsettings + +Displays differences between the current settings file and Django's default +settings. + +Settings that don't appear in the defaults are followed by ``"###"``. For +example, the default settings don't define ``ROOT_URLCONF``, so +``ROOT_URLCONF`` is followed by ``"###"`` in the output of ``diffsettings``. + +Note that Django's default settings live in ``django/conf/global_settings.py``, +if you're ever curious to see the full list of defaults. + +dumpdata <appname appname appname.Model ...> +-------------------------------------------- + +.. django-admin:: dumpdata + +Outputs to standard output all data in the database associated with the named +application(s). + +If no application name is provided, all installed applications will be dumped. + +The output of ``dumpdata`` can be used as input for ``loaddata``. + +Note that ``dumpdata`` uses the default manager on the model for selecting the +records to dump. If you're using a :ref:`custom manager <custom-managers>` as +the default manager and it filters some of the available records, not all of the +objects will be dumped. + +.. django-admin-option:: --format <fmt> + +By default, ``dumpdata`` will format its output in JSON, but you can use the +``--format`` option to specify another format. Currently supported formats +are listed in :ref:`serialization-formats`. + +.. django-admin-option:: --indent <num> + +By default, ``dumpdata`` will output all data on a single line. This isn't +easy for humans to read, so you can use the ``--indent`` option to +pretty-print the output with a number of indentation spaces. + +.. versionadded:: 1.0 + +The :djadminopt:`--exclude` option may be provided to prevent specific +applications from being dumped. + +.. versionadded:: 1.1 + +In addition to specifying application names, you can provide a list of +individual models, in the form of ``appname.Model``. If you specify a model +name to ``dumpdata``, the dumped output will be restricted to that model, +rather than the entire application. You can also mix application names and +model names. + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database +onto which the data will be loaded. + +.. django-admin-option:: --natural + +.. versionadded:: 1.2 + +Use :ref:`natural keys <topics-serialization-natural-keys>` to represent +any foreign key and many-to-many relationship with a model that provides +a natural key definition. If you are dumping ``contrib.auth`` ``Permission`` +objects or ``contrib.contenttypes`` ``ContentType`` objects, you should +probably be using this flag. + +flush +----- + +.. django-admin:: flush + +Returns the database to the state it was in immediately after syncdb was +executed. This means that all data will be removed from the database, any +post-synchronization handlers will be re-executed, and the ``initial_data`` +fixture will be re-installed. + +The :djadminopt:`--noinput` option may be provided to suppress all user +prompts. + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option may be used to specify the database +to flush. + + +inspectdb +--------- + +.. django-admin:: inspectdb + +Introspects the database tables in the database pointed-to by the +``NAME`` setting and outputs a Django model module (a ``models.py`` +file) to standard output. + +Use this if you have a legacy database with which you'd like to use Django. +The script will inspect the database and create a model for each table within +it. + +As you might expect, the created models will have an attribute for every field +in the table. Note that ``inspectdb`` has a few special cases in its field-name +output: + + * If ``inspectdb`` cannot map a column's type to a model field type, it'll + use ``TextField`` and will insert the Python comment + ``'This field type is a guess.'`` next to the field in the generated + model. + + * If the database column name is a Python reserved word (such as + ``'pass'``, ``'class'`` or ``'for'``), ``inspectdb`` will append + ``'_field'`` to the attribute name. For example, if a table has a column + ``'for'``, the generated model will have a field ``'for_field'``, with + the ``db_column`` attribute set to ``'for'``. ``inspectdb`` will insert + the Python comment + ``'Field renamed because it was a Python reserved word.'`` next to the + field. + +This feature is meant as a shortcut, not as definitive model generation. After +you run it, you'll want to look over the generated models yourself to make +customizations. In particular, you'll need to rearrange models' order, so that +models that refer to other models are ordered properly. + +Primary keys are automatically introspected for PostgreSQL, MySQL and +SQLite, in which case Django puts in the ``primary_key=True`` where +needed. + +``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection +only works in PostgreSQL and with certain types of MySQL tables. + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option may be used to specify the +database to introspect. + +loaddata <fixture fixture ...> +------------------------------ + +.. django-admin:: loaddata + +Searches for and loads the contents of the named fixture into the database. + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database +onto which the data will be loaded. + +What's a "fixture"? +~~~~~~~~~~~~~~~~~~~ + +A *fixture* 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. + +Django will search in three locations for fixtures: + + 1. In the ``fixtures`` directory of every installed application + 2. In any directory named in the ``FIXTURE_DIRS`` setting + 3. In the literal path named by the fixture + +Django will load any and all fixtures it finds in these locations that match +the provided fixture names. + +If the named fixture has a file extension, only fixtures of that type +will be loaded. For example:: + + django-admin.py loaddata mydata.json + +would only load JSON fixtures called ``mydata``. The fixture extension +must correspond to the registered name of a +:ref:`serializer <serialization-formats>` (e.g., ``json`` or ``xml``). + +If you omit the extensions, Django will search all available fixture types +for a matching fixture. For example:: + + django-admin.py loaddata mydata + +would look for any fixture of any fixture type called ``mydata``. If a fixture +directory contained ``mydata.json``, that fixture would be loaded +as a JSON fixture. + +The fixtures that are named can include directory components. These +directories will be included in the search path. For example:: + + django-admin.py loaddata foo/bar/mydata.json + +would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed +application, ``<dirname>/foo/bar/mydata.json`` for each directory in +``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``. + +When fixture files are processed, the data is saved to the database as is. +Model defined ``save`` methods and ``pre_save`` signals are not called. + +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. + +The ``dumpdata`` command can be used to generate input for ``loaddata``. + +Compressed fixtures +~~~~~~~~~~~~~~~~~~~ + +Fixtures may be compressed in ``zip``, ``gz``, or ``bz2`` format. For example:: + + django-admin.py loaddata mydata.json + +would look for any of ``mydata.json``, ``mydata.json.zip``, +``mydata.json.gz``, or ``mydata.json.bz2``. The first file contained within a +zip-compressed archive is used. + +Note that if two fixtures with the same name but different +fixture type are discovered (for example, if ``mydata.json`` and +``mydata.xml.gz`` were found in the same fixture directory), fixture +installation will be aborted, and any data installed in the call to +``loaddata`` will be removed from the database. + +.. admonition:: MySQL and Fixtures + + Unfortunately, MySQL isn't capable of completely supporting all the + features of Django fixtures. If you use MyISAM tables, MySQL doesn't + support transactions or constraints, so you won't get a rollback if + multiple transaction files are found, or validation of fixture data. + If you use InnoDB tables, you won't be able to have any forward + references in your data files - MySQL doesn't provide a mechanism to + defer checking of row constraints until a transaction is committed. + +Database-specific fixtures +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are in a multi-database setup, you may have fixture data that +you want to load onto one database, but not onto another. In this +situation, you can add database identifier into . If your +:setting:`DATABASES` setting has a 'master' database defined, you can +define the fixture ``mydata.master.json`` or +``mydata.master.json.gz``. This fixture will only be loaded if you +have specified that you want to load data onto the ``master`` +database. + +makemessages +------------ + +.. django-admin:: makemessages + +.. versionchanged:: 1.0 + Before 1.0 this was the ``bin/make-messages.py`` command. + +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. After making changes to the messages files you need to compile them +with ``compilemessages`` for use with the builtin gettext support. See the +:ref:`i18n documentation <how-to-create-language-files>` for details. + +.. django-admin-option:: --all + +Use the ``--all`` or ``-a`` option to update the message files for all +available languages. + +Example usage:: + + django-admin.py makemessages --all + +.. django-admin-option:: --extension + +Use the ``--extension`` or ``-e`` option to specify a list of file extensions +to examine (default: ".html"). + +Example usage:: + + django-admin.py makemessages --locale=de --extension xhtml + +Separate multiple extensions with commas or use -e or --extension multiple times:: + + django-admin.py makemessages --locale=de --extension=html,txt --extension xml + +Use the :djadminopt:`--locale` option to specify the locale to process. + +Example usage:: + + django-admin.py makemessages --locale=br_PT + +.. django-admin-option:: --domain + +Use the ``--domain`` or ``-d`` option to change the domain of the messages files. +Currently supported: + + * ``django`` for all ``*.py`` and ``*.html`` files (default) + * ``djangojs`` for ``*.js`` files + +.. django-admin-option:: --symlinks + +.. versionadded:: 1.2 + +Use the ``--symlinks`` or ``-s`` option to follow symlinks to directories when +looking for new translation strings. + +Example usage:: + + django-admin.py makemessages --locale=de --symlinks + +.. django-admin-option:: --ignore + +Use the ``--ignore`` or ``-i`` option to ignore files or directories matching +the given `glob-style pattern`_. Use multiple times to ignore more. + +These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'`` + +Example usage:: + + django-admin.py makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html + +.. _`glob-style pattern`: http://docs.python.org/library/glob.html + +.. django-admin-option:: --no-default-ignore + +Use the ``--no-default-ignore`` option to disable the default values of +:djadminopt:`--ignore`. + +reset <appname appname ...> +--------------------------- + +.. django-admin:: reset + +Executes the equivalent of ``sqlreset`` for the given app name(s). + +The :djadminopt:`--noinput` option may be provided to suppress all user +prompts. + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the alias +of the database to reset. + +runfcgi [options] +----------------- + +.. django-admin:: runfcgi + +Starts a set of FastCGI processes suitable for use with any Web server that +supports the FastCGI protocol. See the :doc:`FastCGI deployment documentation +</howto/deployment/fastcgi>` for details. Requires the Python FastCGI module from +`flup`_. + +.. _flup: http://www.saddi.com/software/flup/ + +The options accepted by this command are passed to the FastCGI library and +don't use the ``'--'`` prefix as is usual for other Django management commands. + +.. django-admin-option:: protocol + +``protocol=PROTOCOL`` + +Protocol to use. *PROTOCOL* can be ``fcgi``, ``scgi``, ``ajp``, etc. +(default is ``fcgi``) + +.. django-admin-option:: host + +``host=HOSTNAME`` + +Hostname to listen on. + +.. django-admin-option:: port + +``port=PORTNUM`` + +Port to listen on. + +.. django-admin-option:: socket + +``socket=FILE`` + +UNIX socket to listen on. + +.. django-admin-option:: method + +``method=IMPL`` + +Possible values: ``prefork`` or ``threaded`` (default ``prefork``) + +.. django-admin-option:: maxrequests + +``maxrequests=NUMBER`` + +Number of requests a child handles before it is killed and a new child is +forked (0 means no limit). + +.. django-admin-option:: maxspare + +``maxspare=NUMBER`` + +Max number of spare processes / threads. + +.. django-admin-option:: minspare + +``minspare=NUMBER`` + +Min number of spare processes / threads. + +.. django-admin-option:: maxchildren + +``maxchildren=NUMBER`` + +Hard limit number of processes / threads. + +.. django-admin-option:: daemonize + +``daemonize=BOOL`` + +Whether to detach from terminal. + +.. django-admin-option:: pidfile + +``pidfile=FILE`` + +Write the spawned process-id to file *FILE*. + +.. django-admin-option:: workdir + +``workdir=DIRECTORY`` + +Change to directory *DIRECTORY* when daemonizing. + +.. django-admin-option:: debug + +``debug=BOOL`` + +Set to true to enable flup tracebacks. + +.. django-admin-option:: outlog + +``outlog=FILE`` + +Write stdout to the *FILE* file. + +.. django-admin-option:: errlog + +``errlog=FILE`` + +Write stderr to the *FILE* file. + +.. django-admin-option:: umask + +``umask=UMASK`` + +Umask to use when daemonizing. The value is interpeted as an octal number +(default value is ``022``). + +Example usage:: + + django-admin.py runfcgi socket=/tmp/fcgi.sock method=prefork daemonize=true \ + pidfile=/var/run/django-fcgi.pid + +Run a FastCGI server as a daemon and write the spawned PID in a file. + +runserver [port or ipaddr:port] +------------------------------- + +.. django-admin:: runserver + +Starts a lightweight development Web server on the local machine. By default, +the server runs on port 8000 on the IP address 127.0.0.1. You can pass in an +IP address and port number explicitly. + +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). + +DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through +security audits or performance tests. (And that's how it's gonna stay. We're 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.) + +The development server automatically reloads Python code for each request, as +needed. You don't need to restart the server for code changes to take effect. + +When you start the server, and each time you change Python code while the +server is running, the server will validate all of your installed models. (See +the ``validate`` command below.) If the validator finds errors, it will print +them to standard output, but it won't stop the server. + +You can run as many servers as you want, as long as they're on separate ports. +Just execute ``django-admin.py runserver`` more than once. + +Note that the default IP address, 127.0.0.1, 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. ``192.168.2.1``) or +``0.0.0.0``. + +.. django-admin-option:: --adminmedia + +Use the ``--adminmedia`` option to tell Django where to find the various CSS +and JavaScript files for the Django admin interface. Normally, the development +server serves these files out of the Django source tree magically, but you'd +want to use this if you made any changes to those files for your own site. + +Example usage:: + + django-admin.py runserver --adminmedia=/tmp/new-admin-style/ + +.. django-admin-option:: --noreload + +Use the ``--noreload`` option to disable the use of the auto-reloader. This +means any Python code changes you make while the server is running will *not* +take effect if the particular Python modules have already been loaded into +memory. + +Example usage:: + + django-admin.py runserver --noreload + +Examples of using different ports and addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Port 8000 on IP address 127.0.0.1:: + + django-admin.py runserver + +Port 8000 on IP address 1.2.3.4:: + + django-admin.py runserver 1.2.3.4:8000 + +Port 7000 on IP address 127.0.0.1:: + + django-admin.py runserver 7000 + +Port 7000 on IP address 1.2.3.4:: + + django-admin.py runserver 1.2.3.4:7000 + +Serving static files with the development server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the development server doesn't serve any static files for your site +(such as CSS files, images, things under ``MEDIA_URL`` and so forth). If +you want to configure Django to serve static media, read :doc:`/howto/static-files`. + +shell +----- + +.. django-admin:: shell + +Starts the Python interactive interpreter. + +Django will use IPython_, if it's installed. If you have IPython installed and +want to force use of the "plain" Python interpreter, use the ``--plain`` +option, like so:: + + django-admin.py shell --plain + +.. _IPython: http://ipython.scipy.org/ + +sql <appname appname ...> +------------------------- + +.. django-admin:: sql + +Prints the CREATE TABLE SQL statements for the given app name(s). + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database for +which to print the SQL. + +sqlall <appname appname ...> +---------------------------- + +.. django-admin:: sqlall + +Prints the CREATE TABLE and initial-data SQL statements for the given app name(s). + +Refer to the description of ``sqlcustom`` for an explanation of how to +specify initial data. + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database for +which to print the SQL. + +sqlclear <appname appname ...> +------------------------------ + +.. django-admin:: sqlclear + +Prints the DROP TABLE SQL statements for the given app name(s). + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database for +which to print the SQL. + +sqlcustom <appname appname ...> +------------------------------- + +.. django-admin:: sqlcustom + +Prints the custom SQL statements for the given app name(s). + +For each model in each specified app, this command looks for the file +``<appname>/sql/<modelname>.sql``, where ``<appname>`` is the given app name and +``<modelname>`` is the model's name in lowercase. For example, if you have an +app ``news`` that includes a ``Story`` model, ``sqlcustom`` will attempt +to read a file ``news/sql/story.sql`` and append it to the output of this +command. + +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' +table-creation statements have been executed. Use this SQL hook to make any +table modifications, or insert any SQL functions into the database. + +Note that the order in which the SQL files are processed is undefined. + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database for +which to print the SQL. + +sqlflush +-------- + +.. django-admin:: sqlflush + +Prints the SQL statements that would be executed for the :djadmin:`flush` +command. + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database for +which to print the SQL. + +sqlindexes <appname appname ...> +-------------------------------- + +.. django-admin:: sqlindexes + +Prints the CREATE INDEX SQL statements for the given app name(s). + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database for +which to print the SQL. + +sqlreset <appname appname ...> +------------------------------ + +.. django-admin:: sqlreset + +Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given app name(s). + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database for +which to print the SQL. + +sqlsequencereset <appname appname ...> +-------------------------------------- + +.. django-admin:: sqlsequencereset + +Prints the SQL statements for resetting sequences for the given app name(s). + +Sequences are indexes used by some database engines to track the next available +number for automatically incremented fields. + +Use this command to generate SQL which will fix cases where a sequence is out +of sync with its automatically incremented field data. + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database for +which to print the SQL. + +startapp <appname> +------------------ + +.. django-admin:: startapp + +Creates a Django app directory structure for the given app name in the current +directory. + +startproject <projectname> +-------------------------- + +.. django-admin:: startproject + +Creates a Django project directory structure for the given project name in the +current directory. + +This command is disabled when the ``--settings`` option to +``django-admin.py`` is used, or when the environment variable +``DJANGO_SETTINGS_MODULE`` has been set. To re-enable it in these +situations, either omit the ``--settings`` option or unset +``DJANGO_SETTINGS_MODULE``. + +syncdb +------ + +.. django-admin:: syncdb + +Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables +have not already been created. + +Use this command when you've added new applications to your project and want to +install them in the database. This includes any apps shipped with Django that +might be in ``INSTALLED_APPS`` by default. When you start a new project, run +this command to install the default apps. + +.. admonition:: Syncdb will not alter existing tables + + ``syncdb`` will only create tables for models which have not yet been + installed. It will *never* issue ``ALTER TABLE`` statements to match + changes made to a model class after installation. Changes to model classes + and database schemas often involve some form of ambiguity and, in those + cases, Django would have to guess at the correct changes to make. There is + a risk that critical data would be lost in the process. + + If you have made changes to a model and wish to alter the database tables + to match, use the ``sql`` command to display the new SQL structure and + compare that to your existing table schema to work out the changes. + +If you're installing the ``django.contrib.auth`` application, ``syncdb`` will +give you the option of creating a superuser immediately. + +``syncdb`` will also search for and install any fixture named ``initial_data`` +with an appropriate extension (e.g. ``json`` or ``xml``). See the +documentation for ``loaddata`` for details on the specification of fixture +data files. + +--noinput +~~~~~~~~~ +The :djadminopt:`--noinput` option may be provided to suppress all user +prompts. + +.. versionadded:: 1.2 + +The :djadminopt:`--database` option can be used to specify the database to +synchronize. + +test <app or test identifier> +----------------------------- + +.. django-admin:: test + +Runs tests for all installed models. See :doc:`/topics/testing` for more +information. + +.. versionadded:: 1.2 +.. django-admin-option:: --failfast + +Use the :djadminopt:`--failfast` option to stop running tests and report the failure +immediately after a test fails. + +testserver <fixture fixture ...> +-------------------------------- + +.. django-admin:: testserver + +.. versionadded:: 1.0 + +Runs a Django development server (as in ``runserver``) using data from the +given fixture(s). + +For example, this command:: + + django-admin.py testserver mydata.json + +...would perform the following steps: + + 1. Create a test database, as described in :doc:`/topics/testing`. + 2. Populate the test database with fixture data from the given fixtures. + (For more on fixtures, see the documentation for ``loaddata`` above.) + 3. Runs the Django development server (as in ``runserver``), pointed at + this newly created test database instead of your production database. + +This is useful in a number of ways: + + * When you're writing :doc:`unit tests </topics/testing>` of how your views + act with certain fixture data, you can use ``testserver`` to interact with + the views in a Web browser, manually. + + * Let's say you're developing your Django application and have a "pristine" + copy of a database that you'd like to interact with. You can dump your + database to a fixture (using the ``dumpdata`` command, explained above), + then use ``testserver`` 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're making are only + being made to a test database. + +Note that this server does *not* automatically detect changes to your Python +source code (as ``runserver`` does). It does, however, detect changes to +templates. + +.. django-admin-option:: --addrport [port number or ipaddr:port] + +Use ``--addrport`` to specify a different port, or IP address and port, from +the default of 127.0.0.1:8000. This value follows exactly the same format and +serves exactly the same function as the argument to the ``runserver`` command. + +Examples: + +To run the test server on port 7000 with ``fixture1`` and ``fixture2``:: + + django-admin.py testserver --addrport 7000 fixture1 fixture2 + django-admin.py testserver fixture1 fixture2 --addrport 7000 + +(The above statements are equivalent. We include both of them to demonstrate +that it doesn't matter whether the options come before or after the fixture +arguments.) + +To run on 1.2.3.4:7000 with a ``test`` fixture:: + + django-admin.py testserver --addrport 1.2.3.4:7000 test + +validate +-------- + +.. django-admin:: validate + +Validates all installed models (according to the ``INSTALLED_APPS`` setting) +and prints validation errors to standard output. + +Commands provided by applications +================================= + +Some commands are only available when the ``django.contrib`` application that +:doc:`implements </howto/custom-management-commands>` them has been +:setting:`enabled <INSTALLED_APPS>`. This section describes them grouped by +their application. + +``django.contrib.auth`` +----------------------- + +changepassword +~~~~~~~~~~~~~~ + +.. django-admin:: changepassword + +.. versionadded:: 1.2 + +This command is only available if Django's :doc:`authentication system +</topics/auth>` (``django.contrib.auth``) is installed. + +Allows changing a user's 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. + +Example usage:: + + django-admin.py changepassword ringo + +createsuperuser +~~~~~~~~~~~~~~~ + +.. django-admin:: createsuperuser + +.. versionadded:: 1.0 + +This command is only available if Django's :doc:`authentication system +</topics/auth>` (``django.contrib.auth``) is installed. + +Creates a superuser account (a user who has all permissions). This is +useful if you need to create an initial superuser account but did not +do so during ``syncdb``, or if you need to programmatically generate +superuser accounts for your site(s). + +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. + +.. django-admin-option:: --username +.. django-admin-option:: --email + +The username and e-mail address for the new account can be supplied by +using the ``--username`` and ``--email`` arguments on the command +line. If either of those is not supplied, ``createsuperuser`` will prompt for +it when running interactively. + +``django.contrib.gis`` +---------------------- + +ogrinspect +~~~~~~~~~~ + +This command is only available if :doc:`GeoDjango </ref/contrib/gis/index>` +(``django.contrib.gis``) is installed. + +Please refer to its :djadmin:`description <ogrinspect>` in the GeoDjango +documentation. + +``django.contrib.sitemaps`` +--------------------------- + +ping_google +~~~~~~~~~~~ + +This command is only available if the :doc:`Sitemaps framework +</ref/contrib/sitemaps>` (``django.contrib.sitemaps``) is installed. + +Please refer to its :djadmin:`description <ping_google>` in the Sitemaps +documentation. + +Default options +=============== + +Although some commands may allow their own custom options, every command +allows for the following options: + +.. django-admin-option:: --pythonpath + +Example usage:: + + django-admin.py syncdb --pythonpath='/home/djangoprojects/myproject' + +Adds the given filesystem path to the Python `import search path`_. If this +isn't provided, ``django-admin.py`` will use the ``PYTHONPATH`` environment +variable. + +Note that this option is unnecessary in ``manage.py``, because it takes care of +setting the Python path for you. + +.. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html + +.. django-admin-option:: --settings + +Example usage:: + + django-admin.py syncdb --settings=mysite.settings + +Explicitly specifies the settings module to use. The settings module should be +in Python package syntax, e.g. ``mysite.settings``. If this isn't provided, +``django-admin.py`` will use the ``DJANGO_SETTINGS_MODULE`` environment +variable. + +Note that this option is unnecessary in ``manage.py``, because it uses +``settings.py`` from the current project by default. + +.. django-admin-option:: --traceback + +Example usage:: + + django-admin.py syncdb --traceback + +By default, ``django-admin.py`` will show a simple error message whenever an +error occurs. If you specify ``--traceback``, ``django-admin.py`` will +output a full stack trace whenever an exception is raised. + +.. django-admin-option:: --verbosity + +Example usage:: + + django-admin.py syncdb --verbosity 2 + +Use ``--verbosity`` to specify the amount of notification and debug information +that ``django-admin.py`` should print to the console. + + * ``0`` means no output. + * ``1`` means normal output (default). + * ``2`` means verbose output. + +Common options +============== + +The following options are not available on every commands, but they are +common to a number of commands. + +.. django-admin-option:: --database + +.. versionadded:: 1.2 + +Used to specify the database on which a command will operate. If not +specified, this option will default to an alias of ``default``. + +For example, to dump data from the database with the alias ``master``:: + + django-admin.py dumpdata --database=master + +.. django-admin-option:: --exclude + +Exclude a specific application from the applications whose contents is +output. For example, to specifically exclude the `auth` application from +the output of dumpdata, you would call:: + + django-admin.py dumpdata --exclude=auth + +If you want to exclude multiple applications, use multiple ``--exclude`` +directives:: + + django-admin.py dumpdata --exclude=auth --exclude=contenttypes + +.. django-admin-option:: --locale + +Use the ``--locale`` or ``-l`` option to specify the locale to process. +If not provided all locales are processed. + +.. django-admin-option:: --noinput + +Use the ``--noinput`` option to suppress all user prompting, such as "Are +you sure?" confirmation messages. This is useful if ``django-admin.py`` is +being executed as an unattended, automated script. + +Extra niceties +============== + +.. _syntax-coloring: + +Syntax coloring +--------------- + +The ``django-admin.py`` / ``manage.py`` commands will use pretty +color-coded output if your terminal supports ANSI-colored output. It +won't use the color codes if you're piping the command's output to +another program. + +The colors used for syntax highlighting can be customized. Django +ships with three color palettes: + + * ``dark``, suited to terminals that show white text on a black + background. This is the default palette. + + * ``light``, suited to terminals that show black text on a white + background. + + * ``nocolor``, which disables syntax highlighting. + +You select a palette by setting a ``DJANGO_COLORS`` environment +variable to specify the palette you want to use. For example, to +specify the ``light`` palette under a Unix or OS/X BASH shell, you +would run the following at a command prompt:: + + export DJANGO_COLORS="light" + +You can also customize the colors that are used. Django specifies a +number of roles in which color is used: + + * ``error`` - A major error. + * ``notice`` - A minor error. + * ``sql_field`` - The name of a model field in SQL. + * ``sql_coltype`` - The type of a model field in SQL. + * ``sql_keyword`` - A SQL keyword. + * ``sql_table`` - The name of a model in SQL. + * ``http_info`` - A 1XX HTTP Informational server response. + * ``http_success`` - A 2XX HTTP Success server response. + * ``http_not_modified`` - A 304 HTTP Not Modified server response. + * ``http_redirect`` - A 3XX HTTP Redirect server response other than 304. + * ``http_not_found`` - A 404 HTTP Not Found server response. + * ``http_bad_request`` - A 4XX HTTP Bad Request server response other than 404. + * ``http_server_error`` - A 5XX HTTP Server Error response. + +Each of these roles can be assigned a specific foreground and +background color, from the following list: + + * ``black`` + * ``red`` + * ``green`` + * ``yellow`` + * ``blue`` + * ``magenta`` + * ``cyan`` + * ``white`` + +Each of these colors can then be modified by using the following +display options: + + * ``bold`` + * ``underscore`` + * ``blink`` + * ``reverse`` + * ``conceal`` + +A color specification follows one of the the following patterns: + + * ``role=fg`` + * ``role=fg/bg`` + * ``role=fg,option,option`` + * ``role=fg/bg,option,option`` + +where ``role`` is the name of a valid color role, ``fg`` is the +foreground color, ``bg`` is the background color and each ``option`` +is one of the color modifying options. Multiple color specifications +are then separated by semicolon. For example:: + + export DJANGO_COLORS="error=yellow/blue,blink;notice=magenta" + +would specify that errors be displayed using blinking yellow on blue, +and notices displayed using magenta. All other color roles would be +left uncolored. + +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:: + + export DJANGO_COLORS="light;error=yellow/blue,blink;notice=magenta" + +would specify the use of all the colors in the light color palette, +*except* for the colors for errors and notices which would be +overridden as specified. + +Bash completion +--------------- + +If you use the Bash shell, consider installing the Django bash completion +script, which lives in ``extras/django_bash_completion`` in the Django +distribution. It enables tab-completion of ``django-admin.py`` and +``manage.py`` commands, so you can, for instance... + + * Type ``django-admin.py``. + * Press [TAB] to see all available options. + * Type ``sql``, then [TAB], to see all available options whose names start + with ``sql``. + + +See :doc:`/howto/custom-management-commands` for how to add customized actions. + + +========================================== +Running management commands from your code +========================================== + +.. function:: django.core.management.call_command(name, *args, **options) + +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. + +``**options`` + named options accepted on the command-line. + +Examples:: + + from django.core import management + management.call_command('flush', verbosity=0, interactive=False) + management.call_command('loaddata', 'test_data', verbosity=0) |