--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/thirdparty/google_appengine/lib/django/docs/django-admin.txt Tue Aug 26 21:49:54 2008 +0000
@@ -0,0 +1,544 @@
+=============================
+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 ``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.
+
+Usage
+=====
+
+``django-admin.py action [options]``
+
+``manage.py action [options]``
+
+``action`` should be one of the actions listed in this document. ``options``,
+which is optional, should be zero or more of the options listed in this
+document.
+
+Run ``django-admin.py --help`` to display a help message that includes a terse
+list of all available actions and options.
+
+Most actions take a list of ``appname``s. An ``appname`` is the basename of the
+package containing your models. For example, if your ``INSTALLED_APPS``
+contains the string ``'mysite.blog'``, the ``appname`` is ``blog``.
+
+Available actions
+=================
+
+adminindex [appname appname ...]
+--------------------------------
+
+Prints the admin-index template snippet for the given appnames.
+
+Use admin-index template snippets if you want to customize the look and feel of
+your admin's index page. See `Tutorial 2`_ for more information.
+
+.. _Tutorial 2: ../tutorial2/
+
+createcachetable [tablename]
+----------------------------
+
+Creates a cache table named ``tablename`` for use with the database cache
+backend. See the `cache documentation`_ for more information.
+
+.. _cache documentation: ../cache/
+
+dbshell
+-------
+
+Runs the command-line client for the database engine specified in your
+``DATABASE_ENGINE`` setting, with the connection parameters specified in your
+``DATABASE_USER``, ``DATABASE_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.
+
+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 ...]
+------------------------------
+
+Output to standard output all data in the database associated with the named
+application(s).
+
+By default, the database will be dumped in JSON format. If you want the output
+to be in another format, use the ``--format`` option (e.g., ``format=xml``).
+You may specify any Django serialization backend (including any user specified
+serialization backends named in the ``SERIALIZATION_MODULES`` setting).
+
+If no application name is provided, all installed applications will be dumped.
+
+The output of ``dumpdata`` can be used as input for ``loaddata``.
+
+flush
+-----
+
+Return 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.
+
+inspectdb
+---------
+
+Introspects the database tables in the database pointed-to by the
+``DATABASE_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.
+
+loaddata [fixture fixture ...]
+------------------------------
+
+Searches for and loads the contents of the named fixture into the database.
+
+A *Fixture* is a collection of files that contain the serialized contents of
+the database. Each fixture has a unique name; however, 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 serializer (e.g., ``json`` or
+``xml``).
+
+If you omit the extension, 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. However, if two fixtures with the same name but different
+fixture type are discovered (for example, if ``mydata.json`` and
+``mydata.xml`` 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.
+
+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``.
+
+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.
+
+.. 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.
+
+reset [appname appname ...]
+---------------------------
+Executes the equivalent of ``sqlreset`` for the given appnames.
+
+runfcgi [options]
+-----------------
+Starts a set of FastCGI processes suitable for use with any web server
+which supports the FastCGI protocol. See the `FastCGI deployment
+documentation`_ for details. Requires the Python FastCGI module from
+`flup`_.
+
+.. _FastCGI deployment documentation: ../fastcgi/
+.. _flup: http://www.saddi.com/software/flup/
+
+runserver [optional port number, or ipaddr:port]
+------------------------------------------------
+
+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``.
+
+Examples:
+~~~~~~~~~
+
+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_ROOT_URL`` and so forth). If
+you want to configure Django to serve static media, read the `serving static files`_
+documentation.
+
+.. _serving static files: ../static_files/
+
+Turning off auto-reload
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To disable auto-reloading of code while the development server is running, use the
+``--noreload`` option, like so::
+
+ django-admin.py runserver --noreload
+
+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 ...]
+-------------------------
+
+Prints the CREATE TABLE SQL statements for the given appnames.
+
+sqlall [appname appname ...]
+----------------------------
+
+Prints the CREATE TABLE and initial-data SQL statements for the given appnames.
+
+Refer to the description of ``sqlinitialdata`` for an explanation of how to
+specify initial data.
+
+sqlclear [appname appname ...]
+--------------------------------------
+
+Prints the DROP TABLE SQL statements for the given appnames.
+
+sqlcustom [appname appname ...]
+-------------------------------
+
+Prints the custom SQL statements for the given appnames.
+
+For each model in each specified app, this command looks for the file
+``<appname>/sql/<modelname>.sql``, where ``<appname>`` is the given appname and
+``<modelname>`` is the model's name in lowercase. For example, if you have an
+app ``news`` that includes a ``Story`` model, ``sqlinitialdata`` 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.
+
+sqlindexes [appname appname ...]
+----------------------------------------
+
+Prints the CREATE INDEX SQL statements for the given appnames.
+
+sqlreset [appname appname ...]
+--------------------------------------
+
+Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given appnames.
+
+sqlsequencereset [appname appname ...]
+----------------------------------------------
+
+Prints the SQL statements for resetting PostgreSQL sequences for the given
+appnames.
+
+See http://simon.incutio.com/archive/2004/04/21/postgres for more information.
+
+startapp [appname]
+------------------
+
+Creates a Django app directory structure for the given app name in the current
+directory.
+
+startproject [projectname]
+--------------------------
+
+Creates a Django project directory structure for the given project name in the
+current directory.
+
+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.
+
+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``.
+See the documentation for ``loaddata`` for details on the specification of
+fixture data files.
+
+test
+----
+
+Discover and run tests for all installed models. See `Testing Django applications`_ for more information.
+
+.. _testing django applications: ../testing/
+
+validate
+--------
+
+Validates all installed models (according to the ``INSTALLED_APPS`` setting)
+and prints validation errors to standard output.
+
+Available options
+=================
+
+--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 takes care of
+setting ``DJANGO_SETTINGS_MODULE`` for you.
+
+--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
+
+--format
+--------
+
+Example usage::
+
+ django-admin.py dumpdata --format=xml
+
+Specifies the output format that will be used. The name provided must be the name
+of a registered serializer.
+
+--help
+------
+
+Displays a help message that includes a terse list of all available actions and
+options.
+
+--indent
+--------
+
+Example usage::
+
+ django-admin.py dumpdata --indent=4
+
+Specifies the number of spaces that will be used for indentation when
+pretty-printing output. By default, output will *not* be pretty-printed.
+Pretty-printing will only be enabled if the indent option is provided.
+
+--noinput
+---------
+
+Inform django-admin that the user should NOT be prompted for any input. Useful
+if the django-admin script will be executed as an unattended, automated
+script.
+
+--noreload
+----------
+
+Disable the use of the auto-reloader when running the development server.
+
+--version
+---------
+
+Displays the current Django version.
+
+Example output::
+
+ 0.9.1
+ 0.9.1 (SVN)
+
+--verbosity
+-----------
+
+Example usage::
+
+ django-admin.py syncdb --verbosity=2
+
+Verbosity determines the amount of notification and debug information that
+will be printed to the console. '0' is no output, '1' is normal output,
+and `2` is verbose output.
+
+--adminmedia
+------------
+
+Example usage::
+ django-admin.py manage.py --adminmedia=/tmp/new-admin-style/
+
+Tells Django where to find the various CSS and JavaScript files for the admin
+interface when running the development server. Normally these files are served
+out of the Django source tree, but because some designers customize these files
+for their site, this option allows you to test against custom versions.
+
+Extra niceties
+==============
+
+Syntax coloring
+---------------
+
+The ``django-admin.py`` / ``manage.py`` commands that output SQL to standard
+output 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.
+
+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``.