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, 0 insertions, 1293 deletions
diff --git a/parts/django/docs/ref/django-admin.txt b/parts/django/docs/ref/django-admin.txt deleted file mode 100644 index 70faa3c..0000000 --- a/parts/django/docs/ref/django-admin.txt +++ /dev/null @@ -1,1293 +0,0 @@ -============================= -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) |